@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
@@ -39,7 +39,7 @@ exports.warmRequirementSemanticCache = warmRequirementSemanticCache;
39
39
  exports.headOf = headOf;
40
40
  exports.refreshSemanticVectors = refreshSemanticVectors;
41
41
  exports.createGraphOperationsHandlers = createGraphOperationsHandlers;
42
- // @implements A-SPEC-719, A-SPEC-734, A-SPEC-741.1
42
+ // @implements A-SPEC-719, A-SPEC-734, A-SPEC-741.1, A-SPEC-758.1
43
43
  // @implements A-SPEC-614, A-SPEC-613, A-SPEC-100.2, A-SPEC-121.2, A-SPEC-128, A-SPEC-139, A-SPEC-189, A-SPEC-280, A-SPEC-282, A-SPEC-283, A-SPEC-419, A-SPEC-433, A-SPEC-469, A-SPEC-478, A-SPEC-568.1, A-SPEC-568.2, A-SPEC-569.1, A-SPEC-569.2, A-SPEC-569.3, A-SPEC-589
44
44
  // @implements A-SPEC-632
45
45
  const fs = __importStar(require("node:fs"));
@@ -60,7 +60,10 @@ const vector_coverage_1 = require("../../semantic/vector-coverage");
60
60
  // @implements A-SPEC-283 — bumped whenever the graph's node/edge shape changes, so a store written
61
61
  // by an older build is rebuilt rather than read with new assumptions.
62
62
  // @implements A-SPEC-568.1 — /3: nodes gained the intent `summary` column.
63
- const RTM_GRAPH_SCHEMA = 'rtm-graph/3';
63
+ // @implements A-SPEC-756.2 — /4: an `implements` edge from a function now means the anchor was
64
+ // written in or directly above it, and anchors bound to no function sit on FILE nodes (A-SPEC-756).
65
+ // A /3 store holds the file's whole list on every function and must be rebuilt, not read anew.
66
+ const RTM_GRAPH_SCHEMA = 'rtm-graph/4';
64
67
  // @implements A-SPEC-569.3 — how many impacted specs get their intent sentence attached. A prose
65
68
  // constant, never a verdict input: the impacted list itself is never truncated.
66
69
  const SUMMARY_CAP = 40;
@@ -68,7 +71,10 @@ const SUMMARY_CAP = 40;
68
71
  // characters in the summary column, and every other basis field would still match after upgrading.
69
72
  // A-SPEC-283's own rule applies to us too: an older build's artifact is rebuilt, never read with
70
73
  // new assumptions.
71
- const RTM_EXTRACTOR_VERSION = 'holmes-rtm/2';
74
+ // @implements A-SPEC-756.2 — /3: the extractor binds anchors to functions by place.
75
+ // @implements A-SPEC-758.1 — /4: TypeScript `calls` edges are bound by the compiler; a /3 store holds
76
+ // library calls linked to unrelated symbols by name and is rebuilt.
77
+ const RTM_EXTRACTOR_VERSION = 'holmes-rtm/4';
72
78
  // @implements A-SPEC-632 — the two rebuild paths a completed integration's discharge runs are the
73
79
  // SAME functions explicit reindex runs, so a discharged graph and a reindexed graph are one artifact.
74
80
  /** Publish the complete graph for `specs` over `scanned` at the live path (A-SPEC-631 primitive). */
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createMaintenanceAnalysisHandlers = createMaintenanceAnalysisHandlers;
37
- // @implements A-SPEC-745, A-SPEC-741, A-SPEC-741.1, A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5, A-SPEC-734, A-SPEC-278.3
37
+ // @implements A-SPEC-745, A-SPEC-469.1, A-SPEC-741,A-SPEC-741.1, A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5, A-SPEC-734, A-SPEC-278.3
38
38
  const fs = __importStar(require("node:fs"));
39
39
  const path = __importStar(require("node:path"));
40
40
  const node_child_process_1 = require("node:child_process");
@@ -47,6 +47,8 @@ const test_scope_1 = require("../../rtm/test-scope");
47
47
  const root_1 = require("../../project/root");
48
48
  const test_evidence_1 = require("../../review/test-evidence");
49
49
  const temporal_prior_1 = require("../../review/temporal-prior");
50
+ const co_change_1 = require("../../review/co-change");
51
+ const test_files_1 = require("../../cpg/test-files");
50
52
  const commit_text_1 = require("../../review/commit-text");
51
53
  const bundler_1 = require("../../context/bundler");
52
54
  const tier_1 = require("../../semantic/tier");
@@ -213,9 +215,22 @@ function createMaintenanceAnalysisHandlers(context) {
213
215
  commitTextBoost[hit.file] = hit.score / top;
214
216
  }
215
217
  catch { /* no history, no boost — the ranking falls back to lexical evidence alone */ }
