docs-a11y.yml

# Scans the built docs site for WCAG 2 AA accessibility violations with
# pa11y-ci, using the same "hugo server" flow contributors run locally
# (see docs/Dockerfile). Originally landed as the last step of the
# docs-a11y-audit remediation (PR 9); the docs-a11y-smart-gate plan later
# evolved it from a fixed URL list into a path-aware, two-tier scan:
#
#   Tier 1 (always): a small static list of layout-archetype pages in
#   docs/.pa11yci.json, each scanned in both themes — guards against
#   systemic regressions (shared CSS/JS/templates/SVG) on every run.
#
#   Tier 2 (pull_request only): the content pages the PR actually
#   modifies, mapped from changed Markdown to rendered URLs by
#   scripts/docs-a11y-urls.sh (deterministically capped, both themes) —
#   guards against authored-content issues on exactly what changed. A
#   generated config (static + changed) is used when there's anything to
#   add; push-to-main and content-free PRs fall back to the static-only
#   config, since there's no PR diff to compute Tier 2 from.
#
# Each URL is listed once with ?theme=light and once with ?theme=dark:
# the headless browser's default color-scheme is otherwise indeterminate
# (observed as "light" locally), so without the query param the gate
# would only ever exercise one theme. js/app.js's initTheme() honors
# ?theme= ahead of localStorage/prefers-color-scheme for exactly this
# reason.
#
# The changed-file diff is git-native (`git diff HEAD^1 HEAD` against the
# pull_request test-merge commit, fetch-depth: 2) rather than a
# changed-files action, keeping the SHA-pinned, minimal-supply-chain
# convention (see scripts/docs-a11y-urls.sh's header for the mapping
# rules and env vars, and docs/STYLE.md for how to reproduce a scan
# locally).
#
# pa11y only treats HTML_CodeSniffer "error"-level results as failures
# (warnings/notices are informational and excluded by default), so this
# gates on real violations rather than every possible nit.
name: docs-a11y

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

on:
  push:
    branches: [main]
    paths:
      - ".github/workflows/docs-a11y.yml"
      - "docs/**"
      - "scripts/docs-a11y-urls.sh"
  pull_request:
    paths:
      - ".github/workflows/docs-a11y.yml"
      - "docs/**"
      - "scripts/docs-a11y-urls.sh"

env:
  HUGO_VERSION: 0.163.0

jobs:
  pa11y:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          # Need the merge commit's parent too, so `git diff HEAD^1 HEAD`
          # (below) can compute the PR's changed files without a
          # changed-files action or extra token scope.
          fetch-depth: 2

      # pa11y-ci@3.1.0 bundles an old Puppeteer whose postinstall Chromium
      # download doesn't happen under `npx --yes` ("Could not find expected
      # browser (chrome) locally"). Installing a pinned Chrome and pointing
      # Puppeteer at it via PUPPETEER_EXECUTABLE_PATH (below) sidesteps that
      # download entirely, per pa11y-ci's own guidance for Ubuntu > 20.04.
      - name: Install Chrome
        id: setup-chrome
        uses: browser-actions/setup-chrome@2e1d749697dd1612b833dba4a722266286fbefcd # v2.1.2
        with:
          chrome-version: stable

      - name: Install Hugo
        run: |
          curl -fsSL "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" \
            | sudo tar -xz -C /usr/local/bin hugo
          hugo version

      - name: Start Hugo server
        working-directory: docs
        run: nohup hugo server --bind 127.0.0.1 --port 1313 > hugo-server.log 2>&1 &

      - name: Wait for server
        run: npx --yes wait-on@7.2.0 http://127.0.0.1:1313/docker-agent/ --timeout 60000

      # Tier 2: map this PR's changed content Markdown to rendered URLs.
      # `actions/checkout` puts the pull_request test-merge commit at
      # HEAD, whose first parent (HEAD^1) is the base branch tip, so this
      # diff is exactly the PR's changed files — token-free and identical
      # for fork PRs. Skipped on push (no PR diff to compute from).
      - name: Compute changed-page URLs
        id: changed-urls
        if: github.event_name == 'pull_request'
        env:
          A11Y_BASE_URL: http://127.0.0.1:1313
        run: |
          git diff --name-only --diff-filter=d HEAD^1 HEAD \
            | ./scripts/docs-a11y-urls.sh > /tmp/changed-urls.txt
          count=$(wc -l < /tmp/changed-urls.txt | tr -d ' ')
          echo "count=$count" >> "$GITHUB_OUTPUT"
          echo "Tier 2: $count changed-page URL(s):"
          cat /tmp/changed-urls.txt

      # Merge Tier 2's URLs into the static (Tier 1) config from
      # docs/.pa11yci.json. Only runs when there's something to add;
      # otherwise the run step below falls back to the static-only config.
      - name: Assemble pa11y config
        if: github.event_name == 'pull_request' && steps.changed-urls.outputs.count != '0'
        run: |
          jq -Rn '[inputs]' /tmp/changed-urls.txt > /tmp/changed-urls.json
          jq --slurpfile extra /tmp/changed-urls.json '.urls += $extra[0]' \
            docs/.pa11yci.json > /tmp/pa11yci.generated.json
          echo "Merged pa11y-ci config (static + changed pages):"
          jq -r '.urls[]' /tmp/pa11yci.generated.json

      - name: Run pa11y-ci
        working-directory: docs
        env:
          PUPPETEER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
        run: |
          config=.pa11yci.json
          if [ -f /tmp/pa11yci.generated.json ]; then
            config=/tmp/pa11yci.generated.json
          fi
          echo "Using pa11y-ci config: $config"
          npx --yes pa11y-ci@3.1.0 --config "$config"

      - name: Show Hugo server log on failure
        if: failure()
        working-directory: docs
        run: cat hugo-server.log || true