@holmes-lab/holmes-kit 0.40.0 → 0.41.0

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 (119) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/README.md +79 -5
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-context.js +4 -3
  5. package/dist/holmes/cli/approve.js +22 -12
  6. package/dist/holmes/cli/autonomy.d.ts +21 -0
  7. package/dist/holmes/cli/autonomy.js +35 -5
  8. package/dist/holmes/cli/doctor.js +58 -6
  9. package/dist/holmes/cli/index.js +394 -267
  10. package/dist/holmes/cli/init.js +17 -6
  11. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  12. package/dist/holmes/cli/interactive-prompt.js +98 -16
  13. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  14. package/dist/holmes/cli/ledger-witness.js +212 -0
  15. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  16. package/dist/holmes/cli/playbook-skills.js +26 -349
  17. package/dist/holmes/config/config.d.ts +21 -0
  18. package/dist/holmes/config/config.js +22 -3
  19. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  20. package/dist/holmes/governance/approval-queue.js +279 -9
  21. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  22. package/dist/holmes/governance/autonomous-shell.js +157 -4
  23. package/dist/holmes/governance/autonomy.d.ts +216 -0
  24. package/dist/holmes/governance/autonomy.js +1162 -10
  25. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  26. package/dist/holmes/governance/install-manifest.js +144 -14
  27. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  28. package/dist/holmes/governance/ledger-witness.js +296 -0
  29. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  30. package/dist/holmes/governance/provenance-chain.js +23 -4
  31. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  32. package/dist/holmes/governance/push-gate-runner.js +40 -3
  33. package/dist/holmes/governance/push-gate.d.ts +13 -2
  34. package/dist/holmes/governance/push-gate.js +106 -14
  35. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  36. package/dist/holmes/governance/recorded-pairs.js +25 -1
  37. package/dist/holmes/governance/session-context.d.ts +7 -0
  38. package/dist/holmes/governance/session-context.js +34 -6
  39. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  40. package/dist/holmes/guardrail/advisory-line.js +718 -0
  41. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  42. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  43. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  44. package/dist/holmes/guardrail/command-traits.js +379 -0
  45. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  46. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  47. package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
  48. package/dist/holmes/guardrail/impact-gate.js +32 -5
  49. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  50. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  51. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  52. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  53. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  54. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  55. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  56. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  57. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  58. package/dist/holmes/guardrail/write-target.js +7 -1
  59. package/dist/holmes/hooks/pre-tool-use.d.ts +71 -0
  60. package/dist/holmes/hooks/pre-tool-use.js +1466 -14
  61. package/dist/holmes/hooks/session-start.js +27 -1
  62. package/dist/holmes/hooks/stop.d.ts +7 -0
  63. package/dist/holmes/hooks/stop.js +39 -2
  64. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  65. package/dist/holmes/mcp/elicit-approval.js +5 -2
  66. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  67. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  68. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  69. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  70. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  71. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  72. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  73. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  74. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  75. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  76. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  77. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  78. package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
  79. package/dist/holmes/mcp/handlers/test-execution.js +201 -21
  80. package/dist/holmes/mcp/handlers.d.ts +473 -8
  81. package/dist/holmes/mcp/handlers.js +6 -1
  82. package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
  83. package/dist/holmes/mcp/maintenance-analyze.js +4 -2
  84. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  85. package/dist/holmes/mcp/maintenance-evidence.js +4 -1
  86. package/dist/holmes/mcp/tool-schemas.js +16 -10
  87. package/dist/holmes/project/baseline.d.ts +15 -2
  88. package/dist/holmes/project/baseline.js +11 -6
  89. package/dist/holmes/project/bounded-io.d.ts +1 -0
  90. package/dist/holmes/project/bounded-io.js +4 -2
  91. package/dist/holmes/project/change-source.d.ts +4 -0
  92. package/dist/holmes/project/change-source.js +13 -5
  93. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  94. package/dist/holmes/project/playbook-reference.js +259 -0
  95. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  96. package/dist/holmes/project/playbook-skill-states.js +396 -0
  97. package/dist/holmes/project/root.d.ts +9 -1
  98. package/dist/holmes/project/root.js +26 -3
  99. package/dist/holmes/project/running-package.d.ts +15 -0
  100. package/dist/holmes/project/running-package.js +87 -0
  101. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  102. package/dist/holmes/review/evidence-mode.js +33 -0
  103. package/dist/holmes/review/head-worktree.d.ts +55 -0
  104. package/dist/holmes/review/head-worktree.js +329 -0
  105. package/dist/holmes/review/mrp.js +13 -3
  106. package/dist/holmes/review/run-provenance.d.ts +45 -0
  107. package/dist/holmes/review/run-provenance.js +314 -0
  108. package/dist/holmes/review/test-evidence.d.ts +174 -0
  109. package/dist/holmes/review/test-evidence.js +330 -2
  110. package/dist/holmes/review/test-reports.d.ts +94 -0
  111. package/dist/holmes/review/test-reports.js +382 -0
  112. package/dist/holmes/review/test-runner.d.ts +178 -65
  113. package/dist/holmes/review/test-runner.js +551 -319
  114. package/dist/holmes/review/test-units.d.ts +159 -0
  115. package/dist/holmes/review/test-units.js +814 -0
  116. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  117. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  118. package/package.json +5 -2
  119. package/playbooks/publish/PLAYBOOK.md +2 -1
