@lzehrung/codegraph 2.1.0

package/dist/agent/search.js

@@ -0,0 +1,1002 @@
+import fs from "node:fs/promises";
+import {} from "../analysisSummary.js";
+import { SymbolKind } from "../indexer/types.js";
+import {} from "../graphs/symbol-graph.js";
+import { buildSymbolLookup } from "./symbolLookup.js";
+import { AGENT_SEARCH_EVIDENCE_PER_RESULT_LIMIT, AGENT_SEARCH_FOLLOWUPS_PER_RESULT_LIMIT, AGENT_SEARCH_FORMAT_REASON_LIMIT, AGENT_SEARCH_NEIGHBORS_PER_RESULT_LIMIT, AGENT_SEARCH_RANK_REASONS_PER_RESULT_LIMIT, AGENT_SEARCH_RESULT_LIMIT, } from "../presentation/bounds.js";
+import { normalizePath } from "../util/paths.js";
+import { errorMessage } from "../util/errors.js";
+import { boundAgentList, defaultAgentLimit } from "./bounds.js";
+import { formatAgentChunkHandle, formatAgentFileHandle, formatAgentGraphHandle, formatAgentSqlHandle, formatAgentSymbolHandle, parseAgentChunkHandle, parseAgentFileHandle, parseAgentGraphHandle, parseAgentSqlHandle, parseAgentSymbolHandle, } from "./handles.js";
+import { collectDefinitionFollowUps, collectFileFollowUps as collectCommonFileFollowUps, isAgentSqlObjectNode, normalizeAgentFilePath, resolveAgentSnapshotFile, } from "./normalize.js";
+import { createAgentSession } from "./session.js";
+import { formatAgentFollowUpAsCli, toolFollowUp } from "./followUps.js";
+import { buildQueryTextChunks, detectQueryIndexSurface, normalizeQuerySearchText, QUERY_INDEX_NORMALIZER_VERSION, } from "./query-index/content.js";
+import { findQueryIndexChunkCandidates, QUERY_INDEX_CANDIDATE_VERSION } from "./query-index/candidates.js";
+import { registerSessionInvalidationHook } from "./sessionLifecycle.js";
+const DEFAULT_LIMIT = 20;
+const MAX_TEXT_BYTES = 300_000;
+const MAX_GRAPH_DEPTH = 5;
+const DOCS_EXACT_PHRASE_BOOST = 18;
+const DOCS_PROXIMITY_BOOST = 6;
+const NATURAL_LANGUAGE_SYNTAX_TERMS = new Set([
+    "a",
+    "an",
+    "are",
+    "can",
+    "did",
+    "do",
+    "does",
+    "how",
+    "is",
+    "the",
+    "what",
+    "when",
+    "where",
+    "which",
+    "who",
+    "why",
+    "or",
+]);
+const SEARCH_CACHES = new WeakMap();
+const SEARCH_RESULT_CACHES = new WeakMap();
+const SEARCH_RANKING_VERSION = 2;
+export async function searchCodegraph(request) {
+    const session = createAgentSession({
+        root: request.root,
+        ...(request.buildOptions ? { buildOptions: request.buildOptions } : {}),
+    });
+    try {
+        return await searchCodegraphWithSession(session, request);
+    }
+    finally {
+        session.invalidate();
+    }
+}
+export async function searchCodegraphWithSession(session, request) {
+    if (canUsePathFastPath(request) && session.listFiles && session.root) {
+        const files = await session.listFiles();
+        return searchPathOnly(session.root, files, request);
+    }
+    const snapshot = await session.loadProject({
+        // Hybrid/symbol/graph need symbol nodes, but not the detailed sidecar.
+        symbolGraph: searchNeedsSymbolGraph(request) ? "basic" : "skip",
+    });
+    const resultCache = getSessionSearchResultCache(session);
+    const cacheKey = searchResultCacheKey(snapshot, request);
+    const existing = resultCache.get(cacheKey);
+    if (existing) {
+        const response = await existing;
+        if (response.query === request.query)
+            return response;
+        return { ...response, query: request.query };
+    }
+    const mode = request.mode ?? "hybrid";
+    let queryIndex;
+    if (mode === "hybrid" || mode === "text") {
+        const { ensureSessionQueryIndex } = await import("./query-index/sessionStore.js");
+        queryIndex = await ensureSessionQueryIndex(session, snapshot);
+    }
+    const search = searchSnapshot(snapshot, request, queryIndex);
+    resultCache.set(cacheKey, search);
+    search.catch(() => {
+        if (resultCache.get(cacheKey) === search)
+            resultCache.delete(cacheKey);
+    });
+    return await search;
+}
+export function formatAgentSearchResponse(response) {
+    if (!response.results.length) {
+        return `No matches for "${response.query}"\nAnalysis: ${response.analysis.label}`;
+    }
+    const lines = [`Analysis: ${response.analysis.label}`];
+    for (const [index, result] of response.results.entries()) {
+        const location = result.range
+            ? `${result.file}:${result.range.start.line}:${result.range.start.column}`
+            : result.file;
+        const reasons = result.rankReasons.slice(0, AGENT_SEARCH_FORMAT_REASON_LIMIT).join("; ");
+        lines.push(`${index + 1}. ${result.label} [${result.kind}] ${location} score=${result.score} (${result.provenance.surface}, ${result.provenance.capability})`);
+        lines.push(`   ${reasons}`);
+        for (const followUp of result.followUps) {
+            lines.push(`   follow-up: ${formatAgentFollowUpAsCli(followUp)}`);
+        }
+    }
+    return lines.join("\n");
+}
+async function searchSnapshot(snapshot, request, queryIndex) {
+    const mode = request.mode ?? "hybrid";
+    const query = buildQueryTerms(request.query, snapshot);
+    const resultMap = new Map();
+    const limit = defaultAgentLimit(request.limit, DEFAULT_LIMIT, AGENT_SEARCH_RESULT_LIMIT);
+    let fileNeighborIndex;
+    const getFileNeighborIndex = () => {
+        fileNeighborIndex ??= buildFileNeighborIndex(snapshot);
+        return fileNeighborIndex;
+    };
+    if (query.rankTokens.length) {
+        if (mode === "sql") {
+            addSqlResults(snapshot, resultMap, getFileNeighborIndex(), query);
+        }
+        else if (mode === "hybrid" || mode === "symbol" || mode === "graph") {
+            const symbolLookup = buildSymbolLookup(snapshot);
+            addSymbolResults(snapshot, resultMap, symbolLookup, buildSymbolNeighborIndex(snapshot), query, mode);
+        }
+        if (mode === "hybrid" || mode === "path" || mode === "graph") {
+            addPathResults(snapshot, resultMap, getFileNeighborIndex(), query);
+        }
+        if (mode === "hybrid" || mode === "text") {
+            await addTextResults(snapshot, resultMap, query, request.includeSnippets ?? true, mode, queryIndex);
+        }
+    }
+    if (request.from !== undefined && (mode === "hybrid" || mode === "graph")) {
+        applyGraphNeighborhood(snapshot, resultMap, getFileNeighborIndex(), query, request.from, normalizeDepth(request.depth));
+    }
+    const selectedResults = selectTopResults(resultMap, limit);
+    const results = selectedResults.items.map(finalizeResult);
+    return {
+        schemaVersion: 1,
+        query: request.query,
+        mode,
+        root: snapshot.root,
+        analysis: snapshot.analysis,
+        limits: {
+            results: limit,
+            rankReasonsPerResult: AGENT_SEARCH_RANK_REASONS_PER_RESULT_LIMIT,
+            evidencePerResult: AGENT_SEARCH_EVIDENCE_PER_RESULT_LIMIT,
+            neighborsPerResult: AGENT_SEARCH_NEIGHBORS_PER_RESULT_LIMIT,
+            followUpsPerResult: AGENT_SEARCH_FOLLOWUPS_PER_RESULT_LIMIT,
+        },
+        resultCount: results.length,
+        totalCandidates: selectedResults.totalCandidates,
+        omittedCounts: {
+            results: selectedResults.omitted,
+        },
+        results,
+    };
+}
+function canUsePathFastPath(request) {
+    return (request.mode ?? "hybrid") === "path" && request.from === undefined;
+}
+function getSessionSearchResultCache(session) {
+    const existing = SEARCH_RESULT_CACHES.get(session);
+    if (existing)
+        return existing;
+    const created = new Map();
+    SEARCH_RESULT_CACHES.set(session, created);
+    registerSessionInvalidationHook(session, () => SEARCH_RESULT_CACHES.delete(session));
+    return created;
+}
+function searchResultCacheKey(snapshot, request) {
+    const { rankTokens, normalizedRankPhrase, identifierLike } = buildQueryTerms(request.query, snapshot);
+    return JSON.stringify({
+        projectSnapshotIdentity: snapshot.index.projectSnapshotIdentity ?? "",
+        query: { rankTokens, normalizedRankPhrase, identifierLike },
+        mode: request.mode ?? "hybrid",
+        limit: defaultAgentLimit(request.limit, DEFAULT_LIMIT, AGENT_SEARCH_RESULT_LIMIT),
+        depth: normalizeDepth(request.depth),
+        from: request.from ?? "",
+        includeSnippets: request.includeSnippets ?? true,
+        normalizerVersion: QUERY_INDEX_NORMALIZER_VERSION,
+        rankingVersion: SEARCH_RANKING_VERSION,
+        candidateVersion: QUERY_INDEX_CANDIDATE_VERSION,
+    });
+}
+function searchPathOnly(root, files, request) {
+    const query = buildQueryTerms(request.query, { root, files });
+    const resultMap = new Map();
+    const limit = defaultAgentLimit(request.limit, DEFAULT_LIMIT, AGENT_SEARCH_RESULT_LIMIT);
+    if (query.tokens.length) {
+        for (const file of files) {
+            const relFile = normalizeAgentFilePath(root, file);
+            const pathMatch = matchTokenScore(relFile, query);
+            if (pathMatch.score <= 0)
+                continue;
+            const result = upsertResult(resultMap, {
+                handle: formatAgentFileHandle({ file: relFile }),
+                kind: "file",
+                label: relFile,
+                file: relFile,
+                provenance: createSearchProvenance(relFile, "text", "high", {
+                    mode: "reduced",
+                    backend: "unknown",
+                }),
+            });
+            result.score += pathMatch.score * 2;
+            addMatchedRankTerms(result, pathMatch);
+            addReason(result, `path token match: ${pathMatch.matched.join(", ")}`);
+            addEvidence(result, { source: "path", label: relFile, file: relFile });
+            addFileFollowUps(result, relFile);
+        }
+    }
+    const selectedResults = selectTopResults(resultMap, limit);
+    const results = selectedResults.items.map(finalizeResult);
+    return {
+        schemaVersion: 1,
+        query: request.query,
+        mode: "path",
+        root,
+        analysis: {
+            mode: "reduced",
+            backend: "unknown",
+            parserDegradedFiles: 0,
+            fallbackImportExtractionFiles: 0,
+            nativeFilesUsed: 0,
+            nativeFilesFellBack: 0,
+            label: "path-only",
+        },
+        limits: {
+            results: limit,
+            rankReasonsPerResult: AGENT_SEARCH_RANK_REASONS_PER_RESULT_LIMIT,
+            evidencePerResult: AGENT_SEARCH_EVIDENCE_PER_RESULT_LIMIT,
+            neighborsPerResult: AGENT_SEARCH_NEIGHBORS_PER_RESULT_LIMIT,
+            followUpsPerResult: AGENT_SEARCH_FOLLOWUPS_PER_RESULT_LIMIT,
+        },
+        resultCount: results.length,
+        totalCandidates: selectedResults.totalCandidates,
+        omittedCounts: {
+            results: selectedResults.omitted,
+        },
+        results,
+    };
+}
+function normalizeDepth(depth) {
+    if (typeof depth !== "number" || !Number.isFinite(depth))
+        return 1;
+    return Math.min(MAX_GRAPH_DEPTH, Math.max(0, Math.floor(depth)));
+}
+function searchNeedsSymbolGraph(request) {
+    const mode = request.mode ?? "hybrid";
+    return mode !== "path" && mode !== "text" && mode !== "sql";
+}
+function buildQueryTerms(input, snapshot) {
+    const normalized = normalizeSearchText(input);
+    const tokenSequence = normalized.split(/\s+/).filter((token) => token.length);
+    const tokens = Array.from(new Set(tokenSequence));
+    const identifierLike = isIdentifierLikeQuery(input);
+    const pathLike = isExplicitPathQuery(input, snapshot);
+    const filterNaturalLanguageSyntax = !identifierLike && !pathLike;
+    const filteredRankTokenSequence = filterNaturalLanguageSyntax
+        ? tokenSequence.filter((token) => !NATURAL_LANGUAGE_SYNTAX_TERMS.has(token))
+        : tokenSequence;
+    const rankTokenSequence = filteredRankTokenSequence.length ? filteredRankTokenSequence : tokenSequence;
+    return {
+        tokens,
+        rankTokens: Array.from(new Set(rankTokenSequence)),
+        normalizedRankPhrase: rankTokenSequence.join(" "),
+        identifierLike,
+    };
+}
+function isExplicitPathQuery(input, snapshot) {
+    const trimmed = input.trim();
+    const slashIndex = trimmed.search(/[\\/]/);
+    if (slashIndex < 0)
+        return false;
+    if (!/\s/.test(trimmed))
+        return true;
+    return resolveAgentSnapshotFile(snapshot, trimmed) !== null;
+}
+function normalizeSearchText(input) {
+    return normalizeQuerySearchText(input);
+}
+function isIdentifierLikeQuery(input) {
+    const trimmed = input.trim();
+    return /^[A-Za-z_$][A-Za-z0-9_$]*(?:[.#:][A-Za-z_$][A-Za-z0-9_$]*)*$/.test(trimmed);
+}
+function emptyTokenMatch() {
+    return { score: 0, matched: [], exactPhrase: false, proximity: false };
+}
+function matchTokenScore(text, query) {
+    const normalized = normalizeSearchText(text);
+    return matchTokenScoreFromNormalized(normalized, query);
+}
+function matchTokenScoreFromNormalized(normalized, query) {
+    if (!normalized)
+        return emptyTokenMatch();
+    const words = new Set(normalized.split(/\s+/).filter(Boolean));
+    const compact = normalized.replace(/\s+/g, "");
+    const matched = [];
+    let score = 0;
+    for (const token of query.rankTokens) {
+        if (words.has(token)) {
+            score += 10;
+            matched.push(token);
+        }
+        else if (compact.includes(token)) {
+            score += 7;
+            matched.push(token);
+        }
+        else if (normalized.includes(token)) {
+            score += 4;
+            matched.push(token);
+        }
+    }
+    let exactPhrase = false;
+    let proximity = false;
+    if (matched.length === query.rankTokens.length && query.rankTokens.length > 1) {
+        score += 12;
+        if (normalized.includes(query.normalizedRankPhrase)) {
+            score += 30;
+            exactPhrase = true;
+        }
+        else if (tokensAppearInOrder(normalized, query.rankTokens)) {
+            score += 10;
+            proximity = true;
+        }
+    }
+    return { score, matched, exactPhrase, proximity };
+}
+function tokensAppearInOrder(normalizedText, tokens) {
+    let fromIndex = 0;
+    for (const token of tokens) {
+        const tokenIndex = normalizedText.indexOf(token, fromIndex);
+        if (tokenIndex < 0)
+            return false;
+        fromIndex = tokenIndex + token.length;
+    }
+    return true;
+}
+function addSymbolResults(snapshot, resultMap, lookup, neighborsBySymbolId, query, mode) {
+    for (const node of snapshot.symbolGraph.nodes.values()) {
+        const sqlObject = isAgentSqlObjectNode(node);
+        if (mode === "sql" && !sqlObject)
+            continue;
+        if (mode === "symbol" && sqlObject)
+            continue;
+        const nameMatch = matchTokenScore(node.name, query);
+        const fileMatch = matchTokenScore(normalizeAgentFilePath(snapshot.root, node.file), query);
+        const docMatch = node.docstring ? matchTokenScore(node.docstring, query) : emptyTokenMatch();
+        const score = nameMatch.score * 4 + fileMatch.score + docMatch.score;
+        if (score <= 0)
+            continue;
+        const def = lookup.defById.get(node.id);
+        if (!def)
+            continue;
+        const relFile = normalizeAgentFilePath(snapshot.root, node.file);
+        const handle = sqlObject
+            ? formatAgentSqlHandle({ name: node.name, file: relFile, line: def.range.start.line })
+            : formatAgentSymbolHandle({
+                file: relFile,
+                name: node.name,
+                line: def.range.start.line,
+                column: def.range.start.column,
+            });
+        const result = upsertResult(resultMap, {
+            handle,
+            kind: sqlObject ? "sql_object" : "symbol",
+            label: node.name,
+            file: relFile,
+            range: def.range,
+            provenance: createSearchProvenance(relFile, "semantic", "high", snapshot.analysis),
+        });
+        result.score += score + (lookup.exportedIds.has(node.id) ? 5 : 0);
+        addMatchedRankTerms(result, nameMatch, fileMatch, docMatch);
+        if (nameMatch.matched.length) {
+            addReason(result, `${sqlObject ? "SQL object" : "symbol"} token match: ${nameMatch.matched.join(", ")}`);
+            addEvidence(result, {
+                source: sqlObject ? "sql" : "symbol",
+                label: node.name,
+                file: relFile,
+                line: def.range.start.line,
+            });
+        }
+        if (fileMatch.matched.length) {
+            addReason(result, `path token match: ${fileMatch.matched.join(", ")}`);
+        }
+        if (docMatch.matched.length) {
+            addReason(result, `docstring token match: ${docMatch.matched.join(", ")}`);
+        }
+        addPhraseReasons(result, nameMatch, "symbol name");
+        addPhraseReasons(result, docMatch, "docstring");
+        addSymbolNeighbors(snapshot, result, neighborsBySymbolId.get(node.id) ?? []);
+        addSymbolFollowUps(result, relFile, def);
+    }
+}
+function addSqlResults(snapshot, resultMap, fileNeighborIndex, query) {
+    for (const moduleIndex of snapshot.index.byFile.values()) {
+        for (const local of moduleIndex.locals) {
+            if (!isSqlObjectSymbol(local))
+                continue;
+            const nameMatch = matchTokenScore(local.localName, query);
+            const relFile = normalizeAgentFilePath(snapshot.root, local.file);
+            const fileMatch = matchTokenScore(relFile, query);
+            const docMatch = local.docstring ? matchTokenScore(local.docstring, query) : emptyTokenMatch();
+            const score = nameMatch.score * 4 + fileMatch.score + docMatch.score;
+            if (score <= 0)
+                continue;
+            const result = upsertResult(resultMap, {
+                handle: formatAgentSqlHandle({ name: local.localName, file: relFile, line: local.range.start.line }),
+                kind: "sql_object",
+                label: local.localName,
+                file: relFile,
+                range: local.range,
+                provenance: createSearchProvenance(relFile, "semantic", "high", snapshot.analysis),
+            });
+            result.score += score;
+            addMatchedRankTerms(result, nameMatch, fileMatch, docMatch);
+            if (nameMatch.matched.length) {
+                addReason(result, `SQL object token match: ${nameMatch.matched.join(", ")}`);
+                addEvidence(result, {
+                    source: "sql",
+                    label: local.localName,
+                    file: relFile,
+                    line: local.range.start.line,
+                });
+            }
+            if (fileMatch.matched.length) {
+                addReason(result, `path token match: ${fileMatch.matched.join(", ")}`);
+            }
+            if (docMatch.matched.length) {
+                addReason(result, `docstring token match: ${docMatch.matched.join(", ")}`);
+            }
+            addPhraseReasons(result, nameMatch, "SQL object name");
+            addPhraseReasons(result, docMatch, "docstring");
+            addFileNeighbors(snapshot, result, fileNeighborIndex.get(normalizePath(local.file)) ?? []);
+            addSymbolFollowUps(result, relFile, local);
+        }
+    }
+}
+function isSqlObjectSymbol(symbol) {
+    return (symbol.kind === SymbolKind.Table ||
+        symbol.kind === SymbolKind.View ||
+        symbol.kind === SymbolKind.Index ||
+        symbol.kind === SymbolKind.Routine);
+}
+function addPathResults(snapshot, resultMap, fileNeighborIndex, query) {
+    for (const file of snapshot.files) {
+        const relFile = normalizeAgentFilePath(snapshot.root, file);
+        const pathMatch = matchTokenScore(relFile, query);
+        if (pathMatch.score <= 0)
+            continue;
+        const result = upsertResult(resultMap, {
+            handle: formatAgentFileHandle({ file: relFile }),
+            kind: "file",
+            label: relFile,
+            file: relFile,
+            provenance: createSearchProvenance(relFile, "graph", "high", snapshot.analysis),
+        });
+        result.score += pathMatch.score * 2;
+        addMatchedRankTerms(result, pathMatch);
+        addReason(result, `path token match: ${pathMatch.matched.join(", ")}`);
+        addEvidence(result, { source: "path", label: relFile, file: relFile });
+        addFileNeighbors(snapshot, result, fileNeighborIndex.get(normalizePath(file)) ?? []);
+        addFileFollowUps(result, relFile);
+    }
+}
+function mergeSearchResults(targetMap, sourceMap) {
+    for (const source of sourceMap.values()) {
+        const target = upsertResult(targetMap, source);
+        target.score += source.score;
+        for (const term of source.matchedRankTerms)
+            target.matchedRankTerms.add(term);
+        for (const reason of source.rankReasons)
+            target.rankReasons.add(reason);
+        for (const evidence of source.evidence)
+            addEvidence(target, evidence);
+        for (const [key, neighbor] of source.neighbors)
+            target.neighbors.set(key, neighbor);
+        for (const [key, followUp] of source.followUps)
+            target.followUps.set(key, followUp);
+    }
+}
+async function addTextResults(snapshot, resultMap, query, includeSnippets, mode, queryIndex) {
+    const projectSnapshotIdentity = snapshot.index.projectSnapshotIdentity;
+    const store = queryIndex?.store;
+    const diagnostics = queryIndex?.diagnostics;
+    if (store && diagnostics && projectSnapshotIdentity) {
+        const candidateResultMap = new Map();
+        try {
+            store.withReadSnapshot(projectSnapshotIdentity, () => {
+                const candidateStarted = performance.now();
+                const candidateChunks = findQueryIndexChunkCandidates(store, query.rankTokens);
+                diagnostics.candidateMs += performance.now() - candidateStarted;
+                diagnostics.fileCandidates += new Set(candidateChunks.map((chunk) => chunk.path)).size;
+                diagnostics.chunkCandidates += candidateChunks.length;
+                const allowedPaths = new Set(snapshot.files.map((file) => normalizeAgentFilePath(snapshot.root, file)));
+                const scoringStarted = performance.now();
+                for (const chunk of candidateChunks) {
+                    if (!allowedPaths.has(chunk.path)) {
+                        throw new Error(`Query index returned an out-of-snapshot path: ${chunk.path}`);
+                    }
+                    addTextFileResults(snapshot, candidateResultMap, query, includeSnippets, mode, chunk.path, [chunk]);
+                }
+                diagnostics.scoringMs += performance.now() - scoringStarted;
+            });
+            mergeSearchResults(resultMap, candidateResultMap);
+            return;
+        }
+        catch (error) {
+            diagnostics.sidecarState = "unavailable";
+            diagnostics.fallbackReason = errorMessage(error);
+        }
+    }
+    const cache = getSearchCache(snapshot);
+    for (const file of snapshot.files) {
+        const normalizedText = await getCachedNormalizedText(cache, file);
+        if (!normalizedText || !textCouldMatchNormalized(normalizedText, query.rankTokens))
+            continue;
+        const relFile = normalizeAgentFilePath(snapshot.root, file);
+        const chunks = await getCachedTextChunks(cache, file);
+        addTextFileResults(snapshot, resultMap, query, includeSnippets, mode, relFile, chunks);
+    }
+}
+function addTextFileResults(snapshot, resultMap, query, includeSnippets, mode, relFile, chunks) {
+    const documentationFile = isDocumentationFile(relFile);
+    for (const chunk of chunks) {
+        const match = matchTokenScoreFromNormalized(chunk.normalizedText, query);
+        if (match.score <= 0)
+            continue;
+        const handle = formatAgentChunkHandle({ file: relFile, line: chunk.startLine });
+        const result = upsertResult(resultMap, {
+            handle,
+            kind: "chunk",
+            label: chunk.name ? `${chunk.name} (${relFile})` : `${relFile}:${chunk.startLine}`,
+            file: relFile,
+            range: {
+                start: { line: chunk.startLine, column: 0 },
+                end: { line: chunk.endLine, column: 0 },
+            },
+            provenance: createSearchProvenance(relFile, "text", documentationFile ? "medium" : "high", snapshot.analysis),
+        });
+        if (chunk.name && result.label === `${relFile}:${chunk.startLine}`) {
+            result.label = `${chunk.name} (${relFile})`;
+            result.range = {
+                start: { line: chunk.startLine, column: 0 },
+                end: { line: chunk.endLine, column: 0 },
+            };
+        }
+        result.score += match.score + textResultBoost(match, documentationFile, query, mode);
+        addMatchedRankTerms(result, match);
+        addReason(result, `text token match: ${match.matched.join(", ")}`);
+        addPhraseReasons(result, match, documentationFile ? "docs text" : "text");
+        addEvidence(result, {
+            source: "chunk",
+            label: result.label,
+            file: relFile,
+            line: chunk.startLine,
+            ...(includeSnippets ? { snippet: makeSnippet(chunk.text, query) } : {}),
+        });
+        addFileFollowUps(result, relFile);
+    }
+}
+function textResultBoost(match, documentationFile, query, mode) {
+    if (!documentationFile || query.identifierLike)
+        return 0;
+    if (mode !== "text" && mode !== "hybrid")
+        return 0;
+    if (match.exactPhrase)
+        return DOCS_EXACT_PHRASE_BOOST;
+    if (match.proximity)
+        return DOCS_PROXIMITY_BOOST;
+    return 0;
+}
+function isDocumentationFile(relFile) {
+    const lower = relFile.toLowerCase();
+    return (lower === "readme.md" ||
+        lower.startsWith("docs/") ||
+        lower.endsWith(".md") ||
+        lower.endsWith(".mdx") ||
+        lower.endsWith(".rst") ||
+        lower.endsWith(".adoc") ||
+        lower.endsWith(".txt"));
+}
+function addPhraseReasons(result, match, label) {
+    if (match.exactPhrase) {
+        addReason(result, `exact phrase match in ${label}`);
+        return;
+    }
+    if (match.proximity) {
+        addReason(result, `nearby token match in ${label}`);
+    }
+}
+function textCouldMatchNormalized(normalizedText, tokens) {
+    return tokens.some((token) => normalizedText.includes(token));
+}
+function getSearchCache(snapshot) {
+    const existing = SEARCH_CACHES.get(snapshot);
+    if (existing)
+        return existing;
+    const created = {
+        fileText: new Map(),
+        normalizedText: new Map(),
+        textChunks: new Map(),
+    };
+    SEARCH_CACHES.set(snapshot, created);
+    return created;
+}
+async function getCachedFileText(cache, file) {
+    const cached = cache.fileText.get(file);
+    if (cached)
+        return await cached;
+    const loadPromise = readSearchableFile(file);
+    cache.fileText.set(file, loadPromise);
+    loadPromise.catch(() => {
+        if (cache.fileText.get(file) === loadPromise)
+            cache.fileText.delete(file);
+    });
+    return await loadPromise;
+}
+async function getCachedNormalizedText(cache, file) {
+    const cached = cache.normalizedText.get(file);
+    if (cached)
+        return await cached;
+    const loadPromise = getCachedFileText(cache, file).then((text) => (text ? normalizeSearchText(text) : null));
+    cache.normalizedText.set(file, loadPromise);
+    loadPromise.catch(() => {
+        if (cache.normalizedText.get(file) === loadPromise)
+            cache.normalizedText.delete(file);
+    });
+    return await loadPromise;
+}
+async function getCachedTextChunks(cache, file) {
+    const cached = cache.textChunks.get(file);
+    if (cached)
+        return await cached;
+    const loadPromise = getCachedFileText(cache, file).then((text) => (text ? buildTextChunks(file, text) : []));
+    cache.textChunks.set(file, loadPromise);
+    loadPromise.catch(() => {
+        if (cache.textChunks.get(file) === loadPromise)
+            cache.textChunks.delete(file);
+    });
+    return await loadPromise;
+}
+function applyGraphNeighborhood(snapshot, resultMap, fileNeighborIndex, query, from, depth) {
+    const anchorFiles = resolveAnchorFiles(snapshot, from);
+    if (anchorFiles.size === 0)
+        return;
+    const reachable = collectReachableFiles(fileNeighborIndex, anchorFiles, depth);
+    for (const entry of reachable.values()) {
+        const relFile = normalizeAgentFilePath(snapshot.root, entry.file);
+        const existingResults = [...resultMap.values()].filter((result) => result.file === relFile);
+        const fileMatch = matchTokenScore(relFile, query);
+        if (fileMatch.score > 0) {
+            const graphResult = upsertResult(resultMap, {
+                handle: formatAgentGraphHandle({ file: relFile }),
+                kind: "graph_node",
+                label: relFile,
+                file: relFile,
+                provenance: createSearchProvenance(relFile, "graph", "medium", snapshot.analysis),
+            });
+            graphResult.score += fileMatch.score + graphBoost(entry.distance);
+            addGraphEvidence(graphResult, relFile, entry);
+            addMatchedRankTerms(graphResult, fileMatch);
+            addFileFollowUps(graphResult, relFile);
+        }
+        for (const result of existingResults) {
+            result.score += graphBoost(entry.distance);
+            addGraphEvidence(result, relFile, entry);
+        }
+    }
+}
+function addGraphEvidence(result, relFile, entry) {
+    addReason(result, `graph neighborhood match at depth ${entry.distance}`);
+    addEvidence(result, {
+        source: "graph",
+        label: entry.relation,
+        file: relFile,
+    });
+}
+function graphBoost(distance) {
+    return Math.max(2, 14 - distance * 3);
+}
+function resolveAnchorFiles(snapshot, from) {
+    const anchor = new Set();
+    const directFile = resolveAgentSnapshotFile(snapshot, from);
+    if (directFile)
+        anchor.add(directFile);
+    const fileLikeHandle = parseAgentFileHandle(from) ?? parseAgentChunkHandle(from) ?? parseAgentGraphHandle(from);
+    if (fileLikeHandle) {
+        const handleFile = resolveAgentSnapshotFile(snapshot, fileLikeHandle.file);
+        if (handleFile)
+            anchor.add(handleFile);
+    }
+    if (from.startsWith("symbol:")) {
+        const symbolHandle = parseAgentSymbolHandle(from);
+        const symbolFile = symbolHandle ? resolveAgentSnapshotFile(snapshot, symbolHandle.file) : null;
+        if (symbolFile) {
+            anchor.add(symbolFile);
+        }
+        else {
+            const symbol = snapshot.symbolGraph.nodes.get(from.slice("symbol:".length));
+            if (symbol)
+                anchor.add(normalizePath(symbol.file));
+        }
+    }
+    if (from.startsWith("sql:")) {
+        const sqlHandle = parseAgentSqlHandle(from);
+        if (sqlHandle) {
+            const file = resolveAgentSnapshotFile(snapshot, sqlHandle.file);
+            if (file)
+                anchor.add(file);
+        }
+    }
+    for (const node of snapshot.symbolGraph.nodes.values()) {
+        if (node.name === from) {
+            anchor.add(normalizePath(node.file));
+        }
+    }
+    return anchor;
+}
+function collectReachableFiles(fileNeighborIndex, anchorFiles, depth) {
+    const reachable = new Map();
+    const queue = [...anchorFiles].map((file) => ({
+        file,
+        distance: 0,
+        relation: "anchor",
+    }));
+    while (queue.length) {
+        const current = queue.shift();
+        const existing = reachable.get(current.file);
+        if (existing && existing.distance <= current.distance)
+            continue;
+        reachable.set(current.file, current);
+        if (current.distance >= depth)
+            continue;
+        for (const neighbor of fileNeighborIndex.get(current.file) ?? []) {
+            queue.push({
+                file: neighbor.file,
+                distance: current.distance + 1,
+                relation: neighbor.relation,
+            });
+        }
+    }
+    return reachable;
+}
+async function readSearchableFile(file) {
+    try {
+        const stat = await fs.stat(file);
+        if (stat.size > MAX_TEXT_BYTES)
+            return null;
+        return await fs.readFile(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function buildTextChunks(file, text) {
+    return buildQueryTextChunks(file, text);
+}
+function makeSnippet(text, query) {
+    const lines = text.split(/\r?\n/);
+    const matchIndex = lines.findIndex((line) => matchTokenScore(line, query).score > 0);
+    const index = matchIndex >= 0 ? matchIndex : 0;
+    return lines
+        .slice(Math.max(0, index - 1), Math.min(lines.length, index + 2))
+        .join("\n")
+        .trim();
+}
+function upsertResult(resultMap, base) {
+    const existing = resultMap.get(base.handle);
+    if (existing)
+        return existing;
+    const result = {
+        handle: base.handle,
+        kind: base.kind,
+        label: base.label,
+        file: base.file,
+        ...(base.range ? { range: base.range } : {}),
+        provenance: base.provenance,
+        score: 0,
+        rankReasons: new Set(),
+        evidence: [],
+        neighbors: new Map(),
+        followUps: new Map(),
+        matchedRankTerms: new Set(),
+    };
+    resultMap.set(base.handle, result);
+    return result;
+}
+function addMatchedRankTerms(result, ...matches) {
+    for (const match of matches) {
+        for (const term of match.matched)
+            result.matchedRankTerms.add(term);
+    }
+}
+function addReason(result, reason) {
+    if (reason.trim())
+        result.rankReasons.add(reason);
+}
+function addEvidence(result, evidence) {
+    if (result.evidence.some((entry) => entry.source === evidence.source &&
+        entry.label === evidence.label &&
+        entry.file === evidence.file &&
+        entry.line === evidence.line)) {
+        return;
+    }
+    result.evidence.push(evidence);
+}
+function buildSymbolNeighborIndex(snapshot) {
+    const neighborsBySymbolId = new Map();
+    const addNeighbor = (sourceId, neighbor) => {
+        const neighbors = neighborsBySymbolId.get(sourceId);
+        if (neighbors) {
+            neighbors.push(neighbor);
+            return;
+        }
+        neighborsBySymbolId.set(sourceId, [neighbor]);
+    };
+    for (const edge of snapshot.symbolGraph.edges) {
+        const from = snapshot.symbolGraph.nodes.get(edge.from);
+        const to = snapshot.symbolGraph.nodes.get(edge.to);
+        if (!from || !to)
+            continue;
+        const forwardRelation = edge.label ?? "uses";
+        addNeighbor(from.id, { key: "uses", relation: forwardRelation, target: to });
+        addNeighbor(to.id, {
+            key: "referenced_by",
+            relation: `incoming:${forwardRelation}`,
+            target: from,
+        });
+    }
+    return neighborsBySymbolId;
+}
+function buildFileNeighborIndex(snapshot) {
+    const neighborsByFile = new Map();
+    const addNeighbor = (file, neighbor) => {
+        const normalizedFile = normalizePath(file);
+        const neighbors = neighborsByFile.get(normalizedFile);
+        if (neighbors) {
+            neighbors.push(neighbor);
+            return;
+        }
+        neighborsByFile.set(normalizedFile, [neighbor]);
+    };
+    for (const edge of snapshot.fileGraph.edges) {
+        if (edge.to.type !== "file")
+            continue;
+        const from = normalizePath(edge.from);
+        const to = normalizePath(edge.to.path);
+        addNeighbor(from, { relation: "imports", file: to });
+        addNeighbor(to, { relation: "imported_by", file: from });
+    }
+    return neighborsByFile;
+}
+function addSymbolNeighbors(snapshot, result, neighbors) {
+    for (const neighbor of neighbors) {
+        const relFile = normalizeAgentFilePath(snapshot.root, neighbor.target.file);
+        const key = `${neighbor.key}:${neighbor.target.id}`;
+        result.neighbors.set(key, {
+            relation: neighbor.relation,
+            target: neighbor.target.name,
+            file: relFile,
+        });
+    }
+}
+function addFileNeighbors(snapshot, result, neighbors) {
+    for (const neighbor of neighbors) {
+        const relFile = normalizeAgentFilePath(snapshot.root, neighbor.file);
+        result.neighbors.set(`${neighbor.relation}:${relFile}`, {
+            relation: neighbor.relation,
+            target: relFile,
+            file: relFile,
+        });
+    }
+}
+function addSymbolFollowUps(result, relFile, def) {
+    addFollowUp(result, toolFollowUp("get_symbol", { handle: result.handle }));
+    if (def) {
+        for (const followUp of collectDefinitionFollowUps(relFile, def.range.start.line, def.range.start.column)) {
+            addFollowUp(result, followUp);
+        }
+    }
+    addFileFollowUps(result, relFile);
+}
+function addFileFollowUps(result, relFile) {
+    for (const followUp of collectCommonFileFollowUps(relFile)) {
+        addFollowUp(result, followUp);
+    }
+}
+function addFollowUp(result, followUp) {
+    result.followUps.set(JSON.stringify(followUp), followUp);
+}
+function compareResults(left, right) {
+    const scoreDelta = right.score - left.score;
+    if (scoreDelta !== 0)
+        return scoreDelta;
+    const capabilityDelta = capabilityRank(left.provenance.capability) - capabilityRank(right.provenance.capability);
+    if (capabilityDelta !== 0)
+        return capabilityDelta;
+    const coverageDelta = right.matchedRankTerms.size - left.matchedRankTerms.size;
+    if (coverageDelta !== 0)
+        return coverageDelta;
+    const labelDelta = compareAscii(left.label, right.label);
+    if (labelDelta !== 0)
+        return labelDelta;
+    const fileDelta = compareAscii(left.file, right.file);
+    if (fileDelta !== 0)
+        return fileDelta;
+    return compareAscii(left.handle, right.handle);
+}
+function capabilityRank(capability) {
+    if (capability === "semantic")
+        return 0;
+    if (capability === "graph")
+        return 1;
+    return 2;
+}
+function compareAscii(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+function selectTopResults(resultMap, limit) {
+    const top = [];
+    let totalCandidates = 0;
+    for (const result of resultMap.values()) {
+        if (result.score <= 0)
+            continue;
+        totalCandidates += 1;
+        insertTopResult(top, result, limit);
+    }
+    return {
+        items: top,
+        totalCandidates,
+        omitted: Math.max(0, totalCandidates - top.length),
+    };
+}
+function insertTopResult(top, result, limit) {
+    if (limit <= 0)
+        return;
+    let insertIndex = top.length;
+    while (insertIndex > 0 && compareResults(result, top[insertIndex - 1]) < 0) {
+        insertIndex -= 1;
+    }
+    if (insertIndex >= limit)
+        return;
+    top.splice(insertIndex, 0, result);
+    if (top.length > limit)
+        top.pop();
+}
+function finalizeResult(result) {
+    const rankReasons = [...result.rankReasons].sort();
+    const evidence = result.evidence.sort((left, right) => {
+        const sourceDelta = left.source.localeCompare(right.source);
+        if (sourceDelta !== 0)
+            return sourceDelta;
+        return left.label.localeCompare(right.label);
+    });
+    const neighbors = [...result.neighbors.values()].sort((left, right) => {
+        const relationDelta = left.relation.localeCompare(right.relation);
+        if (relationDelta !== 0)
+            return relationDelta;
+        return left.target.localeCompare(right.target);
+    });
+    const followUps = [...result.followUps.values()].sort((left, right) => formatAgentFollowUpAsCli(left).localeCompare(formatAgentFollowUpAsCli(right)));
+    const boundedRankReasons = boundAgentList(rankReasons, AGENT_SEARCH_RANK_REASONS_PER_RESULT_LIMIT);
+    const boundedEvidence = boundAgentList(evidence, AGENT_SEARCH_EVIDENCE_PER_RESULT_LIMIT);
+    const boundedNeighbors = boundAgentList(neighbors, AGENT_SEARCH_NEIGHBORS_PER_RESULT_LIMIT);
+    const boundedFollowUps = boundAgentList(followUps, AGENT_SEARCH_FOLLOWUPS_PER_RESULT_LIMIT);
+    return {
+        handle: result.handle,
+        kind: result.kind,
+        label: result.label,
+        file: result.file,
+        ...(result.range ? { range: result.range } : {}),
+        score: Number(result.score.toFixed(3)),
+        provenance: result.provenance,
+        rankReasons: boundedRankReasons.items,
+        evidence: boundedEvidence.items,
+        neighbors: boundedNeighbors.items,
+        followUps: boundedFollowUps.items,
+        omittedCounts: {
+            rankReasons: boundedRankReasons.omitted,
+            evidence: boundedEvidence.omitted,
+            neighbors: boundedNeighbors.omitted,
+            followUps: boundedFollowUps.omitted,
+        },
+    };
+}
+function createSearchProvenance(relFile, capability, confidence, analysis) {
+    return {
+        surface: detectSearchSurface(relFile),
+        capability,
+        analysisMode: analysis.mode,
+        backend: analysis.backend,
+        confidence,
+    };
+}
+function detectSearchSurface(relFile) {
+    return detectQueryIndexSurface(relFile);
+}
+//# sourceMappingURL=search.js.map