pi-supernova 0.8.2 → 0.9.1

package/src/context/snap-search.js

@@ -0,0 +1,203 @@
+import * as path from 'node:path';
+import {isString} from '../shared/decode.js';
+import {truncateChars} from '../output/format.js';
+import {extractStructuralSurface} from './surface.js';
+import {scorePathTopology,stem,SOURCE_EXT,MAX_NEEDLE_CHARS} from './query.js';
+
+const MAX_SEARCH_CHARS = 2 * 1024 * 1024;
+
+function inScope(filePath, dir, includeHidden) {
+  const relative = path.relative(dir, filePath);
+
+  if (relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) return false;
+  const parts = relative.split(path.sep);
+
+  return !parts.includes(".git") && (includeHidden || !parts.some(part => part.startsWith(".") && part.length > 1));
+}
+
+function makeCandidate(filePath, dir, query, tokens, flags, needles = tokens.map(token => stem(token).slice(0, MAX_NEEDLE_CHARS))) {
+  const relative = path.relative(dir, filePath);
+  const lower = relative.toLowerCase();
+  const base = path.basename(lower);
+
+  const extension = path.extname(base);
+  const stemBase = extension ? base.slice(0, -extension.length) : base;
+  const queryLower = query.toLowerCase();
+  const exactPath = lower === queryLower || base === queryLower || stemBase === queryLower;
+
+  return { path: filePath, pathScore: scorePathTopology(relative, tokens, flags), exactPath,
+    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 bestDeclaration(items, query, tokens, needles) {
+  let declaration;
+  let definitionCoverage = 0;
+  let exact = false;
+  const queryLower = query.toLowerCase();
+
+  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;
+
+    if (itemExact || coverage > definitionCoverage) { declaration = item; definitionCoverage = coverage; exact = itemExact; }
+    if (exact) break;
+  }
+
+  return { declaration, definitionCoverage, exact };
+}
+
+function applyMatch(candidate, lineNumber, text, query, tokens, needles, lower) {
+  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();
+  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 (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);
+  }
+}
+
+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);
+  candidate.recent.push([lineNumber, excerpt]);
+
+  if (candidate.recent.length > 2) candidate.recent.shift();
+}
+
+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++;
+  }
+
+  return truncated;
+}
+
+function parseRgRecord(line, truncated, isLast) {
+  if (!line) return null;
+
+  try { return JSON.parse(line); } catch (error) {
+    if (truncated && isLast) return undefined;
+    throw error;
+  }
+}
+
+function absorbRgHit(candidates, record, dir, includeHidden, overlayText, candidateRoot, query, tokens, flags, needles, candidateNeedles) {
+  if (record.type !== "match" && record.type !== "context") return;
+  const data = record.data;
+
+  if (!data?.path?.text || !isString(data.lines?.text)) return;
+  const filePath = path.resolve(dir, data.path.text);
+
+  if (!inScope(filePath, dir, includeHidden) || overlayText(filePath) !== undefined) return;
+  let candidate = candidates.get(filePath);
+
+  if (!candidate) {
+    candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags, candidateNeedles);
+    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, candidateNeedles, signal) {
+  let overlayTruncated = false;
+
+  for (const filePath of pendingPaths) {
+    const pending = overlayText(filePath);
+
+    if (pending === undefined) continue;
+    const candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags, candidateNeedles);
+    overlayTruncated = inspectOverlay(candidate, pending, needles, query, tokens, signal) || overlayTruncated;
+
+    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, candidateNeedles, 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, candidateNeedles);
+  }
+}
+
+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));
+  // Coverage needles are always token-derived (even in exact mode, where the
+  // search needles collapse to the query): computed once, not once per file.
+  const candidateNeedles = exact ? tokens.map(token => stem(token).slice(0, MAX_NEEDLE_CHARS)) : needles;
+  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);
+
+  return { candidates, truncated: response.outputTruncated === true || overlayTruncated };
+}
+export { inScope, makeCandidate, contentCandidates, MAX_SEARCH_CHARS };

package/src/context/snap.js

@@ -1,278 +1,17 @@
+import {inScope,makeCandidate,contentCandidates,MAX_SEARCH_CHARS} from './snap-search.js';
+import { tokenizeQuery, stem } from "./query.js";
+export {tokenizeQuery,scorePathTopology,stem} from './query.js';
 import * as path from "node:path";
-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";
 
