Repository navigation
Description
Part of #1259.
Scope
After this PR, pnpm check fails when a tracked code file passes 1,400 lines or a test file passes 2,500, unless the file is on a shrink-only list of the files over their limit when it merges (22 on 059a270). A listed file may not grow past its listed length; a PR that has to grow one raises that length in the list, in the same PR, as a visible line of its diff (ADR 0063 §3). Testing rule 6 gains the reason ADR 0063 §2 gives for testing a part. Nothing else changes.
In short
A contributor whose change makes a file too long sees pnpm check fail, with the file, its lines and the limit named. The files already too long may stay until their own split, but may not grow unless the same PR raises their listed length. A shrink-only list is the test's list of those files, each with its length when the test landed.
flowchart LR
A[pnpm check] --> B[unit tests]
B --> C["source-hygiene: tracked files stay within their size limit, and the shrink-only list stays true (new)"]
C -- over and not listed --> F[fail: file, lines, limit]
C -- listed and grew, or under, or gone --> G[fail: fix the list entry]
C -- otherwise --> P[pass]
The failure lines, word for word (<path>, <n> and <listed> vary; every number is printed with no thousands separator):
<path>: <n> lines; a code file may have at most 1400. Split it (ADR 0063).
<path>: <n> lines; a test file may have at most 2500. Split it (ADR 0063).
<path>: <n> lines, longer than its listed <listed>. A listed file may only shrink (ADR 0063).
<path>: <n> lines, within its limit now. Remove it from the shrink-only list.
<path>: listed but not tracked. Remove it from the shrink-only list.
A user would notice this going wrong as a good PR failing on a file within its limit, or a too-long file passing.
Technical spec
Facts
Commit 059a270.
| # | Fact | Source |
|---|---|---|
| F1 | src/source-hygiene.test.ts lists tracked files with git ls-files -z in its lsFiles helper |
src/source-hygiene.test.ts:13-21 |
| F2 | its tracked files describe holds the checks over every tracked file |
src/source-hygiene.test.ts:86 |
| F3 | unit tests run every src/**/*.test.ts, and pnpm check runs pnpm run test, which runs test:unit |
vitest.config.ts:20; package.json:51, package.json:71 |
| F4 | a 150-line budget on manuals is checked the same way, as a unit test | src/docs-manuals.test.ts:9, src/docs-manuals.test.ts:113-119 |
| F5 | the repo already calls test-* files test files for its import rules |
.dependency-cruiser.mjs:14 |
| F6 | testing rule 6 allows an internal-file test only for pure logic or an ordering, and a code move edits no test | docs/internal/agent-rules/testing.md:83-96 |
| F7 | on 059a270 exactly 22 scanned files are over their limit: 15 tests and 7 code files, listed under Tests | git ls-files src ui e2e scripts .agents/scripts filtered to .ts .tsx .mts .mjs .js .cjs, then wc -l; output first line 11537 src/cli/index.test.ts, last 1496 src/contract/schemas.ts |
| F8 | Fallow 3.36.0, the version locked here, has no file-length rule: its health keys are maxCyclomatic, maxCognitive, maxCrap, maxUnitSize (one function), thresholdOverrides and settings that set no limit |
node_modules/fallow/schema.json HealthConfig at pnpm-lock.yaml:2180 fallow@3.36.0 |
| F9 | a line count is the number of newline characters, as wc -l prints it |
wc -l output of F7 |
Modules touched
Searches: git grep -n "ordering the surface" (2 hits: .agents/scripts/test-lint.mjs:37, src/test-lint.test.ts:62); git grep -n "source-hygiene" (4 hits, all prose naming the file: VENDORED-CODE.md, always-in-scope.md, vendor-and-third-party-code.md, vendor/README.md; none needs a change); git grep -n "Test a module through its surface" (1 hit).
src/source-hygiene.test.ts: two newits intracked files(one per Tests line), the pure check they call, and the shrink-only list..agents/scripts/test-lint.mjsandsrc/test-lint.test.ts: the lint's message quotes rule 6's reasons word for word (.agents/scripts/test-lint.mjs:37, pinned atsrc/test-lint.test.ts:62); both gain the third reason.docs/internal/agent-rules/testing.md: rule 6 gains the third reason and the move exception (ADR 0063 §2).
Contract and event changes
none: no contract file or event changes (git grep of src/contract/ for the new names: 0 hits).
Other code on the same state
The state is the list of tracked files and their contents. Searches: git grep -n "ls-files" src/*.test.ts (4 files: source-hygiene, docs-manuals, lint-rules, stale-refs). All of them only read; none writes a tracked file. No other task of this feature writes the list except #1272, which removes the two Android entries.
Failure modes
| Call | Outcome | What happens | Limit, counted from |
|---|---|---|---|
git ls-files |
ok | the file list is checked | the test's own vitest timeout, from the test's start |
git ls-files |
throws (no git) | the test fails with git's error, as the other tracked files tests do today |
the same |
No state is written.
Rules in play
- Testing rule 7, "extend an existing test": the checks are two more
its insource-hygiene.test.ts'stracked files, one per Tests line. - Testing rule 10, a claim of "every" names its cases: the pure check is table-tested with each Examples row of Split the source and test files too big for agents to read whole #1259.
- ADR 0063 §3, "nothing grows silently": a listed file may not grow past its listed length, a raise is an edit to its line, and an entry that no longer holds fails.
- ADR 0063 §2, narrows testing rule 6:
testing.mdrule 6 says so in the same words.
Tests
The seam is src/source-hygiene.test.ts (model: its tracked files describe at src/source-hygiene.test.ts:86). The pure check takes each file's path and line count and the list, and returns the failure lines above. Each Tests line is one it: a table of its cases through the pure check, then the check over the real tracked files, expecting no failure line of its kind.
- A contributor runs the size test with a file over its limit that is not listed, and it fails naming the file, its lines and the limit; cases: code 1,400 passes, 1,401 fails; test 2,500 passes, 2,501 fails;
test-x.tsandtesting.tscount as tests. - A contributor runs the size test with a listed file, and it fails when the file grew past its listed length or no longer needs the entry; cases: same length passes; shrunk passes; grew by one fails; under its limit fails; deleted fails.
The entries of the list: every file the F7 command prints over its limit on the commit this PR merges from, with its length there. On 059a270 they are these 22 (an open PR such as #1258 can add src/core/config.test.ts):
src/cli/index.test.ts, src/drivers/android/index.test.ts, src/daemon/dispatcher.test.ts, src/drivers/ios/index.test.ts, src/gateway/fleet-coordinator.test.ts, src/leasing/create-leasing.test.ts, src/daemon/main.test.ts, src/agent-device/edge.test.ts, src/daemon/server.test.ts, src/leasing/lease-acquisition-coordinator.test.ts, src/drivers/android/index.ts, src/core/doctor.test.ts, src/http/app.test.ts, src/gateway/dispatcher.test.ts, src/core/warm-pool/converger.test.ts, src/core/registry.test.ts, src/drivers/ios/index.ts, src/daemon/main.ts, src/daemon/server.ts, src/gateway/fleet-coordinator.ts, src/leasing/lease-acquisition-coordinator.ts, src/contract/schemas.ts.
Done when
pnpm exec vitest run --project unit src/source-hygiene.test.tspasses on the branch, and fails when a line is added tosrc/daemon/main.ts.- The list holds exactly the files the F7 command prints over their limit on the branch.
testing.mdrule 6, and the test lint's message, name "a part of a decomposed module"; rule 6 names the move exception.
Out of scope
- Splitting any file. Each split is Android driver: adb-tools.ts, the leaf part for env, commands and device folders #1264–Android driver: seeds.ts owns seeds and copies, and the root is done #1272 or a later feature.
- Counting
vendor/,website/ordocs/.
Depends on
Written by an agent.
Activity
test: a listed file that grew or no longer needs its entry fails (#1263)
feat(test): a listed file may only shrink and its entry must still ho…
docs(testing): rule 6 names a part of a decomposed module and the mov…
test(hygiene): size test, a code file stays at 1,400 lines and a test…