Skip to content

Commit 14d1c8d

Browse files
committed
fix(ci): replace the DI-seam name-based allowlist with an explicit per-site one
Review on PR #2006 (#1976): the previous revision fixed the exit-code handling but decided which `?: typeof X` matches to ban with a regex that exempted matches by the *spelling* of the typeof target (`typeof fetch` always passed, SCREAMING_SNAKE_CASE targets always passed). That's a name-based semantic allowlist, not ownership: a new, genuinely test-only `typeof fetch` seam anywhere in the tree would have silently passed, while an equally legitimate seam under any other name would still fail. Add scripts/di-seams: a small, tested TypeScript checker that judges each match against an explicit, typed, per-site allowlist (scripts/di-seams/approved.ts) keyed by (file, field name, typeof target) rather than by name. A triple is exempt only because it was individually reviewed and named — never because of how it's spelled — and the gate fails just as hard on a stale approval (one whose triple no longer matches anything, e.g. after a rename) as on an unapproved seam, so the list can't silently drift out of sync with the code it describes. Moves the DI-seams step in ci.yml to run after Setup toolchain (it's no longer a toolchain-free text scan); the Swift trailing-comma check stays where it was.
1 parent 358b169 commit 14d1c8d

7 files changed

Lines changed: 329 additions & 32 deletions

File tree

‎.fallowrc.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
"examples/test-app/**",
4040
"scripts/perf/**",
4141
"scripts/layering/**",
42+
"scripts/di-seams/**",
4243
"scripts/maestro-conformance/corpus/**",
4344
"apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests.xctestplan",
4445
"scripts/write-xcuitest-cache-metadata.mjs",

‎.github/workflows/ci.yml‎

Lines changed: 18 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,9 @@ concurrency:
2828
cancel-in-progress: true
2929

3030
jobs:
31-
# Text-only assertions run before the toolchain setup, so a grep failure does
32-
# not wait on an install.
31+
# The Swift trailing-comma assertion is text-only and runs before the toolchain setup, so a
32+
# grep failure does not wait on an install. The DI-seams check below needs a real TypeScript
33+
# runtime (#1976 / PR #2006), so it runs after Setup toolchain instead.
3334
lint:
3435
name: Lint & Format
3536
runs-on: ubuntu-latest
@@ -63,39 +64,24 @@ jobs:
6364
exit 1
6465
fi
6566
66-
# Same false-green shape as the check above, plus a narrower pattern (#1976). Two kinds
67-
# of `?: typeof X` are excluded as not being test-only DI seams:
68-
# - `typeof fetch`: fetchImpl?/fetch? params inject the one global with no module
69-
# boundary `vi.mock` can intercept. src/cli/auth-session.ts, cloud-profile.ts, and
70-
# remote/daemon-proxy.ts use the seam for exact per-call assertions in their unit
71-
# tests, while the CLI-level tests use `vi.stubGlobal('fetch', ...)` where the seam
72-
# isn't reachable — a deliberate, exercised seam, not a leftover one.
73-
# - `typeof SOME_CONSTANT` (SCREAMING_SNAKE_CASE): derives a literal union type from a
74-
# constant, e.g. `dispatchPath?: typeof MAESTRO_COORDINATE_FALLBACK_PATH` in
75-
# src/daemon/handlers/interaction-touch-response.ts. Not an injectable seam at all —
76-
# the pattern only ever matched it by syntax coincidence.
77-
- name: Fail if test-only DI seams reappear in production code
78-
run: |
79-
mapfile -d '' -t seam_files < <(git ls-files -z -- 'src' | grep -zvE '/__tests__/|\.test\.ts$')
80-
if [ "${#seam_files[@]}" -eq 0 ]; then
81-
echo "No production src/ files are tracked; the DI-seam check has nothing to scan." >&2
82-
exit 1
83-
fi
84-
set +e
85-
grep -PnH '\?\s*:\s*typeof\s+(?!fetch\b)(?![A-Z][A-Z0-9_]*\b)' "${seam_files[@]}"
86-
status=$?
87-
set -e
88-
if [ "$status" -eq 0 ]; then
89-
echo "Found test-only DI seams (optional typeof params) in production code."
90-
exit 1
91-
elif [ "$status" -ne 1 ]; then
92-
echo "grep exited $status while scanning src/ for DI seams; treating an unreadable scan as a failure instead of a silent pass."
93-
exit 1
94-
fi
95-
9667
- name: Setup toolchain
9768
uses: ./.github/actions/setup-node-pnpm
9869