@@ -1,18 +1,14 @@
1
1
  import { type ExecFileSyncOptionsWithStringEncoding } from 'node:child_process';
2
2
  import { RegressionTier, TestScope } from '../rtm/test-scope';
3
+ import type { NotDetected, NotRun } from './test-evidence';
4
+ import { type CodeRoot, type Ecosystem, type ScanOptions, type TestUnit } from './test-units';
5
+ import { type TestOutcome } from './test-reports';
3
6
  /**
4
7
  * @implements A-SPEC-734 (round 13) — every runner child is bounded, and a tool probe is short. One passing jest
5
8
  * test that left a `setInterval` open never returned, and the synchronous MCP call wedged the server (measured).
6
9
  * A run stopped at the bound is red and says so — never green.
7
10
  */
8
11
  export declare const RUNNER_TIMEOUT_MS: number;
9
- /**
10
- * @implements A-SPEC-734.3 — the child leads a process group of its own (POSIX), and a child stopped at the bound takes
11
- * that group with it: SIGKILL to the child alone left jest's forked workers running at 100% CPU (two per stopped run,
12
- * 2026-10-26). The group id is the pid of the child this call spawned, ended as soon as the call returns. Windows has
13
- * no groups; there the child alone is stopped, as before. Otherwise execFileSync's contract: stdout on exit 0, else a
14
- * throw carrying stdout, stderr, status and code.
15
- */
16
12
  export declare function runBounded(cmd: string, args: string[], opts: ExecFileSyncOptionsWithStringEncoding, timeoutMs?: number): string;
17
13
  /** @implements A-SPEC-734.4 — the last stop note (tests read it). */
18
14
  export declare function runnerStopNote(): string | null;
