devsmind-mcp 2.4.0 → 4.0.0

package/dist/db/embedder.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Local semantic embedding via a vendored `all-MiniLM-L6-v2` (int8 ONNX), loaded through the
+ * OPTIONAL `onnxruntime-node` dependency. Self-contained on purpose — no DB, no MCP — so it can
+ * be unit-tested against known WordPiece output and a semantic sanity check in isolation.
+ *
+ * `onnxruntime-node` is in `optionalDependencies`, not `dependencies`: an install can fail on an
+ * unsupported platform without breaking devsmind. Every entry point here degrades to returning
+ * null rather than throwing, so callers just fall back to BM25-only search.
+ */
+export declare const EMBEDDING_MODEL_ID = "minilm-l6-v2-int8-v1";
+export declare const EMBEDDING_DIM = 384;
+export interface TokenizedInput {
+    inputIds: number[];
+    attentionMask: number[];
+}
+/** Tokenizes one string into [CLS] ... [SEP], padded/truncated to `maxTokens`. Exported for unit tests. */
+export declare function tokenize(text: string, maxTokens?: number): TokenizedInput | null;
+/** True if onnxruntime-node loaded, the model file exists, and the vocab parsed. Cheap after first call. */
+export declare function isEmbedderAvailable(): Promise<boolean>;
+/** L2-normalized components are in [-1,1], so a fixed scale of 127 needs no per-vector factor. */
+export declare function quantizeInt8(vec: Float32Array): Int8Array;
+/** Cosine similarity between two int8-quantized vectors, approximated via integer dot product. */
+export declare function cosineInt8(a: Int8Array, b: Int8Array): number;
+/**
+ * Embeds a batch of texts in one ONNX call. Returns null (not a rejected promise) if the
+ * embedder is unavailable for any reason — missing dependency, missing model, load failure —
+ * so every caller's fallback path is the same "treat as absent" branch, not exception handling.
+ */
+export declare function embedBatch(texts: string[]): Promise<Float32Array[] | null>;
+/**
+ * Fingerprint of the description a vector was computed from — a vector is stale the instant
+ * its description is edited, and this catches that precisely (unlike the BM25 index's coarse
+ * whole-corpus fingerprint). Not a security hash, just a fast staleness check.
+ */
+export declare function hashDescription(text: string): string;
+/** Convenience wrapper: embed one text, quantized, or null if the embedder is unavailable. */
+export declare function embedTextInt8(text: string): Promise<Int8Array | null>;
+/** Batched convenience wrapper mirroring `embedTextInt8`, for the generation paths in Phase 3. */
+export declare function embedTextsInt8(texts: string[]): Promise<Int8Array[] | null>;

package/dist/db/embedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.js","sourceRoot":"","sources":["../../src/db/embedder.ts"],"names":[],"mappings":"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"}

