pi-supernova 0.10.2 → 0.11.0

package/src/context/outline.js

@@ -27,9 +27,15 @@ function relevance(span, lower, stems) {
   return score;
 }
 
-function chooseExpanded(spans, lower, stems, raw, opts) {
-  if (stems.length === 0) return new Set();
-  const scored = spans.map((s, i) => ({ i, r: relevance(s, lower, stems), chars: raw.slice(s.start - 1, s.end).join("\n").length }));
+function chooseExpanded(spans, lower, stems, raw, opts, about) {
+  const indexed = spans.map((s, i) => ({ s, i }));
+  const name = String(about ?? "").trim().toLowerCase();
+  const exact = indexed.filter(({ s }) => s.name.toLowerCase() === name);
+
+  if (stems.length === 0 && exact.length === 0) return new Set();
+  // Ancestors accumulate descendant hits, but must not outvote an exact symbol.
+  const candidates = exact.length ? exact : indexed;
+  const scored = candidates.map(({ s, i }) => ({ i, r: relevance(s, lower, stems), chars: raw.slice(s.start - 1, s.end).join("\n").length }));
   scored.sort((a, b) => b.r - a.r || a.i - b.i);
   const expanded = new Set();
   let budget = opts.maxChars;
@@ -54,11 +60,11 @@ function foldedLine(span) {
   return String(span.start).padStart(5) + " " + sig + (body > 0 ? " … " + body + " lines" : "");
 }
 
-function expandedBlock(span, raw, opts) {
+function expandedBlock(span, raw, opts, names) {
   const out = [];
 
   for (let l = span.start; l <= span.end; l++) out.push(String(l).padStart(5) + " " + raw[l - 1]);
-  const refs = opts.references ? opts.references(span.name, span.start) : [];
+  const refs = opts.references ? opts.references(span.name, span.start, names) : [];
 
   // Who uses this declaration: the relation a reader would otherwise grep for next.
   if (refs.length) out.push("      // used by: " + refs.slice(0, opts.maxRefs).join(", ") + (refs.length > opts.maxRefs ? " (+" + (refs.length - opts.maxRefs) + ")" : ""));
@@ -127,12 +133,30 @@ export function outlineFile(entry, relPath, about, options = {}) {
   const stems = [...new Set(tokenizeQuery(about || "").tokens.map(stem))];
 
   if (spans.length === 0) return about ? focusedText(raw, lower, stems, relPath, opts) : null;
-  const expanded = chooseExpanded(spans, lower, stems, raw, opts);
-  const parts = outlineHeader(spans, raw, opts);
+  const expanded = chooseExpanded(spans, lower, stems, raw, opts, about);
+  const header = outlineHeader(spans, raw, opts);
+  const parts = [...header];
+  const focused = [];
+  const names = [...expanded].map(i => spans[i].name);
+
+  for (let i = 0; i < spans.length; i++) {
+    const body = expanded.has(i) ? expandedBlock(spans[i], raw, opts, names) : null;
+    parts.push(body ?? foldedLine(spans[i]));
+
+    if (body !== null) focused.push(body);
+  }
 
-  for (let i = 0; i < spans.length; i++) parts.push(expanded.has(i) ? expandedBlock(spans[i], raw, opts) : foldedLine(spans[i]));
   const label = about ? String(about).replace(/\s+/g, " ").slice(0, 120) : "";
   const title = "// " + relPath + " · " + lineCount + " lines · " + spans.length + " declarations · " + expanded.size + " expanded" + (label ? " for \"" + label + "\"" : "") + " · read(path, line, count) for a folded body";
 
-  return { text: clipOutline(title + "\n" + parts.join("\n"), title, opts.maxChars), expanded: expanded.size, declarations: spans.length };
+  let text = title + "\n" + parts.join("\n");
+
+  if (text.length > opts.maxChars && focused.length) {
+    // Navigation may be clipped; requested code must not lose to preceding folds.
+    const navigation = [...header, ...spans.map(foldedLine)];
+    text = title + "\n// focused bodies first; declaration map follows\n" + focused.join("\n")
+      + "\n// declaration map (bodies folded)\n" + navigation.join("\n");
+  }
+
+  return { text: clipOutline(text, title, opts.maxChars), expanded: expanded.size, declarations: spans.length };
 }

package/src/context/query.js

@@ -32,12 +32,15 @@ export function stem(token) {
 export function tokenizeQuery(query) {
   if (!isString(query) || !query.trim()) return { tokens: [], wantsTest: false, wantsType: false, wantsDoc: false };
   const words = query.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-zA-Z0-9_]+/);
+  // A document filename is one literal anchor, not a generic extension hit.
+  const document = /^[\w./\\-]+\.(?:md|mdx|rst|txt)$/i.test(query.trim());
 
   return {
-    tokens: [...new Set(words.filter(word => word.length > 1 && !STOP_WORDS.has(word)))],
+    tokens: document ? [query.trim().toLowerCase().replaceAll("\\", "/")]
+      : [...new Set(words.filter(word => word.length > 1 && !STOP_WORDS.has(word)))],
     wantsTest: words.some(word => TEST_WORDS.has(word)),
     wantsType: words.some(word => TYPE_WORDS.has(word)),
-    wantsDoc: words.some(word => DOC_WORDS.has(word)),
+    wantsDoc: document || words.some(word => DOC_WORDS.has(word)),
   };
 }
 
@@ -62,6 +65,7 @@ function topologyPenalty(normalized, flags) {
   const test = isTestPath(normalized);
 
   if (test && !flags.wantsTest) return -50;
+
   if (!test && flags.wantsTest) return -20;
 }
 
@@ -77,4 +81,5 @@ export function scorePathTopology(filePath, tokens, flags) {
 
   return score + tokenPathScore(path.basename(normalized), normalized.split(/[^a-zA-Z0-9]+/), normalized, tokens);
 }
+
 export { SOURCE_EXT, MAX_NEEDLE_CHARS };

package/src/context/repo-index.js

@@ -1,5 +1,7 @@
 export {globToRegExp} from '../fs/glob.js';
+
 export {declaredName} from './source-entry.js';
+
 import {fromText,linesOf,spansOf,surfaceOf} from './source-entry.js';
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -24,6 +26,7 @@ const WATCH_DEBOUNCE_MS = 150;
 const MAX_INDEXED_FILES = 4000;
 
 const MAX_FILE_BYTES = 512 * 1024;
+
 const MAX_ENTRY_CACHE_BYTES = 64 * 1024 * 1024;
 
 const BINARY_EXT = new Set([
@@ -54,9 +57,9 @@ function parseRgFiles(res, root) {
 
   if (res.exitCode !== 0 && res.exitCode !== 1) error = res.stderr.trim() || "rg exited with status " + res.exitCode;
   const truncated = res.outputTruncated === true;
-  const output = truncated && !res.stdout.endsWith("\n") ? res.stdout.slice(0, res.stdout.lastIndexOf("\n") + 1) : res.stdout;
+  const output = truncated && !res.stdout.endsWith("\0") ? res.stdout.slice(0, res.stdout.lastIndexOf("\0") + 1) : res.stdout;
 
-  return { files: output.split("\n").flatMap(f => f ? [path.resolve(root, f)] : []).sort(), error, truncated, missing: false };
+  return { files: output.split("\0").flatMap(f => f ? [path.resolve(root, f)] : []).sort(), error, truncated, missing: false };
 }
 
 function addPorcelainRow(rows, i, set) {
@@ -95,7 +98,9 @@ function grepPendingHuge(pending, rel, regex, out) {
     const text = pending.slice(start, stop).replace(/\r$/, "");
 
     line++;
+
     if (regex.test(text)) out.push({ rel, line, text, def: false });
+
     if (end === -1) break;
     start = end + 1;
   }
@@ -223,7 +228,7 @@ export class WorkspaceIndex {
   }
 
   async listFilesWithRg(root, includeHidden, signal) {
-    const args = ["rg", "--files"];
+    const args = ["rg", "--files", "--null"];
 
     if (includeHidden) args.push("--hidden");
     args.push("-g", "!.git/**", "-g", "!**/.git/**", "--", root);

package/src/context/search-files.js

@@ -16,4 +16,24 @@ function overlaySearchEntry(index, filePath, overlayText) {
     ? index.entry(filePath)
     : Buffer.byteLength(pending, "utf8") <= 512 * 1024 ? WorkspaceIndex.fromText(filePath, pending) : null;
 }
+
+// Resolve filesystem aliases once per distinct candidate, not per matching line.
+// The snapshot is call-local; synchronous index/scoring code never sees promises.
+export async function overlaySnapshot(files, overlayText, signal) {
+  const paths = [...new Set(files)], values = new Map();
+
+  for (let i = 0; i < paths.length; i += 8) {
+    signal?.throwIfAborted();
+    await Promise.all(paths.slice(i, i + 8).map(async file => {
+      const value = await overlayText(file);
+
+      if (value !== undefined) values.set(file, value);
+    }));
+  }
+
+  signal?.throwIfAborted();
+
+  return file => values.get(file);
+}
+
 export { pendingInScope, overlaySearchEntry };

package/src/context/search.js

@@ -1,5 +1,5 @@
 import {textResult} from '../shared/result.js';
-import {pendingInScope,overlaySearchEntry} from './search-files.js';
+import {pendingInScope,overlaySearchEntry,overlaySnapshot} from './search-files.js';
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isString } from "../shared/decode.js";
@@ -36,7 +36,9 @@ function applyMatchRecord(record, root, overlayText, add) {
   if (overlayText(file) === undefined) add(file, record.data.line_number, record.data.lines.text);
 }
 
-function ingestRgMatches(records, result, signal, root, overlayText, add) {
+async function ingestRgMatches(records, result, signal, root, overlayText, add, pendingPaths) {
+  const matches = [];
+
   for (let i = 0; i < records.length; i++) {
     signal?.throwIfAborted();
     const parsed = parseMatchRecord(records[i], result.outputTruncated, i === records.length - 1);
@@ -44,8 +46,15 @@ function ingestRgMatches(records, result, signal, root, overlayText, add) {
     if (parsed.stop) break;
 
     if (parsed.skip) continue;
-    applyMatchRecord(parsed.record, root, overlayText, add);
+
+    if (isRgMatch(parsed.record)) matches.push(parsed.record);
   }
+
+  const snapshot = await overlaySnapshot([...pendingPaths, ...matches.map(record => path.resolve(root, record.data.path.text))], overlayText, signal);
+
+  for (const record of matches) applyMatchRecord(record, root, snapshot, add);
+
+  return snapshot;
 }
 
 function ingestPendingRefs(root, pendingPaths, overlayText, add) {
@@ -75,8 +84,8 @@ export async function referencesForNames({ root, names, excludePath, overlayText
     { cwd: root, signal, timeoutMs: 5000, maxOutputChars: 65536 });
 
   if (result.exitCode !== 0 && result.exitCode !== 1) throw new Error(result.stderr.trim() || "reference search failed");
-  ingestRgMatches(result.stdout.split("\n"), result, signal, root, overlayText, add);
-  ingestPendingRefs(root, pendingPaths, overlayText, add);
+  const snapshot = await ingestRgMatches(result.stdout.split("\n"), result, signal, root, overlayText, add, pendingPaths);
+  ingestPendingRefs(root, pendingPaths, snapshot, add);
 
   return { references, incomplete: result.outputTruncated === true };
 }
@@ -88,6 +97,8 @@ function grepCaseSensitive(pattern, params) {
 function pushGrepFlags(args, pattern, params) {
   if (!grepCaseSensitive(pattern, params)) args.push("--ignore-case");
 
+  if (params?.literal === true) args.push("--fixed-strings");
+
   if (params?.glob) args.push("--glob", String(params.glob));
   const limit = params?.limit;
 
@@ -120,15 +131,16 @@ function listDirectRows(stat, searchDir, cwd, pending, matcher) {
 }
 
 function mergeListStdout(stdout, cwd, pendingMerged) {
-  const diskRows = String(stdout || "").split("\n").filter(Boolean)
+  const diskRows = String(stdout || "").split("\0").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" : "";
 }
 
 async function listDisk(searchDir, pattern, cwd, signal) {
-  const args = ["--files"];
+  const args = ["--files", "--null"];
 
   if (pattern) args.push("-g", pattern);
   const res = await runCommand(["rg", ...args, searchDir], { cwd, timeoutMs: 30_000, signal }).catch(() => null);
@@ -137,6 +149,7 @@ async function listDisk(searchDir, pattern, cwd, signal) {
   const findArgs = [searchDir];
 
   if (pattern) findArgs.push("-name", pattern);
+  findArgs.push("-print0");
   const findRes = await runCommand(["find", ...findArgs], { cwd, timeoutMs: 30_000, signal });
 
   return { stdout: findRes.stdout, via: "find", outputTruncated: findRes.outputTruncated === true };
@@ -155,7 +168,7 @@ export async function listWithTools(searchDir, pattern, cwd, signal, pendingPath
     return textResult(rows.length ? rows.join("\n") + "\n" : "", { via: pending.length ? "vfs" : "file" });
   }
 
-  const pendingMerged = pendingAbs.filter((_, i) => !matcher || matcher.test(pending[i]));
+  const pendingMerged = pending.filter(file => !matcher || matcher.test(file));
   const listed = await listDisk(searchDir, pattern, cwd, signal);
 
   return textResult(mergeListStdout(listed.stdout, cwd, pendingMerged), { via: listed.via, outputTruncated: listed.outputTruncated });
@@ -212,10 +225,11 @@ export async function grepIndexed(index, pattern, params, searchPath, cwd, overl
 
   if (!index.canScan(files)) return null;
   files = applyGlob(files, params, cwd);
+  overlayText = await overlaySnapshot(files, overlayText);
 
   if (!filesReadable(index, files, overlayText)) 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;
+  const fallback = rows.length === 0 && params?.literal !== true && /^[\w$.-]{4,}$/.test(pattern) ? fuzzyGrepRows(index, files, pattern, cwd, caseSensitive, overlayText) : rows;
 
   return formatGrepRows(fallback, grepLimit(params));
 }
@@ -226,9 +240,10 @@ function grepLimit(params) {
 
 function grepRegex(pattern, params) {
   const caseSensitive = params?.caseSensitive === true || (params?.caseSensitive !== false && smartCase(pattern));
+  const source = params?.literal === true ? pattern.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&") : pattern;
 
   try {
-    return { regex: new RegExp(pattern, caseSensitive ? "" : "i"), caseSensitive };
+    return { regex: new RegExp(source, caseSensitive ? "" : "i"), caseSensitive };
   } catch {
     return null;
   }

package/src/context/snap-search.js

@@ -1,5 +1,6 @@
 import * as path from 'node:path';
 import {isString} from '../shared/decode.js';
+import {overlaySnapshot} from './search-files.js';
 import {truncateChars} from '../output/format.js';
 import {extractStructuralSurface} from './surface.js';
 import {scorePathTopology,stem,SOURCE_EXT,MAX_NEEDLE_CHARS} from './query.js';
@@ -43,6 +44,7 @@ function bestDeclaration(items, query, tokens, needles) {
     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;
   }
 
@@ -102,6 +104,7 @@ function inspectOverlay(candidate, text, needles, query, tokens, signal) {
       const lower = row.toLowerCase();
       inspectLine(candidate, line, row, query, tokens, needles, needles.some(needle => lower.includes(needle)));
     }
+
     start = end;
     line++;
   }
@@ -157,6 +160,7 @@ function rgSearchArgs(includeHidden, searchNeedles, focusFile, dir) {
 
   if (includeHidden) args.push("--hidden");
   args.push("-g", "!.git/**", "-g", "!**/.git/**");
+
   for (const needle of searchNeedles) args.push("-e", needle);
   args.push("--", focusFile ?? dir);
 
@@ -165,7 +169,8 @@ function rgSearchArgs(includeHidden, searchNeedles, focusFile, dir) {
 
 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)
+
+  const response = diskFiles || (focusFile && await overlayText(focusFile) === undefined)
     ? await run(args, { cwd: focusFile ? path.dirname(focusFile) : dir, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS, signal })
     : { stdout: "", stderr: "", exitCode: 1 };
 
@@ -174,17 +179,33 @@ async function runContentSearch({ dir, includeHidden, searchNeedles, run, overla
   return response;
 }
 
-function absorbRgRecords(candidates, response, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles, signal) {
-  const records = response.stdout.split("\n");
+async function absorbRgRecords(candidates, response, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles, signal, pendingPaths) {
+  const records = response.stdout.split("\n"), parsed = [];
 
   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, candidateNeedles);
+    parsed.push(record);
   }
+
+  const files = [];
+
+  for (const record of parsed) {
+    if ((record.type !== "match" && record.type !== "context") || !isString(record.data?.path?.text)) continue;
+    const file = path.resolve(dir, record.data.path.text);
+
+    if (inScope(file, dir, includeHidden)) files.push(file);
+  }
+
+  const snapshot = await overlaySnapshot([...pendingPaths, ...files], overlayText, signal);
+
+  for (const record of parsed) absorbRgHit(candidates, record, dir, includeHidden, snapshot, candidateRoot, query, tokens, flags, needles, candidateNeedles);
+
+  return snapshot;
 }
 
 async function contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles, focusFile }) {
@@ -195,9 +216,10 @@ async function contentCandidates({ dir, includeHidden, query, tokens, flags, pen
   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, candidateNeedles, signal);
-  const overlayTruncated = overlayCandidates(candidates, pendingPaths, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles, signal);
+  const snapshot = await absorbRgRecords(candidates, response, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles, signal, pendingPaths);
+  const overlayTruncated = overlayCandidates(candidates, pendingPaths, snapshot, candidateRoot, query, tokens, flags, needles, candidateNeedles, signal);
 
   return { candidates, truncated: response.outputTruncated === true || overlayTruncated };
 }
+
 export { inScope, makeCandidate, contentCandidates, MAX_SEARCH_CHARS };

package/src/context/snap.js

@@ -1,5 +1,6 @@
 import {inScope,makeCandidate,contentCandidates,MAX_SEARCH_CHARS} from './snap-search.js';
 import { tokenizeQuery, stem } from "./query.js";
+import { looksLikePath } from "../shared/decode.js";
 
 export {tokenizeQuery,scorePathTopology,stem} from './query.js';
 
@@ -29,7 +30,7 @@ function location(candidate, root) {
 }
 
 async function spanCandidates(filePath, lines, root, overlayText, signal) {
-  const staged = overlayText(filePath);
+  const staged = await overlayText(filePath);
   const rel = relativeSlash(root, filePath);
   let text = staged;
 
@@ -61,7 +62,7 @@ async function rankedSpanCandidates(ranked, root, overlayText, signal) {
 
   for (const candidate of ranked) {
     const lines = candidate.exactLines?.size ? [...candidate.exactLines].sort((a, b) => a - b) : [candidate.line];
-    const staged = overlayText(candidate.path);
+    const staged = await overlayText(candidate.path);
     let large = false;
 
     if (staged !== undefined) large = Buffer.byteLength(staged) > 512 * 1024;
@@ -234,9 +235,13 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
 
 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.
+  // Filename queries still need exact file candidates when references matched.
   // 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 needsPaths = looksLikePath(query) || !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 });

package/src/context/source-entry.js

@@ -1,5 +1,6 @@
 import * as path from 'node:path';
 import {extractStructuralSurface} from './surface.js';
+import { braceBlockEndLine } from "../fs/check.js";
 
 const IDENT_TOKEN = /[A-Za-z_$][\w$]*/g;
 
@@ -18,48 +19,83 @@ function lineIndent(raw, i) {
   return raw[i].length - raw[i].trimStart().length;
 }
 
-function pythonDeclarationEnd(raw, lower, start, lineCount) {
-  const base = lineIndent(raw, start - 1);
-  let end = start;
+function pythonHeaderEnd(raw, start, lineCount, suite = true) {
+  let depth = 0;
+  let quote = "";
+  let escape = false;
 
-  for (let i = start; i < lineCount; i++) {
-    if (lower[i] === "") { end = i + 1; continue; }
-    if (lineIndent(raw, i) <= base) break;
-    end = i + 1;
-  }
+  for (let i = start - 1; i < lineCount; i++) {
+    let statement = raw[i].trimEnd();
 
-  return Math.min(end, lineCount);
-}
+    for (let j = 0; j < statement.length; j++) {
+      const ch = statement[j];
 
-function braceDelta(text) {
-  let depth = 0;
+      if (quote) {
+        if (escape) { escape = false; continue; }
 
-  for (const ch of text) {
-    if (ch === "{") depth++;
-    else if (ch === "}") depth--;
-  }
+        if (ch === "\\") { escape = true; continue; }
 
-  return depth;
-}
+        if (statement.startsWith(quote, j)) {
+          j += quote.length - 1;
+          quote = "";
+        }
+
+        continue;
+      }
 
-function braceDeclarationEnd(raw, start, lineCount) {
-  let depth = braceDelta(raw[start - 1] ?? "");
+      // Comments only start outside strings; triple-quoted payload persists
+      // across physical lines and closes on its full delimiter.
+      if (ch === "#") { statement = statement.slice(0, j).trimEnd(); break; }
 
-  if (depth <= 0) return start;
+      if (ch === "'" || ch === "\"") {
+        quote = statement.startsWith(ch.repeat(3), j) ? ch.repeat(3) : ch;
+        j += quote.length - 1;
+      }
+      else if ("([{".includes(ch)) depth++;
+      else if (")]}".includes(ch)) depth--;
+      else if (suite && ch === ":" && depth === 0) return i + 1;
+    }
 
-  for (let i = start; i < raw.length; i++) {
-    depth += braceDelta(raw[i]);
+    // A backslash escaping a physical newline does not escape the next line's
+    // first character; the quote itself still persists.
+    escape = false;
 
-    if (depth <= 0) return i + 1;
+    // Assignments end at a logical newline, not at a suite-opening colon.
+    if (!suite && depth === 0 && !quote && !statement.endsWith("\\")) return i + 1;
   }
 
   return lineCount;
 }
 
-function declarationEnd(raw, lower, start, lineCount, ext) {
-  if (ext === ".py") return pythonDeclarationEnd(raw, lower, start, lineCount);
+function pythonDeclarationEnd(raw, lower, start, lineCount) {
+  const base = lineIndent(raw, start - 1);
+  // Only a top-level colon ends a header, including a header with an inline
+  // suite. Colons in annotations, defaults and comments are not terminators.
+  let end = pythonHeaderEnd(raw, start, lineCount);
+
+  for (let i = end; i < lineCount; i++) {
+    // Blank and comment-only lines do not dedent a Python suite. Include them
+    // only when a later body line extends the span, preserving neighbor comments.
+    if (lower[i] === "" || lower[i].startsWith("#")) continue;
+
+    if (lineIndent(raw, i) <= base) break;
+    // Dedentation inside a continued expression or string is payload, not a
+    // suite boundary. Resume indentation checks after its logical newline.
+    end = pythonHeaderEnd(raw, i + 1, lineCount, false);
+    i = end - 1;
+  }
+
+  return Math.min(end, lineCount);
+}
+
+const BLOCK_DECLARATIONS = new Set(["function", "function*", "method", "class", "fn", "struct", "enum", "trait", "impl", "interface"]);
+
+function declarationEnd(raw, lower, start, lineCount, ext, kind) {
+  if (String(ext ?? "").toLowerCase() === ".py") return kind === "constant"
+    ? pythonHeaderEnd(raw, start, lineCount, false)
+    : pythonDeclarationEnd(raw, lower, start, lineCount);
 
-  return braceDeclarationEnd(raw, start, lineCount);
+  return Math.min(lineCount, Math.max(start, braceBlockEndLine(raw.join("\n"), start, ext, BLOCK_DECLARATIONS.has(kind))));
 }
 
 export function fromText(filePath, text) {
@@ -94,7 +130,7 @@ export function spansOf(entry) {
 
     for (let i = 0; i < items.length; i++) {
       const start = items[i].line;
-      let end = declarationEnd(raw, lower, start, lineCount, entry.ext);
+      let end = declarationEnd(raw, lower, start, lineCount, entry.ext, items[i].kind);
 
       while (end > start && lower[end - 1] === "") end--;
       spans.push({ start, end, name: items[i].name, kind: items[i].kind, isExport: items[i].isExport === true });

package/src/context/spans.js

@@ -6,6 +6,7 @@ export function pickSpan(spans, { line, name } = {}) {
   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)

package/src/contract/bash.js

@@ -39,11 +39,7 @@ export function normalizeBash(command, opts) {
   if (args.action !== undefined || args.sessionId !== undefined) return normalizeTerminalControl(args);
   assertBashOptions(args);
 
-  for (const key of ["background", "pty"]) {
-    if (args[key] !== undefined && args[key] !== true && args[key] !== false) throw new Error(`bash ${key} must be boolean`);
-  }
-
-  if (args.pty !== undefined && args.background !== true) throw new Error("bash pty requires background:true");
+  assertLaunchFlags(args);
 
   if (!isString(args.command) || !args.command.trim()) throw new Error("bash requires a non-empty command string");
 
@@ -55,6 +51,15 @@ export function normalizeBash(command, opts) {
   return args;
 }
 
+function assertLaunchFlags(args) {
+  for (const key of ["background", "pty"]) {
+    if (args[key] !== undefined && args[key] !== true && args[key] !== false) throw new Error(`bash ${key} must be boolean`);
+  }
+
+  if (args.pty !== undefined && args.background !== true) throw new Error("bash pty requires background:true");
+
+}
+
 function normalizeTerminalControl(args) {
   const fields = {
     list: ["action"],
@@ -72,11 +77,15 @@ function normalizeTerminalControl(args) {
 
   if (args.action === "write" && (!isString(args.input) || args.input.length > 16384)) throw new Error("bash terminal input must be a string of at most 16384 characters");
 
+  assertTerminalNumbers(args);
+
+  return args;
+}
+
+function assertTerminalNumbers(args) {
   if (args.cursor !== undefined && (!Number.isSafeInteger(args.cursor) || args.cursor < 0)) throw new Error("bash terminal cursor must be a non-negative safe integer");
 
   if (args.waitMs !== undefined && (!Number.isInteger(args.waitMs) || args.waitMs < 0 || args.waitMs > 30000)) throw new Error("bash terminal waitMs must be an integer from 0 to 30000");
-
-  return args;
 }
 
 function normalizeTimeout(args) {