@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/mcp/handlers/graph-operations.d.ts

@@ -0,0 +1,90 @@
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+import { ChangeSet, ChangeSourceInfo } from '../../project/change-source';
+import { type GraphBasis } from '../../rtm/graph-store';
+export interface GraphOperationsContext {
+    listSpecs(): Promise<Spec[]>;
+    assertStoreReachable(tool: string, root: unknown): void;
+    foreignRootReason(root?: string): string | null;
+    refusal(reason: string): Error;
+    projectRootOf(root: string): string;
+    cachedScan(root: string): ScannedFile[];
+    cacheDirFor(root: string): string;
+    deriveChangedContext(root: string, args: {
+        base?: string;
+        head?: string;
+        since?: string;
+    }, tool: string): Promise<{
+        root: string;
+        changes: ChangeSet;
+        specs: Spec[];
+        scanned: ScannedFile[];
+        bySourcePath: Map<string, ScannedFile>;
+        changeSource: ChangeSourceInfo;
+    }>;
+}
+/** Publish the complete graph for `specs` over `scanned` at the live path (A-SPEC-631 primitive). */
+export declare function publishCurrentGraph(root: string, specs: Spec[], scanned: ScannedFile[]): {
+    basis: GraphBasis;
+    nodes: number;
+    edges: number;
+};
+export type SemanticWarmOutcome = {
+    status: 'discharged';
+    tier: string;
+    computed: number;
+    cached: number;
+} | {
+    status: 'not-applicable';
+    tier: 'none';
+} | {
+    status: 'unavailable';
+    tier: string;
+};
+/**
+ * @implements A-SPEC-478 — the semantic cache WARMING lives in explicit heavy operations, so the
+ * ranking hot path only ever LOOKS UP vectors. Idempotent through the cache. The outcome says
+ * whether there was nothing to do (tier none), whether it happened, or whether a configured tier
+ * could not embed — a discharge must not record the last one as done.
+ */
+export declare function warmSemanticCache(root: string, scanned: readonly ScannedFile[]): Promise<SemanticWarmOutcome>;
+export declare function createGraphOperationsHandlers(context: GraphOperationsContext): {
+    rtm_impact(a: {
+        root: string;
+        changed: string[];
+    }): Promise<{
+        breadthWarning?: string | undefined;
+        rankedImpact: {
+            file: string;
+            score: number;
+        }[];
+        reachedByDepth: number[];
+        bounded: {
+            id: string;
+            reason: "hub" | "depth";
+            inDegree?: number;
+        }[] | undefined;
+        summariesOmitted?: number | undefined;
+        impacted: string[];
+        impactedSummaries: {
+            id: string;
+            summary: string | null;
+        }[];
+    }>;
+    rtm_reindex(a: {
+        root: string;
+        base?: string;
+        head?: string;
+        since?: string;
+    }): Promise<{
+        semanticWarm?: {
+            tier: string;
+            computed: number;
+            cached: number;
+        } | undefined;
+        changed: number;
+        nodes: number;
+        edges: number;
+        changeSource: ChangeSourceInfo;
+    }>;
+};

package/dist/holmes/mcp/handlers/graph-operations.js

