@holmes-lab/holmes-kit 0.35.10 → 0.35.12

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 (40) hide show
  1. package/CHANGELOG.md +95 -0
  2. package/README.md +2 -0
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cpg/cpg-scanner.d.ts +10 -0
  5. package/dist/holmes/cpg/cpg-scanner.js +37 -3
  6. package/dist/holmes/cpg/scan-cache.d.ts +1 -1
  7. package/dist/holmes/cpg/scan-cache.js +6 -1
  8. package/dist/holmes/cpg/scanned-file.d.ts +42 -0
  9. package/dist/holmes/cpg/ts-call-resolution.d.ts +46 -0
  10. package/dist/holmes/cpg/ts-call-resolution.js +252 -0
  11. package/dist/holmes/mcp/handlers/graph-operations.js +9 -3
  12. package/dist/holmes/mcp/handlers/maintenance-analysis.js +16 -1
  13. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +29 -4
  14. package/dist/holmes/mcp/handlers/requirement-triage.js +51 -4
  15. package/dist/holmes/mcp/handlers.d.ts +14 -4
  16. package/dist/holmes/mcp/handlers.js +9 -2
  17. package/dist/holmes/mcp/maintenance-analyze.d.ts +17 -0
  18. package/dist/holmes/mcp/maintenance-analyze.js +95 -5
  19. package/dist/holmes/review/co-change.d.ts +30 -0
  20. package/dist/holmes/review/co-change.js +69 -0
  21. package/dist/holmes/review/graph-resolution.d.ts +61 -0
  22. package/dist/holmes/review/graph-resolution.js +158 -0
  23. package/dist/holmes/review/requirement-triage.js +3 -2
  24. package/dist/holmes/review/run-replay.d.ts +49 -0
  25. package/dist/holmes/review/run-replay.js +138 -14
  26. package/dist/holmes/review/semantic-retrieval.d.ts +2 -0
  27. package/dist/holmes/review/semantic-retrieval.js +4 -1
  28. package/dist/holmes/rtm/anchor-binding.d.ts +34 -0
  29. package/dist/holmes/rtm/anchor-binding.js +43 -0
  30. package/dist/holmes/rtm/anchor-history.d.ts +39 -0
  31. package/dist/holmes/rtm/anchor-history.js +97 -0
  32. package/dist/holmes/rtm/anchor-ids.d.ts +21 -0
  33. package/dist/holmes/rtm/anchor-ids.js +51 -5
  34. package/dist/holmes/rtm/localize.d.ts +7 -0
  35. package/dist/holmes/rtm/localize.js +11 -2
  36. package/dist/holmes/rtm/rtm-builder.d.ts +12 -0
  37. package/dist/holmes/rtm/rtm-builder.js +64 -2
  38. package/dist/holmes/rtm/rtm-graph.d.ts +11 -0
  39. package/dist/holmes/rtm/rtm-graph.js +20 -0
  40. package/package.json +1 -1
