docs: state the enforced dist/ verification scope precisely (closes #331)
All checks were successful
check / check (push) Successful in 29s
e2e / e2e-chrome (push) Successful in 1m11s
e2e / e2e-firefox (push) Successful in 22s

README, the script synopsis, its header paragraph and the check_dist_tree comment now all say the same thing: regular files and symlinks under dist/ are covered; fifos, sockets, device nodes and empty directories are not, and why. No behaviour change — the walk is untouched.
This commit was merged in pull request #338.
This commit is contained in:
2026-08-23 15:33:58 +02:00
parent cef6aaab11
commit c36d8b6ddf
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