@@ -0,0 +1,260 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishCurrentGraph = publishCurrentGraph;
+exports.warmSemanticCache = warmSemanticCache;
+exports.createGraphOperationsHandlers = createGraphOperationsHandlers;
+// @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
+// @implements A-SPEC-632
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const hash_cache_1 = require("../../cpg/hash-cache");
+const root_1 = require("../../project/root");
+const rtm_builder_1 = require("../../rtm/rtm-builder");
+const graph_store_1 = require("../../rtm/graph-store");
+const assoc_arm_1 = require("../../assoc/assoc-arm");
+// @implements A-SPEC-478 — the semantic tier runtime stays at the async reindex edge.
+const tier_1 = require("../../semantic/tier");
+const vector_cache_1 = require("../../semantic/vector-cache");
+const embedder_1 = require("../../semantic/embedder");
+// @implements A-SPEC-283 — bumped whenever the graph's node/edge shape changes, so a store written
+// by an older build is rebuilt rather than read with new assumptions.
+// @implements A-SPEC-568.1 — /3: nodes gained the intent `summary` column.
+const RTM_GRAPH_SCHEMA = 'rtm-graph/3';
+// @implements A-SPEC-569.3 — how many impacted specs get their intent sentence attached. A prose
+// constant, never a verdict input: the impacted list itself is never truncated.
+const SUMMARY_CAP = 40;
+// @implements A-SPEC-569.1 (revision) — /2: pre-fix 0.16.0 builds could persist forged structural
+// characters in the summary column, and every other basis field would still match after upgrading.
+// A-SPEC-283's own rule applies to us too: an older build's artifact is rebuilt, never read with
+// new assumptions.
+const RTM_EXTRACTOR_VERSION = 'holmes-rtm/2';
+// @implements A-SPEC-632 — the two rebuild paths a completed integration's discharge runs are the
+// SAME functions explicit reindex runs, so a discharged graph and a reindexed graph are one artifact.
+/** Publish the complete graph for `specs` over `scanned` at the live path (A-SPEC-631 primitive). */
+function publishCurrentGraph(root, specs, scanned) {
+    // The publication basis: the same five fields rtm_impact expects (A-SPEC-283), so what this
+    // publishes is exactly what the next query reuses.
+    const basis = {
+        graphSchema: RTM_GRAPH_SCHEMA,
+        extractorVersion: RTM_EXTRACTOR_VERSION,
+        sourceCommit: (0, graph_store_1.headCommitOf)(root, (0, root_1.cleanSubprocessEnv)()) ?? '',
+        specFingerprint: (0, graph_store_1.specFingerprint)(specs),
+        scanDigest: (0, graph_store_1.scanDigest)(scanned),
+    };
+    const { nodes, edges } = (0, graph_store_1.publishGraph)(path.join(root, '.ax', 'rtm.sqlite'), basis, (g) => (0, rtm_builder_1.buildRtm)(specs, scanned, g));
+    return { basis, nodes, edges };
+}
+/**
+ * @implements A-SPEC-478 — the semantic cache WARMING lives in explicit heavy operations, so the
+ * ranking hot path only ever LOOKS UP vectors. Idempotent through the cache. The outcome says
+ * whether there was nothing to do (tier none), whether it happened, or whether a configured tier
+ * could not embed — a discharge must not record the last one as done.
+ */
+async function warmSemanticCache(root, scanned) {
+    const tier = (0, tier_1.resolveSemanticTier)();
+    if (tier.tier === 'none')
+        return { status: 'not-applicable', tier: 'none' };
+    const configured = tier.model ? `${tier.tier}:${tier.model}` : tier.tier;
+    const rt = (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
+    if (rt === null)
+        return { status: 'unavailable', tier: configured };
+    const docTexts = scanned.map((f) => (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000));
+    const w = await rt.warm(docTexts);
+    if (docTexts.length > 0 && w.computed + w.cached === 0)
+        return { status: 'unavailable', tier: rt.label };
+    return { status: 'discharged', tier: rt.label, computed: w.computed, cached: w.cached };
+}
+function createGraphOperationsHandlers(context) {
+    return {
+        async rtm_impact(a) {
+            context.assertStoreReachable('rtm_impact', a.root); // @implements A-SPEC-433
+            // @implements A-SPEC-614 — do not scan another workspace with this bound spec store.
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            // @implements A-SPEC-189 §14 (round 13) — `context.projectRootOf(a.root)` was called as a bare
+            // statement: its only effect was to throw on a bad path, and the advertised contract ("a
+            // subdirectory resolves up to it") was dropped on the floor. `taint_scan` one function away
+            // honours it, so the same argument answered about two different trees depending on which tool
+            // was asked. Bind the derivation and use it.
+            const root = context.projectRootOf(a.root);
+            const scanned = context.cachedScan(root);
+            // @implements A-SPEC-569.2 — the impact/advisory graph is APPROVED-ONLY. A draft needs no
+            // approval to exist, and the 0.16.0 adversarial round showed one reaching the agent-visible
+            // channels (impacted closure, advisory anchor summaries) — the trust boundary for those
+            // channels is the act of approval. NOT filterGoverned: that predicate passes drafts (it only
+            // drops outdated/legacy), which is exactly what let this in. Diagnosis (rtm_check) and
+            // matching (issue_localize / maintenance_analyze) keep their own populations — the replay
+            // pins were measured on them.
+            const specs = (await context.listSpecs()).filter((s) => s.status === 'approved');
+            // @implements A-SPEC-283
+            // Reuse the persisted graph when its basis still holds. Measured: on the warm path the graph
+            // build is ~81% of the cost and reopening is ~0ms. `scanDigest` is the field that makes this
+            // safe — an uncommitted edit never moves HEAD, so a commit-only basis would happily serve a
+            // graph describing content the working tree no longer has.
+            const expected = {
+                graphSchema: RTM_GRAPH_SCHEMA,
+                extractorVersion: RTM_EXTRACTOR_VERSION,
+                sourceCommit: (0, graph_store_1.headCommitOf)(root, (0, root_1.cleanSubprocessEnv)()) ?? '',
+                specFingerprint: (0, graph_store_1.specFingerprint)(specs),
+                scanDigest: (0, graph_store_1.scanDigest)(scanned),
+            };
+            // @implements A-SPEC-631 — the live file is NEVER cleared in place. `publishable`: reuse it
+            // while every basis field holds; otherwise build the complete graph in a private temporary
+            // database, answer from it, and publish it by one atomic rename only after the answer stands.
+            // Reproduced 2026-09-13: the previous in-place clear+rebuild (this is also the Stop hook's
+            // refresh path) let a concurrent approval read zero nodes as "no impact", and a refresher
+            // killed mid-way left an empty, basis-less file behind for every later reader.
+            const opened = (0, graph_store_1.openReusableGraph)(path.join(root, '.ax', 'rtm.sqlite'), expected, { publishable: true });
+            const g = opened.graph;
+            let answered = false;
+            try {
+                if (!opened.reusable) {
+                    (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                    opened.commitBasis();
+                }
+                // explainImpact, not impactedBy: the bounds and the breadth signal must reach the caller.
+                // An impact set is not just a list — a broad one means "review the contract", and a consumer
+                // that cannot tell the difference will try to bundle two hundred call sites.
+                const { specs: impactedRaw, reachedByDepth, stoppedAt, seedIsHub } = (0, rtm_builder_1.explainImpact)(g, a.changed);
+                // @implements A-SPEC-569.2 — the closure walks EDGES, and an implements edge is owned by
+                // the code file, so an anchor naming a draft (or a spec nobody wrote) still emits one —
+                // deliberately, for rtm_check's dangling diagnosis. The CHANNEL filter is node existence:
+                // approved-only specs were given nodes above, so only sealed intent reaches the caller.
+                const impacted = impactedRaw.filter((id) => g.hasNode(id));
+                // @implements A-SPEC-469 — the graded FILE surface beside the spec closure, same code path
+                // as the S-484 measurement (identity, not reimplementation). Seeds are the changed symbols'
+                // nodes; the files that own them are excluded — a prediction naming the change itself is
+                // vacuously true. The closure fields above stay exactly as they were: mass never enters a
+                // gate decision.
+                const riSeeds = new Map(a.changed.flatMap((qn) => g.codeNodeIds(qn)).map((id) => [id, 1]));
+                const riExclude = new Set([...riSeeds.keys()]
+                    .map((id) => (id.includes('@') ? id.slice(id.lastIndexOf('@') + 1) : ''))
+                    .filter((f) => f !== ''));
+                const rankedImpact = (0, assoc_arm_1.pprImpactRanked)((0, assoc_arm_1.graphViewOf)(g.dumpCanonical()), riSeeds, riExclude, assoc_arm_1.RANKED_IMPACT_K, assoc_arm_1.RANKED_IMPACT_CONFIG);
+                // @implements A-SPEC-568.2 — the intent sentence beside every impacted spec id, same order
+                // as `impacted` (which stays a bare id list for its existing consumers). Information only:
+                // nothing reads it back into the walk, the ranking or any gate.
+                // @implements A-SPEC-569.3 — capped: measured on this repository, uncapped summaries were
+                // 94% of a 104,706-byte response (a hub-grade impact of 339 specs). The omission is COUNTED,
+                // never silent, and `impacted` itself stays complete — only the annotation is bounded.
+                const shownSummaries = impacted.slice(0, SUMMARY_CAP);
+                const impactedSummaries = shownSummaries.map((id) => {
+                    let summary = null;
+                    try {
+                        summary = g.summaryOf(id);
+                    }
+                    catch { /* summary stays null */ }
+                    return { id, summary };
+                });
+                const summariesOmitted = impacted.length - shownSummaries.length;
+                answered = true;
+                return {
+                    impacted,
+                    impactedSummaries,
+                    ...(summariesOmitted > 0 ? { summariesOmitted } : {}),
+                    rankedImpact,
+                    reachedByDepth,
+                    bounded: stoppedAt.length > 0 ? stoppedAt.slice(0, 20) : undefined,
+                    ...(seedIsHub ? {
+                        breadthWarning: `a changed symbol has ${seedIsHub.callers} callers (hub threshold ${seedIsHub.threshold}) — this is a CONTRACT change; review the contract and its tests rather than bundling every impacted spec`,
+                    } : {}),
+                };
+            }
+            finally {
+                // Release the native SQLite handle even if build/query throws. A failed answer discards a
+                // private rebuild; a successful one publishes it — and a publication failure never
+                // overturns the answer, it only means the cache was not refreshed this time.
+                if (!answered)
+                    opened.discard();
+                else {
+                    try {
+                        opened.publish();
+                    }
+                    catch { /* answer stands; live graph unchanged */ }
+                }
+            }
+        },
+        async rtm_reindex(a) {
+            context.assertStoreReachable('rtm_reindex', a.root); // @implements A-SPEC-419
+            // Removal/re-derivation of changedFiles/changedSymbols is not needed
+            // here (rtm_reindex works off changes/specs/scanned/bySourcePath
+            // directly), but the guard+diff+scan prologue is identical to
+            // review_scope/review_prepare — see deriveChangedContext.
+            const { root, changes, specs, scanned, changeSource } = await context.deriveChangedContext(a.root, a, 'rtm_reindex');
+            const changed = changes.added.length + changes.modified.length + changes.deleted.length + changes.renamed.length;
+            // The HashCache records every changed file's content hash (A-SPEC-128 — project-root cache,
+            // no subdir leak) so an incremental consumer can skip files whose content did not move. The
+            // reindex itself publishes the FULL build below and no longer applies the diff on top of it.
+            const cache = new hash_cache_1.HashCache(context.cacheDirFor(root)); // @implements A-SPEC-128
+            const record = (files) => {
+                for (const relPath of files) {
+                    let content;
+                    try {
+                        content = fs.readFileSync(path.join(root, relPath), 'utf8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!cache.unchanged(relPath, content))
+                        cache.put(relPath, content);
+                }
+            };
+            record(changes.added);
+            record(changes.modified);
+            // @implements A-SPEC-631 — explicit reindex is a persistence operation: build the COMPLETE
+            // graph in a private temporary database, commit the matching basis, close it, and replace
+            // the live file by one atomic rename (A-SPEC-589's publication contract, now the same
+            // primitive rtm_impact uses). The post-build applyIncremental pass is gone: measured
+            // 2026-09-13, its per-file replacement rebuilt symbols but not the changed file's FILE node
+            // or imports edge, so the first reindex after a change published 4 nodes / 3 edges where the
+            // next run over the same tree published 5 / 4. The full build re-resolves every call edge
+            // against the whole scan, which is what A-SPEC-280 required (@implements A-SPEC-280).
+            const published = publishCurrentGraph(root, specs, scanned);
+            // @implements A-SPEC-478 — warming is best-effort here: reindex's own result is unaffected,
+            // and only an actual warm is reported (tier none or an unavailable tier adds no field).
+            let semanticWarm;
+            try {
+                const w = await warmSemanticCache(root, scanned);
+                if (w.status === 'discharged')
+                    semanticWarm = { tier: w.tier, computed: w.computed, cached: w.cached };
+            }
+            catch { /* warming is best-effort; reindex's own result is unaffected */ }
+            return { changed, nodes: published.nodes, edges: published.edges, changeSource,
+                ...(semanticWarm !== undefined ? { semanticWarm } : {}) };
+        },
+    };
+}

package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts

@@ -0,0 +1,34 @@
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+import { DecisionRecord, DecisionCitation } from '../../rtm/rtm-builder';
+import { ContentSource } from '../../context/bundler';
+import { MaintenanceGroundTruth, MaintenanceAnalysis } from '../maintenance-analyze';
+import { Basis } from '../basis';
+export interface MaintenanceAnalysisContext {
+    listSpecs(): Promise<Spec[]>;
+    foreignRootReason(root?: string): string | null;
+    refusal(reason: string): Error;
+    projectRootOf(root: string): string;
+    basisFor(root: string, withDisk: boolean): Basis;
+    collectDecisions(root: string, scanned: readonly ScannedFile[], specs: readonly Spec[]): {
+        decisions: DecisionRecord[];
+        citations: DecisionCitation[];
+    };
+    buildContentSource(specs: Spec[], scanned: ScannedFile[]): ContentSource;
+    specStoreBlindReason(root: string, count: number): string | null;
+    fileDigestOf(root: string, rel: string): string | null;
+}
+export declare function createMaintenanceAnalysisHandlers(context: MaintenanceAnalysisContext): {
+    maintenance_analyze(a: {
+        root: string;
+        request: string;
+        historyLimit?: number;
+        contextBudget?: number;
+        groundTruth?: MaintenanceGroundTruth;
+        persist?: boolean;
+        changedFiles?: string[];
+    }): Promise<MaintenanceAnalysis & {
+        persistedTo?: string;
+        bounded?: boolean;
+    }>;
+};