pi-supernova 0.4.0 → 0.6.0

package/src/context/search.js

@@ -1,3 +1,4 @@
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isString } from "../shared/decode.js";
 import { WorkspaceIndex, globToRegExp } from "./repo-index.js";
@@ -12,6 +13,22 @@ function textResult(text, details) {
   return { content: [{ type: "text", text: String(text ?? "") }], details: details || {} };
 }
 
+async function candidateFileList(index, root, includeHidden = false, signal) {
+  const stat = await fs.stat(root).catch(() => null);
+
+  if (stat?.isFile()) return [root];
+
+  return index.files(root, includeHidden, signal);
+}
+
+function pendingInScope(root, pendingPaths) {
+  return pendingPaths.filter(file => {
+    const relative = path.relative(root, file);
+
+    return relative === "" || (relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative));
+  });
+}
+
 /** One bounded direct search for all changed names; no repository index or per-name spawn. */
 export async function referencesForNames({ root, names, excludePath, overlayText, pendingPaths, signal, run = runCommand }) {
   const references = new Map(names.map(name => [name, []]));
@@ -48,10 +65,10 @@ export async function referencesForNames({ root, names, excludePath, overlayText
     if (overlayText(file) === undefined) add(file, record.data.line_number, record.data.lines.text);
   }
 
-  for (const file of pendingPaths) {
+  for (const file of pendingInScope(root, pendingPaths)) {
     const text = overlayText(file);
 
-    if (text !== undefined) text.split("\n").forEach((line, i) => add(file, i + 1, line));
+    if (text !== undefined && Buffer.byteLength(text, "utf8") <= 512 * 1024) text.split("\n").forEach((line, i) => add(file, i + 1, line));
   }
 
   return { references, incomplete: result.outputTruncated === true };
@@ -59,29 +76,57 @@ export async function referencesForNames({ root, names, excludePath, overlayText
 
 export function rgGrepArgs(pattern, params, searchPath) {
   const args = ["--line-number", "--no-heading", "--color", "never"];
+  const caseSensitive = params?.caseSensitive === true || (params?.caseSensitive !== false && smartCase(pattern));
 
-  if (params?.caseSensitive !== true) args.push("--ignore-case");
+  if (!caseSensitive) args.push("--ignore-case");
 
   if (params?.glob) args.push("--glob", String(params.glob));
+  if (Number.isInteger(params?.limit) && params.limit > 0) args.push("--max-count", String(Math.min(params.limit, 2000)));
   args.push("--", pattern, searchPath);
 
   return args;
 }
 
 /** rg --files, then find(1) when rg is unavailable; both accept an optional glob/name pattern. */
-export async function listWithTools(searchDir, pattern, cwd, signal) {
+export async function listWithTools(searchDir, pattern, cwd, signal, pendingPaths = []) {
+  const stat = await fs.stat(searchDir).catch(() => null);
+  const pendingAbs = pendingInScope(searchDir, pendingPaths);
+  const pending = pendingAbs.map(file => relativeSlash(cwd, file));
+
+  let matcher = null;
+
+  if (pattern) {
+    try { matcher = globToRegExp(pattern); }
+    catch { matcher = /^$/; }
+  }
+
+  if (stat?.isFile() || (!stat?.isDirectory() && pending.length)) {
+    const rel = stat?.isFile() ? relativeSlash(cwd, searchDir) : null;
+    const rows = [...new Set([...(rel ? [rel] : []), ...pending])].filter(file => !matcher || matcher.test(file));
+
+    return textResult(rows.length ? rows.join("\n") + "\n" : "", { via: pending.length ? "vfs" : "file" });
+  }
+
+  const pendingMerged = pendingAbs.filter((_, i) => !matcher || matcher.test(pending[i]));
+  const mergePending = stdout => {
+    const diskRows = String(stdout || "").split("\n").filter(Boolean)
+      .map(row => relativeSlash(cwd, path.isAbsolute(row) ? row : path.resolve(cwd, row)));
+    const rows = [...new Set([...diskRows, ...pendingMerged])];
+
+    return rows.length ? rows.join("\n") + "\n" : "";
+  };
   const args = ["--files"];
 
   if (pattern) args.push("-g", pattern);
   const res = await runCommand(["rg", ...args, searchDir], { cwd, timeoutMs: 30_000, signal }).catch(() => null);
 
-  if (res && (res.exitCode === 0 || res.exitCode === 1)) return textResult(res.stdout, { via: "rg" });
+  if (res && (res.exitCode === 0 || res.exitCode === 1)) return textResult(mergePending(res.stdout), { via: "rg", outputTruncated: res.outputTruncated === true });
   const findArgs = [searchDir];
 
   if (pattern) findArgs.push("-name", pattern);
   const findRes = await runCommand(["find", ...findArgs], { cwd, timeoutMs: 30_000, signal });
 
-  return textResult(findRes.stdout, { via: "find" });
+  return textResult(mergePending(findRes.stdout), { via: "find", outputTruncated: findRes.outputTruncated === true });
 }
 
 const GLOB_CHARS = /[*?[\]{}]/;
@@ -90,9 +135,9 @@ const GLOB_CHARS = /[*?[\]{}]/;
  * fffind: a pattern without glob characters is a fuzzy, typo-tolerant, frecency-ranked path query.
  * Returns "path" rows (best first) or null when the pattern is a real glob.
  */
-export async function fuzzyFind(index, root, cwd, pattern, limit = 20) {
+export async function fuzzyFind(index, root, cwd, pattern, limit = 20, pendingPaths = []) {
   if (!pattern || GLOB_CHARS.test(pattern)) return null;
-  const files = await index.files(root);
+  const files = [...new Set([...await candidateFileList(index, root), ...pendingInScope(root, pendingPaths)])];
 
   if (!index.canScan(files)) return null;
   const rel = files.map((f) => relativeSlash(cwd, f));
@@ -109,12 +154,12 @@ export async function fuzzyFind(index, root, cwd, pattern, limit = 20) {
 }
 
 /** fff-style grep: smart-case, definition lines first, fuzzy fallback when the literal has no hits. */
-export async function grepIndexed(index, pattern, params, searchPath, cwd) {
+export async function grepIndexed(index, pattern, params, searchPath, cwd, overlayText = () => undefined, pendingPaths = []) {
   const compiled = grepRegex(pattern, params);
 
   if (!compiled) return null;
   const { regex, caseSensitive } = compiled;
-  let files = await index.files(searchPath);
+  let files = [...new Set([...await candidateFileList(index, searchPath), ...pendingInScope(searchPath, pendingPaths)])];
 
   if (!index.canScan(files)) return null;
 
@@ -123,14 +168,19 @@ export async function grepIndexed(index, pattern, params, searchPath, cwd) {
     files = files.filter((f) => matcher.test(relativeSlash(cwd, f)));
   }
 
-  const rows = index.grepRows(files, regex, cwd);
-  const fallback = rows.length === 0 && /^[\w$.-]{4,}$/.test(pattern) ? fuzzyGrepRows(index, files, pattern, cwd, caseSensitive) : rows;
+  for (const file of files) {
+    const overlay = overlayText(file);
+
+    if (overlay === undefined && index.entry(file) === null) return null;
+  }
+  const rows = index.grepRows(files, regex, cwd, overlayText);
+  const fallback = rows.length === 0 && /^[\w$.-]{4,}$/.test(pattern) ? fuzzyGrepRows(index, files, pattern, cwd, caseSensitive, overlayText) : rows;
 
   return formatGrepRows(fallback, grepLimit(params));
 }
 
 function grepLimit(params) {
-  return Number.isInteger(params?.limit) && params.limit > 0 ? params.limit : 200;
+  return Number.isInteger(params?.limit) && params.limit > 0 ? Math.min(params.limit, 2000) : 200;
 }
 
 function grepRegex(pattern, params) {
@@ -144,12 +194,15 @@ function grepRegex(pattern, params) {
 }
 
 /** Zero literal hits: retry each line fuzzily (1 typo, 2 for long names) within a tight span, so IsOffTheRecord finds is_off_the_record. */
-function fuzzyGrepRows(index, files, pattern, cwd, caseSensitive) {
+function fuzzyGrepRows(index, files, pattern, cwd, caseSensitive, overlayText = () => undefined) {
   const maxTypos = pattern.length >= 8 ? 2 : 1;
   const rows = [];
 
   for (const filePath of files) {
-    const e = index.entry(filePath);
+    const pending = overlayText(filePath);
+    const e = pending === undefined
+      ? index.entry(filePath)
+      : Buffer.byteLength(pending, "utf8") <= 512 * 1024 ? WorkspaceIndex.fromText(filePath, pending) : null;
 
     if (!e) continue;
     const { raw, defNames } = WorkspaceIndex.linesOf(e);
@@ -197,8 +250,8 @@ function formatGrepRows(rows, limit) {
 }
 
 /** rg --files [-g pattern] served from the index; null when the tree is too large. */
-export async function listIndexed(index, root, cwd, pattern) {
-  const files = await index.files(root);
+export async function listIndexed(index, root, cwd, pattern, pendingPaths = []) {
+  const files = [...new Set([...await candidateFileList(index, root), ...pendingInScope(root, pendingPaths)])];
 
   if (!index.canScan(files)) return null;
   const rel = files.map((f) => path.relative(cwd, f).split(path.sep).join("/"));

package/src/context/snap.js

@@ -3,6 +3,8 @@ import { isString } from "../shared/decode.js";
 import { truncateChars } from "../output/format.js";
 import * as fs from "node:fs/promises";
 import { extractStructuralSurface } from "./surface.js";
+import { WorkspaceIndex } from "./repo-index.js";
+import { pickSpan, spanCandidate, spanWindow } from "./spans.js";
 import { rankPaths } from "./fuzzy.js";
 import { isTestPath, runCommand, relativeSlash } from "../fs/workspace.js";
 
@@ -18,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. */
@@ -80,21 +84,25 @@ 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 };
+    line: 1, signature: "", context: new Map(), recent: [], anchorScore: -1, exactLines: new Set() };
 }
 
-function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
+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 => lower.includes(token));
+    const matches = tokens.filter((token, index) => lower.includes(needles[index] ?? token));
 
     for (const token of matches) candidate.matched.add(token);
     const ext = path.extname(candidate.path).toLowerCase();
@@ -106,7 +114,7 @@ function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
     for (const item of items) {
       const name = item.name.toLowerCase();
       const itemExact = name === query.toLowerCase();
-      const coverage = tokens.filter(token => name.includes(token)).length;
+      const coverage = tokens.filter((token, index) => name.includes(needles[index] ?? token)).length;
 
       if (itemExact || coverage > definitionCoverage) { declaration = item; definitionCoverage = coverage; exact = itemExact; }
 
@@ -115,6 +123,8 @@ function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
 
     const score = (exact ? 10000 : 0) + definitionCoverage * 40 + matches.length;
 
+    if (exact) candidate.exactLines.add(lineNumber);
+
     if (score > candidate.anchorScore) {
       candidate.anchorScore = score;
       candidate.line = lineNumber;
@@ -136,33 +146,47 @@ 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 = [];
-
-  for (let i = 0; i < lines.length; i++) if (needles.some(needle => lines[i].toLowerCase().includes(needle))) matches.push(i);
-
-  for (const i of matches) inspectLine(candidate, i + 1, lines[i], query, tokens, true);
-  candidate.context.clear();
+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 = 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);
+  return truncated;
 }
 
-async function contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles }) {
-  const needles = exact ? [query.toLowerCase()] : tokens;
+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 needles) args.push("-e", needle);
-  args.push("--", dir);
+  for (const needle of searchNeedles) args.push("-e", needle);
+  args.push("--", focusFile ?? dir);
 
-  const response = diskFiles ? await run(args, { cwd: dir, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS, signal })
+  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 candidates = new Map();
   const records = response.stdout.split("\n");
 
   for (let i = 0; i < records.length; i++) {
@@ -186,24 +210,26 @@ async function contentCandidates({ dir, includeHidden, query, tokens, flags, pen
     let candidate = candidates.get(filePath);
 
     if (!candidate) {
-      candidate = makeCandidate(filePath, dir, query, tokens, flags);
+      candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
       candidates.set(filePath, candidate);
     }
 
-    inspectLine(candidate, data.line_number, data.lines.text, query, tokens, record.type === "match");
+    inspectLine(candidate, data.line_number, data.lines.text, query, tokens, needles, record.type === "match");
   }
 
+  let overlayTruncated = false;
+
   for (const filePath of pendingPaths) {
     const pending = overlayText(filePath);
 
     if (pending === undefined) continue;
-    const candidate = makeCandidate(filePath, dir, query, tokens, flags);
-    inspectOverlay(candidate, pending, needles, query, tokens);
+    const candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
+    overlayTruncated = inspectOverlay(candidate, pending, needles, query, tokens, signal) || overlayTruncated;
 
     if (candidate.matched.size) candidates.set(filePath, candidate);
   }
 
-  return { candidates, truncated: response.outputTruncated === true };
+  return { candidates, truncated: response.outputTruncated === true || overlayTruncated };
 }
 
 function rankScore(candidate, tokenCount) {
@@ -220,13 +246,61 @@ 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, signal) {
+  const staged = overlayText(filePath);
+  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, end));
+  });
+}
+
+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];
+    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 (error) { 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 }) {
   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());
 
@@ -235,15 +309,21 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
   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;
+  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 false;
+    return null;
   });
 
-  const empty = { path: null, line: null, signature: "", confidence: 0, context: [] };
+  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);
-  const search = await contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles });
+
+  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));
@@ -254,26 +334,27 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
 
   if (listing.exitCode !== 0 && listing.exitCode !== 1) throw new Error("source file listing failed: " + listing.stderr.trim());
 
