@holmes-lab/holmes-kit 0.19.6 → 0.20.0

package/dist/holmes/mcp/handlers/workspace-queries.js

@@ -0,0 +1,193 @@
+"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.createWorkspaceQueryHandlers = createWorkspaceQueryHandlers;
+// @implements A-SPEC-610, A-SPEC-100.2, A-SPEC-121.2, A-SPEC-128, A-SPEC-131, A-SPEC-146, A-SPEC-189, A-SPEC-419, A-SPEC-461, A-SPEC-496, A-SPEC-506.1
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const validator_1 = require("../../spec/validator");
+const rtm_check_1 = require("../../rtm/rtm-check");
+const test_scope_1 = require("../../rtm/test-scope");
+const gap_analyzer_1 = require("../../rtm/gap-analyzer");
+const spec_types_1 = require("../../spec/spec-types");
+const breaking_change_1 = require("../../spec/breaking-change");
+const consistency_lints_1 = require("../../cpg/consistency-lints");
+const localize_1 = require("../../rtm/localize");
+const tier_1 = require("../../semantic/tier");
+const vector_cache_1 = require("../../semantic/vector-cache");
+const embedder_1 = require("../../semantic/embedder");
+// @implements A-SPEC-496 — policy parity: the direct localization path reranks with the exact
+// A-SPEC-478 math, extracted pure.
+const hit_rerank_1 = require("../../semantic/hit-rerank");
+function createWorkspaceQueryHandlers(context) {
+    return {
+        async rtm_check(a) {
+            // @implements A-SPEC-461 — a root that names a different project would check THIS project's
+            // specs against THAT project's files and report clean — A-SPEC-191 §15. foreignRootReason
+            // returns null for an absent or matching root, so the spec-only and correct-root paths are
+            // unaffected. Shared guard (citation_pin/maintenance_analyze use it), not a copy (A-SPEC-449).
+            {
+                const foreign = context.foreignRootReason(a?.root);
+                if (foreign)
+                    return { ok: false, reason: foreign };
+            }
+            const specs = await context.listSpecs();
+            // rtm_check runs on the GOVERNED set only (excludes archived legacy +
+            // JOB specs, which otherwise flood orphan/dangling results; see
+            // ADR-010).
+            const issues = (0, rtm_check_1.rtmCheck)((0, spec_types_1.filterGoverned)(specs));
+            // @implements A-SPEC-146 — a REPORT, not a verdict: ADR-013 named formulaic `none` a
+            // revisit trigger for a human, and `(unset)` shows how far the corpus has converged.
+            const breakingChangeDistribution_ = (0, breaking_change_1.breakingChangeDistribution)((0, spec_types_1.filterGoverned)(specs));
+            if (a?.root) {
+                // @implements A-SPEC-189 §14 (round 13) — the derivation was computed and discarded, so the
+                // advertised "a subdirectory resolves up to it" held for `taint_scan` and no one else.
+                const root = context.projectRootOf(a.root);
+                // Citation drift: a REQ's cited source may have been edited since it was read, which silently
+                // invalidates the requirement derived from it. Only refs that resolve to a file INSIDE the
+                // repo are re-hashed — an unresolvable ref (external ticket, no adapter configured) is not
+                // evidence of drift, and a path escaping the repo is not ours to read.
+                const readLocal = (ref) => {
+                    const abs = path.resolve(root, ref);
+                    if (!abs.startsWith(path.resolve(root) + path.sep))
+                        return null;
+                    try {
+                        return fs.readFileSync(abs, 'utf8');
+                    }
+                    catch {
+                        return null;
+                    }
+                };
+                for (const s of specs) {
+                    if (s.type !== 'REQ' || s.frontmatter.source == null)
+                        continue;
+                    for (const d of (0, validator_1.verifyCitationDigests)(s.frontmatter.source, readLocal)) {
+                        issues.push({ level: d.level, code: d.code, message: `${s.id}: ${d.message}` });
+                    }
+                }
+                const scanned = context.cachedScan(root, root);
+                // checkImplements checks @implements A-SPEC refs against the FULL
+                // spec id set (not filterGoverned) — it's an existence check: any
+                // existing spec id is a valid anchor target.
+                issues.push(...(0, rtm_check_1.checkImplements)(scanned, specs));
+                // L6 convergence gaps (ADVISORY, not issues): where implementation and the governed spec set
+                // have drifted apart — unimplemented approved specs, unanchored source, untested specs. Feeds
+                // the convergence loop's "pick next work"; an unimplemented spec is normal mid-development.
+                const gaps = (0, gap_analyzer_1.computeConvergenceGaps)(scanned, (0, spec_types_1.filterGoverned)(specs), (0, test_scope_1.scanTestAnchors)(root));
+                return { issues, gaps, breakingChangeDistribution: breakingChangeDistribution_ };
+            }
+            return { issues, breakingChangeDistribution: breakingChangeDistribution_ };
+        },
+        async cpg_scan(a) {
+            // @implements A-SPEC-189 §14 (round 13) — the derivation was computed and discarded, so the
+            // advertised "a subdirectory resolves up to it" held for `taint_scan` and no one else.
+            const root = context.projectRootOf(a.root);
+            // @implements A-SPEC-131
+            // The skip report is part of the answer: a caller cannot distinguish "clean tree" from "tree
+            // with casualties" by counts alone. Bounded listing (50), complete count.
+            const { scanned, skipped } = context.cachedScanWithReport(root);
+            const symbols = scanned.reduce((n, f) => n + f.symbols.length, 0);
+            const base = { files: scanned.length, symbols, skipped: skipped.slice(0, 50), skippedCount: skipped.length };
+            if (!a.lints)
+                return base;
+            // @implements A-SPEC-506.1 — opt-in consistency lints (P-G/P-J field incidents): WARNING
+            // signals only, additive field only, Python only; the default path above is byte-identical.
+            const defined = new Set();
+            for (const f of scanned)
+                for (const s of f.symbols) {
+                    defined.add(s.name);
+                    const last = s.name.split('.').pop();
+                    if (last)
+                        defined.add(last);
+                }
+            const dynamicRef = [];
+            const asyncBlocking = [];
+            for (const f of scanned) {
+                if (!f.sourcePath.endsWith('.py'))
+                    continue;
+                let code;
+                try {
+                    code = fs.readFileSync(path.join(root, f.sourcePath), 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                for (const hit of (0, consistency_lints_1.dynamicRefFindings)(code, defined))
+                    dynamicRef.push({ file: f.sourcePath, ...hit });
+                for (const hit of (0, consistency_lints_1.asyncBlockingFindings)(code))
+                    asyncBlocking.push({ file: f.sourcePath, ...hit });
+            }
+            return { ...base, lints: { dynamicRef, asyncBlocking, limits: [...consistency_lints_1.LINT_LIMITS] } };
+        },
+        async issue_localize(a) {
+            context.assertStoreReachable('issue_localize', a.root); // @implements A-SPEC-419
+            // N1: deterministic localization report — CPG lexical match fused with the RTM spec hop.
+            // @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, root);
+            const specs = await context.listSpecs();
+            const governed = (0, spec_types_1.filterGoverned)(specs);
+            const report = (0, localize_1.localizeIssue)(a.issue, scanned, governed, a.topN ?? 10);
+            // @implements A-SPEC-496 — parity with A-SPEC-478: the SAME uncited gate, the SAME math
+            // (cached vectors only, set fixed, covered hits move, why-line attached). Any missing
+            // signal — no tier, no key, cold cache, embed failure — leaves the report untouched;
+            // localization itself never fails because of the semantic layer.
+            //
+            // A spec-intent-vector assist (REQ-568 S3) was wired ahead of localizeIssue here and REVERTED
+            // on its pre-registered replay — see rtm/localize.ts at the matchedSpecs join for the numbers.
+            try {
+                if (report.hits.length > 1
+                    && (0, localize_1.citationsIn)(a.issue, new Set(governed.map((s) => s.id))).cited.length === 0) {
+                    const rt = (0, embedder_1.makeTierEmbedder)((0, tier_1.resolveSemanticTier)(), new vector_cache_1.VectorCache(root));
+                    if (rt !== null) {
+                        const qv = await rt.embedQuery(a.issue);
+                        const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
+                            (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+                        (0, hit_rerank_1.rerankHitsBySemantic)(report.hits, qv, (file) => {
+                            const dt = docTextOf.get(file);
+                            return dt !== undefined ? rt.cachedDocVector(dt) : null;
+                        }, rt.label);
+                    }
+                }
+            }
+            catch { /* semantic layer is additive — never block the report */ }
+            return report;
+        },
+    };
+}