Feature/async - v2.0.6 (#76)

## Description

This PR represents the final collection of updates needed to address all
outstanding issues related to the stated updates for the v2.0.0 major
update.

## Related Issues

Closes #51, #72, #63, #62, #61, #60

## Type of Change

- [X] Bug fix (non-breaking change that fixes an issue)
- [X] New feature (non-breaking change that adds functionality)
- [X] Breaking change (fix or feature that would cause existing
functionality to change)
- [X] Refactor (code change that neither fixes a bug nor adds a feature)
- [X] Documentation
- [X] Tests

## Checklist

- [X] My commits follow the [Angular commit
convention](https://www.conventionalcommits.org/) (`feat:`, `fix:`,
`refactor:`, etc.)
- [X] I have added/updated docstrings with type hints for any new or
changed public methods
- [X] I have added unit tests that cover my changes (mocked, not
requiring a live comlink service)
- [X] All existing tests still pass (`python -m pytest tests/ -v`)
- [X] Ruff linter passes (`ruff check src/ tests/`)

## Testing

Full current suite of pytests and manual spot validation using samples
from the examples folder

Author: MarTrepodi

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   pull_request:
-    branches: [main, 2.0-development]
+    branches: [main, 1.0-maintenance, 2.0-development]
   push:
     branches: [main]
 
@@ -54,13 +54,10 @@ jobs:
           python-version: "3.12"
 
       - name: Install dependencies
-        run: uv pip install --system -e "." mypy
+        run: uv sync --group typecheck
 
       - name: Run mypy
-        # NOTE: 38 existing errors (mostly implicit Optional). Set continue-on-error
-        # to false once type annotations are cleaned up (see pyproject.toml TODO).
-        continue-on-error: true
-        run: mypy src/swgoh_comlink/
+        run: uv run mypy src/swgoh_comlink/
 
   # ── Test ───────────────────────────────────────────────────────────────
   test:
@@ -82,11 +79,11 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv pip install --system -e "." pytest pytest-cov
+        run: uv sync --group test
 
       - name: Run tests with coverage
         run: |
-          python -m pytest tests/ \
+          uv run python -m pytest tests/ \
             --cov=swgoh_comlink \
             --cov-report=term-missing \
             --cov-report=xml:coverage.xml \
@@ -99,6 +96,27 @@ jobs:
           name: coverage-report
           path: coverage.xml
 
+  # ── Docs build ────────────────────────────────────────────────────────
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build docs
+        run: uv run mkdocs build
+
   # ── Build verification ─────────────────────────────────────────────────
   build:
     name: Build
@@ -114,13 +132,10 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install hatch
-        run: uv pip install --system hatch
-
       - name: Build package
-        run: hatch build
+        run: uvx hatch build
 
       - name: Verify wheel contents
         run: |
-          pip install dist/*.whl
+          uv pip install --system dist/*.whl
           python -c "from swgoh_comlink import SwgohComlink; print('Import OK')"

.github/workflows/commitlint.yml

@@ -2,7 +2,7 @@ name: Commit Lint
 
 on:
   pull_request:
-    branches: [main, 2.0-development]
+    branches: [main, 1.0-maintenance]
 
 permissions:
   contents: read
@@ -26,13 +26,18 @@ jobs:
             "extends": ["@commitlint/config-conventional"],
             "rules": {
               "type-enum": [2, "always", [
-                "feat", "fix", "refactor", "build", "deps",
+                "feat", "fix", "refactor", "build", "deps", "bug",
                 "chore", "docs", "test", "style", "ci", "perf"
               ]],
               "scope-enum": [1, "always", [
-                "core", "helpers", "deps", "release", "ci"
+                "core", "helpers", "deps", "release", "ci", 
+                "version", "hmac", "docs", "tests", "examples", 
+                "async", "statcalc"
               ]],
-              "subject-max-length": [1, "always", 100]
+              "subject-max-length": [1, "always", 100],
+              "header-max-length": [0, "always"],
+              "body-max-line-length": [0, "always"],
+              "footer-max-line-length": [0, "always"]
             }
           }
           EOF

.github/workflows/integration.yml

@@ -0,0 +1,74 @@
+name: Integration Tests
+
+on:
+  pull_request:
+    branches: [main, 1.0-maintenance]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: integration-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  integration:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    services:
+      comlink:
+        image: ghcr.io/swgoh-utils/swgoh-comlink:latest
+        env:
+          APP_NAME: comlink-python-integration-tests
+        ports:
+          - 3000:3000
+
+      comlink-hmac:
+        image: ghcr.io/swgoh-utils/swgoh-comlink:latest
+        env:
+          APP_NAME: comlink-python-hmac-integration-tests
+          ACCESS_KEY: ${{ secrets.COMLINK_ACCESS_KEY }}
+          SECRET_KEY: ${{ secrets.COMLINK_SECRET_KEY }}
+        ports:
+          - 3001:3000
+
+    steps:
+      - name: Wait for Comlink services
+        run: |
+          for port in 3000 3001; do
+            echo "Waiting for service on port $port..."
+            for i in $(seq 1 30); do
+              if curl -sf http://localhost:$port/readyz > /dev/null 2>&1; then
+                echo "Service on port $port is ready."
+                break
+              fi
+              if [ $i -eq 30 ]; then
+                echo "Service on port $port failed to become ready."
+                exit 1
+              fi
+              sleep 2
+            done
+          done
+
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --group test
+
+      - name: Run integration tests
+        env:
+          RUN_INTEGRATION_TESTS: "1"
+          HMAC_ACCESS_KEY: ${{ secrets.COMLINK_ACCESS_KEY }}
+          HMAC_SECRET_KEY: ${{ secrets.COMLINK_SECRET_KEY }}
+        run: uv run python -m pytest tests/integration/ -v

.github/workflows/release.yml

@@ -35,21 +35,18 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install dependencies
-        run: uv pip install --system hatch git-changelog
-
       # Update version
       - name: Update version
-        run: hatch version minor
+        run: uvx hatch version minor
 
       # Update CHANGELOG.md
       - name: Update CHANGELOG.md
-        run: git-changelog -B auto -Tio CHANGELOG.md -c angular -s build,deps,fix,feat,refactor -n semver
+        run: uvx git-changelog -B auto -Tio CHANGELOG.md -c angular -s build,deps,fix,feat,refactor -n semver
 
       # Commit version bump and changelog, then tag and push
       - name: Commit and tag
         run: |
-          VERSION=$(hatch version)
+          VERSION=$(uvx hatch version)
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git add src/swgoh_comlink/version.py CHANGELOG.md
@@ -61,7 +58,7 @@ jobs:
 
       # Build the package
       - name: Build the package
-        run: hatch build
+        run: uvx hatch build
 
       # Upload build artifacts for the publish job
       - name: Upload build artifacts

.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Sync dependencies
+        run: uv sync --group dev --group docs
+
+      - name: Run unit tests
+        run: uv run pytest -q
+
+      - name: Build docs
+        run: uv run mkdocs build

.gitignore

@@ -48,6 +48,12 @@ stash/
 pip-log.txt
 pip-delete-this-directory.txt
 
+# Exhaustive tests and support files (owner-only, not distributed)
+tests/exhaustive/
+scripts/
+data/
+gameData.json
+
 # Unit test / coverage reports
 htmlcov/
 .tox/
@@ -61,6 +67,9 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+.ruff_cache/
+.parity-cache/
+parity/.cache-gameData.json
 cover/
 
 
@@ -176,3 +185,4 @@ cython_debug/
 Pipfile*
 pyvenv.cfg
 /src/swgoh_comlink/tools.py
+/docs/exhaustive-tests.md

.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+# Pre-commit hooks mirroring the CI workflow checks.
+# Install: pre-commit install
+# Run all: pre-commit run --all-files
+
+repos:
+  # ── General file hygiene ──────────────────────────────────────────────
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: debug-statements
+
+  # ── Ruff linter & formatter (mirrors CI lint job) ─────────────────────
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # ── Mypy type checking (mirrors CI type-check job) ────────────────────
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        files: ^src/swgoh_comlink/
+        additional_dependencies: [httpx>=0.28]
+        args: [--strict, --ignore-missing-imports]
+
+  # ── Commitlint (mirrors CI commitlint job) ────────────────────────────
+  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
+    rev: v9.21.0
+    hooks:
+      - id: commitlint
+        stages: [commit-msg]
+        additional_dependencies: ["@commitlint/config-conventional"]