@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
|
@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
3
3
|
exports.withoutCitations = withoutCitations;
|
|
4
4
|
exports.citationsIn = citationsIn;
|
|
5
5
|
exports.significantTerms = significantTerms;
|
|
6
|
+
exports.documentTerms = documentTerms;
|
|
6
7
|
exports.bigramUnspaced = bigramUnspaced;
|
|
7
8
|
exports.localizeIssue = localizeIssue;
|
|
8
9
|
/**
|
|
@@ -69,7 +70,16 @@ const MAX_TERMS = 64;
|
|
|
69
70
|
* camelCase/snake are split; Latin tokens need length>=3, non-ASCII (e.g. Korean) length>=2.
|
|
70
71
|
*/
|
|
71
72
|
function significantTerms(text) {
|
|
72
|
-
|
|
73
|
+
return [...new Set(documentTerms(text))].slice(0, MAX_TERMS);
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* @implements A-SPEC-757 — the same tokens for a DOCUMENT: every occurrence, in order, no bound.
|
|
77
|
+
* `significantTerms` is the request form (distinct, first 64). Scoring a document through the request
|
|
78
|
+
* form read only its first 64 distinct words and flattened every term frequency to 1: all 648 lineages
|
|
79
|
+
* of this repository were ranked on 64 terms out of a median 831 (measured 2026-10-07).
|
|
80
|
+
*/
|
|
81
|
+
function documentTerms(text) {
|
|
82
|
+
return text
|
|
73
83
|
.replace(/([a-z0-9])([A-Z])/g, '$1 $2') // camelCase -> camel Case
|
|
74
84
|
.toLowerCase()
|
|
75
85
|
.split(/[^\p{L}\p{N}]+/u)
|
|
@@ -78,7 +88,6 @@ function significantTerms(text) {
|
|
|
78
88
|
const minLen = /[^\x00-\x7f]/.test(t) ? 2 : 3;
|
|
79
89
|
return t.length >= minLen && !STOP.has(t);
|
|
80
90
|
});
|
|
81
|
-
return [...new Set(raw)].slice(0, MAX_TERMS);
|
|
82
91
|
}
|
|
83
92
|
/**
|
|
84
93
|
* @implements A-SPEC-400
|
|
@@ -33,6 +33,18 @@ export interface ResolutionReport {
|
|
|
33
33
|
selfReference: number;
|
|
34
34
|
/** `<module>`-scoped relations, which are not symbol-to-symbol. */
|
|
35
35
|
moduleScoped: number;
|
|
36
|
+
/**
|
|
37
|
+
* @implements A-SPEC-758
|
|
38
|
+
* `calls` edges bound by the TypeScript compiler's symbol resolution (derivation `compiler-symbol`).
|
|
39
|
+
* They are not part of `resolved`, which keeps counting what the name rule decided.
|
|
40
|
+
*/
|
|
41
|
+
compilerBound: number;
|
|
42
|
+
/**
|
|
43
|
+
* (Calling function, callee name) pairs the name rule was NOT applied to because the compiler binds
|
|
44
|
+
* every such call to its bundled library — `xs.map(...)` on an array is not a call to the one scanned
|
|
45
|
+
* class that happens to define `map`.
|
|
46
|
+
*/
|
|
47
|
+
librarySuppressed: number;
|
|
36
48
|
}
|
|
37
49
|
export interface BuildRtmOptions {
|
|
38
50
|
/** Resolve a spec id to its source file path (e.g. its .md file) for provenance tagging. */
|
|
@@ -128,9 +128,36 @@ function buildFileSubgraph(f, specs, graph, opts) {
|
|
|
128
128
|
const codeId = `CODE:${sym.qualifiedName}@${f.sourcePath}`;
|
|
129
129
|
const digest = opts?.fileDigest?.(f.sourcePath) ?? null;
|
|
130
130
|
graph.addNode(codeId, 'CODE', f.sourcePath, fact(opts, `${f.sourcePath}:${sym.startLine}`, 'ast-scan', 1, digest));
|
|
131
|
-
|
|
131
|
+
}
|
|
132
|
+
// @implements A-SPEC-756 — an anchor written in or directly above a function binds to THAT
|
|
133
|
+
// function. This loop used to add one edge per pair of symbol and spec in the FILE's list:
|
|
134
|
+
// measured 2026-10-07, in 330 of 330 files every function carried the identical set, so
|
|
135
|
+
// "f implements X" said only that f lives in a file that mentions X.
|
|
136
|
+
const digest = opts?.fileDigest?.(f.sourcePath) ?? null;
|
|
137
|
+
const known = new Set(f.symbols.map((sym) => sym.qualifiedName));
|
|
138
|
+
const bound = new Set();
|
|
139
|
+
for (const site of f.anchorSites ?? []) {
|
|
140
|
+
if (site.symbol === null || !known.has(site.symbol))
|
|
141
|
+
continue;
|
|
142
|
+
bound.add(site.spec);
|
|
143
|
+
// DECLARED at this place: the anchor is written in the file, at this line.
|
|
144
|
+
// @implements A-SPEC-756.1 — or OBSERVED: the commit that introduced the anchor last touched this
|
|
145
|
+
// function. A place binding and a commit binding of the same pair keep the place derivation:
|
|
146
|
+
// the scanner's sites come first and an edge is written once.
|
|
147
|
+
graph.addEdge(`CODE:${site.symbol}@${f.sourcePath}`, `SPEC:${site.spec}`, 'implements', f.sourcePath, fact(opts, `${f.sourcePath}:${site.line}`, site.by === 'commit' ? 'anchor-commit' : 'anchor-site', 1, digest));
|
|
148
|
+
}
|
|
149
|
+
// @implements A-SPEC-756.3 — an anchor bound to NO function is a statement about the file, and it
|
|
150
|
+
// stays where every reader already finds it: on each function of that file, derivation `anchor`.
|
|
151
|
+
// A-SPEC-756 first moved these onto a FILE node; the whole suite then showed what that breaks —
|
|
152
|
+
// the per-file path gave a changed function no spec at all, and every walk from a function along
|
|
153
|
+
// `implements` lost the file's specs, which is ALL of them for a repository that anchors only in
|
|
154
|
+
// headers (the shape the shipped guidance produces). A spec bound to a function is not copied to
|
|
155
|
+
// its siblings; a file with no site record builds exactly the graph it built before.
|
|
156
|
+
const fileLevel = [...new Set(f.implementsSpecs)].filter((id) => !bound.has(id));
|
|
157
|
+
for (const sym of f.symbols) {
|
|
158
|
+
for (const aspec of fileLevel) {
|
|
132
159
|
// DECLARED by an `@implements` anchor: the fact is stated in the file, not inferred.
|
|
133
|
-
graph.addEdge(
|
|
160
|
+
graph.addEdge(`CODE:${sym.qualifiedName}@${f.sourcePath}`, `SPEC:${aspec}`, 'implements', f.sourcePath, fact(opts, `${f.sourcePath}:${sym.startLine}`, 'anchor', 1, digest));
|
|
134
161
|
}
|
|
135
162
|
}
|
|
136
163
|
}
|
|
@@ -141,6 +168,7 @@ function buildRtm(specs, scanned, graph, opts) {
|
|
|
141
168
|
// It also makes a failed build atomic — no half-graph that could be mistaken for a complete one.
|
|
142
169
|
let resolution = {
|
|
143
170
|
resolved: 0, ambiguousEdges: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
|
|
171
|
+
compilerBound: 0, librarySuppressed: 0,
|
|
144
172
|
};
|
|
145
173
|
graph.transaction(() => {
|
|
146
174
|
// Add spec nodes and dependencies
|
|
@@ -187,6 +215,7 @@ function buildRtm(specs, scanned, graph, opts) {
|
|
|
187
215
|
function addCallEdges(scanned, graph, opts) {
|
|
188
216
|
const report = {
|
|
189
217
|
resolved: 0, ambiguousEdges: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
|
|
218
|
+
compilerBound: 0, librarySuppressed: 0,
|
|
190
219
|
};
|
|
191
220
|
// @implements A-SPEC-300
|
|
192
221
|
// Indexes are built PER LANGUAGE FAMILY. Resolution used to look across the whole scan, so a Java
|
|
@@ -227,6 +256,28 @@ function addCallEdges(scanned, graph, opts) {
|
|
|
227
256
|
}
|
|
228
257
|
}
|
|
229
258
|
for (const f of scanned) {
|
|
259
|
+
// @implements A-SPEC-758 — what the compiler bound in this file comes first and decides. A pair it
|
|
260
|
+
// recorded (targets, or "library") is closed to the name rule below; a pair it did not record is
|
|
261
|
+
// decided by name exactly as before, and so is every file without the record.
|
|
262
|
+
const decided = new Map(); // `${from}\0${callee name}` -> bound to the library?
|
|
263
|
+
const emitted = new Set();
|
|
264
|
+
const countedLibrary = new Set();
|
|
265
|
+
for (const r of f.resolvedCalls ?? []) {
|
|
266
|
+
decided.set(`${r.from}\u0000${r.name}`, r.library);
|
|
267
|
+
const fromId = `CODE:${r.from}@${f.sourcePath}`;
|
|
268
|
+
if (!graph.hasNode(fromId))
|
|
269
|
+
continue;
|
|
270
|
+
for (const t of r.targets) {
|
|
271
|
+
const toId = `CODE:${t.qualifiedName}@${t.sourcePath}`;
|
|
272
|
+
if (toId === fromId || emitted.has(`${fromId}\u0000${toId}`) || !graph.hasNode(toId))
|
|
273
|
+
continue;
|
|
274
|
+
emitted.add(`${fromId}\u0000${toId}`);
|
|
275
|
+
// DERIVED by the compiler's symbol resolution: the receiver's type is known, the target is one
|
|
276
|
+
// declaration. Confidence stays null — no precision figure has been measured for it either.
|
|
277
|
+
graph.addEdge(fromId, toId, 'calls', f.sourcePath, fact(opts, `${f.sourcePath}`, 'compiler-symbol', null));
|
|
278
|
+
report.compilerBound++;
|
|
279
|
+
}
|
|
280
|
+
}
|
|
230
281
|
for (const e of f.edges ?? []) {
|
|
231
282
|
// @implements A-SPEC-286 — `inherits` resolves by the SAME rule as `calls`: symbol-to-symbol,
|
|
232
283
|
// and only when the name is defined in exactly one file across the scan. `imports` is excluded
|
|
@@ -246,6 +297,17 @@ function addCallEdges(scanned, graph, opts) {
|
|
|
246
297
|
report.callerNotNamed++;
|
|
247
298
|
continue;
|
|
248
299
|
}
|
|
300
|
+
if (e.rel === 'calls' && decided.size > 0) {
|
|
301
|
+
const key = `${e.from}\u0000${e.to.includes('.') ? e.to.slice(e.to.lastIndexOf('.') + 1) : e.to}`;
|
|
302
|
+
const library = decided.get(key);
|
|
303
|
+
if (library !== undefined) {
|
|
304
|
+
if (library && !countedLibrary.has(key)) {
|
|
305
|
+
countedLibrary.add(key);
|
|
306
|
+
report.librarySuppressed++;
|
|
307
|
+
}
|
|
308
|
+
continue;
|
|
309
|
+
}
|
|
310
|
+
}
|
|
249
311
|
const family = familyOf(f.sourcePath);
|
|
250
312
|
const table = definedIn.get(family);
|
|
251
313
|
// @implements A-SPEC-573.5 — an ambiguous target is a CANDIDATE SET, not a dead end. Both
|
|
@@ -172,6 +172,17 @@ export declare class RtmGraph {
|
|
|
172
172
|
* callee's spec. Impact walks callers BACKWARD; only anchors are followed forward.
|
|
173
173
|
*/
|
|
174
174
|
specsOf(codeId: string): string[];
|
|
175
|
+
/**
|
|
176
|
+
* @implements A-SPEC-756.1
|
|
177
|
+
* Every spec a FILE states — the targets of all `implements` edges that file owns — plus their
|
|
178
|
+
* `depends_on` ancestors.
|
|
179
|
+
*
|
|
180
|
+
* For any function this is what `specsOf` answered before anchors were bound to functions, and it
|
|
181
|
+
* is what a caller selecting TESTS must keep using: a function no longer carries its siblings'
|
|
182
|
+
* specs, and a selection gathered function by function would silently drop the tests of everything
|
|
183
|
+
* else the file implements (measured on the first place-binding build: test recall 0.454 -> 0.425).
|
|
184
|
+
*/
|
|
185
|
+
specsOfFile(sourcePath: string): string[];
|
|
175
186
|
/**
|
|
176
187
|
* Neighbours with the relation that connects them, so a traversal can price a `calls` hop
|
|
177
188
|
* differently from a spec-chain hop. Same ordering guarantee as `neighbors`.
|
|
@@ -298,6 +298,26 @@ class RtmGraph {
|
|
|
298
298
|
out.add(id);
|
|
299
299
|
return [...out];
|
|
300
300
|
}
|
|
301
|
+
/**
|
|
302
|
+
* @implements A-SPEC-756.1
|
|
303
|
+
* Every spec a FILE states — the targets of all `implements` edges that file owns — plus their
|
|
304
|
+
* `depends_on` ancestors.
|
|
305
|
+
*
|
|
306
|
+
* For any function this is what `specsOf` answered before anchors were bound to functions, and it
|
|
307
|
+
* is what a caller selecting TESTS must keep using: a function no longer carries its siblings'
|
|
308
|
+
* specs, and a selection gathered function by function would silently drop the tests of everything
|
|
309
|
+
* else the file implements (measured on the first place-binding build: test recall 0.454 -> 0.425).
|
|
310
|
+
*/
|
|
311
|
+
specsOfFile(sourcePath) {
|
|
312
|
+
const direct = this.db.prepare("SELECT DISTINCT dst FROM edges WHERE rel='implements' AND source_path=?").all(sourcePath).map(x => x.dst);
|
|
313
|
+
const out = new Set(direct);
|
|
314
|
+
const anc = this.db.prepare(`WITH RECURSIVE r(id) AS (SELECT dst FROM edges WHERE src=? AND rel='depends_on'
|
|
315
|
+
UNION SELECT e.dst FROM edges e JOIN r ON e.src=r.id WHERE e.rel='depends_on') SELECT DISTINCT id FROM r`);
|
|
316
|
+
for (const s of direct)
|
|
317
|
+
for (const { id } of anc.all(s))
|
|
318
|
+
out.add(id);
|
|
319
|
+
return [...out];
|
|
320
|
+
}
|
|
301
321
|
/**
|
|
302
322
|
* Neighbours with the relation that connects them, so a traversal can price a `calls` hop
|
|
303
323
|
* differently from a spec-chain hop. Same ordering guarantee as `neighbors`.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"//": "@implements A-SPEC-209",
|
|
3
3
|
"name": "@holmes-lab/holmes-kit",
|
|
4
|
-
"version": "0.35.
|
|
4
|
+
"version": "0.35.11",
|
|
5
5
|
"description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
|
|
6
6
|
"main": "dist/holmes/mcp/server.js",
|
|
7
7
|
"types": "dist/holmes/mcp/server.d.ts",
|