package/dist/db/feedback.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Compulsory-but-cheap feedback captured on every `commit_changes` call — the graph only earns
+ * trust if agents that discover it's wrong can say so, and the whole point is capturing that
+ * signal WITHOUT disrupting the working agent's flow: this module only appends, synchronously,
+ * to a local file. No extra round-trip, no live graph mutation, no agent ever blocked on this.
+ *
+ * Two files, two audiences, both under the gitignored `.devmind/local/` tree (same convention as
+ * activity.ts — private per-developer working state, never pushed):
+ *  - `feedback_graph.jsonl`   — machine-actionable. Read later by a supervised batch session
+ *                               (graph-fix tools) that verifies each entry against current code
+ *                               before writing anything to the graph. Never auto-applied live.
+ *  - `feedback_product.jsonl` — human-actionable. Aggregated by a person into "how do we make
+ *                               DevsMind better", never read by an agent to mutate anything.
+ *
+ * `"none"` is a first-class, legitimate, expected answer on every field — a required field is
+ * required to be ANSWERED, not required to contain a problem. Making "none" cheap is what stops a
+ * compulsory field from pressuring an agent into inventing issues just to fill it in.
+ */
+export type GraphFeedbackCategory = 'graph_problem' | 'edge_problem';
+export type ProductFeedbackCategory = 'tools_used' | 'dropped_and_why' | 'devsmind_better';
+/** How sure the reporting agent is. Only `confirmed` entries with evidence are strong candidates
+ * for the batch session to act on directly; `suspected` entries need the batch session to verify
+ * first (or are low priority until corroborated by a repeat report). */
+export type FeedbackConfidence = 'suspected' | 'confirmed';
+export interface FeedbackEvidence {
+    file: string;
+    line?: number;
+    snippet?: string;
+}
+export interface GraphFeedbackEntry {
+    /** Stable identity, minted at append time — what {@link markGraphFeedbackProcessed} targets. */
+    id: string;
+    ts: string;
+    session_id: string;
+    category: GraphFeedbackCategory;
+    text: string;
+    node_id?: string;
+    confidence: FeedbackConfidence;
+    evidence?: FeedbackEvidence;
+    /** Set by the batch graph-fix session once it has verified/applied this entry, so repeated
+     * batch runs don't re-chew the same report. Absent/false = not yet processed. */
+    processed?: boolean;
+}
+export interface ProductFeedbackEntry {
+    ts: string;
+    session_id: string;
+    category: ProductFeedbackCategory;
+    text: string;
+}
+/**
+ * A recurring pattern the batch graph-fix session noticed while resolving feedback — e.g. "every
+ * one of these 12 reports was the same framework's generated-binding pattern" — worth turning
+ * into a PERMANENT deterministic rule (a detector like Phase C's RTK one) instead of fixing the
+ * same class of miss by hand forever. This is a candidate log for a human to review, not something
+ * an agent acts on automatically — writing an actual detector is real engineering work.
+ */
+export interface IndexerRuleCandidate {
+    ts: string;
+    /** Short description of the pattern, e.g. "Vue computed() properties never get aliased". */
+    pattern: string;
+    /** How many feedback entries this pattern was inferred from — the priority signal. */
+    evidence_count: number;
+    /** A few representative examples (file:line style strings), not every occurrence. */
+    examples: string[];
+}
+/**
+ * Appends one graph-correction report. Evidence is required to mark an entry `confirmed` — an
+ * unevidenced report is downgraded to `suspected` regardless of what the caller claimed, since a
+ * "graph problem" with no `file:line` to check is not reconstructable once the code has moved on
+ * (this may be read weeks later, in the batch session — see the module doc).
+ */
+export declare function appendGraphFeedback(devmindPath: string, entry: {
+    session_id: string;
+    category: GraphFeedbackCategory;
+    text: string;
+    node_id?: string;
+    evidence?: FeedbackEvidence;
+}): void;
+/** Appends one product-improvement report — never read by an agent, only aggregated for a human. */
+export declare function appendProductFeedback(devmindPath: string, entry: {
+    session_id: string;
+    category: ProductFeedbackCategory;
+    text: string;
+}): void;
+/**
+ * Reads graph-feedback entries — the batch graph-fix session's input. Unprocessed only by
+ * default (`opts.includeProcessed` to see everything, e.g. for an audit/report).
+ */
+export declare function readGraphFeedback(devmindPath: string, opts?: {
+    includeProcessed?: boolean;
+}): GraphFeedbackEntry[];
+/** Reads every product-feedback entry recorded so far — for human aggregation/reporting. */
+export declare function readProductFeedback(devmindPath: string): ProductFeedbackEntry[];
+/**
+ * Marks graph-feedback entries as processed by id — rewrites the whole file (atomic temp+rename,
+ * same convention as `staging.ts`'s `writeBuffer`), since JSONL is append-only and a past line
+ * can't be edited in place. Idempotent: marking an already-processed or unknown id is a no-op for
+ * that id. Called by the batch graph-fix session once it has verified and applied (or explicitly
+ * rejected) an entry, so a later batch run never re-chews the same report.
+ */
+export declare function markGraphFeedbackProcessed(devmindPath: string, ids: string[]): void;
+/** One node/category's worth of graph feedback, grouped together — frequency is the priority
+ * signal: the same report surfacing many times means it's worth acting on first, and a single
+ * `record_alias`/`link_nodes` call can resolve every entry in the cluster at once. */
+export interface GraphFeedbackCluster {
+    node_id: string;
+    category: GraphFeedbackCategory;
+    count: number;
+    entries: GraphFeedbackEntry[];
+    /** Highest confidence among the cluster's entries — one `confirmed` report is enough to make
+     * the whole cluster worth verifying first, even alongside otherwise-`suspected` duplicates. */
+    confidence: FeedbackConfidence;
+}
+/**
+ * Groups graph-feedback entries by `(node_id, category)` and sorts by frequency (most-reported
+ * first) — the clustering the batch session's `read_graph_feedback` tool exposes, so 30 identical
+ * reports of the same RTK miss show up as ONE cluster of size 30, not 30 things to individually
+ * re-investigate.
+ */
+export declare function clusterGraphFeedback(entries: GraphFeedbackEntry[]): GraphFeedbackCluster[];
+/** Appends one indexer-rule candidate — see {@link IndexerRuleCandidate}. */
+export declare function appendIndexerRuleCandidate(devmindPath: string, entry: {
+    pattern: string;
+    evidence_count: number;
+    examples: string[];
+}): void;
+/** Reads every indexer-rule candidate recorded so far — for a human to review/prioritize. */
+export declare function readIndexerRuleCandidates(devmindPath: string): IndexerRuleCandidate[];

