@holmes-lab/holmes-kit 0.34.0 → 0.35.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +6 -0
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/codex-oracle.js +36 -2
  5. package/dist/holmes/cli/doctor.d.ts +14 -1
  6. package/dist/holmes/cli/doctor.js +335 -71
  7. package/dist/holmes/cli/index.d.ts +1 -1
  8. package/dist/holmes/cli/index.js +38 -5
  9. package/dist/holmes/cli/runtime-binding-approval.d.ts +7 -0
  10. package/dist/holmes/cli/runtime-binding-approval.js +102 -0
  11. package/dist/holmes/cli/runtime-binding.d.ts +29 -0
  12. package/dist/holmes/cli/runtime-binding.js +570 -0
  13. package/dist/holmes/governance/approval-queue.d.ts +2 -0
  14. package/dist/holmes/governance/approval-queue.js +11 -4
  15. package/dist/holmes/guardrail/impact-gate.js +90 -5
  16. package/dist/holmes/guardrail/linear-match.js +8 -1
  17. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -0
  18. package/dist/holmes/guardrail/risk-classifier.js +68 -23
  19. package/dist/holmes/guardrail/shell-argument-roles.d.ts +15 -0
  20. package/dist/holmes/guardrail/shell-argument-roles.js +209 -0
  21. package/dist/holmes/guardrail/shell-syntax.d.ts +20 -0
  22. package/dist/holmes/guardrail/shell-syntax.js +489 -0
  23. package/dist/holmes/guardrail/shell-words.d.ts +2 -18
  24. package/dist/holmes/guardrail/shell-words.js +67 -442
  25. package/dist/holmes/guardrail/write-target.d.ts +54 -0
  26. package/dist/holmes/guardrail/write-target.js +327 -1
  27. package/dist/holmes/hooks/pre-tool-use.d.ts +12 -0
  28. package/dist/holmes/hooks/pre-tool-use.js +377 -66
  29. package/dist/holmes/mcp/handlers/maintenance-analysis.js +4 -2
  30. package/dist/holmes/mcp/handlers/test-execution.js +6 -2
  31. package/dist/holmes/mcp/handlers.d.ts +9 -1
  32. package/dist/holmes/mcp/handlers.js +6 -4
  33. package/dist/holmes/mcp/maintenance-evidence.d.ts +16 -1
  34. package/dist/holmes/mcp/maintenance-evidence.js +29 -3
  35. package/dist/holmes/mcp/operator-recovery.d.ts +9 -0
  36. package/dist/holmes/mcp/operator-recovery.js +63 -0
  37. package/dist/holmes/rtm/test-scope.d.ts +9 -0
  38. package/dist/holmes/rtm/test-scope.js +284 -14
  39. package/dist/holmes/runtime/binding.d.ts +30 -0
  40. package/dist/holmes/runtime/binding.js +164 -0
  41. package/dist/holmes/runtime/dispatch.d.ts +9 -0
  42. package/dist/holmes/runtime/dispatch.js +169 -0
  43. package/dist/holmes/runtime/hook-process.d.ts +11 -0
  44. package/dist/holmes/runtime/hook-process.js +130 -0
  45. package/docs/install-guide.md +65 -0
  46. package/package.json +1 -1
@@ -38,7 +38,8 @@ exports.isHandlerRefusal = isHandlerRefusal;
38
38
  exports.unreadableAmong = unreadableAmong;
39
39
  exports.makeHandlers = makeHandlers;
40
40
  exports.collectDecisions = collectDecisions;
41
- // @implements A-SPEC-723, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732
41
+ // @implements A-SPEC-723, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732, A-SPEC-754
42
+ const operator_recovery_1 = require("./operator-recovery");
42
43
  // @implements A-SPEC-643
43
44
  // @implements A-SPEC-642
44
45
  // @implements A-SPEC-642
@@ -213,7 +214,7 @@ function resolveHandlerApproval(rootArg, store, envApproval, action, now) {
213
214
  const r = (0, approval_grants_1.resolveApproval)(root, envApproval, action, now);
214
215
  return r ? { ...r, root } : undefined;
215
216
  }