218
+ // @implements A-SPEC-469.1 — for a NAMED change: what history says changed together with those
219
+ // files, recency-weighted. One bounded read-only `git log`; no history, no signal.
220
+ let coChange;
221
+ const changedSources = (a.changedFiles ?? []).filter((file) => typeof file === 'string' && !(0, test_files_1.isTestFile)(file));
222
+ if (changedSources.length > 0) {
223
+ try {
224
+ const weights = (0, co_change_1.coChangeFromGit)(root, 'HEAD', changedSources);
225
+ if (weights.size > 0)
226
+ coChange = Object.fromEntries(weights);
227
+ }
228
+ catch { /* the graph ranking alone */ }
229
+ }
216
230
  const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
217
231
  semantic,
218
232
  ...common,
233
+ ...(coChange !== undefined ? { coChange } : {}),
219
234
  coverage: { ...common.coverage, historyStatus },
220
235
  history,
221
236
  changePrior,
@@ -11,7 +11,24 @@ export interface RequirementTriageHandlerContext {
11
11
  status: 'spawned' | 'coalesced' | 'failed';
12
12
  generation?: string;
13
13
  };
14
+ /**
15
+ * @implements A-SPEC-723.1 — how long a call that asked for intake evidence (`persist: true`) waits
16
+ * for the refresh it requested. Absent or 0: no wait, the behaviour of A-SPEC-723.
17
+ */
18
+ freshnessWaitMs?: number;
19
+ /** Injected in tests; the wait polls the receipt between sleeps and does nothing else. */
20
+ sleep?(ms: number): Promise<void>;
21
+ now?(): number;
14
22
  }
23
+ /** @implements A-SPEC-723.1 — the wait bound wired into the server, and its ceiling. */
24
+ export declare const TRIAGE_WAIT_MS = 20000;
25
+ export declare const TRIAGE_WAIT_MAX_MS = 60000;
26
+ /**
27
+ * @implements A-SPEC-723.1
28
+ * `HOLMES_TRIAGE_WAIT_MS`: a non-negative integer overrides the bound (0 disables the wait, anything
29
+ * above the ceiling is the ceiling); every other value leaves the default.
30
+ */
31
+ export declare function triageWaitMsFrom(env: Record<string, string | undefined>): number;
15
32
  type GraphStatus = 'current' | 'stale' | 'unverified' | 'absent' | 'unreadable' | 'empty';
