@holmes-lab/holmes-kit 0.41.1 → 0.41.3

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 (105) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +29 -5
  3. package/bin/holmes-mcp.js +36 -1
  4. package/dist/.build-id +1 -1
  5. package/dist/holmes/cli/claude-switches.d.ts +9 -0
  6. package/dist/holmes/cli/claude-switches.js +11 -8
  7. package/dist/holmes/cli/doctor.d.ts +7 -1
  8. package/dist/holmes/cli/doctor.js +63 -20
  9. package/dist/holmes/cli/holmes-hook-id.d.ts +9 -0
  10. package/dist/holmes/cli/holmes-hook-id.js +22 -0
  11. package/dist/holmes/cli/hook-failure-posture.d.ts +44 -0
  12. package/dist/holmes/cli/hook-failure-posture.js +65 -0
  13. package/dist/holmes/cli/index.js +3 -1
  14. package/dist/holmes/cli/init.d.ts +6 -0
  15. package/dist/holmes/cli/init.js +151 -3
  16. package/dist/holmes/cli/native-deps.d.ts +10 -4
  17. package/dist/holmes/cli/native-deps.js +30 -29
  18. package/dist/holmes/cli/release-history.d.ts +21 -0
  19. package/dist/holmes/cli/release-history.js +116 -0
  20. package/dist/holmes/cli/run-wiring.js +4 -2
  21. package/dist/holmes/cli/runtime-binding.d.ts +24 -0
  22. package/dist/holmes/cli/runtime-binding.js +67 -25
  23. package/dist/holmes/cli/settings-merge.d.ts +3 -2
  24. package/dist/holmes/cli/settings-merge.js +11 -9
  25. package/dist/holmes/config/config.d.ts +6 -0
  26. package/dist/holmes/config/config.js +23 -3
  27. package/dist/holmes/config/judgement-keys.d.ts +20 -0
  28. package/dist/holmes/config/judgement-keys.js +100 -0
  29. package/dist/holmes/config/project-caps.js +3 -2
  30. package/dist/holmes/governance/autonomous-shell.js +1 -1
  31. package/dist/holmes/governance/autonomy.d.ts +27 -1
  32. package/dist/holmes/governance/autonomy.js +126 -6
  33. package/dist/holmes/governance/wiring-receipt.d.ts +7 -0
  34. package/dist/holmes/governance/wiring-receipt.js +84 -0
  35. package/dist/holmes/guardrail/cli-root.d.ts +31 -0
  36. package/dist/holmes/guardrail/cli-root.js +261 -0
  37. package/dist/holmes/guardrail/command-traits.d.ts +2 -0
  38. package/dist/holmes/guardrail/command-traits.js +26 -1
  39. package/dist/holmes/guardrail/impact-gate.d.ts +17 -1
  40. package/dist/holmes/guardrail/impact-gate.js +44 -5
  41. package/dist/holmes/guardrail/outward-acts.js +10 -3
  42. package/dist/holmes/guardrail/package-manager-acts.d.ts +41 -0
  43. package/dist/holmes/guardrail/package-manager-acts.js +1298 -0
  44. package/dist/holmes/guardrail/refusal-codes.js +9 -1
  45. package/dist/holmes/guardrail/shell-syntax.d.ts +3 -0
  46. package/dist/holmes/guardrail/shell-syntax.js +7 -2
  47. package/dist/holmes/guardrail/write-target.d.ts +20 -0
  48. package/dist/holmes/guardrail/write-target.js +168 -2
  49. package/dist/holmes/hooks/pre-tool-use.d.ts +110 -3
  50. package/dist/holmes/hooks/pre-tool-use.js +1208 -60
  51. package/dist/holmes/mcp/evidence-artifact.d.ts +112 -0
  52. package/dist/holmes/mcp/evidence-artifact.js +2 -0
  53. package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +2 -1
  54. package/dist/holmes/mcp/handlers/maintenance-evidence.js +24 -2
  55. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +1 -1
  56. package/dist/holmes/mcp/handlers/operator-inspection.js +2 -2
  57. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +1 -1
  58. package/dist/holmes/mcp/handlers/requirement-triage.js +3 -2
  59. package/dist/holmes/mcp/handlers/spec-approval.d.ts +1 -1
  60. package/dist/holmes/mcp/handlers/spec-approval.js +6 -6
  61. package/dist/holmes/mcp/handlers/test-execution.d.ts +8 -0
  62. package/dist/holmes/mcp/handlers/test-execution.js +12 -6
  63. package/dist/holmes/mcp/handlers.d.ts +16 -7
  64. package/dist/holmes/mcp/maintenance-evidence.d.ts +11 -82
  65. package/dist/holmes/mcp/maintenance-evidence.js +57 -2
  66. package/dist/holmes/mcp/outcome-replay.d.ts +18 -0
  67. package/dist/holmes/mcp/outcome-replay.js +85 -0
  68. package/dist/holmes/mcp/outcome-windows.d.ts +136 -0
  69. package/dist/holmes/mcp/outcome-windows.js +236 -0
  70. package/dist/holmes/mcp/tool-schemas.js +1 -1
  71. package/dist/holmes/project/hook-specs-arg.d.ts +4 -0
  72. package/dist/holmes/project/hook-specs-arg.js +39 -0
  73. package/dist/holmes/project/install-layout.d.ts +11 -0
  74. package/dist/holmes/project/install-layout.js +109 -0
  75. package/dist/holmes/project/install-scripts-policy.d.ts +4 -1
  76. package/dist/holmes/project/install-scripts-policy.js +6 -3
  77. package/dist/holmes/project/native-recovery.d.ts +29 -0
  78. package/dist/holmes/project/native-recovery.js +62 -0
  79. package/dist/holmes/project/root.d.ts +6 -0
  80. package/dist/holmes/project/root.js +15 -3
  81. package/dist/holmes/project/wiring-receipt-format.d.ts +20 -0
  82. package/dist/holmes/project/wiring-receipt-format.js +42 -0
  83. package/dist/holmes/project/workspace-preflight.d.ts +9 -0
  84. package/dist/holmes/project/workspace-preflight.js +40 -1
  85. package/dist/holmes/review/classification-replay.d.ts +53 -0
  86. package/dist/holmes/review/classification-replay.js +78 -0
  87. package/dist/holmes/review/head-worktree.js +5 -4
  88. package/dist/holmes/review/run-provenance.js +3 -2
  89. package/dist/holmes/review/test-evidence.js +2 -2
  90. package/dist/holmes/review/test-outcomes.js +3 -1
  91. package/dist/holmes/rtm/graph-store.d.ts +5 -0
  92. package/dist/holmes/rtm/graph-store.js +12 -4
  93. package/dist/holmes/rtm/native-driver.d.ts +42 -0
  94. package/dist/holmes/rtm/native-driver.js +147 -0
  95. package/dist/holmes/rtm/rtm-graph.js +11 -2
  96. package/dist/holmes/runtime/dispatch.d.ts +6 -0
  97. package/dist/holmes/runtime/dispatch.js +51 -2
  98. package/dist/holmes/runtime/hook-process.d.ts +6 -0
  99. package/dist/holmes/runtime/hook-process.js +3 -3
  100. package/dist/holmes/update/semver-strict.d.ts +3 -0
  101. package/dist/holmes/update/semver-strict.js +58 -0
  102. package/docs/install-guide.md +8 -1
  103. package/package.json +3 -2
  104. package/playbooks/tdd-slice/PLAYBOOK.md +1 -1
  105. package/release-history.json +181 -0
