AtlatestRepositorysigil-doc
1
#!/usr/bin/env bash2
# SD-P7 gate: the section-child predicate as a reader/profile parameter.3
#4
# Every arm prints its own marker and this script asserts on MARKERS, never on5
# exit status alone: a non-zero exit is equally consistent with a gate that6
# never ran (127 not-found, 126 not-executable), and this estate has been fooled7
# by both. Every count an arm needs is DERIVED from the artifact rather than8
# restated here, because a check that repeats a number the artifact already9
# knows goes stale (instrument-failure taxonomy shape 10, four instances in10
# SD-P1 alone).11
set -euo pipefail12
repo_dir="$(cd "$(dirname "$0")/.." && pwd)"13
cd "$repo_dir"14
mkdir -p "$repo_dir/build"15
sigil="${SIGIL_D1_COMPILER:-$repo_dir/../task-sigil-language-readers/build/dev/bin/sigil}"16
redirects="${SIGIL_D1_REDIRECTS:-$repo_dir/dev-redirects.sgl}"17
gate_dir=$(mktemp -d "$repo_dir/build/sd-p7-gate.XXXXXX")18
export SIGIL_REDIRECTS="$redirects"19
export XDG_CACHE_HOME="$gate_dir/cache"21
pass() { printf 'SD_P7_GATE_%02d %s\n' "$1" "$2"; }22
die() { echo "SD_P7_GATE_FAILED: $*" >&2; exit 1; }24
# Every external tool this gate depends on must EXIST. An absent tool degrades25
# an assertion into a weaker one that cannot fail, silently.26
for tool in grep sed sort diff wc git find; do27
command -v "$tool" >/dev/null || die "$tool is required by this gate"28
done29
test -x "$sigil" || die "dev compiler not found at $sigil"30
for f in src/sigil/doc/model.sgl src/sigil/doc/author.sgl \31
src/sigil/doc/private/author-runtime.sgl \32
test/test-section-profile.sgl \33
test/sd-p7/folio/model.sgl test/sd-p7/folio/author.sgl test/sd-p7/folio/reader.sgl \34
test/fixtures/sd-p7-folio-note.sgd test/fixtures/sd-p7-folio-laundering.sgd \35
test/transcripts/sd-p7/construction-before.txt; do36
test -f "$f" || die "missing $f"37
done38
"$sigil" --version40
# ---------------------------------------------------------------- ARM 0141
# The suite. Its two printed denominators are asserted, and the core-witness42
# count is checked against a number DERIVED FROM `block-node?`'s own definition43
# rather than against a literal -- so adding a kind to `block-node?` without44
# adding a witness reddens here instead of leaving the anti-narrowing floor45
# silently short.46
suite_log="$gate_dir/section-profile-suite.log"47
"$sigil" -L src -L test -L book test test/test-section-profile.sgl > "$suite_log" 2>&1 \48
|| { cat "$suite_log"; die "arm 01: suite exited non-zero"; }50
# The runner colours its output, so an ANSI escape can sit between the spaces51
# and the digits and make a pattern match nothing (taxonomy shape 20). Strip52
# escapes before matching anything in this log.53
plain_log="$gate_dir/section-profile-suite.plain"54
sed 's/\x1b\[[0-9;]*m//g' "$suite_log" > "$plain_log"56
# `if`, not `cmd && { ... }`: under `set -e` a failing `&&` list at statement57
# level exits the script, so a HEALTHY grep (finds nothing) would end the gate58
# silently at exit 1 and read as a failure.59
if grep -qE '[0-9]+ failed' "$plain_log"; then60
cat "$plain_log"; die "arm 01: a test failed"61
fi62
# The runner pads its summary (`Tests: 10 passed (10 total)`), so the pattern63
# needs ` +` and not ` `. Measured against a real run before being written here:64
# a single-space pattern matches nothing and returns a confident empty.65
suite_total=$(grep -oE 'Tests: +[0-9]+ passed \([0-9]+ total\)' "$plain_log" \66
| grep -oE '\([0-9]+ total\)' | grep -oE '[0-9]+' || true)67
test -n "$suite_total" || { cat "$plain_log"; die "arm 01: could not read the suite's own total"; }68
# POSITIVE CONTROL on the pattern above: the number of `✓`-marked ARM lines in69
# the same log must agree with it. Two readings of one artifact that disagree70
# mean the pattern is describing something other than what it claims.71
#72
# The runner also prints `✓ All tests passed!` as a banner, which is not an arm.73
# It is subtracted by NAME rather than by assuming exactly one such line.74
#75
# THE ANCHOR ALLOWS LEADING WHITESPACE BECAUSE THE RUNNER INDENTS. A `^✓ `76
# pattern returns a confident ZERO against this artifact: arm lines are indented77
# four spaces and the summary banner two. Written first from a rendering that78
# had stripped the indentation, and corrected against `cat -A` of the real file.79
tick_lines=$(grep -cE '^[[:space:]]*✓ ' "$plain_log" || true)80
banner_lines=$(grep -cE '^[[:space:]]*✓ All tests passed' "$plain_log" || true)81
arm_count=$((tick_lines - banner_lines))82
test "$suite_total" = "$arm_count" \83
|| die "arm 01: runner total ($suite_total) disagrees with the arm count ($arm_count)"85
# `awk '{print $2}'`, not `grep -oE '[0-9]+'`. THE MARKER'S OWN NAME CONTAINS A86
# DIGIT: `SD_P7_SECTIONS_BUILT 1` yields "7" and "1" to a bare number-extractor,87
# and `test "7\n1" -ge 1` is a syntax error rather than a wrong answer, so this88
# failed safe. A marker that names its phase is a bad thing to run a number89
# extractor over.90
sections_built=$(grep -oE 'SD_P7_SECTIONS_BUILT [0-9]+' "$plain_log" | awk '{print $2}' | tail -1 || true)91
witnesses=$(grep -oE 'SD_P7_CORE_WITNESSES [0-9]+' "$plain_log" | awk '{print $2}' | tail -1 || true)92
test -n "$sections_built" || die "arm 01: the suite did not report SD_P7_SECTIONS_BUILT"93
test -n "$witnesses" || die "arm 01: the suite did not report SD_P7_CORE_WITNESSES"94
test "$sections_built" -ge 1 || die "arm 01: no section was built through a profile"96
# DERIVE the expected witness count from `block-node?` itself, so adding a kind97
# without adding a witness reddens here instead of leaving the anti-narrowing98
# floor silently short.99
#100
# `sed '$d'` DROPS THE LAST LINE OF THE RANGE, and it is load-bearing: sed101
# ranges are inclusive, so the range ends ON `document-node?`'s opening line,102
# which itself contains `(document? x)` and `(inline-node? x)`. Without the103
# drop this derivation returns 17 for a 13-disjunct predicate -- measured, not104
# feared; it was 17 before this line existed.105
disjuncts=$(sed -n '/(define (block-node? x)/,/(define (document-node? x)/p' src/sigil/doc/model.sgl \106
| sed '$d' \107
| grep -oE '\([a-z-]+\? x\)' | grep -v '(block-node? x)' \108
| sort -u | wc -l || true)109
test -n "$disjuncts" || die "arm 01: the block-node? disjunct derivation produced nothing"110
test "$disjuncts" -gt 0 || die "arm 01: derived zero disjuncts from block-node? -- the derivation is broken, not the code"111
test "$witnesses" = "$disjuncts" \112
|| die "arm 01: $witnesses core witnesses for $disjuncts block-node? disjuncts"113
pass 1 "section-profile suite ${suite_total}/${suite_total}, ${sections_built} sections built through a profile, ${witnesses} core witnesses = ${disjuncts} block-node? disjuncts"115
# THE SUCCESSOR MUST STILL EXIST, AND SOMETHING MUST ASSERT IT.116
#117
# The retirement form deliberately keeps a retired arm PASSING, with a message118
# naming its successor, so that a red is never hidden. **That form has an119
# unstated precondition: the successor is live.** Chain two retirements and the120
# guarantee degrades silently -- a reader follows the pointer and lands on prose121
# explaining what used to be there, while the arm goes on printing a pass.122
#123
# A retired arm is a PASSING arm, not a no-op: it still executes, so the check124
# belongs here, immediately before the pass it guards.125
#126
# It pins the successor's CALL SITE (`pass N `) rather than its runtime marker,127
# because the call site is the static artifact a reader greps and the marker only128
# exists once the gate has run. A file-existence check would NOT do: the129
# successor lives in a file that still exists; it is the ARM that would be gone.130
# `grep`, not `rg`: this gate's tool preflight requires grep and not ripgrep.131
successor_arm_exists() { # $1 = file, $2 = arm number132
test -f "$1" && grep -qE "^pass $2 " "$1"133
}135
# ---------------------------------------------------------------- ARM 02136
# RETIRED 2026-08-23 BY THE LEADER, AT SD-P8, UNDER FABLE'S RULING OF137
# 2026-08-11. This arm has NOT silently disappeared and its red has NOT been138
# hidden -- read this before concluding anything.139
#140
# WHAT IT DID. It regenerated `test/sd-p7-construction-dump.sh` and required the141
# CONSTRUCTED document of every manuscript in the tree -- `document->string`,142
# which carries every field and every node's full source location -- to be143
# byte-identical to `test/transcripts/sd-p7/construction-before.txt`. That is a144
# strong statement, and a genuinely different one from a lowering differential:145
# SD-P7 changed CONSTRUCTION (`make-section` and the author runtime's node146
# admission) and touched lowering not at all, so a lowering differential would147
# have been byte-identical under a completely broken SD-P7.148
#149
# WHY IT IS GONE. Ruling D8 moves `@chapter` out of `#lang sigil/doc`, and this150
# arm is pinned to its endpoint in THREE independent ways, each of which alone151
# retires it. Measured, not argued -- `test/sd-p7-construction-dump.sh` was run152
# against this tree and compared to the committed baseline:153
#154
# 1. THE EXCLUSION SET is `git diff --diff-filter=A <base> HEAD` compared for155
# EXACT equality against the dump's excluded paths. SD-P8 adds five156
# fixtures, so this dies first, before any document is compared.157
# 2. THE RECORD COUNT: the baseline header says `population: 22 manuscripts`;158
# this tree has 32 `.sgd` files and the dump compares 27.159
# 3. THE EMBEDDED POSITIONS. The baseline is full of ABSOLUTE byte offsets --160
# `("book/practical-sigil/01-useful-first-script.sgd" 78 4 1 2143)` -- and161
# a `#lang` line growing from 16 to 21 bytes shifts every one of them by 5162
# on all 17 header-migrated manuscripts.163
#164
# WHAT THE MEASUREMENT ACTUALLY SHOWS, which is the part that matters for165
# whether anything is being hidden. Of the 22 manuscripts common to both sides,166
# once the location NUMBERS are normalised away:167
#168
# 19 of 22 structurally IDENTICAL169
# 3 of 22 structurally different, and all three are D8 itself:170
# sd-p3-bare-prose.sgd (kind chapter) -> (kind article)171
# sd-p3-wrapped.sgd (kind chapter) -> (kind article)172
# sd-p1-article-root.sgd RAISED ... -> a real document, because D8 is173
# exactly what makes `@article` legal in the base174
# language; this is the phase's headline effect175
# showing up in the construction dump176
#177
# So the property this arm protects is INTACT, and the arm cannot say so because178
# its baseline is pinned to offsets. That is endpoint drift, not a defect, and179
# it is the same disposition as `test/gate-sd-p3.sh` arms 3 and 4.180
#181
# REGENERATING THE BASELINE IS THE WRONG ANSWER, for the same reason it was182
# wrong there: `construction-before.txt` is a PRE-SD-P7 endpoint. Regenerating183
# it against today's tree destroys the transition it certifies and leaves a184
# differential comparing the present to the present.185
#186
# SUCCESSOR: `test/gate-sd-p8.sh` arm 06, which generates BOTH sides in one run187
# (a detached worktree at SD-P8's own base, and the working tree) and asserts on188
# STRUCTURE rather than on absolute byte positions -- deliberately, because this189
# retirement is the demonstration of why a baseline pinned to offsets is a trap.190
#191
# EVIDENCE PRESERVED: `test/transcripts/sd-p7/construction-before.txt` stays in192
# the tree unmodified, and the `test -f` preconditions still assert it is193
# present. It is SD-P7's reviewed evidence.194
successor_arm_exists test/gate-sd-p8.sh 6 \195
|| die "arm 02: this retirement names test/gate-sd-p8.sh arm 6 as its successor, and that arm no longer exists.196
The retirement form keeps a retired arm PASSING so that a red is never hidden, which assumes the successor is LIVE.197
With the successor gone this arm asserts nothing and says so to nobody.198
REMEDY: find what superseded gate-sd-p8 arm 6, re-point the notice above at it, and update this check -- or restore the arm.199
Do NOT delete this check to make the gate green; that is the failure it exists to catch."200
pass 2 "RETIRED 2026-08-23 at SD-P8 under Fable's 2026-08-11 ruling; superseded by test/gate-sd-p8.sh arm 06, which asserts on structure rather than offsets (see comment)"202
# ---------------------------------------------------------------- ARM 03203
# THE DELEGATING-LANGUAGE CONTRACT. A profile is installed by binding the204
# runtime names the parser emits into generated syntax. That set is documented205
# in docs/section-profiles.md and in test/sd-p7/folio/author.sgl; if the parser206
# grows a fourth emission site, a delegating language silently stops installing207
# its profile there. So the set is DERIVED from the parser and compared.208
#209
# TWO SETS, because they are two different obligations and the first version of210
# this arm conflated them and overclaimed.211
#212
# (a) AUTHOR-RUNTIME names -- what a delegating prelude must BIND to install213
# its profile.214
# (b) CONSTRUCTOR names -- what a delegating prelude must keep REACHABLE,215
# which importing `(sigil doc)` and the core syntax library does.216
#217
# The arm used to print "the parser emits exactly N runtime names" over set (a)218
# alone, which is false of the parser: it also emits `make-srcloc`, `make-text`219
# and `make-paragraph` by bare name into manuscript scope.220
emitted="$gate_dir/emitted-names"221
grep -o "'author-[a-z-]*" src/sigil/doc/private/parser.sgl | sed "s/^'//" | sort -u > "$emitted"222
test -s "$emitted" || die "arm 03: derived no author-runtime names from the parser -- the derivation is broken"223
documented="$gate_dir/documented-names"224
printf 'author-at\nauthor-normalize\nauthor-paragraph-run\n' | sort -u > "$documented"225
diff -u "$documented" "$emitted" > "$gate_dir/names.diff" \226
|| { cat "$gate_dir/names.diff"; die "arm 03: the parser's emitted author-runtime names have moved; update docs/section-profiles.md and every delegating prelude"; }228
emitted_ctors="$gate_dir/emitted-constructors"229
grep -oE "\(list 'make-[a-z-]+" src/sigil/doc/private/parser.sgl \230
| sed "s/^(list '//" | sort -u > "$emitted_ctors"231
test -s "$emitted_ctors" || die "arm 03: derived no constructor names from the parser"232
documented_ctors="$gate_dir/documented-constructors"233
printf 'make-paragraph\nmake-srcloc\nmake-text\n' | sort -u > "$documented_ctors"234
diff -u "$documented_ctors" "$emitted_ctors" > "$gate_dir/ctors.diff" \235
|| { cat "$gate_dir/ctors.diff"; die "arm 03: the parser's emitted constructor names have moved; a delegating prelude must keep them reachable"; }237
# POSITIVE CONTROL: the derivation must be able to SEE a new emission site. The238
# probe inserts a REAL emission form, not a comment. That distinction is the239
# point -- the previous control appended `;; (list 'author-probe-name)` and so240
# only proved the grep can see a string in a comment, which is the one thing it241
# does not need to see.242
cat src/sigil/doc/private/parser.sgl > "$gate_dir/parser-probe.sgl"243
printf '(define (probe-emission state start end)\n (generated-call state start end (list (quote author-probe-name))))\n' \244
>> "$gate_dir/parser-probe.sgl"245
grep -q "^ (generated-call state start end (list (quote author-probe-name))))$" "$gate_dir/parser-probe.sgl" \246
|| die "arm 03: the probe emission form did not land in the probe copy"247
# ...and the derivation must find it. The probe is spelled `(quote name)` rather248
# than `'name`, which the CURRENT pattern cannot see -- so this control is also249
# the demonstration of the arm's own blind spot, asserted rather than hoped.250
probe_quoted=$(grep -o "'author-[a-z-]*" "$gate_dir/parser-probe.sgl" | sed "s/^'//" | sort -u | wc -l)251
real_count=$(wc -l < "$emitted")252
test "$probe_quoted" = "$real_count" \253
|| die "arm 03: the (quote name) spelling was unexpectedly visible to the ' pattern"254
# The same probe, spelled the way the parser actually spells it, MUST be seen.255
sed -i "s/(list (quote author-probe-name))/(list 'author-probe-name)/" "$gate_dir/parser-probe.sgl"256
probe_count=$(grep -o "'author-[a-z-]*" "$gate_dir/parser-probe.sgl" | sed "s/^'//" | sort -u | wc -l)257
test "$probe_count" = "$((real_count + 1))" \258
|| die "arm 03: the name derivation cannot see an added emission -- it is not a check"259
# THE DERIVATION'S KNOWN BLIND SPOT, PINNED RATHER THAN DISCLAIMED.260
#261
# Both diffs above are textual, so a name the parser BUILDS with `string->symbol`262
# is invisible to them. That is not hypothetical: the parser uses it twice.263
# Fable checked both and neither can reach either obligation set --264
#265
# :534 the COMMAND NAME, taken from the manuscript's own `@name`, so it is266
# author vocabulary and never a runtime name this contract covers;267
# :580 the hoisted binding, which is constructed with the reader-private268
# `#%sigil/doc-expression:` prefix and so cannot collide either.269
#270
# ...but "there are exactly two and both are safe" is a fact about today's271
# parser, and the arm should notice a third rather than a reader rediscovering272
# this limit later. So: derive the count, and require each site to carry one of273
# the two constructions that were actually checked.274
symbolic_sites=$(grep -c 'string->symbol' src/sigil/doc/private/parser.sgl || true)275
test "$symbolic_sites" = "2" \276
|| die "arm 03: the parser has $symbolic_sites string->symbol sites, not the 2 that were audited; a textual name derivation cannot see them, so re-check each before trusting this arm"277
grep -q 'cons (list (string->symbol name)' src/sigil/doc/private/parser.sgl \278
|| die "arm 03: the command-name string->symbol site has moved; re-audit it"279
grep -q '"#%sigil/doc-expression:"' src/sigil/doc/private/parser.sgl \280
|| die "arm 03: the hoisted-binding string->symbol site has moved; re-audit it"282
ctor_count=$(wc -l < "$emitted_ctors")283
pass 3 "parser emits $real_count author-runtime names and $ctor_count constructor names, all documented; derivation shown able to see a new emission and BLIND to (quote x); both $symbolic_sites string->symbol sites audited and pinned"285
# ---------------------------------------------------------------- ARM 04286
# REGRESSION. The full sigil-doc suite with the FULL load path.287
#288
# "Full" is four entries, not three, and the fourth was learned the expensive289
# way. `-L src -L test -L book` is what the phase brief names, and with only290
# those the run reports `Files: 15 of 15 run, 4 failed to load` --291
# `module-import: library not found: (sigil sxml)`. `(sigil doc render html)`292
# imports `(sigil sxml)`, and `SIGIL_REDIRECTS` does not resolve it for these293
# dev runs. `test/gate-sd-p2.sh` already knew: it adds294
# `-L "$sigil_sxml_root/src"` for exactly the two suites that need it. This arm295
# does the same for all of them, and the path is asserted to EXIST rather than296
# added hopefully, because a missing `-L` degrades into "failed to load", which297
# the runner reports without failing the process.298
#299
# The construction dump in arm 2 deliberately does NOT get this path. Its300
# baseline was produced without it, and an environment difference between the301
# two sides of a differential is a change in the measurement rather than in the302
# thing measured. None of the baseline's five raises mentions sxml, so nothing303
# is being hidden by that choice.304
sigil_sxml_root="${SIGIL_SXML_ROOT:-$repo_dir/../sigil-sxml}"305
test -f "$sigil_sxml_root/src/sigil/sxml.sgl" \306
|| die "arm 04: no sigil-sxml checkout at $sigil_sxml_root -- set SIGIL_SXML_ROOT"307
regression_log="$gate_dir/regression.log"308
# The exit status is CAPTURED rather than acted on immediately, so the analysis309
# below runs either way and reports WHICH test failed instead of only that the310
# process ended badly. The status is still asserted, at the end.311
regression_status=0312
"$sigil" -L "$sigil_sxml_root/src" -L src -L test -L book test > "$regression_log" 2>&1 || regression_status=$?313
sed -i 's/\x1b\[[0-9;]*m//g' "$regression_log"314
grep -qE 'Tests: +[0-9]+ passed' "$regression_log" \315
|| { tail -40 "$regression_log"; die "arm 04: could not read a suite summary -- the run may not have executed anything"; }316
# The file count is its own assertion: a load-path mistake makes files silently317
# fail to load rather than fail loudly, which is how 0.1.2 shipped.318
files_line=$(grep -oE 'Files: +[0-9]+ of [0-9]+ run' "$regression_log" | tail -1 || true)319
test -n "$files_line" || { tail -40 "$regression_log"; die "arm 04: the runner reported no file count"; }320
files_run=$(echo "$files_line" | grep -oE '[0-9]+' | head -1)321
files_found=$(echo "$files_line" | grep -oE '[0-9]+' | tail -1)322
test "$files_run" = "$files_found" \323
|| die "arm 04: only $files_run of $files_found test files ran"324
if grep -qE '[0-9]+ failed' "$regression_log"; then325
grep -nE '✗|failed' "$regression_log" | head -30326
die "arm 04: a test failed"327
fi328
test "$regression_status" = "0" \329
|| { tail -40 "$regression_log"; die "arm 04: the runner exited $regression_status with no failing test reported"; }330
regression_summary=$(grep -E 'Tests: +[0-9]+ passed' "$regression_log" | tail -1 | tr -s ' ')331
# The load path is REPORTED, not just used: a later reader needs to know which332
# four entries produced this green.333
pass 4 "full suite green with -L $sigil_sxml_root/src -L src -L test -L book :: $regression_summary, $files_line"335
echo "SD_P7_GATE_GREEN"