@holmes-lab/holmes-kit 0.35.10 → 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 +75 -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/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
|
@@ -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;
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.bindAnchorsByHistory = bindAnchorsByHistory;
|
|
4
|
+
exports.gitBlameLines = gitBlameLines;
|
|
5
|
+
const bounded_io_1 = require("../project/bounded-io");
|
|
6
|
+
/** Blank, or a line that only continues or opens a comment — the same test the place rule uses. */
|
|
7
|
+
const COMMENT_OR_BLANK = /^\s*(?:$|\/\/|\/\*|\*|#|"""|''')/;
|
|
8
|
+
const NOT_COMMITTED = /^0+$/;
|
|
9
|
+
/**
|
|
10
|
+
* Bind every site that place left unbound to the functions its introducing commit last touched.
|
|
11
|
+
*
|
|
12
|
+
* A site stays unbound when its line is not committed yet, when the commit touched no function, or
|
|
13
|
+
* when it touched EVERY function of a file with two or more — "this commit wrote the whole file" is
|
|
14
|
+
* a statement about the file, and recording it on each function would only relabel the copy.
|
|
15
|
+
*
|
|
16
|
+
* `blameOf` is asked only for a file that has an unbound site. A `null` answer, or a blame shorter
|
|
17
|
+
* than the site's line, leaves that file exactly as it came.
|
|
18
|
+
*/
|
|
19
|
+
function bindAnchorsByHistory(scanned, blameOf) {
|
|
20
|
+
return scanned.map((f) => {
|
|
21
|
+
const sites = f.anchorSites;
|
|
22
|
+
if (sites === undefined || f.symbols.length === 0 || !sites.some((s) => s.symbol === null))
|
|
23
|
+
return f;
|
|
24
|
+
const blame = blameOf(f);
|
|
25
|
+
if (blame === null)
|
|
26
|
+
return f;
|
|
27
|
+
// Per commit: the functions holding a code line it last touched. Built once per file.
|
|
28
|
+
const touchedBy = new Map();
|
|
29
|
+
const functionsOf = (commit) => {
|
|
30
|
+
const known = touchedBy.get(commit);
|
|
31
|
+
if (known !== undefined)
|
|
32
|
+
return known;
|
|
33
|
+
const out = [];
|
|
34
|
+
for (const sym of f.symbols) {
|
|
35
|
+
for (let ln = sym.startLine; ln <= sym.endLine && ln <= blame.length; ln++) {
|
|
36
|
+
const row = blame[ln - 1];
|
|
37
|
+
if (row.commit === commit && !COMMENT_OR_BLANK.test(row.text)) {
|
|
38
|
+
out.push(sym.qualifiedName);
|
|
39
|
+
break;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
touchedBy.set(commit, out);
|
|
44
|
+
return out;
|
|
45
|
+
};
|
|
46
|
+
const everyFunction = new Set(f.symbols.map((s) => s.qualifiedName)).size;
|
|
47
|
+
let changed = false;
|
|
48
|
+
const next = [];
|
|
49
|
+
for (const site of sites) {
|
|
50
|
+
const row = site.symbol === null ? blame[site.line - 1] : undefined;
|
|
51
|
+
if (row === undefined || NOT_COMMITTED.test(row.commit)) {
|
|
52
|
+
next.push(site);
|
|
53
|
+
continue;
|
|
54
|
+
}
|
|
55
|
+
const fns = [...new Set(functionsOf(row.commit))];
|
|
56
|
+
if (fns.length === 0 || (everyFunction >= 2 && fns.length === everyFunction)) {
|
|
57
|
+
next.push(site);
|
|
58
|
+
continue;
|
|
59
|
+
}
|
|
60
|
+
changed = true;
|
|
61
|
+
for (const symbol of fns)
|
|
62
|
+
next.push({ spec: site.spec, line: site.line, symbol, by: 'commit' });
|
|
63
|
+
}
|
|
64
|
+
return changed ? { ...f, anchorSites: next } : f;
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* One `git blame` of a file: the commit that last touched each line, and the line's text.
|
|
69
|
+
*
|
|
70
|
+
* `-w` so a re-indent does not claim a function; `--line-porcelain` because its shape does not change
|
|
71
|
+
* with renames or boundary commits the way the human format's columns do. `rev` reads the file as it
|
|
72
|
+
* was at that revision — the replay uses the PARENT of the commit it scores, never the answer.
|
|
73
|
+
* `null` for anything that is not a tracked file in a repository git can read.
|
|
74
|
+
*/
|
|
75
|
+
function gitBlameLines(root, sourcePath, rev) {
|
|
76
|
+
const args = ['blame', '-w', '--line-porcelain', ...(rev === undefined ? [] : [rev]), '--', sourcePath];
|
|
77
|
+
const r = (0, bounded_io_1.gitOnce)(root, args, 'worktree');
|
|
78
|
+
if (r.error !== undefined || r.status !== 0 || typeof r.stdout !== 'string')
|
|
79
|
+
return null;
|
|
80
|
+
const out = [];
|
|
81
|
+
let commit = null;
|
|
82
|
+
for (const line of r.stdout.split('\n')) {
|
|
83
|
+
if (line.startsWith('\t')) {
|
|
84
|
+
if (commit === null)
|
|
85
|
+
return null;
|
|
86
|
+
out.push({ commit, text: line.slice(1).replace(/\r$/, '') });
|
|
87
|
+
commit = null;
|
|
88
|
+
continue;
|
|
89
|
+
}
|
|
90
|
+
if (commit === null) {
|
|
91
|
+
const m = /^([0-9a-f]{40}) \d+ \d+/.exec(line);
|
|
92
|
+
if (m !== null)
|
|
93
|
+
commit = m[1];
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
return out;
|
|
97
|
+
}
|
|
@@ -7,9 +7,30 @@
|
|
|
7
7
|
* turning commentary into governance.
|
|
8
8
|
*/
|
|
9
9
|
export declare function stripStringLiterals(text: string): string;
|
|
10
|
+
/**
|
|
11
|
+
* @implements A-SPEC-756
|
|
12
|
+
* Where the string literals are: `[index of the opening quote, index of the closing quote]`, in text
|
|
13
|
+
* order. The ONE scan `stripStringLiterals` and the site reader share \u2014 a site reader with its own
|
|
14
|
+
* idea of what a string is would disagree with the claim gate about which markers are anchors.
|
|
15
|
+
*/
|
|
16
|
+
export declare function stringLiteralRanges(text: string): Array<[number, number]>;
|
|
10
17
|
/** Every anchor-marker occurrence's comma-list, as an array of ids per occurrence. */
|
|
11
18
|
export declare function implementsIdLists(text: string): string[][];
|
|
12
19
|
/** Flattened A-SPEC ids across all lists — the graph/coverage consumers' shape. */
|
|
13
20
|
export declare function anchorSpecIds(text: string): string[];
|
|
21
|
+
/**
|
|
22
|
+
* @implements A-SPEC-756
|
|
23
|
+
* Every A-SPEC id of every anchor list with the 1-based line of its marker, in text order.
|
|
24
|
+
*
|
|
25
|
+
* A marker inside a string literal is not a site: it is text some code holds, not a comment about
|
|
26
|
+
* the code around it. (`anchorSpecIds` over the raw text still reports such an id in the file-wide
|
|
27
|
+
* list; with no site it binds to no function and stays a statement about the file.)
|
|
28
|
+
*
|
|
29
|
+
* Lines are counted by `\n`, so a CRLF file numbers exactly as its LF twin does.
|
|
30
|
+
*/
|
|
31
|
+
export declare function anchorSpecSites(text: string): Array<{
|
|
32
|
+
spec: string;
|
|
33
|
+
line: number;
|
|
34
|
+
}>;
|
|
14
35
|
/** Flattened wrong-kind ids (a governed id anchored where only A-SPEC belongs) — anywhere in a list. */
|
|
15
36
|
export declare function wrongKindAnchorIds(text: string): string[];
|
|
@@ -10,8 +10,10 @@
|
|
|
10
10
|
*/
|
|
11
11
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
12
12
|
exports.stripStringLiterals = stripStringLiterals;
|
|
13
|
+
exports.stringLiteralRanges = stringLiteralRanges;
|
|
13
14
|
exports.implementsIdLists = implementsIdLists;
|
|
14
15
|
exports.anchorSpecIds = anchorSpecIds;
|
|
16
|
+
exports.anchorSpecSites = anchorSpecSites;
|
|
15
17
|
exports.wrongKindAnchorIds = wrongKindAnchorIds;
|
|
16
18
|
// @implements A-SPEC-504.1
|
|
17
19
|
// The ONE string-literal preprocessing every anchor-judging surface shares. Measured 2026-09-01:
|
|
@@ -26,10 +28,24 @@ exports.wrongKindAnchorIds = wrongKindAnchorIds;
|
|
|
26
28
|
// place, and every later quote of the same kind before that place is an escaped character of that scan, so it fails there
|
|
27
29
|
// too. `.` in the regex does not match a line terminator; a quote or double-quote body also ends at `\n`.
|
|
28
30
|
function stripStringLiterals(text) {
|
|
29
|
-
const lineEnd = (c) => c === '\n' || c === '\r' || c === '\u2028' || c === '\u2029';
|
|
30
|
-
const failUntil = { "'": -1, '"': -1, '`': -1 };
|
|
31
31
|
let out = '';
|
|
32
32
|
let last = 0;
|
|
33
|
+
for (const [start, end] of stringLiteralRanges(text)) {
|
|
34
|
+
out += `${text.slice(last, start)}""`;
|
|
35
|
+
last = end + 1;
|
|
36
|
+
}
|
|
37
|
+
return out + text.slice(last);
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* @implements A-SPEC-756
|
|
41
|
+
* Where the string literals are: `[index of the opening quote, index of the closing quote]`, in text
|
|
42
|
+
* order. The ONE scan `stripStringLiterals` and the site reader share \u2014 a site reader with its own
|
|
43
|
+
* idea of what a string is would disagree with the claim gate about which markers are anchors.
|
|
44
|
+
*/
|
|
45
|
+
function stringLiteralRanges(text) {
|
|
46
|
+
const lineEnd = (c) => c === '\n' || c === '\r' || c === '\u2028' || c === '\u2029';
|
|
47
|
+
const failUntil = { "'": -1, '"': -1, '`': -1 };
|
|
48
|
+
const ranges = [];
|
|
33
49
|
for (let p = 0; p < text.length; p++) {
|
|
34
50
|
const q = text[p];
|
|
35
51
|
if ((q !== "'" && q !== '"' && q !== '`') || p < failUntil[q])
|
|
@@ -57,11 +73,10 @@ function stripStringLiterals(text) {
|
|
|
57
73
|
failUntil[q] = j;
|
|
58
74
|
continue;
|
|
59
75
|
}
|
|
60
|
-
|
|
61
|
-
last = end + 1;
|
|
76
|
+
ranges.push([p, end]);
|
|
62
77
|
p = end;
|
|
63
78
|
}
|
|
64
|
-
return
|
|
79
|
+
return ranges;
|
|
65
80
|
}
|
|
66
81
|
const ID = String.raw `(?:REQ|A-SPEC|H-SPEC|C-SPEC|T-SPEC)-\d{3,}(?:\.\d+)?`;
|
|
67
82
|
const LIST_RE = new RegExp(String.raw `@implements[ \t]+(${ID}(?:[ \t]*,[ \t]*${ID})*)`, 'g');
|
|
@@ -73,6 +88,37 @@ function implementsIdLists(text) {
|
|
|
73
88
|
function anchorSpecIds(text) {
|
|
74
89
|
return [...new Set(implementsIdLists(text).flat().filter((id) => id.startsWith('A-SPEC-')))];
|
|
75
90
|
}
|
|
91
|
+
/**
|
|
92
|
+
* @implements A-SPEC-756
|
|
93
|
+
* Every A-SPEC id of every anchor list with the 1-based line of its marker, in text order.
|
|
94
|
+
*
|
|
95
|
+
* A marker inside a string literal is not a site: it is text some code holds, not a comment about
|
|
96
|
+
* the code around it. (`anchorSpecIds` over the raw text still reports such an id in the file-wide
|
|
97
|
+
* list; with no site it binds to no function and stays a statement about the file.)
|
|
98
|
+
*
|
|
99
|
+
* Lines are counted by `\n`, so a CRLF file numbers exactly as its LF twin does.
|
|
100
|
+
*/
|
|
101
|
+
function anchorSpecSites(text) {
|
|
102
|
+
const strings = stringLiteralRanges(text);
|
|
103
|
+
const sites = [];
|
|
104
|
+
let s = 0; // first string range that could still contain the marker
|
|
105
|
+
let line = 1; // line of `lineAt`
|
|
106
|
+
let lineAt = 0;
|
|
107
|
+
for (const m of text.matchAll(LIST_RE)) {
|
|
108
|
+
const at = m.index ?? 0;
|
|
109
|
+
while (s < strings.length && strings[s][1] < at)
|
|
110
|
+
s++;
|
|
111
|
+
if (s < strings.length && strings[s][0] < at)
|
|
112
|
+
continue; // the marker sits inside that literal
|
|
113
|
+
for (; lineAt < at; lineAt++)
|
|
114
|
+
if (text.charCodeAt(lineAt) === 10)
|
|
115
|
+
line++;
|
|
116
|
+
for (const id of m[1].split(/[ \t]*,[ \t]*/))
|
|
117
|
+
if (id.startsWith('A-SPEC-'))
|
|
118
|
+
sites.push({ spec: id, line });
|
|
119
|
+
}
|
|
120
|
+
return sites;
|
|
121
|
+
}
|
|
76
122
|
/** Flattened wrong-kind ids (a governed id anchored where only A-SPEC belongs) — anywhere in a list. */
|
|
77
123
|
function wrongKindAnchorIds(text) {
|
|
78
124
|
return [...new Set(implementsIdLists(text).flat().filter((id) => !id.startsWith('A-SPEC-')))];
|
|
@@ -50,6 +50,13 @@ export declare function citationsIn(text: string, known: ReadonlySet<string>): {
|
|
|
50
50
|
* camelCase/snake are split; Latin tokens need length>=3, non-ASCII (e.g. Korean) length>=2.
|
|
51
51
|
*/
|
|
52
52
|
export declare function significantTerms(text: string): string[];
|
|
53
|
+
/**
|
|
54
|
+
* @implements A-SPEC-757 — the same tokens for a DOCUMENT: every occurrence, in order, no bound.
|
|
55
|
+
* `significantTerms` is the request form (distinct, first 64). Scoring a document through the request
|
|
56
|
+
* form read only its first 64 distinct words and flattened every term frequency to 1: all 648 lineages
|
|
57
|
+
* of this repository were ranked on 64 terms out of a median 831 (measured 2026-10-07).
|
|
58
|
+
*/
|
|
59
|
+
export declare function documentTerms(text: string): string[];
|
|
53
60
|
/**
|
|
54
61
|
* @implements A-SPEC-400
|
|
55
62
|
* Character bigrams for scripts that do not space their words.
|