docs: state verify-build's dist/ guarantee at the width it enforces (closes #331)
All checks were successful
check / check (push) Successful in 57s
e2e / e2e-chrome (push) Successful in 1m28s
e2e / e2e-firefox (push) Successful in 41s

check_dist_tree walks -type f -o -type l, so the emitted-tree cross-check covers
regular files and symlinks under dist/. README.md said "nothing under dist/ that
the build did not write", which is broader: fifos, sockets, device nodes and
empty directories are not checked.

The exclusion stays. A build emits none of those types, none can carry a
shippable payload, and grep on a fifo would hang rather than fail. README.md,
the script's header comment and the check_dist_tree comment now say so in the
same words, so the code and the docs cannot drift apart again.

Documentation only: no non-comment line of script/verify-build changed.
This commit is contained in:
2026-08-23 13:15:36 +00:00
parent cef6aaab11
commit e7aade4d09
3 changed files with 49 additions and 27 deletions

View File

@@ -29,12 +29,16 @@
# path fresh per invocation, outside the repo, and deletes it afterwards.
#
# What that does and does not establish. It establishes that dist/ is byte for
# byte the output of the build.js run that just finished, with nothing added,
# nothing missing and nothing altered in between, and that the audited bundles
# in it compiled to the requested mode. It does NOT establish that the source
# tree or build.js were honest, and it says nothing at all to someone handed a
# dist/ from elsewhere: without the receipt from its own build they have no
# input to this check. That is signing, and it is not this control.
# byte the output of the build.js run that just finished, with no regular file
# or symlink added, missing or altered in between, and that the audited bundles
# in it compiled to the requested mode. Regular files and symlinks are the whole
# of what the tree walk covers; fifos, sockets, device nodes and empty
# directories under dist/ are not checked, because a build emits none of them,
# none can carry a shippable payload, and grep on a fifo would hang rather than
# fail. It does NOT establish that the source tree or build.js were honest, and
# it says nothing at all to someone handed a dist/ from elsewhere: without the
# receipt from its own build they have no input to this check. That is signing,
# and it is not this control.
#
# It fails rather than passes whenever it cannot determine something. Minified
# output is not a stable contract, so "matched neither marker" is not evidence
@@ -392,8 +396,10 @@ check_receipt_entries() {
# its own command line, so a linked dist/ collapses this walk to one entry
# and cross-checks nothing.
#
# Types other than regular files and symlinks are left out on purpose: a build
# emits none of them, and grep on a fifo would hang rather than fail.
# Types other than regular files and symlinks — fifos, sockets, device nodes and
# empty directories — are left out on purpose, and the guarantee is bounded to
# what is walked: a build emits none of them, none can carry a shippable
# payload, and grep on a fifo would hang rather than fail.
check_dist_tree() {
LISTING="$(mktemp "${TMPDIR:-/tmp}/verify-build-dist.XXXXXX")" ||
fail "could not create a temporary file for the dist/ listing, so the