@@ -1,4 +1,5 @@
1
1
  import type { MaintenanceAnalysis } from './maintenance-analyze';
2
+ import { type FileScores, type Git } from './outcome-windows';
2
3
  /**
3
4
  * Persisted maintenance evidence — the durable half of the graph-first protocol.
4
5
  *
@@ -11,88 +12,8 @@ import type { MaintenanceAnalysis } from './maintenance-analyze';
11
12
  export declare const EVIDENCE_ARTIFACT_SCHEMA = "maintenance-evidence/1.4";
12
13
  /** Default directory, relative to the project root. */
13
14
  export declare const EVIDENCE_DIR: string;
14
- export interface EvidenceOutcome {
15
- recordedAt: string;
16
- actualFiles: string[];
17
- actualSymbols: string[];
18
- actualTests: string[];
19
- /** Absent when nobody has judged the classification: unscored, NOT scored as wrong. */
20
- actualClassification?: string;
21
- }
22
- export interface EvidenceArtifact {
23
- artifactSchema: string;
24
- digest: string;
25
- recordedAt: string;
26
- analysisSchema: string;
27
- extractorVersion: string;
28
- classification: string;
29
- confidence: number;
30
- /**
31
- * @implements A-SPEC-740 — optional on purpose: an artifact recorded before the marker existed is
32
- * just as uncalibrated, and the schema string stays 1.4 so calibration still reads it.
33
- */
34
- confidenceCalibrated?: false;
35
- graphBasis: MaintenanceAnalysis['graphBasis'];
36
- predicted: {
37
- files: string[];
38
- primaryFiles: string[];
39
- symbols: string[];
40
- tests: string[];
41
- /**
42
- * @implements A-SPEC-277
43
- * sha256 of each predicted file AS ANALYSED. HEAD alone cannot see an uncommitted edit to the
44
- * very file under analysis, which would leave the evidence looking current while describing
45
- * content that no longer exists. Computed by the caller (reading files is I/O; this module is
46
- * pure), keyed by the same repo-relative path as `files`.
47
- */
48
- fileDigests: Record<string, string>;
49
- };
50
- /**
51
- * @implements A-SPEC-276
52
- * What the analysis did NOT establish. A pre-edit gate that reads only the prediction would treat
53
- * "we saw no impact" and "we could not look" as the same sentence; they are opposite claims. The
54
- * artifact is the durable evidence, so the uncertainty travels with it.
55
- */
56
- uncertainty: {
57
- unknowns: string[];
58
- coverage: {
59
- scannedFiles: number;
60
- skippedFiles: string[];
61
- unsupportedLanguages: string[];
62
- };
63
- /** The caller walk stopped at a bound: the transitive set is a lower bound, not a complete one. */
64
- impactTruncated: boolean;
65
- testScopeTier: string;
66
- /** @implements A-SPEC-744 — why the scope was what it was; optional so older artifacts still read. */
67
- testScopeReason?: string;
68
- testScopeCauses?: string[];
69
- /** Files reachable only through a call edge — affected, but never analysed as edit candidates. */
70
- impactedFiles: string[];
71
- /**
72
- * @implements A-SPEC-279
73
- * Whether each constraint axis was EXAMINED. False means the input was missing, never that the
74
- * axis came back clean — the distinction the gate acts on.
75
- */
76
- securityAssessed: boolean;
77
- compatibilityAssessed: boolean;
78
- /**
79
- * @implements A-SPEC-333.9 — the governing documents the architecture basis held. The gate keeps the axis open for
80
- * an edit of a governing document a diff-built basis did not hold. Optional: older artifacts read as before.
81
- */
82
- architectureTouched?: string[];
83
- };
84
- outcome?: EvidenceOutcome;
85
- /**
86
- * @implements A-SPEC-278.3 — what the caller asked and which files it said it would change. The pre-edit gate covers a
87
- * new file the request names (A-SPEC-278.2), which it could not do while the artifact kept no request. Optional: older
88
- * artifacts read as before.
89
- */
90
- request?: string;
91
- changedFiles?: string[];
92
- /** @implements A-SPEC-293.1 — where the architecture axis's changed files came from; never itself a list the gate reads. */
93
- changedFilesSource?: ChangedFilesSource;
94
- }
95
- export type ChangedFilesSource = 'caller' | 'git-diff-default' | 'none';
15
+ export type { EvidenceOutcome, OutcomeWindow, EvidenceArtifact, ChangedFilesSource } from './evidence-artifact';
16
+ import type { EvidenceArtifact, ChangedFilesSource, OutcomeWindow } from './evidence-artifact';
96
17
  /** What the caller supplied to the analysis, recorded beside the prediction (A-SPEC-278.3). */
