kyle/boxmaker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Check that every runbook pointer has an entry

Browse Source 
Implemented-By: Grok 4.6
This commit is contained in:
kyle
2026-09-22 20:25:40 -07:00
parent f1f17a171f
commit 1828048564
4 changed files with 180 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/check-runbook.sh
Executable
+112
View File
@@ -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"
scripts/test-gate-scripts.sh
+66 -1
View File
@@ -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