ci.yml

name: ci

on:
  push:
    branches: [main] # feature-branch validation comes from the pull_request run only (CI-CD-STANDARD §11i)
  pull_request:

# Least-privilege by default; jobs escalate only what they need.
permissions:
  contents: read

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python: ${{ github.event_name == 'pull_request' && fromJSON('["3.12"]') || fromJSON('["3.12","3.13"]') }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - name: Install (dev + serve) on ${{ matrix.python }}
        run: uv sync --locked --extra serve --python ${{ matrix.python }}
      - name: Ruff format check
        run: uv run ruff format --check src tests
      - name: Ruff lint
        run: uv run ruff check src tests
      - name: Mypy (strict)
        run: uv run mypy
      - name: Pytest (branch coverage gate >=90% from pyproject)
        run: uv run pytest
      - name: Build sdist + wheel (packaging regression check — CQ-10)
        run: uv build

  security:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      # gitleaks-action resolves a pull_request's commit range through
      # `GET /repos/{owner}/{repo}/pulls/{n}/commits`, which 403s on a private repo
      # without this scope. Least privilege: read on contents + pull requests, nothing
      # else — no write anywhere.
      pull-requests: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          # The PR-event scan is `git log <first-commit>^..<last-commit>`; those commits
          # are not in a depth-1 checkout of the merge ref, so gitleaks needs real history.
          fetch-depth: 0
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - name: Install (dev)
        run: uv sync --locked
      - name: Semgrep (SAST)
        run: uvx --with 'setuptools<81' semgrep scan --config p/python --error src
      - name: pip-audit (blocking — not muted)
        run: uv run pip-audit
      # Runs on pull_request too, as of 2026-08-01. It used to carry
      # `if: github.event_name != 'pull_request'`, which meant a secret introduced in a
      # PR was not caught until it had already been merged to main — the PR's own
      # "security" check went green having scanned nothing for secrets. Blocking, no
      # `|| true`, no continue-on-error.
      - name: gitleaks (secret scan)
        uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # On a PR finding the action would otherwise try to comment, which needs write
          # scope. Turn the comment off rather than grant it — the failing step is the
          # signal. (The same stance the author's other repos take.)
          GITLEAKS_ENABLE_COMMENTS: "false"

  eval-a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - name: Install (dev + serve)
        run: uv sync --locked --extra serve
      - name: Ingest the bundled corpus
        run: uv run sprout ingest
      - name: Eval suites (offline deterministic judge, merge-blocking)
        run: uv run sprout eval --out docs/audits
      - name: Structural a11y gate (chat UI + HTML report)
        run: |
          uv run sprout a11y-check web/dist/index.html
          uv run sprout a11y-check docs/audits/eval-report.html
      - name: Claims-integrity gate (docs vs code/config source of truth)
        run: uv run sprout claims-check
      - name: Judge calibration (gated — deterministic judge, 66 probes; see docs/ROADMAP.md)
        run: uv run sprout calibrate eval/judge_probes.yaml --out docs/audits --gate
      - name: Gate inventory (FIX-02 — every ledger AUTO row must map to a real mechanism)
        run: uv run sprout gate-inventory --out docs/audits
      - name: Tier-A SLO + burn-rate-alert schema gate
        run: uv run sprout slo-check
      - name: Corpus report (report-only — EXP-12 heuristics advisory until tuned)
        run: uv run sprout corpus-report --out docs/audits
      - name: Corpus proposal review (E5 — every submitted proposal, merge-blocking on errors)
        run: uv run sprout propose check

  smoke:
    # Phase 1: a dedicated CI smoke suite of corpus-derived questions, distinct from the
    # hand-authored Phase 2 eval harness (job `eval-a11y` above). Every case here is
    # templated mechanically from the ingested corpus's own species/topic taxonomy, so
    # coverage tracks the corpus automatically — see src/sprout/smoke.py and
    # docs/ROADMAP.md Phase 1.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - name: Install (dev + serve)
        run: uv sync --locked --extra serve
      - name: Ingest the bundled corpus
        run: uv run sprout ingest
      - name: Corpus-derived smoke suite (merge-blocking)
        run: uv run sprout smoke --out docs/audits

  tuning-scope:
    # ROADMAP Phase 3: tune retrieval/prompts only against committed eval failures, never a
    # held-out set. Mechanical enforcement — see AIEV-30 / docs/ROADMAP.md.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          fetch-depth: 0 # full history + all remote branch refs; the gate diffs against origin/<base>
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - name: Install (dev)
        run: uv sync --locked
      - name: Tuning-scope gate
        env:
          BASE_REF: ${{ github.event.pull_request.base.ref || 'main' }}
        run: uv run sprout check-tuning-scope --base "origin/${BASE_REF}"

  web-static:
    # EXP-08 (docs/ideation/03-expansions.md): the TypeScript port's cross-language
    # conformance test — the deliverable's spine. Regenerates the fixtures from the
    # *current* Python pipeline on every run, so drift fails here, not later.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: "20"
          cache: npm
          cache-dependency-path: web-static/package-lock.json
      - name: Install (dev + serve)
        run: uv sync --locked --extra serve
      - name: Ingest the bundled corpus
        run: uv run sprout ingest
      - name: Export the static bundle (index.json + config.json)
        run: uv run python scripts/export_web_bundle.py
      - name: Generate cross-language conformance fixtures from the Python pipeline
        run: uv run python scripts/generate_conformance_fixtures.py
      - name: Install web-static deps
        run: cd web-static && npm ci
      - name: Typecheck
        run: cd web-static && npm run typecheck
      - name: Conformance test (142 eval-suite cases vs. the Python pipeline)
        run: cd web-static && npm test
      - name: Build the deployable static site
        run: cd web-static && npm run build:site
      - name: Structural accessibility check on the published surface
        run: uv run sprout a11y-check web-static/public/index.html

  pa11y:
    # Browser cross-check (axe + htmlcs runners, see web/.pa11yci.json) against the live-rendered
    # chat UI. Merge-blocking: was advisory-only (continue-on-error + `|| true`); promoted per
    # docs/ROADMAP.md gap tracking once the one real finding it caught (empty reminders table
    # tripping axe's th-has-data-cells) was fixed rather than papered over.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: "20"
      - name: Install + ingest
        run: uv sync --locked --extra serve && uv run sprout ingest
      - name: Serve and pa11y the UI (axe + htmlcs runners, merge-blocking)
        run: |
          uv run sprout serve &
          sleep 5
          npx --yes pa11y-ci --config web/.pa11yci.json

  lighthouse:
    # Lighthouse's accessibility category, scoped with --only-categories so this stays a
    # focused a11y gate (not a performance/SEO budget). Covers the chat UI and the committed
    # HTML eval report, per the WCAG 2.2 AA conformance row in docs/ROADMAP.md. Was previously
    # not wired into CI at all.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: "20"
      - name: Install + ingest
        run: uv sync --locked --extra serve && uv run sprout ingest
      - name: Regenerate the HTML eval report
        run: uv run sprout eval --out docs/audits
      - name: Serve + Lighthouse accessibility audit (chat UI + eval report, merge-blocking, threshold 0.95)
        run: |
          uv run sprout serve &
          python3 -m http.server 4173 --directory docs/audits &
          sleep 5

          npx --yes lighthouse http://127.0.0.1:8000/ \
            --only-categories=accessibility --output=json --output-path=lh-chat-ui.json \
            --chrome-flags="--headless=new --no-sandbox" --quiet
          npx --yes lighthouse http://127.0.0.1:4173/eval-report.html \
            --only-categories=accessibility --output=json --output-path=lh-eval-report.json \
            --chrome-flags="--headless=new --no-sandbox" --quiet

          python3 -c "
          import json, sys
          failed = False
          for label, path in [('chat UI', 'lh-chat-ui.json'), ('eval report', 'lh-eval-report.json')]:
              score = json.load(open(path))['categories']['accessibility']['score']
              print(f'{label} Lighthouse accessibility score: {score}')
              if score is None or score < 0.95:
                  failed = True
          sys.exit(1 if failed else 0)
          "
      - name: Upload Lighthouse reports
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: lighthouse-reports
          path: |
            lh-chat-ui.json
            lh-eval-report.json
          retention-days: 14

  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - name: Install (docs)
        run: uv sync --locked --group docs
      - name: MkDocs strict build
        run: uv run mkdocs build --strict

  zizmor:
    # Workflow-SAST review, RTA §F claim (CICD-19): any PR touching workflows is scanned.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - name: zizmor (workflow SAST)
        run: uvx zizmor --offline --min-severity high .github/workflows/

  ci-parity:
    # Mechanically proves `make verify` covers the same commands as this file's required jobs
    # (CONTRIBUTING.md "CI parity" note; ROADMAP.md ci-parity-no-mechanical-diff). Fails if this
    # workflow or the Makefile changes on one side without the other.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
      - name: Install (dev)
        run: uv sync --locked
      - name: make verify vs. ci-gate invocation diff
        run: uv run sprout ci-parity-check

  ci-gate:
    # The ONLY required status check for branch protection. axe, pa11y, and Lighthouse
    # accessibility are all merge-blocking (see docs/ROADMAP.md).
    if: always()
    needs: [test, security, eval-a11y, smoke, tuning-scope, web-static, pa11y, lighthouse, docs, zizmor, ci-parity]
    runs-on: ubuntu-latest
    steps:
      - name: Require all gates to pass (skipped path-filtered jobs are OK)
        # Interpolating join(needs.*.result) straight into the script body reads as a
        # template-injection-adjacent pattern to workflow-SAST tools (zizmor flags it);
        # the values are GitHub-controlled enums (success/failure/skipped/cancelled) so it
        # was never exploitable, but routing through env: satisfies the rule directly
        # instead of waiving it.
        env:
          GATE_RESULTS: ${{ join(needs.*.result, ' ') }}
        run: |
          echo "gate results: $GATE_RESULTS"
          for r in $GATE_RESULTS; do
            if [ "$r" != "success" ] && [ "$r" != "skipped" ]; then
              echo "::error::a required gate did not pass: $r"
              exit 1
            fi
          done