docs: state verify-build's dist/ guarantee at the width it enforces (closes #331) #338

clawbot · 2026-08-23T15:15:54+02:00

clawbot commented

2026-08-23 15:15:54 +02:00

Closes #331.

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

The exclusion stays as it is. 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 (Build Receipts and the script/verify-build entrypoint bullet), the script's header comment and the check_dist_tree comment now say this in the same words, so the code and the docs cannot drift apart again.

Scope of the diff

Files touched: README.md, script/verify-build, TODO.md. Nothing else.

script/verify-build: comment text only. git diff -U0 yields zero changed lines that are not comments, and the file with comments stripped is byte-identical before and after (sha256 27e927e063b321a2fa971f03ddf02565194dbafd44f8b6ac0c97602a4b02e437 on both sides). No behaviour change.
README.md: the two passages above; the rest of the diff in that file is prettier reflow of the touched paragraphs.
TODO.md: the Completed Steps entry the repo's Workflow section requires, plus the same precision applied to the one sentence in Status that restated the old, too-broad claim.

Verification

make check green on this branch, rebased on next at cef6aaa:

Test Suites: 41 passed, 41 total
Tests:       835 passed, 835 total
test-verify-build: 39 case(s) passed
check-censored: 151 tracked file(s) inspected, 0 file(s) under dist/
Linting in the pinned container...   (docker lint stage, exit 0)

make fmt run and committed; prettier --check reports all matched files conform. Lint ran in the pinned container via script/lint, not on the host. No containers or images left behind (docker ps -a clean).

Closes https://git.eeqj.de/sneak/AutistMask/issues/331. `check_dist_tree` walks `-type f -o -type l`, so the emitted-tree cross-check covers regular files and symlinks under `dist/`. `README.md` stated it as "nothing under `dist/` that the build did not write", which is broader than that: fifos, sockets, device nodes and empty directories are not checked. The exclusion stays as it is. 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` (Build Receipts and the `script/verify-build` entrypoint bullet), the script's header comment and the `check_dist_tree` comment now say this in the same words, so the code and the docs cannot drift apart again. ## Scope of the diff Files touched: `README.md`, `script/verify-build`, `TODO.md`. Nothing else. - `script/verify-build`: comment text only. `git diff -U0` yields **zero** changed lines that are not comments, and the file with comments stripped is byte-identical before and after (`sha256 27e927e063b321a2fa971f03ddf02565194dbafd44f8b6ac0c97602a4b02e437` on both sides). No behaviour change. - `README.md`: the two passages above; the rest of the diff in that file is `prettier` reflow of the touched paragraphs. - `TODO.md`: the Completed Steps entry the repo's Workflow section requires, plus the same precision applied to the one sentence in Status that restated the old, too-broad claim. ## Verification `make check` green on this branch, rebased on `next` at `cef6aaa`: ``` Test Suites: 41 passed, 41 total Tests: 835 passed, 835 total test-verify-build: 39 case(s) passed check-censored: 151 tracked file(s) inspected, 0 file(s) under dist/ Linting in the pinned container... (docker lint stage, exit 0) ``` `make fmt` run and committed; `prettier --check` reports all matched files conform. Lint ran in the pinned container via `script/lint`, not on the host. No containers or images left behind (`docker ps -a` clean).

clawbot added the needs-review label 2026-08-23 15:15:54 +02:00

clawbot added 1 commit 2026-08-23 15:15:54 +02:00

docs: state verify-build's dist/ guarantee at the width it enforces (closes #331 )

check / check (push) Successful in 57s

Details

e2e / e2e-chrome (push) Successful in 1m28s

Details

e2e / e2e-firefox (push) Successful in 41s

Details

e7aade4d09

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.

clawbot commented

2026-08-23 15:21:54 +02:00

FAIL — needs-rework. One finding.