70+
# Same false-green shape as the Swift check above (#1976). An earlier revision of this
71+
# gate (PR #2006, first review pass) fixed the exit-code handling but kept the ban/allow
72+
# decision as a regex that exempted matches by the *spelling* of the typeof target
73+
# (`typeof fetch` always passed, SCREAMING_SNAKE_CASE targets always passed) — a name-based
74+
# semantic allowlist that would silently pass a new, genuinely test-only `typeof fetch` seam
75+
# anywhere in the tree while banning an equally legitimate seam under any other name.
76+
# scripts/di-seams instead checks each match against an explicit, typed, per-site allowlist
77+
# (scripts/di-seams/approved.ts) keyed by (file, field, typeof-target): a triple is exempt
78+
# only because it was individually reviewed and named, never because of how it is spelled.
79+
# The gate fails just as hard on a stale approval (one whose triple no longer matches
80+
# anything) as on an unapproved seam, so the allowlist can't drift out of sync with the code
81+
# it describes. See scripts/di-seams/model.ts and its tests.
82+
- name: Fail if test-only DI seams reappear in production code
83+
run: pnpm check:di-seams
84+
9985
- name: Run oxlint
10086
uses: ./.github/actions/run-gate
10187
with: { gate: lint }

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@
137137
"check:coverage-changed": "node --experimental-strip-types scripts/coverage-changed/run.ts",
138138
"check:coverage-changed:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/coverage-changed/model.test.ts scripts/coverage-changed/run.test.ts",
139139
"check:layering": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/layering/*.test.ts && node --experimental-strip-types scripts/layering/check.ts",
140+
"check:di-seams": "node --experimental-strip-types --test scripts/di-seams/*.test.ts && node --experimental-strip-types scripts/di-seams/check.ts",
140141
"depgraph": "node --experimental-strip-types scripts/depgraph/build.ts",
141142
"depgraph:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/depgraph/model.test.ts scripts/depgraph/affected.test.ts",
142143
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",

‎scripts/di-seams/approved.ts‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
import type { ApprovedSeam } from './model.ts';
2+
3+
/**
4+
* Each entry is a decision about one (file, field, typeof-target) triple, not a name pattern
5+
* (PR #2006 review, #1976). Exempting every `typeof fetch` seam by spelling would silently pass
6+
* a new, genuinely test-only fetch seam anywhere in the tree while banning an equally legitimate
7+
* seam under any other name. Naming the site is what "approved" means here — add an entry only
8+
* for a call site actually reviewed, never to make a whole identifier exempt.
9+
*
10+
* check.ts fails as hard on a stale entry (one whose triple no longer matches anything in the
11+
* tree) as it does on an unapproved seam, so this list cannot silently drift out of sync with
12+
* the code it is meant to describe.
13+
*/
14+
export const APPROVED_SEAMS: readonly ApprovedSeam[] = [
15+
{
16+
file: 'src/cli/auth-session.ts',
17+
field: 'fetch',
18+
target: 'fetch',
19+
reason:
20+
"AuthIo.fetch injects the fetch global, which has no module boundary vi.mock can " +
21+
'intercept. auth-session.test.ts injects it directly for exact per-call assertions.',
22+
},
23+
{
24+
file: 'src/cli/auth-session.ts',
25+
field: 'fetchImpl',
26+
target: 'fetch',
27+
reason:
28+
'Same fetch-global seam as AuthIo.fetch above, threaded through the device-auth-poll ' +
29+
'and postJson helpers as fetchImpl.',
30+
},
31+
{
32+
file: 'src/cli/connection/cloud-profile.ts',
33+
field: 'fetchImpl',
34+
target: 'fetch',
35+
reason:
36+
'Same fetch-global seam, for the cloud connection-profile request. Exercised at the CLI ' +
37+
"layer by cloud-connect-profile.test.ts via vi.stubGlobal('fetch', ...), a layer where " +
38+
'this parameter is not reachable.',
39+
},
40+
{
41+
file: 'src/remote/daemon-proxy.ts',
42+
field: 'fetchImpl',
43+
target: 'fetch',
44+
reason: "Same fetch-global seam, for the remote daemon proxy's upstream request.",
45+
},
46+
{
47+
file: 'src/daemon/handlers/interaction-touch-response.ts',
48+
field: 'dispatchPath',
49+
target: 'MAESTRO_COORDINATE_FALLBACK_PATH',
50+
reason:
51+
'Not a DI seam at all: derives a literal union-member type from a constant for ' +
52+
'discriminated-union typing, not an injectable optional parameter. The seam pattern ' +
53+
'matches it only by syntax coincidence.',
54+
},
55+
];

