Check that every runbook pointer has an entry

Implemented-By: Grok 4.6

scripts/check-runbook.sh

@@ -0,0 +1,112 @@
+#!/bin/sh
+# Fails if a *.rs file under ROOT/crates names a docs/runbook.md#anchor that
+# has no matching `## <anchor>` line in ROOT/docs/runbook.md.
+# Files under any target/ directory are ignored. Test files count.
+ROOT="${1:-.}"
+
+if [ ! -d "$ROOT/crates" ]; then
+    echo "check-runbook: $ROOT/crates is not a directory" >&2
+    exit 1
+fi
+if [ ! -f "$ROOT/docs/runbook.md" ]; then
+    echo "check-runbook: $ROOT/docs/runbook.md is not a file" >&2
+    exit 1
+fi
+
+work=$(mktemp -d)
+if [ $? -ne 0 ] || [ -z "$work" ]; then
+    echo "check-runbook: mktemp failed" >&2
+    exit 1
+fi
+trap 'rm -rf "$work"' EXIT
+
+find "$ROOT/crates" -type d -name target -prune -o -type f -name '*.rs' -print \
+    > "$work/files"
+if [ $? -ne 0 ]; then
+    echo "check-runbook: find failed" >&2
+    exit 1
+fi
+
+: > "$work/pointers"
+while IFS= read -r f; do
+    if [ ! -r "$f" ]; then
+        echo "check-runbook: cannot read $f" >&2
+        exit 1
+    fi
+    awk '{
+        s = $0
+        while (match(s, /docs\/runbook\.md#[A-Za-z0-9_-]*/)) {
+            printf "%s\t%s\n", substr(s, RSTART + 16, RLENGTH - 16), FILENAME
+            s = substr(s, RSTART + RLENGTH)
+        }
+    }' "$f" >> "$work/pointers"
+    if [ $? -ne 0 ]; then
+        echo "check-runbook: awk failed on $f" >&2
+        exit 1
+    fi
+done < "$work/files"
+
+if [ ! -s "$work/pointers" ]; then
+    echo "check-runbook: no pointer found" >&2
+    exit 1
+fi
+
+sort "$work/pointers" > "$work/sorted"
+if [ $? -ne 0 ]; then
+    echo "check-runbook: sort failed" >&2
+    exit 1
+fi
+
+awk -F '\t' '{ print $1 }' "$work/sorted" > "$work/col1"
+if [ $? -ne 0 ]; then
+    echo "check-runbook: awk failed" >&2
+    exit 1
+fi
+sort -u "$work/col1" > "$work/anchors"
+if [ $? -ne 0 ]; then
+    echo "check-runbook: sort failed" >&2
+    exit 1
+fi
+
+status=0
+while IFS= read -r anchor; do
+    awk -F '\t' -v a="$anchor" '$1 == a { print $2 }' "$work/sorted" > "$work/hits"
+    if [ $? -ne 0 ]; then
+        echo "check-runbook: awk failed" >&2
+        exit 1
+    fi
+    sort -u "$work/hits" > "$work/hitfiles"
+    if [ $? -ne 0 ]; then
+        echo "check-runbook: sort failed" >&2
+        exit 1
+    fi
+    files=""
+    while IFS= read -r hf; do
+        if [ -n "$files" ]; then
+            files="$files $hf"
+        else
+            files="$hf"
+        fi
+    done < "$work/hitfiles"
+
+    if [ -z "$anchor" ]; then
+        echo "check-runbook: empty anchor in $files" >&2
+        status=1
+        continue
+    fi
+
+    grep -q -x -F -e "## $anchor" "$ROOT/docs/runbook.md"
+    g=$?
+    if [ "$g" -eq 0 ]; then
+        continue
+    fi
+    if [ "$g" -eq 1 ]; then
+        echo "check-runbook: no entry for $anchor (in $files)" >&2
+        status=1
+        continue
+    fi
+    echo "check-runbook: grep failed" >&2
+    exit 1
+done < "$work/anchors"
+
+exit "$status"