docs.yml

name: Deploy docs

# Builds the Astro Starlight site in site/ and publishes it to GitHub Pages.
# The reference section is regenerated in CI from plugins/ca/** (npm run build
# runs `prebuild` -> the generator), so the generated output is never committed.
#
# On pull_request the build job runs as validation only (no deploy) so a
# site-breaking change - e.g. a dep bump that outruns the runner's Node - is
# caught at review time instead of going red on main after merge. Deploy stays
# scoped to push: it needs pages:write/id-token:write, which a PR (especially
# from a fork) can't safely hold.

# This workflow triggers on ITSELF. It gates the site dependency graph (the
# audit step in site-check) and the deploy edge that makes that audit binding,
# and a change to any of that touches docs.yml and nothing else - which under
# the old `site/** + plugins/ca/**` filters started no run at all. Measured:
# the PR that ADDED the audit step never executed it, with 37 other checks
# green and no `Site |` check among them. Same defect class as #384.
on:
  push:
    branches: [main]
    paths:
      - "site/**"
      - "plugins/ca/**" # the reference is generated from the plugin, so rebuild when it changes
      - ".github/workflows/docs.yml" # this workflow gates the site graph; it must see its own edits
      # Issue #338: the site-voice gate and the detector it calls. Without these
      # a PR that only loosened the rule would skip the job that enforces it -
      # the same defect class the impact filter already guards for ci.yml.
      - ".github/scripts/check_site_voice.py"
      - "core/pysrc/_sloplib.py"
  pull_request:
    branches: [main]
    paths:
      - "site/**"
      - "plugins/ca/**"
      - ".github/workflows/docs.yml"
  workflow_dispatch:

# Least-privilege: only the deploy job needs pages/id-token:write, granted at
# job level below. The build job - which runs on PRs, including forks - stays
# read-only.
permissions:
  contents: read

# One run at a time per ref; let a newer push/PR-push supersede an in-flight
# run. Per-ref grouping keeps PR validation builds from cancelling a main
# deploy (and each other).
concurrency:
  group: pages-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # Gate the site's own test suite and typecheck. The Astro build (below) does
  # not run vitest or `tsc`, so without this job a broken site test or type
  # error would ship silently. Runs on the same site/** + plugins/ca/** triggers
  # as build; a red test here fails the workflow.
  site-check:
    name: Site | [Test] - Generator
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: site
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: 22 # Astro 6 requires Node >=22.12.0
          cache: npm
          cache-dependency-path: site/package-lock.json
      - name: Install deps
        run: npm ci
      - name: Audit (CVE gate - fail on HIGH)
        # Issue #403: nothing audited site/package-lock.json, so a known-
        # vulnerable production dependency could build and publish to GitHub
        # Pages with this whole workflow green. `deploy` needs this job, so a
        # red audit blocks the publish. Same threshold as the farm and sandbox
        # gates in ci.yml; --omit=dev scopes it to what the built site actually
        # ships, keeping routine Astro/vitest dev advisories non-blocking.
        run: npm audit --omit=dev --audit-level=high
      - name: Typecheck
        run: npm run typecheck
      - name: Enforce site/VOICE.md punctuation (issue #338)
        # site/VOICE.md has banned the em-dash as a sentence separator in site
        # prose since 2026-07-02, and NOTHING enforced it: _sloplib's scope
        # covered repo-root docs and docs/**, never site/. 16 of the 36 authored
        # pages violated the rule for 24 days while reviewers cited it at
        # contributors. A rule with no gate is worse than no rule - people learn
        # that the style docs are advisory.
        #
        # `deploy` needs this job, so a violation blocks the publish. Scope is
        # AUTHORED prose only, drawn from `git ls-files` via the shared
        # in_antislop_doc_scope: generated reference pages, the changelog
        # pass-through, and the curated plugin mirrors are all excluded, because
        # a finding nobody wrote and nobody can fix in place is noise.
        #
        # Runs from the repo root, not site/, since it audits tracked paths.
        working-directory: .
        run: python .github/scripts/check_site_voice.py
      - name: Test
        run: npm test

  build:
    name: Site | [Build] - Astro Pages
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: site
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: 22 # Astro 6 requires Node >=22.12.0; the action defaults to 20
          cache: npm
          cache-dependency-path: site/package-lock.json
      - name: Install deps
        run: npm ci
      - name: Build
        run: npm run build # prebuild regenerates the reference from plugins/ca/**
      - name: Link audit
        run: npm run link-audit # post-build dangling-link gate (AC-2/AC-4)
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: site/dist

  deploy:
    name: Site | [Deploy] - GitHub Pages
    needs: [build, site-check] # never publish a build whose tests/typecheck are red
    # Push to main only - pull_request builds are validation-only.
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    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