@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/coding/src/agent/repository/list.ts

@@ -0,0 +1,131 @@
+/** Repository list family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from repository.ts; public surface unchanged behind the barrel. */
+
+import { lstat } from "node:fs/promises";
+import {
+  HARD_MAX_REPO_DEPTH,
+  HARD_MAX_REPO_ENTRIES,
+  HARD_MAX_REPO_RESULTS,
+  validateCodingLimit,
+  validateCodingLimitAllowZero,
+} from "../limits.js";
+import { resolveRepoPath } from "./path.js";
+import type { RepoEntryKind, RepoListEntry, RepositoryListRequest, RepositoryListResult, ResolvedRepositoryLimits } from "./types.js";
+import { RepositoryError } from "./types.js";
+import type { RepositoryWalk } from "./walk.js";
+
+export async function listLocal(
+  request: RepositoryListRequest,
+  defaults: ResolvedRepositoryLimits,
+  walk: RepositoryWalk,
+): Promise<RepositoryListResult> {
+  const resolved = await resolveRepoPath(request.root, request.path);
+  const maxResults = validateCodingLimit("maxResults", request.maxResults ?? defaults.maxResults, HARD_MAX_REPO_RESULTS);
+  const offset = validateCodingLimitAllowZero("offset", request.offset ?? 0, HARD_MAX_REPO_ENTRIES);
+  const maxDepth = validateCodingLimit("maxDepth", request.maxDepth ?? defaults.maxDepth, HARD_MAX_REPO_DEPTH);
+  const exclude = new Set(request.exclude ?? defaults.exclude);
+  const deadlineAt = request.deadlineMs !== undefined ? Date.now() + request.deadlineMs : Date.now() + defaults.maxTimeMs;
+
+  const collected: RepoListEntry[] = [];
+  let scannedEntries = 0;
+  let scannedFiles = 0;
+  let seen = 0;
+  let truncated = false;
+  let truncatedBy: RepositoryListResult["truncatedBy"] = null;
+
+  // Single-file start: return that entry when it falls within the page window.
+  try {
+    const startStat = await lstat(resolved.absolute);
+    if (!startStat.isDirectory()) {
+      let kind: RepoEntryKind = "other";
+      if (startStat.isSymbolicLink()) kind = "symlink";
+      else if (startStat.isFile()) kind = "file";
+      const entry: RepoListEntry =
+        kind === "file" ? { path: resolved.relative, kind, size: startStat.size } : { path: resolved.relative, kind };
+      scannedEntries = 1;
+      scannedFiles = kind === "file" ? 1 : 0;
+      if (offset === 0 && maxResults > 0) collected.push(entry);
+      else if (offset === 0 && maxResults === 0) {
+        truncated = true;
+        truncatedBy = "results";
+      }
+      return {
+        entries: collected,
+        truncated,
+        truncatedBy,
+        scannedEntries,
+        scannedFiles,
+        offset,
+        nextOffset: undefined,
+      };
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new RepositoryError(`cannot open path: ${message}`);
+  }
+
+  try {
+    for await (const event of walk(resolved.rootReal, resolved.absolute, {
+      maxDepth,
+      maxEntries: defaults.maxEntries,
+      maxFiles: defaults.maxFiles,
+      exclude,
+      includeHidden: request.includeHidden === true,
+      signal: request.signal,
+      deadlineAt,
+    })) {
+      if (event.type === "limit") {
+        truncated = true;
+        truncatedBy = event.truncatedBy;
+        break;
+      }
+      scannedEntries++;
+      if (event.entry.kind === "file") scannedFiles++;
+      if (seen < offset) {
+        seen++;
+        continue;
+      }
+      if (collected.length >= maxResults) {
+        truncated = true;
+        truncatedBy = "results";
+        break;
+      }
+      collected.push(event.entry);
+      seen++;
+    }
+  } catch (error) {
+    if (error instanceof RepositoryError && error.message === "Operation aborted") {
+      return {
+        entries: collected,
+        truncated: true,
+        truncatedBy: "abort",
+        scannedEntries,
+        scannedFiles,
+        offset,
+        nextOffset: collected.length > 0 || offset > 0 ? offset + collected.length : undefined,
+      };
+    }
+    if (error instanceof RepositoryError && error.message === "Repository operation exceeded time limit") {
+      return {
+        entries: collected,
+        truncated: true,
+        truncatedBy: "time",
+        scannedEntries,
+        scannedFiles,
+        offset,
+        nextOffset: offset + collected.length,
+      };
+    }
+    throw error;
+  }
+
+  return {
+    entries: collected,
+    truncated,
+    truncatedBy,
+    scannedEntries,
+    scannedFiles,
+    offset,
+    nextOffset: truncated ? offset + collected.length : undefined,
+  };
+}

package/coding/src/agent/repository/operations.ts

@@ -0,0 +1,22 @@
+/** Repository operations family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from repository.ts; public surface unchanged behind the barrel. */
+
+import { globLocal } from "./glob.js";
+import { listLocal } from "./list.js";
+import { searchLocal } from "./search.js";
+import type { RepositoryLimitOptions, RepositoryOperations } from "./types.js";
+import { resolveRepositoryLimits } from "./types.js";
+import type { RepositoryWalk } from "./walk.js";
+import { walkRepository } from "./walk.js";
+
+export function createLocalRepositoryOperations(
+  limits?: RepositoryLimitOptions,
+  walk: RepositoryWalk = walkRepository,
+): RepositoryOperations {
+  const resolved = resolveRepositoryLimits(limits);
+  return {
+    list: (request) => listLocal(request, resolved, walk),
+    search: (request) => searchLocal(request, resolved, walk),
+    glob: (request) => globLocal(request, resolved, walk),
+  };
+}

package/coding/src/agent/repository/path.ts

@@ -0,0 +1,98 @@
+/** Repository path family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from repository.ts; public surface unchanged behind the barrel. */
+
+import type { Dirent } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { DEFAULT_BINARY_SNIFF_BYTES } from "../limits.js";
+import { resolveToCwd } from "../path-utils.js";
+import type { RepoEntryKind } from "./types.js";
+import { RepositoryError } from "./types.js";
+
+export function toRepoRelative(root: string, absolutePath: string): string {
+  const rel = relative(root, absolutePath);
+  if (rel === "") return ".";
+  return rel.split(sep).join("/");
+}
+
+export function isPathInsideRoot(root: string, target: string): boolean {
+  const from = resolve(root);
+  const to = resolve(target);
+  if (to === from) return true;
+  const rel = relative(from, to);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/**
+ * Resolve a list/search start path under the workspace root.
+ * Symlink escapes fail closed after realpath when the path exists.
+ */
+export async function resolveRepoPath(
+  root: string,
+  inputPath: string | undefined,
+): Promise<{
+  absolute: string;
+  relative: string;
+  rootReal: string;
+}> {
+  const rootResolved = resolve(root);
+  let rootReal: string;
+  try {
+    rootReal = await realpath(rootResolved);
+  } catch {
+    throw new RepositoryError(`workspace root is missing or unreadable: ${rootResolved}`);
+  }
+
+  if (!inputPath || inputPath === "." || inputPath === "./") {
+    return { absolute: rootReal, relative: ".", rootReal };
+  }
+
+  const candidate = resolveToCwd(inputPath, rootReal);
+  if (!isPathInsideRoot(rootReal, candidate)) {
+    throw new RepositoryError(`path escapes workspace root: ${inputPath}`);
+  }
+
+  try {
+    const real = await realpath(candidate);
+    if (!isPathInsideRoot(rootReal, real)) {
+      throw new RepositoryError(`path resolves outside workspace root: ${inputPath}`);
+    }
+    return { absolute: real, relative: toRepoRelative(rootReal, real), rootReal };
+  } catch (error) {
+    if (error instanceof RepositoryError) throw error;
+    // ENOENT: allow listing a missing path to fail later with a clear error.
+    return { absolute: candidate, relative: toRepoRelative(rootReal, candidate), rootReal };
+  }
+}
+
+export function shouldSkipName(name: string, includeHidden: boolean, exclude: ReadonlySet<string>): boolean {
+  if (name === "." || name === "..") return true;
+  if (exclude.has(name)) return true;
+  if (!includeHidden && name.startsWith(".")) return true;
+  return false;
+}
+
+export function kindFromDirent(dirent: Dirent): RepoEntryKind {
+  if (dirent.isSymbolicLink()) return "symlink";
+  if (dirent.isDirectory()) return "directory";
+  if (dirent.isFile()) return "file";
+  return "other";
+}
+
+export function assertNotAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new RepositoryError("Operation aborted");
+}
+
+export function assertDeadline(deadlineAt: number | undefined): void {
+  if (deadlineAt !== undefined && Date.now() >= deadlineAt) {
+    throw new RepositoryError("Repository operation exceeded time limit");
+  }
+}
+
+export function isBinaryBuffer(buffer: Buffer): boolean {
+  const length = Math.min(buffer.length, DEFAULT_BINARY_SNIFF_BYTES);
+  for (let i = 0; i < length; i++) {
+    if (buffer[i] === 0) return true;
+  }
+  return false;
+}

package/coding/src/agent/repository/search.ts

@@ -0,0 +1,277 @@
+/** Repository search family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from repository.ts; public surface unchanged behind the barrel. */
+
+import { lstat, open } from "node:fs/promises";
+import { HARD_MAX_SEARCH_CONTEXT_LINES, HARD_MAX_SEARCH_MATCHES, validateCodingLimit, validateCodingLimitAllowZero } from "../limits.js";
+import { compileGlob } from "../glob-match.js";
+import { assertDeadline, assertNotAborted, isBinaryBuffer, resolveRepoPath } from "./path.js";
+import type {
+  RepositoryFileMatcher,
+  RepositoryLineMatch,
+  RepositorySearchMatch,
+  RepositorySearchRequest,
+  RepositorySearchResult,
+  ResolvedRepositoryLimits,
+} from "./types.js";
+import { RepositoryError } from "./types.js";
+import type { RepositoryWalk } from "./walk.js";
+
+export function compileSearchPattern(
+  query: string,
+  caseSensitive: boolean,
+  maxPatternBytes: number,
+): { testLine: (line: string) => { column: number } | null; patternBytes: number } {
+  const patternBytes = Buffer.byteLength(query, "utf8");
+  if (patternBytes < 1) throw new RepositoryError("query must be non-empty");
+  if (patternBytes > maxPatternBytes) {
+    throw new RepositoryError(`query exceeds ${maxPatternBytes} byte pattern limit`);
+  }
+
+  if (caseSensitive) {
+    return {
+      patternBytes,
+      testLine: (line) => {
+        const column = line.indexOf(query);
+        return column >= 0 ? { column: column + 1 } : null;
+      },
+    };
+  }
+  const needle = query.toLowerCase();
+  return {
+    patternBytes,
+    testLine: (line) => {
+      const column = line.toLowerCase().indexOf(needle);
+      return column >= 0 ? { column: column + 1 } : null;
+    },
+  };
+}
+
+/**
+ * One file's text → its line matches with context. Pure, no I/O: the `grep` worker imports this
+ * too, so literal and regex modes format from the same matches.
+ */
+export function matchLines(
+  text: string,
+  testLine: (line: string) => { column: number } | null,
+  context: number,
+  maxLineBytes: number,
+): RepositoryLineMatch[] {
+  const lines = text.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  const out: RepositoryLineMatch[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (maxLineBytes > 0 && Buffer.byteLength(line, "utf8") > maxLineBytes) continue;
+    const hit = testLine(line);
+    if (!hit) continue;
+    out.push({
+      line: i + 1,
+      column: hit.column,
+      text: line,
+      before: lines.slice(Math.max(0, i - context), i),
+      after: lines.slice(i + 1, i + 1 + context),
+    });
+  }
+  return out;
+}
+
+/** The literal matcher: `matchLines` over a compiled substring test. */
+export function literalMatcher(
+  query: string,
+  caseSensitive: boolean,
+  maxPatternBytes: number,
+  maxLineBytes: number,
+): RepositoryFileMatcher {
+  const { testLine } = compileSearchPattern(query, caseSensitive, maxPatternBytes);
+  return (text, context) => matchLines(text, testLine, context, maxLineBytes);
+}
+
+type FileOutcome = "ok" | "binary" | "oversize" | "scan" | "matches";
+
+/** Read one bounded file and collect its matches. Whole-file read: the file is already size-capped. */
+async function searchFile(
+  absolutePath: string,
+  relativePath: string,
+  matcher: RepositoryFileMatcher,
+  options: {
+    maxFileBytes: number;
+    maxScanBytesRemaining: () => number;
+    chargeScan: (n: number) => void;
+    context: number;
+    maxMatchesRemaining: () => number;
+    pushMatch: (match: RepositorySearchMatch) => void;
+    signal?: AbortSignal;
+    deadlineAt?: number;
+    binarySniffBytes: number;
+  },
+): Promise<FileOutcome> {
+  assertNotAborted(options.signal);
+  assertDeadline(options.deadlineAt);
+
+  const handle = await open(absolutePath, "r");
+  try {
+    const st = await handle.stat();
+    if (st.size > options.maxFileBytes) return "oversize";
+    const remaining = options.maxScanBytesRemaining();
+    if (remaining <= 0) return "scan";
+    if (st.size > remaining) {
+      options.chargeScan(remaining);
+      return "scan";
+    }
+    const buf = await handle.readFile();
+    options.chargeScan(buf.length);
+    if (isBinaryBuffer(buf.subarray(0, options.binarySniffBytes))) return "binary";
+
+    for (const match of await matcher(buf.toString("utf8"), options.context)) {
+      if (options.maxMatchesRemaining() <= 0) return "matches";
+      options.pushMatch({ path: relativePath, ...match });
+    }
+    return "ok";
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function searchLocal(
+  request: RepositorySearchRequest,
+  defaults: ResolvedRepositoryLimits,
+  walk: RepositoryWalk,
+): Promise<RepositorySearchResult> {
+  const mode = request.mode ?? "literal";
+  if (mode !== "literal") {
+    throw new RepositoryError(`unsupported search mode: ${String(mode)} (literal only)`);
+  }
+  const caseSensitive = request.caseSensitive === true;
+  const matcher = request.matcher ?? literalMatcher(request.query, caseSensitive, defaults.maxPatternBytes, defaults.maxLineBytes);
+
+  const resolved = await resolveRepoPath(request.root, request.path);
+  const maxMatches = validateCodingLimit("maxMatches", request.maxMatches ?? defaults.maxMatches, HARD_MAX_SEARCH_MATCHES);
+  const context = validateCodingLimitAllowZero("context", request.context ?? defaults.maxContextLines, HARD_MAX_SEARCH_CONTEXT_LINES);
+  const exclude = new Set(request.exclude ?? defaults.exclude);
+  const globMatch = request.glob !== undefined ? compileGlob(request.glob) : undefined;
+  const deadlineAt = request.deadlineMs !== undefined ? Date.now() + request.deadlineMs : Date.now() + defaults.maxTimeMs;
+
+  const matches: RepositorySearchMatch[] = [];
+  let scannedBytes = 0;
+  let scannedFiles = 0;
+  let scannedEntries = 0;
+  let filesSkippedBinary = 0;
+  let filesSkippedOversize = 0;
+  let truncated = false;
+  let truncatedBy: RepositorySearchResult["truncatedBy"] = null;
+
+  const runFile = async (absolutePath: string, relativePath: string): Promise<void> => {
+    if (truncated) return;
+    const status = await searchFile(absolutePath, relativePath, matcher, {
+      maxFileBytes: defaults.maxFileBytes,
+      maxScanBytesRemaining: () => defaults.maxScanBytes - scannedBytes,
+      chargeScan: (n) => {
+        scannedBytes += n;
+      },
+      context,
+      maxMatchesRemaining: () => maxMatches - matches.length,
+      pushMatch: (match) => {
+        if (matches.length < maxMatches) matches.push(match);
+      },
+      signal: request.signal,
+      deadlineAt,
+      binarySniffBytes: defaults.binarySniffBytes,
+    });
+    if (status === "binary") filesSkippedBinary++;
+    else if (status === "oversize") filesSkippedOversize++;
+    else if (status === "scan") {
+      truncated = true;
+      truncatedBy = "scan";
+    } else if (status === "matches") {
+      truncated = true;
+      truncatedBy = "matches";
+    }
+  };
+
+  try {
+    const startStat = await lstat(resolved.absolute);
+    if (startStat.isFile()) {
+      scannedEntries = 1;
+      if (globMatch === undefined || globMatch(resolved.relative)) {
+        scannedFiles = 1;
+        await runFile(resolved.absolute, resolved.relative);
+      }
+    } else if (startStat.isDirectory()) {
+      for await (const event of walk(resolved.rootReal, resolved.absolute, {
+        maxDepth: defaults.maxDepth,
+        maxEntries: defaults.maxEntries,
+        maxFiles: defaults.maxFiles,
+        exclude,
+        includeHidden: request.includeHidden === true,
+        signal: request.signal,
+        deadlineAt,
+      })) {
+        if (truncated) break;
+        if (event.type === "limit") {
+          truncated = true;
+          truncatedBy = event.truncatedBy;
+          break;
+        }
+        scannedEntries++;
+        if (event.entry.kind !== "file") continue;
+        if (globMatch !== undefined && !globMatch(event.entry.path)) continue;
+        scannedFiles++;
+        try {
+          await runFile(event.absolutePath, event.entry.path);
+        } catch (error) {
+          if (error instanceof RepositoryError) {
+            if (error.message === "Operation aborted") {
+              truncated = true;
+              truncatedBy = "abort";
+              break;
+            }
+            if (error.message === "Repository operation exceeded time limit") {
+              truncated = true;
+              truncatedBy = "time";
+              break;
+            }
+          }
+          // Unreadable files are skipped; walk continues.
+        }
+      }
+    } else if (startStat.isSymbolicLink()) {
+      // Symlink starts are not followed for search content.
+      scannedEntries = 1;
+    }
+  } catch (error) {
+    if (error instanceof RepositoryError && error.message === "Operation aborted") {
+      truncated = true;
+      truncatedBy = "abort";
+    } else if (error instanceof RepositoryError && error.message === "Repository operation exceeded time limit") {
+      truncated = true;
+      truncatedBy = "time";
+    } else if (error instanceof RepositoryError) {
+      throw error;
+    } else {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new RepositoryError(`cannot search path: ${message}`);
+    }
+  }
+
+  if (!truncated && matches.length >= maxMatches) {
+    truncated = true;
+    truncatedBy = "matches";
+  }
+
+  matches.sort((a, b) => {
+    if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+    if (a.line !== b.line) return a.line - b.line;
+    return a.column - b.column;
+  });
+
+  return {
+    matches: matches.slice(0, maxMatches),
+    truncated,
+    truncatedBy,
+    scannedBytes,
+    scannedFiles,
+    scannedEntries,
+    filesSkippedBinary,
+    filesSkippedOversize,
+  };
+}