contextpro-mcp 0.0.0-stage → 1.4.0

package/build/tools/resolve-symbol.d.ts

@@ -0,0 +1,41 @@
+import { type FreshnessMetadata, type TrustMetadata } from "../core/context-metadata.js";
+export interface ResolveSymbolOptions {
+    rootDir: string;
+    symbolName: string;
+    fileContext?: string;
+    kind?: string;
+    limit?: number;
+    format?: "text" | "json";
+}
+export interface ResolvedSymbolCandidate {
+    name: string;
+    kind: string;
+    path: string;
+    line: number;
+    endLine: number | null;
+    signature: string | null;
+    parentName: string | null;
+    score: number;
+    reasons: string[];
+}
+export interface ResolveSymbolData {
+    repo: {
+        root: string;
+        fileContext: string | null;
+        projectId: string | null;
+        clientId: string | null;
+        fingerprint: string | null;
+    };
+    query: {
+        symbolName: string;
+        kind: string | null;
+    };
+    freshness: FreshnessMetadata;
+    trust: TrustMetadata;
+    bestMatch: ResolvedSymbolCandidate | null;
+    ambiguous: boolean;
+    candidates: ResolvedSymbolCandidate[];
+}
+export declare function resolveSymbolData(options: ResolveSymbolOptions): Promise<ResolveSymbolData>;
+export declare function resolveSymbol(options: ResolveSymbolOptions): Promise<string>;
+//# sourceMappingURL=resolve-symbol.d.ts.map

package/build/tools/resolve-symbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-symbol.d.ts","sourceRoot":"","sources":["../../src/tools/resolve-symbol.ts"],"names":[],"mappings":"AAOA,OAAO,EAA6D,KAAK,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEpJ,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC;IACF,KAAK,EAAE;QACL,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;KACrB,CAAC;IACF,SAAS,EAAE,iBAAiB,CAAC;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,uBAAuB,EAAE,CAAC;CACvC;AA0GD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgIjG;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlF"}

package/build/tools/resolve-symbol.js

