ci.yml

# SPDX-License-Identifier: Apache-2.0
# nearmiss CI — the merge gate described in CONTRIBUTING.md and the threat model.
#
# Every job here mirrors a `make` target so contributors run the same checks
# locally (`make verify`) that CI enforces. Two gates exist specifically to
# protect the FIVE HARD RULES:
#   * `reproducibility` re-runs `make reproduce` and fails if the committed
#     published artifacts under data/published/ drift from a clean rebuild
#     (Rule 5: open and reproducible end to end; this is the tamper tripwire).
#   * `security` runs pip-audit + gitleaks + CodeQL so a leaked secret or a
#     vulnerable dependency cannot reach the public path (Rule 4 privacy,
#     Rule 5 reproducibility of trusted inputs).
#
# The accessibility job runs the STRUCTURAL gate (tools/a11y_check.py) AND a
# real automated axe-core run (jsdom) via `npm run axe` on every CI run.
# Manual NVDA/VoiceOver review is a conformance TARGET tracked in
# docs/accessibility/ACR.md. It is inherently human and remains intentionally
# OUT of CI scope. A one-person public preview may use ADR 0012's expiring,
# owner-attested provisional REVIEW disposition; it is not a manual pass or a
# conformance result, and every automated gate remains mandatory.

name: ci

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    # Nightly re-scan of `main` (SEC-08's nightly-CodeQL requirement), independent of push/PR
    # activity — a dependency's newly-published CVE or a new CodeQL query pack can surface a
    # finding on code that hasn't changed. Every job except `security` guards itself out on this
    # trigger (`if: github.event_name != 'schedule'`) so a nightly run re-executes only the
    # CodeQL-bearing security job, not the whole suite.
    - cron: "0 7 * * *"

# Least privilege by default. Individual jobs widen scope only where a specific
# action needs it (CodeQL writes to the security-events API).
permissions:
  contents: read

# Cancel superseded runs on the same ref so a force-push or rapid re-push does
# not pile up redundant builds.
concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  # Superseded PR checks can be cancelled; never cancel an in-flight main deploy.
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

env:
  # CI installs from the hashed dev-toolchain lock (`requirements-dev.lock`,
  # `make lock-dev`) with `--require-hashes`, then the local package editable
  # and `--no-deps` (FIX-11 from the 2026-07-05 remediation pass).
  # `requirements.lock` (`make lock`) remains the separate, smaller
  # RUNTIME-only lock for consumers who just `pip install nearmiss`.
  PIP_DISABLE_PIP_VERSION_CHECK: "1"
  PIP_NO_PYTHON_VERSION_WARNING: "1"
  PYTHONHASHSEED: "0"

