@holmes-lab/holmes-kit 0.35.9 → 0.35.11
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 +89 -0
- package/README.md +1 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/cpg/cpg-scanner.d.ts +10 -0
- package/dist/holmes/cpg/cpg-scanner.js +37 -3
- package/dist/holmes/cpg/scan-cache.d.ts +1 -1
- package/dist/holmes/cpg/scan-cache.js +6 -1
- package/dist/holmes/cpg/scanned-file.d.ts +42 -0
- package/dist/holmes/cpg/ts-call-resolution.d.ts +46 -0
- package/dist/holmes/cpg/ts-call-resolution.js +252 -0
- package/dist/holmes/governance/constitution.d.ts +5 -0
- package/dist/holmes/governance/constitution.js +1 -1
- package/dist/holmes/hooks/stop.d.ts +28 -0
- package/dist/holmes/hooks/stop.js +69 -6
- package/dist/holmes/mcp/handlers/graph-operations.js +9 -3
- package/dist/holmes/mcp/handlers/requirement-triage.d.ts +29 -4
- package/dist/holmes/mcp/handlers/requirement-triage.js +51 -4
- package/dist/holmes/mcp/handlers.d.ts +14 -4
- package/dist/holmes/mcp/handlers.js +9 -2
- package/dist/holmes/mcp/maintenance-analyze.d.ts +8 -0
- package/dist/holmes/mcp/maintenance-analyze.js +69 -4
- package/dist/holmes/review/graph-resolution.d.ts +61 -0
- package/dist/holmes/review/graph-resolution.js +158 -0
- package/dist/holmes/review/requirement-triage.js +3 -2
- package/dist/holmes/review/run-replay.d.ts +49 -0
- package/dist/holmes/review/run-replay.js +132 -13
- package/dist/holmes/review/semantic-retrieval.d.ts +2 -0
- package/dist/holmes/review/semantic-retrieval.js +4 -1
- package/dist/holmes/rtm/anchor-binding.d.ts +34 -0
- package/dist/holmes/rtm/anchor-binding.js +43 -0
- package/dist/holmes/rtm/anchor-history.d.ts +39 -0
- package/dist/holmes/rtm/anchor-history.js +97 -0
- package/dist/holmes/rtm/anchor-ids.d.ts +21 -0
- package/dist/holmes/rtm/anchor-ids.js +51 -5
- package/dist/holmes/rtm/localize.d.ts +7 -0
- package/dist/holmes/rtm/localize.js +11 -2
- package/dist/holmes/rtm/rtm-builder.d.ts +12 -0
- package/dist/holmes/rtm/rtm-builder.js +64 -2
- package/dist/holmes/rtm/rtm-graph.d.ts +11 -0
- package/dist/holmes/rtm/rtm-graph.js +20 -0
- package/package.json +1 -1
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
export interface GraphRows {
|
|
2
|
+
nodes: Array<{
|
|
3
|
+
id: string;
|
|
4
|
+
kind: string;
|
|
5
|
+
sourcePath: string | null;
|
|
6
|
+
}>;
|
|
7
|
+
edges: Array<{
|
|
8
|
+
src: string;
|
|
9
|
+
dst: string;
|
|
10
|
+
rel: string;
|
|
11
|
+
derivation: string | null;
|
|
12
|
+
observedAt: string | null;
|
|
13
|
+
validUntil: string | null;
|
|
14
|
+
evidenceDigest: string | null;
|
|
15
|
+
}>;
|
|
16
|
+
}
|
|
17
|
+
export interface GraphResolution {
|
|
18
|
+
nodesByKind: Record<string, number>;
|
|
19
|
+
edgesByRel: Record<string, number>;
|
|
20
|
+
specLink: {
|
|
21
|
+
linkedSymbols: number;
|
|
22
|
+
filesWithTwoOrMore: number;
|
|
23
|
+
uniformFiles: number;
|
|
24
|
+
uniformShare: number | null;
|
|
25
|
+
specsPerSymbolMedian: number | null;
|
|
26
|
+
specsPerSymbolMax: number | null;
|
|
27
|
+
siteBoundEdges: number;
|
|
28
|
+
};
|
|
29
|
+
verification: {
|
|
30
|
+
caseNodes: number;
|
|
31
|
+
criterionNodes: number;
|
|
32
|
+
executesEdges: number;
|
|
33
|
+
verifiesEdges: number;
|
|
34
|
+
};
|
|
35
|
+
calls: {
|
|
36
|
+
resolved: number;
|
|
37
|
+
ambiguous: number;
|
|
38
|
+
ambiguousShare: number | null;
|
|
39
|
+
};
|
|
40
|
+
flowEdges: number;
|
|
41
|
+
provenance: {
|
|
42
|
+
edges: number;
|
|
43
|
+
withObservedAt: number;
|
|
44
|
+
withValidUntil: number;
|
|
45
|
+
withEvidenceDigest: number;
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
export type GraphRowsRead = {
|
|
49
|
+
ok: true;
|
|
50
|
+
rows: GraphRows;
|
|
51
|
+
} | {
|
|
52
|
+
ok: false;
|
|
53
|
+
reason: 'missing' | 'not-a-graph-store';
|
|
54
|
+
};
|
|
55
|
+
export declare function graphResolution(rows: GraphRows): GraphResolution;
|
|
56
|
+
/**
|
|
57
|
+
* The rows of a graph store, read without ever writing to it. `fileMustExist` matters: the driver
|
|
58
|
+
* creates an empty database for an absent path, and an empty store would then read as "a graph with
|
|
59
|
+
* nothing in it" — the zero result this instrument must never report for a missing one.
|
|
60
|
+
*/
|
|
61
|
+
export declare function readGraphRows(dbPath: string): GraphRowsRead;
|
|
@@ -0,0 +1,158 @@
|
|
|
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
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
36
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
37
|
+
};
|
|
38
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
39
|
+
exports.graphResolution = graphResolution;
|
|
40
|
+
exports.readGraphRows = readGraphRows;
|
|
41
|
+
// @implements A-SPEC-755
|
|
42
|
+
/**
|
|
43
|
+
* How far a built traceability graph is from the resolution the design claims.
|
|
44
|
+
*
|
|
45
|
+
* Measured by hand on 2026-10-07: in 330 of 330 files with two or more symbols every symbol carried
|
|
46
|
+
* the identical spec set (the file's anchors copied onto each function), there was no node for a test
|
|
47
|
+
* case or a success criterion, 41% of call edges were ambiguous and no edge carried an observation
|
|
48
|
+
* time, a validity bound or an evidence digest. Those numbers came from throw-away scripts; this is
|
|
49
|
+
* the same measurement with its definitions fixed in A-SPEC-755, so a later change to the graph is
|
|
50
|
+
* judged by it and not by a node count.
|
|
51
|
+
*
|
|
52
|
+
* Read-only by construction: the census is pure, and the reader opens the store read-only.
|
|
53
|
+
*/
|
|
54
|
+
const fs = __importStar(require("node:fs"));
|
|
55
|
+
const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
|
|
56
|
+
const filled = (v) => v !== null && v !== '';
|
|
57
|
+
function graphResolution(rows) {
|
|
58
|
+
const nodesByKind = {};
|
|
59
|
+
const fileOfCode = new Map();
|
|
60
|
+
for (const n of rows.nodes) {
|
|
61
|
+
nodesByKind[n.kind] = (nodesByKind[n.kind] ?? 0) + 1;
|
|
62
|
+
if (n.kind === 'CODE')
|
|
63
|
+
fileOfCode.set(n.id, n.sourcePath);
|
|
64
|
+
}
|
|
65
|
+
const edgesByRel = {};
|
|
66
|
+
// Targets per linked symbol. A Set, so an edge stated twice does not make two symbols look different.
|
|
67
|
+
const specsOfSymbol = new Map();
|
|
68
|
+
let siteBoundEdges = 0, withObservedAt = 0, withValidUntil = 0, withEvidenceDigest = 0;
|
|
69
|
+
for (const e of rows.edges) {
|
|
70
|
+
edgesByRel[e.rel] = (edgesByRel[e.rel] ?? 0) + 1;
|
|
71
|
+
if (filled(e.observedAt))
|
|
72
|
+
withObservedAt++;
|
|
73
|
+
if (filled(e.validUntil))
|
|
74
|
+
withValidUntil++;
|
|
75
|
+
if (filled(e.evidenceDigest))
|
|
76
|
+
withEvidenceDigest++;
|
|
77
|
+
// An edge whose source is not a CODE node in these rows has no file to be attributed to.
|
|
78
|
+
if (e.rel !== 'implements' || !fileOfCode.has(e.src))
|
|
79
|
+
continue;
|
|
80
|
+
if (e.derivation === 'anchor-site')
|
|
81
|
+
siteBoundEdges++;
|
|
82
|
+
const set = specsOfSymbol.get(e.src);
|
|
83
|
+
if (set)
|
|
84
|
+
set.add(e.dst);
|
|
85
|
+
else
|
|
86
|
+
specsOfSymbol.set(e.src, new Set([e.dst]));
|
|
87
|
+
}
|
|
88
|
+
// Per file: the distinct spec sets its linked symbols carry. One distinct set = the file is uniform.
|
|
89
|
+
const setsOfFile = new Map();
|
|
90
|
+
const sizes = [];
|
|
91
|
+
for (const [id, set] of specsOfSymbol) {
|
|
92
|
+
sizes.push(set.size);
|
|
93
|
+
const file = fileOfCode.get(id) ?? null;
|
|
94
|
+
const entry = setsOfFile.get(file) ?? { symbols: 0, distinct: new Set() };
|
|
95
|
+
entry.symbols++;
|
|
96
|
+
entry.distinct.add([...set].sort().join('\n'));
|
|
97
|
+
setsOfFile.set(file, entry);
|
|
98
|
+
}
|
|
99
|
+
let filesWithTwoOrMore = 0, uniformFiles = 0;
|
|
100
|
+
for (const entry of setsOfFile.values()) {
|
|
101
|
+
if (entry.symbols < 2)
|
|
102
|
+
continue;
|
|
103
|
+
filesWithTwoOrMore++;
|
|
104
|
+
if (entry.distinct.size === 1)
|
|
105
|
+
uniformFiles++;
|
|
106
|
+
}
|
|
107
|
+
sizes.sort((a, b) => a - b);
|
|
108
|
+
const count = (m, k) => m[k] ?? 0;
|
|
109
|
+
const resolved = count(edgesByRel, 'calls');
|
|
110
|
+
const ambiguous = count(edgesByRel, 'calls_ambiguous');
|
|
111
|
+
return {
|
|
112
|
+
nodesByKind, edgesByRel,
|
|
113
|
+
specLink: {
|
|
114
|
+
linkedSymbols: sizes.length,
|
|
115
|
+
filesWithTwoOrMore, uniformFiles,
|
|
116
|
+
uniformShare: filesWithTwoOrMore === 0 ? null : uniformFiles / filesWithTwoOrMore,
|
|
117
|
+
// Lower middle for an even count: a median that is always a value some symbol really has.
|
|
118
|
+
specsPerSymbolMedian: sizes.length === 0 ? null : sizes[Math.floor((sizes.length - 1) / 2)],
|
|
119
|
+
specsPerSymbolMax: sizes.length === 0 ? null : sizes[sizes.length - 1],
|
|
120
|
+
siteBoundEdges,
|
|
121
|
+
},
|
|
122
|
+
verification: {
|
|
123
|
+
caseNodes: count(nodesByKind, 'CASE'),
|
|
124
|
+
criterionNodes: count(nodesByKind, 'CRITERION') + count(nodesByKind, 'RULE'),
|
|
125
|
+
executesEdges: count(edgesByRel, 'executes'),
|
|
126
|
+
verifiesEdges: count(edgesByRel, 'verifies'),
|
|
127
|
+
},
|
|
128
|
+
calls: { resolved, ambiguous, ambiguousShare: resolved + ambiguous === 0 ? null : ambiguous / (resolved + ambiguous) },
|
|
129
|
+
flowEdges: count(edgesByRel, 'data_dep') + count(edgesByRel, 'control_dep'),
|
|
130
|
+
provenance: { edges: rows.edges.length, withObservedAt, withValidUntil, withEvidenceDigest },
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* The rows of a graph store, read without ever writing to it. `fileMustExist` matters: the driver
|
|
135
|
+
* creates an empty database for an absent path, and an empty store would then read as "a graph with
|
|
136
|
+
* nothing in it" — the zero result this instrument must never report for a missing one.
|
|
137
|
+
*/
|
|
138
|
+
function readGraphRows(dbPath) {
|
|
139
|
+
if (!fs.existsSync(dbPath))
|
|
140
|
+
return { ok: false, reason: 'missing' };
|
|
141
|
+
let db = null;
|
|
142
|
+
try {
|
|
143
|
+
db = new better_sqlite3_1.default(dbPath, { readonly: true, fileMustExist: true });
|
|
144
|
+
const nodes = db.prepare('SELECT id, kind, source_path AS sourcePath FROM nodes').all();
|
|
145
|
+
const edges = db.prepare(`SELECT src, dst, rel, derivation, observed_at AS observedAt, valid_until AS validUntil,
|
|
146
|
+
evidence_digest AS evidenceDigest FROM edges`).all();
|
|
147
|
+
return { ok: true, rows: { nodes, edges } };
|
|
148
|
+
}
|
|
149
|
+
catch {
|
|
150
|
+
return { ok: false, reason: 'not-a-graph-store' };
|
|
151
|
+
}
|
|
152
|
+
finally {
|
|
153
|
+
try {
|
|
154
|
+
db?.close();
|
|
155
|
+
}
|
|
156
|
+
catch { /* a handle that never opened has nothing to close */ }
|
|
157
|
+
}
|
|
158
|
+
}
|
|
@@ -4,7 +4,7 @@ exports.canonicalRequirementDocument = void 0;
|
|
|
4
4
|
exports.requestIdentifiers = requestIdentifiers;
|
|
5
5
|
exports.triageRequirements = triageRequirements;
|
|
6
6
|
exports.requirementSemanticCoverage = requirementSemanticCoverage;
|
|
7
|
-
// @implements A-SPEC-713.1, A-SPEC-713.2, A-SPEC-713.3, A-SPEC-713.4, A-SPEC-742, A-SPEC-713
|
|
7
|
+
// @implements A-SPEC-713.1, A-SPEC-713.2, A-SPEC-713.3, A-SPEC-713.4, A-SPEC-742, A-SPEC-713, A-SPEC-757
|
|
8
8
|
/** Pure, conservative lifecycle triage over governed requirement documents. */
|
|
9
9
|
const semantic_retrieval_1 = require("./semantic-retrieval");
|
|
10
10
|
const localize_1 = require("../rtm/localize");
|
|
@@ -92,7 +92,8 @@ function rankCompare(a, b, cited) {
|
|
|
92
92
|
return b.lexicalScore - a.lexicalScore || a.reqId.localeCompare(b.reqId);
|
|
93
93
|
}
|
|
94
94
|
function bm25(query, docs) {
|
|
95
|
-
|
|
95
|
+
// @implements A-SPEC-757 — the document form: `normalisedTerms` is the request's (distinct, first 64).
|
|
96
|
+
const terms = docs.map((text) => (0, semantic_retrieval_1.normalisedDocumentTerms)(text));
|
|
96
97
|
const avg = terms.reduce((n, row) => n + row.length, 0) / (terms.length || 1);
|
|
97
98
|
const df = new Map();
|
|
98
99
|
for (const row of terms)
|
|
@@ -1,6 +1,38 @@
|
|
|
1
1
|
import { evaluationMetrics, impactMetrics, ceilingMetrics } from './evaluation-metrics';
|
|
2
2
|
import { type ReplayCorpus } from './replay-corpus';
|
|
3
3
|
import { type PprArmConfig } from '../assoc/assoc-arm';
|
|
4
|
+
/** @implements A-SPEC-756.1 — one case under one anchor-binding arm, with the case's truth. */
|
|
5
|
+
/**
|
|
6
|
+
* @implements A-SPEC-758
|
|
7
|
+
* One impact case under one call-graph arm: `compiler` is the scored run (the scan as the scanner
|
|
8
|
+
* returns it), `name` the same scan with the compiler's record removed — the graph every earlier build
|
|
9
|
+
* produced. Same seed, same expected set, same request.
|
|
10
|
+
*/
|
|
11
|
+
export interface CallArmRow {
|
|
12
|
+
commit: string;
|
|
13
|
+
arm: 'compiler' | 'name';
|
|
14
|
+
/**
|
|
15
|
+
* `union`: the request alone — ranked candidates plus graded impact, scored against every truth file
|
|
16
|
+
* (`seed` is empty). `impact`: one truth file given as changed, scored against the others.
|
|
17
|
+
*/
|
|
18
|
+
surface: 'union' | 'impact';
|
|
19
|
+
seed: string;
|
|
20
|
+
expected: string[];
|
|
21
|
+
ranked: string[];
|
|
22
|
+
rankedImpact: string[];
|
|
23
|
+
impactedFiles: string[];
|
|
24
|
+
}
|
|
25
|
+
export interface AnchorArmRow {
|
|
26
|
+
commit: string;
|
|
27
|
+
arm: 'file' | 'site' | 'site+commit';
|
|
28
|
+
ranked: string[];
|
|
29
|
+
rankedSymbols: string[];
|
|
30
|
+
selectedTests: string[];
|
|
31
|
+
rankedImpact: string[];
|
|
32
|
+
truthFiles: string[];
|
|
33
|
+
truthSymbols: string[];
|
|
34
|
+
truthTests: string[];
|
|
35
|
+
}
|
|
4
36
|
/** One case, scored by both arms. Measurement only — never read by a pin. */
|
|
5
37
|
export interface PairedRow {
|
|
6
38
|
commit: string;
|
|
@@ -228,6 +260,19 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
|
|
|
228
260
|
* the 1-pass result; the dump carries the 2-pass (semantic-injected) output when
|
|
229
261
|
* productSemantic is present. The RUNNER owns blinding: truth goes to a separate file.
|
|
230
262
|
*/
|
|
263
|
+
/**
|
|
264
|
+
* @implements A-SPEC-756.1 — the anchor-binding arms, three rows per case: `file` (the scan
|
|
265
|
+
* with every site record removed — the graph as it was before anchors were bound to functions),
|
|
266
|
+
* `site` (the scan as the scanner returns it — the scored path itself) and `site+commit` (history
|
|
267
|
+
* binding over it, blame taken AT THE PARENT of the case, never at the answer). A callback, like
|
|
268
|
+
* the other measurement options: asking for it changes no scored metric and no existing row.
|
|
269
|
+
*/
|
|
270
|
+
anchorArms?: (row: AnchorArmRow) => void;
|
|
271
|
+
/**
|
|
272
|
+
* @implements A-SPEC-758 — the impact case of each commit under both call graphs. A callback like
|
|
273
|
+
* the others: asking for it changes no scored metric.
|
|
274
|
+
*/
|
|
275
|
+
callArms?: (row: CallArmRow) => void;
|
|
231
276
|
caseDump?: (row: {
|
|
232
277
|
commit: string;
|
|
233
278
|
subject: string;
|
|
@@ -243,6 +288,10 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
|
|
|
243
288
|
semCos?: number;
|
|
244
289
|
}>;
|
|
245
290
|
truthFiles: string[];
|
|
291
|
+
/** @implements A-SPEC-755.1 — the function axis as scored: truth from the parent-side changed
|
|
292
|
+
* lines, prediction from the scored (1-pass) candidates. Empty truth = outside that denominator. */
|
|
293
|
+
truthSymbols: string[];
|
|
294
|
+
rankedSymbols: string[];
|
|
246
295
|
/** @implements A-SPEC-489 — present only when dumpBodies was asked. */
|
|
247
296
|
bodies?: Record<string, string>;
|
|
248
297
|
/** @implements A-SPEC-567.2 — present only when judgementBundle was asked. */
|
|
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
36
36
|
exports.uncitedDiffs = uncitedDiffs;
|
|
37
37
|
exports.runReplay = runReplay;
|
|
38
38
|
exports.semanticCaseRanking = semanticCaseRanking;
|
|
39
|
-
// @implements A-SPEC-346, A-SPEC-734
|
|
39
|
+
// @implements A-SPEC-346, A-SPEC-734, A-SPEC-758
|
|
40
40
|
// @implements A-SPEC-347
|
|
41
41
|
// @implements A-SPEC-348
|
|
42
42
|
// @implements A-SPEC-349
|
|
@@ -83,6 +83,36 @@ const explore_1 = require("../assoc/explore");
|
|
|
83
83
|
const temporal_prior_1 = require("./temporal-prior");
|
|
84
84
|
const commit_text_1 = require("./commit-text");
|
|
85
85
|
const bounded_io_1 = require("../project/bounded-io");
|
|
86
|
+
// @implements A-SPEC-756.1 — the anchor-binding arms: file-level, place, place plus history.
|
|
87
|
+
const anchor_history_1 = require("../rtm/anchor-history");
|
|
88
|
+
/**
|
|
89
|
+
* @implements A-SPEC-756.1
|
|
90
|
+
* The newest commit at or before `rev` that touched each path of the corpus' source — one `git log`.
|
|
91
|
+
* It keys the blame memo: two cases whose parents agree on a path's last commit get the same blame.
|
|
92
|
+
* A path absent from the answer has no history git could list, and the caller keys it by `rev`.
|
|
93
|
+
*/
|
|
94
|
+
function lastTouchAt(corpus, rev) {
|
|
95
|
+
const out = new Map();
|
|
96
|
+
let raw;
|
|
97
|
+
try {
|
|
98
|
+
raw = (0, node_child_process_1.execFileSync)('git', ['-C', corpus.root, 'log', rev, '--format=%x1e%H', '--name-only', '--', ...corpus.sourcePathspec], { timeout: bounded_io_1.GIT_LONG_TIMEOUT_MS, encoding: 'utf8', maxBuffer: bounded_io_1.GIT_MAX_BUFFER, stdio: 'pipe' });
|
|
99
|
+
}
|
|
100
|
+
catch {
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
103
|
+
for (const block of raw.split('\x1e')) {
|
|
104
|
+
const lines = block.split('\n');
|
|
105
|
+
const commit = lines[0].trim();
|
|
106
|
+
if (commit === '')
|
|
107
|
+
continue;
|
|
108
|
+
for (const line of lines.slice(1)) {
|
|
109
|
+
const file = line.trim();
|
|
110
|
+
if (file !== '' && !out.has(file))
|
|
111
|
+
out.set(file, commit);
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
return out;
|
|
115
|
+
}
|
|
86
116
|
/**
|
|
87
117
|
* @implements A-SPEC-578.7
|
|
88
118
|
* The paired differences on the UNCITED axis, ready for `pairedPower`.
|
|
@@ -187,6 +217,9 @@ async function runReplay(corpus, limit, opts = {}) {
|
|
|
187
217
|
const unionCeilingCases = [];
|
|
188
218
|
let unmeasured = 0;
|
|
189
219
|
let casesWithoutSpecs = 0;
|
|
220
|
+
// @implements A-SPEC-756.1 — a blame is the same for every case whose parent sees the same last
|
|
221
|
+
// commit on that path, so it is kept across cases under exactly that key (path + last commit).
|
|
222
|
+
const blameMemo = new Map();
|
|
190
223
|
for (const c of cases) {
|
|
191
224
|
const dest = fs.mkdtempSync(path.join(os.tmpdir(), `replay-${c.commit.slice(0, 8)}-`));
|
|
192
225
|
const parent = `${c.commit}^`;
|
|
@@ -243,17 +276,19 @@ async function runReplay(corpus, limit, opts = {}) {
|
|
|
243
276
|
if (top > 0)
|
|
244
277
|
for (const h of ct)
|
|
245
278
|
commitTextBoost[h.file] = h.score / top;
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
279
|
+
// @implements A-SPEC-756.1 — parameterised by the scan and its graph, so an anchor-binding
|
|
280
|
+
// arm runs the SAME two-pass analysis as the scored path instead of a second copy of it.
|
|
281
|
+
const twoPassOn = (scannedOn, graphOn) => {
|
|
282
|
+
const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
|
|
283
|
+
request: c.subject, scanned: scannedOn, specs, graph: graphOn, testAnchors: anchors, history: [], changePrior, commitTextBoost,
|
|
284
|
+
groundTruth: { files: c.files, tests: c.tests },
|
|
285
|
+
basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
|
|
286
|
+
coverage: { scannedFiles: scannedOn.length, skippedFiles: [], unsupportedLanguages: [] },
|
|
287
|
+
defUse,
|
|
288
|
+
});
|
|
289
|
+
// @implements A-SPEC-573.4 — the same two-pass the handler runs, for the same reason the
|
|
290
|
+
// bench stopped filtering the boost on its own: what is measured has to be what ships.
|
|
291
|
+
const firstPass = analyzeWith();
|
|
257
292
|
const targets = firstPass.candidates.slice(0, defuse_bound_1.DEFUSE_TOP_FILES).map((x) => x.file);
|
|
258
293
|
if (targets.length === 0)
|
|
259
294
|
return firstPass;
|
|
@@ -271,7 +306,21 @@ async function runReplay(corpus, limit, opts = {}) {
|
|
|
271
306
|
catch { /* fail-open, per file */ }
|
|
272
307
|
}
|
|
273
308
|
return Object.keys(defUse).length === 0 ? firstPass : analyzeWith(defUse);
|
|
274
|
-
}
|
|
309
|
+
};
|
|
310
|
+
// @implements A-SPEC-758 — the `name` arm: this case's scan with the compiler's record removed,
|
|
311
|
+
// and the graph built from it. Built only when the arm is asked for.
|
|
312
|
+
const onNameGraph = (fn) => {
|
|
313
|
+
const byName = scanned.map((f) => { const { resolvedCalls: _calls, ...rest } = f; return rest; });
|
|
314
|
+
const g = new rtm_graph_1.RtmGraph();
|
|
315
|
+
try {
|
|
316
|
+
(0, rtm_builder_1.buildRtm)(specs, byName, g);
|
|
317
|
+
return fn(byName, g);
|
|
318
|
+
}
|
|
319
|
+
finally {
|
|
320
|
+
g.close();
|
|
321
|
+
}
|
|
322
|
+
};
|
|
323
|
+
const result = twoPassOn(scanned, graph);
|
|
275
324
|
const ranked = result.candidates.map((x) => x.file);
|
|
276
325
|
// @implements A-SPEC-578.7 — the power arm. Both recalls come from what already exists:
|
|
277
326
|
// the product's from `ranked` (never recomputed — recomputing is how a benchmark ends up
|
|
@@ -319,6 +368,45 @@ async function runReplay(corpus, limit, opts = {}) {
|
|
|
319
368
|
}
|
|
320
369
|
outcomes.push({ ranked, truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests,
|
|
321
370
|
truthSymbols, rankedSymbols });
|
|
371
|
+
// @implements A-SPEC-756.1 — the three anchor-binding arms on this case. The `site` arm IS
|
|
372
|
+
// the scored result above (same scan, same graph), so it is emitted from it, not re-run.
|
|
373
|
+
if (opts.anchorArms !== undefined) {
|
|
374
|
+
const symbolsOfResult = (r) => {
|
|
375
|
+
const out = [];
|
|
376
|
+
for (const cand of r.candidates)
|
|
377
|
+
for (const sy of cand.symbols)
|
|
378
|
+
if (!out.includes(sy))
|
|
379
|
+
out.push(sy);
|
|
380
|
+
return out;
|
|
381
|
+
};
|
|
382
|
+
const emit = (arm, r) => opts.anchorArms({
|
|
383
|
+
commit: c.commit, arm,
|
|
384
|
+
ranked: r.candidates.map((x) => x.file),
|
|
385
|
+
rankedSymbols: symbolsOfResult(r),
|
|
386
|
+
selectedTests: [...r.relevantTests],
|
|
387
|
+
rankedImpact: (r.impacts?.rankedImpact ?? []).map((x) => x.file),
|
|
388
|
+
truthFiles: [...c.files], truthSymbols: [...truthSymbols], truthTests: [...c.tests],
|
|
389
|
+
});
|
|
390
|
+
const onArm = (arm, scannedArm) => {
|
|
391
|
+
const g = new rtm_graph_1.RtmGraph();
|
|
392
|
+
try {
|
|
393
|
+
(0, rtm_builder_1.buildRtm)(specs, scannedArm, g);
|
|
394
|
+
emit(arm, twoPassOn(scannedArm, g));
|
|
395
|
+
}
|
|
396
|
+
finally {
|
|
397
|
+
g.close();
|
|
398
|
+
}
|
|
399
|
+
};
|
|
400
|
+
onArm('file', scanned.map((f) => { const { anchorSites: _sites, ...rest } = f; return rest; }));
|
|
401
|
+
emit('site', result);
|
|
402
|
+
const lastTouch = lastTouchAt(corpus, parent);
|
|
403
|
+
onArm('site+commit', (0, anchor_history_1.bindAnchorsByHistory)(scanned, (f) => {
|
|
404
|
+
const key = `${f.sourcePath}\u0000${lastTouch.get(f.sourcePath) ?? parent}`;
|
|
405
|
+
if (!blameMemo.has(key))
|
|
406
|
+
blameMemo.set(key, (0, anchor_history_1.gitBlameLines)(corpus.root, f.sourcePath, parent));
|
|
407
|
+
return blameMemo.get(key) ?? null;
|
|
408
|
+
}));
|
|
409
|
+
}
|
|
322
410
|
// @implements A-SPEC-487 — the dump: 2-pass with semantic injected when asked (vectors
|
|
323
411
|
// only for the files the 1-pass surfaced — the hot-path lookup contract holds), 1-pass
|
|
324
412
|
// otherwise. Nothing here feeds outcomes or any pin.
|
|
@@ -401,6 +489,9 @@ async function runReplay(corpus, limit, opts = {}) {
|
|
|
401
489
|
candidates: dumpResult.candidates,
|
|
402
490
|
rankedImpact: dumpResult.impacts?.rankedImpact ?? [],
|
|
403
491
|
truthFiles: c.files,
|
|
492
|
+
// @implements A-SPEC-755.1 — the SAME arrays the scored outcome above holds, never a
|
|
493
|
+
// second derivation: a paired before/after on the function axis must compare what was scored.
|
|
494
|
+
truthSymbols, rankedSymbols,
|
|
404
495
|
...(bodies !== undefined ? { bodies } : {}),
|
|
405
496
|
...(judgementBundle !== undefined ? { judgementBundle } : {}),
|
|
406
497
|
});
|
|
@@ -474,6 +565,18 @@ async function runReplay(corpus, limit, opts = {}) {
|
|
|
474
565
|
}
|
|
475
566
|
const unionList = [...new Set([...ranked, ...impacted])];
|
|
476
567
|
unionCases.push({ seed: '', expected: c.files, predicted: unionList });
|
|
568
|
+
// @implements A-SPEC-758 — the union surface (what a caller receives: ranked plus graded impact)
|
|
569
|
+
// under both call graphs.
|
|
570
|
+
if (opts.callArms !== undefined) {
|
|
571
|
+
const emitUnion = (arm, r) => opts.callArms({
|
|
572
|
+
commit: c.commit, arm, surface: 'union', seed: '', expected: [...c.files],
|
|
573
|
+
ranked: r.candidates.map((x) => x.file),
|
|
574
|
+
rankedImpact: (r.impacts?.rankedImpact ?? []).map((x) => x.file),
|
|
575
|
+
impactedFiles: [...(r.impacts?.impactedFiles ?? [])],
|
|
576
|
+
});
|
|
577
|
+
emitUnion('compiler', result);
|
|
578
|
+
onNameGraph((byName, g) => emitUnion('name', twoPassOn(byName, g)));
|
|
579
|
+
}
|
|
477
580
|
// @implements A-SPEC-493 — the ceiling rows: a strict superset of the union prediction.
|
|
478
581
|
if (opts.semanticArm?.gates === true) {
|
|
479
582
|
for (const k of UPA_KS) {
|
|
@@ -622,6 +725,22 @@ async function runReplay(corpus, limit, opts = {}) {
|
|
|
622
725
|
// @implements A-SPEC-469 — score the SHIPPED prediction surface (ablation must score
|
|
623
726
|
// what ships): the graded top-K, not the ungraded closure the gates keep.
|
|
624
727
|
impactCases.push({ seed, expected, predicted: (run.impacts?.rankedImpact ?? []).map((r) => r.file) });
|
|
728
|
+
// @implements A-SPEC-758 — the same impact case on the name-resolved call graph.
|
|
729
|
+
if (opts.callArms !== undefined) {
|
|
730
|
+
const emitCall = (arm, r) => opts.callArms({
|
|
731
|
+
commit: c.commit, arm, surface: 'impact', seed, expected: [...expected],
|
|
732
|
+
ranked: r.candidates.map((x) => x.file),
|
|
733
|
+
rankedImpact: (r.impacts?.rankedImpact ?? []).map((x) => x.file),
|
|
734
|
+
impactedFiles: [...(r.impacts?.impactedFiles ?? [])],
|
|
735
|
+
});
|
|
736
|
+
emitCall('compiler', run);
|
|
737
|
+
onNameGraph((byName, g) => emitCall('name', (0, maintenance_analyze_1.analyzeMaintenance)({
|
|
738
|
+
request: c.subject, scanned: byName, specs, graph: g, testAnchors: anchors, history: [],
|
|
739
|
+
changedFiles: [seed], changePrior, commitTextBoost,
|
|
740
|
+
basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
|
|
741
|
+
coverage: { scannedFiles: byName.length, skippedFiles: [], unsupportedLanguages: [] },
|
|
742
|
+
})));
|
|
743
|
+
}
|
|
625
744
|
// @implements A-SPEC-470 — the frozen string-property heuristic on the same case.
|
|
626
745
|
impactBaselineCases.push({ seed, expected,
|
|
627
746
|
predicted: (0, impact_baseline_1.impactBaselinePredict)(seed, scanned.map((f) => f.sourcePath)) });
|
|
@@ -8,6 +8,8 @@ import type { Spec } from '../spec/spec-parser';
|
|
|
8
8
|
*/
|
|
9
9
|
export declare function normaliseTerm(term: string): string;
|
|
10
10
|
export declare const normalisedTerms: (text: string) => string[];
|
|
11
|
+
/** @implements A-SPEC-757 — a document's terms: every occurrence, unbounded, through the same normaliser. */
|
|
12
|
+
export declare const normalisedDocumentTerms: (text: string) => string[];
|
|
11
13
|
export interface RankedSpec {
|
|
12
14
|
id: string;
|
|
13
15
|
score: number;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.normalisedTerms = void 0;
|
|
3
|
+
exports.normalisedDocumentTerms = exports.normalisedTerms = void 0;
|
|
4
4
|
exports.normaliseTerm = normaliseTerm;
|
|
5
5
|
exports.retrieveSpecs = retrieveSpecs;
|
|
6
6
|
exports.expandThroughGraph = expandThroughGraph;
|
|
@@ -74,6 +74,9 @@ function normaliseTerm(term) {
|
|
|
74
74
|
}
|
|
75
75
|
const normalisedTerms = (text) => (0, localize_1.significantTerms)(text).map(normaliseTerm);
|
|
76
76
|
exports.normalisedTerms = normalisedTerms;
|
|
77
|
+
/** @implements A-SPEC-757 — a document's terms: every occurrence, unbounded, through the same normaliser. */
|
|
78
|
+
const normalisedDocumentTerms = (text) => (0, localize_1.documentTerms)(text).map(normaliseTerm);
|
|
79
|
+
exports.normalisedDocumentTerms = normalisedDocumentTerms;
|
|
77
80
|
/**
|
|
78
81
|
* BM25 over A-SPEC documents.
|
|
79
82
|
*
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which function an anchor speaks about, judged by where it is written.
|
|
3
|
+
*
|
|
4
|
+
* Measured 2026-10-07: 2,816 of this repository's 3,793 anchor mentions sit inside or directly above
|
|
5
|
+
* the code they describe, and the graph builder threw that away — it added one edge per pair of
|
|
6
|
+
* symbol and spec in the FILE's list, so in 330 of 330 files every function carried the identical
|
|
7
|
+
* set. This is the place-based rule; the history-based one (A-SPEC-756.1) covers anchors written in
|
|
8
|
+
* a header, which is where the shipped guidance tells consumers to put them.
|
|
9
|
+
*/
|
|
10
|
+
export interface AnchorSite {
|
|
11
|
+
spec: string;
|
|
12
|
+
line: number;
|
|
13
|
+
}
|
|
14
|
+
export interface BoundAnchorSite extends AnchorSite {
|
|
15
|
+
symbol: string | null;
|
|
16
|
+
}
|
|
17
|
+
export interface SymbolRange {
|
|
18
|
+
qualifiedName: string;
|
|
19
|
+
startLine: number;
|
|
20
|
+
endLine: number;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Bind each site to a function, or to none.
|
|
24
|
+
*
|
|
25
|
+
* 1. Inside one or more symbols' ranges: the INNERMOST one — a note inside a method is about the
|
|
26
|
+
* method, not about the class around it.
|
|
27
|
+
* 2. Otherwise, in the comment block directly above a symbol: every line strictly between the
|
|
28
|
+
* site and the symbol's first line is blank or comment. One line of code in between and the
|
|
29
|
+
* comment was about that code, not about the function further down.
|
|
30
|
+
* 3. Otherwise none. A header anchor above the imports is a statement about the file.
|
|
31
|
+
*
|
|
32
|
+
* `lines[i]` is line `i + 1`. Pure: same text, same ranges, same answer.
|
|
33
|
+
*/
|
|
34
|
+
export declare function bindAnchorSites(lines: readonly string[], symbols: readonly SymbolRange[], sites: readonly AnchorSite[]): BoundAnchorSite[];
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.bindAnchorSites = bindAnchorSites;
|
|
4
|
+
/** Blank, or a line that only continues or opens a comment — the lines a doc block is made of. */
|
|
5
|
+
const COMMENT_OR_BLANK = /^\s*(?:$|\/\/|\/\*|\*|#|"""|''')/;
|
|
6
|
+
/**
|
|
7
|
+
* Bind each site to a function, or to none.
|
|
8
|
+
*
|
|
9
|
+
* 1. Inside one or more symbols' ranges: the INNERMOST one — a note inside a method is about the
|
|
10
|
+
* method, not about the class around it.
|
|
11
|
+
* 2. Otherwise, in the comment block directly above a symbol: every line strictly between the
|
|
12
|
+
* site and the symbol's first line is blank or comment. One line of code in between and the
|
|
13
|
+
* comment was about that code, not about the function further down.
|
|
14
|
+
* 3. Otherwise none. A header anchor above the imports is a statement about the file.
|
|
15
|
+
*
|
|
16
|
+
* `lines[i]` is line `i + 1`. Pure: same text, same ranges, same answer.
|
|
17
|
+
*/
|
|
18
|
+
function bindAnchorSites(lines, symbols, sites) {
|
|
19
|
+
const byStart = [...symbols].sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine);
|
|
20
|
+
return sites.map((site) => {
|
|
21
|
+
let inner = null;
|
|
22
|
+
for (const s of byStart) {
|
|
23
|
+
if (s.startLine > site.line)
|
|
24
|
+
break;
|
|
25
|
+
if (s.endLine < site.line)
|
|
26
|
+
continue;
|
|
27
|
+
const span = s.endLine - s.startLine;
|
|
28
|
+
// Smaller range wins; on a tie the later start (visited later) is the more deeply nested one.
|
|
29
|
+
if (inner === null || span <= inner.endLine - inner.startLine)
|
|
30
|
+
inner = s;
|
|
31
|
+
}
|
|
32
|
+
if (inner !== null)
|
|
33
|
+
return { ...site, symbol: inner.qualifiedName };
|
|
34
|
+
const next = byStart.find((s) => s.startLine > site.line);
|
|
35
|
+
if (next === undefined)
|
|
36
|
+
return { ...site, symbol: null };
|
|
37
|
+
for (let ln = site.line + 1; ln < next.startLine; ln++) {
|
|
38
|
+
if (!COMMENT_OR_BLANK.test(lines[ln - 1] ?? ''))
|
|
39
|
+
return { ...site, symbol: null };
|
|
40
|
+
}
|
|
41
|
+
return { ...site, symbol: next.qualifiedName };
|
|
42
|
+
});
|
|
43
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which functions an anchor speaks about, judged by the commit that introduced it.
|
|
3
|
+
*
|
|
4
|
+
* Place binds an anchor written in or above a function (A-SPEC-756). It cannot bind an anchor
|
|
5
|
+
* written in a file's header — and the header is where the shipped guidance tells people to put
|
|
6
|
+
* them: measured 2026-10-07, 7 of 1,702 anchor sites on the second corpus sit at a function. History
|
|
7
|
+
* can: 88% to 94% of recent source commits on both corpora add an anchor line, and the functions
|
|
8
|
+
* whose lines such a commit last touched are the ones it wrote for that spec. One `git blame` per
|
|
9
|
+
* file answers both halves — which commit introduced the anchor line, and which functions still
|
|
10
|
+
* hold lines of that commit.
|
|
11
|
+
*
|
|
12
|
+
* OBSERVED, not declared: the edge says "the commit that brought this anchor wrote these functions".
|
|
13
|
+
* It decays honestly — a function rewritten by a later commit stops matching.
|
|
14
|
+
*/
|
|
15
|
+
import type { ScannedFile } from '../cpg/scanned-file';
|
|
16
|
+
export interface BlameLine {
|
|
17
|
+
commit: string;
|
|
18
|
+
text: string;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Bind every site that place left unbound to the functions its introducing commit last touched.
|
|
22
|
+
*
|
|
23
|
+
* A site stays unbound when its line is not committed yet, when the commit touched no function, or
|
|
24
|
+
* when it touched EVERY function of a file with two or more — "this commit wrote the whole file" is
|
|
25
|
+
* a statement about the file, and recording it on each function would only relabel the copy.
|
|
26
|
+
*
|
|
27
|
+
* `blameOf` is asked only for a file that has an unbound site. A `null` answer, or a blame shorter
|
|
28
|
+
* than the site's line, leaves that file exactly as it came.
|
|
29
|
+
*/
|
|
30
|
+
export declare function bindAnchorsByHistory(scanned: readonly ScannedFile[], blameOf: (f: ScannedFile) => readonly BlameLine[] | null): ScannedFile[];
|
|
31
|
+
/**
|
|
32
|
+
* One `git blame` of a file: the commit that last touched each line, and the line's text.
|
|
33
|
+
*
|
|
34
|
+
* `-w` so a re-indent does not claim a function; `--line-porcelain` because its shape does not change
|
|
35
|
+
* with renames or boundary commits the way the human format's columns do. `rev` reads the file as it
|
|
36
|
+
* was at that revision — the replay uses the PARENT of the commit it scores, never the answer.
|
|
37
|
+
* `null` for anything that is not a tracked file in a repository git can read.
|
|
38
|
+
*/
|
|
39
|
+
export declare function gitBlameLines(root: string, sourcePath: string, rev?: string): BlameLine[] | null;
|