package/dist/db/feedback.js

@@ -0,0 +1,182 @@
+"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.appendGraphFeedback = appendGraphFeedback;
+exports.appendProductFeedback = appendProductFeedback;
+exports.readGraphFeedback = readGraphFeedback;
+exports.readProductFeedback = readProductFeedback;
+exports.markGraphFeedbackProcessed = markGraphFeedbackProcessed;
+exports.clusterGraphFeedback = clusterGraphFeedback;
+exports.appendIndexerRuleCandidate = appendIndexerRuleCandidate;
+exports.readIndexerRuleCandidates = readIndexerRuleCandidates;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const activity_1 = require("./activity");
+function graphFeedbackPath(devmindPath) {
+    return path.join((0, activity_1.localDir)(devmindPath), 'feedback_graph.jsonl');
+}
+function productFeedbackPath(devmindPath) {
+    return path.join((0, activity_1.localDir)(devmindPath), 'feedback_product.jsonl');
+}
+function indexerRuleCandidatesPath(devmindPath) {
+    return path.join((0, activity_1.localDir)(devmindPath), 'indexer_rule_candidates.jsonl');
+}
+function appendJsonl(devmindPath, target, entry) {
+    (0, activity_1.ensureGitignored)(devmindPath);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.appendFileSync(target, JSON.stringify(entry) + '\n', 'utf-8');
+}
+/**
+ * Appends one graph-correction report. Evidence is required to mark an entry `confirmed` — an
+ * unevidenced report is downgraded to `suspected` regardless of what the caller claimed, since a
+ * "graph problem" with no `file:line` to check is not reconstructable once the code has moved on
+ * (this may be read weeks later, in the batch session — see the module doc).
+ */
+function appendGraphFeedback(devmindPath, entry) {
+    const confidence = entry.evidence ? 'confirmed' : 'suspected';
+    const record = {
+        id: crypto.randomUUID(),
+        ts: new Date().toISOString(),
+        session_id: entry.session_id,
+        category: entry.category,
+        text: entry.text,
+        node_id: entry.node_id,
+        confidence,
+        evidence: entry.evidence
+    };
+    appendJsonl(devmindPath, graphFeedbackPath(devmindPath), record);
+}
+/** Appends one product-improvement report — never read by an agent, only aggregated for a human. */
+function appendProductFeedback(devmindPath, entry) {
+    const record = {
+        ts: new Date().toISOString(),
+        session_id: entry.session_id,
+        category: entry.category,
+        text: entry.text
+    };
+    appendJsonl(devmindPath, productFeedbackPath(devmindPath), record);
+}
+function readJsonl(target) {
+    if (!fs.existsSync(target))
+        return [];
+    const lines = fs.readFileSync(target, 'utf-8').split('\n').map(l => l.trim()).filter(Boolean);
+    const out = [];
+    for (const line of lines) {
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // A partially-written line (crash mid-append) — skip it rather than fail the whole read.
+        }
+    }
+    return out;
+}
+/**
+ * Reads graph-feedback entries — the batch graph-fix session's input. Unprocessed only by
+ * default (`opts.includeProcessed` to see everything, e.g. for an audit/report).
+ */
+function readGraphFeedback(devmindPath, opts = {}) {
+    const all = readJsonl(graphFeedbackPath(devmindPath));
+    return opts.includeProcessed ? all : all.filter(e => !e.processed);
+}
+/** Reads every product-feedback entry recorded so far — for human aggregation/reporting. */
+function readProductFeedback(devmindPath) {
+    return readJsonl(productFeedbackPath(devmindPath));
+}
+/**
+ * Marks graph-feedback entries as processed by id — rewrites the whole file (atomic temp+rename,
+ * same convention as `staging.ts`'s `writeBuffer`), since JSONL is append-only and a past line
+ * can't be edited in place. Idempotent: marking an already-processed or unknown id is a no-op for
+ * that id. Called by the batch graph-fix session once it has verified and applied (or explicitly
+ * rejected) an entry, so a later batch run never re-chews the same report.
+ */
+function markGraphFeedbackProcessed(devmindPath, ids) {
+    if (ids.length === 0)
+        return;
+    const target = graphFeedbackPath(devmindPath);
+    const all = readJsonl(target);
+    const idSet = new Set(ids);
+    const updated = all.map(e => (idSet.has(e.id) ? { ...e, processed: true } : e));
+    (0, activity_1.ensureGitignored)(devmindPath);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, updated.map(e => JSON.stringify(e)).join('\n') + (updated.length ? '\n' : ''), 'utf-8');
+    fs.renameSync(tmp, target);
+}
+/**
+ * Groups graph-feedback entries by `(node_id, category)` and sorts by frequency (most-reported
+ * first) — the clustering the batch session's `read_graph_feedback` tool exposes, so 30 identical
+ * reports of the same RTK miss show up as ONE cluster of size 30, not 30 things to individually
+ * re-investigate.
+ */
+function clusterGraphFeedback(entries) {
+    const groups = new Map();
+    for (const e of entries) {
+        const key = `${e.node_id ?? 'unknown'}::${e.category}`;
+        const arr = groups.get(key);
+        if (arr)
+            arr.push(e);
+        else
+            groups.set(key, [e]);
+    }
+    const clusters = [];
+    for (const [key, es] of groups) {
+        const sep = key.lastIndexOf('::');
+        clusters.push({
+            node_id: key.slice(0, sep),
+            category: key.slice(sep + 2),
+            count: es.length,
+            entries: es,
+            confidence: es.some(e => e.confidence === 'confirmed') ? 'confirmed' : 'suspected'
+        });
+    }
+    return clusters.sort((a, b) => b.count - a.count);
+}
+/** Appends one indexer-rule candidate — see {@link IndexerRuleCandidate}. */
+function appendIndexerRuleCandidate(devmindPath, entry) {
+    const record = {
+        ts: new Date().toISOString(),
+        pattern: entry.pattern,
+        evidence_count: entry.evidence_count,
+        examples: entry.examples
+    };
+    appendJsonl(devmindPath, indexerRuleCandidatesPath(devmindPath), record);
+}
+/** Reads every indexer-rule candidate recorded so far — for a human to review/prioritize. */
+function readIndexerRuleCandidates(devmindPath) {
+    return readJsonl(indexerRuleCandidatesPath(devmindPath));
+}
+//# sourceMappingURL=feedback.js.map