@@ -0,0 +1,69 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CO_CHANGE_DEFAULTS = void 0;
4
+ exports.coChangeWeights = coChangeWeights;
5
+ exports.coChangeFromGit = coChangeFromGit;
6
+ exports.fuseRanked = fuseRanked;
7
+ // @implements A-SPEC-469.1
8
+ // Which files have changed together with these, how often, and how recently? Evolutionary coupling is
9
+ // the oldest evidence there is for "what else moves when I change this" (ROSE, 2004; combined with
10
+ // retrieval in Kagdi et al., 2010), and this repository had tried it once: twelve cases, as a
11
+ // threshold admitting candidates for a request. Measured 2026-10-07 as a RANKING for a named change,
12
+ // fused with the graph ranking: recall@10 0.337 -> 0.442 on the second corpus (n=79, MDE80 0.091),
13
+ // replicated on 93 further cases (+0.080, MDE80 0.064); no detectable loss on this repository.
14
+ const node_child_process_1 = require("node:child_process");
15
+ const bounded_io_1 = require("../project/bounded-io");
16
+ /** The values measured. Not tuned afterwards: a change here is a new measurement. */
17
+ exports.CO_CHANGE_DEFAULTS = { limit: 400, maxCommitFiles: 30, halfLife: 50 };
18
+ /**
19
+ * Recency-weighted co-change of every path with the seeds, from commits listed newest first.
20
+ * A commit that touches a seed adds `0.5^(age / halfLife)` to every other path it touches; `age` is
21
+ * the commit's position in the list. Seeds themselves are never returned.
22
+ */
23
+ function coChangeWeights(commits, seeds, opts = exports.CO_CHANGE_DEFAULTS) {
24
+ const seedSet = new Set(seeds);
25
+ const weights = new Map();
26
+ if (seedSet.size === 0)
27
+ return weights;
28
+ commits.slice(0, opts.limit).forEach((files, age) => {
29
+ if (files.length > opts.maxCommitFiles || !files.some((file) => seedSet.has(file)))
30
+ return;
31
+ const weight = Math.pow(0.5, age / opts.halfLife);
32
+ for (const file of new Set(files))
33
+ if (!seedSet.has(file))
34
+ weights.set(file, (weights.get(file) ?? 0) + weight);
35
+ });
36
+ return weights;
37
+ }
38
+ /**
39
+ * The same, read from git: the `limit` non-merge commits reachable from `before`, itself included and
40
+ * nothing after it. Unreadable history is an empty answer, never an error — the caller ranks without
41
+ * the signal.
42
+ */
43
+ function coChangeFromGit(root, before, seeds, opts = exports.CO_CHANGE_DEFAULTS) {
44
+ if (seeds.length === 0)
45
+ return new Map();
46
+ let raw;
47
+ try {
48
+ // `core.quotePath=false`: non-ASCII paths come out as themselves. A path holding a quote, a tab or
49
+ // a newline is still quoted by git; it then matches no scanned path and simply carries no weight.
50
+ raw = (0, node_child_process_1.execFileSync)('git', ['-C', root, '-c', 'core.quotePath=false', 'log', '--no-merges', `-${opts.limit}`, '--format=%x1e', '--name-only', before], { timeout: bounded_io_1.GIT_TIMEOUT_MS, encoding: 'utf8', maxBuffer: bounded_io_1.GIT_MAX_BUFFER, stdio: ['ignore', 'pipe', 'ignore'] });
51
+ }
52
+ catch {
53
+ return new Map();
54
+ }
55
+ const commits = raw.split('\x1e').slice(1)
56
+ .map((block) => block.split('\n').map((line) => line.trim()).filter((line) => line !== ''));
57
+ return coChangeWeights(commits, seeds, opts);
58
+ }
59
+ /**
60
+ * Reciprocal-rank fusion of two ranked lists (k = 60, the constant of the original paper, untuned):
61
+ * a file's score is the sum of 1 / (k + rank) over the lists that hold it. Ties keep path order.
62
+ */
63
+ function fuseRanked(a, b, k = 60) {
64
+ const score = new Map();
65
+ for (const list of [a, b])
66
+ list.forEach((file, i) => score.set(file, (score.get(file) ?? 0) + 1 / (k + i + 1)));
67
+ return [...score.entries()].map(([file, s]) => ({ file, score: s }))
68
+ .sort((x, y) => y.score - x.score || x.file.localeCompare(y.file));
69
+ }
@@ -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
- const terms = docs.map((text) => (0, semantic_retrieval_1.normalisedTerms)(text));
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, A-SPEC-469.1
40
40
  // @implements A-SPEC-347
41
41
  // @implements A-SPEC-348
42
42
  // @implements A-SPEC-349
@@ -81,8 +81,39 @@ const dense_retrieval_1 = require("./dense-retrieval");
81
81
  // @implements A-SPEC-472 — the three-arm iteration experiment (static / re-seed / judged).
82
82
  const explore_1 = require("../assoc/explore");
83
83
  const temporal_prior_1 = require("./temporal-prior");
84
+ const co_change_1 = require("./co-change");
84
85
  const commit_text_1 = require("./commit-text");
85
86
  const bounded_io_1 = require("../project/bounded-io");
