pi-supernova 0.6.0 → 0.7.1

package/src/context/snap.js

@@ -43,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) {
@@ -97,47 +106,53 @@ function makeCandidate(filePath, dir, query, tokens, flags) {
     line: 1, signature: "", context: new Map(), recent: [], anchorScore: -1, exactLines: new Set() };
 }
 
-function inspectLine(candidate, lineNumber, raw, query, tokens, needles, isMatch) {
-  const text = raw.replace(/\r?\n$/, "");
-  const lower = text.toLowerCase();
-
-  if (isMatch) {
-    const matches = tokens.filter((token, index) => lower.includes(needles[index] ?? 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, index) => name.includes(needles[index] ?? 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);
@@ -169,54 +184,34 @@ function inspectOverlay(candidate, text, needles, query, tokens, signal) {
   return truncated;
 }
 
-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 searchNeedles = [...new Set(needles)];
-  const candidateRoot = focusFile ? path.dirname(focusFile) : dir;
-  const candidates = new Map();
-
-  const args = ["rg", "--json", "--fixed-strings", "--ignore-case", "--before-context", "2", "--after-context", "4"];
-
-  if (includeHidden) args.push("--hidden");
-  args.push("-g", "!.git/**", "-g", "!**/.git/**");
-
-  for (const needle of searchNeedles) args.push("-e", needle);
-  args.push("--", 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 (response.exitCode !== 0 && response.exitCode !== 1) throw new Error("source search failed: " + response.stderr.trim());
-  const records = response.stdout.split("\n");
-
-  for (let i = 0; i < records.length; i++) {
-    if ((i & 127) === 0) signal?.throwIfAborted();
-
-    if (!records[i]) continue;
-    let record;
+function parseRgRecord(line, truncated, isLast) {
+  if (!line) return null;
 
-    try { record = JSON.parse(records[i]); } catch (error) {
-      if (response.outputTruncated && i === records.length - 1) break;
-      throw error;
-    }
-
-    if (record.type !== "match" && record.type !== "context") continue;
-    const data = record.data;
+  try { return JSON.parse(line); } catch (error) {
+    if (truncated && isLast) return undefined;
+    throw error;
+  }
+}
 
-    if (!data?.path?.text || !isString(data.lines?.text)) continue;
-    const filePath = path.resolve(dir, data.path.text);
+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 (!inScope(filePath, dir, includeHidden) || overlayText(filePath) !== undefined) continue;
-    let candidate = candidates.get(filePath);
+  if (!data?.path?.text || !isString(data.lines?.text)) return;
+  const filePath = path.resolve(dir, data.path.text);
 
-    if (!candidate) {
-      candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
-      candidates.set(filePath, candidate);
-    }
+  if (!inScope(filePath, dir, includeHidden) || overlayText(filePath) !== undefined) return;
+  let candidate = candidates.get(filePath);
 
-    inspectLine(candidate, data.line_number, data.lines.text, query, tokens, needles, record.type === "match");
+  if (!candidate) {
+    candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
+    candidates.set(filePath, candidate);
   }
 
+  inspectLine(candidate, data.line_number, data.lines.text, query, tokens, needles, record.type === "match");
+}
+
+function overlayCandidates(candidates, pendingPaths, overlayText, candidateRoot, query, tokens, flags, needles, signal) {
   let overlayTruncated = false;
 
   for (const filePath of pendingPaths) {
@@ -229,6 +224,52 @@ async function contentCandidates({ dir, includeHidden, query, tokens, flags, pen
     if (candidate.matched.size) candidates.set(filePath, candidate);
   }
 
+  return overlayTruncated;
+}
+
+function rgSearchArgs(includeHidden, searchNeedles, focusFile, dir) {
+  const args = ["rg", "--json", "--fixed-strings", "--ignore-case", "--before-context", "2", "--after-context", "4"];
+
+  if (includeHidden) args.push("--hidden");
+  args.push("-g", "!.git/**", "-g", "!**/.git/**");
+  for (const needle of searchNeedles) args.push("-e", needle);
+  args.push("--", focusFile ?? dir);
+
+  return args;
+}
+
+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 (response.exitCode !== 0 && response.exitCode !== 1) throw new Error("source search failed: " + response.stderr.trim());
+
+  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 || overlayTruncated };
 }
 
@@ -286,7 +327,7 @@ async function rankedSpanCandidates(ranked, root, overlayText, signal) {
     if (large) out.push(location(candidate, root));
     else {
       try { out.push(...await spanCandidates(candidate.path, lines, root, overlayText, signal)); }
-      catch (error) { signal?.throwIfAborted(); out.push(location(candidate, root)); }
+      catch { signal?.throwIfAborted(); out.push(location(candidate, root)); }
     }
     if (out.length >= MAX_ALTERNATIVES) break;
   }
@@ -294,7 +335,7 @@ async function rankedSpanCandidates(ranked, root, overlayText, signal) {
   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");
@@ -305,87 +346,78 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
   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 empty = { path: null, line: null, signature: "", confidence: 0, context: [] };
-  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 = dirStat?.isDirectory() === true;
-  const focusFile = dirStat?.isFile() === true || pendingPaths.includes(dir) ? dir : null;
-
-  const exact = /^[a-zA-Z_$][\w$]*$/.test(query);
+  return {
+    flags,
+    tokens,
+    query,
+    dir,
+    exact: /^[a-zA-Z_$][\w$]*$/.test(query),
+    pendingPaths: pendingPaths.filter(file => inScope(file, dir, includeHidden)),
+  };
+}
 
-  if (!tokens.length) return { ...empty, status: "not_found" };
-  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));
+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)] : []), ...(focusFile ? [focusFile] : []), ...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(candidateRoot, filePath).toLowerCase();
 
