@jcode.labs/ragmir 2.0.0

package/dist/query.d.ts

@@ -0,0 +1,5 @@
+import type { AskResult, SearchOptions, SearchResult } from "./types.js";
+export declare function search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+export declare function vectorCandidateLimit(topK: number): number;
+export declare function ask(query: string, options?: SearchOptions): Promise<AskResult>;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AA0BxE,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA8BhG;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAsB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,CAsBxF"}

package/dist/query.js

@@ -0,0 +1,180 @@
+import { recordAccess } from "./access-log.js";
+import { loadConfig } from "./config.js";
+import { embedText } from "./embeddings.js";
+import { openRowsTable } from "./store.js";
+import { normalizeForMatch, tokenize } from "./text.js";
+const MIN_VECTOR_CANDIDATES = 80;
+const VECTOR_CANDIDATE_MULTIPLIER = 4;
+const HYBRID_TEXT_SCAN_LIMIT = 5_000;
+const VECTOR_SCORE_WEIGHT = 0.55;
+const LEXICAL_SCORE_WEIGHT = 0.45;
+const EXACT_QUERY_BOOST = 0.15;
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+export async function search(query, options = {}) {
+    const config = await loadConfig(String(options.cwd ?? process.cwd()));
+    const table = await openRowsTable(config);
+    if (!table) {
+        return [];
+    }
+    const topK = options.topK ?? config.topK;
+    const vector = await embedText(query, config);
+    const vectorRows = (await table
+        .vectorSearch(vector)
+        .limit(vectorCandidateLimit(topK))
+        .toArray());
+    const textRows = (await table.query().limit(HYBRID_TEXT_SCAN_LIMIT).toArray());
+    const rows = rankHybridRows(query, vectorRows, textRows).slice(0, topK);
+    const results = rows.map((row) => ({
+        source: row.row.source,
+        relativePath: row.row.relativePath,
+        chunkIndex: row.row.chunkIndex,
+        text: row.row.text,
+        distance: typeof row.row._distance === "number" ? row.row._distance : null,
+    }));
+    await recordAccess(config, {
+        action: "search",
+        query,
+        topK,
+        resultCount: results.length,
+    });
+    return results;
+}
+export function vectorCandidateLimit(topK) {
+    return Math.max(MIN_VECTOR_CANDIDATES, topK * VECTOR_CANDIDATE_MULTIPLIER);
+}
+export async function ask(query, options = {}) {
+    const config = await loadConfig(String(options.cwd ?? process.cwd()));
+    const sources = await search(query, options);
+    if (sources.length === 0) {
+        return {
+            answer: "No relevant passages were found. Add documents and run `ragmir doctor --fix` first.",
+            sources,
+        };
+    }
+    await recordAccess(config, {
+        action: "ask",
+        query,
+        topK: options.topK ?? config.topK,
+        resultCount: sources.length,
+    });
+    return {
+        answer: retrievalOnlyAnswer(sources),
+        sources,
+    };
+}
+function retrievalOnlyAnswer(sources) {
+    const snippets = sources
+        .map((source, index) => {
+        const text = source.text.replace(/\s+/gu, " ").trim();
+        return `[${index + 1}] ${source.relativePath}#${source.chunkIndex}: ${text}`;
+    })
+        .join("\n\n");
+    return [
+        "Ragmir returns retrieval context only. Use these passages as grounded context for your agent or LLM:",
+        "",
+        snippets,
+    ].join("\n");
+}
+function rankHybridRows(query, vectorRows, textRows) {
+    const queryTokens = tokenize(query);
+    const rows = mergeRows(vectorRows, textRows);
+    const vectorScores = new Map();
+    for (const row of vectorRows) {
+        vectorScores.set(rowKey(row), vectorScore(row));
+    }
+    const lexicalScores = bm25Scores(queryTokens, rows);
+    const maxVectorScore = Math.max(...vectorScores.values(), 0);
+    const maxLexicalScore = Math.max(...lexicalScores.values(), 0);
+    const normalizedQuery = normalizeForMatch(query);
+    return rows
+        .map((row) => {
+        const key = rowKey(row);
+        const vector = normalizeScore(vectorScores.get(key) ?? 0, maxVectorScore);
+        const lexical = normalizeScore(lexicalScores.get(key) ?? 0, maxLexicalScore);
+        const exactBoost = normalizedQuery.length > 0 && normalizeForMatch(row.text).includes(normalizedQuery)
+            ? EXACT_QUERY_BOOST
+            : 0;
+        return {
+            row,
+            vectorScore: vector,
+            lexicalScore: lexical,
+            combinedScore: vector * VECTOR_SCORE_WEIGHT + lexical * LEXICAL_SCORE_WEIGHT + exactBoost,
+        };
+    })
+        .filter((ranked) => ranked.combinedScore > 0)
+        .sort((a, b) => {
+        const scoreDelta = b.combinedScore - a.combinedScore;
+        if (scoreDelta !== 0) {
+            return scoreDelta;
+        }
+        const distanceDelta = rowDistance(a.row) - rowDistance(b.row);
+        if (Number.isFinite(distanceDelta) && distanceDelta !== 0) {
+            return distanceDelta;
+        }
+        return (a.row.relativePath.localeCompare(b.row.relativePath) || a.row.chunkIndex - b.row.chunkIndex);
+    });
+}
+function mergeRows(vectorRows, textRows) {
+    const rows = new Map();
+    for (const row of textRows) {
+        rows.set(rowKey(row), row);
+    }
+    for (const row of vectorRows) {
+        rows.set(rowKey(row), row);
+    }
+    return [...rows.values()];
+}
+function bm25Scores(queryTokens, rows) {
+    const scores = new Map();
+    if (queryTokens.length === 0 || rows.length === 0) {
+        return scores;
+    }
+    const uniqueQueryTokens = [...new Set(queryTokens)];
+    const documents = rows.map((row) => {
+        const tokens = tokenize(row.text);
+        const frequencies = new Map();
+        for (const token of tokens) {
+            frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+        }
+        return { row, tokens, frequencies };
+    });
+    const averageLength = documents.reduce((sum, document) => sum + document.tokens.length, 0) / documents.length || 1;
+    const documentFrequencies = new Map();
+    for (const token of uniqueQueryTokens) {
+        documentFrequencies.set(token, documents.filter((document) => document.frequencies.has(token)).length);
+    }
+    for (const document of documents) {
+        let score = 0;
+        for (const token of uniqueQueryTokens) {
+            const frequency = document.frequencies.get(token) ?? 0;
+            if (frequency === 0) {
+                continue;
+            }
+            const documentFrequency = documentFrequencies.get(token) ?? 0;
+            const inverseDocumentFrequency = Math.log(1 + (documents.length - documentFrequency + 0.5) / (documentFrequency + 0.5));
+            const denominator = frequency + BM25_K1 * (1 - BM25_B + BM25_B * (document.tokens.length / averageLength));
+            score += inverseDocumentFrequency * ((frequency * (BM25_K1 + 1)) / denominator);
+        }
+        if (score > 0) {
+            scores.set(rowKey(document.row), score);
+        }
+    }
+    return scores;
+}
+function vectorScore(row) {
+    const distance = rowDistance(row);
+    return 1 / (1 + distance);
+}
+function rowDistance(row) {
+    return typeof row._distance === "number" && row._distance >= 0
+        ? row._distance
+        : Number.POSITIVE_INFINITY;
+}
+function normalizeScore(score, maxScore) {
+    return maxScore > 0 ? score / maxScore : 0;
+}
+function rowKey(row) {
+    return `${row.relativePath}\0${row.chunkIndex}`;
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

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

package/dist/redaction.d.ts

@@ -0,0 +1,7 @@
+import type { Config, RedactionCount } from "./types.js";
+export declare function redactText(input: string, config: Config): {
+    text: string;
+    counts: RedactionCount[];
+};
+export declare function totalRedactions(counts: RedactionCount[]): number;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAA;AAkE1E,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,EAAE,CAAA;CAAE,CAyB5C;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,CAEhE"}

package/dist/redaction.js

@@ -0,0 +1,93 @@
+const BUILT_IN_PATTERNS = [
+    {
+        name: "private_key",
+        pattern: "-----BEGIN [A-Z ]*PRIVATE KEY-----[\\s\\S]*?-----END [A-Z ]*PRIVATE KEY-----",
+        flags: "g",
+    },
+    {
+        name: "jwt",
+        pattern: "\\beyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\b",
+        flags: "g",
+    },
+    {
+        name: "api_token",
+        pattern: "\\b(?:sk|pk|ghp|gho|github_pat|npm)_[A-Za-z0-9_=-]{20,}\\b|\\b[A-Za-z0-9_-]{32,}\\.[A-Za-z0-9_-]{16,}\\.[A-Za-z0-9_-]{16,}\\b",
+        flags: "g",
+    },
+    {
+        name: "openai_api_key",
+        pattern: "\\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\\b",
+        flags: "g",
+    },
+    {
+        name: "aws_access_key_id",
+        pattern: "\\b(?:AKIA|ASIA)[0-9A-Z]{16}\\b",
+        flags: "g",
+    },
+    {
+        name: "google_api_key",
+        pattern: "\\bAIza[0-9A-Za-z_-]{35}\\b",
+        flags: "g",
+    },
+    {
+        name: "slack_token",
+        pattern: "\\bxox[baprs]-[0-9A-Za-z-]{10,}\\b",
+        flags: "g",
+    },
+    {
+        name: "sendgrid_api_key",
+        pattern: "\\bSG\\.[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}\\b",
+        flags: "g",
+    },
+    {
+        name: "url_credentials",
+        pattern: "\\b[a-z][a-z0-9+.-]*://[^\\s:/@]+:[^\\s/@]+@",
+        flags: "gi",
+    },
+    {
+        name: "email",
+        pattern: "\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}\\b",
+        flags: "gi",
+    },
+    {
+        name: "iban",
+        pattern: "\\b[A-Z]{2}\\d{2}[A-Z0-9]{11,30}\\b",
+        flags: "gi",
+    },
+    {
+        name: "credit_card",
+        pattern: "\\b(?:\\d[ -]*?){13,19}\\b",
+        flags: "g",
+    },
+];
+export function redactText(input, config) {
+    if (!config.redaction.enabled) {
+        return { text: input, counts: [] };
+    }
+    let text = input;
+    const counts = [];
+    const patterns = [
+        ...(config.redaction.builtIn ? BUILT_IN_PATTERNS : []),
+        ...config.redaction.patterns,
+    ];
+    for (const pattern of patterns) {
+        const regexp = compilePattern(pattern);
+        let count = 0;
+        text = text.replace(regexp, () => {
+            count += 1;
+            return pattern.replacement ?? `[REDACTED_${pattern.name.toUpperCase()}]`;
+        });
+        if (count > 0) {
+            counts.push({ name: pattern.name, count });
+        }
+    }
+    return { text, counts };
+}
+export function totalRedactions(counts) {
+    return counts.reduce((total, entry) => total + entry.count, 0);
+}
+function compilePattern(pattern) {
+    const flags = pattern.flags?.includes("g") ? pattern.flags : `${pattern.flags ?? ""}g`;
+    return new RegExp(pattern.pattern, flags);
+}
+//# sourceMappingURL=redaction.js.map

package/dist/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAEA,MAAM,iBAAiB,GAAuB;IAC5C;QACE,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,8EAA8E;QACvF,KAAK,EAAE,GAAG;KACX;IACD;QACE,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,2DAA2D;QACpE,KAAK,EAAE,GAAG;KACX;IACD;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EACL,+HAA+H;QACjI,KAAK,EAAE,GAAG;KACX;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,uCAAuC;QAChD,KAAK,EAAE,GAAG;KACX;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,iCAAiC;QAC1C,KAAK,EAAE,GAAG;KACX;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,6BAA6B;QACtC,KAAK,EAAE,GAAG;KACX;IACD;QACE,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,oCAAoC;QAC7C,KAAK,EAAE,GAAG;KACX;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,kDAAkD;QAC3D,KAAK,EAAE,GAAG;KACX;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,8CAA8C;QACvD,KAAK,EAAE,IAAI;KACZ;IACD;QACE,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,8CAA8C;QACvD,KAAK,EAAE,IAAI;KACZ;IACD;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,qCAAqC;QAC9C,KAAK,EAAE,IAAI;KACZ;IACD;QACE,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,4BAA4B;QACrC,KAAK,EAAE,GAAG;KACX;CACF,CAAA;AAED,MAAM,UAAU,UAAU,CACxB,KAAa,EACb,MAAc;IAEd,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;IACpC,CAAC;IAED,IAAI,IAAI,GAAG,KAAK,CAAA;IAChB,MAAM,MAAM,GAAqB,EAAE,CAAA;IACnC,MAAM,QAAQ,GAAG;QACf,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ;KAC7B,CAAA;IAED,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;QACtC,IAAI,KAAK,GAAG,CAAC,CAAA;QACb,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE;YAC/B,KAAK,IAAI,CAAC,CAAA;YACV,OAAO,OAAO,CAAC,WAAW,IAAI,aAAa,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAA;QAC1E,CAAC,CAAC,CAAA;QACF,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;QAC5C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;AACzB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAwB;IACtD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;AAChE,CAAC;AAED,SAAS,cAAc,CAAC,OAAyB;IAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,GAAG,CAAA;IACtF,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;AAC3C,CAAC"}

package/dist/research.d.ts

@@ -0,0 +1,9 @@
+import type { CompactSearchResult, ResearchEvidence, ResearchOptions, ResearchReport, SearchResult } from "./types.js";
+export declare function research(query: string, options?: ResearchOptions): Promise<ResearchReport>;
+export declare function compactSearchResults(results: SearchResult[], maxLength?: number): CompactSearchResult[];
+export declare function compactResearchReport(report: ResearchReport): Omit<ResearchReport, "evidence"> & {
+    evidence: Array<Omit<ResearchEvidence, "text"> & {
+        snippet: string;
+    }>;
+};
+//# sourceMappingURL=research.d.ts.map

package/dist/research.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research.d.ts","sourceRoot":"","sources":["../src/research.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAEV,mBAAmB,EAEnB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,YAAY,EACb,MAAM,YAAY,CAAA;AAwDnB,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAsEzB;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,YAAY,EAAE,EACvB,SAAS,SAAyB,GACjC,mBAAmB,EAAE,CAQvB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,GAAG;IAChG,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACtE,CAYA"}

package/dist/research.js

@@ -0,0 +1,335 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import fg from "fast-glob";
+import { recordAccess } from "./access-log.js";
+import { loadConfig } from "./config.js";
+import { countSkippedByReason, DEFAULT_FAST_GLOB_IGNORES, isSensitiveFilePath } from "./files.js";
+import { audit } from "./ingest.js";
+import { search } from "./query.js";
+import { redactText } from "./redaction.js";
+import { securityAudit } from "./security.js";
+import { normalizeForMatch } from "./text.js";
+const DEFAULT_RESEARCH_QUERY_LIMIT = 5;
+const DEFAULT_CODE_EVIDENCE_LIMIT = 20;
+const CODE_EVIDENCE_CANDIDATE_MULTIPLIER = 5;
+const COMPACT_SNIPPET_LENGTH = 260;
+const CODE_SCAN_MAX_BYTES = 256_000;
+const CODE_SCAN_EXTENSIONS = new Set([
+    ".c",
+    ".cjs",
+    ".cpp",
+    ".cs",
+    ".go",
+    ".java",
+    ".js",
+    ".json",
+    ".jsonl",
+    ".jsx",
+    ".kt",
+    ".md",
+    ".mdx",
+    ".mjs",
+    ".mts",
+    ".php",
+    ".py",
+    ".rb",
+    ".rs",
+    ".sql",
+    ".txt",
+    ".ts",
+    ".tsx",
+    ".vue",
+    ".yaml",
+    ".yml",
+]);
+const CODE_SCAN_IGNORE = [
+    ...DEFAULT_FAST_GLOB_IGNORES,
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/coverage/**",
+    "**/release-artifacts/**",
+    "**/bun.lock",
+    "**/bun.lockb",
+    "**/Cargo.lock",
+    "**/composer.lock",
+    "**/Gemfile.lock",
+    "**/go.sum",
+    "**/npm-shrinkwrap.json",
+    "**/package-lock.json",
+    "**/Pipfile.lock",
+    "**/pnpm-lock.yaml",
+    "**/poetry.lock",
+    "**/yarn.lock",
+];
+export async function research(query, options = {}) {
+    const normalizedQuery = query.trim();
+    if (!normalizedQuery) {
+        throw new Error("Research query must not be empty.");
+    }
+    const config = await loadConfig(String(options.cwd ?? process.cwd()));
+    const topK = options.topK ?? config.topK;
+    const [auditReport, securityReport] = await Promise.all([
+        audit(config.projectRoot),
+        securityAudit(config.projectRoot),
+    ]);
+    const generatedQueries = researchQueries(normalizedQuery);
+    const perQueryTopK = Math.max(2, Math.ceil(topK / 2));
+    const searchResults = await Promise.all(generatedQueries.map(async (generatedQuery) => ({
+        query: generatedQuery,
+        results: await search(generatedQuery, { cwd: config.projectRoot, topK: perQueryTopK }),
+    })));
+    const evidence = mergeEvidence(searchResults).slice(0, topK);
+    const codeEvidence = options.includeCode === false
+        ? []
+        : await findCodeEvidence(config, normalizedQuery, DEFAULT_CODE_EVIDENCE_LIMIT);
+    const unsupportedFiles = countSkippedByReason(auditReport.skippedFiles, "unsupported-extension");
+    const gaps = researchGaps({
+        evidenceCount: evidence.length,
+        codeEvidenceCount: codeEvidence.length,
+        includeCode: options.includeCode !== false,
+        missingFromIndex: auditReport.missingFromIndex.length,
+        staleInIndex: auditReport.staleInIndex.length,
+        securityWarnings: securityReport.warnings.length,
+        unsupportedFiles,
+        duplicateCandidates: auditReport.sourceDiagnostics.duplicateCandidates.length,
+        archiveCandidates: auditReport.sourceDiagnostics.archiveCandidates.length,
+        mirrorCandidates: auditReport.sourceDiagnostics.mirrorCandidates.length,
+    });
+    await recordAccess(config, {
+        action: "research",
+        query: normalizedQuery,
+        topK,
+        resultCount: evidence.length,
+    });
+    return {
+        query: normalizedQuery,
+        generatedQueries,
+        ready: evidence.length > 0 &&
+            auditReport.missingFromIndex.length === 0 &&
+            auditReport.staleInIndex.length === 0 &&
+            securityReport.warnings.length === 0,
+        audit: {
+            supportedFiles: auditReport.supportedFiles.length,
+            skippedFiles: auditReport.skippedFiles.length,
+            unsupportedFiles,
+            indexedFiles: auditReport.indexedFiles.length,
+            totalChunks: auditReport.totalChunks,
+            missingFromIndex: auditReport.missingFromIndex.length,
+            staleInIndex: auditReport.staleInIndex.length,
+            emptyTextFiles: auditReport.emptyTextFiles.length,
+        },
+        securityWarnings: securityReport.warnings,
+        sourceDiagnostics: auditReport.sourceDiagnostics,
+        evidence,
+        codeEvidence,
+        gaps,
+        nextSteps: researchNextSteps(gaps),
+    };
+}
+export function compactSearchResults(results, maxLength = COMPACT_SNIPPET_LENGTH) {
+    return results.map((result) => ({
+        source: result.source,
+        relativePath: result.relativePath,
+        chunkIndex: result.chunkIndex,
+        snippet: compactText(result.text, maxLength),
+        distance: result.distance,
+    }));
+}
+export function compactResearchReport(report) {
+    return {
+        ...report,
+        evidence: report.evidence.map((evidence) => ({
+            source: evidence.source,
+            relativePath: evidence.relativePath,
+            chunkIndex: evidence.chunkIndex,
+            snippet: compactText(evidence.text),
+            distance: evidence.distance,
+            queries: evidence.queries,
+        })),
+    };
+}
+function researchQueries(query) {
+    const trimmed = query.trim();
+    const queries = [
+        trimmed,
+        `${trimmed} scope requirements rules`,
+        `${trimmed} actors permissions workflow status validation`,
+        `${trimmed} dates deadlines planning risks blockers`,
+        `${trimmed} integration API data model export dependencies`,
+    ];
+    return [...new Set(queries)].slice(0, DEFAULT_RESEARCH_QUERY_LIMIT);
+}
+function mergeEvidence(searchResults) {
+    const bySource = new Map();
+    for (const searchResult of searchResults) {
+        for (const result of searchResult.results) {
+            const key = `${result.relativePath}\0${result.chunkIndex}`;
+            const existing = bySource.get(key);
+            if (existing) {
+                existing.queries.push(searchResult.query);
+                continue;
+            }
+            bySource.set(key, {
+                source: result.source,
+                relativePath: result.relativePath,
+                chunkIndex: result.chunkIndex,
+                text: result.text,
+                distance: result.distance,
+                queries: [searchResult.query],
+            });
+        }
+    }
+    return [...bySource.values()];
+}
+async function findCodeEvidence(config, query, limit) {
+    const terms = meaningfulTerms(query);
+    if (terms.length === 0) {
+        return [];
+    }
+    const ignore = [...CODE_SCAN_IGNORE, ...projectRelativeIgnores(config)];
+    const minimumMatchedTerms = terms.length === 1 ? 1 : 2;
+    const candidateLimit = Math.max(limit, limit * CODE_EVIDENCE_CANDIDATE_MULTIPLIER);
+    const entries = (await fg("**/*", {
+        cwd: config.projectRoot,
+        absolute: true,
+        onlyFiles: true,
+        dot: true,
+        followSymbolicLinks: false,
+        ignore,
+        objectMode: true,
+        stats: true,
+        unique: true,
+    }));
+    const candidates = [];
+    for (const entry of entries) {
+        if (candidates.length >= candidateLimit) {
+            break;
+        }
+        const absolutePath = path.isAbsolute(entry.path)
+            ? entry.path
+            : path.resolve(config.projectRoot, entry.path);
+        if (!isScannableCodePath(absolutePath) ||
+            isSensitiveFilePath(absolutePath) ||
+            (entry.stats?.size ?? 0) > CODE_SCAN_MAX_BYTES) {
+            continue;
+        }
+        const relativePath = path.relative(config.projectRoot, absolutePath);
+        const content = await readFile(absolutePath, "utf8").catch(() => null);
+        if (content === null) {
+            continue;
+        }
+        for (const [index, line] of content.split(/\r?\n/u).entries()) {
+            const normalizedLine = normalizeForMatch(line);
+            const matchedTerms = terms.filter((term) => normalizedLine.includes(term));
+            if (matchedTerms.length < minimumMatchedTerms) {
+                continue;
+            }
+            const redactedSnippet = redactText(line.trim(), config).text;
+            candidates.push({
+                relativePath,
+                lineNumber: index + 1,
+                snippet: redactedSnippet.slice(0, COMPACT_SNIPPET_LENGTH),
+                matchedTerms,
+            });
+            break;
+        }
+    }
+    return candidates.sort(compareCodeEvidence).slice(0, limit);
+}
+function compareCodeEvidence(a, b) {
+    return (b.matchedTerms.length - a.matchedTerms.length ||
+        a.relativePath.localeCompare(b.relativePath) ||
+        a.lineNumber - b.lineNumber);
+}
+function projectRelativeIgnores(config) {
+    return [config.rawDir, config.storageDir, config.embeddingModelPath]
+        .map((absolutePath) => path.relative(config.projectRoot, absolutePath))
+        .filter((relativePath) => relativePath && !relativePath.startsWith(".."))
+        .map((relativePath) => `${relativePath}/**`);
+}
+function isScannableCodePath(absolutePath) {
+    const extension = path.extname(absolutePath).toLowerCase();
+    return CODE_SCAN_EXTENSIONS.has(extension);
+}
+function meaningfulTerms(query) {
+    return [
+        ...new Set(normalizeForMatch(query)
+            .match(/[\p{L}\p{N}]{3,}/gu)
+            ?.filter((term) => !STOP_WORDS.has(term)) ?? []),
+    ].slice(0, 8);
+}
+function researchGaps(input) {
+    const gaps = [];
+    if (input.evidenceCount === 0) {
+        gaps.push("No retrieved evidence matched the research query.");
+    }
+    if (input.includeCode && input.codeEvidenceCount === 0) {
+        gaps.push("No code evidence matched the research query.");
+    }
+    if (input.missingFromIndex > 0) {
+        gaps.push(`${input.missingFromIndex} supported source files are missing from the index.`);
+    }
+    if (input.staleInIndex > 0) {
+        gaps.push(`${input.staleInIndex} indexed source files are stale.`);
+    }
+    if (input.securityWarnings > 0) {
+        gaps.push(`${input.securityWarnings} security warnings require review.`);
+    }
+    if (input.unsupportedFiles > 0) {
+        gaps.push(`${input.unsupportedFiles} source files were skipped because their type is unsupported.`);
+    }
+    if (input.duplicateCandidates > 0) {
+        gaps.push(`${input.duplicateCandidates} possible duplicate source groups need source-truth review.`);
+    }
+    if (input.archiveCandidates > 0 || input.mirrorCandidates > 0) {
+        gaps.push("Some source paths look like archives, exports, raw files, or drive mirrors.");
+    }
+    return gaps;
+}
+function researchNextSteps(gaps) {
+    if (gaps.length === 0) {
+        return [
+            "Use the cited evidence as grounded context for an AI agent or reviewer.",
+            "Run targeted searches for names, dates, amounts, and decisions before high-stakes conclusions.",
+        ];
+    }
+    return gaps.map((gap) => {
+        if (gap.includes("missing") || gap.includes("stale")) {
+            return "Run `ragmir doctor --fix`, then rerun `ragmir research`.";
+        }
+        if (gap.includes("unsupported")) {
+            return "Run `ragmir audit --unsupported` and transcribe, OCR, convert, or explicitly configure unsupported formats.";
+        }
+        if (gap.includes("duplicate") || gap.includes("archive") || gap.includes("mirror")) {
+            return "Review source diagnostics and prefer the canonical source before presenting conclusions.";
+        }
+        if (gap.includes("code evidence")) {
+            return "Run repository-aware code search to compare documents with implementation.";
+        }
+        return "Add or refresh source documents, then rerun the research command.";
+    });
+}
+function compactText(text, maxLength = COMPACT_SNIPPET_LENGTH) {
+    const normalized = text.replace(/\s+/gu, " ").trim();
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+const STOP_WORDS = new Set([
+    "about",
+    "avec",
+    "dans",
+    "des",
+    "for",
+    "les",
+    "pour",
+    "que",
+    "qui",
+    "sur",
+    "the",
+    "une",
+    "what",
+]);
+//# sourceMappingURL=research.js.map