@@ -0,0 +1,250 @@
+// Symbol resolution with ambiguity scoring and file-context-aware ranking
+// FEATURE: ResolveSymbol — precise definition lookup for ambiguous identifiers
+import { dirname, resolve } from "path";
+import { getDB } from "../core/db.js";
+import { loadProjectConfig } from "../core/project-config.js";
+import { persistArtifact } from "../core/artifacts.js";
+import { buildFreshnessMetadata, buildTrustMetadata, getIndexState } from "../core/context-metadata.js";
+function nameSegments(name) {
+    // Split camelCase and snake_case into lowercase word segments.
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+}
+function isLikelyTestPath(path) {
+    return /(^|\/)(tests?|__tests__|spec)\//.test(path)
+        || /\.(test|spec|demo)\./.test(path)
+        || /(^|\/)test_[^/]+\.py$/.test(path)
+        || /_test\.go$/.test(path);
+}
+function scoreSymbolCandidate(input) {
+    let score = 0;
+    const reasons = [];
+    const exactMatch = input.symbol.name === input.symbolName;
+    const normalizedQuery = input.symbolName.toLowerCase();
+    const normalizedName = input.symbol.name.toLowerCase();
+    const querySegments = nameSegments(input.symbolName);
+    const nameSegs = nameSegments(input.symbol.name);
+    if (exactMatch) {
+        score += 100;
+        reasons.push("exact name match");
+    }
+    else if (normalizedName === normalizedQuery) {
+        score += 90;
+        reasons.push("case-insensitive exact name match");
+    }
+    else if (querySegments.length > 0 && querySegments.every((seg) => nameSegs.includes(seg))) {
+        // All query word-segments are present as whole words in the symbol name.
+        // e.g. "fee model" matches "FeeModel"; "run" matches "run_scanner" but NOT "drunk".
+        score += 55;
+        reasons.push("word-boundary segment match");
+    }
+    else if (nameSegs.includes(normalizedQuery)) {
+        // The whole query is one of the symbol's word segments. This is what kills the
+        // fee-in-feed substring collision: "fee" is NOT a segment of "run_venue_a_feed".
+        score += 50;
+        reasons.push("matches a whole word segment");
+    }
+    else if (normalizedName.includes(normalizedQuery)) {
+        // Pure substring — lowest tier, and only counts when the query is reasonably long
+        // so 2-3 char queries don't spray across unrelated names.
+        score += normalizedQuery.length >= 4 ? 20 : 8;
+        reasons.push("partial (substring) name match");
+    }
+    if (input.expectedKind && input.symbol.kind === input.expectedKind) {
+        score += 35;
+        reasons.push(`kind match (${input.expectedKind})`);
+    }
+    else if (input.expectedKind && input.symbol.kind !== input.expectedKind) {
+        score -= 15;
+        reasons.push(`kind mismatch (${input.symbol.kind})`);
+    }
+    if (input.fileContext && input.file.path === input.fileContext) {
+        score += 40;
+        reasons.push("same file as file_context");
+    }
+    if (input.importedFileIds.has(input.file.id)) {
+        score += 30;
+        reasons.push("definition is in a directly imported file");
+    }
+    if (input.fileContext && dirname(input.file.path) === dirname(input.fileContext)) {
+        score += 10;
+        reasons.push("same directory as file_context");
+    }
+    if (input.symbol.parent_symbol_id !== null) {
+        score += 5;
+        reasons.push("nested/member definition");
+    }
+    // Tie-breakers when file_context is absent: prefer non-test, well-imported definitions.
+    if (isLikelyTestPath(input.file.path)) {
+        score -= 6;
+        reasons.push("in a test file (de-prioritized)");
+    }
+    if (input.importerCount > 0) {
+        const bump = Math.min(8, input.importerCount);
+        score += bump;
+        reasons.push(`${input.importerCount} importer(s)`);
+    }
+    return { score, reasons };
+}
+function resolveParentName(symbol, siblings) {
+    if (symbol.parent_symbol_id === null)
+        return null;
+    return siblings.find((candidate) => candidate.id === symbol.parent_symbol_id)?.name ?? null;
+}
+export async function resolveSymbolData(options) {
+    const [db, config, indexState] = await Promise.all([
+        getDB(options.rootDir),
+        loadProjectConfig(options.rootDir),
+        getIndexState(options.rootDir),
+    ]);
+    const allFiles = db.getAllFiles();
+    const filesById = new Map(allFiles.map((file) => [file.id, file]));
+    const currentFile = options.fileContext ? db.getFile(options.fileContext) : null;
+    const importedFileIds = new Set();
+    if (currentFile) {
+        for (const imp of db.getImportsFrom(currentFile.id)) {
+            if (imp.target_file_id !== null)
+                importedFileIds.add(imp.target_file_id);
+        }
+    }
+    const rawMatches = db.searchSymbolsByName(options.symbolName);
+    const exactMatches = rawMatches.filter((symbol) => symbol.name === options.symbolName);
+    const candidateRows = exactMatches.length > 0 ? exactMatches : rawMatches;
+    const ranked = candidateRows
+        .map((symbol) => {
+        const file = filesById.get(symbol.file_id);
+        if (!file)
+            return null;
+        const siblings = db.getSymbolsByFile(file.id);
+        const importerCount = db.getImportersOf(file.id).length;
+        const { score, reasons } = scoreSymbolCandidate({
+            symbolName: options.symbolName,
+            expectedKind: options.kind,
+            symbol,
+            file,
+            fileContext: options.fileContext,
+            importedFileIds,
+            importerCount,
+        });
+        const candidate = {
+            name: symbol.name,
+            kind: symbol.kind,
+            path: file.path,
+            line: symbol.line_start,
+            endLine: symbol.line_end,
+            signature: symbol.signature,
+            parentName: resolveParentName(symbol, siblings),
+            score,
+            reasons,
+        };
+        return candidate;
+    })
+        .filter((candidate) => candidate !== null)
+        .sort((left, right) => right.score - left.score || left.path.localeCompare(right.path) || left.line - right.line);
+    const limited = ranked.slice(0, options.limit ?? 8);
+    const bestMatch = limited[0] ?? null;
+    const ambiguous = limited.length > 1 && bestMatch !== null && (bestMatch.score - limited[1].score) < 20;
+    const freshness = buildFreshnessMetadata(indexState, {
+        staleCount: 0,
+        refreshed: false,
+        warning: indexState.state === "empty"
+            ? "Index is empty. Run reindex before resolving symbols."
+            : indexState.state === "indexing"
+                ? "Indexing is still in progress. Wait for completion before trusting symbol resolution."
+                : indexState.state === "stale"
+                    ? "Index is stale relative to the workspace. Run reindex before trusting symbol resolution."
+                    : null,
+    });
+    const evidence = [
+        ...(bestMatch ? [`best candidate ${bestMatch.path}:L${bestMatch.line}`] : []),
+        ...(currentFile ? [`file context ${currentFile.path}`] : []),
+        ...(importedFileIds.size > 0 ? [`${importedFileIds.size} directly imported files considered`] : []),
+    ];
+    const ambiguities = [
+        ...(limited.length === 0 ? ["no symbol candidates found"] : []),
+        ...(ambiguous ? ["top symbol candidates are close in score"] : []),
+    ];
+    const partial = {
+        repo: {
+            root: resolve(options.rootDir),
+            fileContext: options.fileContext ?? null,
+            projectId: config?.projectId ?? null,
+            clientId: config?.clientId ?? null,
+            fingerprint: config?.repoFingerprint ?? null,
+        },
+        query: {
+            symbolName: options.symbolName,
+            kind: options.kind ?? null,
+        },
+        freshness,
+        trust: buildTrustMetadata({
+            baseConfidence: bestMatch ? (ambiguous ? 0.62 : 0.84) : 0.24,
+            freshness,
+            evidence,
+            ambiguities,
+            artifact: null,
+        }),
+        bestMatch,
+        ambiguous,
+        candidates: limited,
+    };
+    const artifact = await persistArtifact({
+        rootDir: options.rootDir,
+        kind: "resolve_symbol",
+        key: JSON.stringify({
+            symbolName: options.symbolName,
+            fileContext: options.fileContext ?? null,
+            kind: options.kind ?? null,
+            limit: options.limit ?? 8,
+        }),
+        repoFingerprint: partial.repo.fingerprint,
+        projectId: partial.repo.projectId,
+        clientId: partial.repo.clientId,
+        metadata: {
+            symbolName: options.symbolName,
+            kind: options.kind ?? "",
+        },
+        payload: partial,
+    });
+    return {
+        ...partial,
+        trust: buildTrustMetadata({
+            baseConfidence: bestMatch ? (ambiguous ? 0.62 : 0.84) : 0.24,
+            freshness,
+            evidence,
+            ambiguities,
+            artifact,
+        }),
+    };
+}
+export async function resolveSymbol(options) {
+    const data = await resolveSymbolData(options);
+    if (options.format === "json") {
+        return JSON.stringify(data, null, 2);
+    }
+    if (data.candidates.length === 0) {
+        return `No symbol matches found for "${options.symbolName}".`;
+    }
+    const lines = [
+        `=== Resolve Symbol: ${options.symbolName} ===`,
+        `File Context: ${data.repo.fileContext ?? "none"}`,
+        `Ambiguous: ${data.ambiguous ? "yes" : "no"}`,
+        data.trust.artifact ? `Artifact: ${data.trust.artifact.id}` : "",
+        "",
+    ].filter(Boolean);
+    for (const candidate of data.candidates) {
+        lines.push(`${candidate.kind}: ${candidate.path} L${candidate.line}${candidate.endLine && candidate.endLine > candidate.line ? `-L${candidate.endLine}` : ""}`);
+        if (candidate.signature)
+            lines.push(`  ${candidate.signature}`);
+        if (candidate.parentName)
+            lines.push(`  parent: ${candidate.parentName}`);
+        lines.push(`  score: ${candidate.score} | ${candidate.reasons.join(", ")}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=resolve-symbol.js.map

package/build/tools/resolve-symbol.js.map

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

package/build/tools/retrieval-helpers.d.ts

@@ -0,0 +1,35 @@
+export declare function unique<T>(items: T[]): T[];
+export declare function parseMetadata(raw: string): Record<string, string>;
+export declare function parseJsonArray(raw: string | null): string[];
+export declare function isTestFile(path: string): boolean;
+export declare function isTestEvidence(path: string): boolean;
+export declare function findTestsForFiles(rootDir: string, files: string[]): Promise<Array<{
+    path: string;
+    reason: string;
+    score: number;
+}>>;
+export declare function getRecentDiffSummary(rootDir: string, filePath: string): Promise<{
+    path: string;
+    commit: string;
+    summary: string;
+} | null>;
+export declare function getProjectMemoryHits(rootDir: string, query: string, topK: number, keywordOnly?: boolean): Promise<Array<{
+    id: string;
+    kind: string;
+    summary: string;
+}>>;
+/** Bounded lexical risk lookup; never pay for embeddings on the context path. */
+export declare function getProjectRiskEvidence(rootDir: string, query: string): Promise<Array<{
+    id: string;
+    risks: string[];
+}>>;
+export declare function resolveFilesFromSymbols(rootDir: string, symbols: string[] | undefined): Promise<string[]>;
+export declare function findTextDependents(rootDir: string, filePath: string, symbolNames?: string[]): Promise<string[]>;
+export declare function scanExactMentions(rootDir: string, candidateFiles: string[], symbolNames: string[]): Promise<string[]>;
+export declare function fileRisk(rootDir: string, filePath: string): Promise<{
+    importers: number;
+    imports: number;
+    churn: number;
+}>;
+export declare function hubMatchesForFiles(rootDir: string, filePaths: string[]): Promise<string[]>;
+//# sourceMappingURL=retrieval-helpers.d.ts.map

package/build/tools/retrieval-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-helpers.d.ts","sourceRoot":"","sources":["../../src/tools/retrieval-helpers.ts"],"names":[],"mappings":"AAiBA,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAEzC;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQjE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,EAAE,CAQ3D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKhD;AAGD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AA4DD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAmBzI;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAa/I;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAwC3K;AAED,iFAAiF;AACjF,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC,CAsB5H;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa/G;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAwBzH;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAU3H;AAED,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAehI;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWhG"}

package/build/tools/retrieval-helpers.js

@@ -0,0 +1,302 @@
+// Shared retrieval utilities: test discovery, diff summaries, memory hits, import resolution
+// FEATURE: Helper layer for agentic-context — query-independent data fetching functions
+import { execFile } from "child_process";
+import { memoryEvidenceStatus } from "../core/evidence-state.js";
+import { promisify } from "util";
+import { readFile } from "fs/promises";
+import { basename } from "path";
+import { fetchQueryEmbedding, hasCompatibleEmbeddingModel } from "../core/embeddings.js";
+import { getDB } from "../core/db.js";
+import { loadProjectConfig } from "../core/project-config.js";
+import { discoverHubs, parseHubFile } from "../core/hub.js";
+import { walkDirectory } from "../core/walker.js";
+import { resolveProjectPath } from "../core/path-guard.js";
+const execFileAsync = promisify(execFile);
+export function unique(items) {
+    return Array.from(new Set(items));
+}
+export function parseMetadata(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return {};
+        return Object.fromEntries(Object.entries(parsed).map(([key, value]) => [key, String(value)]));
+    }
+    catch {
+        return {};
+    }
+}
+export function parseJsonArray(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.map((value) => String(value)) : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function isTestFile(path) {
+    const name = basename(path).toLowerCase();
+    return /\.(?:test|spec|demo|smoke)\.\w+$/.test(path)
+        || /^test_[^/]+\.py$/.test(name)
+        || /_test\.py$/.test(name);
+}
+// Helpers are test evidence, but test selection must traverse them to runnable tests.
+export function isTestEvidence(path) {
+    return isTestFile(path) || /(?:^|\/)(?:tests?|__tests__)\/.*\.(?:[cm]?[jt]sx?|py)$/i.test(path);
+}
+function baseNameWithoutTestAffixes(path) {
+    const base = path.replace(/\.\w+$/, "").split("/").pop() ?? "";
+    return base
+        .replace(/\.(test|spec|demo)$/i, "")
+        .replace(/^test_/i, "")
+        .replace(/_test$/i, "");
+}
+async function findConventionTests(rootDir, sourceFile, allFiles) {
+    const base = baseNameWithoutTestAffixes(sourceFile);
+    return allFiles.filter((file) => {
+        if (!isTestFile(file))
+            return false;
+        const testBase = baseNameWithoutTestAffixes(file);
+        return testBase === base;
+    });
+}
+async function findImporterTests(rootDir, file, maxDepth) {
+    const db = await getDB(rootDir);
+    const target = db.getFile(file);
+    if (!target)
+        return [];
+    const indexedFiles = db.getAllFiles();
+    const fileById = new Map(indexedFiles.map((candidate) => [candidate.id, candidate]));
+    const queue = [{ fileId: target.id, via: [file], depth: 0 }];
+    const visited = new Set([target.id]);
+    const results = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current.depth >= maxDepth)
+            continue;
+        for (const importer of db.getImportersOf(current.fileId)) {
+            const source = fileById.get(importer.source_file_id);
+            if (!source || visited.has(source.id))
+                continue;
+            visited.add(source.id);
+            const path = source.path;
+            const via = [...current.via, path];
+            const depth = current.depth + 1;
+            if (isTestFile(path)) {
+                results.push({
+                    path,
+                    reason: depth === 1 ? "Imports target module" : `Imports dependent chain: ${via.join(" <- ")}`,
+                    score: Math.max(0.68, 0.9 - depth * 0.08),
+                });
+                continue;
+            }
+            queue.push({ fileId: source.id, via, depth });
+        }
+    }
+    return results;
+}
+export async function findTestsForFiles(rootDir, files) {
+    const entries = await walkDirectory({ rootDir, depthLimit: 0 });
+    const allFiles = entries.filter((entry) => !entry.isDirectory).map((entry) => entry.relativePath);
+    const results = [];
+    for (const file of files) {
+        const convention = await findConventionTests(rootDir, file, allFiles);
+        for (const testPath of convention) {
+            results.push({ path: testPath, reason: "Matched by test naming convention", score: 0.68 });
+        }
+        results.push(...await findImporterTests(rootDir, file, 5));
+    }
+    const deduped = new Map();
+    for (const item of results) {
+        const existing = deduped.get(item.path);
+        if (!existing || item.score > existing.score)
+            deduped.set(item.path, item);
+    }
+    return [...deduped.values()].sort((a, b) => b.score - a.score);
+}
+export async function getRecentDiffSummary(rootDir, filePath) {
+    try {
+        const { stdout } = await execFileAsync("git", ["log", "--oneline", "-n", "1", "--", filePath], {
+            cwd: rootDir,
+            timeout: 5000,
+        });
+        const line = stdout.trim().split("\n")[0];
+        if (!line)
+            return null;
+        const [commit, ...summary] = line.split(" ");
+        return { path: filePath, commit, summary: summary.join(" ") };
+    }
+    catch {
+        return null;
+    }
+}
+export async function getProjectMemoryHits(rootDir, query, topK, keywordOnly = false) {
+    if (!Number.isFinite(topK) || topK <= 0)
+        return [];
+    const db = await getDB(rootDir);
+    const config = await loadProjectConfig(rootDir);
+    const projectId = config?.projectId ?? "";
+    const clientId = config?.clientId ?? "";
+    let queryVector;
+    try {
+        queryVector = keywordOnly || !hasCompatibleEmbeddingModel(db) ? [] : await fetchQueryEmbedding(query);
+    }
+    catch {
+        queryVector = [];
+    }
+    const terms = query.toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [];
+    const lexicalHits = db.listMemoryNodes().map((node) => ({ node, distance: 1, score: terms.reduce((sum, term) => sum + Number(`${node.label} ${node.content}`.toLowerCase().includes(term)), 0) }))
+        .filter((hit) => hit.score > 0).sort((a, b) => b.score - a.score || a.node.id.localeCompare(b.node.id));
+    const semanticHits = queryVector.length && hasCompatibleEmbeddingModel(db) ? db.searchMemoryNodes(queryVector, Math.max(topK * 6, 18)) : [];
+    const hits = [...semanticHits, ...lexicalHits.filter((hit) => !semanticHits.some((candidate) => candidate.node.id === hit.node.id))];
+    const filtered = [];
+    for (const hit of hits) {
+        const evidenceStatus = await memoryEvidenceStatus(rootDir, hit.node);
+        if (evidenceStatus === "stale" || evidenceStatus === "superseded")
+            continue;
+        const metadata = parseMetadata(hit.node.metadata);
+        const scope = metadata.scope ?? "project";
+        if (scope === "global") {
+            // Global memories are always relevant.
+        }
+        else if (scope === "client") {
+            if (metadata.client_id !== clientId)
+                continue;
+        }
+        else if (scope === "project") {
+            if (metadata.project_id !== projectId)
+                continue;
+        }
+        else {
+            continue;
+        }
+        filtered.push({
+            id: hit.node.id,
+            kind: metadata.record_kind ?? "memory",
+            summary: `[${evidenceStatus}] ${hit.node.content.slice(0, 220)}`,
+        });
+        if (filtered.length >= topK)
+            break;
+    }
+    return filtered;
+}
+/** Bounded lexical risk lookup; never pay for embeddings on the context path. */
+export async function getProjectRiskEvidence(rootDir, query) {
+    const db = await getDB(rootDir), config = await loadProjectConfig(rootDir);
+    const terms = [...new Set(query.toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [])];
+    const candidates = db.listMemoryNodes().flatMap(node => {
+        const metadata = parseMetadata(node.metadata);
+        if (metadata.record_kind !== "task" || metadata.scope !== "project" || metadata.project_id !== (config?.projectId ?? ""))
+            return [];
+        // Older task records used a labelled content line. Preserve inspection and
+        // compatibility, but still require current bound evidence below.
+        const risks = metadata.open_risks !== undefined ? parseJsonArray(metadata.open_risks)
+            : (node.content.match(/^Open Risks: (.+)$/m)?.[1].split(" | ") ?? []);
+        if (!risks.length)
+            return [];
+        const text = `${node.label} ${node.content}`.toLowerCase();
+        const score = terms.reduce((sum, term) => sum + Number(text.includes(term)), 0);
+        return score ? [{ node, risks, score }] : [];
+    }).sort((a, b) => b.score - a.score || a.node.id.localeCompare(b.node.id));
+    const result = [];
+    for (const { node, risks } of candidates.slice(0, 12)) {
+        if (await memoryEvidenceStatus(rootDir, node) !== "current")
+            continue;
+        result.push({ id: node.id, risks: risks.slice(0, 2) });
+        if (result.length === 2)
+            break;
+    }
+    return result;
+}
+export async function resolveFilesFromSymbols(rootDir, symbols) {
+    if (!symbols || symbols.length === 0)
+        return [];
+    const db = await getDB(rootDir);
+    const files = [];
+    const indexedFiles = db.getAllFiles();
+    for (const symbol of symbols) {
+        const matches = db.searchSymbolsByName(symbol);
+        for (const match of matches) {
+            const file = indexedFiles.find((candidate) => candidate.id === match.file_id);
+            if (file)
+                files.push(file.path);
+        }
+    }
+    return unique(files);
+}
+export async function findTextDependents(rootDir, filePath, symbolNames = []) {
+    const db = await getDB(rootDir);
+    const dbFile = db.getFile(filePath);
+    if (dbFile) {
+        const importerRows = db.getImportersOf(dbFile.id);
+        const importerPaths = importerRows
+            .map((row) => db.getFileById(row.source_file_id)?.path)
+            .filter((path) => path !== undefined && path !== filePath);
+        if (importerPaths.length > 0 || symbolNames.length === 0)
+            return unique(importerPaths);
+    }
+    const entries = await walkDirectory({ rootDir, depthLimit: 0 });
+    const candidates = entries.filter((entry) => !entry.isDirectory).map((entry) => entry.relativePath);
+    const baseName = basename(filePath).replace(/\.\w+$/, "");
+    const matches = [];
+    for (const candidate of candidates) {
+        if (candidate === filePath)
+            continue;
+        try {
+            const content = await readFile(resolveProjectPath(rootDir, candidate, "candidate file"), "utf-8");
+            if (content.includes(baseName) || symbolNames.some((symbol) => content.includes(symbol))) {
+                matches.push(candidate);
+            }
+        }
+        catch { }
+    }
+    return unique(matches);
+}
+export async function scanExactMentions(rootDir, candidateFiles, symbolNames) {
+    if (candidateFiles.length === 0 || symbolNames.length === 0)
+        return [];
+    const matches = [];
+    for (const candidate of candidateFiles) {
+        try {
+            const content = await readFile(resolveProjectPath(rootDir, candidate, "candidate file"), "utf-8");
+            if (symbolNames.some((symbol) => content.includes(symbol)))
+                matches.push(candidate);
+        }
+        catch { }
+    }
+    return unique(matches);
+}
+export async function fileRisk(rootDir, filePath) {
+    const db = await getDB(rootDir);
+    const dbFile = db.getFile(filePath);
+    let importers = 0;
+    let imports = 0;
+    if (dbFile) {
+        importers = db.getImportersOf(dbFile.id).length;
+        imports = db.getImportsFrom(dbFile.id).length;
+    }
+    let churn = 0;
+    try {
+        const { stdout } = await execFileAsync("git", ["log", "--oneline", "--", filePath], { cwd: rootDir, timeout: 5000 });
+        churn = stdout.trim().split("\n").filter(Boolean).length;
+    }
+    catch { }
+    return { importers, imports, churn };
+}
+export async function hubMatchesForFiles(rootDir, filePaths) {
+    const hubs = await discoverHubs(rootDir).catch(() => []);
+    const matches = [];
+    for (const hubPath of hubs) {
+        const hub = await parseHubFile(resolveProjectPath(rootDir, hubPath, "hubPath")).catch(() => null);
+        if (!hub)
+            continue;
+        if (hub.links.some((link) => filePaths.includes(link.target))) {
+            matches.push(hubPath);
+        }
+    }
+    return matches;
+}
+//# sourceMappingURL=retrieval-helpers.js.map