‎scripts/di-seams/check.ts‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
// `pnpm check:di-seams` — fails if a test-only DI seam (an optional `field?: typeof X`
2+
// parameter that exists only to let a test inject an alternate implementation) reappears in
3+
// production code. See model.ts and approved.ts for how a match is judged; #1976 / PR #2006 for
4+
// why the judgment is an explicit per-site allowlist rather than a name pattern.
5+
6+
import { execFileSync } from 'node:child_process';
7+
import fs from 'node:fs';
8+
import path from 'node:path';
9+
import { pathToFileURL } from 'node:url';
10+
import { APPROVED_SEAMS } from './approved.ts';
11+
import { checkSeams, findSeamMatches, type SourceFile } from './model.ts';
12+
13+
const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
14+
encoding: 'utf8',
15+
}).trim();
16+
17+
function listProductionSourceFiles(): string[] {
18+
const out = execFileSync('git', ['ls-files', '--', 'src'], { cwd: repoRoot, encoding: 'utf8' });
19+
return out
20+
.split('\n')
21+
.filter(Boolean)
22+
.filter((file) => !file.includes('/__tests__/') && !file.endsWith('.test.ts'));
23+
}
24+
25+
function readSources(files: readonly string[]): SourceFile[] {
26+
return files.map((file) => ({
27+
path: file,
28+
source: fs.readFileSync(path.join(repoRoot, file), 'utf8'),
29+
}));
30+
}
31+
32+
export function main(): number {
33+
const files = readSources(listProductionSourceFiles());
34+
const matches = findSeamMatches(files);
35+
const { violations, staleApprovals } = checkSeams(matches, APPROVED_SEAMS);
36+
37+
if (violations.length === 0 && staleApprovals.length === 0) {
38+
process.stdout.write(
39+
`DI-seam guard: OK — ${files.length} production src/ files scanned, ` +
40+
`${APPROVED_SEAMS.length} approved seam(s) all still present, no unapproved seams.\n`,
41+
);
42+
return 0;
43+
}
44+
45+
if (violations.length > 0) {
46+
process.stderr.write(
47+
`Found ${violations.length} test-only DI seam(s) (optional typeof params) in production code:\n`,
48+
);
49+
for (const violation of violations) {
50+
process.stderr.write(` ${violation.file}:${violation.line}: ${violation.text}\n`);
51+
process.stderr.write(
52+
`::error file=${violation.file},line=${violation.line},title=Test-only DI seam::` +
53+
`${violation.text}\n`,
54+
);
55+
}
56+
process.stderr.write(
57+
'\nIf this is a deliberate, reviewed injection seam and not a leftover test seam, add it ' +
58+
'to APPROVED_SEAMS in scripts/di-seams/approved.ts with a reason for this exact site — ' +
59+
'do not broaden the pattern in model.ts to exempt it by name.\n\n',
60+
);
61+
}
62+
if (staleApprovals.length > 0) {
63+
process.stderr.write(
64+
`${staleApprovals.length} APPROVED_SEAMS entry(ies) no longer match anything in the ` +
65+
'tree (the site moved, was renamed, or was removed) — update or delete them in ' +
66+
'scripts/di-seams/approved.ts:\n',
67+
);
68+
for (const stale of staleApprovals) {
69+
process.stderr.write(` ${stale.file} :: ${stale.field} :: typeof ${stale.target}\n`);
70+
}
71+
}
72+
return 1;
73+
}
74+
75+
if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
76+
process.exit(main());
77+
}

