Check that every runbook pointer has an entry

Implemented-By: Grok 4.6

scripts/test-gate-scripts.sh

@@ -1,5 +1,5 @@
 #!/bin/sh
-# Self-test for the three gate scripts. It builds small fake trees in a temporary
+# Self-test for the gate scripts. It builds small fake trees in a temporary
 # directory and checks that each script passes the good tree and fails the bad ones.
 # Do not edit: this file defines the required behaviour of the scripts.
 set -eu
@@ -87,6 +87,65 @@ expect fail "table-form dependency without workspace = true" check-dep-docs.sh "
 tree "$tmp/d-sectok"; printf '\n[dependencies.serde]\nworkspace = true\nfeatures = ["derive"]\n' >> "$tmp/d-sectok/crates/loopd/Cargo.toml"
 expect pass "table-form dependency with workspace = true" check-dep-docs.sh "$tmp/d-sectok"
 
+# check-runbook.sh
+book() { # book ROOT [HEADING-LINES...]: a tree whose runbook has these lines
+    root="$1"; shift
+    tree "$root"
+    { printf '# Runbook\n\nProse that mentions grants-invalid is not an entry.\n\n'
+      for line in "$@"; do printf '%s\n\nText.\n\n' "$line"; done
+    } > "$root/docs/runbook.md"
+}
+src() { # src FILE TEXT: a source file holding TEXT
+    mkdir -p "$(dirname "$1")"
+    printf '%s\n' "$2" > "$1"
+}
+says() { # says NAME SCRIPT ROOT WORD...: the script's output must contain every WORD
+    name="$1"; script="$2"; root="$3"; shift 3
+    output=$(sh "$here/$script" "$root" 2>&1) || true
+    for word in "$@"; do
+        case "$output" in
+            *"$word"*) ;;
+            *) echo "test-gate-scripts: $name: output lacks $word" >&2; fails=$((fails + 1)) ;;
+        esac
+    done
+}
+
+book "$tmp/r-ok" '## grants-invalid' '## audit-unavailable'
+src "$tmp/r-ok/crates/brokerd/src/a.rs" 'eprintln!("see docs/runbook.md#grants-invalid");'
+src "$tmp/r-ok/crates/brokerd/src/b.rs" '// see docs/runbook.md#audit-unavailable.'
+expect pass "every pointer has an entry" check-runbook.sh "$tmp/r-ok"
+book "$tmp/r-miss" '## audit-unavailable'
+src "$tmp/r-miss/crates/brokerd/src/a.rs" 'eprintln!("see docs/runbook.md#grants-invalid");'
+expect fail "a pointer without an entry; a mention in prose is not one" check-runbook.sh "$tmp/r-miss"
+book "$tmp/r-h3" '### grants-invalid' '## grants-invalid and more' ' ## grants-invalid'
+src "$tmp/r-h3/crates/brokerd/src/a.rs" 'eprintln!("see docs/runbook.md#grants-invalid");'
+expect fail "the entry is the whole line, at level two" check-runbook.sh "$tmp/r-h3"
+book "$tmp/r-test" '## grants-invalid'
+src "$tmp/r-test/crates/brokerd/src/a.rs" 'eprintln!("see docs/runbook.md#grants-invalid");'
+src "$tmp/r-test/crates/brokerd/tests/t.rs" 'assert!(m.ends_with("see docs/runbook.md#no-such-entry"));'
+expect fail "a pointer in a test file counts" check-runbook.sh "$tmp/r-test"
+book "$tmp/r-line" '## grants-invalid'
+src "$tmp/r-line/crates/brokerd/src/a.rs" 'f("docs/runbook.md#grants-invalid", "docs/runbook.md#second-on-the-line");'
+expect fail "the second pointer on a line counts" check-runbook.sh "$tmp/r-line"
+book "$tmp/r-tgt" '## grants-invalid'
+src "$tmp/r-tgt/crates/brokerd/src/a.rs" 'eprintln!("see docs/runbook.md#grants-invalid");'
+src "$tmp/r-tgt/crates/brokerd/target/debug/gen.rs" 'eprintln!("see docs/runbook.md#no-such-entry");'
+expect pass "files under target/ are ignored" check-runbook.sh "$tmp/r-tgt"
+book "$tmp/r-case" '## grants-invalid'
+src "$tmp/r-case/crates/brokerd/src/a.rs" 'eprintln!("see docs/runbook.md#Grants-Invalid");'
+expect fail "anchors are compared exactly" check-runbook.sh "$tmp/r-case"
+book "$tmp/r-fmt" '## grants-invalid'
+src "$tmp/r-fmt/crates/brokerd/src/a.rs" 'eprintln!("see docs/runbook.md#grants-invalid");'
+src "$tmp/r-fmt/crates/brokerd/src/b.rs" 'eprintln!("see docs/runbook.md#{anchor}");'
+expect fail "a pointer whose anchor is not written out" check-runbook.sh "$tmp/r-fmt"
+# Report every problem, not only the first.
+book "$tmp/r-all" '## grants-invalid'
+src "$tmp/r-all/crates/brokerd/src/a.rs" 'eprintln!("see docs/runbook.md#first-missing");'
+src "$tmp/r-all/crates/loopd/src/b.rs" 'eprintln!("see docs/runbook.md#second-missing");'
+expect fail "two pointers without entries" check-runbook.sh "$tmp/r-all"
+says "both missing entries and their files are reported" check-runbook.sh "$tmp/r-all" \
+    first-missing second-missing crates/brokerd/src/a.rs crates/loopd/src/b.rs
+
 # A check that cannot find what it checks must fail, not pass.
 mkdir -p "$tmp/empty"
 expect fail "check-lines without a crates directory" check-lines.sh "$tmp/empty"
@@ -94,6 +153,12 @@ expect fail "check-crate-deps without a crates directory" check-crate-deps.sh "$
 expect fail "check-dep-docs without a crates directory" check-dep-docs.sh "$tmp/empty"
 tree "$tmp/d-nodoc"; rm "$tmp/d-nodoc/docs/dependencies.md"
 expect fail "check-dep-docs without docs/dependencies.md" check-dep-docs.sh "$tmp/d-nodoc"
+expect fail "check-runbook without a crates directory" check-runbook.sh "$tmp/empty"
+book "$tmp/r-nobook" '## grants-invalid'; rm "$tmp/r-nobook/docs/runbook.md"
+src "$tmp/r-nobook/crates/brokerd/src/a.rs" 'eprintln!("see docs/runbook.md#grants-invalid");'
+expect fail "check-runbook without docs/runbook.md" check-runbook.sh "$tmp/r-nobook"
+book "$tmp/r-none" '## grants-invalid'
+expect fail "check-runbook when no source file has a pointer" check-runbook.sh "$tmp/r-none"
 
 if [ "$fails" -ne 0 ]; then
     echo "test-gate-scripts: $fails failure(s)" >&2