[finding] `affected-docs.mjs` passes `isTestFile` a BASENAME, so its three directory arms (`__tests__`/`__mocks__`/`__fixtures__`) are dead — latent today, 0 live

[os-steve]

Observed while implementing #11178 (PR #11865). Latent, not live — filed so it is recorded rather than re-discovered. Filed unassigned and unlabelled for queueing. ⛔ Not a claim on anyone's time.

The reading

scripts/docs-audit/affected-docs.mjs defines the exclusion over a path:

function isTestFile(path) {
 return /(^|\/)__(tests|mocks|fixtures)__\//.test(path)
 || /(^|\/)[^/]+\.(test|spec)\.[^/]+$/.test(path);
}

Both scanRouteSurface's walk and the --bridge-coverage ceiling added by PR #11865 call it with e.name — the basename:

else if (e.isFile() && e.name.endsWith('.ts') && !isTestFile(e.name)) {

The first arm requires a /, so against a basename it can never match. Only the *.test.ts / *.spec.ts arm does any work. The function's directory-based exclusion is not happening at this call site.

Measured impact today: zero

Three non-.test/.spec .ts files live in such directories under packages/** and are therefore walked:

• packages/services/service-datasource/src/__tests__/entitled-caller.fixture.ts
• packages/cli/src/utils/__tests__/server-body.ts
• packages/adapters/hono/src/__mocks__/runtime.ts

0 of the three match REGISTRAR_FILE_RE, so none becomes a registrar and no route tail today comes from a test directory. (server-body.ts does not match the -server.ts alternative — that requires -server immediately before the extension.) Confirmed on 589758d22: none of the 14 discovery-gap witnesses PR #11865 reports comes from any of these paths; all 14 are packages/spec/src/api/*.zod.ts.

So this is a dormant hole, not a current wrong number. It becomes live the moment a file named *route*.ts or *-server.ts is added under a __tests__/, __mocks__/ or __fixtures__/ directory — at which point a test double starts contributing production route tails silently.

Not claimed

• No opinion on the remedy. Passing rel instead of e.name is the obvious shape, but rel is computed after the test in the current code, and whether the walk should exclude these directories at all is a real question — the ceiling in PR fix(devx): split the sdk bridge's unreachable rows by cause (#11178) #11865 arguably wants the widest possible population.
• Whether other callers of isTestFile pass a path or a basename was not swept.

Related but different

#11857 records a separate gap in the same function — that it excludes neither test/fixtures/*.ts (no underscores) nor *.bench.ts. That one is about the patterns; this one is about the argument the patterns are tested against. Both would need to hold for a test double to be reliably kept out.

Refs

#11178 · PR #11865 (where this was observed) · #11857 (the sibling isTestFile gap)

[claude]

Concentrated triage batch: finding → pm:queue, Task, S (domain:devx stands) — latent (0 live today, measured) but one-line-cheap: both call sites hand isTestFile a basename, so the three directory arms can never match. Pass the walk-relative path (or test e.name against the file arms and the joined path against the directory arms); pin with one fixture file under a __tests__/ dir.

---

Generated by Claude Code

[os-steve]

Claim: devx PM seat, session session_015ahemw8RcTgqtxrj15PEZx, branch claude/issue-11866-affected-docs-basename-arms.

Dispatching now. Label swapped pm:queue → pm:dispatched.

---

Generated by Claude Code

[os-steve]

{
 "issue": 11866,
 "status": "done",
 "branch": "claude/issue-11866-affected-docs-basename-arms",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12002",
 "premise_still_valid": true,
 "summary": "Split scanRouteSurface's walk out as walkSourceFiles(root, readDir) and gave isTestFile the walk-relative path instead of e.name, so the __tests__/__mocks__/__fixtures__ arms actually fire. RULED THE REMEDY THE CARD DECLINED TO RULE: exclude the test directories from BOTH consumers of that walk. The ceiling does not want the widest possible population — a row counted `remediable by discovery` is a claim that widening the FILENAME CONVENTION would reach it, and no widening of that convention may legitimately admit a test double, so a __tests__/ witness would move a row into `remediable` against a remedy nobody can take (the exact conflation bridgeCoverageFrom's split exists to end). Two supports: the superset invariant survives because both populations come off the one walk and narrow together; and NO ratchet moves — check-affected-docs.mjs exits non-zero on brokenScan alone, the 45/221 ratio and the 82-tail ceiling are reported, never gated. Chose triage route (a) over (b) because isTestFile is DEFINED over a path (docblock plus all 14 existing self-test cases), so (b) would enshrine a two-convention contract nothing pins. The card's framing is CONFIRMED, not falsified: re-measured on d63b01436 (a day newer than the card's 589758d22, with #11865 landed), still exactly 3 files, still 0 matching REGISTRAR_FILE_RE or LEDGER_FILE_RE. I also measured the half the card never did — the CEILING, whose population is every walked file, not just convention-matched ones — and --bridge-coverage is byte-identical across the fix, so latent-not-live holds for both halves.",
 "tests": "ALL RUN AT ad9307722 (branch head; git status clean, union run on that exact tree). ① `node scripts/docs-audit/affected-docs.mjs --self-test` → `✓ affected-docs self-test: 451 cases pass.` ② NON-VACUITY, red-before/green-after observed ON DISK IN BOTH DIRECTIONS, from a COMMITTED state. No rebuild leg exists or is needed: affected-docs.mjs is a dependency-free .mjs run directly by `node` from source, never through a dist/ — there is no build output that could keep a stale copy alive, so the ablation's disk state IS the executed state. Mutation = the one call-site argument reverted to `isTestFile(e.name)`, under `trap '<git checkout -- $F>' EXIT INT TERM`. Confirmed on disk by anchored `grep -c -F` on BOTH the injected and the removed text, not by the editor's exit code — and that guard EARNED ITS KEEP: attempt 1 was a silent no-op (a perl `\\Q…\\E` anchor with pre-escaped parens matched nothing and exited 0); counts read fixed=1/buggy=0 unchanged, the script refused to read a result, and that reading was discarded rather than quietly re-run. Attempt 2, mutated leg: fixed form 0 · buggy form 1 · `git diff --stat` 1 file changed → `--self-test` EXIT 1, `✗ affected-docs self-test failed (9 case(s))` — registrarFiles came back as 4 (real-route.ts PLUS __tests__/x-route.ts, __mocks__/fake-server.ts, __fixtures__/stub-route-ledger.ts) and sourceFiles as 6, against the 1 and 2 asserted. Restored leg: fixed form 1 · buggy form 0 · `git status --porcelain` 0 files → `✓ affected-docs self-test: 451 cases pass.` ③ CEILING MEASUREMENT: `--bridge-coverage` and `--bridge-coverage --json` diffed pre-fix vs post-fix → byte-identical, and the ablated run is identical to the pre-fix baseline too (12 registrar files · 43 tails · 82-tail ceiling · 45 reachable / 177 unreachable · causes 14/56/107). ④ STRICT-TIGHTENING PROOF over all 4625 .ts files under packages/**: 3 excluded-by-path-not-by-basename, 0 the other way — so reordering `rel` ahead of the test cannot admit anything the old order excluded. ⑤ GATES: derived with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` and NO hand-written path list (it read the change set off merge base d63b01436 itself: 1 path, committed 1 / working tree 0 / untracked 0; stderr confirmed the answer came from objectstack-ai/objectstack at ad9307722). All 12 matched families green, quoted from their OWN verdict lines with exit codes captured before any pipe: `✓ affected-docs self-test: 451 cases pass.` · `✓ check-drift-comment: 56 cases pass across 5 fixture diff(s).` · `✓ check-self-test-wired: every one of the 127 script(s) CI runs that ship a --self-test has that self-test run by CI.` · `✓ check:entry-guard: 156 scripts/ file(s)` · `✓ check:parse-guard: 155 scripts/ file(s)` · `✓ check-governed-merges --self-test: 129 assertions` · `✓ check-pnpm-filter-targets --self-test: 40 assertions` · `✓ check-agent-test-spelling: 0 violations` · `✓ docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s).` · `OK: all 96 declared cross-package glob(s) (81 unique) are covered` · `OK: 16 package(s) read outside themselves` (×2 spellings). Plus `check-nul-bytes: OK (scanned 6661 text file(s) … no raw ASCII control bytes)` and a manual `grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]'` over the changed file and the PR body, both clean. ⑥ LINT NOT NARROWED: repo-wide `pnpm lint` (= `eslint . --no-inline-config`) run IN FULL under the shared verify lock — `VERDICT command-exit 0 · held the lock 55s · waited 0s`. No narrowing argument is owed because no narrowing was taken.",
 "open_questions": [],
 "out_of_scope_findings": []
}

Notes for the PM, outside the JSON

• [finding] An evidence-based registrar route reaches 14 more client-bound rows and closes the storage ledger — but it redefines "registrar" to include Zod contract declarations, and admits 3 non-registrars #11857 collision check (requested explicitly): none, and the two are complementary in one direction. Measured — all three files [finding] An evidence-based registrar route reaches 14 more client-bound rows and closes the storage ledger — but it redefines "registrar" to include Zod contract declarations, and admits 3 non-registrars #11857 enumerates (qa/dogfood/test/fixtures/endpoint-policy-fixture.ts, spec/src/benchmark.bench.ts, spec/src/conversions/registry.ts) are admitted both before and after this change, so the fixes are disjoint on today's tree. But test/fixtures/*.ts is itself a path-shaped pattern: adding it to isTestFile while this call site still passed a basename would have produced another dead arm — the identical failure. This PR is a prerequisite for [finding] An evidence-based registrar route reaches 14 more client-bound rows and closes the storage ledger — but it redefines "registrar" to include Zod contract declarations, and admits 3 non-registrars #11857's cheaper half, not a competitor. Textually [finding] An evidence-based registrar route reaches 14 more client-bound rows and closes the storage ledger — but it redefines "registrar" to include Zod contract declarations, and admits 3 non-registrars #11857 edits the predicate body and may extend walkSourceFiles; that is a rebase touch, not a semantic conflict.
• A small correction to the card's reading. The card says "both call sites hand isTestFile a basename". There is only one — the walk at what was line 1394. It serves two consumers (registrarFiles, the bridge's discovery, and sourceFiles, the The sdk doc-nomination bridge cannot reach the auth surface: REGISTRAR_FILE_RE matches by filename convention and auth-plugin.ts matches neither alternative (#10534 follow-up 3) #11178 ceiling) from the same pass, which is why it reads as two. This does not change the finding or the fix.
• The other callers, swept (the card flagged this as not done). isTestFile is module-local, never exported, and the script is only ever spawned — so the sweep is closed. Three call sites: the walk (basename, broken — fixed), the --self-test cases (full paths, correct), and the changed-file loop over git diff --name-only output (full paths, correct). Only the broken one is touched, so no correct caller is disturbed.
• Same-class sweep beyond this file, clean. The repo has three other isTestFile definitions. check-runner-env-posture.mjs (via isProductSource) and check-dispatcher-error-vocabulary.mjs (via walkSources) both pass a full relative path; dispatch-gates.mjs's isTestFilePath deliberately does not treat __tests__ helpers as tests and pins that. No live instance of this defect class elsewhere — nothing to file.
• Why the pin had to be structural. The existing self-test pins isTestFile with full paths and stays green either way — the predicate was never the broken half, the caller was. So the walk is split out as walkSourceFiles(root, readDir), readDir injectable for the same reason packageRootOf's hasPackageJson is, and the new cases walk a fake tree through the real call site. With a zero live population, a pin built from real repo paths would have passed just as green with the bug in place.
• skip-changeset applied via the additive POST endpoint and read back after the size labeler ran — labels are now size/m + skip-changeset, so it was not clobbered. No changeset: this edits a CI-internal script and releases nothing, the case lint.yml names as the textbook use of that label.
• No CI wait, per the dispatch contract — reporting at draft-PR time. Worktree removed cleanly (no --force).

---

Generated by Claude Code

---

Generated by Claude Code