harnery 0.7.1 → 0.9.0

package/dist/commands/grep.js

@@ -1,12 +1,37 @@
 import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { resolveSearchEngine } from "../lib/tools/ripgrep.js";
 /**
- * `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 = [
     ".git",
@@ -47,19 +72,28 @@ const LANG_GLOBS = {
 export function registerGrepCommand(program, emit, context) {
     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.")
+        .description("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, [])
         .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, [])
+        .option("--without <pattern>", "Drop files that contain this pattern (file-level, repeatable)", collect, [])
+        .option("-q, --quiet", "No output; exit 0 if any match exists, 1 if none")
         .option("--include <glob>", "Extra --include glob (repeatable)", collect, [])
         .option("--exclude <glob>", "Extra --exclude glob (repeatable)", collect, [])
         .option("--no-default-excludes", "Disable the default skip list (node_modules, dist, etc.)")
@@ -67,6 +101,12 @@ export function registerGrepCommand(program, emit, context) {
         .action(async (pattern, paths, opts) => {
         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);
@@ -83,41 +123,177 @@ export function registerGrepCommand(program, emit, context) {
 function collect(value, prev) {
     return [...prev, value];
 }
-async function runGrep(pattern, paths, opts, context) {
+/**
+ * Parse a strictly-decimal integer option. Rejects empty, negative, signed,
+ * fractional, and trailing-junk values before any engine is spawned.
+ */
+function parseIntOpt(flag, raw, min) {
+    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) {
+    const rawValues = typeof lang === "string" ? [lang] : (lang ?? []);
+    const keys = [];
+    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 = [];
+    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) {
+    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 = [
+            [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 = [
+            [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 = [
+            [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, paths, opts, context) {
     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 = [];
     let totalMatches = 0;
     const filesSeen = new Set();
     let truncated = false;
-    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;
+    let budget = norm.limit;
+    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,
@@ -155,8 +331,71 @@ function resolveRepos(opts, context) {
     }
     return [{ name: "cwd", cwd: process.cwd() }];
 }
-async function runGrepInRepo(pattern, paths, opts, cwd, repoName, limit) {
-    const args = ["-rn", "--color=never", "-I"]; // -I: skip binary files
+async function runGrepInRepo(pattern, paths, opts, norm, cwd, repoName, acceptLimit, engine, rgBin, extraExcludeDirs) {
+    // 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;
+    if (norm.andPatterns.length > 0 || norm.withoutPatterns.length > 0) {
+        const requiredSets = [];
+        // 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();
+        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, paths, opts, norm, cwd, engine, rgBin, extraExcludeDirs) {
+    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));
+}
+/**
+ * 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, paths, opts, norm, engine, rgBin, extraExcludeDirs, membership) {
+    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 = 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];
+}
+function buildGrepArgs(pattern, paths, opts, norm, extraExcludeDirs, shape) {
+    // --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 = ["-rn", "-H", "--null", "--color=never", "-I"];
     if (opts.ignoreCase)
         args.push("-i");
     if (opts.wholeWord)
@@ -165,32 +404,24 @@ async function runGrepInRepo(pattern, paths, opts, cwd, repoName, limit) {
         args.push("-F");
     else
         args.push("-E");
-    if (opts.filesOnly)
+    if (shape.filesOnly)
         args.push("-l");
-    if (opts.count)
+    if (shape.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 (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)
+    if (norm.langGlobs)
+        for (const g of norm.langGlobs)
             args.push(`--include=${g}`);
     for (const g of opts.include ?? [])
         args.push(`--include=${g}`);
@@ -199,36 +430,230 @@ async function runGrepInRepo(pattern, paths, opts, cwd, repoName, limit) {
         args.push(...paths);
     else
         args.push(".");
-    const matches = await execGrep(args, cwd, limit);
-    return matches.map((m) => ({ ...m, repo: repoName }));
+    return args;
+}
+function buildRgArgs(pattern, paths, opts, norm, extraExcludeDirs, shape) {
+    // --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 = [
+        "-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;
+}
+/**
+ * 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, paths, opts, extraExcludeDirs) {
+    const args = ["--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, paths, opts, extraExcludeDirs) {
+    const args = 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;
 }
-function execGrep(args, cwd, limit) {
+/**
+ * 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 {
+    mode;
+    buffer = Buffer.alloc(0);
+    constructor(mode) {
+        this.mode = mode;
+    }
+    push(chunk) {
+        this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
+        const rows = [];
+        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() {
+        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] : [];
+    }
+    decodeRecord(record) {
+        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, args, cwd, acceptLimit, decodeMode, filePredicate, strict) {
     return new Promise((resolveP, reject) => {
-        const proc = spawn("grep", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const proc = spawn(bin, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const decoder = new NulDecoder(decodeMode);
         const matches = [];
-        let buffer = "";
         let stderr = "";
-        let truncated = false;
-        proc.stdout.setEncoding("utf8");
+        let killed = false;
+        const accept = (rows) => {
+            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) => {
-            if (truncated)
+            if (killed)
                 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");
+            if (accept(decoder.push(chunk))) {
+                killed = true;
+                proc.kill("SIGTERM");
             }
         });
         proc.stderr.setEncoding("utf8");
@@ -237,47 +662,99 @@ function execGrep(args, cwd, limit) {
         });
         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);
         });
     });
 }
-/** Parse `path:line:content` from grep -n output. Returns null for ambiguous (no line number) lines. */
-function parseGrepLine(line) {
-    // 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, cwd, before, after) {
+    const byFile = new Map();
+    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 = [];
+    for (const [file, rows] of byFile) {
+        const abs = isAbsolute(file) ? file : join(cwd, file);
+        let lines = 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 = rows
+            .map((m) => [
+            Math.max(1, m.line - before),
+            Math.min(lines.length, m.line + after),
+        ])
+            .sort((a, b) => a[0] - b[0]);
+        const merged = [];
+        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();
+        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) {
+    return file.startsWith("./") ? file.slice(2) : file;
 }
 function renderResult(r, opts) {
     const lines = [];
@@ -285,33 +762,45 @@ function renderResult(r, opts) {
     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;
         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");
 }