Skip to content

Commit 49e9df4

Browse files
committed
fix: harden test-only-exports ratchet per review
Addresses the two should-fixes and all five minors from the independent review of #1202: - Replace the regex own-file occurrence count with an oxc-parser AST walk (typescript@7 ships no JS scanner API, so the review's fallback tool suggestion is the primary): identifiers are counted as AST nodes deduped by source span, so mentions in JSDoc/block comments, strings, and template-literal text no longer masquerade as call sites (review finding 1, both constructed cases re-verified fixed), and a `//` inside a string no longer hides real usages (finding 6). Span dedupe keeps barrel re-exports (`export { x } from`) counting once. The sharper count surfaced one organic false negative on main: `selector` in src/commands/index.ts was previously exempted because the regex matched "selector" inside the './...selector-read.ts' import path string; it is now baselined alongside its sibling `ref` (same re-export line). - Make the baseline shrink-only (finding 2): --update-baseline refuses new findings with the same wire/delete/annotate message, so the `// test-seam:` annotation in the reviewed source diff is the only acceptance path; CONTRIBUTING no longer documents baseline regeneration as an acceptance option and now describes baseline growth as a deliberate manual edit. - Stale baseline entries now emit a `::warning` CI annotation (finding 3). - Commit a re-runnable fixture test (finding 4): check.test.ts mirrors scripts/layering/model.test.ts, builds a synthetic package with a clearMetroSessionHints-shaped export (JSDoc self-mention included), asserts it is flagged, and asserts the annotated twin passes; wired before the check in pnpm check:test-only-exports. - Mark the unreadable/unparseable-file fallbacks CONSERVATIVE: per CONTRIBUTING's convention (finding 5). - Document the dynamic property access (obj[name]) blind spot in the script header and CONTRIBUTING (finding 7).
1 parent 818b2a4 commit 49e9df4

5 files changed

Lines changed: 307 additions & 72 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -64,9 +64,14 @@ graph against its `--production` graph (which excludes test files); an export al
6464
and dead in the second has no production call site. New findings fail CI against the checked-in
6565
`scripts/test-only-exports-baseline.json`. Fix a finding by wiring the export into a real call
6666
site, deleting it, or — if it is an intentional test seam — adding `// test-seam: <reason>`
67-
directly above the export, which removes it from the check. Run
68-
`pnpm check:test-only-exports:baseline` to regenerate the baseline after fixing or intentionally
69-
accepting findings.
67+
directly above the export. The annotation is the only acceptance path, and it lives in the
68+
reviewed source diff. The baseline is shrink-only: after removing an offender, run
69+
`pnpm check:test-only-exports:baseline` to shrink it; the command refuses to add entries, so
70+
growing the baseline takes a deliberate manual edit and should be rare (expected only when the
71+
check itself is migrated). Known limitation: production usage reached only via dynamic property
72+
access (`obj[name]`) is invisible to fallow's import graph — the same blind spot as fallow's own
73+
dead-code check — so such exports need a `// test-seam:` annotation or a `.fallowrc.json`
74+
`ignoreExports` entry (like the daemon route handlers loaded through `typeof import()`).
7075

7176
Optional device selectors for tests:
7277

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@
113113
"check:fallow": "fallow audit",
114114
"check:layering": "node --experimental-strip-types --test scripts/layering/model.test.ts && node --experimental-strip-types scripts/layering/check.ts",
115115
"check:layering:baseline": "node --experimental-strip-types scripts/layering/check.ts --update-baseline",
116-
"check:test-only-exports": "node --experimental-strip-types scripts/test-only-exports/check.ts",
116+
"check:test-only-exports": "node --experimental-strip-types --test scripts/test-only-exports/check.test.ts && node --experimental-strip-types scripts/test-only-exports/check.ts",
117117
"check:test-only-exports:baseline": "node --experimental-strip-types scripts/test-only-exports/check.ts --update-baseline",
118118
"check:quick": "pnpm lint && pnpm typecheck",
119119
"sync:mcp-metadata": "node scripts/sync-mcp-metadata.mjs",