package/dist/db/feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.js","sourceRoot":"","sources":["../../src/db/feedback.ts"],"names":[],"mappings":"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"}

package/dist/db/file-diff.d.ts

@@ -0,0 +1,32 @@
+import { MessageEdit } from './activity';
+import { DiffLine } from '../utils/diff';
+export interface FileDiffResult {
+    file_path: string;
+    before_file: string;
+    after_file: string;
+    hunks: DiffLine[];
+    drifted: boolean;
+    drift_reason?: string;
+}
+/**
+ * Reconstructs the whole-file "before" state for one file's worth of edits from a single
+ * activity message, by undoing each edit's `after -> before` in memory, newest-first — the same
+ * ordering `revertOneMessageAtomically` (message-revert.ts) uses when it does this for real on
+ * disk. `fileEdits` must already be filtered to one file_path, in chronological (oldest-first)
+ * order, matching how they appear in `ActivityMessage.edits`.
+ *
+ * Drift (a hand-edit, a pull, a later message touching the same text) means some `after` snippet
+ * no longer matches the file uniquely — reported rather than guessed at, same as revert refuses
+ * rather than forcing a mismatched restore.
+ */
+export declare function reconstructBeforeFile(liveContent: string, fileEdits: MessageEdit[]): {
+    before: string;
+    drifted: boolean;
+};
+/**
+ * Collapses every edit a message made to ONE file into a single git-style whole-file diff,
+ * reading the live file off disk as the "after" state. On drift, the reconstruction is not
+ * trustworthy — the caller should fall back to the per-node `diffSnapshots(before, after)` for
+ * this file instead of rendering a wrong whole-file diff.
+ */
+export declare function fileDiffForMessage(filePath: string, fileEdits: MessageEdit[]): FileDiffResult;

