harnery 0.8.0 → 0.10.0

package/dist/commands/grep.js

@@ -1,26 +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. Prefers ripgrep (`rg`) when it is on
- * PATH and falls back to GNU `grep -rn` 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).
+ * 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`), and language presets.
+ * scoping (`--repo <name>` or `--all-repos`), language presets, file-level
+ * boolean composition (`--and` / `--without`), and context (`-C`/`-A`/`-B`).
  *
  * 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 (previously the
- * parent scan descended into submodules, double-scanning and double-reporting
- * every submodule match).
+ * 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, `{rows, total, truncated}`
- * in --json mode. Matches are sorted (file, then line) for stable output
- * across runs and engines; with `-C <n>` context, engine order is kept so
- * context groups stay adjacent.
+ * 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",
@@ -63,10 +74,11 @@ export function registerGrepCommand(program, emit, context) {
         .command("grep <pattern> [paths...]")
         .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. Regex by default; -F for literal.")
+        "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)")
@@ -75,8 +87,13 @@ export function registerGrepCommand(program, emit, context) {
         "(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.)")
@@ -84,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);
@@ -100,39 +123,128 @@ export function registerGrepCommand(program, emit, context) {
 function collect(value, prev) {
     return [...prev, value];
 }
-/** 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");
+/**
+ * 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 = [
-            [opts.lang, "--lang"],
+            [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"],
-            [Number.parseInt(opts.context ?? "0", 10) > 0 ? true : undefined, "-C/--context"],
+            [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;
-    const contextN = Number.parseInt(opts.context ?? "0", 10);
-    const sortable = !(Number.isFinite(contextN) && contextN > 0);
     // 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 is capped at the global limit
-    // (a single repo can never contribute more), then the global budget is
-    // applied in repo order below so `--limit` semantics stay deterministic.
+    // 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
@@ -141,27 +253,26 @@ export async function runGrep(pattern, paths, opts, context) {
         // 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, repo.cwd, repo.name, limit, engine, rgBin, extraDirs);
+        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;
-    let budget = limit;
+    let budget = norm.limit;
     for (let i = 0; i < repos.length; i++) {
         const repo = repos[i];
         if (!repo)
             continue;
         const collected = perRepo[i] ?? [];
-        if (sortable) {
-            collected.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
-        }
-        const engineCapped = Number.isFinite(limit) && collected.length >= limit;
+        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;
-        const matches = collected.slice(0, take);
-        const repoTruncated = engineCapped || collected.length > take;
+        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))
@@ -169,12 +280,20 @@ export async function runGrep(pattern, paths, opts, context) {
         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.files ? "files" : opts.literal ? "literal" : "regex",
         engine,
+        and_patterns: norm.andPatterns,
+        without_patterns: norm.withoutPatterns,
         repos: allRepoResults,
         total_matches: totalMatches,
         total_files: filesSeen.size,
@@ -212,32 +331,71 @@ function resolveRepos(opts, context) {
     }
     return [{ name: "cwd", cwd: process.cwd() }];
 }
-async function runGrepInRepo(pattern, paths, opts, cwd, repoName, limit, engine, rgBin, extraExcludeDirs) {
-    // Filename mode: `rg --files` when available; POSIX `find` otherwise (GNU
-    // grep has no list-by-name mode). Content mode: rg / grep as selected.
-    const [bin, args] = opts.files
-        ? engine === "rg"
-            ? [rgBin, buildRgFilesArgs(pattern, paths, opts, extraExcludeDirs)]
-            : ["find", buildFindArgs(pattern, paths, opts, extraExcludeDirs)]
-        : engine === "rg"
-            ? [rgBin, buildRgArgs(pattern, paths, opts, extraExcludeDirs)]
-            : ["grep", buildGrepArgs(pattern, paths, opts, extraExcludeDirs)];
-    let matches = await execSearch(bin, args, cwd, limit);
+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 }));
 }
-function resolveLangGlobs(opts) {
-    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(", ")}`);
+/** 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"];
     }
-    return langGlobs;
+    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, extraExcludeDirs) {
-    const args = ["-rn", "-H", "--color=never", "-I"]; // -I: skip binary files
+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)
@@ -246,18 +404,12 @@ function buildGrepArgs(pattern, paths, opts, extraExcludeDirs) {
         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}`);
@@ -268,9 +420,8 @@ function buildGrepArgs(pattern, paths, opts, extraExcludeDirs) {
         args.push(`--exclude-dir=${d}`);
     for (const e of opts.exclude ?? [])
         args.push(`--exclude=${e}`);
-    const langGlobs = resolveLangGlobs(opts);
-    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}`);
@@ -281,16 +432,18 @@ function buildGrepArgs(pattern, paths, opts, extraExcludeDirs) {
         args.push(".");
     return args;
 }
-function buildRgArgs(pattern, paths, opts, extraExcludeDirs) {
+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 parser.
+    // 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",
@@ -302,27 +455,20 @@ function buildRgArgs(pattern, paths, opts, extraExcludeDirs) {
         args.push("-w");
     if (opts.literal)
         args.push("-F");
-    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}`);
     // 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.
-    const langGlobs = resolveLangGlobs(opts);
-    if (langGlobs)
-        for (const g of langGlobs)
+    if (norm.langGlobs)
+        for (const g of norm.langGlobs)
             args.push(`--glob=${g}`);
     for (const g of opts.include ?? [])
         args.push(`--glob=${g}`);
@@ -395,33 +541,119 @@ function buildFindArgs(pattern, paths, opts, extraExcludeDirs) {
     args.push("-print");
     return args;
 }
-function execSearch(bin, 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(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");
@@ -430,15 +662,15 @@ function execSearch(bin, 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);
-            }
-            // Exit 1 is "no matches" on both engines: normal, not an error. Exit 2
-            // with matches collected means a partial failure (an unreadable file
-            // mid-walk); surface the results rather than throwing them away.
-            if (code !== null && code !== 0 && code !== 1 && !truncated && matches.length === 0) {
+            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;
             }
@@ -446,34 +678,79 @@ function execSearch(bin, args, cwd, limit) {
         });
     });
 }
-/** Parse `path:line:content` from grep/rg -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: normalizeFile(line), line: 0, text: "" };
+/**
+ * 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 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: normalizeFile(line.slice(0, firstColon)), line: count, text: "" };
+    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: normalizeFile(line.slice(0, firstColon)), line: 0, text: after };
-    }
-    const lineNum = Number.parseInt(after.slice(0, secondColon), 10);
-    if (!Number.isFinite(lineNum)) {
-        // Probably a context separator like `--`. Skip.
-        return null;
     }
-    return {
-        file: normalizeFile(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) {
@@ -485,23 +762,34 @@ 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 (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) {
@@ -511,7 +799,7 @@ function renderResult(r, opts) {
     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)" : "";
+        const tail = r.truncated ? " (truncated; raise --limit)" : "";
         lines.push(`${summary}${tail}  (${r.elapsed_ms}ms, ${r.engine})`);
     }
     return lines.join("\n");