Round 2's cold review found the previous commit had reproduced, one layer up,
the exact defect it was fixing: `expectedTrackedSources` — the function that
closes the dot-directory / case-divergence hole — had no clause proof. Measured:
replacing its body with `return []` left all 1249 tests green while the hole it
exists to catch went undetected, and deleting the `absentFromDisk` subtraction
(the whole point of the plugin's second field) was green too.
Three proofs added, each MEASURED red against the mutation it names:
- a direct fixture test pinning all four terms of `expectedTrackedSources`
(`return []` and dropping the subtraction now each redden it);
- an anti-vacuity floor INSIDE the shortfall test, so an empty expected set
cannot pass the comparison it feeds;
- a table pinning `isInScopeSourcePath`. That one closes a hole the review
measured separately: the walk and the index side applied the SAME scope
filters, so scope cancelled out of the equality between them — excluding
`src/components/` dropped 13 real files with the whole suite green. The two
copies of that predicate are now ONE named function, and the table is what
reddens a change to it, since no assertion comparing the two sides can.
Also corrected, all found by the same review:
- The comment justifying the `absentFromDisk` subtraction cited
`scripts/tests/tracked_files.py` as stating the rule it follows. That module
states the OPPOSITE and enforces it with `assert absolute.is_file()`. It is
now recorded as a deliberate DEVIATION with its reason (that population is a
handful of hooks where a missing file is remarkable; this one is ~260 SPA
sources a developer edits continuously), rather than as an instance of it.
- `absentFromDisk` is named for what it measures — no READABLE file — not for
its common cause. `existsSync` follows links, so a tracked BROKEN SYMLINK is a
committed, permanent state landing in that set, which "deleted in the working
tree" licensed subtracting without saying so.
- The Dockerfile comment claimed the `needs: [test, …]` edge alone guarantees no
image ships from an untested tree. `Test SPA` is also gated on `docs_only` and
the #420 revalidate skip, and `build` is not gated on `revalidate`; the
property survives via #420's byte-identical-tree argument, which the comment
now names instead of implying the wrong mechanism.
- `docs/testing.md`'s web row was falsified by this PR: `web/vite-plugins/**` is
a third collection root, and `npm test` now hard-requires a git checkout.
- Two prose slips: guard-inventory counted "the first of those" onto the wrong
file, and both `docs/spa-conventions.md` and the Dockerfile said "guards"
plural where exactly one derives a population.
Rebased onto 4b3f6f6c9 (#872), which rewrote `docs/guard-inventory.md`.
refs #819
137 lines
6.6 KiB
TypeScript
137 lines
6.6 KiB
TypeScript
import { execFileSync } from 'node:child_process';
|
|
import { existsSync } from 'node:fs';
|
|
import { join } from 'node:path';
|
|
import type { Plugin } from 'vite';
|
|
|
|
/**
|
|
* ersatztv#819: hands `web/src/api/pageSizeCallSites.guard.test.ts` — the one SPA guard that derives a
|
|
* file population — the set of files under `src/` that git actually tracks.
|
|
*
|
|
* That guard asserts EXACT completeness over the files it discovers, so its population has to be
|
|
* the git index — `testing.guard-derives-population-from-source`. A directory walk is not an
|
|
* authoritative source: an untracked `.ts`/`.tsx` under `web/src/` (a scratch file, a half-finished
|
|
* component, an editor dropping) enters the population and fails as unregistered on that checkout
|
|
* while CI, which only ever sees tracked files, stays green. That is the developer-red / CI-green
|
|
* shape #778 named and #806 removed from every other guard here.
|
|
*
|
|
* Why a Vite plugin rather than `node:child_process` in the guard itself: `@types/node` is
|
|
* deliberately absent from `tsconfig.app.json`, which covers production browser code too, and
|
|
* wiring it in was tried and reverted — under `tsc -b`'s single-program compilation it leaked
|
|
* Node's ambient `setTimeout` into the whole app project and broke three unrelated
|
|
* `window.setTimeout` mocks expecting the DOM signature. A plugin runs in Vite's own Node context,
|
|
* where `@types/node` is already available via `tsconfig.node.json`, and hands the result to the
|
|
* app project as plain data. No app-project type change, no `/// <reference types="node" />`.
|
|
*
|
|
* SCOPE: the pathspec is `src/` only. A future guard over `web/e2e`, `web/scripts` or
|
|
* `web/vite-plugins` must not import this module expecting its own files — it would receive a
|
|
* silently truncated population, which is the defect this exists to remove. Widen the pathspec
|
|
* (and say so here) rather than reusing it out of scope.
|
|
*/
|
|
export const TRACKED_SOURCE_FILES_ID = 'virtual:etv-tracked-source-files';
|
|
|
|
/** Rollup convention: a resolved virtual id is `\0`-prefixed so no other plugin claims it. */
|
|
const RESOLVED_ID = `\0${TRACKED_SOURCE_FILES_ID}`;
|
|
|
|
export interface TrackedSources {
|
|
/** Tracked paths under `src/`, relative to the Vite root (`web/`), e.g. `src/api/pageSizeScan.ts`. */
|
|
tracked: string[];
|
|
/**
|
|
* The subset of `tracked` with NO READABLE FILE at that path. Usually a working-tree deletion
|
|
* that is not yet staged, which is the case the consumer tolerates — but the test is
|
|
* `existsSync`, so it also covers a tracked BROKEN SYMLINK (a committed, permanent state, not a
|
|
* mid-edit one), a sparse checkout that excludes the path, and an unreadable parent directory.
|
|
* Named for what it measures rather than for the common cause, because a consumer subtracts this
|
|
* set and a wrong name there licenses subtracting more than intended.
|
|
*
|
|
* Reported rather than silently removed: the consumer needs to tell these apart from a tracked
|
|
* file the WALK cannot see, which is a real hole. Collapsing the two is how a population shrinks
|
|
* without anyone noticing.
|
|
*/
|
|
absentFromDisk: string[];
|
|
}
|
|
|
|
/** Injectable so `resolveTrackedSourceFiles` is testable without a real repository. */
|
|
export type GitRunner = (args: readonly string[]) => string;
|
|
/** Injectable for the same reason; defaults to a real on-disk existence check. */
|
|
export type FileExists = (path: string) => boolean;
|
|
|
|
const runGitDefault: GitRunner = (args) =>
|
|
execFileSync('git', [...args], {
|
|
encoding: 'utf8',
|
|
maxBuffer: 64 * 1024 * 1024,
|
|
// Keep git's own `fatal: not a git repository` off the terminal so the framed error below is
|
|
// the only message a reader sees.
|
|
stdio: ['ignore', 'pipe', 'pipe']
|
|
});
|
|
|
|
export function resolveTrackedSourceFiles(
|
|
root: string,
|
|
runGit: GitRunner = runGitDefault,
|
|
fileExists: FileExists = existsSync
|
|
): TrackedSources {
|
|
let raw: string;
|
|
try {
|
|
raw = runGit(['-C', root, 'ls-files', '-z', '--', 'src']);
|
|
} catch (cause) {
|
|
// FAIL, never degrade to the unfiltered walk. "Could not tell" is a third outcome distinct from
|
|
// pass and fail, and a check that answers it by falling back to the population it exists to
|
|
// replace is a permanent no-op that reports green — the shape ersatztv#772 was filed for.
|
|
throw new Error(
|
|
`${TRACKED_SOURCE_FILES_ID}: could not read the git index under ${root}. The SPA guards derive ` +
|
|
`their population from it and must not fall back to a filesystem walk — fix the checkout ` +
|
|
`rather than the guard.`,
|
|
{ cause }
|
|
);
|
|
}
|
|
|
|
// `-z` rather than plain `ls-files`: git applies `core.quotePath` to non-ASCII names by default
|
|
// and would hand back a C-quoted string that no longer matches the path Vite reports, silently
|
|
// dropping that file from the population. NUL-separated output is never quoted.
|
|
const tracked = raw.split('\0').filter((path) => path.length > 0);
|
|
if (tracked.length === 0) {
|
|
// Anti-vacuity at the source. An empty population makes every completeness claim downstream
|
|
// pass while proving nothing, which is the characteristic failure of a completeness check.
|
|
throw new Error(
|
|
`${TRACKED_SOURCE_FILES_ID}: git reported ZERO tracked files under ${root}/src. That is never ` +
|
|
`true of this repository, so it means the index was not readable rather than that the ` +
|
|
`population is genuinely empty.`
|
|
);
|
|
}
|
|
|
|
return {
|
|
tracked,
|
|
absentFromDisk: tracked.filter((path) => !fileExists(join(root, path)))
|
|
};
|
|
}
|
|
|
|
export function trackedSourceFilesPlugin(runGit?: GitRunner, fileExists?: FileExists): Plugin {
|
|
// Deliberately NOT seeded with `process.cwd()`. A wrong root is a silent wrong answer — git would
|
|
// report zero files and the anti-vacuity throw would fire, but only by luck of this repo's
|
|
// layout. Refusing is the honest outcome.
|
|
let root: string | undefined;
|
|
|
|
return {
|
|
name: 'etv:tracked-source-files',
|
|
configResolved(config) {
|
|
root = config.root;
|
|
},
|
|
resolveId(id) {
|
|
return id === TRACKED_SOURCE_FILES_ID ? RESOLVED_ID : undefined;
|
|
},
|
|
// Deliberately LAZY: git runs only when something imports the virtual module. `vite build`
|
|
// never resolves this id and so never shells out to git.
|
|
load(id) {
|
|
if (id !== RESOLVED_ID) {
|
|
return undefined;
|
|
}
|
|
if (root === undefined) {
|
|
throw new Error(
|
|
`${TRACKED_SOURCE_FILES_ID}: the plugin's \`configResolved\` hook never ran, so the Vite ` +
|
|
`root is unknown. Refusing to guess a root rather than derive a population from the wrong one.`
|
|
);
|
|
}
|
|
return `export default ${JSON.stringify(resolveTrackedSourceFiles(root, runGit, fileExists))};\n`;
|
|
}
|
|
};
|
|
}
|