-const STOP_WORDS = new Set([
-  "the", "a", "an", "and", "or", "in", "on", "at", "to", "for", "of", "with",
-  "by", "from", "is", "it", "this", "that", "where", "how", "what", "which",
-  "file", "code", "function", "class", "method", "find", "get", "look", "are", "does", "do",
-]);
-
-const SOURCE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".rs", ".py", ".go"]);
-
-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. */
-export function stem(token) {
-  if (token.length < 5) return token;
-
-  return token.replace(/(ations?|ings?|ed|es|e|s|ly|ers?)$/, (m) => (token.length - m.length >= 4 ? "" : m));
-}
-
-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_]+/);
-
-  return {
-    tokens: [...new Set(words.filter(word => word.length > 1 && !STOP_WORDS.has(word)))],
-    wantsTest: words.some(word => ["test", "tests", "testing", "spec", "specs"].includes(word)),
-    wantsType: words.some(word => ["type", "types", "interface", "interfaces", "schema", "schemas"].includes(word)),
-    wantsDoc: words.some(word => ["doc", "docs", "documentation", "readme"].includes(word)),
-  };
-}
-
-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;
-}
-
-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;
-
-  return score + tokenPathScore(path.basename(normalized), normalized.split(/[^a-zA-Z0-9]+/), normalized, tokens);
-}
-
-function inScope(filePath, dir, includeHidden) {
-  const relative = path.relative(dir, filePath);
-
-  if (relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) return false;
-  const parts = relative.split(path.sep);
-
-  return !parts.includes(".git") && (includeHidden || !parts.some(part => part.startsWith(".") && part.length > 1));
-}
-
-function makeCandidate(filePath, dir, query, tokens, flags) {
-  const relative = path.relative(dir, filePath);
-  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()
-    || 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, 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 bestDeclaration(items, query, tokens, needles) {
-  let declaration;
-  let definitionCoverage = 0;
-  let exact = false;
-  const queryLower = query.toLowerCase();
-
-  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;
-
-    if (itemExact || coverage > definitionCoverage) { declaration = item; definitionCoverage = coverage; exact = itemExact; }
-    if (exact) break;
-  }
-
-  return { declaration, definitionCoverage, exact };
-}
-
-function applyMatch(candidate, lineNumber, text, query, tokens, needles, lower) {
-  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();
-  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 (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);
-  }
-}
-
-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);
-  candidate.recent.push([lineNumber, excerpt]);
-
-  if (candidate.recent.length > 2) candidate.recent.shift();
-}
-
-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++;
-  }
-
-  return truncated;
-}
-
-function parseRgRecord(line, truncated, isLast) {
-  if (!line) return null;
-
-  try { return JSON.parse(line); } catch (error) {
-    if (truncated && isLast) return undefined;
-    throw error;
-  }
-}
-
-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 (!data?.path?.text || !isString(data.lines?.text)) return;
-  const filePath = path.resolve(dir, data.path.text);
-
-  if (!inScope(filePath, dir, includeHidden) || overlayText(filePath) !== undefined) return;
-  let candidate = candidates.get(filePath);
-
-  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) {
-    const pending = overlayText(filePath);
-
-    if (pending === undefined) continue;
-    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 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 };
-}
-
 function rankScore(candidate, tokenCount) {
   return (candidate.exactDefinition ? 10000 : 0) + (candidate.exactPath ? 500 : 0)
     + candidate.definitionCoverage / tokenCount * 100 + candidate.matched.size / tokenCount * 30

package/src/context/source-entry.js

@@ -0,0 +1,112 @@
+import * as path from 'node:path';
+import {extractStructuralSurface} from './surface.js';
+
+const IDENT_TOKEN = /[A-Za-z_$][\w$]*/g;
+
+const EMPTY = Object.freeze([]);
+
+const DEF_PATTERN = /^(?:pub\s+)?(?:export\s+)?(?:async\s+)?(?:default\s+)?(?:(function|class|def|fn|const|let|interface|type|struct|enum)\s+([a-zA-Z0-9_$]+)|([A-Z][A-Z0-9_$]*)\s*(?::[^=\n]+)?=)/;
+
+/** Declared identifier on a line (function/class/UPPER_CASE constant/…), or ""; the same rule snap and grep use. */
+export function declaredName(line) {
+  const match = DEF_PATTERN.exec(String(line).trim());
+
+  return match?.[2] ?? match?.[3] ?? "";
+}
+
+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;
+
+  for (let i = start; i < lineCount; i++) {
+    if (lower[i] === "") { end = i + 1; continue; }
+    if (lineIndent(raw, i) <= base) break;
+    end = i + 1;
+  }
+
+  return Math.min(end, lineCount);
+}
+
+function braceDelta(text) {
+  let depth = 0;
+
+  for (const ch of text) {
+    if (ch === "{") depth++;
+    else if (ch === "}") depth--;
+  }
+
+  return depth;
+}
+
+function braceDeclarationEnd(raw, start, lineCount) {
+  let depth = braceDelta(raw[start - 1] ?? "");
+
+  if (depth <= 0) return start;
+
+  for (let i = start; i < raw.length; i++) {
+    depth += braceDelta(raw[i]);
+
+    if (depth <= 0) return i + 1;
+  }
+
+  return lineCount;
+}
+
+function declarationEnd(raw, lower, start, lineCount, ext) {
+  if (ext === ".py") return pythonDeclarationEnd(raw, lower, start, lineCount);
+
+  return braceDeclarationEnd(raw, start, lineCount);
+}
+
+export function fromText(filePath, text) {
+    return { text, lower: text.toLowerCase(), ext: path.extname(filePath), surface: undefined, lines: undefined, spans: undefined };
+  }
+
+export function linesOf(entry) {
+    if (entry.lines) return entry.lines;
+    const raw = entry.text.split("\n");
+    const lower = [];
+    const defNames = [];
+    const idents = [];
+
+    for (let i = 0; i < raw.length; i++) {
+      const trimmed = raw[i].trim();
+      lower[i] = trimmed.toLowerCase();
+      const declared = DEF_PATTERN.exec(trimmed);
+      defNames[i] = (declared?.[2] ?? declared?.[3] ?? "").toLowerCase();
+      idents[i] = trimmed.match(IDENT_TOKEN) || EMPTY;
+    }
+
+    entry.lines = { raw, lower, defNames, idents };
+
+    return entry.lines;
+  }
+
+export function spansOf(entry) {
+    if (entry.spans) return entry.spans;
+    const { items, lineCount } = surfaceOf(entry);
+    const { lower, raw } = linesOf(entry);
+    const spans = [];
+
+    for (let i = 0; i < items.length; i++) {
+      const start = items[i].line;
+      let end = declarationEnd(raw, lower, start, lineCount, entry.ext);
+
+      while (end > start && lower[end - 1] === "") end--;
+      spans.push({ start, end, name: items[i].name, kind: items[i].kind, isExport: items[i].isExport === true });
+    }
+
+    entry.spans = spans;
+
+    return spans;
+  }
+
+export function surfaceOf(entry) {
+    if (!entry.surface) entry.surface = extractStructuralSurface(entry.text, entry.ext);
+
+    return entry.surface;
+  }