@@ -47,8 +43,59 @@ export interface TestRunResult {
47
43
  * than it claims, and the caller must be able to see that.
48
44
  */
49
45
  unsupported?: string[];
46
+ /**
47
+ * @implements A-SPEC-466.2 — the worker count placed on the jest argv; null when no worker flag reached jest (no
48
+ * count given, or no jest group ran). Absent only on results built before 466.2.
49
+ */
50
+ workers?: number | null;
51
+ /** @implements A-SPEC-466.3 — the runners that ran and took no worker count, when one was given (jest only takes it). */
52
+ workersIgnoredBy?: string[];
50
53
  /** Which adapters actually ran, for evidence provenance. */
51
54
  ranWith?: string[];
55
+ /**
56
+ * @implements A-SPEC-128.5 — the tests the runners executed, summed over ecosystems, whatever their attribution to files
57
+ * or A-SPECs (a full go or cargo run credits no file; an unanchored test credits no A-SPEC). The push gate reads this.
58
+ */
59
+ testsRun?: number;
60
+ /** @implements A-SPEC-128.5 — a runner child was stopped at the budget: the run is not judged. */
61
+ stopped?: boolean;
62
+ /** @implements A-SPEC-128.6 — the tests executed per ecosystem. */
63
+ testsRunBy?: Record<string, number>;
64
+ /** @implements A-SPEC-128.5 — the ecosystems a full plan found in the project; a full run must run every one. */
65
+ detected?: string[];
66
+ /** @implements A-SPEC-128.7 — per detected ecosystem, the root-relative path of the shallowest file that named it. */
67
+ detectedBy?: Record<string, string>;
68
+ /** @implements A-SPEC-128.7 — the ecosystems whose runner was red or stopped. */
69
+ failedBy?: string[];
70
+ /** @implements A-SPEC-128.7 — I1: impacted test files of an ecosystem a full run does not run, named instead. */
71
+ notRun?: NotRun[];
72
+ /** @implements A-SPEC-128.7 — build files outside the detection range, named and not run. */
73
+ notDetected?: NotDetected[];
74
+ /** @implements A-SPEC-128.9 — what each execution unit ran; every unit must run at least one test. */
75
+ units?: UnitResult[];
76
+ /** @implements A-SPEC-128.9 — units that failed because their runner is missing (E4 environment). */
77
+ environment?: Array<{
78
+ ecosystem: string;
79
+ dir: string;
80
+ reason: string;
81
+ }>;
82
+ /** @implements A-SPEC-128.9 — implementation sources outside tests and exclusions (E2). */
83
+ implementationCount?: number;
84
+ implementationSample?: string[];
85
+ /** @implements A-SPEC-128.9 — test-named python files holding no test function (A L3). */
86
+ notTests?: string[];
87
+ /** @implements A-SPEC-128.13 — the test files the scan found (E2: "nothing to test" needs none). */
88
+ testFileCount?: number;
89
+ /** @implements A-SPEC-128.13 — T4: _test.go files go does not build on this platform with no tags (named, not refused). */
90
+ notBuilt?: string[];
91
+ /** @implements A-SPEC-128.10 — I3: detected test files the runners did not report. */
92
+ notExecuted?: string[];
93
+ /** @implements A-SPEC-128.10 — R2: build roots whose code saw no executed test. */
94
+ untestedCode?: Array<{
95
+ root: string;
96
+ sample: string[];
97
+ missingBuildFile?: string;
98
+ }>;
52
99
  /**
53
100
  * @implements A-SPEC-534.5
54
101
  * Per-file RED-first outcome (jest only). red-assertion | red-error | green, for the outcome ledger
@@ -56,51 +103,12 @@ export interface TestRunResult {
56
103
  */
57
104
  outcomeByFile?: Record<string, TestOutcome>;
58
105
  }
59
- export type Ecosystem = 'jest' | 'pytest' | 'go' | 'rust' | 'java' | 'dotnet';
106
+ export type { Ecosystem, TestUnit, EcosystemScan, ScanOptions, CodeRoot } from './test-units';
107
+ export { scanEcosystems, excludedDir, normaliseExcludeDirs, BUILD_ROOTS, pytestRules, projectFiles } from './test-units';
60
108
  /** Ecosystem of a test file, by extension/convention. `null` when no runner adapter exists for it. */
61
109
  export declare function ecosystemOf(file: string): Ecosystem | null;
62
- /**
63
- * @implements A-SPEC-137.1
64
- * Executed-test counts per Go package from `go test -json` output. A test is EXECUTED when a NAMED
65
- * test (`Test` present) reaches `Action: 'pass'` or `'fail'` — a skip does not count (matching the
66
- * jest/pytest rule), and a package-level result (no `Test`) is not a test case. Non-JSON lines (go
67
- * interleaves build output) are ignored. Pure; empty/garbage input yields `{}` rather than throwing.
68
- */
69
- export declare function parseGoTestJson(out: string): Record<string, number>;
70
- /**
71
- * Parse jest --json output into per-file EXECUTED case counts. This is the execution-proof upgrade
72
- * over the syntactic countTestCases lower bound: a case only appears here if jest actually ran it
73
- * (pending/skipped assertions are excluded), so `if(false){it(…)}`, aliasing, and other syntactic
74
- * fabrications cannot produce evidence. Returns {} for unparseable output (caller falls back).
75
- */
76
- export declare function parseExecutedCounts(stdout: string, cwd: string): Record<string, number>;
77
- /**
78
- * Per-file test outcome for RED-first evidence (REQ-534). `red-assertion` is a REAL red — a case ran
79
- * and its assertion failed; `red-error` is a file that could not run its cases (load/collection/import
80
- * error), which ART-8 (534.2) must NOT accept as a valid RED; `green` ran and all assertions passed.
81
- */
82
- export type TestOutcome = 'red-assertion' | 'red-error' | 'green';
83
- /**
84
- * @implements A-SPEC-534.1
85
- * Classify each jest-executed file into red-assertion | red-error | green from `jest --json` stdout.
86
- * Pure; unparseable/empty input → {} (same fail-soft convention as parseExecutedCounts).
87
- *
88
- * A failed assertion anywhere in a file wins (`red-assertion`) — that is a real red. A file that ran
89
- * NO assertions but errored (testExecError, or status 'failed' with an empty assertion list — a
90
- * load/collection/import failure) is `red-error`, which ART-8 must not accept as a valid RED. A file
91
- * that executed ≥1 assertion with none failing is `green`. A file that only pended/skipped carries no
92
- * evidence and is omitted entirely.
93
- */
94
- export declare function classifyJestOutcomes(stdout: string, cwd: string): Record<string, TestOutcome>;
95
- /**
96
- * Parse pytest's built-in JUnit XML into per-file EXECUTED case counts — the pytest analogue of
97
- * parseExecutedCounts. `--junit-xml` ships with pytest core, so this needs no plugin, and it is the
98
- * only pytest output that is both machine-readable and per-file.
99
- *
100
- * A `<testcase>` counts as executed unless it carries `<skipped>`, matching the jest rule where
101
- * pending/skipped assertions are excluded. Errors and failures DO count: they executed.
102
- */
103
- export declare function parseJUnitXmlCounts(xml: string, ext?: string): Record<string, number>;
110
+ export { parseGoTestJson, goPackagesWithTestEvents, parseExecutedCounts, classifyJestOutcomes, parseJUnitXmlCounts, parseJUnitXmlOutcomes, parseJUnitXmlFiles, wellShapedJson, readJestReport } from './test-reports';
111
+ export type { TestOutcome } from './test-reports';
104
112
  /**
105
113
  * @implements A-SPEC-466 — W-4. The TARGET repo's own jest entry, as its package declares it.
106
114
  *
@@ -116,35 +124,70 @@ export declare function parseJUnitXmlCounts(xml: string, ext?: string): Record<s
116
124
  * there), and a repo with no local jest could never yield meaningful suite evidence anyway.
117
125
  */