16
33
  export declare function createRequirementTriageHandlers(context: RequirementTriageHandlerContext): {
17
34
  requirement_triage(a: {
@@ -67,10 +84,12 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
67
84
  state: string;
68
85
  };
69
86
  refresh: {
87
+ waitedMs?: number | undefined;
88
+ outcome?: "current" | "timeout" | "ended" | undefined;
70
89
  status: "spawned" | "coalesced" | "failed";
71
90
  generation?: string;
72
91
  } | {
73
- status: "unavailable" | "not-needed";
92
+ status: string;
74
93
  };
75
94
  lexicalOnly?: true | undefined;
76
95
  verdict: import("../../review/requirement-triage").RequirementVerdict;
@@ -125,10 +144,12 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
125
144
  state: string;
126
145
  };
127
146
  refresh: {
147
+ waitedMs?: number | undefined;
148
+ outcome?: "current" | "timeout" | "ended" | undefined;
128
149
  status: "spawned" | "coalesced" | "failed";
129
150
  generation?: string;
130
151
  } | {
131
- status: "unavailable" | "not-needed";
152
+ status: string;
132
153
  };
133
154
  lexicalOnly?: true | undefined;
134
155
  candidates: {
@@ -205,10 +226,12 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
205
226
  state: string;
206
227
  };
207
228
  refresh: {
229
+ waitedMs?: number | undefined;
230
+ outcome?: "current" | "timeout" | "ended" | undefined;
208
231
  status: "spawned" | "coalesced" | "failed";
209
232
  generation?: string;
210
233
  } | {
211
- status: "unavailable" | "not-needed";
234
+ status: string;
212
235
  };
213
236
  lexicalOnly?: true | undefined;
214
237
  verdict: import("../../review/requirement-triage").RequirementVerdict;
@@ -269,10 +292,12 @@ export declare function createRequirementTriageHandlers(context: RequirementTria
269
292
  state: string;
270
293
  };
271
294
  refresh: {
295
+ waitedMs?: number | undefined;
296
+ outcome?: "current" | "timeout" | "ended" | undefined;
272
297
  status: "spawned" | "coalesced" | "failed";
273
298
  generation?: string;
274
299
  } | {
275
- status: "unavailable" | "not-needed";
300
+ status: string;
276
301
  };
277
302
  lexicalOnly?: true | undefined;
278
303
  candidates: {
@@ -33,8 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.TRIAGE_WAIT_MAX_MS = exports.TRIAGE_WAIT_MS = void 0;
37
+ exports.triageWaitMsFrom = triageWaitMsFrom;
36
38
  exports.createRequirementTriageHandlers = createRequirementTriageHandlers;
37
- // @implements A-SPEC-743, A-SPEC-742, A-SPEC-729, A-SPEC-723, A-SPEC-719, A-SPEC-734
39
+ // @implements A-SPEC-743, A-SPEC-742, A-SPEC-729, A-SPEC-723, A-SPEC-719, A-SPEC-734, A-SPEC-723.1
38
40
  // @implements A-SPEC-713
39
41
  /** Read-only MCP projection of the pure requirement lifecycle triage model. */
40
42
  const node_child_process_1 = require("node:child_process");
@@ -50,6 +52,23 @@ const model_cache_1 = require("../../semantic/model-cache");
50
52
  const graph_store_1 = require("../../rtm/graph-store");
51
53
  const freshness_coordinator_1 = require("../../refresh/freshness-coordinator");
52
54
  const bounded_io_1 = require("../../project/bounded-io");
55
+ /** @implements A-SPEC-723.1 — the wait bound wired into the server, and its ceiling. */
56
+ exports.TRIAGE_WAIT_MS = 20_000;
57
+ exports.TRIAGE_WAIT_MAX_MS = 60_000;
58
+ const TRIAGE_POLL_MS = 250;
59
+ /**
60
+ * @implements A-SPEC-723.1
61
+ * `HOLMES_TRIAGE_WAIT_MS`: a non-negative integer overrides the bound (0 disables the wait, anything
62
+ * above the ceiling is the ceiling); every other value leaves the default.
63
+ */
64
+ function triageWaitMsFrom(env) {
65
+ const raw = env.HOLMES_TRIAGE_WAIT_MS;
66
+ if (raw === undefined || !/^\d+$/.test(raw.trim()))
67
+ return exports.TRIAGE_WAIT_MS;
68
+ return Math.min(Number(raw.trim()), exports.TRIAGE_WAIT_MAX_MS);
69
+ }
70
+ /** Receipt states a refresh will not leave by being waited on. */
71
+ const SETTLED_UNUSABLE = new Set(['failed', 'retry-at', 'suppressed', 'not-adopted', 'current']);
53
72
  const requirementKinds = new Set(['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC']);
54
73
  const cosine = (a, b) => {
55
74
  if (a.length === 0 || a.length !== b.length)
@@ -119,10 +138,11 @@ function createRequirementTriageHandlers(context) {
119
138
  const scanned = context.cachedScan(root, root);
120
139
  const evidence = (0, test_evidence_1.readTestEvidence)(root);
121
140
  const currentHead = headOf(root);
122
- const freshness = (0, freshness_coordinator_1.readFreshnessReceipt)(root, { workspaceId: (0, freshness_coordinator_1.workspaceIdFor)(root), head: currentHead || null, now: new Date() });
141
+ const readReceipt = () => (0, freshness_coordinator_1.readFreshnessReceipt)(root, { workspaceId: (0, freshness_coordinator_1.workspaceIdFor)(root), head: currentHead || null, now: new Date() });
142
+ let freshness = readReceipt();
123
143
  // A-SPEC-719: graph current plus a requirement lane that is current or the owner-chosen
124
144
  // lexical-only not-adopted/suppressed. The source lane is reported, never required.
125
- const freshnessCurrent = (0, freshness_coordinator_1.intakeUsable)(freshness);
145
+ let freshnessCurrent = (0, freshness_coordinator_1.intakeUsable)(freshness);
126
146
  // Triage remains read-only with respect to its decision: unavailable or
127
147
  // stale evidence still returns ambiguity. The optional bridge merely
128
148
  // requests the same detached, lease-coalesced refresh as the Stop hook.
@@ -135,6 +155,33 @@ function createRequirementTriageHandlers(context) {
135
155
  refresh = { status: 'failed' };
136
156
  }
137
157
  }
158
+ // @implements A-SPEC-723.1 — the call that asked for intake evidence waits, within the bound,
159
+ // for the refresh it just requested. Measured: four of four intakes after a commit needed two or
160
+ // three calls because this handler returned before a 12–16 s refresh had finished. The refresh
161
+ // still runs in the detached child; this only re-reads the receipt, which stays the one
162
+ // authority for currency (same workspace, same HEAD, or it is not accepted).
163
+ let wait;
164
+ const bound = context.freshnessWaitMs ?? 0;
165
+ if (!freshnessCurrent && a.persist === true && refresh !== undefined && refresh.status !== 'failed' && bound > 0) {
166
+ const now = context.now ?? (() => Date.now());
167
+ const sleep = context.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
168
+ const started = now();
169
+ let outcome = 'timeout';
170
+ while (now() - started < bound) {
171
+ await sleep(TRIAGE_POLL_MS);
172
+ freshness = readReceipt();
173
+ if ((0, freshness_coordinator_1.intakeUsable)(freshness)) {
174
+ freshnessCurrent = true;
175
+ outcome = 'current';
176
+ break;
177
+ }
178
+ if (freshness !== null && SETTLED_UNUSABLE.has(freshness.state)) {
179
+ outcome = 'ended';
180
+ break;
181
+ }
182
+ }
183
+ wait = { waitedMs: now() - started, outcome };
184
+ }
138
185
  const graph = readGraphEvidence(root, currentHead, documents);
139
186
  const fresh = (0, test_evidence_1.isFresh)(evidence, currentHead) && evidence?.passed === true;
140
187
  const lineageEvidence = {};
@@ -218,7 +265,7 @@ function createRequirementTriageHandlers(context) {
218
265
  graph: { status: graph.status, sourceCommit: graph.sourceCommit, graphAsOf: graph.graphAsOf, resolutionLimits: graph.resolutionLimits },
219
266
  graphBasis: { head: currentHead, governedDocumentCount: documents.length, scannedSourceCount: scanned.length },
220
267
  freshness: freshness === null ? { state: 'absent' } : freshness,
221
- refresh: refresh ?? { status: freshnessCurrent ? 'not-needed' : 'unavailable' } };
268
+ refresh: refresh !== undefined ? { ...refresh, ...(wait ?? {}) } : { status: freshnessCurrent ? 'not-needed' : 'unavailable' } };
222
269
  if (!a.persist || !freshnessCurrent || freshness === null)
223
270
  return answer;
224
271
  // @implements A-SPEC-729 — persisted AND issued on the ledger; intake accepts nothing else.
@@ -22,6 +22,8 @@ export declare class HandlerRefusal extends Error {
22
22
  readonly holmesRefusal = true;
23
23
  constructor(message: string);
24
24
  }
25
+ /** GET a localhost JSON endpoint (used by rtm_dashboard to read the census off the server it launched). */
26
+ export declare function fetchJson(url: string): Promise<any>;
25
27
  /** Marker test that survives realm boundaries (jest's instanceof does not). */
26
28
  export declare function isHandlerRefusal(e: unknown): e is Error;
27
29
  import { ChangeSourceInfo } from '../project/change-source';
@@ -747,10 +749,12 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
747
749
  state: string;
748
750
  };
749
751
  refresh: {
752
+ waitedMs?: number | undefined;
753
+ outcome?: "current" | "timeout" | "ended" | undefined;
750
754
  status: "spawned" | "coalesced" | "failed";
751
755
  generation?: string;
752
756
  } | {
753
- status: "unavailable" | "not-needed";
757
+ status: string;
754
758
  };
755
759
  lexicalOnly?: true | undefined;
756
760
  verdict: import("../review/requirement-triage").RequirementVerdict;
@@ -805,10 +809,12 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
805
809
  state: string;
806
810
  };
