sift-light 1.0.0

package/src/rg.ts

@@ -0,0 +1,574 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { abortError, RipgrepInputError, SiftLightError } from "./errors.js";
+import { excerptText } from "./excerpt.js";
+import { SearchRetention } from "./search-retention.js";
+import { consumeCappedLines } from "./capped-lines.js";
+import { isPathInsideCwd, SearchPathPolicy } from "./path-policy.js";
+import { runOwnedProcess } from "./owned-process.js";
+import { resolveRipgrepExecutable } from "./ripgrep-executable.js";
+import {
+  boundedRipgrepDiagnostic,
+  classifyRipgrepDiagnostics,
+  createRipgrepInputError,
+  describeUnreadableDiagnostics,
+  hasRequestedRootUnreadable,
+} from "./ripgrep-diagnostics.js";
+import { matchesModificationTime } from "./source.js";
+import { captureCandidateRevisions, retainStableSourceRevisions } from "./scan-revisions.js";
+import {
+  MAX_SOURCE_REVISION_CONCURRENCY,
+  MAX_PROTOCOL_LINE_BYTES,
+  MAX_SOURCE_REVISION_FILES,
+  MAX_STORED_MATCHES,
+  type MatchOccurrence,
+  type MatchRecord,
+  type SearchRequest,
+  type SearchScan,
+  type TextRange,
+} from "./types.js";
+
+interface RgText {
+  text?: string;
+  bytes?: string;
+}
+
+interface RgSubmatch {
+  match: RgText;
+  start: number;
+  end: number;
+}
+
+interface RgMatchEvent {
+  type: "match";
+  data: {
+    path: RgText;
+    lines: RgText;
+    line_number: number;
+    submatches?: RgSubmatch[];
+  };
+}
+
+export interface RipgrepRunnerOptions {
+  executable?: string;
+  maxStoredMatches?: number;
+  maxEventBytes?: number;
+  maxSourceRevisionFiles?: number;
+  maxStoredBytes?: number;
+  maxStoredOccurrences?: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isRgText(value: unknown): value is RgText {
+  return isRecord(value) && (typeof value.text === "string" || typeof value.bytes === "string");
+}
+
+function isRgSubmatch(value: unknown): value is RgSubmatch {
+  if (!isRecord(value)) return false;
+  return (
+    isRgText(value.match) &&
+    typeof value.start === "number" &&
+    Number.isSafeInteger(value.start) &&
+    typeof value.end === "number" &&
+    Number.isSafeInteger(value.end) &&
+    value.start >= 0 &&
+    value.end >= value.start
+  );
+}
+
+function isRgMatchEvent(value: unknown): value is RgMatchEvent {
+  if (!isRecord(value) || value.type !== "match" || !isRecord(value.data)) return false;
+  const submatches = value.data.submatches;
+  return (
+    isRgText(value.data.path) &&
+    isRgText(value.data.lines) &&
+    typeof value.data.line_number === "number" &&
+    Number.isSafeInteger(value.data.line_number) &&
+    value.data.line_number > 0 &&
+    (submatches === undefined || (Array.isArray(submatches) && submatches.every(isRgSubmatch)))
+  );
+}
+
+interface DecodedRgText {
+  text: string;
+  bytes: Buffer;
+  encoding: "utf-8" | "utf-16";
+}
+
+function decodeRgText(value: RgText, field: string): DecodedRgText {
+  if (typeof value.text === "string") {
+    return { text: value.text, bytes: Buffer.from(value.text, "utf8"), encoding: "utf-16" };
+  }
+  if (typeof value.bytes === "string") {
+    const bytes = Buffer.from(value.bytes, "base64");
+    return { text: bytes.toString("utf8"), bytes, encoding: "utf-8" };
+  }
+  throw new SiftLightError(`ripgrep JSON event omitted ${field}`);
+}
+
+function displayPath(rawPath: string, cwd: string): { absolutePath: string; displayPath: string } {
+  const absolutePath = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
+  const localPath = relative(cwd, absolutePath).replaceAll("\\", "/");
+  const isInsideCwd = localPath !== ".." && !localPath.startsWith("../") && !isAbsolute(localPath);
+  return {
+    absolutePath,
+    displayPath: isInsideCwd && localPath.length > 0 ? localPath : absolutePath,
+  };
+}
+function jsonObjectEnd(value: string, start: number, end: number): number | undefined {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = start; index < end; index += 1) {
+    const character = value[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"') {
+      inString = true;
+      continue;
+    }
+    if (character === "{") {
+      depth += 1;
+      continue;
+    }
+    if (character !== "}") continue;
+    depth -= 1;
+    if (depth === 0) return index + 1;
+  }
+  return undefined;
+}
+
+function jsonObjectStringProperty(
+  value: string,
+  property: string,
+  pathStart: number,
+): string | undefined {
+  let offset = pathStart + '"path"'.length;
+  while (/\s/.test(value[offset] ?? "")) offset += 1;
+  if (value[offset] !== ":") return undefined;
+  offset += 1;
+  while (/\s/.test(value[offset] ?? "")) offset += 1;
+  if (value[offset] !== "{") return undefined;
+  const objectEnd = jsonObjectEnd(value, offset, value.length);
+  if (objectEnd === undefined) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(value.slice(offset, objectEnd));
+    if (!isRecord(parsed)) return undefined;
+    const candidate = parsed[property];
+    return typeof candidate === "string" ? candidate : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function oversizedMatchPath(
+  prefix: string,
+  cwd: string,
+): { absolutePath: string; displayPath: string } | undefined {
+  const pathStart = prefix.indexOf('"path"');
+  if (pathStart < 0) return undefined;
+  const text = jsonObjectStringProperty(prefix, "text", pathStart);
+  if (text !== undefined) return displayPath(text, cwd);
+  const encoded = jsonObjectStringProperty(prefix, "bytes", pathStart);
+  if (encoded === undefined) return undefined;
+  const bytes = Buffer.from(encoded, "base64");
+  const decoded = bytes.toString("utf8");
+  return Buffer.from(decoded, "utf8").equals(bytes) ? displayPath(decoded, cwd) : undefined;
+}
+
+async function assertSearchTargetIdentity(
+  policy: SearchPathPolicy,
+  path: string,
+  expectedCanonical: string | undefined,
+): Promise<void> {
+  const currentCanonical = await policy.resolveExistingPath(path);
+  if (currentCanonical !== expectedCanonical) {
+    throw new SiftLightError("Search target changed during validation; retry the search");
+  }
+}
+
+async function assertRetainedPathsAllowed(
+  policy: SearchPathPolicy,
+  paths: readonly string[],
+  signal?: AbortSignal,
+): Promise<void> {
+  for (let offset = 0; offset < paths.length; offset += MAX_SOURCE_REVISION_CONCURRENCY) {
+    if (signal?.aborted) throw abortError();
+    const batch = paths.slice(offset, offset + MAX_SOURCE_REVISION_CONCURRENCY);
+    // oxlint-disable-next-line no-await-in-loop -- bounded batches avoid unbounded filesystem work.
+    await Promise.all(batch.map((path) => policy.resolveExistingPath(path)));
+  }
+}
+
+function utf16Length(value: string): number {
+  return value.length;
+}
+
+function byteOffsetToCharacter(
+  bytes: Buffer,
+  byteOffset: number,
+  encoding: "utf-8" | "utf-16",
+): number {
+  if (byteOffset < 0 || byteOffset > bytes.length) {
+    throw new SiftLightError("ripgrep emitted a submatch outside its matching line");
+  }
+  if (encoding === "utf-8") return byteOffset;
+  const prefix = bytes.subarray(0, byteOffset).toString("utf8").replaceAll("\r", "");
+  return utf16Length(prefix);
+}
+
+function createOccurrences(
+  lineNumber: number,
+  decodedLine: DecodedRgText,
+  submatches: RgSubmatch[],
+): MatchOccurrence[] {
+  const range: TextRange = {
+    start: { line: lineNumber - 1, character: 0 },
+    end: { line: lineNumber - 1, character: 0 },
+    encoding: decodedLine.encoding,
+  };
+  const occurrences: MatchOccurrence[] = [];
+  for (const submatch of submatches) {
+    if (submatch.end > decodedLine.bytes.length) {
+      throw new SiftLightError("ripgrep emitted a submatch outside its matching line");
+    }
+    occurrences.push({
+      byteStart: submatch.start,
+      byteEnd: submatch.end,
+      range: {
+        start: {
+          ...range.start,
+          character: byteOffsetToCharacter(decodedLine.bytes, submatch.start, range.encoding),
+        },
+        end: {
+          ...range.end,
+          character: byteOffsetToCharacter(decodedLine.bytes, submatch.end, range.encoding),
+        },
+        encoding: range.encoding,
+      },
+    });
+  }
+  return occurrences;
+}
+
+export function fileScopeArguments(
+  request: Pick<SearchRequest, "hidden" | "glob" | "exclude"> & {
+    ignorePolicy?: "respect" | "include";
+  },
+): string[] {
+  const args: string[] = [];
+  if (request.ignorePolicy === "include") args.push("--no-ignore", "--no-ignore-parent");
+  if (request.hidden) args.push("--hidden");
+  for (const glob of request.glob) args.push("--glob", glob);
+  for (const excluded of request.exclude) {
+    const normalized = excluded.startsWith("!") ? excluded : `!${excluded}`;
+    args.push("--glob", normalized);
+  }
+  // Ripgrep gives the last matching glob priority, so this invariant must come last.
+  args.push("--iglob", "!.git", "--iglob", "!.git/**", "--iglob", "!**/.git/**");
+  return args;
+}
+
+export function buildRipgrepArguments(
+  request: SearchRequest,
+  cwd: string,
+  validatedSearchPath?: string,
+): string[] {
+  const searchPath = validatedSearchPath ?? resolve(cwd, request.path ?? ".");
+  const policy = new SearchPathPolicy(cwd);
+  policy.assertPath(searchPath);
+  const args = [
+    "--no-config",
+    "--json",
+    "--line-number",
+    "--color=never",
+    "--no-heading",
+    ...(request.binaryAsText ? ["--text"] : []),
+    ...fileScopeArguments(request),
+    ...policy.ripgrepGlobArguments(searchPath),
+  ];
+
+  args.push(...patternArguments(request));
+
+  const searchTarget = isPathInsideCwd(searchPath, cwd)
+    ? relative(resolve(cwd), searchPath) || "."
+    : searchPath;
+  args.push("--", request.pattern, searchTarget);
+  return args;
+}
+
+export function patternArguments(
+  request: Pick<SearchRequest, "literal" | "ignoreCase" | "wholeWord">,
+): string[] {
+  return [
+    ...(request.wholeWord ? ["--word-regexp"] : []),
+    ...(request.literal ? ["--fixed-strings"] : []),
+    request.ignoreCase === true
+      ? "--ignore-case"
+      : request.ignoreCase === false
+        ? "--case-sensitive"
+        : "--smart-case",
+  ];
+}
+
+export function createRipgrepRunner(options: RipgrepRunnerOptions = {}) {
+  const maxStoredMatches = options.maxStoredMatches ?? MAX_STORED_MATCHES;
+  const maxEventBytes = options.maxEventBytes ?? MAX_PROTOCOL_LINE_BYTES;
+  const maxSourceRevisionFiles = options.maxSourceRevisionFiles ?? MAX_SOURCE_REVISION_FILES;
+
+  return async function runRipgrep(
+    request: SearchRequest,
+    cwd: string,
+    signal?: AbortSignal,
+  ): Promise<SearchScan> {
+    if (signal?.aborted) throw abortError();
+    const executable = options.executable ?? (await resolveRipgrepExecutable());
+    const searchPath = resolve(cwd, request.path ?? ".");
+    const policy = new SearchPathPolicy(cwd);
+    const validatedSearchPath = await policy.resolveSearchTarget(searchPath);
+    const expectedSearchTarget = await policy.resolveExistingPath(validatedSearchPath);
+    const searchTarget = isPathInsideCwd(validatedSearchPath, cwd)
+      ? relative(resolve(cwd), validatedSearchPath) || "."
+      : validatedSearchPath;
+    const args = buildRipgrepArguments(request, cwd, validatedSearchPath);
+    if (signal?.aborted) throw abortError();
+
+    const matches: MatchRecord[] = [];
+    const retention = new SearchRetention(options.maxStoredBytes, options.maxStoredOccurrences);
+    const fileCounts = new Map<string, number>();
+    const lossyPaths = new Set<string>();
+    const oversizedPathReasons = new Set<string>();
+    let totalMatches = 0;
+    let truncatedLines = 0;
+    let modificationTimeFilterIncomplete = false;
+    let candidateRevisions = new Map<string, import("./types.js").SourceRevision>();
+
+    const onLine = (line: string) => {
+      if (line.length === 0) return;
+      let event: unknown;
+      try {
+        event = JSON.parse(line);
+      } catch (error) {
+        throw new SiftLightError("Failed to parse ripgrep JSON output", { cause: error });
+      }
+      if (!isRecord(event)) return;
+      if (event.type !== "match") return;
+      if (!isRgMatchEvent(event)) {
+        throw new SiftLightError("ripgrep emitted an invalid match event");
+      }
+
+      const rawPath = decodeRgText(event.data.path, "path");
+      const rawContent = decodeRgText(event.data.lines, "line content");
+      const normalizedContent = rawContent.text.replaceAll("\r", "").replace(/\n$/, "");
+      const path = displayPath(rawPath.text, cwd);
+      if (request.modifiedAfterMs !== undefined || request.modifiedBeforeMs !== undefined) {
+        const revision = candidateRevisions.get(path.absolutePath);
+        if (!revision) {
+          modificationTimeFilterIncomplete = true;
+          retention.noteLimit(
+            `Modification time could not be verified for ${path.displayPath}; matching evidence was retained`,
+          );
+        } else if (
+          !matchesModificationTime(revision, request.modifiedAfterMs, request.modifiedBeforeMs)
+        ) {
+          return;
+        }
+      }
+      if (rawPath.encoding === "utf-8") lossyPaths.add(path.absolutePath);
+      const submatches = event.data.submatches ?? [];
+      if (submatches.some((match) => match.end > rawContent.bytes.length))
+        throw new SiftLightError("ripgrep emitted a submatch outside its matching line");
+      const primaryOccurrence = submatches[0];
+      let focusStart = 0;
+      let focusEnd = 0;
+      if (primaryOccurrence) {
+        focusStart = byteOffsetToCharacter(rawContent.bytes, primaryOccurrence.start, "utf-16");
+        focusEnd = byteOffsetToCharacter(rawContent.bytes, primaryOccurrence.end, "utf-16");
+      }
+      const excerpt = excerptText(normalizedContent, focusStart, focusEnd);
+      const { text: lineContent, truncated: lineTruncated } = excerpt;
+
+      totalMatches += 1;
+      if (!fileCounts.has(path.displayPath)) {
+        if (retention.file(path.displayPath, path.absolutePath))
+          fileCounts.set(path.displayPath, 0);
+      }
+      if (fileCounts.has(path.displayPath))
+        fileCounts.set(path.displayPath, (fileCounts.get(path.displayPath) ?? 0) + 1);
+      if (lineTruncated) truncatedLines += 1;
+      if (matches.length >= maxStoredMatches)
+        retention.noteLimit(
+          `Matching-line retention reached the ${String(maxStoredMatches)} limit`,
+        );
+      if (matches.length < maxStoredMatches && retention.canRetainOccurrences(submatches.length)) {
+        const match = {
+          ...path,
+          lineNumber: event.data.line_number,
+          lineContent,
+          lineTruncated,
+          occurrences: createOccurrences(event.data.line_number, rawContent, submatches),
+        };
+        if (retention.retain(match)) matches.push(match);
+      }
+    };
+
+    try {
+      const before = await captureCandidateRevisions(
+        executable,
+        [
+          "--no-config",
+          "--files",
+          "--null",
+          ...fileScopeArguments(request),
+          ...policy.ripgrepGlobArguments(validatedSearchPath),
+          "--",
+          searchTarget,
+        ],
+        cwd,
+        maxSourceRevisionFiles,
+        signal,
+        request.redact,
+      );
+      let ignoredFileCount = 0;
+      let ignoredFileSamples: string[] = [];
+      let filesystemCoverage: SearchScan["filesystemCoverage"] = "complete";
+      const filesystemCoverageReasons = new Set<string>();
+      if (before.enumerationTruncated) {
+        filesystemCoverage = "partial";
+        filesystemCoverageReasons.add(
+          `Filesystem coverage comparison reached the ${String(maxSourceRevisionFiles)} file metadata limit`,
+        );
+      }
+      if (before.invalidPathCount > 0) {
+        filesystemCoverage = "partial";
+        filesystemCoverageReasons.add(
+          `${String(before.invalidPathCount)} candidate path(s) were not valid UTF-8`,
+        );
+      }
+      if (request.ignorePolicy !== "include") {
+        const allCandidates = await captureCandidateRevisions(
+          executable,
+          [
+            "--no-config",
+            "--files",
+            "--null",
+            ...fileScopeArguments({ ...request, ignorePolicy: "include" }),
+            ...policy.ripgrepGlobArguments(validatedSearchPath),
+            "--",
+            searchTarget,
+          ],
+          cwd,
+          maxSourceRevisionFiles,
+          signal,
+          request.redact,
+        );
+        const ignored = [...allCandidates.revisions.keys()].filter(
+          (path) => !before.revisions.has(path),
+        );
+        ignoredFileCount = ignored.length;
+        ignoredFileSamples = ignored.slice(0, 20).map((path) => displayPath(path, cwd).displayPath);
+        if (ignoredFileCount > 0) filesystemCoverage = "policy-filtered";
+        if (allCandidates.unreadable.length > 0) {
+          filesystemCoverage = "partial";
+          retention.noteLimit(describeUnreadableDiagnostics(allCandidates.unreadable));
+        }
+        if (allCandidates.enumerationTruncated) {
+          filesystemCoverage = "partial";
+          filesystemCoverageReasons.add(
+            `Include-ignored coverage comparison reached the ${String(maxSourceRevisionFiles)} file metadata limit`,
+          );
+        }
+        if (allCandidates.invalidPathCount > 0) {
+          filesystemCoverage = "partial";
+          filesystemCoverageReasons.add(
+            `${String(allCandidates.invalidPathCount)} include-ignored candidate path(s) were not valid UTF-8`,
+          );
+        }
+      }
+      if (hasRequestedRootUnreadable(before.unreadable, cwd, validatedSearchPath))
+        throw new SiftLightError(describeUnreadableDiagnostics(before.unreadable));
+      candidateRevisions = before.revisions;
+      if (before.unreadable.length > 0)
+        retention.noteLimit(describeUnreadableDiagnostics(before.unreadable));
+      if (before.unreadable.length > 0) filesystemCoverage = "partial";
+      if (before.unreadable.length > 0)
+        filesystemCoverageReasons.add(describeUnreadableDiagnostics(before.unreadable));
+      await assertSearchTargetIdentity(policy, validatedSearchPath, expectedSearchTarget);
+      const { code, stderr } = await runOwnedProcess(
+        { executable, args, cwd, ...(signal ? { signal } : {}) },
+        (stdout) =>
+          consumeCappedLines(stdout, onLine, {
+            maxLineBytes: maxEventBytes,
+            onLineTooLong: ({ prefix, observedBytes }) => {
+              const source = oversizedMatchPath(prefix, cwd);
+              const label = source?.displayPath ?? "unknown source";
+              if (oversizedPathReasons.has(label)) return;
+              oversizedPathReasons.add(label);
+              retention.noteLimit(
+                `Skipped oversized ripgrep match line in ${JSON.stringify(label)}; observed at least ${String(observedBytes)} bytes, limit is ${String(maxEventBytes)} bytes`,
+              );
+            },
+          }),
+      );
+      const diagnostics = classifyRipgrepDiagnostics(stderr);
+      const inputError = createRipgrepInputError(stderr, request.redact);
+      if (inputError) throw inputError;
+      if (hasRequestedRootUnreadable(diagnostics.unreadable, cwd, validatedSearchPath))
+        throw new SiftLightError(describeUnreadableDiagnostics(diagnostics.unreadable));
+      if (diagnostics.unreadable.length > 0)
+        retention.noteLimit(describeUnreadableDiagnostics(diagnostics.unreadable));
+      if (diagnostics.unreadable.length > 0) filesystemCoverage = "partial";
+      if (diagnostics.unreadable.length > 0)
+        filesystemCoverageReasons.add(describeUnreadableDiagnostics(diagnostics.unreadable));
+      if (code === 2 && (diagnostics.other.length > 0 || diagnostics.unreadable.length === 0)) {
+        throw new SiftLightError(stderr.trim() || `ripgrep exited with status ${String(code)}`);
+      }
+      await assertSearchTargetIdentity(policy, validatedSearchPath, expectedSearchTarget);
+      const retainedPaths = new Set(
+        matches.map((match) => match.absolutePath).filter((path) => !lossyPaths.has(path)),
+      );
+      await assertRetainedPathsAllowed(policy, [...retainedPaths], signal);
+      const sourceRevisions = await retainStableSourceRevisions(
+        retainedPaths,
+        before.revisions,
+        signal,
+      );
+      if (signal?.aborted) throw abortError();
+      return {
+        request,
+        matches,
+        totalMatches,
+        fileCounts,
+        sourceRevisions,
+        snapshotComplete:
+          matches.length === totalMatches &&
+          !modificationTimeFilterIncomplete &&
+          retention.details.reasons.length === 0,
+        filesystemCoverage,
+        filesystemCoverageReasons: [...filesystemCoverageReasons],
+        ignoredFileCount,
+        ignoredFileSamples,
+        searchedFileCount: before.revisions.size,
+        truncatedLines,
+        retention: retention.details,
+      };
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") throw abortError();
+      if (error instanceof RipgrepInputError) throw error;
+      const cause = error instanceof Error ? error : new Error(String(error));
+      const executableMissing = "code" in cause && cause.code === "ENOENT";
+      const message = executableMissing
+        ? `ripgrep executable not found: ${boundedRipgrepDiagnostic(executable, request.redact)}`
+        : boundedRipgrepDiagnostic(cause.message, request.redact);
+      throw new SiftLightError(message, { cause });
+    }
+  };
+}
+
+export type RipgrepRunner = ReturnType<typeof createRipgrepRunner>;

package/src/ripgrep-diagnostics.ts

@@ -0,0 +1,122 @@
+import { resolve } from "node:path";
+import { RipgrepInputError, type RipgrepInputErrorCode } from "./errors.js";
+import { redactDiagnosticText } from "./redaction.js";
+
+export interface RipgrepUnreadableDiagnostic {
+  message: string;
+  path?: string;
+}
+
+export interface RipgrepDiagnostics {
+  unreadable: RipgrepUnreadableDiagnostic[];
+  other: string[];
+}
+
+const UNREADABLE_SUFFIX = /:\s+Permission denied(?:\s+\(os error 13\))?\s*$/iu;
+const UNREADABLE_CODE = /\(os error 13\)\s*$/iu;
+const INVALID_REGEX_DIAGNOSTIC = /(?:^|\n)\s*(?:rg:\s*)?regex parse error:/iu;
+const MISSING_PATH_DIAGNOSTIC =
+  /(?:IO error for operation on .+?:\s*)?No such file or directory \(os error 2\)\s*$/iu;
+const MAX_RIPGREP_DIAGNOSTIC_CHARACTERS = 4_096;
+
+function diagnosticLines(stderr: string): string[] {
+  return stderr
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+}
+
+export function boundedRipgrepDiagnostic(value: string, redact = false): string {
+  const safe = redact ? redactDiagnosticText(value) : value;
+  const normalized = safe.toWellFormed();
+  return normalized.length <= MAX_RIPGREP_DIAGNOSTIC_CHARACTERS
+    ? normalized
+    : `${normalized.slice(0, MAX_RIPGREP_DIAGNOSTIC_CHARACTERS - 1)}…`;
+}
+
+/** Classify only stable ripgrep input failures; unknown stderr remains a normal runtime error. */
+export function classifyRipgrepInputFailure(stderr: string): RipgrepInputErrorCode | undefined {
+  if (INVALID_REGEX_DIAGNOSTIC.test(stderr)) return "E_REGEX_INVALID";
+  if (diagnosticLines(stderr).some((line) => MISSING_PATH_DIAGNOSTIC.test(line)))
+    return "E_SEARCH_PATH_NOT_FOUND";
+  return undefined;
+}
+
+function missingPathFromDiagnostics(stderr: string): string | undefined {
+  for (const line of diagnosticLines(stderr)) {
+    const operation =
+      /IO error for operation on (.+?):\s*No such file or directory \(os error 2\)\s*$/iu.exec(
+        line,
+      );
+    if (operation?.[1]) return operation[1].trim();
+    const direct = /^rg:\s*(.+?):\s*No such file or directory \(os error 2\)\s*$/iu.exec(line);
+    if (direct?.[1]) return direct[1].trim();
+  }
+  return undefined;
+}
+
+export function createRipgrepInputError(
+  stderr: string,
+  redact = false,
+): RipgrepInputError | undefined {
+  const code = classifyRipgrepInputFailure(stderr);
+  if (code === "E_REGEX_INVALID") {
+    return new RipgrepInputError(
+      code,
+      "ripgrep regex parse error: pattern is not a valid regular expression.",
+      "Correct pattern or set literal=true for source text; no automatic literal conversion was attempted.",
+    );
+  }
+  if (code === "E_SEARCH_PATH_NOT_FOUND") {
+    const path = missingPathFromDiagnostics(stderr);
+    const location = path ? ` (${JSON.stringify(boundedRipgrepDiagnostic(path, redact))})` : "";
+    return new RipgrepInputError(
+      code,
+      `A searched path${location} does not exist or became unavailable.`,
+      "Provide an existing exact path, or use mode=files with query to discover an unknown filename; no retry or scope expansion was attempted.",
+    );
+  }
+  // Known input failures above intentionally omit ripgrep's raw pattern and path echo.
+  return undefined;
+}
+
+function unreadablePath(line: string, suffix: RegExp): string | undefined {
+  const match = suffix.exec(line);
+  if (!match || match.index === undefined) return undefined;
+  const prefix = line.slice(0, match.index).trim();
+  const separator = prefix.indexOf(": ");
+  const path = (separator < 0 ? prefix : prefix.slice(separator + 2)).trim();
+  return path.replace(/^['"]|['"]$/gu, "") || undefined;
+}
+
+export function classifyRipgrepDiagnostics(stderr: string): RipgrepDiagnostics {
+  const unreadable: RipgrepUnreadableDiagnostic[] = [];
+  const other: string[] = [];
+  for (const line of diagnosticLines(stderr)) {
+    const path = unreadablePath(line, UNREADABLE_SUFFIX);
+    if (path !== undefined || UNREADABLE_CODE.test(line)) {
+      unreadable.push({ message: line, ...(path ? { path } : {}) });
+    } else {
+      other.push(line);
+    }
+  }
+  return { unreadable, other };
+}
+
+export function hasRequestedRootUnreadable(
+  diagnostics: readonly RipgrepUnreadableDiagnostic[],
+  cwd: string,
+  searchPath: string,
+): boolean {
+  const expected = resolve(cwd, searchPath);
+  return diagnostics.some(
+    (diagnostic) => diagnostic.path === undefined || resolve(cwd, diagnostic.path) === expected,
+  );
+}
+
+export function describeUnreadableDiagnostics(
+  diagnostics: readonly RipgrepUnreadableDiagnostic[],
+): string {
+  const messages = [...new Set(diagnostics.map((diagnostic) => diagnostic.message))];
+  return `Ripgrep skipped ${String(messages.length)} unreadable path(s); search coverage is partial: ${messages.join("; ")}`;
+}