pi-supernova 0.0.7 → 0.0.8

package/snap.js

@@ -63,37 +63,41 @@ export function scorePathTopology(filePath, tokens, { wantsTest, wantsDoc, wants
   return score;
 }
 
-function scoreContentDefinitions(content, tokens) {
-  const lines = content.split("\n");
+function isSkippableLine(line) {
+  return !line || line.startsWith("//") || line.startsWith("#") || line.startsWith("*");
+}
+
+function lineScoreFor(line, tokens, isDef) {
+  const lower = line.toLowerCase();
+  let lineScore = 0;
+  for (const token of tokens) {
+    if (lower.includes(token)) lineScore += isDef ? 40 : 5;
+  }
+  return lineScore;
+}
+
+function accumulateContentScore(lines, tokens, defPattern) {
   let score = 0;
   let bestLine = 1;
   let bestLineScore = 0;
-
-  const defRegex = /^(?:pub\s+)?(?:export\s+)?(?:async\s+)?(?:default\s+)?(function|class|def|fn|const|let|interface|type|struct|enum)\s+([a-zA-Z0-9_$]+)/;
-
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i].trim();
-    if (!line || line.startsWith("//") || line.startsWith("#") || line.startsWith("*")) continue;
-
-    let lineScore = 0;
-    const isDef = defRegex.test(line);
-
-    for (const token of tokens) {
-      if (line.toLowerCase().includes(token)) {
-        lineScore += isDef ? 40 : 5;
-      }
-    }
-
+    if (isSkippableLine(line)) continue;
+    const lineScore = lineScoreFor(line, tokens, defPattern.test(line));
     if (lineScore > bestLineScore) {
       bestLineScore = lineScore;
       bestLine = i + 1;
     }
     score += lineScore;
   }
-
   return { totalScore: score, bestLine, bestLineScore };
 }
 
+function scoreContentDefinitions(content, tokens) {
+  const defRegex = /^(?:pub\s+)?(?:export\s+)?(?:async\s+)?(?:default\s+)?(function|class|def|fn|const|let|interface|type|struct|enum)\s+([a-zA-Z0-9_$]+)/;
+  return accumulateContentScore(content.split("\n"), tokens, defRegex);
+}
+
 function relativeHasSegment(relativePath, segmentName) {
   return relativePath.split(path.sep).includes(segmentName);
 }
@@ -102,78 +106,83 @@ function relativeHasHiddenSegment(relativePath) {
   return relativePath.split(path.sep).some((segment) => segment.startsWith(".") && segment.length > 1);
 }
 