-    if (!tokens.some(token => relative.includes(token))) continue;
-
-    if (exact && tokens.length > 1 && !relative.includes(query.toLowerCase())) continue;
+    if (!filenameEligible(search, filePath, relative, tokens, exact, queryLower)) continue;
     const candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
 
     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 (focusFile || candidate.pathScore > -50) {
-      ranked.push({ ...candidate, score: focusFile ? Math.max(1, rankScore(candidate, tokens.length)) : rankScore(candidate, tokens.length) });
+      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, signal) };
@@ -399,3 +431,75 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
 
   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];

package/src/context/surface.js

@@ -116,15 +116,24 @@ function declarationItem(line, rawLine, lineNumber) {
   return null;
 }
 
+function skipJsNoise(line) {
+  return !line || line.startsWith("//") || line.startsWith("/*") || line.startsWith("*");
+}
+
+function jsItemAt(lines, i) {
+  const line = lines[i].trim();
+
+  if (skipJsNoise(line)) return null;
+  const indent = lines[i].length - lines[i].trimStart().length;
+
+  return declarationItem(line, lines[i], i + 1) || (indent > 0 && indent <= 8 ? methodItem(line, i + 1, Math.max(1, Math.floor(indent / 2))) : null);
+}
+
 function scanJavaScript(lines) {
   const items = [];
 
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i].trim();
-
-    if (!line || line.startsWith("//") || line.startsWith("/*") || line.startsWith("*")) continue;
-    const indent = lines[i].length - lines[i].trimStart().length;
-    const item = declarationItem(line, lines[i], i + 1) || (indent > 0 && indent <= 8 ? methodItem(line, i + 1, Math.max(1, Math.floor(indent / 2))) : null);
+    const item = jsItemAt(lines, i);
 
     if (item) items.push(item);
   }

package/src/contract/bash.js

@@ -0,0 +1,31 @@
+import { isString, isObject } from "../shared/decode.js";
+
+const ARGV_ERROR = "bash argv requires a command string and an array of string args";
+
+function quoteShellArg(value) {
+  return "'" + String(value).replaceAll("'", "'\\''") + "'";
+}
+
+/** Normalize guest bash(command, opts) / bash({command, args}) into host args. */
+function normalizeArgv(args) {
+  if (args.args === undefined) return;
+  if (!isString(args.command) || !Array.isArray(args.args)) throw new Error(ARGV_ERROR);
+
+  for (let i = 0; i < args.args.length; i++) if (!isString(args.args[i])) throw new Error(ARGV_ERROR);
+  args.args = args.args.map(String);
+
+  if (process.platform === "win32") {
+    delete args._directArgv;
+    args.command = [args.command, ...args.args].map(quoteShellArg).join(" ");
+    delete args.args;
+  } else args._directArgv = true;
+}
+
+export function normalizeBash(command, opts) {
+  const args = isObject(command) ? { ...opts, ...command } : { command, ...opts };
+  normalizeArgv(args);
+
+  if (args.timeout !== undefined && args.timeoutMs === undefined) args.timeoutMs = args.timeout * 1000;
+
+  return args;
+}