216
- function refusalQueueHint(rootArg, store, req) {
217
+ function refusalQueueHint(rootArg, store, req, operation) {
217
218
  try {
218
219
  // The SpecStore interface carries no root; the file-backed store exposes one. A store without a
219
220
  // root files nothing — the queue lives on disk, and with no disk location there is nothing to do.
@@ -221,7 +222,8 @@ function refusalQueueHint(rootArg, store, req) {
221
222
  const base = rootArg !== undefined ? rootArg : (typeof storeRoot === 'string' ? storeRoot : undefined);
222
223
  if (base === undefined)
223
224
  return '';
224
- return (0, approval_queue_1.queueHint)(projectRootOf(base), req);
225
+ const root = projectRootOf(base);
226
+ return (0, approval_queue_1.queueHint)(root, req, (0, operator_recovery_1.operatorRecovery)(root, req.target, operation));
225
227
  }
226
228
  catch {
227
229
  return '';
@@ -873,7 +875,7 @@ function makeRawHandlers(store, opts) {
873
875
  prepareHostApproval,
874
876
  consumeHostApproval,
875
877
  resolveHandlerApproval: (root, approval, action, now) => resolveHandlerApproval(root, store, approval, action, now),
876
- refusalQueueHint: (root, request) => refusalQueueHint(root, store, request),
878
+ refusalQueueHint: (root, request) => refusalQueueHint(root, store, request, 'spec_approve'),
877
879
  foreignRootReason: (root) => foreignRootReason(store, root),
878
880
  });
879
881
  /**
@@ -77,6 +77,18 @@ export interface EvidenceArtifact {
77
77
  compatibilityAssessed: boolean;
78
78
  };
79
79
  outcome?: EvidenceOutcome;
80
+ /**
81
+ * @implements A-SPEC-278.3 — what the caller asked and which files it said it would change. The pre-edit gate covers a
82
+ * new file the request names (A-SPEC-278.2), which it could not do while the artifact kept no request. Optional: older
83
+ * artifacts read as before.
84
+ */
85
+ request?: string;
86
+ changedFiles?: string[];
87
+ }
88
+ /** What the caller supplied to the analysis, recorded beside the prediction (A-SPEC-278.3). */
89
+ export interface AnalysisIntake {
90
+ request?: string;
91
+ changedFiles?: string[];
80
92
  }
81
93
  /**
82
94
  * A digest reaches the filesystem as a filename, and it arrives from an MCP caller. Refuse anything
@@ -84,8 +96,11 @@ export interface EvidenceArtifact {
84
96
  * turn "record an outcome" into an arbitrary-path write.
85
97
  */
86
98
  export declare function digestFilename(digest: string): string;
99
+ /** A-SPEC-278.3 bounds: the request is free text from the caller, and the list is whatever it passed. */
100
+ export declare const INTAKE_REQUEST_MAX = 4096;
101
+ export declare const INTAKE_CHANGED_FILES_MAX = 512;
87
102
  /** Project an analysis into the durable prediction record. Pure: the caller supplies the clock. */
88
- export declare function artifactFrom(analysis: MaintenanceAnalysis, recordedAt: string, fileDigests?: Record<string, string>): EvidenceArtifact;
103
+ export declare function artifactFrom(analysis: MaintenanceAnalysis, recordedAt: string, fileDigests?: Record<string, string>, intake?: AnalysisIntake): EvidenceArtifact;
89
104
  /**
90
105
  * Persist an artifact, addressed by its digest. Re-running the same analysis is a re-run, not a
91
106
  * reason to forget what actually happened, so an outcome already recorded at this digest survives.
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.EVIDENCE_DIR = exports.EVIDENCE_ARTIFACT_SCHEMA = void 0;
36
+ exports.INTAKE_CHANGED_FILES_MAX = exports.INTAKE_REQUEST_MAX = exports.EVIDENCE_DIR = exports.EVIDENCE_ARTIFACT_SCHEMA = void 0;
37
37
  exports.digestFilename = digestFilename;
38
38
  exports.artifactFrom = artifactFrom;
39
39
  exports.writeArtifact = writeArtifact;
@@ -43,7 +43,7 @@ exports.openArtifacts = openArtifacts;
43
43
  exports.closeOpenArtifacts = closeOpenArtifacts;
44
44
  exports.scopeCauses = scopeCauses;
45
45
  exports.computeCalibration = computeCalibration;
46
- // @implements A-SPEC-744, A-SPEC-740, A-SPEC-724.1, A-SPEC-271
46
+ // @implements A-SPEC-744, A-SPEC-740, A-SPEC-724.1, A-SPEC-271, A-SPEC-278.3
47
47
  // @implements A-SPEC-268
48
48
  const fs = __importStar(require("node:fs"));
49
49
  const path = __importStar(require("node:path"));
@@ -76,9 +76,35 @@ function digestFilename(digest) {
76
76
  function sortedUnique(values) {
77
77
  return [...new Set(values)].sort((a, b) => a.localeCompare(b));
78
78
  }
79
+ /** A-SPEC-278.3 bounds: the request is free text from the caller, and the list is whatever it passed. */
80
+ exports.INTAKE_REQUEST_MAX = 4096;
81
+ exports.INTAKE_CHANGED_FILES_MAX = 512;
82
+ /** Repository-relative and `/`-separated, as the gate compares them; at most INTAKE_CHANGED_FILES_MAX entries. */
83
+ function intakeRecord(intake) {
84
+ if (!intake)
85
+ return {};
86
+ const out = {};
87
+ if (typeof intake.request === 'string')
88
+ out.request = intake.request.slice(0, exports.INTAKE_REQUEST_MAX);
89
+ if (Array.isArray(intake.changedFiles)) {
90
+ const files = [];
91
+ for (const raw of intake.changedFiles) {
92
+ if (typeof raw !== 'string')
93
+ continue;
94
+ const rel = raw.replace(/\\/g, '/').replace(/^(?:\.\/)+/, '');
95
+ if (rel !== '' && !files.includes(rel))
96
+ files.push(rel);
97
+ if (files.length === exports.INTAKE_CHANGED_FILES_MAX)
98
+ break;
99
+ }
100
+ out.changedFiles = files;
101
+ }
102
+ return out;
103
+ }
79
104
  /** Project an analysis into the durable prediction record. Pure: the caller supplies the clock. */
80
- function artifactFrom(analysis, recordedAt, fileDigests = {}) {
105
+ function artifactFrom(analysis, recordedAt, fileDigests = {}, intake) {
81
106
  return {
107
+ ...intakeRecord(intake),
82
108
  artifactSchema: exports.EVIDENCE_ARTIFACT_SCHEMA,
83
109
  digest: analysis.evidenceDigest,
84
110
  recordedAt,
@@ -0,0 +1,9 @@
1
+ /** Formatting only: the caller must return pending text only after a successful enqueue. */
2
+ export declare function operatorRecovery(root: string, target: string, operation?: string, options?: {
3
+ platform?: NodeJS.Platform;
4
+ executable?: string;
5
+ cli?: string;
6
+ }): {
7
+ reviewCommand: string;
8
+ pendingHint(id: string): string;
9
+ };
@@ -0,0 +1,63 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.operatorRecovery = operatorRecovery;
37
+ // @implements A-SPEC-754
38
+ const path = __importStar(require("node:path"));
39
+ const unsafeDisplay = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
40
+ function literal(value, platform) {
41
+ return platform === 'win32' ? `'${value.replace(/'/g, "''")}'` : `'${value.replace(/'/g, `'\\''`)}'`;
42
+ }
43
+ /** Formatting only: the caller must return pending text only after a successful enqueue. */
44
+ function operatorRecovery(root, target, operation, options) {
45
+ const platform = options?.platform ?? process.platform;
46
+ const executable = options?.executable ?? process.execPath;
47
+ // Both src/holmes/mcp (tests) and dist/holmes/mcp (installed) have the same depth.
48
+ const cli = options?.cli ?? path.resolve(__dirname, '../../..', 'bin/holmes-kit.js');
49
+ const commandSafe = [root, executable, cli].every(value => value.length > 0 && value.length <= 2048 && !unsafeDisplay.test(value));
50
+ const command = commandSafe ? `${platform === 'win32' ? '& ' : ''}${literal(executable, platform)} ${literal(cli, platform)} approve --target ${literal(root, platform)}` : '';
51
+ const display = (value) => JSON.stringify(value.slice(0, 300)).replace(/[\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
52
+ return {
53
+ reviewCommand: command || 'the installed Holmes-Kit approval UI (path cannot be safely displayed; no command emitted)',
54
+ pendingHint(id) {
55
+ if (!/^req-[a-f0-9]{12}$/.test(id))
56
+ return '';
57
+ if (!command)
58
+ return `\n[승인 대기 ${id}] The request was recorded. Use the installed approval UI; a path exceeds the safe command display limit. No truncated command is provided.`;
59
+ return `\n[승인 대기 ${id}] 운영자: ${command} --grant ${literal(id, platform)}`
60
+ + `\nAfter official approval, retry ${operation ? display(operation) : 'the original MCP operation'} for target ${display(target)} in the same workspace. Do not retry until approval is available.`;
61
+ },
62
+ };
63
+ }
@@ -115,6 +115,15 @@ export declare function accountChangedFiles(changedFiles: string[], scanEntry: (
115
115
  implementsSpecs: string[];
116
116
  symbolCount: number;
117
117
  } | undefined): ChangedFileAccount;
118
+ /**
119
+ * @implements A-SPEC-750 — one left-to-right pass over source, replacing the regex passes that stripped comments, then
120
+ * strings, in sequence (a `/*`, `//` or backtick inside a literal began a comment or a template there and swallowed the
121
+ * real case heads up to the next closer — measured 2026-10-01: 72 test files counted fewer cases than Jest ran).
122
+ * Strings become `""`, a template keeps only its `${…}` code, comments become a space, and (when `js`) a regex literal
123
+ * becomes `/x/`. A failed regex attempt disables attempts until the end of that line, so a long line costs one pass.
124
+ * Without `js`, a backtick string is a raw string with no interpolation and `/` is never a regex.
125
+ */
126
+ export declare function stripCode(src: string, js: boolean): string;
118
127
  /** Frameworks this counter understands, for diagnostics and tests. */
119
128
  export declare const SUPPORTED_TEST_FRAMEWORKS: string[];
120
129
  export declare function countTestCases(source: string, filePath?: string): number;
@@ -36,11 +36,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.SUPPORTED_TEST_FRAMEWORKS = void 0;
37
37
  exports.architectureGoverningFiles = architectureGoverningFiles;
38
38
  exports.accountChangedFiles = accountChangedFiles;
39
+ exports.stripCode = stripCode;
39
40
  exports.countTestCases = countTestCases;
40
41
  exports.extractAnchors = extractAnchors;
41
42
  exports.scanTestAnchors = scanTestAnchors;
42
43
  exports.computeTestScope = computeTestScope;
43
- // @implements A-SPEC-121.2, A-SPEC-734
44
+ // @implements A-SPEC-121.2, A-SPEC-734, A-SPEC-750
44
45
  const anchor_ids_1 = require("./anchor-ids");
45
46
  const fs = __importStar(require("node:fs"));
46
47
  const path = __importStar(require("node:path"));
@@ -143,11 +144,282 @@ function accountChangedFiles(changedFiles, scanEntry) {
143
144
  * wrappers or aliasing can still fabricate heads. Execution proof is the test RUNNER's job
144
145
  * (planTestRun/runTestScope); this counter only stops declared coverage over an absent/empty suite.
145
146
  */
146
- /** Strip block/line comments and string literals from C-family source. */
147
- const stripCFamily = (src) => src
148
- .replace(/\/\*[\s\S]*?\*\//g, ' ') // block comments
149
- .replace(/(^|[^:])\/\/[^\n]*/g, '$1 ') // line comments (not ://)
150
- .replace(/'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\])*`/g, '""');
147
+ /** Keywords after which a `/` starts a regex literal rather than a division. */
148
+ const REGEX_AFTER_KEYWORD = new Set(['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'throw', 'case', 'do',
149
+ 'else', 'yield', 'await']);
150
+ // Character classes by code: a regex test per character made the lexer seven times slower than the regex counter it
151
+ // replaces (measured 2026-10-02: 170 ms against 25 ms over the 648-file tree).
152
+ const isIdentStart = (cc) => (cc >= 97 && cc <= 122) || (cc >= 65 && cc <= 90) || cc === 95 || cc === 36 || cc > 127;
153
+ const isIdentPart = (cc) => isIdentStart(cc) || (cc >= 48 && cc <= 57);
154
+ const isSpace = (cc) => cc === 32 || cc === 10 || cc === 9 || cc === 13 || cc === 11 || cc === 12 || cc === 160;
155
+ const PLAIN_RUN = /[^/'"`{}]+/y;
156
+ /** Whether a `/` after the run src[from, to) may start a regex: by the run's last significant token, else `prev`. */
157
+ function regexOkAfterRun(src, from, to, prev) {
158
+ let k = to - 1;
159
+ while (k >= from && isSpace(src.charCodeAt(k)))
160
+ k--;
161
+ if (k < from)
162
+ return prev;
163
+ const cc = src.charCodeAt(k);
164
+ if (cc === 41 || cc === 93)
165
+ return false;
166
+ if (!isIdentPart(cc))
167
+ return true;
168
+ let w = k;
169
+ while (w > from && isIdentPart(src.charCodeAt(w - 1)))
170
+ w--;
171
+ const first = src.charCodeAt(w);
172
+ if (first >= 48 && first <= 57)
173
+ return false;
174
+ // Only a short word can be a keyword: slicing every identifier would cost more than the whole lexer.
175
+ return k - w < 10 && REGEX_AFTER_KEYWORD.has(src.slice(w, k + 1));
176
+ }
177
+ /** Index just past a quoted string starting at `i`; a string ends at its quote or at a newline. */
178
+ function endOfQuoted(src, i, quote) {
179
+ for (let j = i + 1; j < src.length; j++) {
180
+ const ch = src[j];
181
+ if (ch === '\\') {
182
+ j++;
183
+ continue;
184
+ }
185
+ if (ch === quote)
186
+ return j + 1;
187
+ if (ch === '\n')
188
+ return j;
189
+ }
190
+ return src.length;
191
+ }
192
+ /** From inside a template, the index after its closing backtick, or after the next `${` (interp = true). */
193
+ function scanTemplate(src, j) {
194
+ for (; j < src.length; j++) {
195
+ const ch = src[j];
196
+ if (ch === '\\') {
197
+ j++;
198
+ continue;
199
+ }
200
+ if (ch === '`')
201
+ return { next: j + 1, interp: false };
202
+ if (ch === '$' && src[j + 1] === '{')
203
+ return { next: j + 2, interp: true };
204
+ }
205
+ return { next: src.length, interp: false };
206
+ }
207
+ /** Index just past a regex literal starting at `i`, or -1 when none closes before the line ends. */
208
+ function endOfRegex(src, i) {
209
+ let inClass = false;
210
+ for (let j = i + 1; j < src.length; j++) {
211
+ const ch = src[j];
212
+ if (ch === '\n' || ch === '\r')
213
+ return -1;
214
+ if (ch === '\\') {
215
+ j++;
216
+ continue;
217
+ }
218
+ if (ch === '[')
219
+ inClass = true;
220
+ else if (ch === ']')
221
+ inClass = false;
222
+ else if (ch === '/' && !inClass) {
223
+ let k = j + 1;
224
+ while (k < src.length && /[A-Za-z]/.test(src[k]))
225
+ k++;
226
+ return k;
227
+ }
228
+ }
229
+ return -1;
230
+ }
231
+ /**
232
+ * @implements A-SPEC-750 — one left-to-right pass over source, replacing the regex passes that stripped comments, then
233
+ * strings, in sequence (a `/*`, `//` or backtick inside a literal began a comment or a template there and swallowed the
234
+ * real case heads up to the next closer — measured 2026-10-01: 72 test files counted fewer cases than Jest ran).
235
+ * Strings become `""`, a template keeps only its `${…}` code, comments become a space, and (when `js`) a regex literal
236
+ * becomes `/x/`. A failed regex attempt disables attempts until the end of that line, so a long line costs one pass.
237
+ * Without `js`, a backtick string is a raw string with no interpolation and `/` is never a regex.
238
+ */
239
+ function stripCode(src, js) {
240
+ const out = [];
241
+ const n = src.length;
242
+ let i = 0;
243
+ let start = 0;
244
+ let regexOk = true;
245
+ let regexOffUntil = -1;
246
+ const interp = [];
247
+ const emit = (text, next) => { out.push(src.slice(start, i), text); i = next; start = next; };
248
+ const template = (from, lead) => {
249
+ const t = scanTemplate(src, from);
250
+ if (t.interp) {
251
+ emit(lead + '${', t.next);
252
+ interp.push(0);
253
+ regexOk = true;
254
+ }
255
+ else {
256
+ emit(lead + '`', t.next);
257
+ regexOk = false;
258
+ }
259
+ };
260
+ while (i < n) {
261
+ const c = src[i];
262
+ if (c === '/' && src[i + 1] === '/') {
263
+ const e = src.indexOf('\n', i);
264
+ emit(' ', e < 0 ? n : e);
265
+ continue;
266
+ }
267
+ if (c === '/' && src[i + 1] === '*') {
268
+ const e = src.indexOf('*/', i + 2);
269
+ emit(' ', e < 0 ? n : e + 2);
270
+ continue;
271
+ }
272
+ if (c === '"' || c === "'") {
273
+ emit('""', endOfQuoted(src, i, c));
274
+ regexOk = false;
275
+ continue;
276
+ }
277
+ if (c === '`') {
278
+ if (js) {
279
+ template(i + 1, '`');
280
+ continue;
281
+ }
282
+ let j = i + 1;
283
+ while (j < n && src[j] !== '`')
284
+ j += src[j] === '\\' ? 2 : 1;
285
+ emit('""', Math.min(n, j + 1));
286
+ regexOk = false;
287
+ continue;
288
+ }
289
+ if (js && c === '}' && interp.length > 0 && interp[interp.length - 1] === 0) {
290
+ interp.pop();
291
+ template(i + 1, '}');
292
+ continue;
293
+ }
294
+ if (js && c === '/' && regexOk && i >= regexOffUntil) {
295
+ const e = endOfRegex(src, i);
296
+ if (e > 0) {
297
+ emit('/x/', e);
298
+ regexOk = false;
299
+ continue;
300
+ }
301
+ const nl = src.indexOf('\n', i);
302
+ regexOffUntil = nl < 0 ? n : nl;
303
+ i++;
304
+ regexOk = true;
305
+ continue;
306
+ }
307
+ // Everything but the six characters that open or close a literal, a comment or a brace is copied as one run; only
308
+ // its last significant token matters, for whether a following `/` may start a regex.
309
+ PLAIN_RUN.lastIndex = i;
310
+ if (PLAIN_RUN.test(src)) {
311
+ const j = PLAIN_RUN.lastIndex;
312
+ regexOk = regexOkAfterRun(src, i, j, regexOk);
313
+ i = j;
314
+ continue;
315
+ }
316
+ if (c === '{' && interp.length > 0)
317
+ interp[interp.length - 1]++;
318
+ else if (c === '}' && interp.length > 0)
319
+ interp[interp.length - 1]--;
320
+ regexOk = true;
321
+ i++;
322
+ }
323
+ out.push(src.slice(start, n));
324
+ return out.join('');
325
+ }
326
+ /** Index after spaces, tabs and newlines. */
327
+ function skipSpace(code, j) {
328
+ while (j < code.length && /\s/.test(code[j]))
329
+ j++;
330
+ return j;
331
+ }
332
+ /** Index just past the group opened at `j` (`(`, `[`, `{` or a stripped template), or the end of the code. */
333
+ function skipGroup(code, j) {
334
+ if (code[j] === '`') {
335
+ for (j++; j < code.length; j++) {
336
+ if (code[j] === '`')
337
+ return j + 1;
338
+ if (code[j] === '$' && code[j + 1] === '{')
339
+ j = skipGroup(code, j + 1) - 1;
340
+ }
341
+ return code.length;
342
+ }
343
+ let depth = 0;
344
+ for (; j < code.length; j++) {
345
+ const ch = code[j];
346
+ if (ch === '`') {
347
+ j = skipGroup(code, j) - 1;
348
+ continue;
349
+ }
350
+ if (ch === '(' || ch === '[' || ch === '{')
351
+ depth++;
352
+ else if (ch === ')' || ch === ']' || ch === '}') {
353
+ if (--depth === 0)
354
+ return j + 1;
355
+ }
356
+ }
357
+ return code.length;
358
+ }
359
+ const JEST_HEADS = ['it', 'test', 'fit'];
360
+ // @implements A-SPEC-653 — the platform helpers of A-SPEC-220.3 (`posixOnly('why')(…)`) are heads too: a POSIX-only suite
361
+ // written with the REPORTING skip must not read as "no real cases". `.skip` on a helper is still not a head.
362
+ const JEST_HELPERS = new Set(['posixOnly', 'posixOnlyNonRoot', 'posixOnlyWithCommand', 'win32Only']);
363
+ // @implements A-SPEC-750 — searched in the stripped CODE: a skip token inside a string or a comment (this counter's own tests
364
+ // hold several) no longer forfeits the file; one in code, including an alias line or any computed access, still does.
365
+ const JEST_SUITE_SKIP = /(?<![\w$.])describe\s*(?:\.\s*skip(?![\w$])|\[)|(?<![\w$])xdescribe(?![\w$])/;
366
+ const JEST_ALIAS_HINT = /=\s*(?:it|test|fit|posixOnly|posixOnlyNonRoot|posixOnlyWithCommand|win32Only)(?![\w$])/;
367
+ const JEST_ALIAS = /(?<![\w$.])(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]*)?=\s*(it|test|fit|posixOnly|posixOnlyNonRoot|posixOnlyWithCommand|win32Only)(?![\w$])/g;
368
+ /**
369
+ * Jest cases in stripped code: a standalone `it|test|fit` (or a same-file alias of one, or of a platform helper call)
370
+ * followed by `(`, or by `.each(…)(` / `.each` + template + `(`. Method calls (`re.test(`) never match: the head must not
371
+ * follow a `.`. `it.skip(`/`it.todo(`/`xit(` never match, so nothing is subtracted.
372
+ */
373
+ function jestCount(code) {
374
+ if (JEST_SUITE_SKIP.test(code))
375
+ return 0;
376
+ const direct = new Set(JEST_HEADS);
377
+ // Most files bind no alias; the declaration scan below visits every `const`, so it runs only when an alias can exist.
378
+ if (JEST_ALIAS_HINT.test(code))
379
+ for (const m of code.matchAll(JEST_ALIAS)) {
380
+ let j = m.index + m[0].length;
381
+ if (JEST_HELPERS.has(m[2])) {
382
+ j = skipSpace(code, j);
383
+ if (code[j] !== '(')
384
+ continue;
385
+ j = skipGroup(code, j);
386
+ }
387
+ while (j < code.length && (code[j] === ' ' || code[j] === '\t'))
388
+ j++;
389
+ if (j >= code.length || ';,\n\r}'.includes(code[j]))
390
+ direct.add(m[1]);
391
+ }
392
+ const names = [...direct, ...[...JEST_HELPERS].filter((h) => !direct.has(h))].map((s) => s.replace(/\$/g, '\\$'));
393
+ let cases = 0;
394
+ for (const m of code.matchAll(new RegExp(`(?<![\\w$.])(?:${names.join('|')})(?![\\w$])`, 'g'))) {
395
+ let j = m.index + m[0].length;
396
+ if (!direct.has(m[0])) {
397
+ j = skipSpace(code, j);
398
+ if (code[j] !== '(')
399
+ continue;
400
+ j = skipGroup(code, j);
401
+ }
402
+ j = skipSpace(code, j);
403
+ if (code[j] === '(') {
404
+ cases++;
405
+ continue;
406
+ }
407
+ if (code[j] !== '.')
408
+ continue;
409
+ let k = skipSpace(code, j + 1);
410
+ if (!code.startsWith('each', k) || /[\w$]/.test(code[k + 4] ?? ''))
411
+ continue;
412
+ k = skipSpace(code, k + 4);
413
+ if (code[k] !== '(' && code[k] !== '`')
414
+ continue;
415
+ k = skipSpace(code, skipGroup(code, k));
416
+ if (code[k] === '(')
417
+ cases++;
418
+ }
419
+ return cases;
420
+ }
421
+ /** Strip block/line comments and string literals from C-family source (no regex literals, no interpolation). */
422
+ const stripCFamily = (src) => stripCode(src, false);
151
423
  /** Strip `#` comments, docstrings and string literals from Python source. */
152
424
  const stripPython = (src) => src
153
425
  .replace(/'''[\s\S]*?'''|"""[\s\S]*?"""/g, '""') // docstrings first — they may contain #
@@ -168,14 +440,10 @@ const FRAMEWORKS = [
168
440
  {
169
441
  id: 'jest',
170
442
  ext: /\.(ts|mts|cts|tsx|jsx|js|mjs|cjs)$/i,
171
- strip: stripCFamily,
172
- suiteSkip: /\bdescribe\s*(?:\.\s*skip|\[\s*['"]skip['"]\s*\])|\bxdescribe\b/,
173
- // Head must be a STANDALONE identifier (not `.test(`/`.it(` method calls) followed directly by
174
- // `(` or by `.each(...)(`: `it.skip(`/`it.todo(`/`xit(` never match — no subtraction needed.
175
- // @implements A-SPEC-653 — the platform helpers of A-SPEC-220.3 (`posixOnly('why')(…)`) are heads too:
176
- // a POSIX-only suite written with the REPORTING skip must not read as "no real cases" (measured: that
177
- // is why two suites had used a bare early return instead). `.skip` on a helper is still not a head.
178
- head: /(?<![.\w])(?:it|test|fit|(?:posixOnly|posixOnlyNonRoot|posixOnlyWithCommand|win32Only)\s*\([^)]*\))(?:\s*\.\s*each\s*\([^)]*\)\s*)?\s*\(/g,
443
+ strip: (src) => stripCode(src, true),
444
+ suiteSkip: JEST_SUITE_SKIP,
445
+ head: /(?!)/g,
446
+ count: (src) => jestCount(stripCode(src, true)),
179
447
  },
180
448
  {
181
449
  id: 'pytest',
@@ -246,6 +514,8 @@ const ruleFor = (filePath) => (filePath && FRAMEWORKS.find((f) => f.ext.test(fil
246
514
  exports.SUPPORTED_TEST_FRAMEWORKS = FRAMEWORKS.map((f) => f.id);
247
515
  function countTestCases(source, filePath) {
248
516
  const rule = ruleFor(filePath);
517
+ if (rule.count)
518
+ return rule.count(source);
249
519
  const stripped = rule.strip(source);
250
520
  // Suite-skip detection runs on the ORIGINAL source: string-stripping turns `describe['skip'](`
251
521
  // into `describe[""](`, hiding the marker (round-2 test caught this). Comments are already
@@ -0,0 +1,30 @@
1
+ export interface RuntimeRegistry {
2
+ version: 1;
3
+ releasePackageRoot: string;
4
+ bindings: {
5
+ workspaceRoot: string;
6
+ packageRoot: string;
7
+ }[];
8
+ }
9
+ export interface RuntimeSelection {
10
+ mode: 'development' | 'release';
11
+ workspaceRoot: string;
12
+ packageRoot: string;
13
+ buildId: string;
14
+ specsRoot: string;
15
+ }
16
+ export type RuntimeHarness = 'claude' | 'codex' | 'antigravity';
17
+ export type RuntimeEntry = 'mcp' | 'pre-tool-use' | 'stop';
18
+ export declare const RUNTIME_ENTRIES: string[];
19
+ export declare function readBounded(file: string, max?: number): string;
20
+ export declare function canonicalDirectory(value: string): string;
21
+ export declare function workspaceRoot(cwd: string): string;
22
+ export declare function inside(root: string, target: string): boolean;
23
+ export declare function validateRegistry(input: unknown): RuntimeRegistry;
24
+ export declare function readRuntimeRegistry(file: string): RuntimeRegistry;
25
+ export declare function verifyRuntime(packageRoot: string): string;
26
+ export declare function selectRuntime(registry: RuntimeRegistry, context: {
27
+ cwd: string;
28
+ workspaceHints?: string[];
29
+ specsHint?: string;
30
+ }): RuntimeSelection;