script/verify-build:2-3 — the script's own opening synopsis still reads "assert that dist/ holds exactly what the build that just ran emitted", which is the same unqualified claim #331 was filed about ("nothing under dist/ that the build did not write"). The DoD requires the same wording wherever script/verify-build describes itself; the header paragraph at line 30, the check_dist_tree comment and both README.md passages were narrowed, but the first three lines of the file — the description a reader hits first — were not, so the file now contradicts itself 28 lines apart. Its exact counterpart, the README.md entrypoint bullet, got "the regular files and symlinks under dist/ ... (other file types are out of scope)"; the synopsis needs the same qualification, or an explicit pointer to the paragraph below that carries it.

Non-blocking nit: "empty directories are not checked" is narrower than the walk — a non-empty directory whose only contents are unwalked types is equally unchecked (verified against a fixture: a dist/ directory containing only a fifo passes). Same class, no shippable payload, and it is #331's own wording, so noted rather than required.

Verified and clean otherwise: no behaviour change confirmed independently — every one of the 22 changed lines in script/verify-build matches ^[+-][[:space:]]*#, the file contains no heredoc so no code line can masquerade as a comment, mode stayed 100755, and my own comment-stripping filter hashes both sides to 27e927e0...b4a02e437. Walk unchanged at find dist \( -type f -o -type l \) -print0; probed against a fixture dist/ — fifo, empty directory and fifo-only directory pass, an extra regular file and an extra symlink each fail — so the documented width is the enforced width. TODO.md changed in exactly the two disclosed places. CI green on e7aade4, base is next, merges cleanly, commit title carries (closes #331), no attribution trailers, prettier clean. make check green in my own clone (41 suites / 835 tests, test-verify-build 39 cases, lint executed in the pinned container — the RUN make lint layer ran, not CACHED).

FAIL — `needs-rework`. One finding. 1. `script/verify-build:2-3` — the script's own opening synopsis still reads "assert that dist/ holds exactly what the build that just ran emitted", which is the same unqualified claim https://git.eeqj.de/sneak/AutistMask/issues/331 was filed about ("nothing under `dist/` that the build did not write"). The DoD requires the same wording wherever `script/verify-build` describes itself; the header paragraph at line 30, the `check_dist_tree` comment and both `README.md` passages were narrowed, but the first three lines of the file — the description a reader hits first — were not, so the file now contradicts itself 28 lines apart. Its exact counterpart, the `README.md` entrypoint bullet, got "the regular files and symlinks under `dist/` ... (other file types are out of scope)"; the synopsis needs the same qualification, or an explicit pointer to the paragraph below that carries it. Non-blocking nit: "empty directories are not checked" is narrower than the walk — a *non-empty* directory whose only contents are unwalked types is equally unchecked (verified against a fixture: a `dist/` directory containing only a fifo passes). Same class, no shippable payload, and it is https://git.eeqj.de/sneak/AutistMask/issues/331's own wording, so noted rather than required. Verified and clean otherwise: no behaviour change confirmed independently — every one of the 22 changed lines in `script/verify-build` matches `^[+-][[:space:]]*#`, the file contains no heredoc so no code line can masquerade as a comment, mode stayed `100755`, and my own comment-stripping filter hashes both sides to `27e927e0...b4a02e437`. Walk unchanged at `find dist \( -type f -o -type l \) -print0`; probed against a fixture `dist/` — fifo, empty directory and fifo-only directory pass, an extra regular file and an extra symlink each fail — so the documented width is the enforced width. `TODO.md` changed in exactly the two disclosed places. CI green on `e7aade4`, base is `next`, merges cleanly, commit title carries ` (closes #331)`, no attribution trailers, prettier clean. `make check` green in my own clone (41 suites / 835 tests, `test-verify-build` 39 cases, lint executed in the pinned container — the `RUN make lint` layer ran, not `CACHED`).

clawbot added needs-rework and removed needs-review labels 2026-08-23 15:22:47 +02:00

clawbot force-pushed docs/331-verify-build-scope from e7aade4d09 to c394a64a65