97
18
  export interface AnalysisIntake {
98
19
  request?: string;
@@ -128,6 +49,8 @@ export interface OutcomeInput {
128
49
  actualSymbols?: string[];
129
50
  actualTests?: string[];
130
51
  actualClassification?: string;
52
+ /** @implements A-SPEC-578.17 */
53
+ window?: OutcomeWindow;
131
54
  }
132
55
  /**
133
56
  * Attach what actually happened to a prediction that was actually made. An unknown digest is
@@ -172,8 +95,11 @@ export declare function openArtifacts(dir: string, since?: string): EvidenceArti
172
95
  */
173
96
  export declare function closeOpenArtifacts(dir: string, actual: {
174
97
  files: string[];
98
+ root?: string;
99
+ git?: Git;
175
100
  }, recordedAt: string, since?: string): {
176
101
  closed: string[];
102
+ failed?: number;
177
103
  };
178
104
  export interface CalibrationBin {
179
105
  lower: number;
@@ -212,6 +138,8 @@ export interface Calibration {
212
138
  unrecorded: number;
213
139
  causes: Record<string, number>;
214
140
  };
141
+ /** @implements A-SPEC-578.17 — the file-level score per window, at the emitted ten and over the ranked set. */
142
+ fileScores: FileScores;
215
143
  }
216
144
  /**
217
145
  * @implements A-SPEC-744
@@ -227,4 +155,5 @@ export declare function scopeCauses(scope: MaintenanceAnalysis['testScope']): st
227
155
  */
228
156
  export declare function computeCalibration(artifacts: readonly EvidenceArtifact[], opts?: {
229
157
  minSamples?: number;
158
+ unscored?: readonly string[];
230
159
  }): Calibration;
@@ -43,10 +43,11 @@ 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, A-SPEC-278.3, A-SPEC-293.1, A-SPEC-333.9
46
+ // @implements A-SPEC-744, A-SPEC-740, A-SPEC-724.1, A-SPEC-271, A-SPEC-278.3, A-SPEC-293.1, A-SPEC-333.9, A-SPEC-578.17, A-SPEC-578.18
47
47
  // @implements A-SPEC-268
48
48
  const fs = __importStar(require("node:fs"));
49
49
  const path = __importStar(require("node:path"));
50
+ const outcome_windows_1 = require("./outcome-windows");
50
51
  /**
51
52
  * Persisted maintenance evidence — the durable half of the graph-first protocol.
52
53
  *
@@ -103,6 +104,15 @@ function intakeRecord(intake) {
103
104
  }
104
105
  return out;
105
106
  }
107
+ /** @implements A-SPEC-578.17 — the emitted candidates in rank order, then the rerank pool, each file once. */
108
+ function rankedFilesOf(analysis) {
109
+ const out = [];
110
+ for (const row of [...(analysis.candidates ?? []), ...(analysis.rerankPool ?? [])]) {
111
+ if (typeof row?.file === 'string' && !out.includes(row.file))
112
+ out.push(row.file);
113
+ }
114
+ return out;
115
+ }
106
116
  /** Project an analysis into the durable prediction record. Pure: the caller supplies the clock. */
107
117
  function artifactFrom(analysis, recordedAt, fileDigests = {}, intake) {
108
118
  return {
@@ -123,6 +133,7 @@ function artifactFrom(analysis, recordedAt, fileDigests = {}, intake) {
123
133
  symbols: sortedUnique([...analysis.impacts.direct, ...analysis.impacts.transitive]),
124
134
  tests: sortedUnique(analysis.relevantTests),
125
135
  fileDigests: { ...fileDigests },
136
+ rankedFiles: rankedFilesOf(analysis),
126
137
  },
127
138
  uncertainty: {
128
139
  unknowns: [...analysis.unknowns],
@@ -228,6 +239,7 @@ function recordOutcome(dir, digest, outcome, recordedAt) {
228
239
  const prev = artifact.outcome;
229
240
  const merged = (given, before) => given === undefined ? (before ?? []) : sortedUnique(given);
230
241
  const classification = outcome.actualClassification ?? prev?.actualClassification;
242
+ const window = outcome.window ?? prev?.window; // @implements A-SPEC-578.17 — kept like every field it did not name
231
243
  const updated = {
232
244
  ...artifact,
233
245
  outcome: {
@@ -236,6 +248,7 @@ function recordOutcome(dir, digest, outcome, recordedAt) {
236
248
  actualSymbols: merged(outcome.actualSymbols, prev?.actualSymbols),
237
249
  actualTests: merged(outcome.actualTests, prev?.actualTests),
238
250
  ...(classification ? { actualClassification: classification } : {}),
251
+ ...(window ? { window } : {}),
239
252
  },
240
253
  };
241
254
  const text = `${JSON.stringify(updated, null, 2)}\n`;
@@ -307,6 +320,10 @@ function openArtifacts(dir, since) {
307
320
  */
308
321
  function closeOpenArtifacts(dir, actual, recordedAt, since) {
309
322
  const files = Array.isArray(actual?.files) ? actual.files : [];
323
+ // A-SPEC-578.18 — a windowed close is exact whenever it runs, so `since` bounds only the legacy close below: filtering
324
+ // by it would leave an analysis that was pending at the previous run open forever
325
+ if (typeof actual?.root === 'string')
326
+ return closeByWindows(dir, actual.git ?? (0, outcome_windows_1.projectGit)(actual.root), recordedAt);
310
327
  if (files.length === 0)
311
328
  return { closed: [] };
312
329
  const closed = [];
@@ -319,6 +336,37 @@ function closeOpenArtifacts(dir, actual, recordedAt, since) {
319
336
  }
320
337
  return { closed };
321
338
  }
339
+ /**
340
+ * @implements A-SPEC-578.18 — each open analysis is closed on its own window once that window has ended: every commit
341
+ * between its HEAD and the next persisted analysis's HEAD (open or closed — the next request was asked either way).
342
+ * Superseded and unattributable windows close with no files and are never scored; a pending window (no next analysis)
343
+ * and a failed git read write nothing, so production closes exactly what the replay rebuilds, whenever it runs.
344
+ */
345
+ function closeByWindows(dir, git, recordedAt) {
346
+ const all = readArtifacts(dir).artifacts;
347
+ const open = all.filter((a) => a.outcome === undefined);
348
+ const windows = (0, outcome_windows_1.windowsFor)(all, open, git);
349
+ const closed = [];
350
+ let failed = 0;
351
+ for (const a of open) {
352
+ const w = windows.get(a.digest);
353
+ if (!w || w.kind === 'pending')
354
+ continue;
355
+ if (w.kind === 'failed') {
356
+ failed++;
357
+ continue;
358
+ }
359
+ const outcome = w.kind === 'commits'
360
+ ? { actualFiles: w.files, window: { kind: 'commits', from: w.from, to: w.to, shas: w.shas } }
361
+ : { actualFiles: [], window: w };
362
+ try {
363
+ recordOutcome(dir, a.digest, outcome, recordedAt);
364
+ closed.push(a.digest);
365
+ }
366
+ catch { /* an artifact we cannot write is not a reason to abandon the rest */ }
367
+ }
368
+ return { closed, failed };
369
+ }
322
370
  /**
323
371
  * @implements A-SPEC-744
324
372
  * The named reasons a test scope is `full`, read from its structured fields — never parsed out of the
@@ -373,6 +421,7 @@ function scopeCauseTally(artifacts) {
373
421
  */
374
422
  function computeCalibration(artifacts, opts = {}) {
375
423
  const minSamples = Math.max(1, Math.floor(opts.minSamples ?? 5));
424
+ const scoreOpts = opts.unscored ? { unscored: opts.unscored } : {};
376
425
  const scored = artifacts.filter((a) => a.outcome?.actualClassification !== undefined);
377
426
  const withoutClassification = artifacts.length - scored.length; // @implements A-SPEC-434
378
427
  let falsePositives = 0;
@@ -382,7 +431,12 @@ function computeCalibration(artifacts, opts = {}) {
382
431
  // outcome names one — independent of whether the classification was judged.
383
432
  if (!artifact.outcome)
384
433
  continue;
385
- const actual = new Set(artifact.outcome.actualFiles);
434
+ // @implements A-SPEC-578.17, A-SPEC-578.18 — a superseded or unattributable outcome is empty by construction, not
435
+ // a claim that nothing changed; and FP/FN read the same scorable set as fileScores
436
+ const kind = artifact.outcome.window?.kind;
437
+ if (kind === 'superseded' || kind === 'unattributable')
438
+ continue;
439
+ const actual = new Set(artifact.outcome.actualFiles.filter((f) => (0, outcome_windows_1.isScorable)(f, opts.unscored)));
386
440
  const predicted = new Set(artifact.predicted.files);
387
441
  for (const file of predicted)
388
442
  if (!actual.has(file))
@@ -425,5 +479,6 @@ function computeCalibration(artifacts, opts = {}) {
425
479
  minSamples,
426
480
  status: correctness.length >= minSamples ? 'measured' : 'insufficient-data',
427
481
  scopeCauses: scopeCauseTally(artifacts),
482
+ fileScores: (0, outcome_windows_1.fileScores)(artifacts, scoreOpts),
428
483
  };
429
484
  }
@@ -0,0 +1,18 @@
1
+ import type { EvidenceArtifact } from './maintenance-evidence';
2
+ import { type FileScores, type RangeResult, type ScoreOptions } from './outcome-windows';
3
+ export type Choice = 'first-commit' | 'head-to-head' | 'merged-same-request';
4
+ export interface ChoiceReport {
5
+ scores: FileScores;
6
+ pending: number;
7
+ failed: number;
8
+ merged: number;
9
+ }
10
+ export interface ReplayReport {
11
+ inputs: {
12
+ artifacts: number;
13
+ digest: string;
14
+ heads: number;
15
+ };
16
+ choices: Record<Choice, ChoiceReport>;
17
+ }
18
+ export declare function replayWindows(artifacts: readonly EvidenceArtifact[], rangeOf: (from: string, to: string) => RangeResult, opts?: ScoreOptions): ReplayReport;
@@ -0,0 +1,85 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.replayWindows = replayWindows;
4
+ // @implements A-SPEC-578.18
5
+ /**
6
+ * The replay of A-SPEC-578.18 (review H5: the numbers of 578.17 had no committed source). Read-only: it rebuilds each
7
+ * persisted analysis's window from git and scores it, under three choices of what "the change the analysis led to" is,
8
+ * so the choice is made with its numbers in view:
9
+ * - `first-commit` 578.17's rule — the oldest commit of the head-to-head range only;
10
+ * - `head-to-head` 578.18's rule — every commit between the analysis's HEAD and the next analysis's HEAD;
11
+ * - `merged-same-request` head-to-head, but an analysis that repeats the previous one's request is merged into it
12
+ * (its window ends at the next analysis that asks something else).
13
+ * It names its inputs (artifact count, the digest of the sorted artifact digests, distinct HEADs) so a figure can be
14
+ * reproduced, and every exclusion is counted rather than dropped.
15
+ */
16
+ const node_crypto_1 = require("node:crypto");
17
+ const outcome_windows_1 = require("./outcome-windows");
18
+ /** The artifact as if closed on `w` — the shape fileScores reads; nothing is written. */
19
+ function closedOn(a, w) {
20
+ const window = w.kind === 'commits' ? { kind: 'commits', from: w.from, to: w.to, shas: w.shas } : w;
21
+ return { ...a, outcome: { recordedAt: a.recordedAt, actualFiles: w.kind === 'commits' ? w.files : [], actualSymbols: [], actualTests: [],
22
+ window: window } };
23
+ }
24
+ function firstCommitOf(w, rangeOf) {
25
+ if (w.kind !== 'commits')
26
+ return w;
27
+ const r = rangeOf(w.from, w.to);
28
+ if (!r.ok || r.commits.length === 0)
29
+ return w;
30
+ const first = r.commits[0];
31
+ return { kind: 'commits', from: w.from, to: w.to, shas: [first.sha], files: [...new Set(first.files)].sort((x, y) => x.localeCompare(y)) };
32
+ }
33
+ function replayWindows(artifacts, rangeOf, opts = {}) {
34
+ const sorted = (0, outcome_windows_1.byTime)(artifacts);
35
+ const memo = new Map();
36
+ const range = (from, to) => {
37
+ const k = `${from}..${to}`;
38
+ if (!memo.has(k))
39
+ memo.set(k, rangeOf(from, to));
40
+ return memo.get(k);
41
+ };
42
+ const run = (choose) => {
43
+ const closed = [];
44
+ let pending = 0, failed = 0, merged = 0;
45
+ sorted.forEach((a, i) => {
46
+ const c = choose(a, i);
47
+ if (c.merged) {
48
+ merged++;
49
+ return;
50
+ }
51
+ const w = c.window;
52
+ if (w.kind === 'pending') {
53
+ pending++;
54
+ return;
55
+ }
56
+ if (w.kind === 'failed') {
57
+ failed++;
58
+ return;
59
+ }
60
+ closed.push(closedOn(a, w));
61
+ });
62
+ return { scores: (0, outcome_windows_1.fileScores)(closed, opts), pending, failed, merged };
63
+ };
64
+ const headToHead = (a) => (0, outcome_windows_1.decideWindow)(a, (0, outcome_windows_1.nextAnalysis)(sorted, a), range);
65
+ const heads = new Set(sorted.map((a) => a.graphBasis?.head).filter((h) => typeof h === 'string'));
66
+ return {
67
+ inputs: {
68
+ artifacts: sorted.length,
69
+ digest: `sha256:${(0, node_crypto_1.createHash)('sha256').update(sorted.map((a) => a.digest).sort().join('\n')).digest('hex')}`,
70
+ heads: heads.size,
71
+ },
72
+ choices: {
73
+ 'first-commit': run((a) => ({ window: firstCommitOf(headToHead(a), range) })),
74
+ 'head-to-head': run((a) => ({ window: headToHead(a) })),
75
+ 'merged-same-request': run((a, i) => {
76
+ const prev = i > 0 ? sorted[i - 1] : undefined;
77
+ if (prev && typeof a.request === 'string' && prev.request === a.request)
78
+ return { merged: true };
79
+ const t = Date.parse(a.recordedAt);
80
+ const next = sorted.find((b) => Date.parse(b.recordedAt) > t && !(typeof a.request === 'string' && b.request === a.request));
81
+ return { window: (0, outcome_windows_1.decideWindow)(a, next, range) };
82
+ }),
83
+ },
84
+ };
85
+ }
@@ -0,0 +1,136 @@
1
+ /**
2
+ * The window of one persisted analysis, and the split score of its prediction.
3
+ *
4
+ * A-SPEC-578.17 replaced test_run's practice of attaching its whole change set to every open analysis (105–138
5
+ * actual files per analysis in 2026-11). Its reviews (2026-11-14, 0/5/9) found the replacement measured a fragment:
6
+ * the first commit after an analysis is one commit of a spec → RED → GREEN flow. A-SPEC-578.18 therefore takes the
7
+ * answer from git, not a clock: every commit between the analysis's HEAD and the next persisted analysis's HEAD
8
+ * (`graphBasis.head` of both), read only once that next analysis exists — so a run at any time writes what the replay
9
+ * rebuilds. A git failure closes nothing; "not a repository", a missing or rewritten HEAD and a range wider than the
10
+ * cap close as unattributable, never as a score.
11
+ *
12
+ * Pure except `projectGit`, the default git (through `gitOnce`: the shared environment and the blocked-root memory).
13
+ */
14
+ import type { EvidenceArtifact, UnattributableReason } from './evidence-artifact';
15
+ /** A range with more commits than this is unattributable: read whole or not at all, never truncated. */
16
+ export declare const WINDOW_COMMITS_MAX = 500;
17
+ /** What a project scores by default leaves out besides `.ax/` (configurable as `calibration.unscoredPaths`). */
18
+ export declare const DEFAULT_UNSCORED: readonly string[];
19
+ export interface GitAnswer {
20
+ status: number | null;
21
+ stdout: string;
22
+ stderr: string;
23
+ error?: {
24
+ code?: string;
25
+ };
26
+ }
27
+ export type Git = (args: string[]) => GitAnswer;
28
+ export type WindowDecision = {
29
+ kind: 'commits';
30
+ from: string;
31
+ to: string;
32
+ shas: string[];
33
+ files: string[];
34
+ } | {
35
+ kind: 'superseded';
36
+ by: string;
37
+ sameRequest: boolean | null;
38
+ } | {
39
+ kind: 'unattributable';
40
+ reason: UnattributableReason;
41
+ } | {
42
+ kind: 'pending';
43
+ } | {
44
+ kind: 'failed';
45
+ why: string;
46
+ };
47
+ export type RangeResult = {
48
+ ok: true;
49
+ commits: Array<{
50
+ sha: string;
51
+ files: string[];
52
+ }>;
53
+ } | {
54
+ ok: false;
55
+ unattributable: Exclude<UnattributableReason, 'no-head'>;
56
+ } | {
57
+ ok: false;
58
+ failed: string;
59
+ };
60
+ /** The project's git: run in the project root, so `--relative` and `-- .` mean the project, not the repository. */
61
+ export declare function projectGit(root: string): Git;
62
+ /** `git log -z --name-only --format=%x1e%H%x1f%cI` → commits, as git printed them; one naming no file is skipped. */
63
+ export declare function parseGitLogZ(text: string): Array<{
64
+ sha: string;
65
+ files: string[];
66
+ }>;
67
+ /**
68
+ * The commits in `from..to` that touch the project, oldest first. `from` must be an ancestor of `to` (otherwise the
69
+ * two analyses were on different lines of history, or a HEAD was rewritten: `diverged`); the count is read before the
70
+ * log so a range over the cap is refused, not cut.
71
+ */
72
+ export declare function rangeFiles(git: Git, from: string, to: string): RangeResult;
73
+ /** Whether two analyses asked the same thing: null when either did not record its request. */
74
+ export declare function sameRequest(a: EvidenceArtifact, b: EvidenceArtifact): boolean | null;
75
+ /** The persisted analysis recorded next after `a` (open or closed), by time; undefined when `a` is the last. */
76
+ export declare function nextAnalysis(sorted: readonly EvidenceArtifact[], a: EvidenceArtifact): EvidenceArtifact | undefined;
77
+ /** Sorted by recorded time, then digest — the one order every reader of the windows uses. */
78
+ export declare function byTime(all: readonly EvidenceArtifact[]): EvidenceArtifact[];
79
+ /** The window of `a` given the analysis that ends it; `rangeOf` reads git. */
80
+ export declare function decideWindow(a: EvidenceArtifact, next: EvidenceArtifact | undefined, rangeOf: (from: string, to: string) => RangeResult): WindowDecision;
81
+ /** The window of every analysis in `open`, ended by the next analysis in `all`. */
82
+ export declare function windowsFor(all: readonly EvidenceArtifact[], open: readonly EvidenceArtifact[], git: Git): Map<string, WindowDecision>;
83
+ /** `.ax/` is never scorable; the rest by `unscored`: `dir/` a prefix, `*.ext` a suffix, anything else an exact path. */
84
+ export declare function isScorable(file: string, unscored?: readonly string[]): boolean;
85
+ export interface Cut {
86
+ recall: number;
87
+ precision: number;
88
+ }
89
+ export interface NullableCut {
90
+ recall: number | null;
91
+ precision: number | null;
92
+ }
93
+ export interface OutcomeScore {
94
+ source: {
95
+ at10: Cut;
96
+ ranked: Cut | null;
97
+ ceiling: number;
98
+ } | null;
99
+ tests: Cut | null;
100
+ }
101
+ export interface FileScores {
102
+ windows: {
103
+ commits: number;
104
+ superseded: {
105
+ sameRequest: number;
106
+ otherRequest: number;
107
+ unknown: number;
108
+ };
109
+ unattributable: Partial<Record<UnattributableReason, number>>;
110
+ unwindowed: number;
111
+ };
112
+ scored: number;
113
+ noScorable: number;
114
+ at10: {
115
+ macro: NullableCut;
116
+ micro: NullableCut;
117
+ ceiling: number | null;
118
+ };
119
+ rankedN: number;
120
+ ranked: {
121
+ macro: NullableCut;
122
+ micro: NullableCut;
123
+ };
124
+ testsN: number;
125
+ tests: {
126
+ macro: NullableCut;
127
+ micro: NullableCut;
128
+ };
129
+ }
130
+ export interface ScoreOptions {
131
+ unscored?: readonly string[];
132
+ }
133
+ /** Source files against `predicted.files` (and `rankedFiles`), test files against `predicted.tests`. */
134
+ export declare function scoreOutcome(a: EvidenceArtifact, opts?: ScoreOptions): OutcomeScore;
135
+ /** Counts per window kind and reason, and macro and micro averages over the `commits` windows. */
136
+ export declare function fileScores(artifacts: readonly EvidenceArtifact[], opts?: ScoreOptions): FileScores;