name: Code Quality

on:
  push:
    branches: [main]
  # Run on every PR regardless of its base branch (e.g. PRs stacked onto a
  # `claude/*` working branch, not just those targeting main).
  pull_request:
    branches: ['**']

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python 3.10
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      - name: Install quality tooling
        run: |
          python -m pip install --upgrade pip
          pip install ".[quality]"
          pip install pytest

      - name: Run ruff (lightweight lint)
        run: ruff check expert_backend scripts

      - name: Run code-quality gate
        run: python scripts/check_code_quality.py

      - name: Run docs-tree gate (D9)
        # Fails when a CLAUDE.md reference points at a file that no longer exists
        # or reintroduces a rotting `file.py:NNN` line anchor. See
        # docs/architecture/code-quality-analysis.md §23.
        run: python scripts/check_docs_tree.py

      - name: Run reporter + docs-tree unit tests
        run: pytest scripts/test_code_quality_report.py scripts/test_check_docs_tree.py -q

      - name: Run mypy (gate)
        # GATES the build: the shared-state base (services/_recommender_state.py)
        # makes the mixin composition type-check cleanly, so mypy is at 0 and
        # any new type error fails CI (see pyproject [tool.mypy] + §19).
        run: mypy

      - name: Generate report artifacts
        run: |
          python scripts/code_quality_report.py \
            --output reports/code-quality.json \
            --markdown reports/code-quality.md

      - name: Publish report to workflow summary
        if: always()
        run: cat reports/code-quality.md >> "$GITHUB_STEP_SUMMARY"

      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: code-quality-report
          path: reports/
          retention-days: 30