open-standards/.github/workflows/spec-refs.yml

name: spec citations resolve

# Every `SPEC §N` a standard's code cites is a section that standard's SPEC.md
# has. See the header of scripts/check-spec-refs.py for why: a citation to a
# section that does not exist reads as authority it does not have, and the three
# instances found so far were each discovered by reading, long after they were
# written.
#
# Deliberately NO `paths:` filter, for two reasons.
#
# The check is one Python pass over the tree — about a second, no toolchain, no
# cargo — so running it on every change costs less than describing when to run
# it. And a correct filter here would have to name every standard's `**/*.rs`
# plus every `SPEC.md`; `standards-build.yml` records that `**`-prefixed globs
# do not match on this forge the way they do elsewhere, and that a gate which
# quietly fails to fire is worse than no gate, because it reports nothing and
# everyone reads that as green. An unfiltered cheap check cannot fail that way.
#
# The self-test runs first and on its own line. A check that cannot fail is
# decoration, and this one would be easy to break into permanent silence — a
# regex that stops matching finds nothing and exits 0.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  spec-refs:
    name: Code cites no section its SPEC lacks
    runs-on: linux
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: The check can fail (self-test)
        run: bash scripts/check-spec-refs-selftest.sh

      - name: Every SPEC citation resolves
        run: python3 scripts/check-spec-refs.py