package/src/contract/bash.js

@@ -44,6 +44,12 @@ export function normalizeBash(command, opts) {
   if (args.command.includes("\0")) throw new Error("bash command must not contain null bytes");
   normalizeArgv(args);
 
+  normalizeTimeout(args);
+
+  return args;
+}
+
+function normalizeTimeout(args) {
   if (args.timeout !== undefined && args.timeoutMs === undefined) args.timeoutMs = args.timeout * 1000;
   // Reject before the host's external-mutation barrier can flush staged files.
   if (args.timeoutMs !== undefined) {
@@ -52,5 +58,4 @@ export function normalizeBash(command, opts) {
     args.timeoutMs = Math.max(1, Math.min(2_147_483_647, Math.floor(timeout)));
   }
 
-  return args;
 }

package/src/contract/program.js

@@ -0,0 +1,36 @@
+import {createRequire} from 'node:module';
+
+// Sync only, never top-level await. Dynamic import of host/deps hung OMP plugin load.
+const require = createRequire(import.meta.url);
+
+let Type;
+
+try {
+  Type = require("typebox").Type;
+} catch {
+  Type = {
+    Object: (props, opts) => ({ type: "object", properties: props || {}, additionalProperties: false, ...opts }),
+    String: (opts) => ({ type: "string", ...opts }),
+    Unknown: (opts) => ({ ...opts }),
+    Array: (items, opts) => ({ type: "array", items, ...opts }),
+    Integer: (opts) => ({ type: "integer", ...opts }),
+    Optional: (s) => ({ ...s }),
+    Boolean: (opts) => ({ type: "boolean", ...opts }),
+  };
+}
+
+export function programParameters(config) {
+  return Type.Object({
+      code: Type.Optional(Type.String({ maxLength: config.maxCodeChars ?? 48000 })),
+      file: Type.Optional(Type.String({ minLength: 1 })),
+      data: Type.Optional(Type.Unknown()),
+      timeoutMs: Type.Optional(Type.Integer({ minimum: 1000 })),
+      programs: Type.Optional(Type.Array(Type.Object({
+        code: Type.Optional(Type.String({ maxLength: config.maxCodeChars ?? 48000 })),
+        file: Type.Optional(Type.String({ minLength: 1 })),
+        data: Type.Optional(Type.Unknown()),
+      }, {additionalProperties:false}), {minItems:1,maxItems:32})),
+      parallel: Type.Optional(Type.Boolean()),
+      mergeData: Type.Optional(Type.Boolean()),
+    });
+}