package/src/contract/edit.js

@@ -0,0 +1,95 @@
+import { isString, isObject, isFunction, isNumber } from "../shared/decode.js";
+
+export const EDIT_USAGE = 'invalid edit signature; use edit(path,oldText,newText), edit({path,edits:[{oldText,newText}]}), or edit({path,patch:"@@ -1 +1 @@\n-old\n+new\n"})';
+
+function spanStart(value) {
+  return isNumber(value.start) ? value.start : Array.isArray(value.lines) ? value.lines[0] : value.line;
+}
+
+function spanEnd(value, start) {
+  return isNumber(value.end) ? value.end : Array.isArray(value.lines) && value.lines.length > 1 ? value.lines[1] : start;
+}
+
+export function viewSpan(value) {
+  const start = spanStart(value);
+  const end = spanEnd(value, start);
+
+  if (!isNumber(start) || !isNumber(end) || start < 1 || end < start) return null;
+
+  return { start: Math.floor(start), end: Math.floor(end) };
+}
+
+export function isEditView(value) {
+  return isObject(value) && !Array.isArray(value) && isString(value.path) && value.path.trim() && isString(value.text) && (value.status === undefined || value.status === "found") && viewSpan(value);
+}
+
+function classifyViewEdit(p, oldText, newText) {
+  if (isNumber(p.nextOffset)) throw new Error("edit view is incomplete");
+  const span = viewSpan(p);
+  const args = { path: p.path, viewStart: span.start, viewEnd: span.end, viewText: p.text, newText: newText === undefined ? oldText : newText };
+
+  if (newText !== undefined) args.oldText = oldText;
+
+  return { kind: "view", command: "edit", args };
+}
+
+function namedEditObject(p, oldText, newText) {
+  if (isObject(p) && (Array.isArray(p) || oldText !== undefined || newText !== undefined)) throw new Error(EDIT_USAGE);
+
+  return p;
+}
+
+function namedEditPositional(p, oldText, newText) {
+  if (isObject(oldText) && !Array.isArray(oldText)) throw new Error(EDIT_USAGE);
+
+  return Array.isArray(oldText) ? { path: p, edits: oldText } : { path: p, oldText, newText };
+}
+
+function normalizeEditArgs(p, oldText, newText) {
+  return isObject(p) ? namedEditObject(p, oldText, newText) : namedEditPositional(p, oldText, newText);
+}
+
+function namedEditArgs(p, oldText, newText) {
+  const args = normalizeEditArgs(p, oldText, newText);
+
+  if (!isString(args.path) || !args.path.trim()) throw new Error(EDIT_USAGE);
+
+  return args;
+}
+
+function assertNamedEditMode(args, oldText, newText) {
+  const modes = Number(args.patch !== undefined) + Number(args.edits !== undefined) + Number(args.oldText !== undefined || args.newText !== undefined);
+
+  if (modes !== 1 || (Array.isArray(oldText) && newText !== undefined)) throw new Error(EDIT_USAGE);
+}
+
+function classifyPatch(args) {
+  if (!isString(args.patch) || !args.patch.trim()) throw new Error(EDIT_USAGE);
+
+  return { kind: "patch", command: "apply_patch", args };
+}
+
+function classifyReplacements(args) {
+  const edits = args.edits === undefined ? [args] : args.edits;
+
+  if (!Array.isArray(edits) || !edits.length) throw new Error(EDIT_USAGE);
+
+  for (const e of edits) if (!isString(e?.oldText) || !e.oldText.length || !isString(e?.newText)) throw new Error(EDIT_USAGE + "; replacements require non-empty oldText and string newText");
+
+  return { kind: "edits", command: "edit", args };
+}
+
+function classifyNamedEdit(p, oldText, newText) {
+  const args = namedEditArgs(p, oldText, newText);
+  assertNamedEditMode(args, oldText, newText);
+
+  return args.patch !== undefined ? classifyPatch(args) : classifyReplacements(args);
+}
+
+/** Guest signature → { command, args } for one host call. */
+export function classifyEdit(p, oldText, newText) {
+  if (isFunction(p)) return { kind: "checkpoint", fn: p };
+  if (isEditView(p) && isString(oldText) && (newText === undefined || isString(newText))) return classifyViewEdit(p, oldText, newText);
+
+  return classifyNamedEdit(p, oldText, newText);
+}