-  const paths = [...new Set([...listing.stdout.split("\0").flatMap(file => file ? [path.resolve(dir, file)] : []), ...pendingPaths])]
+  const paths = [...new Set([...listing.stdout.split("\0").flatMap(file => file ? [path.resolve(dir, file)] : []), ...(focusFile ? [focusFile] : []), ...pendingPaths])]
     .filter(file => inScope(file, dir, includeHidden));
+  const candidateRoot = focusFile ? path.dirname(focusFile) : dir;
 
   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 (exact && tokens.length > 1 && !relative.includes(query.toLowerCase())) continue;
-    const candidate = makeCandidate(filePath, dir, query, tokens, flags);
+    const candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
 
-    if (candidate.pathScore > 0) search.candidates.set(filePath, candidate);
+    if (focusFile || candidate.pathScore > 0) search.candidates.set(filePath, candidate);
   }
 
   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) {
+      ranked.push({ ...candidate, score: focusFile ? Math.max(1, rankScore(candidate, tokens.length)) : rankScore(candidate, tokens.length) });
     }
   }
 
@@ -306,7 +387,14 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
   const coverage = Math.max(best.matched.size, best.pathCoverage) / tokens.length;
   const uniqueExact = best.exactDefinition && !second?.exactDefinition || best.exactPath && !second?.exactPath && !second?.exactDefinition;
 