package/dist/db/file-diff.js

@@ -0,0 +1,110 @@
+"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.reconstructBeforeFile = reconstructBeforeFile;
+exports.fileDiffForMessage = fileDiffForMessage;
+const fs = __importStar(require("fs"));
+const diff_1 = require("../utils/diff");
+/**
+ * Same single-occurrence exact-match semantics as replaceTextInFile (src/utils/edit.ts), but
+ * in-memory and read-only — no disk write, no atomic-rename. Returns null (rather than throwing)
+ * when `oldString` isn't found exactly once, so the caller can treat that as drift.
+ */
+function replaceOnce(content, oldString, newString) {
+    if (oldString === newString)
+        return content; // a no-op edit (before === after) has nothing to undo
+    if (oldString === '')
+        return null; // no anchor to locate — can't undo an insertion blind
+    let count = 0;
+    for (let i = content.indexOf(oldString); i !== -1; i = content.indexOf(oldString, i + oldString.length)) {
+        count++;
+        if (count > 1)
+            break;
+    }
+    if (count !== 1)
+        return null;
+    const i = content.indexOf(oldString);
+    return content.slice(0, i) + newString + content.slice(i + oldString.length);
+}
+/**
+ * Reconstructs the whole-file "before" state for one file's worth of edits from a single
+ * activity message, by undoing each edit's `after -> before` in memory, newest-first — the same
+ * ordering `revertOneMessageAtomically` (message-revert.ts) uses when it does this for real on
+ * disk. `fileEdits` must already be filtered to one file_path, in chronological (oldest-first)
+ * order, matching how they appear in `ActivityMessage.edits`.
+ *
+ * Drift (a hand-edit, a pull, a later message touching the same text) means some `after` snippet
+ * no longer matches the file uniquely — reported rather than guessed at, same as revert refuses
+ * rather than forcing a mismatched restore.
+ */
+function reconstructBeforeFile(liveContent, fileEdits) {
+    const newestFirst = fileEdits.slice().reverse();
+    let content = liveContent;
+    for (const edit of newestFirst) {
+        const undone = replaceOnce(content, edit.after, edit.before);
+        if (undone === null)
+            return { before: content, drifted: true };
+        content = undone;
+    }
+    return { before: content, drifted: false };
+}
+/**
+ * Collapses every edit a message made to ONE file into a single git-style whole-file diff,
+ * reading the live file off disk as the "after" state. On drift, the reconstruction is not
+ * trustworthy — the caller should fall back to the per-node `diffSnapshots(before, after)` for
+ * this file instead of rendering a wrong whole-file diff.
+ */
+function fileDiffForMessage(filePath, fileEdits) {
+    let live;
+    try {
+        live = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return { file_path: filePath, before_file: '', after_file: '', hunks: [], drifted: true, drift_reason: 'file no longer exists on disk' };
+    }
+    const { before, drifted } = reconstructBeforeFile(live, fileEdits);
+    if (drifted) {
+        return {
+            file_path: filePath,
+            before_file: before,
+            after_file: live,
+            hunks: [],
+            drifted: true,
+            drift_reason: 'file has changed since this message was recorded — showing per-change diffs instead'
+        };
+    }
+    return { file_path: filePath, before_file: before, after_file: live, hunks: (0, diff_1.diffSnapshots)(before, live, 8), drifted: false };
+}
+//# sourceMappingURL=file-diff.js.map

package/dist/db/file-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-diff.js","sourceRoot":"","sources":["../../src/db/file-diff.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,sDASC;AAQD,gDAqBC;AAhFD,uCAAyB;AAEzB,wCAAwD;AAWxD;;;;GAIG;AACH,SAAS,WAAW,CAAC,OAAe,EAAE,SAAiB,EAAE,SAAiB;IACxE,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,CAAC,sDAAsD;IACnG,IAAI,SAAS,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,CAAC,sDAAsD;IACzF,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QACxG,KAAK,EAAE,CAAC;QACR,IAAI,KAAK,GAAG,CAAC;YAAE,MAAM;IACvB,CAAC;IACD,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACrC,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,qBAAqB,CAAC,WAAmB,EAAE,SAAwB;IACjF,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC;IAChD,IAAI,OAAO,GAAG,WAAW,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7D,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC/D,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,QAAgB,EAAE,SAAwB;IAC3E,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,+BAA+B,EAAE,CAAC;IAC3I,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,qBAAqB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACnE,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO;YACL,SAAS,EAAE,QAAQ;YACnB,WAAW,EAAE,MAAM;YACnB,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,IAAI;YACb,YAAY,EAAE,qFAAqF;SACpG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,IAAA,oBAAa,EAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC/H,CAAC"}