jobs:
  dco:
    name: dco (Signed-off-by on every commit)
    # The DCO merge gate documented in CONTRIBUTING.md: every commit in the PR
    # must carry a `Signed-off-by:` trailer (added with `git commit -s`).
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          # Need the full PR commit range, not just the merge commit.
          fetch-depth: 0
          persist-credentials: false

      - name: Verify Signed-off-by trailer on every PR commit
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          missing=0
          # Walk each commit in the PR range and require a DCO sign-off trailer.
          for sha in $(git rev-list "$BASE_SHA".."$HEAD_SHA"); do
            signoff="$(git log -1 --format='%(trailers:key=Signed-off-by)' "$sha")"
            if [ -z "$signoff" ]; then
              subject="$(git log -1 --format='%s' "$sha")"
              echo "::error::Commit $sha is missing a Signed-off-by trailer: $subject"
              missing=1
            fi
          done
          if [ "$missing" -ne 0 ]; then
            echo "::error::Sign off every commit with 'git commit -s' (see CONTRIBUTING.md)."
            exit 1
          fi

  lint:
    name: lint (ruff)
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      # CQ-09. This runs before anything else touches the environment, deliberately:
      # `uv lock --check` has to come before any command that could rewrite uv.lock
      # (a bare `uv run` silently relocks, which would repair the very drift this
      # gate exists to catch). Note that `uv sync --frozen` is NOT a drift gate — it
      # installs from uv.lock without reading pyproject.toml and exits 0 even when the
      # two disagree, which is how this repository's committed lock reached `main`
      # describing `nearmiss 0.2.0` while pyproject.toml declared `nearmiss-safety 0.3.1`.
      - name: Set up uv
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
        with:
          enable-cache: false

      - name: uv.lock is in sync with pyproject.toml (CQ-09)
        run: make lock-check

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dev dependencies (hashed, --require-hashes)
        # Installs the exact, hashed dev-toolchain lock (requirements-dev.lock,
        # `make lock-dev`, FIX-11) instead of a fresh, unpinned
        # `pip install -e ".[dev]"` resolve — the tools this gate runs
        # (pytest/ruff/mypy/pip-audit/babel/...) are pinned AND hash-verified,
        # not "whatever PyPI serves today." The local package then installs
        # editable and --no-deps, since it has no PyPI hash of its own.
        run: |
          python -m pip install --require-hashes -r requirements-dev.lock
          python -m pip install --no-deps -e .

      - name: ruff (check + format --check)
        run: make lint

  type:
    name: type (mypy --strict)
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dev dependencies (hashed, --require-hashes)
        # Installs the exact, hashed dev-toolchain lock (requirements-dev.lock,
        # `make lock-dev`, FIX-11) instead of a fresh, unpinned
        # `pip install -e ".[dev]"` resolve — the tools this gate runs
        # (pytest/ruff/mypy/pip-audit/babel/...) are pinned AND hash-verified,
        # not "whatever PyPI serves today." The local package then installs
        # editable and --no-deps, since it has no PyPI hash of its own.
        run: |
          python -m pip install --require-hashes -r requirements-dev.lock
          python -m pip install --no-deps -e .

      - name: mypy --strict
        run: make type

  test:
    name: test (pytest, known-answer fixtures)
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.11", "3.12"]
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip

      - name: Install dev dependencies (hashed, --require-hashes)
        # Installs the exact, hashed dev-toolchain lock (requirements-dev.lock,
        # `make lock-dev`, FIX-11) instead of a fresh, unpinned
        # `pip install -e ".[dev]"` resolve — the tools this gate runs
        # (pytest/ruff/mypy/pip-audit/babel/...) are pinned AND hash-verified,
        # not "whatever PyPI serves today." The local package then installs
        # editable and --no-deps, since it has no PyPI hash of its own.
        run: |
          python -m pip install --require-hashes -r requirements-dev.lock
          python -m pip install --no-deps -e .

      - name: pytest (planted hotspot seg-06 recovered, branch-coverage floor enforced)
        # `make test` runs pytest with --cov-branch and --cov-fail-under=90, so a
        # drop in meaningful coverage fails the merge gate (not just a test failure).
        run: make test
  qgis-plugin:
    name: qgis-plugin (EXP-11 honest-symbology rules, no PyQGIS needed)
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
          cache: pip

      # integrations/qgis/nearmiss_honest/rules.py + verify.py are deliberately
      # PyQGIS-free (there is no pip-installable `qgis` package; PyQGIS only
      # ships inside a QGIS install), so this job needs only pytest itself —
      # not the project's own dependencies — to exercise the invariant logic
      # the plugin's renderer/tooltip/CLI rely on, against the two bundled
      # sample datasets.
      - name: Install pytest
        run: python -m pip install pytest
      - name: qgis plugin rules (make qgis-plugin-test)
        run: make qgis-plugin-test

  teaching:
    name: teaching (execute EXP-12 heat-map notebooks)
    # EXP-12 "How to lie with heat maps" module: execute the three bilingual
    # teaching notebooks over the synthetic Davis fixtures and fail if any cell
    # errors. Like `make reproduce`, this is a reproducibility tripwire — the
    # notebooks are seeded/known-answer, so a red cell means the analysis API or
    # the fixtures drifted. The Jupyter execution stack is the isolated
    # `.[teaching]` extra (NOT in `dev`), so the security job's audited
    # dependency surface is unchanged.
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
          cache: pip

      - name: Install the package with the teaching extra
        run: python -m pip install -e ".[teaching]"

      - name: Execute the teaching notebooks (make teach)
        # `make teach` runs `nbconvert --execute` on notebooks/teaching/*.ipynb
        # into the gitignored notebooks/_build/. A cell that raises fails the job.
        run: make teach

  i18n:
    name: i18n (gettext catalog gate)
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
          cache: pip

      # msgfmt (G7 PO-compilation gate) is a system gettext binary, not a pip
      # dependency — installed here just like the security job would install a
      # non-pip scanner. babel/pybabel come from the dev extras below.
      - name: Install gettext (msgfmt)
        run: sudo apt-get update && sudo apt-get install -y gettext

      - name: Install dev dependencies
        run: python -m pip install -e ".[dev]"

      # Exactly what `make verify` runs locally (no local/CI drift): G2-lite
      # (POT committed & current), G7 (msgfmt --check), G6/G5 (EN/ES key-parity +
      # completeness + placeholder parity), G3 (BCP 47 tag validity).
      - name: i18n catalog gate (make i18n)
        run: make i18n

  claims:
    name: claims (docs-code claims-parity drift gate)
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dev dependencies
        run: python -m pip install -e ".[dev]"

      # Exactly what `make verify` runs locally (no local/CI drift): the
      # docs/CLAIMS.md manifest, <!-- claim:… --> doc tags, and code witnesses
      # must stay in three-way agreement or this job fails.
      - name: Claims-parity gate (make claims)
        run: make claims

      # CQ-34 is declared an AUTO-GATE by the vendored CODE-QUALITY-STANDARD and
      # had no implementation anywhere until tools/check_debt_markers.py. Runs in
      # this job rather than its own so the two "the docs and the tree agree"
      # gates share one checkout. Pure stdlib: no extra install cost.
      - name: Debt-marker gate, CQ-34 (make markers)
        run: make markers

  accessibility:
    name: accessibility (structural WCAG gate + axe-core on web UI)
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dev dependencies (hashed, --require-hashes)
        # Installs the exact, hashed dev-toolchain lock (requirements-dev.lock,
        # `make lock-dev`, FIX-11) instead of a fresh, unpinned
        # `pip install -e ".[dev]"` resolve — the tools this gate runs
        # (pytest/ruff/mypy/pip-audit/babel/...) are pinned AND hash-verified,
        # not "whatever PyPI serves today." The local package then installs
        # editable and --no-deps, since it has no PyPI hash of its own.
        run: |
          python -m pip install --require-hashes -r requirements-dev.lock
          python -m pip install --no-deps -e .

      - name: Set up Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
        with:
          node-version: "20"
          # CI-CD-STANDARD §11f: reuse the npm cache keyed on the committed
          # lockfile (the axe/contract/rtl steps below run `npm ci` against it).
          cache: npm
          cache-dependency-path: web/package-lock.json

      # The deployed national studio and retained local prototypes are plain
      # static HTML. `make accessibility` runs the structural gate across both
      # scopes (skip links, landmarks, semantic tables, and text equivalents).
      - name: a11y structural gate (production and source-only HTML)
        run: make accessibility

      # Real automated axe-core run in jsdom (tools/axe_check.mjs), so the
      # axe-core check runs on every CI run in addition to the structural gate.
      # `web/package-lock.json` is committed, so this merge-blocking job installs
      # with `npm ci` — it resolves axe-core/jsdom exactly from the committed
      # lockfile instead of a fresh registry resolve, matching the local `make
      # axe` target (Makefile) and closing the supply-chain gap where a
      # merge-blocking gate ran unpinned code. Manual NVDA/VoiceOver review is
      # inherently human and is intentionally OUT of CI scope — it stays tracked
      # in docs/accessibility/ACR.md.
      - name: axe-core (jsdom) accessibility check
        run: cd web && npm ci && npm run axe

      # Web-consumer contract gate (FIX-10): boot app.js against a committed
      # published GeoJSON in jsdom and assert it honors schema/dataset.schema.json
      # (every consumed property is schema-required; dropping one breaks the map).
      - name: dataset schema contract (jsdom web consumer)
        run: cd web && npm run contract

      # G10: parse every authored page under dir=rtl and scan both inline styles
      # and locally linked authored CSS for physical horizontal properties.
      - name: RTL authored-layout smoke
        run: cd web && npm run rtl

  security:
    name: security (pip-audit + gitleaks + CodeQL)
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      security-events: write # Upload CodeQL SARIF to this repository's code-scanning API.
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          # gitleaks needs full history to scan every commit on the PR/push.
          fetch-depth: 0
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dev dependencies (hashed, --require-hashes)
        # Installs the exact, hashed dev-toolchain lock (requirements-dev.lock,
        # `make lock-dev`, FIX-11) instead of a fresh, unpinned
        # `pip install -e ".[dev]"` resolve — the tools this gate runs
        # (pytest/ruff/mypy/pip-audit/babel/...) are pinned AND hash-verified,
        # not "whatever PyPI serves today." The local package then installs
        # editable and --no-deps, since it has no PyPI hash of its own.
        run: |
          python -m pip install --require-hashes -r requirements-dev.lock
          python -m pip install --no-deps -e .

      # Dependency vulnerability scan — blocking. A known-vulnerable dependency
      # fails the build (no `|| true`), per SECURITY-AND-SUPPLY-CHAIN §3. The
      # retry absorbs a transient advisory-database fetch failure (CI runners are
      # not guaranteed egress) without silencing a real finding.
      # Audit the hashed dev lock rather than the live environment: the local
      # editable nearmiss install is not a PyPI release, so an environment
      # audit errors on it ("not found") — and at version 0.1.0 it silently
      # audited a same-named stranger's PyPI package. -r requirements-dev.lock
      # scans the exact pinned+hashed dependency set the gates install
      # (`make security` runs the identical command).
      - name: pip-audit (known-vulnerable dependencies)
        run: |
          for attempt in 1 2 3; do
            python -m pip_audit --strict --require-hashes --disable-pip -r requirements-dev.lock && exit 0
            echo "pip-audit attempt $attempt failed; retrying in 10s..." && sleep 10
          done
          python -m pip_audit --strict --require-hashes --disable-pip -r requirements-dev.lock

      - name: gitleaks (committed secrets)
        uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e  # v3.0.0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # Python, the web JS (web/app.js, submit.js, embed.js, nearmiss-embed.js — CICD-20's prior
      # "JS unscanned since 6/21" finding), and the workflow YAML itself (the "actions" CodeQL
      # language, GA since codeql-action v3.28). One init/analyze pair covers all three; the
      # action auto-scopes each language's SARIF to its own code-scanning category, so no manual
      # `category:` override is needed (and would be wrong once >1 language is configured).
      - name: Initialize CodeQL (python, javascript, actions)
        uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3  # v4.37.6
        with:
          languages: python, javascript, actions
          queries: security-extended

      - name: Analyze with CodeQL
        uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3  # v4.37.6
        with:
          # Keep the normal code-scanning upload and also retain local SARIF so
          # this required job makes its own merge-blocking pass/fail decision.
          upload: always
          output: codeql-results

      - name: Enforce zero CodeQL findings
        shell: bash
        run: |
          set -euo pipefail
          shopt -s nullglob
          sarif=(codeql-results/*.sarif)
          if (( ${#sarif[@]} == 0 )); then
            echo "CodeQL produced no SARIF output" >&2
            exit 1
          fi
          count=$(jq -s '[.[] | .runs[]?.results[]?] | length' "${sarif[@]}")
          if (( count > 0 )); then
            echo "CodeQL reported ${count} finding(s)" >&2
            exit 1
          fi

  zizmor:
    name: zizmor (GitHub Actions workflow SAST)
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      # `advanced-security: false` makes zizmor-action itself fail the job on a
      # finding at or above `min-severity` — a real merge-blocking gate that does
      # not depend on GitHub Advanced Security or a configured code-scanning
      # merge-protection rule (CICD-19). zizmor's top severity tier is `high`
      # (there is no separate "critical"), so `min-severity: high` is this
      # project's High/Critical bar.
      - name: zizmor (workflow SAST, blocking on high severity)
        uses: zizmorcore/zizmor-action@3dc1ecc9bcb9e94e9b2c709687979e1298497054  # v0.6.2
        with:
          advanced-security: false
          min-severity: high

  reproducibility:
    name: reproducibility (make reproduce + diff published artifacts)
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dev dependencies (hashed, --require-hashes)
        # Installs the exact, hashed dev-toolchain lock (requirements-dev.lock,
        # `make lock-dev`, FIX-11) instead of a fresh, unpinned
        # `pip install -e ".[dev]"` resolve — the tools this gate runs
        # (pytest/ruff/mypy/pip-audit/babel/...) are pinned AND hash-verified,
        # not "whatever PyPI serves today." The local package then installs
        # editable and --no-deps, since it has no PyPI hash of its own.
        run: |
          python -m pip install --require-hashes -r requirements-dev.lock
          python -m pip install --no-deps -e .

      # Rule 5: a clean rebuild from raw inputs must reproduce the committed
      # public artifacts byte-for-byte. Synthetic fixtures (not private raw
      # reports) drive the public-path rebuild in CI.
      - name: Rebuild the published GeoJSON + brief from raw inputs
        run: make reproduce

      - name: Fail if published artifacts drifted from a clean rebuild
        run: |
          if ! git diff --exit-code -- data/published; then
            echo "::error::data/published drifted from 'make reproduce'." \
              "Commit the regenerated artifacts or fix the non-deterministic step."
            exit 1
          fi
          # Catch newly generated, uncommitted published files as well.
          if [ -n "$(git status --porcelain -- data/published)" ]; then
            echo "::error::'make reproduce' produced untracked files under data/published."
            git status --porcelain -- data/published
            exit 1
          fi

  build-pages:
    name: build minimal public artifact
    # Exercise the exact Pages assembly and packaging path on PRs as well as
    # main. Nightly runs are security-only and intentionally skip this job.
    if: github.event_name != 'schedule'
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout the candidate commit
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Configure Pages
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

      - name: Assemble minimal public artifact
        run: python tools/build_site.py --out _site --sha "$GITHUB_SHA"

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: _site

      - name: Upload immutable CloudFront artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: static-site-${{ github.sha }}
          path: _site
          if-no-files-found: error
          include-hidden-files: true
          retention-days: 7

  deploy-cloudfront:
    name: deploy nearmiss.chelseakr.com
    if: github.event_name == 'push'
    needs:
      - lint
      - type
      - test
      - qgis-plugin
      - teaching
      - i18n
      - claims
      - accessibility
      - security
      - zizmor
      - reproducibility
      - build-pages
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    permissions:
      contents: read
      id-token: write
    environment:
      name: production
      url: https://nearmiss.chelseakr.com
    steps:
      - name: Download the reviewed static artifact
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: static-site-${{ github.sha }}
          path: _site

      - name: Checkout the exact source without touching the artifact
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          path: source
          persist-credentials: false

      - name: Rebuild and byte-verify before obtaining deploy authority
        run: |
          if [ -n "$(find _site -type l -print -quit)" ]; then
            echo "::error::downloaded static artifact contains a symlink"
            exit 1
          fi
          python -S source/tools/build_site.py \
            --out _expected-site \
            --sha "$GITHUB_SHA"
          diff --recursive --brief _expected-site _site

      - name: Authenticate to AWS with GitHub OIDC
        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
        with:
          aws-region: ${{ vars.AWS_REGION }}
          role-to-assume: ${{ vars.AWS_DEPLOY_ROLE_ARN }}
          role-session-name: nearmiss-${{ github.run_id }}

      - name: Publish the exact artifact to the private origin
        run: |
          cache_control='public, max-age=0, must-revalidate'
          for host_control in .nojekyll CNAME; do
            aws s3 rm "s3://${{ vars.NEARMISS_S3_BUCKET }}/$host_control" --only-show-errors
          done
          aws s3 sync _site "s3://${{ vars.NEARMISS_S3_BUCKET }}/" \
            --delete --exclude '.nojekyll' --exclude 'CNAME' \
            --cache-control "$cache_control" --only-show-errors

          # Do not delegate browser-significant MIME metadata to runner-local
          # /etc/mime.types. CloudFront sends nosniff, so a correct payload with
          # generic S3 metadata is still a broken deployment.
          mime_specs=(
            '*.html|text/html; charset=utf-8'
            '*.js|application/javascript; charset=utf-8'
            '*.css|text/css; charset=utf-8'
            '*.json|application/json; charset=utf-8'
            '*.geojson|application/geo+json'
            '*.svg|image/svg+xml'
            '*.woff2|font/woff2'
            '*.png|image/png'
          )
          for spec in "${mime_specs[@]}"; do
            pattern="${spec%%|*}"
            content_type="${spec#*|}"
            aws s3 cp _site "s3://${{ vars.NEARMISS_S3_BUCKET }}/" \
              --recursive --exclude '*' --include "$pattern" \
              --content-type "$content_type" --cache-control "$cache_control" \
              --only-show-errors
          done
          for host_control in .nojekyll CNAME; do
            aws s3 rm "s3://${{ vars.NEARMISS_S3_BUCKET }}/$host_control" --only-show-errors
          done

      - name: Invalidate and wait for the public edge
        env:
          DISTRIBUTION_ID: ${{ vars.NEARMISS_CLOUDFRONT_DISTRIBUTION_ID }}
        run: |
          invalidation_id="$(aws cloudfront create-invalidation \
            --distribution-id "$DISTRIBUTION_ID" \
            --paths '/*' \
            --query 'Invalidation.Id' \
            --output text)"
          aws cloudfront wait invalidation-completed \
            --distribution-id "$DISTRIBUTION_ID" \
            --id "$invalidation_id"

      - name: Verify exact live bytes and denied-path retirement
        run: >-
          python -S source/tools/verify_live_site.py
          --expected-sha "$GITHUB_SHA"
          --attempts 12
          --retry-seconds 10
          --timeout-seconds 10
          --deadline-seconds 480

  deploy-pages:
    name: deploy minimal public artifact
    if: github.event_name == 'push'
    needs:
      - lint
      - type
      - test
      - qgis-plugin
      - teaching
      - i18n
      - claims
      - accessibility
      - security
      - zizmor
      - reproducibility
      - build-pages
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      pages: write # Publish only the reviewed artifact through GitHub Pages.
      id-token: write # Authenticate that Pages deployment with short-lived OIDC.
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

      - name: Verify deployed commit, critical paths, and retired-path denial
        env:
          SITE_URL: ${{ steps.deployment.outputs.page_url }}
        run: |
          set -euo pipefail
          base_url="${SITE_URL%/}"
          manifest_file="$(mktemp)"
          critical_dir="$(mktemp -d)"
          fars_index_file="$critical_dir/data/published/fars-state-mode-index-v2.json"
          boundary_file="$critical_dir/data/published/us-state-boundaries-2024.json"
          boundary_sha256="705219b3339077f1d03466391bb286fe7f1841298fc0bcce948de1d8c66df25d"
          fars_release_dir="$(mktemp -d)"
          trap 'rm -f "$manifest_file"; rm -rf "$critical_dir" "$fars_release_dir"' EXIT
          critical_specs=(
            'index.html|'
            '404.html|404.html'
            'deployment.json|deployment.json'
            'web/index.html|web/index.html'
            'web/us-coverage.html|web/us-coverage.html'
            'fars/national/index.html|fars/national/'
            'dossier/index.html|dossier/'
            'studio/index.html|studio/'
            'web/dossier.js|web/dossier.js'
            'web/studio.js|web/studio.js'
            'web/workflow.css|web/workflow.css'
            'web/interface.css|web/interface.css'
            'web/us-coverage.js|web/us-coverage.js'
            'web/i18n.js|web/i18n.js'
            'web/landing.css|web/landing.css'
            'web/locales/en.json|web/locales/en.json'
            'web/locales/es.json|web/locales/es.json'
            'web/us-coverage.css|web/us-coverage.css'
            'web/us-coverage-studio.css|web/us-coverage-studio.css'
            'web/brand.css|web/brand.css'
            'web/style.css|web/style.css'
            'web/vendor/fonts/overpass-latin-wght-normal.woff2|web/vendor/fonts/overpass-latin-wght-normal.woff2'
            'web/vendor/fonts/atkinson-hyperlegible-next-latin-wght-normal.woff2|web/vendor/fonts/atkinson-hyperlegible-next-latin-wght-normal.woff2'
            'web/vendor/fonts/fragment-mono-latin-400-normal.woff2|web/vendor/fonts/fragment-mono-latin-400-normal.woff2'
            'data/published/fars-state-mode-index.json|data/published/fars-state-mode-index.json'
            'data/published/fars-2024-state-mode.json|data/published/fars-2024-state-mode.json'
            'data/published/fars-state-mode-index-v2.json|data/published/fars-state-mode-index-v2.json'
            'data/published/fars-release-corrections.json|data/published/fars-release-corrections.json'
            'data/published/us-state-boundaries-2024.json|data/published/us-state-boundaries-2024.json'
          )
          retired_paths=(
            'web/app.js'
            'web/davis-demo.html'
            'web/embed.css'
            'web/embed.html'
            'web/embed.js'
            'web/nearmiss-embed.js'
            'web/share-card.js'
            'web/submit.html'
            'web/submit.js'
            'web/vendor/leaflet/images/layers-2x.png'
            'web/vendor/leaflet/images/layers.png'
            'web/vendor/leaflet/images/marker-icon-2x.png'
            'web/vendor/leaflet/images/marker-icon.png'
            'web/vendor/leaflet/images/marker-shadow.png'
            'web/vendor/leaflet/leaflet.css'
            'web/vendor/leaflet/leaflet.js'
            'data/published/davis-ranked.md'
            'data/published/davis-rates.svg'
            'data/published/davis-sensitivity.md'
            'data/published/davis.corridors.geojson'
            'data/published/davis.geojson'
            'data/published/davis.metadata.json'
            'data/published/riverside-ranked.md'
            'data/published/riverside-rates.svg'
            'data/published/riverside-sensitivity.md'
            'data/published/riverside.corridors.geojson'
            'data/published/riverside.geojson'
            'data/published/riverside.metadata.json'
            'data/published/preregistration/README.md'
          )
          for _ in $(seq 1 30); do
            if curl --fail --silent --show-error \
              "${base_url}/site-manifest.json" --output "$manifest_file"; then
              deployed_sha="$(python -c \
                'import json,sys; print(json.load(open(sys.argv[1]))["source_sha"])' \
                "$manifest_file")" || true
              if [ "$deployed_sha" = "$GITHUB_SHA" ]; then
                critical_ok=true
                for spec in "${critical_specs[@]}"; do
                  manifest_path="${spec%%|*}"
                  url_path="${spec#*|}"
                  live_file="$critical_dir/$manifest_path"
                  mkdir -p "$(dirname "$live_file")"
                  if ! expected_sha="$(python -c \
                    'import json,re,sys; d=json.load(open(sys.argv[1]))["files"][sys.argv[2]]; assert re.fullmatch(r"[0-9a-f]{64}", d); print(d)' \
                    "$manifest_file" "$manifest_path")"; then
                    critical_ok=false
                    break
                  fi
                  if ! curl --fail --silent --show-error \
                    "${base_url}/${url_path}" --output "$live_file"; then
                    critical_ok=false
                    break
                  fi
                  live_sha="$(python -c \
                    'import hashlib,sys; print(hashlib.sha256(open(sys.argv[1], "rb").read()).hexdigest())' \
                    "$live_file")"
                  if [ "$live_sha" != "$expected_sha" ]; then
                    critical_ok=false
                    break
                  fi
                done
                if [ "$critical_ok" = true ]; then
                  live_boundary_sha="$(python -c \
                    'import hashlib,sys; print(hashlib.sha256(open(sys.argv[1], "rb").read()).hexdigest())' \
                    "$boundary_file")"
                  if [ "$live_boundary_sha" != "$boundary_sha256" ]; then
                    critical_ok=false
                  fi
                fi
                if [ "$critical_ok" = true ]; then
                  if ! python -c '
          import json,sys
          files=json.load(open(sys.argv[1]))["files"]
          retired=set(sys.argv[2:])
          assert not retired.intersection(files)
          ' "$manifest_file" "${retired_paths[@]}"; then
                    critical_ok=false
                  fi
                fi
                if [ "$critical_ok" = true ]; then
                  retired_ok=true
                  for retired_path in "${retired_paths[@]}"; do
                    retired_file="$critical_dir/retired/$retired_path"
                    mkdir -p "$(dirname "$retired_file")"
                    retired_status="$(curl --silent --show-error \
                      --output "$retired_file" --write-out '%{http_code}' \
                      "${base_url}/${retired_path}?verify=${GITHUB_SHA}")" || retired_status=""
                    if [ "$retired_status" != 404 ] || \
                      ! cmp --silent "$critical_dir/404.html" "$retired_file"; then
                      retired_ok=false
                      break
                    fi
                  done
                  if [ "$retired_ok" != true ]; then
                    critical_ok=false
                  fi
                fi
                if [ "$critical_ok" = true ]; then
                  release_records="$(python -c '
          import json,re,sys
          index=json.load(open(sys.argv[1]))
          releases=index["releases"]
          years=[release["dataset_year"] for release in releases]
          assert 1 <= len(releases) <= 5 and years == sorted(set(years))
          assert index["default_year"] == years[-1]
          for release in releases:
              path=release["artifact_path"]
              size=release["artifact_bytes"]
              digest=release["artifact_sha256"]
              assert re.fullmatch(r"fars-[0-9]{4}-state-mode(?:-r[2-9][0-9]*)?[.]json", path)
              assert type(size) is int and 1 <= size <= 262144
              assert re.fullmatch(r"[0-9a-f]{64}", digest)
              print(f"{path}\t{size}\t{digest}")
          ' "$fars_index_file")" || release_records=""
                  releases_ok=true
                  if [ -z "$release_records" ]; then
                    releases_ok=false
                  else
                    while IFS=$'\t' read -r artifact_path artifact_bytes artifact_sha; do
                      artifact_file="$fars_release_dir/$artifact_path"
                      manifest_artifact_path="data/published/$artifact_path"
                      if ! manifest_artifact_sha="$(python -c \
                        'import json,re,sys; d=json.load(open(sys.argv[1]))["files"][sys.argv[2]]; assert re.fullmatch(r"[0-9a-f]{64}", d); print(d)' \
                        "$manifest_file" "$manifest_artifact_path")"; then
                        releases_ok=false
                        break
                      fi
                      if ! curl --fail --silent --show-error \
                        "${base_url}/${manifest_artifact_path}" \
                        --output "$artifact_file"; then
                        releases_ok=false
                        break
                      fi
                      live_bytes="$(python -c \
                        'import os,sys; print(os.path.getsize(sys.argv[1]))' \
                        "$artifact_file")"
                      live_sha="$(python -c \
                        'import hashlib,sys; print(hashlib.sha256(open(sys.argv[1], "rb").read()).hexdigest())' \
                        "$artifact_file")"
                      if [ "$live_bytes" != "$artifact_bytes" ] || \
                        [ "$live_sha" != "$artifact_sha" ] || \
                        [ "$live_sha" != "$manifest_artifact_sha" ]; then
                        releases_ok=false
                        break
                      fi
                    done <<< "$release_records"
                  fi
                  if [ "$releases_ok" = true ]; then
                    exit 0
                  fi
                fi
              fi
            fi
            sleep 5
          done
          echo "::error::deployed site did not converge to ${GITHUB_SHA}"
          exit 1