1
+import * as fs from 'node:fs';
2
+import * as path from 'node:path';
3
+
4
+export interface CommandTestExemption {
5
+ readonly command: string;
6
+ readonly reason: string;
7
+}
8
+
9
+export interface CommandTestInputs {
10
+ readonly commands: readonly string[];
11
+ readonly tests: readonly string[];
12
+ readonly exemptions: readonly CommandTestExemption[];
13
+}
14
+
15
+const COMMAND_SUFFIX = '.cmd.ts';
16
+const TEST_SUFFIX = '.cmd.test.ts';
17
+
18
+// Command paths are relative to src/commands/; tests are relative to
19
+// test/src/commands/. Both use forward slashes.
20
+export const COMMAND_TEST_EXEMPTIONS: readonly CommandTestExemption[] = [
21
+ { command: 'agent/commands/agent.claim.cmd.ts', reason: 'no test yet' },
22
+ { command: 'agent/commands/agent.inbox.cmd.ts', reason: 'no test yet' },
23
+ { command: 'agent/commands/agent.login.cmd.ts', reason: 'no test yet' },
24
+ { command: 'agent/commands/agent.signup.cmd.ts', reason: 'no test yet' },
25
+ { command: 'agent/commands/agent.whoami.cmd.ts', reason: 'no test yet' },
26
+ { command: 'artifacts.cmd.ts', reason: 'no test yet' },
27
+ { command: 'connections/commands/connections.remove.cmd.ts', reason: 'no test yet' },
28
+ { command: 'debug.cmd.ts', reason: 'no test yet' },
29
+ {
30
+ command: 'generate/generate.py.cmd.ts',
31
+ reason: 'thin wrapper over py.generate; covered by py/py.generate.cmd.test.ts',
32
+ },
33
+ {
34
+ command: 'generate/generate.ts.cmd.ts',
35
+ reason: 'thin wrapper over ts.generate; covered by ts/ts.generate.cmd.test.ts',
36
+ },
37
+ {
38
+ command: 'logs/commands/logs.triggers.cmd.ts',
39
+ reason: 'covered by logs.triggers.client.cmd.test.ts; split pending',
40
+ },
41
+ { command: 'orgs/commands/orgs.list.cmd.ts', reason: 'no test yet' },
42
+ { command: 'signup.cmd.ts', reason: 'no test yet' },
43
+ {
44
+ command: 'triggers/commands/triggers.create.cmd.ts',
45
+ reason: 'covered by triggers.mutations.cmd.test.ts; split pending',
46
+ },
47
+ {
48
+ command: 'triggers/commands/triggers.disable.cmd.ts',
49
+ reason: 'covered by triggers.mutations.cmd.test.ts; split pending',
50
+ },
51
+ {
52
+ command: 'triggers/commands/triggers.enable.cmd.ts',
53
+ reason: 'covered by triggers.mutations.cmd.test.ts; split pending',
54
+ },
55
+ { command: 'triggers/commands/triggers.listen.cmd.ts', reason: 'no test yet' },
56
+ { command: 'upgrade.cmd.ts', reason: 'no test yet' },
57
+];
58
+
59
+// A group entry is `<dir>.cmd.ts` or `root-<dir>.cmd.ts` inside `<dir>/` when
60
+// `<dir>/` holds other command modules; it only wires subcommands and is
61
+// covered by root-help-consistency.test.ts. The same name with nothing below
62
+// it is a top-level command in the per-command directory shape
63
+// (`login/login.cmd.ts`).
64
+export const isGroupEntry = (command: string, commands: readonly string[]): boolean => {
65
+ const segments = command.split('/');
66
+ const dir = segments.at(-2);
67
+ const base = segments.at(-1);
68
+ if (dir === undefined || base === undefined) return false;
69
+ if (base !== `${dir}${COMMAND_SUFFIX}` && base !== `root-${dir}${COMMAND_SUFFIX}`) return false;
70
+ const prefix = `${segments.slice(0, -1).join('/')}/`;
71
+ return commands.some(other => other !== command && other.startsWith(prefix));
72
+};
73
+
74
+export const mirroredTestPath = (command: string): string =>
75
+ command
76
+ .split('/')
77
+ .filter(segment => segment !== 'commands')
78
+ .join('/')
79
+ .replace(/\.cmd\.ts$/, TEST_SUFFIX);
80
+
81
+// Resolves a test to the command it exercises: the longest dotted prefix of
82
+// its basename that names a `<prefix>.cmd.ts` anywhere under src/commands/.
83
+// Extra segments name a test aspect (`setup.telemetry`, `tools.execute.client`).
84
+export const resolveTestCommand = (
85
+ test: string,
86
+ commands: readonly string[]
87
+): string | undefined => {
88
+ const base = path.posix.basename(test, TEST_SUFFIX);
89
+ const byBasename = new Map(commands.map(command => [path.posix.basename(command), command]));
90
+ const parts = base.split('.');
91
+ for (let length = parts.length; length > 0; length--) {
92
+ const match = byBasename.get(`${parts.slice(0, length).join('.')}${COMMAND_SUFFIX}`);
93
+ if (match !== undefined) return match;
94
+ }
95
+ return undefined;
96
+};
97
+
98
+export const checkCommandTests = ({
99
+ commands,
100
+ tests,
101
+ exemptions,
102
+}: CommandTestInputs): readonly string[] => {
103
+ const errors: string[] = [];
104
+ const testSet = new Set(tests);
105
+ const commandSet = new Set(commands);
106
+ const exempted = new Map(exemptions.map(exemption => [exemption.command, exemption]));
107
+
108
+ for (const exemption of exemptions) {
109
+ if (!commandSet.has(exemption.command)) {
110
+ errors.push(
111
+ `stale exemption: ${exemption.command} is not a command under src/commands/; remove it from COMMAND_TEST_EXEMPTIONS.`
112
+ );
113
+ } else if (isGroupEntry(exemption.command, commands)) {
114
+ errors.push(
115
+ `stale exemption: ${exemption.command} is a group entry and needs no test; remove it from COMMAND_TEST_EXEMPTIONS.`
116
+ );
117
+ }
118
+ }
119
+
120
+ for (const command of [...commands].sort()) {
121
+ if (isGroupEntry(command, commands)) continue;
122
+ const expected = mirroredTestPath(command);
123
+ const hasTest = testSet.has(expected);
124
+ if (exempted.has(command)) {
125
+ if (hasTest) {
126
+ errors.push(
127
+ `stale exemption: ${command} now has test/src/commands/${expected}; remove it from COMMAND_TEST_EXEMPTIONS.`
128
+ );
129
+ }
130
+ } else if (!hasTest) {
131
+ errors.push(`missing test: src/commands/${command} needs test/src/commands/${expected}.`);
132
+ }
133
+ }
134
+
135
+ for (const test of [...tests].sort()) {
136
+ if (resolveTestCommand(test, commands) === undefined) {
137
+ errors.push(
138
+ `orphan test: test/src/commands/${test} matches no <prefix>.cmd.ts under src/commands/.`
139
+ );
140
+ }
141
+ }
142
+
143
+ return errors;
144
+};
145
+
146
+const listFiles = (root: string, suffix: string): string[] =>
147
+ fs
148
+ .readdirSync(root, { recursive: true, encoding: 'utf8' })
149
+ .filter(file => file.endsWith(suffix) && fs.statSync(path.join(root, file)).isFile())
150
+ .map(file => file.split(path.sep).join('/'))
151
+ .sort();
152
+
153
+export const collectCommandTests = (
154
+ packageRoot: string
155
+): { readonly commands: readonly string[]; readonly tests: readonly string[] } => ({
156
+ commands: listFiles(path.join(packageRoot, 'src', 'commands'), COMMAND_SUFFIX),
157
+ tests: listFiles(path.join(packageRoot, 'test', 'src', 'commands'), TEST_SUFFIX),
158
+});