fix(819): the Docker stage needs the git BINARY excluded too, not just the index

Round 8 found a BLOCKER, and it was my verification that was wrong rather than
an argument. The previous commit re-armed `npm test` in the web-build stage and
excluded the one file that needs a git CHECKOUT. It did not exclude the file
added in round 6 that needs the git BINARY: `trackedSourceFiles`' real-repository
tests shell out to `git` to prove the derivation by executing it, and
`node:22-bookworm-slim` ships no git. So `docker build` would have failed on
every push to `main` and every `v*` tag — no image ships.

Why I did not catch it: every "gitless replica" I ran deleted `.git` and left the
git binary on `PATH`. That reproduces one of the two preconditions. Re-measured
with `PATH` stripped, the previous head gives `spawnSync git ENOENT`,
`Test Files 1 failed | 116 passed`. The Dockerfile comment stated the right
premise — "no `.git`, AND node:22-bookworm-slim ships no git binary" — two lines
above the line that only acted on the first half.

The real-git block is now its own file, `trackedSourceFiles.realgit.test.ts`, so
excluding it costs two tests rather than the thirteen injected-runner ones that
run fine with no git at all. Both exclusions are named in the Dockerfile with
their DIFFERENT reasons, and with the instruction to verify any change there with
the binary off `PATH`. MEASURED in a replica with neither `.git` nor `git`:
117 files / 1225 tests pass, lint, typecheck and build all exit 0.

Also from round 8:
- `docs/testing.md`'s row asserted the suite "cannot run against an exported tree
  with no index" and that the Dockerfile "no longer runs it" — both false at the
  previous head. It now distinguishes the checkout requirement from the binary
  requirement, which is the distinction the blocker turned on.
- Two clauses this PR added had no proof and MEASURED green when disarmed: the
  trailing-slash restriction in `unaccountedWalkedPaths` (without it every
  `others` entry becomes a prefix mask) and the plugin's dedupe. Both now have
  fixtures, and both mutations redden by name.
- The dedupe's stated rationale was wrong: duplicates appear on both sides of the
  ratio the floor computes, so they cancel. Re-stated as tidiness, with the
  measurement, and "three times" corrected to two-or-three (a both-added conflict
  has two stages).
- Three JSDoc blocks were stacked above one function, so two of them documented
  functions defined 15 and 50 lines below and attached to the wrong ones. Pure
  reordering, plus the blank lines that were detaching them.
- `vite-env.d.ts` named the wrong mechanism for its loud-failure claim: a renamed
  field yields an empty Set, caught by the anti-vacuity floor rather than by a
  throw at first read.
- The Dockerfile no longer hardcodes a test-file count that nothing reddens on.