‎scripts/di-seams/model.test.ts‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'node:test';
3+
import { checkSeams, findSeamMatches } from './model.ts';
4+
5+
test('findSeamMatches finds an optional typeof field with its line number', () => {
6+
const matches = findSeamMatches([
7+
{ path: 'a.ts', source: 'type T = {\n dispatch?: typeof dispatchCommand;\n};\n' },
8+
]);
9+
assert.deepEqual(matches, [
10+
{
11+
file: 'a.ts',
12+
line: 2,
13+
field: 'dispatch',
14+
target: 'dispatchCommand',
15+
text: 'dispatch?: typeof dispatchCommand;',
16+
},
17+
]);
18+
});
19+
20+
test('findSeamMatches ignores a required (non-optional) field', () => {
21+
const matches = findSeamMatches([
22+
{ path: 'a.ts', source: 'type T = { dispatch: typeof dispatchCommand };' },
23+
]);
24+
assert.deepEqual(matches, []);
25+
});
26+
27+
test('checkSeams passes a match whose exact (file, field, target) triple is approved', () => {
28+
const matches = findSeamMatches([{ path: 'src/x.ts', source: 'fetchImpl?: typeof fetch;' }]);
29+
const { violations, staleApprovals } = checkSeams(matches, [
30+
{ file: 'src/x.ts', field: 'fetchImpl', target: 'fetch', reason: 'test' },
31+
]);
32+
assert.deepEqual(violations, []);
33+
assert.deepEqual(staleApprovals, []);
34+
});
35+
36+
// This is the exact failure mode PR #2006's review flagged in the earlier name-based version:
37+
// approving `typeof fetch` in one file must not silently approve it everywhere.
38+
test('checkSeams flags the same field/target seam in an unapproved file', () => {
39+
const matches = findSeamMatches([{ path: 'src/y.ts', source: 'fetchImpl?: typeof fetch;' }]);
40+
const { violations } = checkSeams(matches, [
41+
{ file: 'src/x.ts', field: 'fetchImpl', target: 'fetch', reason: 'test' },
42+
]);
43+
assert.equal(violations.length, 1);
44+
assert.equal(violations[0]?.file, 'src/y.ts');
45+
});
46+
47+
test('checkSeams flags an unapproved field name in an approved file, even for an approved target', () => {
48+
const matches = findSeamMatches([{ path: 'src/x.ts', source: 'otherField?: typeof fetch;' }]);
49+
const { violations } = checkSeams(matches, [
50+
{ file: 'src/x.ts', field: 'fetchImpl', target: 'fetch', reason: 'test' },
51+
]);
52+
assert.equal(violations.length, 1);
53+
assert.equal(violations[0]?.field, 'otherField');
54+
});
55+
56+
test('checkSeams flags a seam under a different target, even for an approved field name', () => {
57+
const matches = findSeamMatches([
58+
{ path: 'src/x.ts', source: 'fetchImpl?: typeof otherFn;' },
59+
]);
60+
const { violations } = checkSeams(matches, [
61+
{ file: 'src/x.ts', field: 'fetchImpl', target: 'fetch', reason: 'test' },
62+
]);
63+
assert.equal(violations.length, 1);
64+
assert.equal(violations[0]?.target, 'otherFn');
65+
});
66+
67+
test('checkSeams reports an approval as stale when its triple matches nothing', () => {
68+
const { staleApprovals, violations } = checkSeams([], [
69+
{ file: 'src/x.ts', field: 'fetchImpl', target: 'fetch', reason: 'test' },
70+
]);
71+
assert.equal(violations.length, 0);
72+
assert.equal(staleApprovals.length, 1);
73+
assert.equal(staleApprovals[0]?.field, 'fetchImpl');
74+
});
75+
76+
test('checkSeams approves every occurrence of the same triple within a file', () => {
77+
const matches = findSeamMatches([
78+
{
79+
path: 'src/x.ts',
80+
source: 'fetchImpl?: typeof fetch;\n// ...\nfetchImpl?: typeof fetch;\n',
81+
},
82+
]);
83+
const { violations, staleApprovals } = checkSeams(matches, [
84+
{ file: 'src/x.ts', field: 'fetchImpl', target: 'fetch', reason: 'test' },
85+
]);
86+
assert.deepEqual(violations, []);
87+
assert.deepEqual(staleApprovals, []);
88+
});

