harnery 0.7.1 → 0.9.0

package/src/commands/grep.ts

@@ -1,15 +1,40 @@
 import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { resolveSearchEngine, type SearchEngine } from "../lib/tools/ripgrep.ts";
 
 /**
- * `grep`: monorepo-aware code search. Thin wrapper over grep -rn with
- * smart default excludes (skip dist/.next/node_modules/.git/...), repo
- * scoping (`--repo <name>` or `--all-repos`), and language presets.
+ * `grep`: monorepo-aware code search. Prefers ripgrep (`rg`) when it is on
+ * PATH and falls back to GNU/BSD grep transparently — both engines are driven
+ * with equivalent flags and their output is parsed into the same envelope, so
+ * results are identical (pinned by tests/unit/grep-engine.test.ts).
+ * Smart default excludes (skip dist/.next/node_modules/.git/...), repo
+ * scoping (`--repo <name>` or `--all-repos`), language presets, file-level
+ * boolean composition (`--and` / `--without`), and context (`-C`/`-A`/`-B`).
  *
- * Default behavior matches grep's "regex" semantics (`-E` extended). Use
- * `-F` / `--literal` to pin to literal-string mode. Output is line-oriented
- * `file:line:content` in TTY mode, `{rows, total, truncated}` in --json mode.
+ * Engine selection: `HARNERY_GREP_ENGINE=rg|grep` forces one; otherwise `rg`
+ * is resolved (managed install, PATH, or opt-in auto-provision; see
+ * resolveEngine) and used when available. Repos are searched in parallel, and
+ * in `--all-repos` mode the parent scan prunes submodule directories so each
+ * match is attributed to exactly one repo.
+ *
+ * Output framing: content searches request the NUL filename delimiter
+ * (`--null` on both engines — the long spelling, because BSD grep repurposes
+ * `-Z` for decompression) so filename boundaries are never inferred from
+ * punctuation. Context lines are NOT requested from the engines: matches are
+ * selected (and budgeted) first, then context windows are materialized from
+ * one file read per selected file, which keeps `--limit` semantics exact and
+ * both engines byte-identical.
+ *
+ * Default behavior matches extended-regex semantics (`grep -E` / ripgrep's
+ * default). Use `-F` / `--literal` to pin to literal-string mode. Output is
+ * line-oriented `file:line:content` in TTY mode (context rows render
+ * grep-style as `file-line-content`); `--json` emits the full GrepResult
+ * envelope `{ pattern, mode, engine, and_patterns, without_patterns, repos,
+ * total_matches, total_files, truncated, elapsed_ms }`. Matches are sorted
+ * (file, then line) for stable output across runs and engines.
  */
 
 const DEFAULT_EXCLUDE_DIRS = [
@@ -51,29 +76,40 @@ const LANG_GLOBS: Record<string, string[]> = {
   rs: ["*.rs"],
 };
 
-interface GrepOpts {
+export type GrepEngine = SearchEngine;
+
+export interface GrepOpts {
   repo?: string;
   allRepos?: boolean;
-  lang?: string;
+  /** Repeatable and/or comma-separated (`--lang ts,tsx`). A bare string is accepted for direct callers. */
+  lang?: string | string[];
   ignoreCase?: boolean;
   wholeWord?: boolean;
   literal?: boolean;
   filesOnly?: boolean;
+  files?: boolean;
   count?: boolean;
   context?: string;
+  afterContext?: string;
+  beforeContext?: string;
   maxCount?: string;
   limit?: string;
   include?: string[];
   exclude?: string[];
+  and?: string[];
+  without?: string[];
+  quiet?: boolean;
   noDefaultExcludes?: boolean;
   json?: boolean;
 }
 
-interface Match {
+export interface Match {
   repo: string;
   file: string;
   line: number;
   text: string;
+  /** "match" = primary result row (counts toward totals + --limit); "context" = free -C/-A/-B row. */
+  kind: "match" | "context";
 }
 
 export function registerGrepCommand(
@@ -84,20 +120,50 @@ export function registerGrepCommand(
   program
     .command("grep <pattern> [paths...]")
     .description(
-      "Monorepo-aware code search. Skips dist/.next/node_modules/.git/... by default. " +
-        "Use --repo, --all-repos, --lang for scoping. Regex by default; -F for literal.",
+      "Monorepo-aware code search (ripgrep when available, GNU grep fallback). " +
+        "Skips dist/.next/node_modules/.git/... by default. " +
+        "Use --repo, --all-repos, --lang for scoping; --and/--without for file-level composition. " +
+        "Regex by default; -F for literal.",
     )
     .option("--repo <name>", "Scope to one submodule (`.` = parent repo root)")
     .option("--all-repos", "Search parent + every submodule")
-    .option("--lang <lang>", `File type preset (${Object.keys(LANG_GLOBS).join(", ")})`)
+    .option(
+      "--lang <lang>",
+      `File type preset, repeatable or comma-separated (${Object.keys(LANG_GLOBS).join(", ")})`,
+      collect,
+      [] as string[],
+    )
     .option("-i, --ignore-case", "Case-insensitive match")
     .option("-w, --whole-word", "Match whole words only")
     .option("-F, --literal", "Treat <pattern> as a literal string (no regex)")
     .option("-l, --files-only", "Only print file names containing a match")
+    .option(
+      "--files",
+      "Filename search: treat <pattern> as a filename glob and list matching files " +
+        "(rg --files when available, POSIX find fallback)",
+    )
     .option("-c, --count", "Print match count per file (suppresses content)")
     .option("-C, --context <n>", "Print N lines of context around each match", "0")
+    .option("-A, --after-context <n>", "Print N lines after each match (overrides -C's after side)")
+    .option(
+      "-B, --before-context <n>",
+      "Print N lines before each match (overrides -C's before side)",
+    )
     .option("--max-count <n>", "Stop after N matches per file")
     .option("--limit <n>", "Truncate output to N matches total")
+    .option(
+      "--and <pattern>",
+      "Only show files that ALSO contain this pattern (file-level, repeatable)",
+      collect,
+      [] as string[],
+    )
+    .option(
+      "--without <pattern>",
+      "Drop files that contain this pattern (file-level, repeatable)",
+      collect,
+      [] as string[],
+    )
+    .option("-q, --quiet", "No output; exit 0 if any match exists, 1 if none")
     .option("--include <glob>", "Extra --include glob (repeatable)", collect, [] as string[])
     .option("--exclude <glob>", "Extra --exclude glob (repeatable)", collect, [] as string[])
     .option("--no-default-excludes", "Disable the default skip list (node_modules, dist, etc.)")
@@ -105,6 +171,12 @@ export function registerGrepCommand(
     .action(async (pattern: string, paths: string[], opts: GrepOpts) => {
       try {
         const result = await runGrep(pattern, paths, opts, context);
+        if (opts.quiet) {
+          // No output by contract; grep-conventional status. exitCode (not
+          // process.exit) so an embedding host isn't terminated mid-flush.
+          process.exitCode = result.total_matches > 0 ? 0 : 1;
+          return;
+        }
         if (opts.json) {
           emit.config({ format: "json" });
           emit.data(result);
@@ -122,9 +194,12 @@ function collect(value: string, prev: string[]): string[] {
   return [...prev, value];
 }
 
-interface GrepResult {
+export interface GrepResult {
   pattern: string;
-  mode: "regex" | "literal";
+  mode: "regex" | "literal" | "files";
+  engine: GrepEngine;
+  and_patterns: string[];
+  without_patterns: string[];
   repos: { name: string; cwd: string; matches: Match[]; truncated: boolean }[];
   total_matches: number;
   total_files: number;
@@ -132,47 +207,204 @@ interface GrepResult {
   elapsed_ms: number;
 }
 
-async function runGrep(
+/** Validated, resolved options — built once before repo fan-out. */
+interface NormOpts {
+  limit: number; // Infinity when unset
+  maxCount: number | undefined;
+  before: number;
+  after: number;
+  langGlobs: string[] | undefined;
+  andPatterns: string[];
+  withoutPatterns: string[];
+}
+
+/**
+ * Parse a strictly-decimal integer option. Rejects empty, negative, signed,
+ * fractional, and trailing-junk values before any engine is spawned.
+ */
+function parseIntOpt(flag: string, raw: string, min: number): number {
+  if (!/^\d+$/.test(raw.trim())) {
+    throw new Error(`${flag} expects a non-negative integer, got "${raw}"`);
+  }
+  const n = Number.parseInt(raw.trim(), 10);
+  if (n < min) throw new Error(`${flag} must be >= ${min}, got ${n}`);
+  return n;
+}
+
+function normalizeLangs(lang: string | string[] | undefined): string[] | undefined {
+  const rawValues = typeof lang === "string" ? [lang] : (lang ?? []);
+  const keys: string[] = [];
+  for (const raw of rawValues) {
+    for (const piece of raw.split(",")) {
+      const key = piece.trim();
+      if (key === "") continue;
+      if (!LANG_GLOBS[key]) {
+        throw new Error(`unknown --lang "${key}". Valid: ${Object.keys(LANG_GLOBS).join(", ")}`);
+      }
+      if (!keys.includes(key)) keys.push(key);
+    }
+  }
+  if (keys.length === 0) return undefined;
+  const globs: string[] = [];
+  for (const key of keys) {
+    const langGlobs = LANG_GLOBS[key];
+    if (!langGlobs) continue;
+    for (const g of langGlobs) if (!globs.includes(g)) globs.push(g);
+  }
+  return globs;
+}
+
+/** Validate numerics, resolve context sides, expand langs, enforce the compatibility matrix. */
+function normalizeOpts(opts: GrepOpts): NormOpts {
+  const limit = opts.limit ? parseIntOpt("--limit", opts.limit, 1) : Number.POSITIVE_INFINITY;
+  const maxCount = opts.maxCount ? parseIntOpt("--max-count", opts.maxCount, 1) : undefined;
+  const c = opts.context !== undefined ? parseIntOpt("-C/--context", opts.context, 0) : 0;
+  const before =
+    opts.beforeContext !== undefined
+      ? parseIntOpt("-B/--before-context", opts.beforeContext, 0)
+      : c;
+  const after =
+    opts.afterContext !== undefined ? parseIntOpt("-A/--after-context", opts.afterContext, 0) : c;
+  const andPatterns = opts.and ?? [];
+  const withoutPatterns = opts.without ?? [];
+  const contextActive = before > 0 || after > 0;
+
+  if (opts.files) {
+    // Filename mode lists files by name glob; content-search flags make no
+    // sense here — reject loudly rather than silently ignoring them.
+    const incompatible: [unknown, string][] = [
+      [normalizeLangs(opts.lang)?.length, "--lang"],
+      [opts.count, "-c/--count"],
+      [opts.wholeWord, "-w/--whole-word"],
+      [opts.literal, "-F/--literal"],
+      [opts.maxCount, "--max-count"],
+      [opts.include?.length, "--include"],
+      [contextActive ? true : undefined, "-C/-A/-B context"],
+      [andPatterns.length ? true : undefined, "--and"],
+      [withoutPatterns.length ? true : undefined, "--without"],
+    ];
+    for (const [set, flag] of incompatible) {
+      if (set) throw new Error(`${flag} does not apply to --files (filename glob) mode`);
+    }
+  }
+  if (contextActive) {
+    const rejected: [unknown, string][] = [
+      [opts.filesOnly, "-l/--files-only"],
+      [opts.count, "-c/--count"],
+      [opts.quiet, "-q/--quiet"],
+    ];
+    for (const [set, flag] of rejected) {
+      if (set) throw new Error(`-C/-A/-B context does not combine with ${flag}`);
+    }
+  }
+  if (opts.quiet) {
+    const rejected: [unknown, string][] = [
+      [opts.json, "--json"],
+      [opts.filesOnly, "-l/--files-only"],
+      [opts.count, "-c/--count"],
+      [opts.limit, "--limit"],
+    ];
+    for (const [set, flag] of rejected) {
+      if (set) throw new Error(`-q/--quiet does not combine with ${flag}`);
+    }
+  }
+
+  return {
+    // -q only needs existence: one accepted primary row settles the exit code.
+    limit: opts.quiet ? 1 : limit,
+    maxCount,
+    before,
+    after,
+    langGlobs: normalizeLangs(opts.lang),
+    andPatterns,
+    withoutPatterns,
+  };
+}
+
+/** Exported for tests (not part of the package exports map). */
+export async function runGrep(
   pattern: string,
   paths: string[],
   opts: GrepOpts,
   context: HarneryProgramContext | undefined,
 ): Promise<GrepResult> {
   if (!pattern) throw new Error("pattern required");
+  const norm = normalizeOpts(opts);
   const started = Date.now();
 
+  const { engine, rgBin } = await resolveSearchEngine("grep");
   const repos = resolveRepos(opts, context);
-  const limit = opts.limit ? Number.parseInt(opts.limit, 10) : Number.POSITIVE_INFINITY;
+
+  // Host-injected default excludes (generated mirrors, vendored trees, ...)
+  // ride the same --no-default-excludes gate as the built-in list.
+  const hostExcludeDirs = opts.noDefaultExcludes ? [] : (context?.grepExcludeDirs ?? []);
+
+  // All repos are searched concurrently; each collects at most limit+1
+  // accepted rows (one row of lookahead, so "exactly N results" is
+  // distinguishable from "more than N"), then the global budget is applied
+  // in repo order below so `--limit` semantics stay deterministic.
+  const acceptLimit = Number.isFinite(norm.limit) ? norm.limit + 1 : Number.POSITIVE_INFINITY;
+  const perRepo = await Promise.all(
+    repos.map((repo) => {
+      // In --all-repos mode the parent scan prunes submodule dirs — each
+      // submodule gets its own scoped scan, so descending from the parent
+      // would double-scan and double-report every submodule match. This
+      // pruning is correctness (one repo owns each match), so it applies
+      // even when --no-default-excludes is set.
+      const dedupeDirs = opts.allRepos && repo.name === "parent" ? (context?.submodules ?? []) : [];
+      const extraDirs = [...hostExcludeDirs, ...dedupeDirs];
+      return runGrepInRepo(
+        pattern,
+        paths,
+        opts,
+        norm,
+        repo.cwd,
+        repo.name,
+        acceptLimit,
+        engine,
+        rgBin,
+        extraDirs,
+      );
+    }),
+  );
 
   const allRepoResults: GrepResult["repos"] = [];
   let totalMatches = 0;
   const filesSeen = new Set<string>();
   let truncated = false;
+  let budget = norm.limit;
 
-  for (const repo of repos) {
-    if (truncated) break;
-    const repoLimit = Number.isFinite(limit)
-      ? Math.max(0, limit - totalMatches)
-      : Number.POSITIVE_INFINITY;
-    if (repoLimit === 0) {
-      truncated = true;
-      allRepoResults.push({ name: repo.name, cwd: repo.cwd, matches: [], truncated: true });
-      break;
-    }
-    const matches = await runGrepInRepo(pattern, paths, opts, repo.cwd, repo.name, repoLimit);
-    let repoTruncated = false;
-    if (Number.isFinite(repoLimit) && matches.length >= repoLimit) {
-      repoTruncated = true;
-      truncated = true;
-    }
+  for (let i = 0; i < repos.length; i++) {
+    const repo = repos[i];
+    if (!repo) continue;
+    const collected = perRepo[i] ?? [];
+    collected.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
+    const take = Number.isFinite(budget)
+      ? Math.min(collected.length, Math.max(0, budget))
+      : collected.length;
+    let matches = collected.slice(0, take);
+    // truncated only when an accepted primary row was actually omitted —
+    // the lookahead row (or a later-repo surplus) is the proof.
+    const repoTruncated = collected.length > take;
+    if (repoTruncated) truncated = true;
+    if (Number.isFinite(budget)) budget -= take;
     totalMatches += matches.length;
     for (const m of matches) filesSeen.add(`${repo.name}/${m.file}`);
+    // Context is materialized only for the SELECTED rows, after budgeting,
+    // so context rows never consume the limit and trailing context is never
+    // cut off by an engine kill.
+    if (!opts.files && !opts.filesOnly && !opts.count && (norm.before > 0 || norm.after > 0)) {
+      matches = await materializeContext(matches, repo.cwd, norm.before, norm.after);
+    }
     allRepoResults.push({ name: repo.name, cwd: repo.cwd, matches, truncated: repoTruncated });
   }
 
   return {
     pattern,
-    mode: opts.literal ? "literal" : "regex",
+    mode: opts.files ? "files" : opts.literal ? "literal" : "regex",
+    engine,
+    and_patterns: norm.andPatterns,
+    without_patterns: norm.withoutPatterns,
     repos: allRepoResults,
     total_matches: totalMatches,
     total_files: filesSeen.size,
@@ -220,71 +452,403 @@ async function runGrepInRepo(
   pattern: string,
   paths: string[],
   opts: GrepOpts,
+  norm: NormOpts,
   cwd: string,
   repoName: string,
-  limit: number,
+  acceptLimit: number,
+  engine: GrepEngine,
+  rgBin: string,
+  extraExcludeDirs: readonly string[],
 ): Promise<Match[]> {
-  const args: string[] = ["-rn", "--color=never", "-I"]; // -I: skip binary files
+  // File-level boolean composition: build the complete auxiliary file sets
+  // FIRST (no limit — a partial set can't prove absence), then feed the
+  // primary scan an in-stream predicate. Running the primary with its limit
+  // and filtering afterwards would let non-qualifying early hits consume the
+  // budget and hide later valid results.
+  let predicate: ((file: string) => boolean) | undefined;
+  if (norm.andPatterns.length > 0 || norm.withoutPatterns.length > 0) {
+    const requiredSets: Set<string>[] = [];
+    // Sequential, not parallel: repeated flags must not multiply peak child
+    // process concurrency by repos x patterns. Repo workers stay parallel.
+    for (const p of norm.andPatterns) {
+      const files = await runFileSetScan(
+        p,
+        paths,
+        opts,
+        norm,
+        cwd,
+        engine,
+        rgBin,
+        extraExcludeDirs,
+      );
+      if (files.size === 0) return []; // intersection is already empty
+      requiredSets.push(files);
+    }
+    const forbidden = new Set<string>();
+    for (const p of norm.withoutPatterns) {
+      const files = await runFileSetScan(
+        p,
+        paths,
+        opts,
+        norm,
+        cwd,
+        engine,
+        rgBin,
+        extraExcludeDirs,
+      );
+      for (const f of files) forbidden.add(f);
+    }
+    predicate = (file) => requiredSets.every((s) => s.has(file)) && !forbidden.has(file);
+  }
+
+  const [bin, args, decodeMode] = buildEngineInvocation(
+    pattern,
+    paths,
+    opts,
+    norm,
+    engine,
+    rgBin,
+    extraExcludeDirs,
+    false,
+  );
+
+  let matches = await execSearch(bin, args, cwd, acceptLimit, decodeMode, predicate, false);
+  // -c mode: GNU grep prints a `path:0` row for every searched file; ripgrep
+  // omits zero-count rows. Filter zeros on both engines so output matches.
+  if (opts.count) matches = matches.filter((m) => m.line > 0);
+  return matches.map((m) => ({ ...m, repo: repoName }));
+}
+
+/** Membership scan for one --and/--without pattern: complete files-only set, strict failure. */
+async function runFileSetScan(
+  pattern: string,
+  paths: string[],
+  opts: GrepOpts,
+  norm: NormOpts,
+  cwd: string,
+  engine: GrepEngine,
+  rgBin: string,
+  extraExcludeDirs: readonly string[],
+): Promise<Set<string>> {
+  const [bin, args, decodeMode] = buildEngineInvocation(
+    pattern,
+    paths,
+    opts,
+    norm,
+    engine,
+    rgBin,
+    extraExcludeDirs,
+    true,
+  );
+  const rows = await execSearch(
+    bin,
+    args,
+    cwd,
+    Number.POSITIVE_INFINITY,
+    decodeMode,
+    undefined,
+    true,
+  );
+  return new Set(rows.map((r) => r.file));
+}
+
+type DecodeMode = "content" | "count" | "filesOnly" | "plainLines";
+
+/**
+ * Build one engine invocation. `membership: true` forces files-only mode for
+ * --and/--without set scans (match-shaping + scope flags shared with the
+ * primary; output flags not applied).
+ */
+function buildEngineInvocation(
+  pattern: string,
+  paths: string[],
+  opts: GrepOpts,
+  norm: NormOpts,
+  engine: GrepEngine,
+  rgBin: string,
+  extraExcludeDirs: readonly string[],
+  membership: boolean,
+): [string, string[], DecodeMode] {
+  if (opts.files) {
+    // Filename mode keeps its existing rg/find framing (plain lines).
+    return engine === "rg"
+      ? [rgBin, buildRgFilesArgs(pattern, paths, opts, extraExcludeDirs), "plainLines"]
+      : ["find", buildFindArgs(pattern, paths, opts, extraExcludeDirs), "plainLines"];
+  }
+  const filesOnly = membership || Boolean(opts.filesOnly);
+  const count = !membership && Boolean(opts.count);
+  const decodeMode: DecodeMode = filesOnly ? "filesOnly" : count ? "count" : "content";
+  const args =
+    engine === "rg"
+      ? buildRgArgs(pattern, paths, opts, norm, extraExcludeDirs, { filesOnly, count })
+      : buildGrepArgs(pattern, paths, opts, norm, extraExcludeDirs, { filesOnly, count });
+  return [engine === "rg" ? rgBin : "grep", args, decodeMode];
+}
+
+interface OutputShape {
+  filesOnly: boolean;
+  count: boolean;
+}
+
+function buildGrepArgs(
+  pattern: string,
+  paths: string[],
+  opts: GrepOpts,
+  norm: NormOpts,
+  extraExcludeDirs: readonly string[],
+  shape: OutputShape,
+): string[] {
+  // --null (NOT -Z: BSD grep repurposes -Z for decompression): NUL after the
+  // filename, so paths containing colons/dashes can't confuse the decoder.
+  // -I: skip binary files. Context is never requested from the engine — see
+  // materializeContext.
+  const args: string[] = ["-rn", "-H", "--null", "--color=never", "-I"];
   if (opts.ignoreCase) args.push("-i");
   if (opts.wholeWord) args.push("-w");
   if (opts.literal) args.push("-F");
   else args.push("-E");
-  if (opts.filesOnly) args.push("-l");
-  if (opts.count) args.push("-c");
-  const contextN = Number.parseInt(opts.context ?? "0", 10);
-  if (Number.isFinite(contextN) && contextN > 0) args.push(`-C${contextN}`);
-  if (opts.maxCount) {
-    const n = Number.parseInt(opts.maxCount, 10);
-    if (Number.isFinite(n) && n > 0) args.push(`-m${n}`);
-  }
+  if (shape.filesOnly) args.push("-l");
+  if (shape.count) args.push("-c");
+  if (norm.maxCount !== undefined) args.push(`-m${norm.maxCount}`);
 
   if (!opts.noDefaultExcludes) {
     for (const d of DEFAULT_EXCLUDE_DIRS) args.push(`--exclude-dir=${d}`);
     for (const f of DEFAULT_EXCLUDE_FILES) args.push(`--exclude=${f}`);
   }
+  for (const d of extraExcludeDirs) args.push(`--exclude-dir=${d}`);
   for (const e of opts.exclude ?? []) args.push(`--exclude=${e}`);
 
-  const langGlobs = opts.lang ? LANG_GLOBS[opts.lang] : undefined;
-  if (opts.lang && !langGlobs) {
-    throw new Error(`unknown --lang "${opts.lang}". Valid: ${Object.keys(LANG_GLOBS).join(", ")}`);
-  }
-  if (langGlobs) for (const g of langGlobs) args.push(`--include=${g}`);
+  if (norm.langGlobs) for (const g of norm.langGlobs) args.push(`--include=${g}`);
   for (const g of opts.include ?? []) args.push(`--include=${g}`);
 
   args.push("--", pattern);
   if (paths.length > 0) args.push(...paths);
   else args.push(".");
+  return args;
+}
 
-  const matches = await execGrep(args, cwd, limit);
-  return matches.map((m) => ({ ...m, repo: repoName }));
+function buildRgArgs(
+  pattern: string,
+  paths: string[],
+  opts: GrepOpts,
+  norm: NormOpts,
+  extraExcludeDirs: readonly string[],
+  shape: OutputShape,
+): string[] {
+  // --hidden --no-ignore: match GNU grep's semantics (search dotdirs, ignore
+  // .gitignore) so the only filters are the explicit exclude lists.
+  // --no-config: a user's ripgrep config file must not skew results.
+  // --with-filename: rg drops the file prefix for a single explicit file arg,
+  // which would break the shared decoder.
+  // --null: NUL after the filename (same spelling as GNU/BSD grep's long flag).
+  const args: string[] = [
+    "-n",
+    "--no-heading",
+    "--with-filename",
+    "--null",
+    "--color=never",
+    "--no-config",
+    "--hidden",
+    "--no-ignore",
+  ];
+  if (opts.ignoreCase) args.push("-i");
+  if (opts.wholeWord) args.push("-w");
+  if (opts.literal) args.push("-F");
+  if (shape.filesOnly) args.push("-l");
+  if (shape.count) args.push("-c");
+  if (norm.maxCount !== undefined) args.push(`-m${norm.maxCount}`);
+
+  // Gitignore-style globs: a bare name matches (and prunes) at any depth,
+  // mirroring grep's --exclude-dir / --exclude basename semantics. ORDER
+  // MATTERS: rg globs are last-match-wins, so positives (includes/lang) go
+  // first and negatives (excludes) last — otherwise `--include '*.md'` would
+  // re-include a .md file inside an excluded node_modules/. grep's
+  // --exclude-dir always beats --include, so this keeps the engines aligned.
+  if (norm.langGlobs) for (const g of norm.langGlobs) args.push(`--glob=${g}`);
+  for (const g of opts.include ?? []) args.push(`--glob=${g}`);
+
+  if (!opts.noDefaultExcludes) {
+    for (const d of DEFAULT_EXCLUDE_DIRS) args.push(`--glob=!${d}`);
+    for (const f of DEFAULT_EXCLUDE_FILES) args.push(`--glob=!${f}`);
+  }
+  for (const d of extraExcludeDirs) args.push(`--glob=!${d}`);
+  for (const e of opts.exclude ?? []) args.push(`--glob=!${e}`);
+
+  args.push("--", pattern);
+  if (paths.length > 0) args.push(...paths);
+  else args.push(".");
+  return args;
 }
 
-function execGrep(args: string[], cwd: string, limit: number): Promise<Omit<Match, "repo">[]> {
+/**
+ * Filename mode via ripgrep: `--files` lists files; a single positive glob
+ * acts as a whitelist, negative globs prune. `--iglob` gives -i semantics.
+ */
+function buildRgFilesArgs(
+  pattern: string,
+  paths: string[],
+  opts: GrepOpts,
+  extraExcludeDirs: readonly string[],
+): string[] {
+  const args: string[] = ["--files", "--hidden", "--no-ignore", "--no-config", "--color=never"];
+  // Positive pattern FIRST, negatives last (rg globs are last-match-wins;
+  // excludes must beat the pattern — see the ordering note in buildRgArgs).
+  args.push(`${opts.ignoreCase ? "--iglob" : "--glob"}=${pattern}`);
+  if (!opts.noDefaultExcludes) {
+    for (const d of DEFAULT_EXCLUDE_DIRS) args.push(`--glob=!${d}`);
+    for (const f of DEFAULT_EXCLUDE_FILES) args.push(`--glob=!${f}`);
+  }
+  for (const d of extraExcludeDirs) args.push(`--glob=!${d}`);
+  for (const e of opts.exclude ?? []) args.push(`--glob=!${e}`);
+  if (paths.length > 0) args.push(...paths);
+  else args.push(".");
+  return args;
+}
+
+/**
+ * Filename mode via POSIX find (the no-ripgrep fallback):
+ *   find <paths> ( -name d1 -o -name d2 ... ) -prune -o -type f -name <glob> [! -name <ex>]... -print
+ * Sticks to POSIX operators (`(`, `-o`, `!`) so BSD/macOS find behaves the same.
+ */
+function buildFindArgs(
+  pattern: string,
+  paths: string[],
+  opts: GrepOpts,
+  extraExcludeDirs: readonly string[],
+): string[] {
+  const args: string[] = paths.length > 0 ? [...paths] : ["."];
+  const pruneDirs = [...(opts.noDefaultExcludes ? [] : DEFAULT_EXCLUDE_DIRS), ...extraExcludeDirs];
+  if (pruneDirs.length > 0) {
+    args.push("(");
+    pruneDirs.forEach((d, i) => {
+      if (i > 0) args.push("-o");
+      args.push("-name", d);
+    });
+    args.push(")", "-prune", "-o");
+  }
+  args.push("-type", "f", opts.ignoreCase ? "-iname" : "-name", pattern);
+  const fileExcludes = [
+    ...(opts.noDefaultExcludes ? [] : DEFAULT_EXCLUDE_FILES),
+    ...(opts.exclude ?? []),
+  ];
+  for (const e of fileExcludes) args.push("!", "-name", e);
+  args.push("-print");
+  return args;
+}
+
+/**
+ * Streaming decoder for NUL-framed engine output. Exported for direct
+ * chunk-boundary tests. Record shapes (both engines, pinned by the parity
+ * suite):
+ *   content:    <path>NUL<line>:<text>LF
+ *   count:      <path>NUL<count>LF
+ *   filesOnly:  <path>NUL            (NUL is the record terminator)
+ *   plainLines: <path>LF             (files mode: rg --files / find)
+ *
+ * Operates on Buffers so a chunk boundary can fall anywhere — including
+ * inside a multi-byte UTF-8 sequence — without corrupting a record: bytes
+ * are only decoded to strings once a full record is framed.
+ */
+export class NulDecoder {
+  private buffer: Buffer = Buffer.alloc(0);
+  constructor(private readonly mode: DecodeMode) {}
+
+  push(chunk: Buffer): Omit<Match, "repo" | "kind">[] {
+    this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
+    const rows: Omit<Match, "repo" | "kind">[] = [];
+    if (this.mode === "filesOnly") {
+      let nul = this.buffer.indexOf(0);
+      while (nul >= 0) {
+        const path = this.buffer.subarray(0, nul).toString("utf8");
+        this.buffer = this.buffer.subarray(nul + 1);
+        // Engines may still newline-separate NUL-terminated records in edge
+        // configurations; a bare leading LF is framing residue, not a path.
+        const cleaned = path.startsWith("\n") ? path.slice(1) : path;
+        if (cleaned.length > 0) rows.push({ file: normalizeFile(cleaned), line: 0, text: "" });
+        nul = this.buffer.indexOf(0);
+      }
+      return rows;
+    }
+    let nl = this.buffer.indexOf(0x0a);
+    while (nl >= 0) {
+      const record = this.buffer.subarray(0, nl);
+      this.buffer = this.buffer.subarray(nl + 1);
+      const row = this.decodeRecord(record);
+      if (row) rows.push(row);
+      nl = this.buffer.indexOf(0x0a);
+    }
+    return rows;
+  }
+
+  /** Flush a trailing unterminated record (engine killed mid-write, or no final LF). */
+  flush(): Omit<Match, "repo" | "kind">[] {
+    if (this.buffer.length === 0) return [];
+    const record = this.buffer;
+    this.buffer = Buffer.alloc(0);
+    if (this.mode === "filesOnly") {
+      // A partial filesOnly record has no terminating NUL — an engine killed
+      // mid-path would yield a corrupt name; drop it.
+      return [];
+    }
+    const row = this.decodeRecord(record);
+    return row ? [row] : [];
+  }
+
+  private decodeRecord(record: Buffer): Omit<Match, "repo" | "kind"> | null {
+    if (this.mode === "plainLines") {
+      const path = record.toString("utf8");
+      if (path.length === 0) return null;
+      return { file: normalizeFile(path), line: 0, text: "" };
+    }
+    const nul = record.indexOf(0);
+    if (nul < 0) return null; // not a NUL-framed record (stray engine chatter)
+    const file = normalizeFile(record.subarray(0, nul).toString("utf8"));
+    const rest = record.subarray(nul + 1).toString("utf8");
+    if (this.mode === "count") {
+      const count = Number.parseInt(rest, 10);
+      if (!Number.isFinite(count)) return null;
+      return { file, line: count, text: "" };
+    }
+    // content: <line>:<text>. The engines never emit context/separator rows
+    // (context is materialized from file reads), so `:` is always present.
+    const colon = rest.indexOf(":");
+    if (colon < 0) return null;
+    const lineNum = Number.parseInt(rest.slice(0, colon), 10);
+    if (!Number.isFinite(lineNum)) return null;
+    return { file, line: lineNum, text: rest.slice(colon + 1) };
+  }
+}
+
+function execSearch(
+  bin: string,
+  args: string[],
+  cwd: string,
+  acceptLimit: number,
+  decodeMode: DecodeMode,
+  filePredicate: ((file: string) => boolean) | undefined,
+  strict: boolean,
+): Promise<Match[]> {
   return new Promise((resolveP, reject) => {
-    const proc = spawn("grep", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
-    const matches: Omit<Match, "repo">[] = [];
-    let buffer = "";
+    const proc = spawn(bin, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const decoder = new NulDecoder(decodeMode);
+    const matches: Match[] = [];
     let stderr = "";
-    let truncated = false;
-
-    proc.stdout.setEncoding("utf8");
-    proc.stdout.on("data", (chunk: string) => {
-      if (truncated) return;
-      buffer += chunk;
-      let nl = buffer.indexOf("\n");
-      while (nl >= 0) {
-        const line = buffer.slice(0, nl);
-        buffer = buffer.slice(nl + 1);
-        if (line.length !== 0) {
-          const parsed = parseGrepLine(line);
-          if (parsed) matches.push(parsed);
-          if (Number.isFinite(limit) && matches.length >= limit) {
-            truncated = true;
-            proc.kill("SIGTERM");
-            return;
-          }
-        }
-        nl = buffer.indexOf("\n");
+    let killed = false;
+
+    const accept = (rows: Omit<Match, "repo" | "kind">[]): boolean => {
+      for (const row of rows) {
+        if (filePredicate && !filePredicate(row.file)) continue;
+        matches.push({ ...row, repo: "", kind: "match" });
+        if (Number.isFinite(acceptLimit) && matches.length >= acceptLimit) return true;
+      }
+      return false;
+    };
+
+    proc.stdout.on("data", (chunk: Buffer) => {
+      if (killed) return;
+      if (accept(decoder.push(chunk))) {
+        killed = true;
+        proc.kill("SIGTERM");
       }
     });
     proc.stderr.setEncoding("utf8");
@@ -293,13 +857,15 @@ function execGrep(args: string[], cwd: string, limit: number): Promise<Omit<Matc
     });
     proc.on("error", reject);
     proc.on("close", (code) => {
-      if (buffer.length > 0 && !truncated) {
-        const parsed = parseGrepLine(buffer);
-        if (parsed) matches.push(parsed);
-      }
-      // grep exits 1 on "no matches": normal, not an error.
-      if (code !== null && code !== 0 && code !== 1 && !truncated) {
-        reject(new Error(`grep exited ${code}: ${stderr.trim() || "(no stderr)"}`));
+      if (!killed) accept(decoder.flush());
+      // Exit 1 is "no matches" on both engines: normal, not an error.
+      // Primary scans tolerate exit 2 with matches collected (an unreadable
+      // file mid-walk): surface the results rather than throwing them away.
+      // STRICT scans (--and/--without membership) must reject on ANY partial
+      // failure — an incomplete set cannot prove that a file lacks a pattern.
+      const failed = code !== null && code !== 0 && code !== 1 && !killed;
+      if (failed && (strict || matches.length === 0)) {
+        reject(new Error(`${bin} exited ${code}: ${stderr.trim() || "(no stderr)"}`));
         return;
       }
       resolveP(matches);
@@ -307,32 +873,81 @@ function execGrep(args: string[], cwd: string, limit: number): Promise<Omit<Matc
   });
 }
 
-/** Parse `path:line:content` from grep -n output. Returns null for ambiguous (no line number) lines. */
-function parseGrepLine(line: string): Omit<Match, "repo"> | null {
-  // First colon ends path; second colon ends line number (if numeric).
-  const firstColon = line.indexOf(":");
-  if (firstColon < 0) {
-    // -l mode: just a path. Encode as line=0, text="".
-    return { file: line, line: 0, text: "" };
-  }
-  const after = line.slice(firstColon + 1);
-  const secondColon = after.indexOf(":");
-  if (secondColon < 0) {
-    // -c mode: `path:count`.
-    const count = Number.parseInt(after, 10);
-    if (Number.isFinite(count)) return { file: line.slice(0, firstColon), line: count, text: "" };
-    return { file: line.slice(0, firstColon), line: 0, text: after };
+/**
+ * Materialize -C/-A/-B context for already-selected match rows: one file
+ * read per selected file, intervals clamped + merged, match rows keep the
+ * engine-captured text, other window lines become kind:"context" rows.
+ * An unreadable file (deleted since the scan — the accepted TOCTOU window)
+ * degrades to its match rows without context rather than failing the search.
+ */
+async function materializeContext(
+  selected: Match[],
+  cwd: string,
+  before: number,
+  after: number,
+): Promise<Match[]> {
+  const byFile = new Map<string, Match[]>();
+  for (const m of selected) {
+    const rows = byFile.get(m.file);
+    if (rows) rows.push(m);
+    else byFile.set(m.file, [m]);
   }
-  const lineNum = Number.parseInt(after.slice(0, secondColon), 10);
-  if (!Number.isFinite(lineNum)) {
-    // Probably a context separator like `--`. Skip.
-    return null;
+
+  const out: Match[] = [];
+  for (const [file, rows] of byFile) {
+    const abs = isAbsolute(file) ? file : join(cwd, file);
+    let lines: string[] | null = null;
+    try {
+      const content = await readFile(abs, "utf8");
+      lines = content.split("\n");
+      if (lines.at(-1) === "") lines.pop();
+    } catch {
+      lines = null;
+    }
+    if (lines === null) {
+      out.push(...rows);
+      continue;
+    }
+    // Merge overlapping/adjacent [line-before, line+after] windows.
+    const intervals: [number, number][] = rows
+      .map((m): [number, number] => [
+        Math.max(1, m.line - before),
+        Math.min(lines.length, m.line + after),
+      ])
+      .sort((a, b) => a[0] - b[0]);
+    const merged: [number, number][] = [];
+    for (const iv of intervals) {
+      const last = merged.at(-1);
+      if (last && iv[0] <= last[1] + 1) last[1] = Math.max(last[1], iv[1]);
+      else merged.push([iv[0], iv[1]]);
+    }
+    const matchByLine = new Map(rows.map((m) => [m.line, m]));
+    const emitted = new Set<Match>();
+    for (const [start, end] of merged) {
+      if (start > end) continue;
+      for (let n = start; n <= end; n++) {
+        const m = matchByLine.get(n);
+        if (m) {
+          out.push(m);
+          emitted.add(m);
+        } else {
+          const repo = rows[0]?.repo ?? "";
+          out.push({ repo, file, line: n, text: lines[n - 1] ?? "", kind: "context" });
+        }
+      }
+    }
+    // A match whose line exceeds the file's current length (file shrank
+    // since the scan) sits outside every clamped window — still emit it.
+    for (const m of rows) {
+      if (!emitted.has(m)) out.push(m);
+    }
   }
-  return {
-    file: line.slice(0, firstColon),
-    line: lineNum,
-    text: after.slice(secondColon + 1),
-  };
+  return out;
+}
+
+/** Both engines may emit a leading `./` for the default path; strip it so output is engine-identical. */
+function normalizeFile(file: string): string {
+  return file.startsWith("./") ? file.slice(2) : file;
 }
 
 function renderResult(r: GrepResult, opts: GrepOpts): string {
@@ -340,32 +955,41 @@ function renderResult(r: GrepResult, opts: GrepOpts): string {
   const showRepoHeader = r.repos.length > 1;
   for (const repo of r.repos) {
     if (repo.matches.length === 0) continue;
+    const primary = repo.matches.filter((m) => m.kind === "match").length;
     if (showRepoHeader) {
       lines.push("");
-      lines.push(
-        `── ${repo.name} (${repo.matches.length} match${repo.matches.length === 1 ? "" : "es"}) ──`,
-      );
+      lines.push(`── ${repo.name} (${primary} match${primary === 1 ? "" : "es"}) ──`);
     }
+    // Context mode: `--` between disjoint windows (file change or line gap).
+    const contextMode = repo.matches.some((x) => x.kind === "context");
+    let prev: Match | undefined;
     for (const m of repo.matches) {
-      if (opts.filesOnly) {
+      if (contextMode && prev && (prev.file !== m.file || m.line !== prev.line + 1)) {
+        lines.push("--");
+      }
+      if (opts.filesOnly || opts.files) {
         lines.push(m.file);
       } else if (opts.count) {
         lines.push(`${m.file}:${m.line}`);
+      } else if (m.kind === "context") {
+        lines.push(`${m.file}-${m.line}-${m.text}`);
       } else {
         lines.push(`${m.file}:${m.line}:${m.text}`);
       }
+      prev = m;
     }
     if (repo.truncated) {
-      lines.push("  (truncated; pass --limit to widen)");
+      lines.push("  (truncated; raise --limit)");
     }
   }
   if (r.total_matches === 0) {
-    lines.push(`(no matches for /${r.pattern}/${r.mode === "literal" ? " (literal)" : ""})`);
+    const modeTag = r.mode === "literal" ? " (literal)" : r.mode === "files" ? " (files)" : "";
+    lines.push(`(no matches for /${r.pattern}/${modeTag})`);
   } else if (r.repos.length > 1 || r.truncated) {
     lines.push("");
     const summary = `${r.total_matches} match${r.total_matches === 1 ? "" : "es"} across ${r.total_files} file${r.total_files === 1 ? "" : "s"}`;
-    const tail = r.truncated ? " (truncated; use --limit)" : "";
-    lines.push(`${summary}${tail}  (${r.elapsed_ms}ms)`);
+    const tail = r.truncated ? " (truncated; raise --limit)" : "";
+    lines.push(`${summary}${tail}  (${r.elapsed_ms}ms, ${r.engine})`);
   }
   return lines.join("\n");
 }