Refs: #819
This commit is contained in:
2026-08-29 05:12:23 +02:00
parent e3a3c46f1d
commit 157d16df67
8 changed files with 152 additions and 110 deletions
+16 -8
View File
@@ -9,13 +9,19 @@ WORKDIR /source
COPY design-system/. ./design-system/
COPY web/. ./web/
WORKDIR /source/web
# The SPA suite runs here EXCEPT for one file (ersatztv#819). This stage's context is `web/` and
# `design-system/` only — no `.git`, and `node:22-bookworm-slim` ships no git binary — while
# `web/src/api/pageSizeCallSites.guard.test.ts` derives its file population from `git ls-files`
# rather than a directory walk, and refuses rather than falling back, so that ONE file cannot run
# without an index. Excluding it keeps the other 117 files (~1228 tests) that run fine gitless;
# dropping `npm test` wholesale, which was the first fix here, threw those away for one file.
# The excluded file is not skipped overall: `docker-build.yml`'s `Build & test (.NET)` job runs the
# The SPA suite runs here except for two files (ersatztv#819), and the two are excluded for
# DIFFERENT reasons — the distinction is the one that broke this stage once already:
# * `web/src/api/pageSizeCallSites.guard.test.ts` needs a git CHECKOUT. It derives its file
# population from `git ls-files` rather than a directory walk, and refuses rather than falling
# back. This stage's context is `web/` + `design-system/` only, so there is no `.git`.
# * `web/vite-plugins/trackedSourceFiles.realgit.test.ts` needs the git BINARY. It builds a real
# temp repository to prove the derivation by executing it. `node:22-bookworm-slim` ships no git
# (`command -v git` -> not found), so it dies with `spawnSync git ENOENT`.
# Excluding only the first is NOT enough, and a replica that merely deletes `.git` cannot show it:
# verify any change here with the git binary off `PATH`, not just with the directory absent.
# Everything else — all but those two files — runs fine gitless and is kept, rather than dropping
# the whole suite for one file as an earlier fix here did.
# The excluded pair is not skipped overall: `docker-build.yml`'s `Build & test (.NET)` job runs the
# whole suite on a real checkout, and `build` (the job that invokes this Dockerfile) carries
# `needs: [test, migrations, scan]`. State that chain precisely, because the `needs:` edge is not
# all of it: `Test SPA` is also gated on `docs_only` and on the #420 revalidate skip, and `build` is
@@ -25,7 +31,9 @@ WORKDIR /source/web
# and `ci-detect-docs-only.sh` classifies by PATH SHAPE (`docs/` or `*.md`), not by directory, so a
# `web/*.md` would count as docs — there are none today, but do not restate it as "any `web/**`".
RUN npm run lint && npm run typecheck && \
npm test -- --run --exclude 'src/api/pageSizeCallSites.guard.test.ts' && \
npm test -- --run \
--exclude 'src/api/pageSizeCallSites.guard.test.ts' \
--exclude 'vite-plugins/trackedSourceFiles.realgit.test.ts' && \
npm run build
FROM --platform=linux/amd64 192.168.1.95:3000/timothy/ersatztv-ffmpeg:8.1.2 AS runtime-base
+3 -2
View File
@@ -66,8 +66,9 @@ with have sat in these gaps. Treat anything not named here as unassessed, not as
`Proof: NONE` honestly instead of borrowing a neighbouring file's proof.
2. **C# and TypeScript guards** — `ErsatzTV.Mcp.Tests/ToolCatalogTests.cs`,
`web/src/api/pageSizeCallSites.guard.test.ts`, `web/src/api/completeRequest.guard.test.ts` and
`web/vite-plugins/trackedSourceFiles.test.ts` (the proof for the population
`pageSizeCallSites.guard.test.ts` derives) are all structural guards or proofs of one, and none
`web/vite-plugins/trackedSourceFiles.test.ts` and its `…realgit.test.ts` sibling (the proof for
the population `pageSizeCallSites.guard.test.ts` derives — split because only the second needs a
git BINARY, which the Docker web-build stage has not got) are all structural guards or proofs of one, and none
has a row. Note what that costs: this list is a HAND-WRITTEN
mirror of a population nothing derives, so it goes stale silently and CI stays green — #807
added the third entry, and only review caught that the second had become the only one named.
+1 -1
View File
@@ -20,7 +20,7 @@ before adding tests, not just `docs/contributing.md` §8 (which now just points
| `ErsatzTV.Scanner.Tests` | Library scanning: scan handlers, folder scanners, NFO readers | Handler tests substitute the folder scanners + `ILibraryRepository` and assert the resulting repository writes (e.g. `ScanLocalLibraryHandlerTests` pins which `LastScan` levels a scan records — ersatztv#264). Fakes/`Testably` back the file-system-facing scanners. ~1,485 tests (approximate on purpose — an exact count goes stale on every PR that adds one). Additionally contains `Core/FFmpeg/TranscodingTests` — `[Explicit]` + `[Combinatorial]`, so it never runs in CI or a plain `dotnet test` (it needs real ffmpeg/hardware) and contributes 0 to that count; run it by name when touching the transcoding pipeline. |
| `ErsatzTV.Architecture.Tests` | Layering rules via NetArchTest.eNhancedEdition | Core↛Infra/App/EF; FFmpeg↛all; App↛concrete providers. 5 tests. See `docs/contributing.md` §1. |
| `ErsatzTV.FFmpeg.Tests` | FFmpeg command construction | Build a pipeline, assert the exact rendered arg string (`PipelineBuilderBaseTests.cs`). |
| `web/` (vitest) | React SPA unit tests | Run alongside typecheck + build (see below). Collects `src/**`, `web/scripts/**` *and* `web/vite-plugins/**`, but deliberately **excludes** `web/e2e/**` (the Playwright specs — vitest's default `**/*.spec.*` glob would otherwise run them under jsdom). **Requires a git checkout and a `git` binary** since ersatztv#819: `web/src/api/pageSizeCallSites.guard.test.ts` derives its file population from `git ls-files` (via `web/vite-plugins/trackedSourceFiles.ts`) rather than a directory walk, and refuses rather than falling back, so the suite cannot run against an exported tree with no index. `docker/Dockerfile` no longer runs it for exactly that reason. |
| `web/` (vitest) | React SPA unit tests | Run alongside typecheck + build (see below). Collects `src/**`, `web/scripts/**` *and* `web/vite-plugins/**`, but deliberately **excludes** `web/e2e/**` (the Playwright specs — vitest's default `**/*.spec.*` glob would otherwise run them under jsdom). Two files have git prerequisites since ersatztv#819, and they differ: `web/src/api/pageSizeCallSites.guard.test.ts` needs a git **checkout** (it derives its file population from `git ls-files` via `web/vite-plugins/trackedSourceFiles.ts` rather than a directory walk, and refuses rather than falling back), while `web/vite-plugins/trackedSourceFiles.realgit.test.ts` needs the git **binary** (it builds a real temp repository to prove that derivation by executing it). Every other file runs fine with neither. `docker/Dockerfile`'s web-build stage runs the suite with exactly those two `--exclude`d, because its context carries no `.git` and `node:22-bookworm-slim` ships no git — and the two exclusions are there for those two different reasons. |
| `web/e2e/` (Playwright) | UI-interactive E2E flows against a **live** instance | Not a unit suite and **not** part of `npm test` — needs a running server, so it runs via `scripts/e2e-ui.sh` (boots its own fresh instance) and in CI as a step of the `functional-e2e` job. Headless Chromium, `serial`, `retries: 0`. Scope rule: assert only what the curl harness structurally cannot. See `docs/e2e-local.md` → "UI-E2E harness". |
## Golden-file nets
+27 -21
View File
@@ -398,27 +398,6 @@ export function isTrackedSourcePath(key: string, tracked: ReadonlySet<string>):
return tracked.has(globKeyToRootRelativePath(key));
}
/**
* Whether a root-relative path is in scope for the scanner at all — the ONE place that decides it.
*
* Both sides of the comparison call this: the walk (`listSourceFilesFrom`) and the index
* (`expectedTrackedSources`). Two copies of this predicate would be the classic one-helper-two-callers
* divergence, and a divergence between them is a bug in EITHER direction — the walk quietly scanning
* something the index side does not expect, or vice versa.
*/
/**
* Whether the on-disk population has shrunk so far below the index that it reads as a degenerate
* plugin result rather than as a developer mid-edit.
*
* A named function rather than an inline comparison so the threshold has a clause proof: disarming
* an inline `toBeGreaterThan` is an uncaught mutation whose failure direction is fail-OPEN — a
* disarmed floor lets a degenerate population pass every completeness claim below it.
*
* The threshold is deliberately tight, and the cost is stated: a tenth of the in-scope files is
* ~14 today, so deleting a whole feature directory without staging it trips this. That is the #806
* shape (a guard red on an ordinary state), accepted here only because the message names deletions
* first and the remedy is one `git add`.
*/
/**
* Walked paths git accounted for in NEITHER list — see the cross-check test for why that is the
* signal. Extracted and exported for the same reason every other clause in this file was: on a
@@ -446,10 +425,31 @@ export function unaccountedWalkedPaths(
);
}
/**
* Whether the on-disk population has shrunk so far below the index that it reads as a degenerate
* plugin result rather than as a developer mid-edit.
*
* A named function rather than an inline comparison so the threshold has a clause proof: disarming
* an inline `toBeGreaterThan` is an uncaught mutation whose failure direction is fail-OPEN — a
* disarmed floor lets a degenerate population pass every completeness claim below it.
*
* The threshold is deliberately tight, and the cost is stated: a tenth of the in-scope files is
* ~14 today, so deleting a whole feature directory without staging it trips this. That is the #806
* shape (a guard red on an ordinary state), accepted here only because the message names deletions
* first and the remedy is one `git add`.
*/
export function populationIsDegenerate(presentCount: number, inScopeCount: number): boolean {
return presentCount <= inScopeCount * 0.9;
}
/**
* Whether a root-relative path is in scope for the scanner at all — the ONE place that decides it.
*
* Both sides of the comparison call this: the walk (`listSourceFilesFrom`) and the index
* (`expectedTrackedSources`). Two copies of this predicate would be the classic one-helper-two-callers
* divergence, and a divergence between them is a bug in EITHER direction — the walk quietly scanning
* something the index side does not expect, or vice versa.
*/
export function isInScopeSourcePath(rootRelativePath: string): boolean {
// The basename is computed INLINE rather than through a shared `basename()` helper, and that is
// the #819 round-5 fix rather than a style choice: a helper here is a helper the restatement in
@@ -850,6 +850,12 @@ describe('pageSize call-site guard (#650)', () => {
expect(unaccountedWalkedPaths(['src/nestedOther.ts'], [], ['src/nested/'])).toEqual([
'src/nestedOther.ts'
]);
// The trailing-slash RESTRICTION is the clause under test here, not decoration: drop it and
// every `others` entry becomes a prefix mask, so an untracked `src/scratch.ts` would account
// for a walked `src/scratch.tsx` that git never mentioned.
expect(unaccountedWalkedPaths(['src/scratch.tsx'], [], ['src/scratch.ts'])).toEqual([
'src/scratch.tsx'
]);
});
it.each([
+2 -1
View File
@@ -8,7 +8,8 @@
// compile-time link to it, so a renamed or retyped field type-checks here and fails at
// runtime. Importing the real type would drag `@types/node` into the app project, which is
// the whole thing this arrangement exists to avoid. The runtime failure is loud and immediate
// (the guard's first assertion reads the field), which is why the trade is taken.
// — a renamed field yields `new Set(undefined)`, an empty population, which the anti-vacuity floor
// reddens on immediately — which is why the trade is taken.
declare module 'virtual:etv-tracked-source-files' {
const trackedSources: {
/** Paths relative to the Vite root (`web/`), e.g. `src/api/pageSizeScan.ts`. */
@@ -0,0 +1,89 @@
import { execFileSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterAll, describe, expect, it } from 'vitest';
import { type GitRunner, resolveTrackedSourceFiles } from './trackedSourceFiles';
/**
* SEPARATE FILE because these are the only tests in the SPA suite that need the `git` BINARY, not
* merely a checkout (ersatztv#819).
*
* `docker/Dockerfile`'s web-build stage runs on `node:22-bookworm-slim`, which ships no git at all,
* so this file is excluded there alongside the guard that needs an index. Keeping them apart means
* that exclusion costs two files rather than the thirteen injected-runner tests in
* `trackedSourceFiles.test.ts`, which run fine with no git and no repository.
*
* Do NOT make these skip when git is missing. A check that answers "could not tell" by passing is a
* permanent no-op, which is the whole failure mode this plugin exists to avoid.
*/
describe('resolveTrackedSourceFiles against a REAL repository (#819)', () => {
// Every test above injects a fake `GitRunner`, which proves the derivation's SHAPE and never that
// it works against git. `scripts/tests/test_guard_populations_derive_from_git.py` makes exactly
// this point about its own primitive — "It proves the mechanism by EXECUTING it rather than by
// recognising its shape — no monkeypatching, no stand-in for git" — and the population this
// plugin feeds is asserted for completeness, so it earns the same treatment.
const repos: string[] = [];
afterAll(() => {
for (const dir of repos) {
rmSync(dir, { recursive: true, force: true });
}
});
function repoWithOneTrackedAndOneUntracked(): string {
const dir = mkdtempSync(join(tmpdir(), 'etv-819-'));
repos.push(dir);
const git = (...args: string[]) => execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
git('init', '-q');
mkdirSync(join(dir, 'src'), { recursive: true });
writeFileSync(join(dir, 'src', 'tracked.ts'), 'export const a = 1;\n');
writeFileSync(join(dir, 'src', 'untracked.ts'), 'export const b = 2;\n');
// STAGED, not committed. `ls-files` reads the INDEX, so a commit adds nothing — and committing
// makes the fixture depend on the developer's global git config: under a `commit.gpgsign = true`
// that many people set, `git commit` fails and these tests go red on their machine while CI
// stays green. That is the very shape #819 exists to remove, so it must not be reintroduced by
// #819's own tests. `git add` is unaffected by signing.
git('add', 'src/tracked.ts');
return dir;
}
it('really separates a tracked file from an identical untracked sibling', () => {
const result = resolveTrackedSourceFiles(repoWithOneTrackedAndOneUntracked());
expect(result.tracked).toEqual(['src/tracked.ts']);
expect(result.others).toEqual(['src/untracked.ts']);
expect(result.absentFromDisk).toEqual([]);
});
it('really reports a tracked file deleted from the working tree as absent', () => {
const dir = repoWithOneTrackedAndOneUntracked();
rmSync(join(dir, 'src', 'tracked.ts'));
const result = resolveTrackedSourceFiles(dir);
expect(result.tracked).toEqual(['src/tracked.ts']);
expect(result.absentFromDisk).toEqual(['src/tracked.ts']);
});
it('really throws outside a repository, rather than returning an empty population', () => {
const notARepo = mkdtempSync(join(tmpdir(), 'etv-819-bare-'));
repos.push(notARepo);
mkdirSync(join(notARepo, 'src'), { recursive: true });
// `GIT_CEILING_DIRECTORIES` stops git walking up into an enclosing repository — without it this
// test depends on where TMPDIR happens to point, and reports the wrong throw when TMPDIR sits
// inside a checkout.
const ceiling: GitRunner = (args) =>
execFileSync('git', [...args], {
encoding: 'utf8',
// Same stderr suppression `runGitDefault` sets, for the same reason: without it git's own
// `fatal: not a git repository` prints on every run of this file.
stdio: ['ignore', 'pipe', 'pipe'],
env: { ...process.env, GIT_CEILING_DIRECTORIES: tmpdir() }
});
expect(() => resolveTrackedSourceFiles(notARepo, ceiling)).toThrow(/could not read the git index/);
});
});
+10 -74
View File
@@ -1,8 +1,4 @@
import { execFileSync } from 'node:child_process';
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterAll, describe, expect, it } from 'vitest';
import { describe, expect, it } from 'vitest';
import {
TRACKED_SOURCE_FILES_ID,
type FileExists,
@@ -107,6 +103,15 @@ describe('resolveTrackedSourceFiles (#819)', () => {
expect(seen).toEqual(['/repo/web/src/present.ts', '/repo/web/src/deleted.ts']);
});
it('deduplicates a path git emits once per merge-conflict stage', () => {
// `git ls-files` lists an unmerged path once per stage. Nothing downstream needs the repetition.
const { run } = runnerReturning('src/a.ts\0src/a.ts\0src/b.ts\0');
expect(resolveTrackedSourceFiles('/repo/web', run, allPresent).tracked).toEqual([
'src/a.ts',
'src/b.ts'
]);
});
it('THROWS when git fails, instead of degrading to an unfiltered walk', () => {
// The failure this rejects is the fail-open one: answering "could not tell" with the very
// population the index was brought in to replace is a permanent no-op that reports green.
@@ -169,72 +174,3 @@ describe('trackedSourceFilesPlugin (#819)', () => {
expect(calls).toHaveLength(2);
});
});
describe('resolveTrackedSourceFiles against a REAL repository (#819)', () => {
// Every test above injects a fake `GitRunner`, which proves the derivation's SHAPE and never that
// it works against git. `scripts/tests/test_guard_populations_derive_from_git.py` makes exactly
// this point about its own primitive — "It proves the mechanism by EXECUTING it rather than by
// recognising its shape — no monkeypatching, no stand-in for git" — and the population this
// plugin feeds is asserted for completeness, so it earns the same treatment.
const repos: string[] = [];
afterAll(() => {
for (const dir of repos) {
rmSync(dir, { recursive: true, force: true });
}
});
function repoWithOneTrackedAndOneUntracked(): string {
const dir = mkdtempSync(join(tmpdir(), 'etv-819-'));
repos.push(dir);
const git = (...args: string[]) => execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
git('init', '-q');
mkdirSync(join(dir, 'src'), { recursive: true });
writeFileSync(join(dir, 'src', 'tracked.ts'), 'export const a = 1;\n');
writeFileSync(join(dir, 'src', 'untracked.ts'), 'export const b = 2;\n');
// STAGED, not committed. `ls-files` reads the INDEX, so a commit adds nothing — and committing
// makes the fixture depend on the developer's global git config: under a `commit.gpgsign = true`
// that many people set, `git commit` fails and these tests go red on their machine while CI
// stays green. That is the very shape #819 exists to remove, so it must not be reintroduced by
// #819's own tests. `git add` is unaffected by signing.
git('add', 'src/tracked.ts');
return dir;
}
it('really separates a tracked file from an identical untracked sibling', () => {
const result = resolveTrackedSourceFiles(repoWithOneTrackedAndOneUntracked());
expect(result.tracked).toEqual(['src/tracked.ts']);
expect(result.others).toEqual(['src/untracked.ts']);
expect(result.absentFromDisk).toEqual([]);
});
it('really reports a tracked file deleted from the working tree as absent', () => {
const dir = repoWithOneTrackedAndOneUntracked();
rmSync(join(dir, 'src', 'tracked.ts'));
const result = resolveTrackedSourceFiles(dir);
expect(result.tracked).toEqual(['src/tracked.ts']);
expect(result.absentFromDisk).toEqual(['src/tracked.ts']);
});
it('really throws outside a repository, rather than returning an empty population', () => {
const notARepo = mkdtempSync(join(tmpdir(), 'etv-819-bare-'));
repos.push(notARepo);
mkdirSync(join(notARepo, 'src'), { recursive: true });
// `GIT_CEILING_DIRECTORIES` stops git walking up into an enclosing repository — without it this
// test depends on where TMPDIR happens to point, and reports the wrong throw when TMPDIR sits
// inside a checkout.
const ceiling: GitRunner = (args) =>
execFileSync('git', [...args], {
encoding: 'utf8',
env: { ...process.env, GIT_CEILING_DIRECTORIES: tmpdir() }
});
expect(() => resolveTrackedSourceFiles(notARepo, ceiling)).toThrow(/could not read the git index/);
});
});
+4 -3
View File
@@ -99,9 +99,10 @@ export function resolveTrackedSourceFiles(
// `-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.
// Deduplicated: during a merge conflict `git ls-files` emits an unmerged path once per stage
// (three times), which nothing downstream needs and which makes the list's length meaningless as
// a denominator.
// Deduplicated: during a merge conflict `git ls-files` emits an unmerged path once per STAGE —
// two for a both-added conflict, three for a content conflict. Nothing downstream needs the
// repetition. It is tidiness rather than a fix: the ratio the floor computes uses the same list
// on both sides, so duplicates cancel out of it (measured green with and without this).
const tracked = [...new Set(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