‎scripts/di-seams/model.ts‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
// Detects `field?: typeof X` — the shape of a test-only DI seam (an optional parameter that
2+
// exists to let a test inject an alternate implementation). Not every match is a seam this gate
3+
// should ban: some are deliberately approved injection points, and some are unrelated `typeof
4+
// CONST` literal-type derivations that only match by syntax coincidence. See approved.ts.
5+
//
6+
// #1976 / PR #2006 review: an earlier version of this gate exempted matches by the *spelling* of
7+
// the typeof target (`typeof fetch` always passed, ALL-CAPS targets always passed). That silently
8+
// waved through a new, genuinely test-only `typeof fetch` seam anywhere in the tree while banning
9+
// an equally legitimate seam under any other name — the pattern did not actually own the
10+
// invariant it was enforcing. This module instead checks each match against an explicit,
11+
// per-site allowlist keyed by (file, field name, typeof target): a triple is exempt only if it
12+
// was individually reviewed and named, never because of how it happens to be spelled.
13+
14+
const SEAM_PATTERN = /(\w+)\?\s*:\s*typeof\s+(\w+)/g;
15+
16+
export type SourceFile = {
17+
readonly path: string;
18+
readonly source: string;
19+
};
20+
21+
export type SeamMatch = {
22+
readonly file: string;
23+
readonly line: number;
24+
readonly field: string;
25+
readonly target: string;
26+
readonly text: string;
27+
};
28+
29+
export function findSeamMatches(files: readonly SourceFile[]): SeamMatch[] {
30+
const matches: SeamMatch[] = [];
31+
for (const { path: file, source } of files) {
32+
source.split('\n').forEach((lineText, idx) => {
33+
SEAM_PATTERN.lastIndex = 0;
34+
let match: RegExpExecArray | null;
35+
while ((match = SEAM_PATTERN.exec(lineText)) !== null) {
36+
matches.push({
37+
file,
38+
line: idx + 1,
39+
field: match[1]!,
40+
target: match[2]!,
41+
text: lineText.trim(),
42+
});
43+
}
44+
});
45+
}
46+
return matches;
47+
}
48+
49+
export type ApprovedSeam = {
50+
readonly file: string;
51+
readonly field: string;
52+
readonly target: string;
53+
readonly reason: string;
54+
};
55+
56+
function seamKey(seam: { file: string; field: string; target: string }): string {
57+
return `${seam.file}::${seam.field}::${seam.target}`;
58+
}
59+
60+
export type SeamCheckResult = {
61+
readonly violations: readonly SeamMatch[];
62+
readonly staleApprovals: readonly ApprovedSeam[];
63+
};
64+
65+
/**
66+
* A match passes only if its exact (file, field, typeof-target) triple is named in `approved` —
67+
* not if its field name or target merely resembles one that is. An approval whose triple no
68+
* longer appears in `matches` is stale: the site moved, was renamed, or was deleted, so the
69+
* approval needs to follow it or be removed. Reporting that as loudly as a real violation is
70+
* what keeps the list from drifting into an allowlist for identifiers rather than sites.
71+
*/
72+
export function checkSeams(
73+
matches: readonly SeamMatch[],
74+
approved: readonly ApprovedSeam[],
75+
): SeamCheckResult {
76+
const approvedKeys = new Set(approved.map(seamKey));
77+
const seenKeys = new Set<string>();
78+
const violations: SeamMatch[] = [];
79+
for (const match of matches) {
80+
const key = seamKey(match);
81+
if (approvedKeys.has(key)) {
82+
seenKeys.add(key);
83+
} else {
84+
violations.push(match);
85+
}
86+
}
87+
const staleApprovals = approved.filter((entry) => !seenKeys.has(seamKey(entry)));
88+
return { violations, staleApprovals };
89+
}

0 commit comments

Comments
 (0)