Commit Graph
2 Commits
Author SHA1 Message Date
timothy eedf56b8ad fix(819): close the review's blocker and the blind spot it measured
Three defects found by cold review of 9e5c288db, all reproduced here before
fixing and re-measured after.

BLOCKER — the Docker image build failed on the previous commit.
`docker/Dockerfile`'s web-build stage copies only `web/` and `design-system/`,
so it has no `.git`, and `node:22-bookworm-slim` ships no git binary. Its
`RUN` line ran `npm test -- --run`, which loads the virtual module, which shells
out to git and throws by design. Measured in an exact gitless replica of the
stage: `Test Files 1 failed | 117 passed`, against `117 passed` on the parent.
`build` is gated `needs: [test, migrations, scan]` and the `test` job — which
carries no `if:`, so it runs on PR, main and tag alike — already runs the
identical suite on a real checkout, so the Dockerfile's run was duplicated work
and is dropped rather than propped up with a `.git` copy and a git install. The
previous commit message asserted this build was safe on the strength of having
verified `vite build` alone; the test step on the same line was never measured.

HIGH — a tracked file could still leave the population silently, and one way was
a REGRESSION. `import.meta.glob` matches no dotfile or dot-directory, and on
`core.ignorecase=true` a disk spelling that diverges from the index spelling
(`caseprobe.tsx` vs `CaseProbe.tsx`) is tracked, present, and invisible to the
intersection — measured blind here, and measured CAUGHT by the parent commit.
The stated residual named only the deleted-file case, so the prose claimed a
completeness the code did not have. Fixed by asserting the other direction: the
plugin now reports which tracked paths are absent from disk, and the guard
requires every tracked, on-disk, in-scope path to have reached the scanner. A
mid-edit deletion stays tolerated — measured, still green — because that is
transient, while a hole is now named and red. This is the rule
`scripts/tests/tracked_files.py` already states for the Python derivations:
existence is ASSERTED, never filtered.

MEDIUM — the clause proof was fixture-only. Every clause test drove
`listSourceFilesFrom` with injected inputs, so `... && tracked.size < 10` was
live over the 1-2 entry fixtures and dead over the real 260-path index: the fix
fully regressed, suite green. Measured. Added a liveness test that drives the
REAL glob and REAL index with one synthetic key. That mutation now reddens it,
and disarming the clause outright reddens two named tests.

Also: the plugin refuses instead of guessing when `configResolved` never ran
(a wrong root was a silent wrong answer), its doc comment states the `src/`-only
pathspec so a future caller cannot inherit a truncated population, and git's
stderr is piped so the framed error is the only message.

Docs: `docs/spa-conventions.md` §1 gains the `web/vite-plugins/` layout entry;
`docs/guard-inventory.md`'s hand-written TS/C# list gains the fourth file the
review noted it had already gone stale against, and the row's Notes no longer
overstate the population as "`git ls-files`" when it is the walk intersected
with the index.

refs #819
2026-08-29 05:12:23 +02:00
timothy 63afc5f743 fix(819): derive the SPA page-size guard's population from the git index
`pageSizeCallSites.guard.test.ts` asserts EXACT completeness over the files it
discovers, but discovered them with `import.meta.glob` over `web/src`. A
directory walk is not an authoritative source: an untracked `.ts`/`.tsx` — a
scratch file, a half-finished component, an editor dropping — entered the
population and failed as unregistered on that checkout, while CI, which only
ever checks out tracked files, stayed green. Developer-red / CI-green, the #778
shape #806 removed from every other guard here.

Witnessed before the fix: planting an untracked `Scratch819Untracked.tsx` with a
`pageSize: 25` literal reddened the guard with
`UNREGISTERED (1) — screens/Scratch819Untracked.tsx:literal:25`.

The glob stays, as the source of file CONTENT. The POPULATION is now
`git ls-files`, read by `web/vite-plugins/trackedSourceFiles.ts` in Vite's own
Node context and handed to the app project as the virtual module
`virtual:etv-tracked-source-files`. That is what reaches the index without
admitting `@types/node` to `tsconfig.app.json` — the obstacle that deferred this
in #818, since wiring those types in was tried and reverted (it leaked Node's
ambient `setTimeout` into the app project and broke three unrelated
`window.setTimeout` mocks).

The plugin fails rather than degrading: a failed or empty `git ls-files` throws,
because answering "could not tell" with the very population the index replaced
is a permanent no-op that reports green (#772's shape). It reads the index
lazily, inside `load()`, so `vite build` — including the Docker image build,
whose context carries no `.git` — never shells out to git. Verified by building
in a copy of `web/` outside any repository.

Proofs, all executed:
- clause mutation: deleting `if (!isTrackedSourcePath(...))` from
  `listSourceFilesFrom` reddens exactly one named test, `EXCLUDES an untracked
  file that matches the scope in every other way (#819)`, and nothing else. The
  pipeline was extracted to take injected inputs precisely so that clause is
  provable — over real source on a clean checkout it removes nothing, so a
  plant-a-real-file check pins nothing, the same argument
  `isScannableSourceFileName` already records.
- negative control: the same planted file, once `git add`ed, is caught again.
  Untracked is ignored, tracked is caught — the guard did not go blind.
- positive control against a clause mutated to reject everything.
- anti-vacuity on the consuming side: the real index is >50 paths and contains
  named known files, so a plugin that stopped being registered cannot pass an
  empty population off as a satisfied one.

Residual, stated rather than implied: a file tracked but DELETED in the working
tree has no content and drops out. Not asserted — an unstaged deletion is a
normal developer state, and a guard red on one gets ignored (#806) — and a
REGISTERED site in such a file still fails loudly on the STALE direction.

fixes #819
2026-08-29 05:12:23 +02:00