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

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
committed by sneak
parent cef6aaab11
commit c394a64a65
3 changed files with 51 additions and 27 deletions

View File

@@ -81,17 +81,21 @@ lives.
one of the bundles containing `src/shared/constants.js` — into a build receipt,
and `script/verify-build` checks `dist/` against that receipt: every recorded
file present with exactly the recorded bytes, every audited bundle carrying the
requested `DEBUG` marker, and nothing under `dist/` that the build did not
write. The `Makefile` creates the receipt path with `mktemp` per invocation,
outside the repo, and deletes it afterwards.
requested `DEBUG` marker, and no regular file or symlink under `dist/` that the
build did not write. The `Makefile` creates the receipt path with `mktemp` per
invocation, outside the repo, and deletes it afterwards.
That is what ties the check to a build rather than to a directory. What it
establishes is narrow and worth stating exactly: `dist/` is byte for byte the
output of the `build.js` run that just finished, with nothing added, removed or
altered in between. It establishes nothing about whether the source tree or
`build.js` were honest, and it offers nothing to someone handed a `dist/` from
elsewhere — without the receipt from its own build there is no input to the
check. Verifiable provenance for a third party is signing, which this is not.
output of the `build.js` run that just finished, with no regular file or symlink
added, removed or altered in between. 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
establishes nothing about whether the source tree or `build.js` were honest, and
it offers nothing to someone handed a `dist/` from elsewhere — without the
receipt from its own build there is no input to the check. Verifiable provenance
for a third party is signing, which this is not.
There is deliberately no target that re-verifies an existing `dist/` on its own.
The list of files to check has to come from the build that produced them; read
@@ -143,12 +147,13 @@ provide:
serves. Run deliberately, never as part of a build: the output is committed
and there is no runtime fetch, so the shipped list is as fresh as the last
vendoring run that was released
- `script/verify-build --expect release|debug --receipt PATH` — assert that
`dist/` is exactly what the build that just ran emitted, and that the compiled
`DEBUG` state of the bundles in it is the one that was asked for. Both
arguments are required and neither has a default: the expected mode is stated
by the caller rather than read from `AUTISTMASK_DEBUG`, and the file list
comes from the build's receipt rather than from `dist/` (see
- `script/verify-build --expect release|debug --receipt PATH` — assert that the
regular files and symlinks under `dist/` are exactly what the build that just
ran emitted (other file types are out of scope), and that the compiled `DEBUG`
state of the bundles in it is the one that was asked for. Both arguments are
required and neither has a default: the expected mode is stated by the caller
rather than read from `AUTISTMASK_DEBUG`, and the file list comes from the
build's receipt rather than from `dist/` (see
[Build Receipts](#build-receipts)). Run automatically at the end of
`make build` and `make build-debug`; fails loudly rather than passing whenever
it cannot determine something. Not part of `make check`, which does not depend