scai 0.1.178 → 1.0.0

package/dist/agent/read/summarizeReadEvidence.js

@@ -0,0 +1,733 @@
+/**
+ * Builds grounded triage and fallback read evidence for the modular agent runtime.
+ *
+ * Why this file exists:
+ * - file-aware extraction should stay separate from read execution and loop control
+ * - cheap triage reads should preserve more real code shape than single matching lines
+ * - deterministic fallback data should use the same evidence shape as model-backed reads
+ */
+import fs from "fs";
+import path from "path";
+import { computeContentFingerprint, computeQueryFingerprint } from "../../utils/fileEvidenceCache.js";
+import { nowLocalIso } from "../../utils/time.js";
+const MAX_QUERY_TERMS = 6;
+const MAX_SUMMARY_CHARS = 240;
+const MAX_KEY_SYMBOLS = 8;
+const MAX_SNIPPETS = 4;
+const MAX_EXCERPTS = 3;
+const MAX_EXCERPT_LINES = 40;
+const BLOCK_SEARCH_RADIUS = 8;
+const MAX_FULL_READ_BLOCKS = 4;
+export function nowIso() {
+    return nowLocalIso();
+}
+export function uniqueStrings(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        const trimmed = String(value ?? "").trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}
+export function dedupePaths(paths) {
+    return uniqueStrings(paths.map((filePath) => path.normalize(filePath)));
+}
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Treats real folders as folders when they exist.
+ * Example: "cli/src/agents" -> true, "agentLoop.ts" -> false.
+ */
+export function looksLikeDirectoryTarget(target, executionPath) {
+    const absolute = path.isAbsolute(target) ? target : path.join(executionPath, target);
+    try {
+        return fs.existsSync(absolute) && fs.statSync(absolute).isDirectory();
+    }
+    catch {
+        return !path.extname(target);
+    }
+}
+function extractQueryTerms(query) {
+    return uniqueStrings(query
+        .split(/[^A-Za-z0-9_./-]+/)
+        .map((part) => part.trim().toLowerCase())
+        .filter((part) => part.length >= 4 && !part.includes("/"))).slice(0, MAX_QUERY_TERMS);
+}
+function firstNonEmptyLine(lines) {
+    return lines.find((line) => line.trim().length > 0)?.trim() ?? "[empty file]";
+}
+/**
+ * Pulls the first doc block near the top of the file into one compact summary line.
+ * Example: a top doc comment becomes one plain summary string.
+ */
+function extractTopCommentBlock(code) {
+    const match = code.match(/^\s*\/\*\*([\s\S]*?)\*\//);
+    if (!match)
+        return undefined;
+    const text = match[1]
+        .split("\n")
+        .map((line) => line.replace(/^\s*\*\s?/, "").trim())
+        .filter(Boolean)
+        .join(" ")
+        .trim();
+    return text.length > 0 ? text.slice(0, MAX_SUMMARY_CHARS) : undefined;
+}
+/**
+ * Extracts readable exported contract names from common TS declarations.
+ * Example: an exported interface yields its symbol name.
+ */
+function extractExportNames(code) {
+    const matches = Array.from(code.matchAll(/^\s*export\s+(?:default\s+)?(?:async\s+)?(?:type|interface|class|function|const|let|var|enum)\s+([A-Za-z0-9_$]+)/gm));
+    return uniqueStrings(matches.map((match) => match[1] ?? "").filter(Boolean)).slice(0, MAX_KEY_SYMBOLS);
+}
+/**
+ * Extracts local declaration names from one file.
+ * Example: `function buildFinalAnswer()` -> `buildFinalAnswer`.
+ */
+function extractLocalDeclarationNames(code) {
+    const matches = Array.from(code.matchAll(/^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|const|let|var|enum)\s+([A-Za-z0-9_$]+)/gm));
+    return uniqueStrings(matches.map((match) => match[1] ?? "").filter(Boolean)).slice(0, 20);
+}
+function isCommentOnlyLine(line) {
+    const trimmed = line.trim();
+    return trimmed.startsWith("//") || trimmed === "/**" || trimmed === "*/" || trimmed.startsWith("*");
+}
+function isImportLine(line) {
+    const trimmed = line.trim();
+    return /^import\s+(?:type\s+)?/.test(trimmed) || /^const\s+[A-Za-z0-9_$]+\s*=\s*require\(/.test(trimmed);
+}
+function isBridgeLine(line) {
+    return /^export\s+(?:\*|\{[\s\S]+?\})\s+from\s+["'][^"']+["'];?$/.test(line.trim());
+}
+function isTypeOnlyLine(line) {
+    return /^(?:export\s+)?type\s+[A-Za-z0-9_$]+\s*=/.test(line.trim());
+}
+function isNoiseLine(line) {
+    const trimmed = line.trim();
+    return (trimmed.length === 0 ||
+        /^\/\/\s*File:/.test(trimmed) ||
+        /^[{}[\]]\s*;?$/.test(trimmed));
+}
+function scoreSnippetLine(line, queryTerms, keySymbols) {
+    const trimmed = line.trim();
+    const lowered = trimmed.toLowerCase();
+    const matchedTermCount = queryTerms.filter((term) => lowered.includes(term)).length
+        + keySymbols.filter((symbol) => lowered.includes(symbol.toLowerCase())).length;
+    let kind = "other";
+    let score = matchedTermCount * 25;
+    if (isNoiseLine(trimmed)) {
+        kind = "noise";
+        score -= 90;
+    }
+    else if (isCommentOnlyLine(trimmed)) {
+        kind = "comment";
+        score -= 45;
+    }
+    else if (isImportLine(trimmed)) {
+        kind = "import";
+        score -= 35;
+    }
+    else if (isBridgeLine(trimmed)) {
+        kind = "bridge";
+        score -= 8;
+    }
+    else if (isTypeOnlyLine(trimmed)) {
+        kind = "type";
+        score -= 16;
+    }
+    else if (/\.(?:command|action)\s*\(/.test(trimmed)) {
+        kind = "command-registration";
+        score += 60;
+    }
+    else if (/\bprepare\(.+\)\s*\.\s*(?:all|get|run)\(/.test(trimmed) || /\.prepare\(/.test(trimmed)) {
+        kind = "query-execution";
+        score += 55;
+    }
+    else if (/\b(?:export\s+)?(?:async\s+)?function\b/.test(trimmed)) {
+        kind = "function";
+        score += 50;
+    }
+    else if (/\bclass\s+[A-Za-z0-9_$]+/.test(trimmed)) {
+        kind = "class";
+        score += 45;
+    }
+    else if (/\bprocess\.env\b/.test(trimmed) || /^[A-Za-z0-9_$"'`.-]+\s*:\s*(?:["'`[{]|true\b|false\b|null\b|\d)/.test(trimmed)) {
+        kind = "config";
+        score += 35;
+    }
+    else if (/\b(?:export\s+)?(?:const|let|var)\s+[A-Za-z0-9_$]+\s*=/.test(trimmed)) {
+        kind = "object";
+        score += 28;
+    }
+    else {
+        score += 8;
+    }
+    if (trimmed.length > 140) {
+        score -= 6;
+    }
+    return {
+        index: 0,
+        line,
+        score,
+        matchedTermCount,
+        kind,
+    };
+}
+function isImplementationCandidateKind(kind) {
+    return kind === "command-registration"
+        || kind === "function"
+        || kind === "class"
+        || kind === "config"
+        || kind === "query-execution"
+        || kind === "object";
+}
+function classifyGroundingDepth(code) {
+    const codeLines = code
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .filter((line) => !isCommentOnlyLine(line));
+    if (codeLines.length === 0) {
+        return "wrapper";
+    }
+    const realBodyCount = codeLines.filter((line) => /\.(?:command|action)\s*\(/.test(line) ||
+        /\b(?:export\s+)?(?:async\s+)?function\b/.test(line) ||
+        /\bclass\s+[A-Za-z0-9_$]+/.test(line) ||
+        /\b(?:export\s+)?(?:const|let|var)\s+[A-Za-z0-9_$]+\s*=/.test(line) ||
+        /\bprocess\.env\b/.test(line)).length;
+    const bridgeCount = codeLines.filter((line) => isBridgeLine(line)).length;
+    const importishCount = codeLines.filter((line) => isImportLine(line) || isTypeOnlyLine(line)).length;
+    if (realBodyCount === 0 && bridgeCount > 0 && bridgeCount + importishCount === codeLines.length) {
+        return "wrapper";
+    }
+    if (realBodyCount > 0 && bridgeCount > 0) {
+        return "mixed";
+    }
+    return "direct";
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+function pickGroundingSnippets(lines, query, keySymbols, groundingDepth) {
+    const terms = extractQueryTerms(query);
+    const candidates = lines
+        .map((line, index) => {
+        const candidate = scoreSnippetLine(line, terms, keySymbols);
+        return { ...candidate, index };
+    })
+        .filter((candidate) => candidate.line.trim().length > 0);
+    if (groundingDepth === "wrapper") {
+        const bridge = candidates
+            .filter((candidate) => candidate.kind === "bridge")
+            .sort((left, right) => right.score - left.score || left.index - right.index)[0];
+        if (bridge) {
+            return [`${bridge.index + 1}: ${bridge.line.trim()}`];
+        }
+    }
+    const matchingCandidates = candidates
+        .filter((candidate) => candidate.matchedTermCount > 0)
+        .sort((left, right) => right.score - left.score || right.matchedTermCount - left.matchedTermCount || left.index - right.index);
+    const fallbackCandidates = candidates
+        .filter((candidate) => candidate.kind !== "noise")
+        .sort((left, right) => right.score - left.score || left.index - right.index);
+    const selected = uniqueStrings([...matchingCandidates, ...fallbackCandidates]
+        .filter((candidate) => candidate.score > -10)
+        .slice(0, MAX_SNIPPETS)
+        .map((candidate) => `${candidate.index + 1}: ${candidate.line.trim()}`));
+    if (selected.length > 0) {
+        return selected;
+    }
+    return lines
+        .map((line, index) => ({ line, index }))
+        .filter(({ line }) => line.trim().length > 0)
+        .slice(0, 1)
+        .map(({ line, index }) => `${index + 1}: ${line.trim()}`);
+}
+function findMatchingLineIndexes(lines, query, keySymbols) {
+    const terms = extractQueryTerms(query);
+    const symbolTerms = keySymbols.map((symbol) => symbol.toLowerCase());
+    const indexes = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const lowered = lines[index].toLowerCase();
+        if (terms.some((term) => lowered.includes(term)) || symbolTerms.some((term) => lowered.includes(term))) {
+            indexes.push(index);
+        }
+    }
+    return indexes;
+}
+function trimTrailingBlankLines(lines) {
+    let end = lines.length;
+    while (end > 0 && lines[end - 1].trim().length === 0) {
+        end -= 1;
+    }
+    return lines.slice(0, end);
+}
+function resolveBlockStart(lines, seedIndex) {
+    const seedLine = lines[seedIndex]?.trim() ?? "";
+    if (seedLine.startsWith("/**") || seedLine.startsWith("/*") || seedLine.startsWith("*")) {
+        for (let cursor = seedIndex; cursor >= Math.max(0, seedIndex - BLOCK_SEARCH_RADIUS); cursor -= 1) {
+            const line = lines[cursor].trim();
+            if (line.startsWith("/**") || line.startsWith("/*")) {
+                return cursor;
+            }
+        }
+    }
+    for (let cursor = seedIndex; cursor >= Math.max(0, seedIndex - BLOCK_SEARCH_RADIUS); cursor -= 1) {
+        const line = lines[cursor];
+        if (/^\s*(export\s+)?(async\s+)?(function|class|interface|type|enum)\b/.test(line)) {
+            return cursor;
+        }
+        if (/^\s*(export\s+)?(const|let|var)\s+[A-Za-z0-9_$]+\s*=/.test(line)) {
+            return cursor;
+        }
+        if (/\.(?:command|action)\s*\(/.test(line)) {
+            return cursor;
+        }
+        if (/^\s*[A-Za-z0-9_$"'`.-]+\s*:\s*(?:["'`[{]|true\b|false\b|null\b|\d)/.test(line)) {
+            return cursor;
+        }
+    }
+    return seedIndex;
+}
+function resolveBlockEnd(lines, startIndex) {
+    const startLine = lines[startIndex]?.trim() ?? "";
+    if (startLine.startsWith("/**") || startLine.startsWith("/*")) {
+        for (let cursor = startIndex; cursor < Math.min(lines.length, startIndex + MAX_EXCERPT_LINES); cursor += 1) {
+            if (lines[cursor].trim().endsWith("*/")) {
+                return cursor;
+            }
+        }
+    }
+    let balance = 0;
+    let opened = false;
+    for (let cursor = startIndex; cursor < lines.length; cursor += 1) {
+        const line = lines[cursor];
+        if (cursor > startIndex && /\.(?:command|action)\s*\(/.test(lines[startIndex]) && !/\.(?:command|action)\s*\(/.test(line) && line.trim().length === 0) {
+            return cursor - 1;
+        }
+        for (const char of line) {
+            if (char === "{") {
+                balance += 1;
+                opened = true;
+            }
+            else if (char === "}") {
+                balance -= 1;
+            }
+        }
+        if (opened && balance <= 0) {
+            return cursor;
+        }
+        if (!opened && /;\s*$/.test(line.trim())) {
+            return cursor;
+        }
+        if (cursor - startIndex >= MAX_EXCERPT_LINES - 1) {
+            return cursor;
+        }
+    }
+    return Math.min(lines.length - 1, startIndex + MAX_EXCERPT_LINES - 1);
+}
+function extractSymbolsFromHeader(headerLine, knownSymbols) {
+    const symbols = new Set();
+    const declarationMatch = headerLine.match(/\b(?:function|class|interface|type|enum|const|let|var)\s+([A-Za-z0-9_$]+)/);
+    if (declarationMatch?.[1]) {
+        symbols.add(declarationMatch[1]);
+    }
+    for (const symbol of knownSymbols) {
+        if (headerLine.includes(symbol)) {
+            symbols.add(symbol);
+        }
+    }
+    return Array.from(symbols);
+}
+function isConceptExcerpt(excerpt) {
+    const description = excerpt.description.toLowerCase();
+    const code = excerpt.code.trim();
+    return description.includes("overview")
+        || description.includes("responsibilities")
+        || description.includes("boundary")
+        || /^\/\*\*/.test(code)
+        || /^\/\*/.test(code);
+}
+function isImplementationExcerpt(excerpt) {
+    const description = excerpt.description.toLowerCase();
+    const code = excerpt.code;
+    return description.startsWith("implementation block")
+        || description.includes("query execution")
+        || description.includes("command registration")
+        || /\b(?:export\s+)?(?:async\s+)?function\b/.test(code)
+        || /\bclass\s+[A-Za-z0-9_$]+/.test(code)
+        || /\b(?:export\s+)?(?:const|let|var)\s+[A-Za-z0-9_$]+\s*=/.test(code)
+        || /\.command\(/.test(code)
+        || /\.prepare\(/.test(code);
+}
+function buildExcerptFromSeed(lines, seedIndex, keySymbols) {
+    const startIndex = resolveBlockStart(lines, seedIndex);
+    const endIndex = resolveBlockEnd(lines, startIndex);
+    const blockLines = trimTrailingBlankLines(lines.slice(startIndex, endIndex + 1));
+    if (blockLines.length === 0) {
+        return undefined;
+    }
+    const headerLine = blockLines[0];
+    const symbols = extractSymbolsFromHeader(headerLine, keySymbols);
+    return {
+        description: buildExcerptDescription(symbols, headerLine, blockLines),
+        startLine: startIndex + 1,
+        endLine: startIndex + blockLines.length,
+        ...(symbols.length > 0 ? { symbols } : {}),
+        code: blockLines.join("\n"),
+    };
+}
+function isExplanationLikeQuery(query) {
+    return /\b(explain|summary|summarize|architecture|module|how|purpose|responsibilit)/i.test(query);
+}
+function prioritizeExcerptsForAnswer(excerpts, query) {
+    if (excerpts.length <= 1) {
+        return excerpts;
+    }
+    if (!isExplanationLikeQuery(query)) {
+        return excerpts;
+    }
+    const bestConcept = excerpts.find((excerpt) => isConceptExcerpt(excerpt));
+    const bestImplementation = excerpts.find((excerpt) => isImplementationExcerpt(excerpt));
+    const ordered = [];
+    if (bestConcept) {
+        ordered.push(bestConcept);
+    }
+    if (bestImplementation && !ordered.some((excerpt) => excerpt.startLine === bestImplementation.startLine && excerpt.endLine === bestImplementation.endLine)) {
+        ordered.push(bestImplementation);
+    }
+    for (const excerpt of excerpts) {
+        if (!ordered.some((entry) => entry.startLine === excerpt.startLine && entry.endLine === excerpt.endLine)) {
+            ordered.push(excerpt);
+        }
+    }
+    return ordered.slice(0, MAX_EXCERPTS);
+}
+function buildExcerptDescription(symbols, startLine, blockLines) {
+    const blockText = blockLines.join("\n");
+    if (/^\s*\/\*\*/.test(startLine) && /\b(?:responsibilit|overview|final answer module|phase boundary)\b/i.test(blockText)) {
+        return "Module overview and key responsibilities";
+    }
+    if (/^\s*\/\*/.test(startLine) && /\b(?:boundary|grounding rule)\b/i.test(blockText)) {
+        return "Boundary conditions and grounding rules";
+    }
+    const commandLiteral = blockText.match(/\.command\(\s*["'`]([^"'`]+)["'`]\s*\)/)?.[1];
+    if (commandLiteral) {
+        return `CLI command registration for ${commandLiteral}`;
+    }
+    if (/prepare\([^)]+\)\s*\.\s*(?:all|get|run)\(/.test(blockText) || /\.prepare\([^)]+\)/.test(blockText)) {
+        const symbol = symbols[0];
+        return symbol ? `SQLite query execution in ${symbol}` : "SQLite query execution block";
+    }
+    const bridgeTarget = startLine.match(/^export\s+(?:\*|\{[\s\S]+?\})\s+from\s+["'][^"']*\/([^/"']+)\.[^/"']+["'];?$/)?.[1];
+    if (bridgeTarget) {
+        return `Legacy bridge re-export to ${bridgeTarget}`;
+    }
+    if (symbols.length > 0 && /\bcreateProgram\b/.test(blockText)) {
+        return "Program factory wiring for top-level CLI commands";
+    }
+    if (symbols.length > 0 && /\bdefineConfig\b/.test(blockText)) {
+        return `Configuration block for ${symbols[0]}`;
+    }
+    if (symbols.length > 0) {
+        return `Implementation block for ${symbols.slice(0, 3).join(", ")}`;
+    }
+    if (/^\s*export\b/.test(startLine)) {
+        return "Relevant exported declaration block";
+    }
+    return "Relevant code block near the strongest query match";
+}
+function buildBlockExcerpts(code, query, keySymbols) {
+    const lines = code.split("\n");
+    const queryTerms = extractQueryTerms(query);
+    const matchIndexes = findMatchingLineIndexes(lines, query, keySymbols);
+    const fallbackBlockSeeds = lines
+        .map((line, index) => ({ ...scoreSnippetLine(line, queryTerms, keySymbols), index }))
+        .filter((candidate) => candidate.kind !== "noise" && candidate.kind !== "comment" && candidate.kind !== "import")
+        .sort((left, right) => right.score - left.score || left.index - right.index)
+        .slice(0, MAX_FULL_READ_BLOCKS)
+        .map((candidate) => candidate.index);
+    const seedIndexes = uniqueStrings((matchIndexes.length > 0 ? matchIndexes : keySymbols.map((symbol) => {
+        const index = lines.findIndex((line) => line.includes(symbol));
+        return index >= 0 ? String(index) : "";
+    }))
+        .map((value) => String(value))
+        .filter((value) => value.length > 0)).map((value) => Number(value)).filter((value) => Number.isInteger(value) && value >= 0);
+    const orderedSeedIndexes = uniqueStrings([
+        ...seedIndexes.map(String),
+        ...fallbackBlockSeeds.map(String),
+    ]).map(Number);
+    const excerpts = [];
+    const seenRanges = new Set();
+    for (const seedIndex of orderedSeedIndexes) {
+        const excerpt = buildExcerptFromSeed(lines, seedIndex, keySymbols);
+        if (!excerpt) {
+            continue;
+        }
+        const rangeKey = `${excerpt.startLine ?? 0}:${excerpt.endLine ?? 0}`;
+        if (seenRanges.has(rangeKey)) {
+            continue;
+        }
+        seenRanges.add(rangeKey);
+        excerpts.push(excerpt);
+        if (excerpts.length >= MAX_EXCERPTS) {
+            break;
+        }
+    }
+    if (isExplanationLikeQuery(query) && excerpts.some((excerpt) => isConceptExcerpt(excerpt)) && !excerpts.some((excerpt) => isImplementationExcerpt(excerpt))) {
+        const implementationSeed = lines
+            .map((line, index) => ({ ...scoreSnippetLine(line, queryTerms, keySymbols), index }))
+            .filter((candidate) => isImplementationCandidateKind(candidate.kind))
+            .sort((left, right) => right.score - left.score || left.index - right.index)[0];
+        if (implementationSeed) {
+            const implementationExcerpt = buildExcerptFromSeed(lines, implementationSeed.index, keySymbols);
+            if (implementationExcerpt) {
+                const exists = excerpts.some((excerpt) => excerpt.startLine === implementationExcerpt.startLine && excerpt.endLine === implementationExcerpt.endLine);
+                if (!exists) {
+                    excerpts.push(implementationExcerpt);
+                }
+            }
+        }
+    }
+    return prioritizeExcerptsForAnswer(excerpts, query);
+}
+function determineRole(hardTarget, excerpts, matchedTerms, keySymbols) {
+    if (hardTarget) {
+        return "primary";
+    }
+    if (excerpts.length >= 2 || matchedTerms.length >= 2) {
+        return "primary";
+    }
+    if (excerpts.length > 0 || keySymbols.length > 0) {
+        return "supporting";
+    }
+    return "contextual";
+}
+function buildRelevantContext(code, query, summary, keySymbols, relevanceExplanation) {
+    const terms = extractQueryTerms(query);
+    const context = [];
+    const docBlock = extractTopCommentBlock(code);
+    if (docBlock) {
+        context.push({
+            kind: "purpose",
+            text: docBlock.slice(0, MAX_SUMMARY_CHARS),
+        });
+    }
+    else if (summary.trim().length > 0) {
+        context.push({
+            kind: "purpose",
+            text: summary.slice(0, MAX_SUMMARY_CHARS),
+        });
+    }
+    const matchedTerms = terms.filter((term) => code.toLowerCase().includes(term));
+    if (matchedTerms.length > 0) {
+        context.push({
+            kind: "query-match",
+            text: `Matches query terms: ${matchedTerms.slice(0, 4).join(", ")}.`,
+        });
+    }
+    else if (relevanceExplanation.trim().length > 0) {
+        context.push({
+            kind: "query-match",
+            text: relevanceExplanation.slice(0, MAX_SUMMARY_CHARS),
+        });
+    }
+    if (keySymbols.length > 0) {
+        context.push({
+            kind: "dependency",
+            text: `Defines exported symbols: ${keySymbols.slice(0, 4).join(", ")}.`,
+        });
+    }
+    return context.slice(0, 3);
+}
+function buildRelevanceExplanation(docBlock, matchedTerms, keySymbols, excerpts, role) {
+    const reasons = [];
+    if (docBlock) {
+        reasons.push(`The top file comment describes ${docBlock.slice(0, 90)}.`);
+    }
+    if (matchedTerms.length > 0) {
+        reasons.push(`It directly matches query terms: ${matchedTerms.slice(0, 4).join(", ")}.`);
+    }
+    if (keySymbols.length > 0) {
+        reasons.push(`It exports relevant symbols: ${keySymbols.slice(0, 4).join(", ")}.`);
+    }
+    if (excerpts.length > 0) {
+        const excerpt = excerpts[0];
+        const span = excerpt.startLine && excerpt.endLine
+            ? `lines ${excerpt.startLine}-${excerpt.endLine}`
+            : "the extracted block";
+        reasons.push(`The strongest grounded block is in ${span}.`);
+    }
+    if (reasons.length === 0) {
+        reasons.push(`This file looks ${role ?? "contextual"} to the query from its visible declarations and path shape.`);
+    }
+    return reasons.join(" ");
+}
+function collectCommandFacts(excerpts) {
+    const facts = new Set();
+    for (const excerpt of excerpts) {
+        const code = String(excerpt.code ?? "");
+        const commandPattern = /\.command\(\s*["'`]([^"'`]+)["'`]\s*\)(?:[\s\S]{0,240}?)\.description\(\s*["'`]([^"'`]+)["'`]\s*\)/g;
+        let describedMatch;
+        while ((describedMatch = commandPattern.exec(code)) !== null) {
+            facts.add(`CLI command: ${describedMatch[1]}`);
+            facts.add(`The CLI registers "${describedMatch[1]}" to ${describedMatch[2].replace(/\.$/, "").toLowerCase()}.`);
+        }
+        const bareCommandPattern = /\.command\(\s*["'`]([^"'`]+)["'`]\s*\)/g;
+        let bareMatch;
+        while ((bareMatch = bareCommandPattern.exec(code)) !== null) {
+            facts.add(`CLI command: ${bareMatch[1]}`);
+        }
+    }
+    return Array.from(facts).slice(0, 6);
+}
+function collectExactTargetPhrases(code, explicitTargets) {
+    const phrases = [];
+    for (const target of explicitTargets) {
+        const trimmed = String(target ?? "").trim();
+        if (!trimmed) {
+            continue;
+        }
+        const match = code.match(new RegExp(escapeRegex(trimmed), "i"));
+        if (match?.[0]) {
+            phrases.push(match[0]);
+        }
+    }
+    return uniqueStrings(phrases).slice(0, 6);
+}
+function pickStrongestConceptExcerpt(excerpts) {
+    return excerpts.find((excerpt) => isConceptExcerpt(excerpt));
+}
+function pickStrongestImplementationExcerpt(excerpts) {
+    return excerpts.find((excerpt) => isImplementationExcerpt(excerpt));
+}
+function buildStrengthSignals(code, explicitTargets, excerpts) {
+    const strongestConceptExcerpt = pickStrongestConceptExcerpt(excerpts);
+    const strongestImplementationExcerpt = pickStrongestImplementationExcerpt(excerpts);
+    const implementationSymbols = uniqueStrings([
+        ...(strongestImplementationExcerpt?.symbols ?? []),
+        ...extractLocalDeclarationNames(code),
+    ]).slice(0, 8);
+    return {
+        exactTargetPhrases: collectExactTargetPhrases(code, explicitTargets),
+        implementationSymbols,
+        directAnswerFacts: collectCommandFacts(excerpts),
+        ...(strongestConceptExcerpt ? {
+            strongestConceptExcerpt: {
+                description: strongestConceptExcerpt.description,
+                startLine: strongestConceptExcerpt.startLine,
+                endLine: strongestConceptExcerpt.endLine,
+                symbols: strongestConceptExcerpt.symbols,
+            },
+        } : {}),
+        ...(strongestImplementationExcerpt ? {
+            strongestImplementationExcerpt: {
+                description: strongestImplementationExcerpt.description,
+                startLine: strongestImplementationExcerpt.startLine,
+                endLine: strongestImplementationExcerpt.endLine,
+                symbols: strongestImplementationExcerpt.symbols,
+            },
+        } : {}),
+    };
+}
+function buildRisks(matchedTerms, excerpts, readMode) {
+    const risks = [];
+    if (matchedTerms.length === 0) {
+        risks.push("No direct query-term matches; relevance was inferred from declarations or nearby context.");
+    }
+    if (excerpts.length === 0) {
+        risks.push("No stable block excerpt was found; grounding relies on lighter line-level evidence.");
+    }
+    if (readMode === "triage") {
+        risks.push("This is a deterministic triage read, not a full model-backed file analysis.");
+    }
+    return risks.slice(0, 3);
+}
+function computeTriageScore(matchedTerms, keySymbols, excerpts, hardTarget) {
+    const raw = (hardTarget ? 0.35 : 0) + matchedTerms.length * 0.14 + keySymbols.length * 0.05 + excerpts.length * 0.18;
+    return clamp(Number(raw.toFixed(2)), 0, 1);
+}
+function buildDeterministicReadEvidence(filePath, code, query, options = {}) {
+    const readMode = options.readMode ?? "full";
+    const hardTarget = options.hardTarget === true;
+    const lines = code.split("\n");
+    const terms = extractQueryTerms(query);
+    const docBlock = extractTopCommentBlock(code);
+    const keySymbols = extractExportNames(code);
+    const groundingDepth = classifyGroundingDepth(code);
+    const snippets = pickGroundingSnippets(lines, query, keySymbols, groundingDepth);
+    const excerpts = buildBlockExcerpts(code, query, keySymbols);
+    const strengthSignals = buildStrengthSignals(code, options.explicitTargets ?? [], excerpts);
+    const summarySource = excerpts[0]?.description ?? docBlock ?? snippets[0] ?? firstNonEmptyLine(lines);
+    const matchedTerms = terms.filter((term) => code.toLowerCase().includes(term));
+    const role = determineRole(hardTarget, excerpts, matchedTerms, keySymbols);
+    const relevanceExplanation = buildRelevanceExplanation(docBlock, matchedTerms, keySymbols, excerpts, role);
+    const relevantContext = buildRelevantContext(code, query, summarySource, keySymbols, relevanceExplanation);
+    const triageScore = computeTriageScore(matchedTerms, keySymbols, excerpts, hardTarget);
+    const risks = buildRisks(matchedTerms, excerpts, readMode);
+    return {
+        filePath,
+        readMode,
+        summary: summarySource.slice(0, MAX_SUMMARY_CHARS),
+        snippets,
+        keySymbols,
+        matchedTerms,
+        relevanceExplanation,
+        role,
+        excerpts,
+        strengthSignals,
+        risks,
+        triageScore,
+        relevantContext,
+        contentFingerprint: computeContentFingerprint(code),
+        queryFingerprint: computeQueryFingerprint(query),
+        recordedAt: nowIso(),
+    };
+}
+/**
+ * Selects a compact, code-shaped prompt slice for full reads.
+ * Example: keep the top docblock plus the strongest command/config/function blocks.
+ */
+export function selectCodeForFullReadPrompt(code, query, maxChars) {
+    if (code.length <= maxChars) {
+        return code;
+    }
+    const keySymbols = extractExportNames(code);
+    const docBlockMatch = code.match(/^\s*\/\*\*[\s\S]*?\*\//)?.[0]?.trim();
+    const excerpts = buildBlockExcerpts(code, query, keySymbols).slice(0, MAX_FULL_READ_BLOCKS);
+    const parts = [];
+    if (docBlockMatch && docBlockMatch.length <= Math.floor(maxChars * 0.3)) {
+        parts.push(docBlockMatch);
+    }
+    for (const excerpt of excerpts) {
+        const block = `// ${excerpt.description}\n${excerpt.code.trim()}`;
+        if (parts.join("\n\n").length + block.length > maxChars) {
+            break;
+        }
+        parts.push(block);
+    }
+    const selected = parts.join("\n\n").trim();
+    if (selected.length > 0) {
+        return selected.length <= maxChars
+            ? selected
+            : `${selected.slice(0, maxChars - 40)}\n/* … file truncated for agent full read … */`;
+    }
+    const head = code.slice(0, Math.floor(maxChars * 0.6));
+    const tail = code.slice(-Math.floor(maxChars * 0.4));
+    return [head, "\n/* … file truncated for agent full read … */\n", tail].join("");
+}
+export function summarizeFileRead(filePath, code, query, options = {}) {
+    return buildDeterministicReadEvidence(filePath, code, query, options);
+}
+export function buildDeterministicFullReadFallback(filePath, code, query, options = {}) {
+    return buildDeterministicReadEvidence(filePath, code, query, {
+        ...options,
+        readMode: "full",
+    });
+}
+//# sourceMappingURL=summarizeReadEvidence.js.map