-export async function executeSnap({ query, searchDir, includeHidden = false, vfs, runCommand, pendingPaths = [] }) {
-  const { tokens, wantsTest, wantsType, wantsDoc } = tokenizeQuery(query);
-  if (tokens.length === 0) {
-    throw new Error("snap requires at least one searchable concept keyword");
-  }
-
-  const dir = searchDir || process.cwd();
-  if (path.resolve(dir).split(path.sep).includes(".git")) {
-    throw new Error("snap cannot search Git metadata");
-  }
-  let fileList = [];
+async function listCandidateFiles(dir, includeHidden, runCommand) {
+  const rgArgs = ["rg", "--files"];
+  if (includeHidden) rgArgs.push("--hidden");
+  rgArgs.push("-g", "!.git/**", "-g", "!**/.git/**", dir);
   try {
-    const rgArgs = ["rg", "--files"];
-    if (includeHidden) rgArgs.push("--hidden");
-    rgArgs.push("-g", "!.git/**", "-g", "!**/.git/**", dir);
     const res = await runCommand(rgArgs, { timeoutMs: 15_000 });
-    fileList = res.stdout.split("\n").map((f) => f.trim()).filter(Boolean);
+    // rg --files is multithreaded and emits in nondeterministic order; ties must rank stably.
+    return res.stdout.split("\n").map((f) => f.trim()).filter(Boolean).sort();
   } catch {
-    fileList = [];
+    return [];
   }
+}
 
+function mergePendingPaths(fileList, pendingPaths, dir, includeHidden = false) {
+  const resolvedDir = path.resolve(dir);
   const seenPaths = new Set(fileList.map((filePath) => path.resolve(filePath)));
   for (const pendingPath of pendingPaths) {
     const absolutePath = path.resolve(pendingPath);
-    const relativePath = path.relative(path.resolve(dir), absolutePath);
+    const relativePath = path.relative(resolvedDir, absolutePath);
     const escapesDir = relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
     const hiddenRelativePath = relativeHasHiddenSegment(relativePath);
     if (escapesDir || relativeHasSegment(relativePath, ".git") || (!includeHidden && hiddenRelativePath) || seenPaths.has(absolutePath)) continue;
     seenPaths.add(absolutePath);
     fileList.push(absolutePath);
   }
+  return fileList;
+}
 
-  if (fileList.length === 0) {
-    throw new Error(`no files found to search in ${dir}`);
+function mergeGrepHits(candidates, grepHits) {
+  const seen = new Set(candidates);
+  for (const h of grepHits) {
+    if (seen.has(h)) continue;
+    seen.add(h);
+    candidates.push(h);
+    if (candidates.length >= 15) break;
   }
+  return candidates;
+}
 
-  const scoredPaths = [];
-  for (const f of fileList) {
-    const score = scorePathTopology(f, tokens, { wantsTest, wantsDoc, wantsType });
-    if (score > 0) scoredPaths.push({ path: f, score });
+async function expandCandidatesWithGrep(candidates, fileList, tokens, flags, dir, includeHidden, runCommand) {
+  if (candidates.length >= 5) return candidates;
+  try {
+    // Tokens are lowercased; identifiers are not.
+    const grepArgs = ["-l", "-i", "--max-count=1", "-g", "!.git/**", "-g", "!**/.git/**"];
+    if (includeHidden) grepArgs.push("--hidden");
+    if (!flags.wantsTest) {
+      grepArgs.push("-g", "!test/**", "-g", "!tests/**", "-g", "!*.test.*", "-g", "!*.spec.*");
+    }
+    const salient = tokens.filter((t) => t.length > 2).slice(0, 4);
+    for (const t of salient) grepArgs.push("-e", t);
+    const res = await runCommand(["rg", ...grepArgs, dir], { timeoutMs: 15_000 });
+    mergeGrepHits(candidates, res.stdout.split("\n").map((f) => f.trim()).filter(Boolean).sort());
+  } catch {
+    if (candidates.length === 0) candidates = fileList.slice(0, 5);
   }
+  return candidates;
+}
 
-  scoredPaths.sort((a, b) => b.score - a.score);
-
-  let candidates = scoredPaths.filter((p) => p.score >= 25).slice(0, 10).map((p) => p.path);
-
-  if (candidates.length < 5) {
-    try {
-      const grepArgs = ["-l", "--max-count=1", "-g", "!.git/**", "-g", "!**/.git/**"];
-      if (includeHidden) grepArgs.push("--hidden");
-      if (!wantsTest) {
-        grepArgs.push("-g", "!test/**", "-g", "!tests/**", "-g", "!*.test.*", "-g", "!*.spec.*");
-      }
-      const salient = tokens.filter((t) => t.length > 2).slice(0, 4);
-      for (const t of salient) grepArgs.push("-e", t);
-      const res = await runCommand(["rg", ...grepArgs, dir], { timeoutMs: 15_000 });
-      const grepHits = res.stdout.split("\n").map((f) => f.trim()).filter(Boolean);
-      const seen = new Set(candidates);
-      for (const h of grepHits) {
-        if (!seen.has(h)) {
-          seen.add(h);
-          candidates.push(h);
-          if (candidates.length >= 15) break;
-        }
-      }
-    } catch {
-      if (candidates.length === 0) candidates = fileList.slice(0, 5);
+function scoreSurfaceItems(items, tokens, fallbackLine) {
+  let bonus = 0;
+  let signature = "";
+  let anchorLine = fallbackLine;
+  for (const item of items) {
+    const nameLower = item.name.toLowerCase();
+    for (const token of tokens) {
+      if (!nameLower.includes(token)) continue;
+      bonus += item.isExport ? 80 : 50;
+      if (signature) continue;
+      signature = item.signature;
+      anchorLine = item.line;
     }
   }
+  return { bonus, signature, anchorLine };
+}
 
+async function scoreCandidateContents(candidates, tokens, flags, vfs) {
   const candidateScores = [];
-
   for (const filePath of candidates) {
     let content = "";
     try {
@@ -181,71 +190,81 @@ export async function executeSnap({ query, searchDir, includeHidden = false, vfs
     } catch {
       continue;
     }
-
     const { totalScore, bestLine, bestLineScore } = scoreContentDefinitions(content, tokens);
-    const ext = path.extname(filePath);
-    const surface = extractStructuralSurface(content, ext);
-
-    let surfaceBonus = 0;
-    let signature = "";
-    let anchorLine = bestLine;
-
-    for (const item of surface.items) {
-      const nameLower = item.name.toLowerCase();
-      for (const token of tokens) {
-        if (nameLower.includes(token)) {
-          surfaceBonus += item.isExport ? 80 : 50;
-          if (!signature) {
-            signature = item.signature;
-            anchorLine = item.line;
-          }
-        }
-      }
-    }
-
-    const isTestFile = filePath.toLowerCase().includes("test") || filePath.toLowerCase().includes("spec");
-    const testAdjustment = isTestFile && !wantsTest ? -200 : (isTestFile && wantsTest ? 100 : 0);
-    const finalScore = totalScore + surfaceBonus + (bestLineScore * 2) + testAdjustment;
+    const surface = extractStructuralSurface(content, path.extname(filePath));
+    const { bonus: surfaceBonus, signature, anchorLine } = scoreSurfaceItems(surface.items, tokens, bestLine);
+    const lowerPath = filePath.toLowerCase();
+    const isTestFile = lowerPath.includes("test") || lowerPath.includes("spec");
+    const testAdjustment = !isTestFile ? 0 : (flags.wantsTest ? 100 : -200);
     candidateScores.push({
       path: filePath,
-      score: finalScore,
+      score: totalScore + surfaceBonus + (bestLineScore * 2) + testAdjustment,
       anchorLine,
       signature,
       content,
     });
   }
-
   candidateScores.sort((a, b) => b.score - a.score);
+  return candidateScores;
+}
+
+async function rankCandidates(fileList, tokens, flags, dir, includeHidden, runCommand, vfs) {
+  const scoredPaths = [];
+  for (const f of fileList) {
+    const score = scorePathTopology(f, tokens, flags);
+    if (score > 0) scoredPaths.push({ path: f, score });
+  }
+  scoredPaths.sort((a, b) => b.score - a.score);
+  const selected = scoredPaths.filter((p) => p.score >= 25).slice(0, 10).map((p) => p.path);
+  const candidates = await expandCandidatesWithGrep(selected, fileList, tokens, flags, dir, includeHidden, runCommand);
+  const candidateScores = await scoreCandidateContents(candidates, tokens, flags, vfs);
+  return { candidates, candidateScores };
+}
 
+function buildSnapResult(candidates, candidateScores, fileList) {
   if (candidateScores.length === 0 || candidateScores[0].score <= 0) {
-    const fallbackPath = candidates[0] || fileList[0];
     return {
-      path: fallbackPath,
+      path: candidates[0] || fileList[0],
       line: 1,
       signature: "",
       confidence: 0.3,
       context: [],
     };
   }
-
   const best = candidateScores[0];
   const lines = best.content.split("\n");
   const startLine = Math.max(1, best.anchorLine - 3);
   const endLine = Math.min(lines.length, best.anchorLine + 8);
-
-  const contextLines = [];
+  const context = [];
   for (let l = startLine; l <= endLine; l++) {
     const marker = l === best.anchorLine ? "►" : " ";
-    contextLines.push(`${marker} ${String(l).padStart(4)} │ ${lines[l - 1]}`);
+    context.push(`${marker} ${String(l).padStart(4)} │ ${lines[l - 1]}`);
   }
-
   const confidence = Math.min(0.98, Math.max(0.65, best.score / 150));
-
   return {
     path: best.path,
     line: best.anchorLine,
     signature: best.signature,
     confidence: Number(confidence.toFixed(2)),
-    context: contextLines,
+    context,
   };
 }
+
+export async function executeSnap({ query, searchDir, includeHidden = false, vfs, runCommand, pendingPaths = [] }) {
+  const { tokens, wantsTest, wantsType, wantsDoc } = tokenizeQuery(query);
+  if (tokens.length === 0) {
+    throw new Error("snap requires at least one searchable concept keyword");
+  }
+  const dir = searchDir || process.cwd();
+  if (path.resolve(dir).split(path.sep).includes(".git")) {
+    throw new Error("snap cannot search Git metadata");
+  }
+  const fileList = await listCandidateFiles(dir, includeHidden, runCommand);
+  mergePendingPaths(fileList, pendingPaths, dir, includeHidden);
+  if (fileList.length === 0) {
+    throw new Error(`no files found to search in ${dir}`);
+  }
+  const flags = { wantsTest, wantsDoc, wantsType };
+  const { candidates, candidateScores } = await rankCandidates(fileList, tokens, flags, dir, includeHidden, runCommand, vfs);
+  return buildSnapResult(candidates, candidateScores, fileList);
+}

package/surface.js

@@ -61,45 +61,28 @@ function scanGo(lines) {
   return items;
 }
 
+const JS_DECL_PATTERNS = [
+  [/^export\s+(?:default\s+)?(?:async\s+)?(function\*?|class|const|let|var|type|interface|enum)\s+([a-zA-Z0-9_$]+)/, true],
+  [/^(?:async\s+)?(function\*?|class)\s+([a-zA-Z0-9_$]+)/, false],
+  [/^(interface|type)\s+([a-zA-Z0-9_$]+)/, false],
+];
+
 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 expMatch = /^export\s+(?:default\s+)?(?:async\s+)?(function\*?|class|const|let|var|type|interface|enum)\s+([a-zA-Z0-9_$]+)/.exec(line);
-    if (expMatch) {
-      items.push({
-        kind: expMatch[1],
-        name: expMatch[2],
-        isExport: true,
-        signature: line.replace(/\{.*$/, "").trim(),
-        line: i + 1,
-      });
-      continue;
-    }
-
-    const declMatch = /^(?:async\s+)?(function\*?|class)\s+([a-zA-Z0-9_$]+)/.exec(line);
-    if (declMatch) {
-      items.push({
-        kind: declMatch[1],
-        name: declMatch[2],
-        isExport: false,
-        signature: line.replace(/\{.*$/, "").trim(),
-        line: i + 1,
-      });
-      continue;
-    }
-
-    const tsMatch = /^(interface|type)\s+([a-zA-Z0-9_$]+)/.exec(line);
-    if (tsMatch) {
+    for (const [pattern, isExport] of JS_DECL_PATTERNS) {
+      const match = pattern.exec(line);
+      if (!match) continue;
       items.push({
-        kind: tsMatch[1],
-        name: tsMatch[2],
-        isExport: false,
+        kind: match[1],
+        name: match[2],
+        isExport,
         signature: line.replace(/\{.*$/, "").trim(),
         line: i + 1,
       });
+      break;
     }
   }
   return items;

package/vfs.js

@@ -0,0 +1,138 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+const VFS_CACHE_MAX = 1024;
+
+export class CausalVfs {
+  constructor() {
+    this.cache = new Map();
+    this.overlays = [];
+  }
+
+  setCache(target, content) {
+    if (this.cache.size >= VFS_CACHE_MAX && !this.cache.has(target)) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) this.cache.delete(oldest);
+    }
+    this.cache.set(target, content);
+  }
+
+  getOverlay(target) {
+    for (let i = this.overlays.length - 1; i >= 0; i--) {
+      if (this.overlays[i].has(target)) return this.overlays[i].get(target);
+    }
+    return undefined;
+  }
+
+  getOverlayPaths() {
+    const paths = new Set();
+    for (const overlay of this.overlays) {
+      for (const target of overlay.keys()) paths.add(target);
+    }
+    return [...paths];
+  }
+
+  async read(target) {
+    const overlay = this.getOverlay(target);
+    if (overlay !== undefined) return overlay;
+
+    const cached = this.cache.get(target);
+    if (cached !== undefined) return cached;
+
+    try {
+      const text = await fs.readFile(target, "utf8");
+      this.setCache(target, text);
+      return text;
+    } catch (err) {
+      if (err.code === "EISDIR") {
+        throw new Error(`read path is a directory, not a file: ${target}`);
+      }
+      if (err.code === "ENOENT") {
+        const missing = new Error(`no such file: ${target} (locate it with nova.call("glob", {pattern}) or snap(query))`);
+        missing.code = "ENOENT";
+        throw missing;
+      }
+      throw err;
+    }
+  }
+
+  async write(target, content) {
+    if (this.overlays.length > 0) {
+      this.overlays[this.overlays.length - 1].set(target, content);
+      return { speculative: true };
+    }
+
+    try {
+      const stat = await fs.stat(target);
+      if (stat.isDirectory()) {
+        throw new Error(`cannot write to a directory: ${target}`);
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, content, "utf8");
+    this.setCache(target, content);
+    return { speculative: false };
+  }
+
+  begin() {
+    this.overlays.push(new Map());
+    return this.overlays.length;
+  }
+
+  async commit() {
+    if (this.overlays.length === 0) return { committed: 0, depth: 0 };
+    const top = this.overlays.pop();
+    if (this.overlays.length > 0) {
+      const parent = this.overlays[this.overlays.length - 1];
+      for (const [k, v] of top.entries()) parent.set(k, v);
+      return { committed: top.size, depth: this.overlays.length };
+    }
+    for (const [filePath, fileContent] of top.entries()) {
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.writeFile(filePath, fileContent, "utf8");
+      this.setCache(filePath, fileContent);
+    }
+    return { committed: top.size, depth: 0 };
+  }
+
+  rollback() {
+    if (this.overlays.length === 0) return { rolledBack: 0, depth: 0 };
+    const top = this.overlays.pop();
+    return { rolledBack: top.size, depth: this.overlays.length };
+  }
+
+  async prepareExternalMutation(name) {
+    if (this.overlays.length > 1) {
+      throw new Error(`${name} cannot run inside nova.speculate because external mutations cannot be rolled back`);
+    }
+    if (this.overlays.length === 0) return false;
+    const pending = this.overlays[0];
+    for (const [filePath, fileContent] of pending.entries()) {
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.writeFile(filePath, fileContent, "utf8");
+      this.setCache(filePath, fileContent);
+    }
+    this.overlays[0] = new Map();
+    return pending.size > 0;
+  }
+
+  invalidateCache() {
+    this.cache.clear();
+  }
+
+  clear() {
+    this.invalidateCache();
+    this.overlays.length = 0;
+  }
+
+  getCacheSize() {
+    return this.cache.size;
+  }
+
+  getOverlayDepth() {
+    return this.overlays.length;
+  }
+}

package/workspace.js

@@ -0,0 +1,112 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { isString } from "./decode.js";
+
+let cachedCwd = null;
+let cachedResolvedCwd = null;
+
+function getResolvedCwd(cwd) {
+  if (cwd === cachedCwd && cachedResolvedCwd) return cachedResolvedCwd;
+  cachedCwd = cwd;
+  cachedResolvedCwd = path.resolve(cwd);
+  return cachedResolvedCwd;
+}
+
+function assertInside(rel, message) {
+  if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    throw new Error(message);
+  }
+}
+
+async function realpathNearest(target) {
+  let probe = target;
+  while (true) {
+    try {
+      return await fs.realpath(probe);
+    } catch (err) {
+      if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") throw err;
+      const parent = path.dirname(probe);
+      if (parent === probe) throw err;
+      probe = parent;
+    }
+  }
+}
+
+export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false) {
+  if (inputPath == null || !isString(inputPath) || !inputPath.trim()) {
+    throw new Error(`${opName} requires path`);
+  }
+  const resolvedCwd = getResolvedCwd(cwd);
+  const target = path.resolve(resolvedCwd, inputPath.trim());
+  assertInside(path.relative(resolvedCwd, target), `${opName} path escapes workspace: paths resolve relative to ${resolvedCwd}`);
+  if (!allowRoot && target === resolvedCwd) {
+    throw new Error(`${opName} path cannot be the workspace root directory`);
+  }
+  const realRoot = await fs.realpath(resolvedCwd);
+  const probe = await realpathNearest(target);
+  assertInside(path.relative(realRoot, probe), `${opName} path escapes workspace through symlink`);
+  return target;
+}
+
+export async function runCommand(argv, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const timeoutMs = options.timeoutMs ?? 60_000;
+  const maxOutputChars = options.maxOutputChars ?? 2 * 1024 * 1024;
+  return await new Promise((resolve, reject) => {
+    const child = spawn(argv[0], argv.slice(1), {
+      cwd,
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let outputTruncated = false;
+    let onAbort;
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      if (options.signal && onAbort) options.signal.removeEventListener("abort", onAbort);
+    };
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    };
+    const append = (current, chunk) => {
+      const remaining = Math.max(0, maxOutputChars - current.length);
+      if (chunk.length > remaining) outputTruncated = true;
+      return remaining > 0 ? current + chunk.slice(0, remaining) : current;
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      fail(new Error(`command timed out after ${timeoutMs}ms: ${argv.join(" ")}`));
+    }, timeoutMs);
+
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout = append(stdout, chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr = append(stderr, chunk);
+    });
+    child.on("error", fail);
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve({ stdout, stderr, exitCode: code ?? 0, outputTruncated });
+    });
+    if (options.signal) {
+      onAbort = () => {
+        child.kill("SIGTERM");
+        fail(new Error("aborted"));
+      };
+      if (options.signal.aborted) onAbort();
+      else options.signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}