-  if (!uniqueExact && (coverage < 0.6 || margin < 0.15 || best.definitionCoverage / tokens.length < 0.5)) return { ...empty, status: "ambiguous", candidates };
+  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) };
+  }
+
+  if (best.exactLines.size > 1) {
+    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)) };

package/src/context/spans.js

@@ -0,0 +1,39 @@
+import { truncateChars } from "../output/format.js";
+
+export function pickSpan(spans, { line, name } = {}) {
+  const needle = typeof name === "string" && /^[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];
+  if (!line) return;
+
+  return spans.find(item => item.start === line)
+    ?? spans.filter(item => item.start <= line && line <= item.end).sort((a, b) => (a.end - a.start) - (b.end - b.start))[0];
+}
+
+export function spanWindow(text, start, end) {
+  const raw = text.split("\n");
+
+  return {
+    start,
+    end,
+    text: raw.slice(start - 1, end).join("\n"),
+    signature: truncateChars((raw[start - 1] ?? "").trim().replace(/\{.*$/, "").trim(), 240, "signature").text,
+    context: Array.from({ length: Math.max(0, end - start + 1) }, (_, i) => {
+      const n = start + i;
+
+      return { line: n, text: raw[n - 1] ?? "" };
+    }),
+  };
+}
+
+export function spanCandidate(relPath, line, window) {
+  return {
+    path: relPath,
+    line,
+    lines: [window.start, window.end],
+    text: window.text,
+    signature: window.signature,
+    context: window.context.map(row => (row.line === line ? "►" : " ") + row.line + " " + row.text),
+  };
+}

package/src/context/surface.js

@@ -8,14 +8,20 @@ function scanPython(lines) {
     const line = lines[i];
     const match = /^([ \t]*)(def|class|async def)\s+([a-zA-Z0-9_]+)(\(.*?\))?:?/.exec(line);
 
-    if (!match) continue;
-    items.push({
-      kind: match[2].includes("def") ? "function" : "class",
-      name: match[3],
-      signature: match[0].trim(),
-      line: i + 1,
-      depth: Math.floor(match[1].length / 4),
-    });
+    if (match) {
+      items.push({
+        kind: match[2].includes("def") ? "function" : "class",
+        name: match[3],
+        signature: match[0].trim(),
+        line: i + 1,
+        depth: Math.floor(match[1].length / 4),
+      });
+      continue;
+    }
+
+    const constant = /^([ \t]*)([A-Z][A-Z0-9_]*)\s*(?::[^=\n]+)?=/.exec(line);
+
+    if (constant && constant[1].length === 0) items.push({ kind: "constant", name: constant[2], signature: constant[0].replace(/=\s*$/, "=").trim(), line: i + 1, depth: 0 });
   }
 
   return items;
@@ -81,10 +87,10 @@ const JS_DECL_PATTERNS = [
 // Module-level tables/constants (column 0 only): without them the previous declaration's span swallows them.
 const JS_TOP_LEVEL_BINDING = /^(const|let|var)\s+([a-zA-Z0-9_$]+)\s*=/;
 
-// Indented methods (object-literal adapters, class members) that open a block on the same line.
-const JS_METHOD = /^(?:static\s+)?(?:async\s+)?(?:get\s+|set\s+)?\*?([a-zA-Z_$][\w$]*)\s*\([^()]*\)\s*\{$/;
+// Indented methods (object-literal adapters, class members), including one-liners.
+const JS_METHOD = /^(?:static\s+)?(?:async\s+)?(?:get\s+|set\s+)?\*?([a-zA-Z_$][\w$]*)\s*\([^()]*\)\s*\{/;
 
-const JS_ARROW_PROPERTY = /^([a-zA-Z_$][\w$]*)\s*[:=]\s*(?:async\s+)?(?:\([^()]*\)|[a-zA-Z_$][\w$]*)\s*=>\s*\{$/;
+const JS_ARROW_PROPERTY = /^([a-zA-Z_$][\w$]*)\s*[:=]\s*(?:async\s+)?(?:\([^()]*\)|[a-zA-Z_$][\w$]*)\s*=>\s*\{/;
 
 const NOT_METHOD_NAMES = new Set(["if", "for", "while", "switch", "catch", "function", "return", "else", "do", "try", "with", "await", "typeof", "new", "constructor"]);
 
@@ -93,16 +99,18 @@ function methodItem(line, lineNumber, depth) {
 
   if (!match || NOT_METHOD_NAMES.has(match[1])) return null;
 
-  return { kind: "method", name: match[1], isExport: false, signature: line.replace(/\s*\{$/, ""), line: lineNumber, depth };
+  return { kind: "method", name: match[1], isExport: false, signature: line.replace(/\s*\{.*$/, "").trim(), line: lineNumber, depth };
 }
 
 function declarationItem(line, rawLine, lineNumber) {
+  const indent = rawLine.length - rawLine.trimStart().length;
+  const depth = Math.floor(indent / 2);
   const patterns = /^\S/.test(rawLine) ? [...JS_DECL_PATTERNS, [JS_TOP_LEVEL_BINDING, false]] : JS_DECL_PATTERNS;
 
   for (const [pattern, isExport] of patterns) {
     const match = pattern.exec(line);
 
-    if (match) return { kind: match[1], name: match[2], isExport, signature: line.replace(/\{.*$/, "").trim(), line: lineNumber, depth: 0 };
+    if (match) return { kind: match[1], name: match[2], isExport, signature: line.replace(/\{.*$/, "").trim(), line: lineNumber, depth };
   }
 
   return null;
@@ -116,7 +124,7 @@ function scanJavaScript(lines) {
 
     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, 1) : null);
+    const item = declarationItem(line, lines[i], i + 1) || (indent > 0 && indent <= 8 ? methodItem(line, i + 1, Math.max(1, Math.floor(indent / 2))) : null);
 
     if (item) items.push(item);
   }
@@ -139,7 +147,7 @@ const SCANNERS = {
 export function extractStructuralSurface(code, extension = "js") {
   if (!isString(code) || !code.trim()) return { items: [], lineCount: 0 };
   const lines = code.split("\n");
-  const ext = extension.replace(/^\./, "").toLowerCase();
+  const ext = String(extension ?? "").replace(/^\./, "").toLowerCase();
   const scanner = SCANNERS[ext] || SCANNERS.js;
   const items = scanner(lines);
 

package/src/fs/check.js

@@ -60,7 +60,7 @@ function skipComment(text, i) {
 
   const end = text.indexOf("*/", i + 2);
 
-  return end < 0 ? text.length : end + 2;
+  return end < 0 ? -1 : end + 2;
 }
 
 function skipRegex(text, i) {
@@ -126,7 +126,13 @@ function consumeLiteral(text, i, stack, prev) {
 
   if (c !== "/") return null;
 
-  if (text[i + 1] === "/" || text[i + 1] === "*") return { end: skipComment(text, i), prev };
+  if (text[i + 1] === "/" || text[i + 1] === "*") {
+    const end = skipComment(text, i);
+
+    if (end < 0) return { error: "unterminated comment", at: i };
+
+    return { end, prev };
+  }
 
   if (prev !== "" && !REGEX_PRECEDERS.has(prev)) return null;
   const end = skipRegex(text, i);
@@ -190,6 +196,8 @@ const CODE_EXT = new Set([".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".mts",
 
 /** { ok: true } | { ok: false, message }; message names the problem and line. */
 export function quickCheck(text, ext) {
+  ext = String(ext ?? "").toLowerCase();
+
   if (ext === ".json") {
     try {
       JSON.parse(text);

package/src/fs/json-read.js

@@ -43,7 +43,11 @@ export function jsonProjector(json) {
   return function* (root) {
     for (const steps of plans) yield steps.reduce((value, step) => {
       if (step.key !== undefined) {
-        if (!isObject(value) || !Object.hasOwn(value, step.key)) throw new Error("JSON field not found: " + JSON.stringify(step.key));
+        if (!isObject(value) || !Object.hasOwn(value, step.key)) {
+          const keys = isObject(value) ? Object.keys(value) : [];
+          const preview = keys.length ? "; available keys: " + keys.slice(0, 24).map(key => JSON.stringify(key)).join(", ") + (keys.length > 24 ? ", …" : "") : "";
+          throw new Error("JSON field not found: " + JSON.stringify(step.key) + preview);
+        }
 
         return value[step.key];
       }