@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.
- package/CHANGELOG.md +40 -0
- package/README.md +29 -5
- package/bin/holmes-mcp.js +36 -1
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/claude-switches.d.ts +9 -0
- package/dist/holmes/cli/claude-switches.js +11 -8
- package/dist/holmes/cli/doctor.d.ts +7 -1
- package/dist/holmes/cli/doctor.js +63 -20
- package/dist/holmes/cli/holmes-hook-id.d.ts +9 -0
- package/dist/holmes/cli/holmes-hook-id.js +22 -0
- package/dist/holmes/cli/hook-failure-posture.d.ts +44 -0
- package/dist/holmes/cli/hook-failure-posture.js +65 -0
- package/dist/holmes/cli/index.js +3 -1
- package/dist/holmes/cli/init.d.ts +6 -0
- package/dist/holmes/cli/init.js +151 -3
- package/dist/holmes/cli/native-deps.d.ts +10 -4
- package/dist/holmes/cli/native-deps.js +30 -29
- package/dist/holmes/cli/release-history.d.ts +21 -0
- package/dist/holmes/cli/release-history.js +116 -0
- package/dist/holmes/cli/run-wiring.js +4 -2
- package/dist/holmes/cli/runtime-binding.d.ts +24 -0
- package/dist/holmes/cli/runtime-binding.js +67 -25
- package/dist/holmes/cli/settings-merge.d.ts +3 -2
- package/dist/holmes/cli/settings-merge.js +11 -9
- package/dist/holmes/config/config.d.ts +6 -0
- package/dist/holmes/config/config.js +23 -3
- package/dist/holmes/config/judgement-keys.d.ts +20 -0
- package/dist/holmes/config/judgement-keys.js +100 -0
- package/dist/holmes/config/project-caps.js +3 -2
- package/dist/holmes/governance/autonomous-shell.js +1 -1
- package/dist/holmes/governance/autonomy.d.ts +27 -1
- package/dist/holmes/governance/autonomy.js +126 -6
- package/dist/holmes/governance/wiring-receipt.d.ts +7 -0
- package/dist/holmes/governance/wiring-receipt.js +84 -0
- package/dist/holmes/guardrail/cli-root.d.ts +31 -0
- package/dist/holmes/guardrail/cli-root.js +261 -0
- package/dist/holmes/guardrail/command-traits.d.ts +2 -0
- package/dist/holmes/guardrail/command-traits.js +26 -1
- package/dist/holmes/guardrail/impact-gate.d.ts +17 -1
- package/dist/holmes/guardrail/impact-gate.js +44 -5
- package/dist/holmes/guardrail/outward-acts.js +10 -3
- package/dist/holmes/guardrail/package-manager-acts.d.ts +41 -0
- package/dist/holmes/guardrail/package-manager-acts.js +1298 -0
- package/dist/holmes/guardrail/refusal-codes.js +9 -1
- package/dist/holmes/guardrail/shell-syntax.d.ts +3 -0
- package/dist/holmes/guardrail/shell-syntax.js +7 -2
- package/dist/holmes/guardrail/write-target.d.ts +20 -0
- package/dist/holmes/guardrail/write-target.js +168 -2
- package/dist/holmes/hooks/pre-tool-use.d.ts +110 -3
- package/dist/holmes/hooks/pre-tool-use.js +1208 -60
- package/dist/holmes/mcp/evidence-artifact.d.ts +112 -0
- package/dist/holmes/mcp/evidence-artifact.js +2 -0
- package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +2 -1
- package/dist/holmes/mcp/handlers/maintenance-evidence.js +24 -2
- package/dist/holmes/mcp/handlers/operator-inspection.d.ts +1 -1
- package/dist/holmes/mcp/handlers/operator-inspection.js +2 -2
- package/dist/holmes/mcp/handlers/requirement-triage.d.ts +1 -1
- package/dist/holmes/mcp/handlers/requirement-triage.js +3 -2
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +1 -1
- package/dist/holmes/mcp/handlers/spec-approval.js +6 -6
- package/dist/holmes/mcp/handlers/test-execution.d.ts +8 -0
- package/dist/holmes/mcp/handlers/test-execution.js +12 -6
- package/dist/holmes/mcp/handlers.d.ts +16 -7
- package/dist/holmes/mcp/maintenance-evidence.d.ts +11 -82
- package/dist/holmes/mcp/maintenance-evidence.js +57 -2
- package/dist/holmes/mcp/outcome-replay.d.ts +18 -0
- package/dist/holmes/mcp/outcome-replay.js +85 -0
- package/dist/holmes/mcp/outcome-windows.d.ts +136 -0
- package/dist/holmes/mcp/outcome-windows.js +236 -0
- package/dist/holmes/mcp/tool-schemas.js +1 -1
- package/dist/holmes/project/hook-specs-arg.d.ts +4 -0
- package/dist/holmes/project/hook-specs-arg.js +39 -0
- package/dist/holmes/project/install-layout.d.ts +11 -0
- package/dist/holmes/project/install-layout.js +109 -0
- package/dist/holmes/project/install-scripts-policy.d.ts +4 -1
- package/dist/holmes/project/install-scripts-policy.js +6 -3
- package/dist/holmes/project/native-recovery.d.ts +29 -0
- package/dist/holmes/project/native-recovery.js +62 -0
- package/dist/holmes/project/root.d.ts +6 -0
- package/dist/holmes/project/root.js +15 -3
- package/dist/holmes/project/wiring-receipt-format.d.ts +20 -0
- package/dist/holmes/project/wiring-receipt-format.js +42 -0
- package/dist/holmes/project/workspace-preflight.d.ts +9 -0
- package/dist/holmes/project/workspace-preflight.js +40 -1
- package/dist/holmes/review/classification-replay.d.ts +53 -0
- package/dist/holmes/review/classification-replay.js +78 -0
- package/dist/holmes/review/head-worktree.js +5 -4
- package/dist/holmes/review/run-provenance.js +3 -2
- package/dist/holmes/review/test-evidence.js +2 -2
- package/dist/holmes/review/test-outcomes.js +3 -1
- package/dist/holmes/rtm/graph-store.d.ts +5 -0
- package/dist/holmes/rtm/graph-store.js +12 -4
- package/dist/holmes/rtm/native-driver.d.ts +42 -0
- package/dist/holmes/rtm/native-driver.js +147 -0
- package/dist/holmes/rtm/rtm-graph.js +11 -2
- package/dist/holmes/runtime/dispatch.d.ts +6 -0
- package/dist/holmes/runtime/dispatch.js +51 -2
- package/dist/holmes/runtime/hook-process.d.ts +6 -0
- package/dist/holmes/runtime/hook-process.js +3 -3
- package/dist/holmes/update/semver-strict.d.ts +3 -0
- package/dist/holmes/update/semver-strict.js +58 -0
- package/docs/install-guide.md +8 -1
- package/package.json +3 -2
- package/playbooks/tdd-slice/PLAYBOOK.md +1 -1
- 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
|
|
15
|
-
|
|
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
|
-
|
|
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;
|