118
126
  export declare function jestEntry(cwd: string): string | null;
127
+ /** @implements A-SPEC-466.1 — what a run may be told beyond its scope. Only the jest adapter reads it. */
128
+ export interface TestRunOptions {
129
+ workers?: number;
130
+ timeoutMinutes?: number;
131
+ /** @implements A-SPEC-128.6 — the trees detection never walks, injected by the caller from ax.config.json. */
132
+ excludeDirs?: string[];
133
+ /** @implements A-SPEC-128.9 — the project's ignore matcher (root-relative), injected by the caller. */
134
+ isIgnored?: (relPath: string) => boolean;
135
+ /** @implements A-SPEC-128.13 — the work tree a HEAD worktree run came from: pytest's interpreter (a .venv) is found there. */
136
+ sourceRoot?: string;
137
+ /** @implements A-SPEC-794.119 — the tree the run executes in; the test children's CLAUDE_PROJECT_DIR names it. */
138
+ projectRoot?: string;
139
+ }
140
+ /** @implements A-SPEC-128.9 — one unit's outcome in a full run. */
141
+ export interface UnitResult {
142
+ ecosystem: string;
143
+ dir: string;
144
+ testsRun: number;
145
+ passed: boolean;
146
+ environment?: string;
147
+ }
148
+ /**
149
+ * @implements A-SPEC-466.6 — test_run's `timeoutMinutes`, the run's time budget: absent or null is 30; an integer
150
+ * 1..180 is kept; anything else throws (never clamped). It is not a judgement input.
151
+ */
152
+ export declare function testRunTimeoutMinutes(value: unknown): number;
153
+ /**
154
+ * @implements A-SPEC-466.1 — test_run's `workers`: absent stays absent; an integer 1..64 is kept; anything else
155
+ * throws, so a bad count is refused before any change set is derived or any runner starts.
156
+ */
157
+ export declare function testRunWorkers(value: unknown): number | undefined;
158
+ /**
159
+ * @implements A-SPEC-128.12 — the one message for a configuration outside the 0.40.x supported surface (jest with one
160
+ * project and one unit, pytest under default naming, go). It leads every such environment reason.
161
+ */
162
+ export declare const UNSUPPORTED = "\uC774 \uAD6C\uC131\uC740 0.40.x\uAC00 \uC99D\uBE59\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 0.41 / \uC624\uB108 \uACB0\uC815";
119
163
  /**
120
164
  * @implements A-SPEC-534.8
121
165
  * Run specific jest files and return only their RED-first outcomes — the runner `test_run --mutate`
122
166
  * injects into runKillsOnFile. Scoped, jest only (the classifier is jest-only), fail-soft to {}.
123
167
  */