87
+ // @implements A-SPEC-756.1 — the anchor-binding arms: file-level, place, place plus history.
88
+ const anchor_history_1 = require("../rtm/anchor-history");
89
+ /**
90
+ * @implements A-SPEC-756.1
91
+ * The newest commit at or before `rev` that touched each path of the corpus' source — one `git log`.
92
+ * It keys the blame memo: two cases whose parents agree on a path's last commit get the same blame.
93
+ * A path absent from the answer has no history git could list, and the caller keys it by `rev`.
94
+ */
95
+ function lastTouchAt(corpus, rev) {
96
+ const out = new Map();
97
+ let raw;
98
+ try {
99
+ 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' });
100
+ }
101
+ catch {
102
+ return out;
103
+ }
104
+ for (const block of raw.split('\x1e')) {
105
+ const lines = block.split('\n');
106
+ const commit = lines[0].trim();
107
+ if (commit === '')
108
+ continue;
109
+ for (const line of lines.slice(1)) {
110
+ const file = line.trim();
111
+ if (file !== '' && !out.has(file))
112
+ out.set(file, commit);
113
+ }
114
+ }
115
+ return out;
116
+ }
86
117
  /**
87
118
  * @implements A-SPEC-578.7
88
119
  * The paired differences on the UNCITED axis, ready for `pairedPower`.
@@ -187,6 +218,9 @@ async function runReplay(corpus, limit, opts = {}) {
187
218
  const unionCeilingCases = [];
188
219
  let unmeasured = 0;
189
220
  let casesWithoutSpecs = 0;
221
+ // @implements A-SPEC-756.1 — a blame is the same for every case whose parent sees the same last
222
+ // commit on that path, so it is kept across cases under exactly that key (path + last commit).
223
+ const blameMemo = new Map();
190
224
  for (const c of cases) {
191
225
  const dest = fs.mkdtempSync(path.join(os.tmpdir(), `replay-${c.commit.slice(0, 8)}-`));
192
226
  const parent = `${c.commit}^`;
@@ -243,17 +277,19 @@ async function runReplay(corpus, limit, opts = {}) {
243
277
  if (top > 0)
244
278
  for (const h of ct)
245
279
  commitTextBoost[h.file] = h.score / top;
246
- const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
247
- request: c.subject, scanned, specs, graph, testAnchors: anchors, history: [], changePrior, commitTextBoost,
248
- groundTruth: { files: c.files, tests: c.tests },
249
- basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
250
- coverage: { scannedFiles: scanned.length, skippedFiles: [], unsupportedLanguages: [] },
251
- defUse,
252
- });
253
- // @implements A-SPEC-573.4 — the same two-pass the handler runs, for the same reason the
254
- // bench stopped filtering the boost on its own: what is measured has to be what ships.
255
- const firstPass = analyzeWith();
256
- const result = (() => {
280
+ // @implements A-SPEC-756.1 — parameterised by the scan and its graph, so an anchor-binding
281
+ // arm runs the SAME two-pass analysis as the scored path instead of a second copy of it.
282
+ const twoPassOn = (scannedOn, graphOn) => {
283
+ const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
284
+ request: c.subject, scanned: scannedOn, specs, graph: graphOn, testAnchors: anchors, history: [], changePrior, commitTextBoost,
285
+ groundTruth: { files: c.files, tests: c.tests },
286
+ basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
287
+ coverage: { scannedFiles: scannedOn.length, skippedFiles: [], unsupportedLanguages: [] },
288
+ defUse,
289
+ });
290
+ // @implements A-SPEC-573.4 — the same two-pass the handler runs, for the same reason the
291
+ // bench stopped filtering the boost on its own: what is measured has to be what ships.
292
+ const firstPass = analyzeWith();
257
293
  const targets = firstPass.candidates.slice(0, defuse_bound_1.DEFUSE_TOP_FILES).map((x) => x.file);
258
294
  if (targets.length === 0)
259
295
  return firstPass;
@@ -271,7 +307,21 @@ async function runReplay(corpus, limit, opts = {}) {
271
307
  catch { /* fail-open, per file */ }
272
308
  }
273
309
  return Object.keys(defUse).length === 0 ? firstPass : analyzeWith(defUse);
