pi-supernova 0.5.0 → 0.7.0

package/src/context/snap.js

@@ -20,6 +20,8 @@ const TYPED_EXT = new Set([".ts", ".tsx", ".rs", ".go"]);
 
 const MAX_SEARCH_CHARS = 2 * 1024 * 1024;
 
+const MAX_NEEDLE_CHARS = 128;
+
 const MAX_ALTERNATIVES = 3;
 
 /** Light suffix stripping so "terminated" ⊇ "terminat" matches "terminate"; deterministic, no dictionary. */
@@ -41,31 +43,40 @@ export function tokenizeQuery(query) {
   };
 }
 
-export function scorePathTopology(filePath, tokens, flags) {
-  const normalized = filePath.replaceAll("\\", "/").toLowerCase();
+function tokenPathScore(base, words, normalized, tokens) {
+  let score = 0;
+
+  for (const token of tokens) {
+    if (base === token || base.startsWith(token + ".")) score += 60;
+    else if (base.includes(token)) score += 30;
+    else if (words.includes(token)) score += 15;
+    else if (normalized.includes(token)) score += 5;
+  }
+
+  return score;
+}
+
+function topologyPenalty(normalized, flags) {
   const parts = normalized.split("/");
 
   if (parts.some(part => ["node_modules", "dist", "target"].includes(part))) return -100;
   const test = isTestPath(normalized);
 
   if (test && !flags.wantsTest) return -50;
-
   if (!test && flags.wantsTest) return -20;
-  const base = path.basename(normalized);
-  const words = normalized.split(/[^a-zA-Z0-9]+/);
+}
+
+export function scorePathTopology(filePath, tokens, flags) {
+  const normalized = filePath.replaceAll("\\", "/").toLowerCase();
+  const penalty = topologyPenalty(normalized, flags);
+
+  if (penalty !== undefined) return penalty;
   const ext = path.extname(normalized);
   let score = SOURCE_EXT.has(ext) && !flags.wantsDoc ? 5 : 0;
 
   if (flags.wantsType && TYPED_EXT.has(ext)) score += 10;
 
-  for (const token of tokens) {
-    if (base === token || base.startsWith(token + ".")) score += 60;
-    else if (base.includes(token)) score += 30;
-    else if (words.includes(token)) score += 15;
-    else if (normalized.includes(token)) score += 5;
-  }
-
-  return score;
+  return score + tokenPathScore(path.basename(normalized), normalized.split(/[^a-zA-Z0-9]+/), normalized, tokens);
 }
 
 function inScope(filePath, dir, includeHidden) {
@@ -82,56 +93,66 @@ function makeCandidate(filePath, dir, query, tokens, flags) {
   const lower = relative.toLowerCase();
   const base = path.basename(lower);
 
+  const extension = path.extname(base);
+  const stemBase = extension ? base.slice(0, -extension.length) : base;
   const exactPath = lower === query.toLowerCase() || base === query.toLowerCase()
-    || base.slice(0, -path.extname(base).length) === query.toLowerCase();
+    || stemBase === query.toLowerCase();
+
+  const needles = tokens.map(token => stem(token).slice(0, MAX_NEEDLE_CHARS));
 
   return { path: filePath, pathScore: scorePathTopology(relative, tokens, flags), exactPath,
-    pathCoverage: tokens.filter(token => lower.includes(token)).length,
+    pathCoverage: tokens.filter((token, index) => lower.includes(needles[index] ?? token)).length,
     matched: new Set(), exactDefinition: false, definitionCoverage: 0, lineCoverage: 0,
     line: 1, signature: "", context: new Map(), recent: [], anchorScore: -1, exactLines: new Set() };
 }
 
-function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
-  const text = raw.replace(/\r?\n$/, "");
-  const lower = text.toLowerCase();
-
-  if (isMatch) {
-    const matches = tokens.filter(token => lower.includes(token));
+function bestDeclaration(items, query, tokens, needles) {
+  let declaration;
+  let definitionCoverage = 0;
+  let exact = false;
+  const queryLower = query.toLowerCase();
 
-    for (const token of matches) candidate.matched.add(token);
-    const ext = path.extname(candidate.path).toLowerCase();
-    const items = SOURCE_EXT.has(ext) ? extractStructuralSurface(text, ext).items : [];
-    let declaration;
-    let definitionCoverage = 0;
-    let exact = false;
+  for (const item of items) {
+    const name = item.name.toLowerCase();
+    const itemExact = name === queryLower;
+    const coverage = tokens.filter((token, index) => name.includes(needles[index] ?? token)).length;
 
-    for (const item of items) {
-      const name = item.name.toLowerCase();
-      const itemExact = name === query.toLowerCase();
-      const coverage = tokens.filter(token => name.includes(token)).length;
+    if (itemExact || coverage > definitionCoverage) { declaration = item; definitionCoverage = coverage; exact = itemExact; }
+    if (exact) break;
+  }
 
-      if (itemExact || coverage > definitionCoverage) { declaration = item; definitionCoverage = coverage; exact = itemExact; }
+  return { declaration, definitionCoverage, exact };
+}
 
-      if (exact) break;
-    }
+function applyMatch(candidate, lineNumber, text, query, tokens, needles, lower) {
+  const matches = tokens.filter((token, index) => lower.includes(needles[index] ?? token));
 
-    const score = (exact ? 10000 : 0) + definitionCoverage * 40 + matches.length;
+  for (const token of matches) candidate.matched.add(token);
+  const ext = path.extname(candidate.path).toLowerCase();
+  const items = SOURCE_EXT.has(ext) ? extractStructuralSurface(text, ext).items : [];
+  const { declaration, definitionCoverage, exact } = bestDeclaration(items, query, tokens, needles);
+  const score = (exact ? 10000 : 0) + definitionCoverage * 40 + matches.length;
 
-    if (exact) candidate.exactLines.add(lineNumber);
+  if (exact) candidate.exactLines.add(lineNumber);
 
-    if (score > candidate.anchorScore) {
-      candidate.anchorScore = score;
-      candidate.line = lineNumber;
-      candidate.signature = truncateChars(declaration?.signature ?? "", 240, "signature").text;
-      candidate.exactDefinition = exact;
-      candidate.definitionCoverage = definitionCoverage;
-      candidate.lineCoverage = matches.length;
-      candidate.context.clear();
+  if (score > candidate.anchorScore) {
+    candidate.anchorScore = score;
+    candidate.line = lineNumber;
+    candidate.signature = truncateChars(declaration?.signature ?? "", 240, "signature").text;
+    candidate.exactDefinition = exact;
+    candidate.definitionCoverage = definitionCoverage;
+    candidate.lineCoverage = matches.length;
+    candidate.context.clear();
 
-      for (const [number, line] of candidate.recent) if (number >= lineNumber - 2) candidate.context.set(number, line);
-    }
+    for (const [number, line] of candidate.recent) if (number >= lineNumber - 2) candidate.context.set(number, line);
   }
+}
+
+function inspectLine(candidate, lineNumber, raw, query, tokens, needles, isMatch) {
+  const text = raw.replace(/\r?\n$/, "");
+  const lower = text.toLowerCase();
 
+  if (isMatch) applyMatch(candidate, lineNumber, text, query, tokens, needles, lower);
   const excerpt = truncateChars(text, 240, "source line").text;
 
   if (lineNumber >= candidate.line - 2 && lineNumber <= candidate.line + 4) candidate.context.set(lineNumber, excerpt);
@@ -140,74 +161,116 @@ function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
   if (candidate.recent.length > 2) candidate.recent.shift();
 }
 
-function inspectOverlay(candidate, text, needles, query, tokens) {
-  const lines = text.split("\n");
-  const matches = [];
+function inspectOverlay(candidate, text, needles, query, tokens, signal) {
+  let start = 0, line = 1, truncated = false;
+
+  // Keep only the candidate and its short context, not another copy of every
+  // line in a staged document. Oversized individual lines disclose uncertainty.
+  while (start < text.length) {
+    if ((line & 127) === 0) signal?.throwIfAborted();
+    const newline = text.indexOf("\n", start);
+    const end = newline < 0 ? text.length : newline + 1;
+
+    if (end - start > MAX_SEARCH_CHARS) truncated = true;
+    else {
+      const row = text.slice(start, end);
+      const lower = row.toLowerCase();
+      inspectLine(candidate, line, row, query, tokens, needles, needles.some(needle => lower.includes(needle)));
+    }
+    start = end;
+    line++;
+  }
 
-  for (let i = 0; i < lines.length; i++) if (needles.some(needle => lines[i].toLowerCase().includes(needle))) matches.push(i);
+  return truncated;
+}
 
-  for (const i of matches) inspectLine(candidate, i + 1, lines[i], query, tokens, true);
-  candidate.context.clear();
+function parseRgRecord(line, truncated, isLast) {
+  if (!line) return null;
 
-  for (let i = Math.max(0, candidate.line - 3); i < Math.min(lines.length, candidate.line + 4); i++) candidate.context.set(i + 1, truncateChars(lines[i], 240, "source line").text);
+  try { return JSON.parse(line); } catch (error) {
+    if (truncated && isLast) return undefined;
+    throw error;
+  }
 }
 
-async function contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles }) {
-  const needles = exact ? [query.toLowerCase()] : tokens;
-  const args = ["rg", "--json", "--fixed-strings", "--ignore-case", "--before-context", "2", "--after-context", "4"];
+function absorbRgHit(candidates, record, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles) {
+  if (record.type !== "match" && record.type !== "context") return;
+  const data = record.data;
 
-  if (includeHidden) args.push("--hidden");
-  args.push("-g", "!.git/**", "-g", "!**/.git/**");
+  if (!data?.path?.text || !isString(data.lines?.text)) return;
+  const filePath = path.resolve(dir, data.path.text);
 
-  for (const needle of needles) args.push("-e", needle);
-  args.push("--", dir);
+  if (!inScope(filePath, dir, includeHidden) || overlayText(filePath) !== undefined) return;
+  let candidate = candidates.get(filePath);
 
-  const response = diskFiles ? await run(args, { cwd: dir, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS, signal })
-    : { stdout: "", stderr: "", exitCode: 1 };
+  if (!candidate) {
+    candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
+    candidates.set(filePath, candidate);
+  }
 
-  if (response.exitCode !== 0 && response.exitCode !== 1) throw new Error("source search failed: " + response.stderr.trim());
-  const candidates = new Map();
-  const records = response.stdout.split("\n");
+  inspectLine(candidate, data.line_number, data.lines.text, query, tokens, needles, record.type === "match");
+}
 
-  for (let i = 0; i < records.length; i++) {
-    if ((i & 127) === 0) signal?.throwIfAborted();
+function overlayCandidates(candidates, pendingPaths, overlayText, candidateRoot, query, tokens, flags, needles, signal) {
+  let overlayTruncated = false;
 
-    if (!records[i]) continue;
-    let record;
+  for (const filePath of pendingPaths) {
+    const pending = overlayText(filePath);
 
-    try { record = JSON.parse(records[i]); } catch (error) {
-      if (response.outputTruncated && i === records.length - 1) break;
-      throw error;
-    }
+    if (pending === undefined) continue;
+    const candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
+    overlayTruncated = inspectOverlay(candidate, pending, needles, query, tokens, signal) || overlayTruncated;
 
-    if (record.type !== "match" && record.type !== "context") continue;
-    const data = record.data;
+    if (candidate.matched.size) candidates.set(filePath, candidate);
+  }
 
-    if (!data?.path?.text || !isString(data.lines?.text)) continue;
-    const filePath = path.resolve(dir, data.path.text);
+  return overlayTruncated;
+}
 
-    if (!inScope(filePath, dir, includeHidden) || overlayText(filePath) !== undefined) continue;
-    let candidate = candidates.get(filePath);
+function rgSearchArgs(includeHidden, searchNeedles, focusFile, dir) {
+  const args = ["rg", "--json", "--fixed-strings", "--ignore-case", "--before-context", "2", "--after-context", "4"];
 
-    if (!candidate) {
-      candidate = makeCandidate(filePath, dir, query, tokens, flags);
-      candidates.set(filePath, candidate);
-    }
+  if (includeHidden) args.push("--hidden");
+  args.push("-g", "!.git/**", "-g", "!**/.git/**");
+  for (const needle of searchNeedles) args.push("-e", needle);
+  args.push("--", focusFile ?? dir);
 
-    inspectLine(candidate, data.line_number, data.lines.text, query, tokens, record.type === "match");
-  }
+  return args;
+}
 
-  for (const filePath of pendingPaths) {
-    const pending = overlayText(filePath);
+async function runContentSearch({ dir, includeHidden, searchNeedles, run, overlayText, signal, diskFiles, focusFile }) {
+  const args = rgSearchArgs(includeHidden, searchNeedles, focusFile, dir);
+  const response = diskFiles || (focusFile && overlayText(focusFile) === undefined)
+    ? await run(args, { cwd: focusFile ? path.dirname(focusFile) : dir, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS, signal })
+    : { stdout: "", stderr: "", exitCode: 1 };
 
-    if (pending === undefined) continue;
-    const candidate = makeCandidate(filePath, dir, query, tokens, flags);
-    inspectOverlay(candidate, pending, needles, query, tokens);
+  if (response.exitCode !== 0 && response.exitCode !== 1) throw new Error("source search failed: " + response.stderr.trim());
 
-    if (candidate.matched.size) candidates.set(filePath, candidate);
+  return response;
+}
+
+function absorbRgRecords(candidates, response, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, signal) {
+  const records = response.stdout.split("\n");
+
+  for (let i = 0; i < records.length; i++) {
+    if ((i & 127) === 0) signal?.throwIfAborted();
+    const record = parseRgRecord(records[i], response.outputTruncated, i === records.length - 1);
+
+    if (record === undefined) break;
+    if (!record) continue;
+    absorbRgHit(candidates, record, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles);
   }
+}
+
+async function contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles, focusFile }) {
+  const needles = exact ? [query.toLowerCase().slice(0, MAX_NEEDLE_CHARS)] : tokens.map(token => stem(token).slice(0, MAX_NEEDLE_CHARS));
+  const candidateRoot = focusFile ? path.dirname(focusFile) : dir;
+  const candidates = new Map();
+  const response = await runContentSearch({ dir, includeHidden, searchNeedles: [...new Set(needles)], run, overlayText, signal, diskFiles, focusFile });
+  absorbRgRecords(candidates, response, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, signal);
+  const overlayTruncated = overlayCandidates(candidates, pendingPaths, overlayText, candidateRoot, query, tokens, flags, needles, signal);
 
-  return { candidates, truncated: response.outputTruncated === true };
+  return { candidates, truncated: response.outputTruncated === true || overlayTruncated };
 }
 
 function rankScore(candidate, tokenCount) {
@@ -224,126 +287,219 @@ function location(candidate, root) {
     context: [...context].sort((a, b) => a[0] - b[0]).map(([line, text]) => (line === candidate.line ? "►" : " ") + line + " " + text) };
 }
 
-async function spanCandidates(filePath, lines, root, overlayText) {
+async function spanCandidates(filePath, lines, root, overlayText, signal) {
   const staged = overlayText(filePath);
-  const text = staged !== undefined ? staged : await fs.readFile(filePath, "utf8");
-  const spans = WorkspaceIndex.spansOf(WorkspaceIndex.fromText(filePath, text));
   const rel = path.relative(root, filePath);
+  let text = staged;
+
+  if (text === undefined) {
+    const file = await fs.open(filePath, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+
+    try {
+      const stat = await file.stat();
+
+      if (!stat.isFile()) throw new Error("source candidate is not a regular file: " + filePath);
+      if (stat.size > 512 * 1024) return lines.map(line => ({ path: rel, line, signature: "", context: [] }));
+      text = await file.readFile({ encoding: "utf8", signal });
+    } finally { await file.close(); }
+  }
+  const spans = WorkspaceIndex.spansOf(WorkspaceIndex.fromText(filePath, text));
 
   return lines.map(line => {
     const span = pickSpan(spans, { line }) ?? { start: line, end: line };
+    const end = Math.min(span.end, span.start + 119);
 
-    return spanCandidate(rel, line, spanWindow(text, span.start, span.end));
+    return spanCandidate(rel, line, spanWindow(text, span.start, end));
   });
 }
 
-async function rankedSpanCandidates(ranked, root, overlayText) {
+async function rankedSpanCandidates(ranked, root, overlayText, signal) {
   const out = [];
 
   for (const candidate of ranked) {
     const lines = candidate.exactLines?.size ? [...candidate.exactLines].sort((a, b) => a - b) : [candidate.line];
-    out.push(...await spanCandidates(candidate.path, lines, root, overlayText));
+    const staged = overlayText(candidate.path);
+    let large = false;
+
+    if (staged !== undefined) large = Buffer.byteLength(staged) > 512 * 1024;
+    else try { large = (await fs.stat(candidate.path)).size > 512 * 1024; } catch {}
+
+    if (large) out.push(location(candidate, root));
+    else {
+      try { out.push(...await spanCandidates(candidate.path, lines, root, overlayText, signal)); }
+      catch { signal?.throwIfAborted(); out.push(location(candidate, root)); }
+    }
     if (out.length >= MAX_ALTERNATIVES) break;
   }
 
   return out.slice(0, MAX_ALTERNATIVES);
 }
 
-export async function executeSnap({ query, searchDir, root, includeHidden = false, run = runCommand, overlayText = () => undefined, pendingPaths = [], pathContext = {}, signal }) {
+function admitSnapQuery(query, searchDir, root, includeHidden, pendingPaths) {
   const flags = tokenizeQuery(query);
+
+  if (flags.tokens.length > 16) throw new Error("source question is too broad; use at most 16 keywords");
   const tokens = [...new Set(flags.tokens.map(stem))];
 
   if (tokens.length === 0) throw new Error("read requires a file path or a searchable source question");
-
-  if (tokens.length > 16) throw new Error("source question is too broad; use at most 16 keywords");
   query = query.trim();
   const dir = path.resolve(searchDir || process.cwd());
 
   if (dir.split(path.sep).includes(".git")) throw new Error("cannot search Git metadata");
-  signal?.throwIfAborted();
   flags.wantsTest ||= isTestPath(path.relative(root ?? dir, dir));
-  pendingPaths = pendingPaths.filter(file => inScope(file, dir, includeHidden));
 
-  const diskFiles = await fs.stat(dir).then(stat => stat.isDirectory(), error => {
-    if (error.code !== "ENOENT" || !pendingPaths.length) throw error;
-
-    return false;
-  });
+  return {
+    flags,
+    tokens,
+    query,
+    dir,
+    exact: /^[a-zA-Z_$][\w$]*$/.test(query),
+    pendingPaths: pendingPaths.filter(file => inScope(file, dir, includeHidden)),
+  };
+}
 
-  const empty = { path: null, line: null, signature: "", confidence: 0, context: [] };
-  const exact = /^[a-zA-Z_$][\w$]*$/.test(query);
-  const search = await contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles });
-  // A declaration hit needs no prerequisite file listing or persistent index.
-  // Bare names can name files, even when callers mention the same word.
-  const needsPaths = !search.candidates.size || (exact && ![...search.candidates.values()].some(candidate => candidate.exactDefinition));
+function listedSnapPaths(listing, dir, includeHidden, focusFile, pendingPaths) {
+  return [...new Set([...listing.stdout.split("\0").flatMap(file => file ? [path.resolve(dir, file)] : []), ...(focusFile ? [focusFile] : []), ...pendingPaths])]
+    .filter(file => inScope(file, dir, includeHidden));
+}
 
-  const listing = needsPaths && !search.truncated && diskFiles
-    ? await run(["rg", "--files", "--null", ...(includeHidden ? ["--hidden"] : []), "-g", "!.git/**", "-g", "!**/.git/**", dir], { cwd: dir, signal, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS })
-    : { stdout: "", exitCode: 1 };
+function filenameEligible(search, filePath, relative, tokens, exact, queryLower) {
+  if (search.candidates.has(filePath)) return false;
+  if (!tokens.some(token => relative.includes(token))) return false;
+  if (exact && tokens.length > 1 && !relative.includes(queryLower)) return false;
 
-  if (listing.exitCode !== 0 && listing.exitCode !== 1) throw new Error("source file listing failed: " + listing.stderr.trim());
+  return true;
+}
 
-  const paths = [...new Set([...listing.stdout.split("\0").flatMap(file => file ? [path.resolve(dir, file)] : []), ...pendingPaths])]
-    .filter(file => inScope(file, dir, includeHidden));
+function addFilenameCandidates(search, paths, { dir, focusFile, query, tokens, flags, exact }) {
+  const candidateRoot = focusFile ? path.dirname(focusFile) : dir;
+  const queryLower = query.toLowerCase();
 
   for (const filePath of paths) {
-    if (!inScope(filePath, dir, includeHidden) || search.candidates.has(filePath)) continue;
-    const relative = path.relative(dir, filePath).toLowerCase();
+    const relative = path.relative(candidateRoot, filePath).toLowerCase();
 
-    if (!tokens.some(token => relative.includes(token))) continue;
+    if (!filenameEligible(search, filePath, relative, tokens, exact, queryLower)) continue;
+    const candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
 
-    if (exact && tokens.length > 1 && !relative.includes(query.toLowerCase())) continue;
-    const candidate = makeCandidate(filePath, dir, query, tokens, flags);
-
-    if (candidate.pathScore > 0) search.candidates.set(filePath, candidate);
+    if (focusFile || candidate.pathScore > 0) search.candidates.set(filePath, candidate);
   }
+}
 
+function rankSnapCandidates(search, tokenCount, focusFile) {
   const ranked = [];
 
   for (const candidate of search.candidates.values()) {
-    if (candidate.pathScore > -50) {
-      ranked.push({ ...candidate, score: rankScore(candidate, tokens.length) });
+    if (focusFile || candidate.pathScore > -50) {
+      const score = rankScore(candidate, tokenCount);
+      ranked.push({ ...candidate, score: focusFile ? Math.max(1, score) : score });
     }
   }
 
   ranked.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
 
-  const incomplete = search.truncated || listing.outputTruncated === true;
-  const relativeRoot = root ?? dir;
-  const candidates = ranked.slice(0, MAX_ALTERNATIVES).map(candidate => location(candidate, relativeRoot));
-
-  if (incomplete) return { ...empty, status: "incomplete", candidates, message: "Search output exceeded its budget. Narrow the directory with read(path, {about: question})." };
-
-  if (!ranked.length) {
-    // Reuse bounded filename discovery; fuzzy rank never authorizes a source selection.
-    const eligible = exact && query.length >= 4 && query.length <= 64;
-    const limited = eligible && paths.length > 1024;
+  return ranked;
+}
 
-    const fuzzy = eligible ? rankPaths(query, paths.slice(0, 1024).map(file => relativeSlash(relativeRoot, file)),
-      { ...pathContext, maxTypos: 1 }).filter(hit => hit.score > 0).slice(0, MAX_ALTERNATIVES) : [];
+function emptySnap() {
+  return { path: null, line: null, signature: "", confidence: 0, context: [] };
+}
 
-    if (fuzzy.length || limited) return { ...empty, status: limited ? "incomplete" : "ambiguous",
-      candidates: fuzzy.map(hit => ({ path: hit.path, line: 1, context: [], match: "fuzzy" })),
-      message: limited ? "No literal match; fuzzy hints cover only 1024 paths. Narrow the directory." : "No literal match. Fuzzy filename hints are not selected source; read an explicit path." };
+function uniqueExactHit(best, second) {
+  return best.exactDefinition && !second?.exactDefinition || best.exactPath && !second?.exactPath && !second?.exactDefinition;
+}
 
-    return { ...empty, status: "not_found" };
-  }
+function snapCoverage(best, tokens) {
+  return Math.max(best.matched.size, best.pathCoverage) / tokens.length;
+}
 
+async function decideSnapResult(ranked, tokens, empty, candidates, relativeRoot, overlayText, signal) {
   const best = ranked[0];
   const second = ranked[1];
   const margin = second ? (best.score - second.score) / Math.max(1, best.score) : 1;
-  const coverage = Math.max(best.matched.size, best.pathCoverage) / tokens.length;
-  const uniqueExact = best.exactDefinition && !second?.exactDefinition || best.exactPath && !second?.exactPath && !second?.exactDefinition;
+  const coverage = snapCoverage(best, tokens);
+  const uniqueExact = uniqueExactHit(best, second);
 
   if (!uniqueExact && (coverage < 0.6 || margin < 0.15 || best.definitionCoverage / tokens.length < 0.5)) {
-    return { ...empty, status: "ambiguous", candidates: await rankedSpanCandidates(ranked, relativeRoot, overlayText) };
+    return { ...empty, status: "ambiguous", candidates: await rankedSpanCandidates(ranked, relativeRoot, overlayText, signal) };
   }
 
   if (best.exactLines.size > 1) {
-    return { ...empty, status: "ambiguous", candidates: await rankedSpanCandidates([best], relativeRoot, overlayText) };
+    return { ...empty, status: "ambiguous", candidates: await rankedSpanCandidates([best], relativeRoot, overlayText, signal) };
   }
 
   const confidence = uniqueExact ? 0.95 : Math.min(0.85, 0.5 + coverage * 0.2 + margin * 0.15);
 
   return { ...candidates[0], status: "found", confidence: Number(confidence.toFixed(2)) };
 }
+
+function fuzzySnapMiss(exact, query, paths, pathContext, relativeRoot, empty) {
+  const eligible = exact && query.length >= 4 && query.length <= 64;
+  const limited = eligible && paths.length > 1024;
+  const fuzzy = eligible ? rankPaths(query, paths.slice(0, 1024).map(file => relativeSlash(relativeRoot, file)),
+    { ...pathContext, maxTypos: 1 }).filter(hit => hit.score > 0).slice(0, MAX_ALTERNATIVES) : [];
+
+  if (fuzzy.length || limited) return { ...empty, status: limited ? "incomplete" : "ambiguous",
+    candidates: fuzzy.map(hit => ({ path: hit.path, line: 1, context: [], match: "fuzzy" })),
+    message: limited ? "No literal match; fuzzy hints cover only 1024 paths. Narrow the directory." : "No literal match. Fuzzy filename hints are not selected source; read an explicit path." };
+
+  return { ...empty, status: "not_found" };
+}
+
+async function snapListing(needsPaths, truncated, diskFiles, includeHidden, dir, run, signal) {
+  const listing = needsPaths && !truncated && diskFiles
+    ? await run(["rg", "--files", "--null", ...(includeHidden ? ["--hidden"] : []), "-g", "!.git/**", "-g", "!**/.git/**", dir], { cwd: dir, signal, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS })
+    : { stdout: "", exitCode: 1 };
+
+  if (listing.exitCode !== 0 && listing.exitCode !== 1) throw new Error("source file listing failed: " + listing.stderr.trim());
+
+  return listing;
+}
+
+function snapFocus(dirStat, pendingPaths, dir) {
+  return {
+    diskFiles: dirStat?.isDirectory() === true,
+    focusFile: dirStat?.isFile() === true || pendingPaths.includes(dir) ? dir : null,
+  };
+}
+
+export async function executeSnap({ query, searchDir, root, includeHidden = false, run = runCommand, overlayText = () => undefined, pendingPaths = [], pathContext = {}, signal }) {
+  const admitted = admitSnapQuery(query, searchDir, root, includeHidden, pendingPaths);
+  const { flags, tokens, dir, exact } = admitted;
+  query = admitted.query;
+  pendingPaths = admitted.pendingPaths;
+  signal?.throwIfAborted();
+
+  const empty = emptySnap();
+  const dirStat = await fs.stat(dir).catch(error => {
+    if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
+
+    return null;
+  });
+
+  if (!dirStat && !pendingPaths.length) return { ...empty, status: "not_found" };
+  const { diskFiles, focusFile } = snapFocus(dirStat, pendingPaths, dir);
+
+  if (!tokens.length) return { ...empty, status: "not_found" };
+
+  return rankSnapSearch({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles, focusFile, root, pathContext, empty });
+}
+
+async function rankSnapSearch({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles, focusFile, root, pathContext, empty }) {
+  const search = await contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles, focusFile });
+  // A declaration hit needs no prerequisite file listing or persistent index.
+  // Bare names can name files, even when callers mention the same word.
+  const needsPaths = !search.candidates.size || (exact && ![...search.candidates.values()].some(candidate => candidate.exactDefinition));
+  const listing = await snapListing(needsPaths, search.truncated, diskFiles, includeHidden, dir, run, signal);
+  const paths = listedSnapPaths(listing, dir, includeHidden, focusFile, pendingPaths);
+  addFilenameCandidates(search, paths, { dir, focusFile, query, tokens, flags, exact });
+  const ranked = rankSnapCandidates(search, tokens.length, focusFile);
+  const relativeRoot = root ?? dir;
+  const candidates = ranked.slice(0, MAX_ALTERNATIVES).map(candidate => location(candidate, relativeRoot));
+
+  if (search.truncated || listing.outputTruncated === true) {
+    return { ...empty, status: "incomplete", candidates, message: "Search output exceeded its budget. Narrow the directory with read(path, {about: question})." };
+  }
+
+  return ranked.length ? decideSnapResult(ranked, tokens, empty, candidates, relativeRoot, overlayText, signal)
+    : fuzzySnapMiss(exact, query, paths, pathContext, relativeRoot, empty);
+}

package/src/context/spans.js

@@ -1,7 +1,8 @@
 import { truncateChars } from "../output/format.js";
+import { isString } from "../shared/decode.js";
 
 export function pickSpan(spans, { line, name } = {}) {
-  const needle = typeof name === "string" && /^[A-Za-z_$][\w$]*$/.test(name.trim()) ? name.trim().toLowerCase() : "";
+  const needle = isString(name) && /^[A-Za-z_$][\w$]*$/.test(name.trim()) ? name.trim().toLowerCase() : "";
   const named = needle ? spans.filter(item => item.name.toLowerCase() === needle) : [];
 
   if (named.length === 1) return named[0];