124
- export declare function runJestOutcomes(files: string[], cwd: string): Record<string, TestOutcome>;
168
+ export declare function runJestOutcomes(files: string[], cwd: string, timeoutMinutes?: number): Record<string, TestOutcome>;
125
169
  /** Run the pytest half of a plan, taking execution evidence from pytest's built-in JUnit XML. */
126
- /**
127
- * @implements A-SPEC-647
128
- * Per-file RED-first outcome from the same JUnit XML `parseJUnitXmlCounts` reads. Measured 2026-09-14
129
- * in an external pytest project: a ranged test_run executed the anchored case and recorded NOTHING,
130
- * because classification was jest-only — a Python project could never produce the red-assertion→green
131
- * sequence ART-8 reads. `<error>` (collection/import/setup) is a red-error, `<failure>` (an assertion)
132
- * a red-assertion, executed cases without either are green; a file with only skipped cases says nothing.
133
- */
134
- export declare function parseJUnitXmlOutcomes(xml: string, ext?: string): Record<string, TestOutcome>;
135
170
  /**
136
171
  * @implements A-SPEC-647
137
172
  * The ecosystems a project's OWN test files belong to, by file-name convention, under a bounded walk
138
173
  * that skips vendored trees and virtualenvs. Measured: a full-tier run with no impacted list assumed
139
- * the jest suite on a pytest-only project, ran nothing and reported passed:false. This repository's
140
- * Python tests live under `reference/`, so it detects jest only and its runs are unchanged.
174
+ * the jest suite on a pytest-only project, ran nothing and reported passed:false.
175
+ * @implements A-SPEC-128.5 — configuration files name an ecosystem too (a pytest.ini, a go.mod), the root's are read
176
+ * even where the walk stops early, and the skipped trees a project vendors are its own declaration
177
+ * (`ax.config.json` testRun.excludeDirs), not a name built in here. This repository lists `reference`.
141
178
  */