807
811
  refresh: {
812
+ waitedMs?: number | undefined;
813
+ outcome?: "current" | "timeout" | "ended" | undefined;
808
814
  status: "spawned" | "coalesced" | "failed";
809
815
  generation?: string;
810
816
  } | {
811
- status: "unavailable" | "not-needed";
817
+ status: string;
812
818
  };
813
819
  lexicalOnly?: true | undefined;
814
820
  candidates: {
@@ -885,10 +891,12 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
885
891
  state: string;
886
892
  };
887
893
  refresh: {
894
+ waitedMs?: number | undefined;
895
+ outcome?: "current" | "timeout" | "ended" | undefined;
888
896
  status: "spawned" | "coalesced" | "failed";
889
897
  generation?: string;
890
898
  } | {
891
- status: "unavailable" | "not-needed";
899
+ status: string;
892
900
  };
893
901
  lexicalOnly?: true | undefined;
894
902
  verdict: import("../review/requirement-triage").RequirementVerdict;
@@ -949,10 +957,12 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
949
957
  state: string;
950
958
  };
951
959
  refresh: {
960
+ waitedMs?: number | undefined;
961
+ outcome?: "current" | "timeout" | "ended" | undefined;
952
962
  status: "spawned" | "coalesced" | "failed";
953
963
  generation?: string;
954
964
  } | {
955
- status: "unavailable" | "not-needed";
965
+ status: string;
956
966
  };
957
967
  lexicalOnly?: true | undefined;