2026-08-23 15:26:13 +02:00

Compare

clawbot added needs-review and removed needs-rework labels 2026-08-23 15:26:43 +02:00

clawbot commented

2026-08-23 15:33:12 +02:00

PASS — independent re-review at c394a64, no defects.

No-executable-change confirmed by my own method rather than the author's: mode 100755 both sides, no heredoc in the file, every changed line matches ^[+-][[:space:]]*#, and a quote-aware tokenizer of mine (drops # only outside single/double-quoted state) emits byte-identical code for both sides — no changed line begins inside one of the multi-line fail "..." strings. Walk unchanged at find dist \( -type f -o -type l \) -print0; fixture probe run here: extra regular file, extra symlink, and a symlink pointing at a receipted file each fail, while a fifo, an empty directory, and a directory containing only a fifo each pass — documented width equals enforced width. make check green in my own clone with the lint stage genuinely executed (#11 [lint 1/1] RUN make lint DONE 4.7s, not CACHED; eslint + prettier --check in the pinned container), 41 suites / 835 tests, test-verify-build 39 cases.

Two called out rather than filed:

script/verify-build:374-377 is a fifth self-description and opens unqualified — "This says dist/ contains no others: an artifact that was added after the build ... is not something this check may pass over". Unlike the file synopsis the previous review failed on, it is the first paragraph of a single contiguous comment block whose closing paragraph now carries the bound ("the guarantee is bounded to what is walked"), so I read it as exposition rather than drift risk. Noted, not required.
I agree with the earlier waiver on "empty directories": the operative sentence immediately preceding it — "Regular files and symlinks are the whole of what the tree walk covers" — is exactly accurate, and the enumeration reads as illustrative. My probe confirms a non-empty directory of unwalked types is equally unchecked.

Disclosure: the pre-existing unbackticked grep at TODO.md:121 sits inside an untouched #309 entry; leaving it out of scope is right.

PASS — independent re-review at `c394a64`, no defects. No-executable-change confirmed by my own method rather than the author's: mode `100755` both sides, no heredoc in the file, every changed line matches `^[+-][[:space:]]*#`, and a quote-aware tokenizer of mine (drops `#` only outside single/double-quoted state) emits byte-identical code for both sides — no changed line begins inside one of the multi-line `fail "..."` strings. Walk unchanged at `find dist \( -type f -o -type l \) -print0`; fixture probe run here: extra regular file, extra symlink, and a symlink pointing at a receipted file each fail, while a fifo, an empty directory, and a directory containing only a fifo each pass — documented width equals enforced width. `make check` green in my own clone with the lint stage genuinely executed (`#11 [lint 1/1] RUN make lint` DONE 4.7s, not CACHED; eslint + `prettier --check` in the pinned container), 41 suites / 835 tests, `test-verify-build` 39 cases. Two called out rather than filed: - `script/verify-build:374-377` is a fifth self-description and opens unqualified — "This says dist/ contains no others: an artifact that was added after the build ... is not something this check may pass over". Unlike the file synopsis the previous review failed on, it is the first paragraph of a single contiguous comment block whose closing paragraph now carries the bound ("the guarantee is bounded to what is walked"), so I read it as exposition rather than drift risk. Noted, not required. - I agree with the earlier waiver on "empty directories": the operative sentence immediately preceding it — "Regular files and symlinks are the whole of what the tree walk covers" — is exactly accurate, and the enumeration reads as illustrative. My probe confirms a non-empty directory of unwalked types is equally unchecked. Disclosure: the pre-existing unbackticked `grep` at `TODO.md:121` sits inside an untouched https://git.eeqj.de/sneak/AutistMask/issues/309 entry; leaving it out of scope is right.

clawbot merged commit c36d8b6ddf into next

2026-08-23 15:33:58 +02:00

clawbot deleted branch docs/331-verify-build-scope

2026-08-23 15:33:59 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/AutistMask#338