142
- export declare function detectProjectEcosystems(cwd: string): Ecosystem[];
143
- export declare function runPytest(files: string[], mode: TestRunPlan['mode'], cwd: string): {
179
+ export declare function detectProjectEcosystems(cwd: string, opts?: ScanOptions): Ecosystem[];
180
+ export declare function runPytest(files: string[], mode: TestRunPlan['mode'], cwd: string, ignore?: string[], pythonFrom?: string, run?: {
181
+ root: string;
182
+ sourceRoot: string;
183
+ }): {
144
184
  passed: boolean;
145
185
  tail: string;
146
186
  executed: Record<string, number>;
147
187
  outcomes: Record<string, TestOutcome>;
188
+ testsRun?: number;
189
+ reported?: string[];
190
+ environment?: boolean;
148
191
  };
149
192
  /**
150
193
  * @implements A-SPEC-137.2
@@ -170,6 +213,7 @@ export declare function runCargo(files: string[], _mode: TestRunPlan['mode'], cw
170
213
  tail: string;
171
214
  executed: Record<string, number>;
172
215
  unsupported?: string[];
216
+ testsRun?: number;
173
217
  };
174
218
  /**
175
219
  * @implements A-SPEC-137.3
@@ -185,6 +229,7 @@ export declare function runGradle(files: string[], _mode: TestRunPlan['mode'], c
185
229
  tail: string;
186
230
  executed: Record<string, number>;
187
231
  unsupported?: string[];
232
+ testsRun?: number;
188
233
  };
189
234
  /**
190
235
  * @implements A-SPEC-137.3
@@ -199,6 +244,7 @@ export declare function runDotnet(files: string[], _mode: TestRunPlan['mode'], c
199
244
  tail: string;
200
245
  executed: Record<string, number>;
201
246
  unsupported?: string[];
247
+ testsRun?: number;
202
248
  };
203
249
  /**
204
250
  * @implements A-SPEC-137.1
@@ -209,11 +255,14 @@ export declare function runDotnet(files: string[], _mode: TestRunPlan['mode'], c
209
255
  */
210
256
  export declare function runGo(files: string[], mode: TestRunPlan['mode'], cwd: string, opts?: {
211
257
  goPresent?: boolean;
258
+ ignore?: string[];
259
+ env?: Record<string, string>;
212
260
  }): {
213
261
  passed: boolean;
214
262
  tail: string;
215
263
  executed: Record<string, number>;
216
264
  unsupported?: string[];
265
+ testsRun?: number;
217
266
  };
218
267
  /**
219
268
  * Execute a plan (I/O). Deterministic inputs → deterministic command; the pass/fail is the suite's.
@@ -224,7 +273,63 @@ export declare function runGo(files: string[], mode: TestRunPlan['mode'], cwd: s
224
273
  * ecosystem has no adapter are returned in `unsupported` — never dropped quietly, because a scoped
225
274
  * gate that ran part of its scope has verified less than it reports.
226
275
  */
227
- export declare function runTestScope(scope: TestScope, cwd: string): TestRunResult;
276
+ export declare function runTestScope(scope: TestScope, cwd: string, opts?: TestRunOptions): TestRunResult;
277
+ /**
278
+ * @implements A-SPEC-128.4 — which ecosystem groups a plan runs. A scoped plan groups its own files. A full plan runs
279
+ * every ecosystem the PROJECT has, together with those of the impacted test files: detecting from the impacted files
280
+ * alone let a full run of a jest+pytest project skip pytest and still record `mode: full` (review 2026-11-05, A H1).
281
+ * Jest is assumed only when the project shows no ecosystem at all, and the run says so.
282
+ */
283
+ export declare function runEcosystems(scope: TestScope, plan: TestRunPlan, cwd: string, opts?: ScanOptions): {
284
+ groups: Map<Ecosystem, string[]>;
285
+ units: Array<TestUnit & {
286
+ files: string[];
287
+ }>;
288
+ unsupported: string[];
289
+ assumedJest: boolean;
290
+ detected: Ecosystem[];
291
+ detectedBy: Record<string, string>;
292
+ notRun: NotRun[];
293
+ notDetected: NotDetected[];
294
+ implementationCount: number;
295
+ implementationSample: string[];
296
+ notTests: string[];
297
+ expected: Record<string, string[]>;
298
+ codeRoots: CodeRoot[];
299
+ buildRoots: string[];
300
+ sparseTests: string[];
301
+ outsideSurface: Array<{
302
+ ecosystem: string;
303
+ dir: string;
304
+ reason: string;
305
+ }>;
306
+ testFiles: string[];
307
+ notBuilt: string[];
308
+ };
309
+ /**
310
+ * @implements A-SPEC-128.10 — I3 and R2, judged AFTER the run from what the runners reported: the expected test files
311
+ * a unit did not report (a runner configuration, a root narrower than the tree, a package that ran nothing), and the
312
+ * build roots whose code saw no executed test. Units that could not run (environment, stop) are judged elsewhere.
313
+ */
314
+ export declare function coverageAfterRun(expected: Record<string, string[]>, codeRoots: CodeRoot[], reported: Set<string>, executedByFile: Record<string, number>, skipUnits: Set<string>, buildRoots?: readonly string[], testFiles?: readonly string[]): {
315
+ notExecuted: string[];
316
+ untestedCode: Array<{
317
+ root: string;
318
+ sample: string[];
319
+ missingBuildFile?: string;
320
+ testFiles?: number;
321
+ }>;
322
+ };
323
+ /**
324
+ * @implements A-SPEC-128.9 — E4: why a unit that ran nothing failed, when the cause is its environment, not its tests: a
325
+ * missing runner. Null when the unit executed a test or failed for any other reason (then it is the tests).
326
+ */
327
+ export declare function environmentReason(r: {
328
+ passed: boolean;
329
+ tail: string;
330
+ unsupported?: string[];
331
+ environment?: boolean;
332
+ }, counted: number): string | null;
228
333
  /**
229
334
  * The last few lines of a runner's output, bounded by SIZE as well as by line count.
230
335
  *
@@ -266,4 +371,12 @@ export declare function tailOf(s: string, opts?: number | {
266
371
  * Only the FIRST line of a failure message: one failure, one look. The rest is in the file.
267
372
  */
268
373
  export declare function failedTestSummary(stdout: string, limit?: number): string | null;
374
+ /**
375
+ * @implements A-SPEC-466.3, A-SPEC-466.4 \u2014 the tail of a red jest run. The failing names come first; jest's stderr
376
+ * follows with a bound of its own. One `tailOf` over both kept the last lines and cut the front, so a long stderr pushed
377
+ * every name out (2026-11-04, `27bc0c40`: five failures, none named). The name block is bounded by its parts: five names
378
+ * of at most WHERE_MAX and FIRST_MAX characters and one count line, so the whole tail stays under 7,000 characters.
379
+ * Without readable jest JSON the tail is what it always was.
380
+ */
381
+ export declare function redJestTail(stdout: string, stderr: string): string;
269
382
  export declare function summarizeJestJson(stdout: string): string | null;