package/dist/db/grep.d.ts

@@ -0,0 +1,78 @@
+/**
+ * True if a path is a lockfile or build artifact excluded from search by default. Exported so
+ * `searchNodes` can tell an agent that explicitly scoped `path` AT such a file WHY it got nothing
+ * back, rather than leaving it to read as "the pattern isn't in there".
+ */
+export declare function isDefaultIgnoredFile(filePath: string): boolean;
+export interface GrepHit {
+    file_path: string;
+    line_number: number;
+    line_content: string;
+    /** The actual substring the regex matched at this hit (lowercased) — used to attribute and
+     * rank matches without needing a fixed keyword list, since the pattern may be a single regex
+     * with no discrete "terms" of its own (e.g. `on\w+Tap`). */
+    matched_text: string;
+}
+export interface GrepResult {
+    hits: GrepHit[];
+    truncated: boolean;
+    files_scanned: number;
+}
+export interface RankedFile {
+    file_path: string;
+    total_matches: number;
+    /** Per-matched-text counts in this file — how the AI sees which part of the pattern actually landed. */
+    match_counts: Record<string, number>;
+    /** How many DISTINCT matched strings landed here — the strongest relevance signal. */
+    distinct_matches: number;
+    score: number;
+    /** A few representative matching lines (capped), for the AI to eyeball without opening the file.
+     * `symbol` — the containing function/class, when resolvable — is populated by the CALLER
+     * (`DevMindDatabase.annotateSampleLinesWithSymbol`), never by grep.ts itself: this module is
+     * deliberately dependency-free (no DB/AST access), see the file-level doc comment. */
+    sample_lines: {
+        line_number: number;
+        line_content: string;
+        symbol?: string;
+    }[];
+}
+/** `rankGrepHits`' result: a capped page of files plus the TRUE total, so the caller can tell
+ * "nothing more to find" from "more exists past this page" instead of guessing from a bare list. */
+export interface RankGrepHitsResult {
+    files: RankedFile[];
+    /** Total distinct files that matched, before the `maxFiles`/`offset` page was cut. */
+    total: number;
+}
+/** Escapes a literal string so it matches as text, not as a regex pattern. Exported so callers
+ * building a regex out of LITERAL terms (e.g. `searchNodes` deriving one from query tokens when
+ * no explicit `pattern` was given) can reuse the exact same escaping grep.ts uses internally. */
+export declare function escapeRegExp(s: string): string;
+/**
+ * Greps every configured repo root (or, when `opts.scopePath` is given, just that one folder or
+ * file) for `pattern` — a real regex, used as-is. Returns raw hits plus whether the deadline
+ * forced an early, partial stop. Ranking is a separate pure step (`rankGrepHits`).
+ *
+ * Invalid regex throws `Invalid regex pattern: <message>` immediately (same shape as the
+ * precedent already established by `DevMindDatabase.searchCode`) rather than surfacing as an
+ * opaque failure deeper in the walk.
+ */
+export declare function grepRepos(repoRoots: string[], pattern: string, opts?: {
+    ignoredPaths?: string[];
+    timeoutMs?: number;
+    caseInsensitive?: boolean;
+    scopePath?: string;
+}): Promise<GrepResult>;
+/**
+ * Ranks raw hits into a capped, ordered PAGE of files — the anti-firehose gate — plus the TRUE
+ * total file count before that cap, so a caller can tell "that's everything" from "more exists,
+ * ask for the next page" instead of guessing from a bare capped list. Unranked hits across 8
+ * repos can be hundreds; dumping them recreates the exact "15-20 low-confidence results I have to
+ * eyeball-filter" complaint that made the AI distrust the tool. So: group by file, score by match
+ * count weighted toward RARER matched strings (IDF-shaped, same instinct as BM25), reward files
+ * matching MULTIPLE distinct strings, sort with a stable tiebreaker, and page.
+ */
+export declare function rankGrepHits(hits: GrepHit[], opts?: {
+    maxFiles?: number;
+    maxSampleLines?: number;
+    offset?: number;
+}): RankGrepHitsResult;