‎scripts/test-only-exports-baseline.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,11 @@
4949
"export": "ref",
5050
"line": 47
5151
},
52+
{
53+
"path": "src/commands/index.ts",
54+
"export": "selector",
55+
"line": 47
56+
},
5257
{
5358
"path": "src/core/command-descriptor/registry.ts",
5459
"export": "listCapabilityCheckedCommandNames",
Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
// Re-runnable acceptance test for the test-only-exports ratchet, mirroring
2+
// scripts/layering/model.test.ts. The fixture scenarios reproduce the shape
3+
// of PR #1199's clearMetroSessionHints (exported + unit-tested + zero
4+
// production call sites) and the reviewer-constructed false negatives from
5+
// PR #1202's review (JSDoc/string mentions of the export's own name).
6+
7+
import assert from 'node:assert/strict';
8+
import { test } from 'node:test';
9+
import fs from 'node:fs';
10+
import os from 'node:os';
11+
import path from 'node:path';
12+
import { fileURLToPath } from 'node:url';
13+
import { computeTestOnlyExports, countIdentifierOccurrences } from './check.ts';
14+
15+
const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
16+
const fallowBin = path.join(repoRoot, 'node_modules/.bin/fallow');
17+
18+
test('JSDoc and string mentions of the export name are not call sites', () => {
19+
const source = [
20+
'/**',
21+
' * clearHints is documented here mentioning clearHints by name.',
22+
' */',
23+
'export function clearHints(): void {}',
24+
"const note = 'clearHints is unused in prod';",
25+
'const tpl = `template text clearHints`;',
26+
].join('\n');
27+
assert.equal(countIdentifierOccurrences('t.ts', source, 'clearHints'), 1);
28+
});
29+
30+
test('a template substitution or same-file call is a real occurrence', () => {
31+
const called = ['export function clearHints(): void {}', 'clearHints();'].join('\n');
32+
assert.equal(countIdentifierOccurrences('t.ts', called, 'clearHints'), 2);
33+
const substituted = [
34+
'export function clearHints(): string { return ""; }',
35+
'const tpl = `${clearHints()}`;',
36+
].join('\n');
37+
assert.equal(countIdentifierOccurrences('t.ts', substituted, 'clearHints'), 2);
38+
});
39+
40+
test('a // inside a string does not hide a real usage after it', () => {
41+
// The pre-review regex stripped everything after a `//` even inside a
42+
// string literal, which could under-count real same-line usages.
43+
const source = [
44+
'export function clearHints(): void {}',
45+
"const url = 'https://example.com'; clearHints();",
46+
].join('\n');
47+
assert.equal(countIdentifierOccurrences('t.ts', source, 'clearHints'), 2);
48+
});
49+
50+
test('a barrel re-export counts its source token once', () => {
51+
const source = "export { clearHints } from './hints.ts';";
52+
assert.equal(countIdentifierOccurrences('t.ts', source, 'clearHints'), 1);
53+
});
54+
55+
test('an unparseable file reports undefined instead of a count', () => {
56+
assert.equal(countIdentifierOccurrences('t.ts', 'export function {{{', 'clearHints'), undefined);
57+
});
58+
59+
type FixtureOptions = {
60+
annotated: boolean;
61+
};
62+
63+
function writeFixture(options: FixtureOptions): string {
64+
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'test-only-exports-fixture-'));
65+
fs.mkdirSync(path.join(root, 'src'));
66+
// an empty node_modules keeps fallow from warning about a missing install
67+
fs.mkdirSync(path.join(root, 'node_modules'));
68+
fs.writeFileSync(
69+
path.join(root, 'package.json'),
70+
`${JSON.stringify(
71+
{ name: 'test-only-exports-fixture', private: true, type: 'module', main: 'src/index.ts' },
72+
null,
73+
2,
74+
)}\n`,
75+
);
76+
fs.writeFileSync(
77+
path.join(root, 'src/index.ts'),
78+
"export { persistSessionHints } from './session-hints.ts';\n",
79+
);
80+
const annotation = options.annotated
81+
? '// test-seam: fixture twin proving the annotation is honored\n'
82+
: '';
83+
fs.writeFileSync(
84+
path.join(root, 'src/session-hints.ts'),
85+
[
86+
'export function persistSessionHints(session: string): string {',
87+
' return `persisted:${session}`;',
88+
'}',
89+
'',
90+
'/**',
91+
' * clearSessionHints removes the hint file; this JSDoc mentions',
92+
' * clearSessionHints by name, like ordinary documentation does.',
93+
' */',
94+
`${annotation}export function clearSessionHints(session: string): string {`,
95+
' return `cleared:${session}`;',
96+
'}',
97+
'',
98+
].join('\n'),
99+
);
100+
fs.writeFileSync(
101+
path.join(root, 'src/session-hints.test.ts'),
102+
[
103+
"import { clearSessionHints } from './session-hints.ts';",
104+
'',
105+
"if (clearSessionHints('s') !== 'cleared:s') throw new Error('fixture self-check');",
106+
'',
107+
].join('\n'),
108+
);
109+
return root;
110+
}
111+
112+
test('flags an exported-and-tested function with zero production call sites', () => {
113+
const root = writeFixture({ annotated: false });
114+
try {
115+
const findings = computeTestOnlyExports({ root, fallowBin });
116+
assert.deepEqual(findings, [
117+
{ path: 'src/session-hints.ts', export: 'clearSessionHints', line: 9 },
118+
]);
119+
} finally {
120+
fs.rmSync(root, { recursive: true, force: true });
121+
}
122+
});
123+
124+
test('a test-seam annotation removes the export from the check', () => {
125+
const root = writeFixture({ annotated: true });
126+
try {
127+
assert.deepEqual(computeTestOnlyExports({ root, fallowBin }), []);
128+
} finally {
129+
fs.rmSync(root, { recursive: true, force: true });
130+
}
131+
});

0 commit comments

Comments
 (0)