274
- })();
310
+ };
311
+ // @implements A-SPEC-758 — the `name` arm: this case's scan with the compiler's record removed,
312
+ // and the graph built from it. Built only when the arm is asked for.
313
+ const onNameGraph = (fn) => {
314
+ const byName = scanned.map((f) => { const { resolvedCalls: _calls, ...rest } = f; return rest; });
315
+ const g = new rtm_graph_1.RtmGraph();
316
+ try {
317
+ (0, rtm_builder_1.buildRtm)(specs, byName, g);
318
+ return fn(byName, g);
319
+ }
320
+ finally {
321
+ g.close();
322
+ }
323
+ };
324
+ const result = twoPassOn(scanned, graph);
275
325
  const ranked = result.candidates.map((x) => x.file);
276
326
  // @implements A-SPEC-578.7 — the power arm. Both recalls come from what already exists:
277
327
  // the product's from `ranked` (never recomputed — recomputing is how a benchmark ends up
@@ -319,6 +369,45 @@ async function runReplay(corpus, limit, opts = {}) {
319
369
  }
320
370
  outcomes.push({ ranked, truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests,
321
371
  truthSymbols, rankedSymbols });
372
+ // @implements A-SPEC-756.1 — the three anchor-binding arms on this case. The `site` arm IS
373
+ // the scored result above (same scan, same graph), so it is emitted from it, not re-run.
374
+ if (opts.anchorArms !== undefined) {
375
+ const symbolsOfResult = (r) => {
376
+ const out = [];
377
+ for (const cand of r.candidates)
378
+ for (const sy of cand.symbols)
379
+ if (!out.includes(sy))
380
+ out.push(sy);
381
+ return out;
382
+ };
383
+ const emit = (arm, r) => opts.anchorArms({
384
+ commit: c.commit, arm,
385
+ ranked: r.candidates.map((x) => x.file),
386
+ rankedSymbols: symbolsOfResult(r),
387
+ selectedTests: [...r.relevantTests],
388
+ rankedImpact: (r.impacts?.rankedImpact ?? []).map((x) => x.file),
389
+ truthFiles: [...c.files], truthSymbols: [...truthSymbols], truthTests: [...c.tests],
390
+ });
391
+ const onArm = (arm, scannedArm) => {
392
+ const g = new rtm_graph_1.RtmGraph();
393
+ try {
394
+ (0, rtm_builder_1.buildRtm)(specs, scannedArm, g);
395
+ emit(arm, twoPassOn(scannedArm, g));
396
+ }
397
+ finally {
398
+ g.close();
399
+ }
400
+ };
401
+ onArm('file', scanned.map((f) => { const { anchorSites: _sites, ...rest } = f; return rest; }));
402
+ emit('site', result);
403
+ const lastTouch = lastTouchAt(corpus, parent);
404
+ onArm('site+commit', (0, anchor_history_1.bindAnchorsByHistory)(scanned, (f) => {
405
+ const key = `${f.sourcePath}\u0000${lastTouch.get(f.sourcePath) ?? parent}`;
406
+ if (!blameMemo.has(key))
407
+ blameMemo.set(key, (0, anchor_history_1.gitBlameLines)(corpus.root, f.sourcePath, parent));
408
+ return blameMemo.get(key) ?? null;
409
+ }));
410
+ }
322
411
  // @implements A-SPEC-487 — the dump: 2-pass with semantic injected when asked (vectors
323
412
  // only for the files the 1-pass surfaced — the hot-path lookup contract holds), 1-pass
324
413
  // otherwise. Nothing here feeds outcomes or any pin.
@@ -401,6 +490,9 @@ async function runReplay(corpus, limit, opts = {}) {
401
490
  candidates: dumpResult.candidates,
402
491
  rankedImpact: dumpResult.impacts?.rankedImpact ?? [],
403
492
  truthFiles: c.files,
493
+ // @implements A-SPEC-755.1 — the SAME arrays the scored outcome above holds, never a
494
+ // second derivation: a paired before/after on the function axis must compare what was scored.
495
+ truthSymbols, rankedSymbols,
404
496
  ...(bodies !== undefined ? { bodies } : {}),
405
497
  ...(judgementBundle !== undefined ? { judgementBundle } : {}),
406
498
  });