958
968
  candidates: {
@@ -34,11 +34,12 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.HandlerRefusal = void 0;
37
+ exports.fetchJson = fetchJson;
37
38
  exports.isHandlerRefusal = isHandlerRefusal;
38
39
  exports.unreadableAmong = unreadableAmong;
39
40
  exports.makeHandlers = makeHandlers;
40
41
  exports.collectDecisions = collectDecisions;
41
- // @implements A-SPEC-718.1, A-SPEC-718.2, A-SPEC-723, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732, A-SPEC-754
42
+ // @implements A-SPEC-718.1, A-SPEC-718.2, A-SPEC-723, A-SPEC-723.1, A-SPEC-545.6, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732, A-SPEC-754
42
43
  const operator_recovery_1 = require("./operator-recovery");
43
44
  // @implements A-SPEC-643
44
45
  // @implements A-SPEC-642
@@ -148,7 +149,11 @@ exports.HandlerRefusal = HandlerRefusal;
148
149
  /** GET a localhost JSON endpoint (used by rtm_dashboard to read the census off the server it launched). */
149
150
  function fetchJson(url) {
150
151
  return new Promise((resolve, reject) => {
151
- http.get(url, (res) => {
152
+ // @implements A-SPEC-545.6 — `agent: false`: one connection per read, never a pooled socket. The
153
+ // caller does seconds of synchronous work between reads; with a kept-alive socket the dashboard
154
+ // server had closed it by then, this process had not yet seen the close, and the next read failed
155
+ // with ECONNRESET (measured: the second `rtm_dashboard` call, 7 of 7 whole-suite runs).
156
+ http.get(url, { agent: false }, (res) => {
152
157
  let data = '';
153
158
  res.on('data', (c) => (data += c));
154
159
  res.on('end', () => { try {
@@ -780,6 +785,8 @@ function makeRawHandlers(store, opts) {
780
785
  assertStoreReachable: (tool, root) => assertSpecStoreReachable(tool, store, root),
781
786
  refusal: reason => new HandlerRefusal(reason),
782
787
  requestFreshness: rtm_refresh_1.requestBackgroundFreshness,
788
+ // @implements A-SPEC-723.1 — an intake call waits for the refresh it requested, within this bound.
789
+ freshnessWaitMs: (0, requirement_triage_1.triageWaitMsFrom)(process.env),
783
790
  });
784
791
  const resolver = (specs) => (id) => specs.find((s) => s.id === id) ?? null;
785
792
  // @implements A-SPEC-100.2, A-SPEC-128, A-SPEC-138, A-SPEC-140.2, A-SPEC-189, A-SPEC-461, A-SPEC-512.2, A-SPEC-513.1, A-SPEC-524.1
@@ -102,6 +102,13 @@ export interface MaintenanceAnalysisInput {
102
102
  * property that lets the replay benchmark run it against a materialised tree.
103
103
  */
104
104
  changePrior?: Record<string, number>;
105
+ /**
106
+ * @implements A-SPEC-469.1
107
+ * Recency-weighted co-change of each path with the CHANGED files (`review/co-change.ts`), read by
108
+ * the caller from history up to the analysed state. Used only when `changedFiles` names a file, and
109
+ * only to rank `impacts.rankedImpact`. Absent: that list is the graph ranking alone.
110
+ */
111
+ coChange?: Record<string, number>;
105
112
  /**
106
113
  * @implements A-SPEC-388
107
114
  * Per-file multipliers from how much each file's COMMIT PROSE talks like the request, normalised
@@ -311,10 +318,12 @@ export interface MaintenanceAnalysis {
311
318
  * (HOLMES), the graded top-10's 0.5713 / 0.1611, and both metrics won on all three corpora,
312
319
  * which is the bar that A-SPEC-309/313 set and their expansions failed.
313
320
  */
321
+ /** @implements A-SPEC-469.1 — `coChange`: the row's recency-weighted co-change with the changed files, when it has one. */
314
322
  rankedImpact: Array<{
315
323
  file: string;
316
324
  score: number;
317
325
  semCos?: number;
326
+ coChange?: number;
318
327
  }>;
319
328
  /**
320
329
  * @implements A-SPEC-289
@@ -449,6 +458,14 @@ export interface MaintenanceAnalysis {
449
458
  };
450
459
  evidenceDigest: string;
451
460
  }
461
+ /**
462
+ * @implements A-SPEC-745.1
463
+ * Is this test file named after that source file? The convention a person greps by: the test's
464
+ * basename without its extension and test markers (`.test`, `.spec`, a leading `test_`, a trailing
465
+ * `_test`, a trailing `Test`/`Tests`) equals the source's basename without extension, or starts with
466
+ * it followed by `-`, `_` or `.`. A name that merely CONTAINS the source name is not a match.
467
+ */
468
+ export declare function testNameMatches(testPath: string, sourcePath: string): boolean;
452
469
  /**
453
470
  * Decode a pathname as git prints it in `--name-only`/`--name-status` output. With the default
454
471
  * `core.quotepath=true`, any non-ASCII or control byte makes git wrap the name in double quotes and
@@ -1,10 +1,11 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.ANALYZE_TEXT_CAP = exports.ANALYZE_LIST_CAP = exports.PRIMARY_TIER_WIDTH = exports.EVIDENCE_DIMENSIONS = exports.CONFIDENCE_NOTE = exports.MAINTENANCE_ANALYSIS_EXTRACTOR = exports.MAINTENANCE_ANALYSIS_SCHEMA = void 0;
4
+ exports.testNameMatches = testNameMatches;
4
5
  exports.unquoteGitPath = unquoteGitPath;
5
6
  exports.analyzeMaintenance = analyzeMaintenance;
6
7
  exports.boundAnalysis = boundAnalysis;
7
- // @implements A-SPEC-745, A-SPEC-741, A-SPEC-741.1, A-SPEC-740, A-SPEC-725, A-SPEC-310
8
+ // @implements A-SPEC-745, A-SPEC-745.1, A-SPEC-469.1,A-SPEC-741, A-SPEC-741.1, A-SPEC-740, A-SPEC-725, A-SPEC-310
8
9
  // @implements A-SPEC-295
9
10
  // @implements A-SPEC-294
10
11
  // @implements A-SPEC-293
@@ -28,6 +29,8 @@ const admission_1 = require("../semantic/admission");
28
29
  const unreadable_paths_1 = require("../semantic/unreadable-paths");
29
30
  const dense_retrieval_1 = require("../review/dense-retrieval");
30
31
  const test_scope_1 = require("../rtm/test-scope");
32
+ const test_files_1 = require("../cpg/test-files");
33
+ const co_change_1 = require("../review/co-change");
31
34
  const scope_1 = require("../review/scope");
32
35
  // @implements A-SPEC-469 — the SAME code path the S-484 measurement ran; identity is the reason
33
36
  // the measured numbers transfer to the shipped surface.
@@ -98,6 +101,24 @@ exports.EVIDENCE_DIMENSIONS = [
98
101
  * precision), and tuning a threshold on 12 samples would be fitting noise.
99
102
  */
100
103
  exports.PRIMARY_TIER_WIDTH = 3;
104
+ /**
105
+ * @implements A-SPEC-745.1
106
+ * Is this test file named after that source file? The convention a person greps by: the test's
107
+ * basename without its extension and test markers (`.test`, `.spec`, a leading `test_`, a trailing
108
+ * `_test`, a trailing `Test`/`Tests`) equals the source's basename without extension, or starts with
109
+ * it followed by `-`, `_` or `.`. A name that merely CONTAINS the source name is not a match.
110
+ */
111
+ function testNameMatches(testPath, sourcePath) {
112
+ const base = (p) => p.slice(p.lastIndexOf('/') + 1);
113
+ const stem = base(sourcePath).replace(/\.[^.]+$/, '');
114
+ if (stem === '')
115
+ return false;
116
+ let name = base(testPath).replace(/\.[^.]+$/, '').replace(/\.(test|spec)$/i, '');
117
+ if (/^test_/i.test(name))
118
+ name = name.slice(5);
119
+ name = name.replace(/_test$/i, '').replace(/Tests?$/, '');
120
+ return name === stem || name.startsWith(`${stem}-`) || name.startsWith(`${stem}_`) || name.startsWith(`${stem}.`);
121
+ }
101
122
  function sortedUnique(values) {
102
123
  return [...new Set(values)].sort((a, b) => a.localeCompare(b));
103
124
  }
@@ -402,6 +423,14 @@ function analyzeMaintenance(input) {
402
423
  // symbols the request actually named keep the front, and the data-flow neighbours are appended.
403
424
  const defUseTerms = input.defUse === undefined ? [] : (0, localize_1.significantTerms)(input.request);
404
425
  const symbolsByFile = new Map(scanned.map((f) => [f.sourcePath, f.symbols.map((sy) => sy.qualifiedName)]));
426
+ // @implements A-SPEC-756.4 — MEASURED AND WITHDRAWN: "the functions bound to the specs this
427
+ // request cites or matches lead a candidate's list" (rule R of A-SPEC-756.1, weight c/n per bound
428
+ // function, five leading). On the fixed replay windows it changed the list in 92 of 120 cases on
429
+ // this repository and moved function-axis recall at 10 by +0.0056 against a detectable bound of
430
+ // 0.0157; with history binding −0.0037 against 0.0247; no case moved on the second corpus. A
431
+ // function-level spec link does not find the changed function better than the name match below.
432
+ // Do not re-add an ordering by bound specs without a new pre-registered measurement; the replay's
433
+ // `anchorArms` reproduces this one (build d47d6523 for the rule itself).
405
434
  const symbolsOf = (file, matched) => {
406
435
  const facts = input.defUse?.[file];
407
436
  if (facts === undefined)
@@ -566,9 +595,17 @@ function analyzeMaintenance(input) {
566
595
  const seeds = direct.flatMap((qualifiedName) => input.graph.codeNodeIds(qualifiedName));
567
596
  const seen = new Set(seeds);
568
597
  const candidateSpecs = new Set(localization.matchedSpecs);
598
+ // @implements A-SPEC-756.1 — gathered per FILE, not per function. These specs choose the tests,
599
+ // and a function no longer carries what its siblings implement: gathering function by function
600
+ // dropped test recall 0.454 -> 0.425 on the first place-binding build. `specsOfFile` returns for
601
+ // any function exactly what `specsOf` returned before anchors were bound to functions.
602
+ const specsOfCode = (id) => {
603
+ const at = id.lastIndexOf('@');
604
+ return at < 0 ? input.graph.specsOf(id) : input.graph.specsOfFile(id.slice(at + 1));
605
+ };
569
606
  for (const qualifiedName of direct) {
570
607
  for (const id of input.graph.codeNodeIds(qualifiedName)) {
571
- for (const specId of input.graph.specsOf(id))
608
+ for (const specId of specsOfCode(id))
572
609
  candidateSpecs.add(specId.replace(/^SPEC:/, ''));
573
610
  }
574
611
  }
@@ -632,7 +669,7 @@ function analyzeMaintenance(input) {
632
669
  const transitive = sortedUnique([...transitiveIds].map(codeQualifiedName).filter((qn) => !direct.includes(qn)));
633
670
  for (const qualifiedName of transitive) {
634
671
  for (const id of input.graph.codeNodeIds(qualifiedName)) {
635
- for (const specId of input.graph.specsOf(id))
672
+ for (const specId of specsOfCode(id))
636
673
  candidateSpecs.add(specId.replace(/^SPEC:/, ''));
637
674
  }
638
675
  }
@@ -657,7 +694,31 @@ function analyzeMaintenance(input) {
657
694
  const rankedImpactSeeds = new Map(rankedImpactSeedSymbols
658
695
  .flatMap((qualifiedName) => input.graph.codeNodeIds(qualifiedName))
659
696
  .map((id) => [id, 1]));
660
- const rankedImpact = (0, assoc_arm_1.pprImpactRanked)((0, assoc_arm_1.graphViewOf)(input.graph.dumpCanonical()), rankedImpactSeeds, new Set(input.changedFiles ?? []), assoc_arm_1.RANKED_IMPACT_K, assoc_arm_1.RANKED_IMPACT_CONFIG);
697
+ const graphRankedImpact = (0, assoc_arm_1.pprImpactRanked)((0, assoc_arm_1.graphViewOf)(input.graph.dumpCanonical()), rankedImpactSeeds, new Set(input.changedFiles ?? []), assoc_arm_1.RANKED_IMPACT_K, assoc_arm_1.RANKED_IMPACT_CONFIG);
698
+ // @implements A-SPEC-469.1 — for a NAMED change, fuse the graph ranking with what history says
699
+ // changed together with those files (recency-weighted, supplied by the caller: no I/O here).
700
+ // Reciprocal-rank fusion, the first ten kept. A row keeps its graph score (0 when the graph did not
701
+ // rank the file) and carries its co-change weight. Only scanned, unchanged files can enter — the
702
+ // scan holds no test files. Measured: recall@10 0.337 -> 0.442 on the second corpus, replicated;
703
+ // the request-only list was not measured and is left as it was.
704
+ const rankedImpact = (() => {
705
+ const weights = input.coChange;
706
+ const changed = new Set(input.changedFiles ?? []);
707
+ if (weights === undefined || changed.size === 0)
708
+ return graphRankedImpact;
709
+ const scannedPaths = new Set(scanned.map((file) => file.sourcePath));
710
+ const coList = Object.entries(weights)
711
+ .filter(([file, weight]) => weight > 0 && scannedPaths.has(file) && !changed.has(file))
712
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
713
+ .map(([file]) => file);
714
+ if (coList.length === 0)
715
+ return graphRankedImpact;
716
+ const graphRow = new Map(graphRankedImpact.map((row) => [row.file, row]));
717
+ return (0, co_change_1.fuseRanked)(graphRankedImpact.map((row) => row.file), coList).slice(0, assoc_arm_1.RANKED_IMPACT_K).map(({ file }) => ({
718
+ ...(graphRow.get(file) ?? { file, score: 0 }),
719
+ ...(weights[file] !== undefined && weights[file] > 0 ? { coChange: weights[file] } : {}),
720
+ }));
721
+ })();
661
722
  // @implements A-SPEC-486 — the same additive verdict on the graded impact surface: a cached
662
723
  // cosine per row, no row added or removed, score untouched.
663
724
  {
@@ -1098,6 +1159,35 @@ function analyzeMaintenance(input) {
1098
1159
  specRank.set(id, index);
1099
1160
  });
1100
1161
  const relevanceOrderedSpecs = [...specIds].sort((a, b) => (specRank.get(a) ?? Infinity) - (specRank.get(b) ?? Infinity) || a.localeCompare(b));
1162
+ // @implements A-SPEC-745.1 — the same for `relevantTests`: the same set, in relevance order. Path
1163
+ // order made the ten the response keeps `src/holmes/assoc/…` for every request here. Seeds are the
1164
+ // changed source files when given, else the ranked candidates. A test named after a seed comes
1165
+ // first, then a test anchoring a spec the seed anchors, then the rest; ties keep path order.
1166
+ // Measured on the fixed replay windows: recall@10 of the returned list 0.206 -> 0.481 here.
1167
+ const changedSources = (input.changedFiles ?? []).filter((file) => !(0, test_files_1.isTestFile)(file));
1168
+ const testSeeds = changedSources.length > 0 ? changedSources : candidates.map((candidate) => candidate.file);
1169
+ // The first seed that anchors each spec, computed once: a seed can anchor a hundred specs and the
1170
+ // list can hold hundreds of tests.
1171
+ const firstSeedOfSpec = new Map();
1172
+ testSeeds.forEach((seed, index) => {
1173
+ for (const id of anchorsOf.get(seed) ?? [])
1174
+ if (!firstSeedOfSpec.has(id))
1175
+ firstSeedOfSpec.set(id, index);
1176
+ });
1177
+ const testRank = (test) => {
1178
+ const byName = testSeeds.findIndex((seed) => testNameMatches(test, seed));
1179
+ if (byName >= 0)
1180
+ return byName;
1181
+ let bySpec = Infinity;
1182
+ for (const id of input.testAnchors[test] ?? [])
1183
+ bySpec = Math.min(bySpec, firstSeedOfSpec.get(id) ?? Infinity);
1184
+ return bySpec === Infinity ? Infinity : testSeeds.length + bySpec;
1185
+ };
1186
+ const testRanks = new Map(relevantTests.map((test) => [test, testRank(test)]));
1187
+ const relevanceOrderedTests = [...relevantTests].sort((a, b) => {
1188
+ const ra = testRanks.get(a), rb = testRanks.get(b);
1189
+ return ra === rb ? a.localeCompare(b) : ra - rb;
1190
+ });
1101
1191
  const evidence = {
1102
1192
  schemaVersion: exports.MAINTENANCE_ANALYSIS_SCHEMA,
1103
1193
  extractorVersion: exports.MAINTENANCE_ANALYSIS_EXTRACTOR,
@@ -1143,7 +1233,7 @@ function analyzeMaintenance(input) {
1143
1233
  unactionableCriteria,
1144
1234
  intent,
1145
1235
  testScope,
1146
- relevantTests,
1236
+ relevantTests: relevanceOrderedTests,
1147
1237
  relevantTestSpecs,
1148
1238
  historicalRationale: history,
1149
1239
  contextBundle: input.contextBundle ?? null,
@@ -0,0 +1,30 @@
1
+ export interface CoChangeOptions {
2
+ /** Commits read, newest first. */
3
+ limit: number;
4
+ /** A commit touching more files than this says nothing about any pair (a mass rename, a release). */
5
+ maxCommitFiles: number;
6
+ /** Age, in commits, at which a shared commit counts half. */
7
+ halfLife: number;
8
+ }
9
+ /** The values measured. Not tuned afterwards: a change here is a new measurement. */
10
+ export declare const CO_CHANGE_DEFAULTS: CoChangeOptions;
11
+ /**
12
+ * Recency-weighted co-change of every path with the seeds, from commits listed newest first.
13
+ * A commit that touches a seed adds `0.5^(age / halfLife)` to every other path it touches; `age` is
14
+ * the commit's position in the list. Seeds themselves are never returned.
15
+ */
16
+ export declare function coChangeWeights(commits: ReadonlyArray<readonly string[]>, seeds: readonly string[], opts?: CoChangeOptions): Map<string, number>;
17
+ /**
18
+ * The same, read from git: the `limit` non-merge commits reachable from `before`, itself included and
19
+ * nothing after it. Unreadable history is an empty answer, never an error — the caller ranks without
20
+ * the signal.
21
+ */
22
+ export declare function coChangeFromGit(root: string, before: string, seeds: readonly string[], opts?: CoChangeOptions): Map<string, number>;
23
+ /**
24
+ * Reciprocal-rank fusion of two ranked lists (k = 60, the constant of the original paper, untuned):
25
+ * a file's score is the sum of 1 / (k + rank) over the lists that hold it. Ties keep path order.
26
+ */
27
+ export declare function fuseRanked(a: readonly string[], b: readonly string[], k?: number): Array<{
28
+ file: string;
29
+ score: number;
30
+ }>;