@@ -474,6 +566,18 @@ async function runReplay(corpus, limit, opts = {}) {
474
566
  }
475
567
  const unionList = [...new Set([...ranked, ...impacted])];
476
568
  unionCases.push({ seed: '', expected: c.files, predicted: unionList });
569
+ // @implements A-SPEC-758 — the union surface (what a caller receives: ranked plus graded impact)
570
+ // under both call graphs.
571
+ if (opts.callArms !== undefined) {
572
+ const emitUnion = (arm, r) => opts.callArms({
573
+ commit: c.commit, arm, surface: 'union', seed: '', expected: [...c.files],
574
+ ranked: r.candidates.map((x) => x.file),
575
+ rankedImpact: (r.impacts?.rankedImpact ?? []).map((x) => x.file),
576
+ impactedFiles: [...(r.impacts?.impactedFiles ?? [])],
577
+ });
578
+ emitUnion('compiler', result);
579
+ onNameGraph((byName, g) => emitUnion('name', twoPassOn(byName, g)));
580
+ }
477
581
  // @implements A-SPEC-493 — the ceiling rows: a strict superset of the union prediction.
478
582
  if (opts.semanticArm?.gates === true) {
479
583
  for (const k of UPA_KS) {
@@ -613,15 +717,35 @@ async function runReplay(corpus, limit, opts = {}) {
613
717
  const seed = [...c.files].sort()[0];
614
718
  const expected = c.files.filter((f) => f !== seed);
615
719
  if (expected.length > 0) {
720
+ // @implements A-SPEC-469.1 — what the product's handler passes for a named change: co-change
721
+ // with the seed, read up to the PARENT and never the answer commit.
722
+ const coChangeWeights = (0, co_change_1.coChangeFromGit)(corpus.root, parent, [seed]);
723
+ const coChange = coChangeWeights.size > 0 ? Object.fromEntries(coChangeWeights) : undefined;
616
724
  const run = (0, maintenance_analyze_1.analyzeMaintenance)({
617
725
  request: c.subject, scanned, specs, graph, testAnchors: anchors, history: [],
618
- changedFiles: [seed], changePrior, commitTextBoost,
726
+ changedFiles: [seed], changePrior, commitTextBoost, ...(coChange !== undefined ? { coChange } : {}),
619
727
  basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
620
728
  coverage: { scannedFiles: scanned.length, skippedFiles: [], unsupportedLanguages: [] },
621
729
  });
622
730
  // @implements A-SPEC-469 — score the SHIPPED prediction surface (ablation must score
623
731
  // what ships): the graded top-K, not the ungraded closure the gates keep.
624
732
  impactCases.push({ seed, expected, predicted: (run.impacts?.rankedImpact ?? []).map((r) => r.file) });
733
+ // @implements A-SPEC-758 — the same impact case on the name-resolved call graph.
734
+ if (opts.callArms !== undefined) {
735
+ const emitCall = (arm, r) => opts.callArms({
736
+ commit: c.commit, arm, surface: 'impact', seed, expected: [...expected],
737
+ ranked: r.candidates.map((x) => x.file),
738
+ rankedImpact: (r.impacts?.rankedImpact ?? []).map((x) => x.file),
739
+ impactedFiles: [...(r.impacts?.impactedFiles ?? [])],
740
+ });
741
+ emitCall('compiler', run);
742
+ onNameGraph((byName, g) => emitCall('name', (0, maintenance_analyze_1.analyzeMaintenance)({
743
+ request: c.subject, scanned: byName, specs, graph: g, testAnchors: anchors, history: [],
744
+ changedFiles: [seed], changePrior, commitTextBoost, ...(coChange !== undefined ? { coChange } : {}),
745
+ basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
746
+ coverage: { scannedFiles: byName.length, skippedFiles: [], unsupportedLanguages: [] },
747
+ })));
748
+ }
625
749
  // @implements A-SPEC-470 — the frozen string-property heuristic on the same case.
626
750
  impactBaselineCases.push({ seed, expected,
627
751
  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
  *