@aria-cli/tools 1.0.1 → 1.0.3

package/src/executors/frg-freshness.ts

@@ -0,0 +1,743 @@
+import * as fsSync from "node:fs";
+import * as fs from "node:fs/promises";
+import * as nodePath from "node:path";
+import { execFileSync } from "node:child_process";
+import { frg, type FrgSearchMatch } from "@aria-cli/fastripgrep";
+
+export type FrgMutationOperation = "write" | "delete";
+
+export interface FrgMutationRecord {
+  repoRoot: string;
+  path: string;
+  operation: FrgMutationOperation;
+  sequence: number;
+  recordedAt: number;
+  content?: string;
+}
+
+export interface FrgSessionDeltaSearchOptions {
+  pattern: string;
+  context?: number;
+  caseInsensitive?: boolean;
+  smartCase?: boolean;
+  literal?: boolean;
+  glob?: string;
+  fileType?: string;
+  filesOnly?: boolean;
+  count?: boolean;
+  quiet?: boolean;
+  maxCount?: number;
+}
+
+export interface FrgSessionDeltaSearchResult {
+  mode: "matches" | "files" | "counts" | "quiet";
+  matches?: FrgSearchMatch[];
+  files?: string[];
+  counts?: Array<{ file: string; count: number }>;
+  matched?: boolean;
+}
+
+export interface FrgGitDirtyStatus {
+  headCommit?: string;
+  headTree?: string;
+  tracked: Array<{ path: string; operation: FrgMutationOperation }>;
+  untracked: string[];
+}
+
+export interface FrgFlushStatus {
+  inFlight: boolean;
+  scheduled: boolean;
+  lastScheduledAt?: number;
+  lastFlushAt?: number;
+  lastError?: string;
+  retryCount: number;
+  retryDelayMs?: number;
+}
+
+export interface FrgFreshnessSnapshot {
+  headCommit?: string;
+  headTree?: string;
+  dirtyTrackedCount: number;
+  dirtyUntrackedCount: number;
+  sessionPendingCount: number;
+  sessionPendingBytes: number;
+  flush: FrgFlushStatus;
+  freshnessState:
+    | "missing"
+    | "fresh"
+    | "session-dirty"
+    | "overlay-dirty"
+    | "head-mismatch"
+    | "syncing"
+    | "sync-scheduled"
+    | "stale";
+}
+
+interface RepoState {
+  loaded: boolean;
+  sequence: number;
+  pending: Map<string, FrgMutationRecord>;
+}
+
+interface FlushState {
+  timer: NodeJS.Timeout | null;
+  inFlight: boolean;
+  lastScheduledAt?: number;
+  lastFlushAt?: number;
+  lastError?: string;
+  retryDelayMs?: number;
+  retryCount: number;
+}
+
+const repoStates = new Map<string, RepoState>();
+const flushStates = new Map<string, FlushState>();
+
+export const DEFAULT_BACKGROUND_FRG_FLUSH_DELAY_MS = 750;
+export const BACKGROUND_FRG_MAX_FLUSH_DELAY_MS = 30_000;
+export const MAX_PENDING_MUTATIONS_BEFORE_SYNC_FLUSH = 32;
+export const MAX_PENDING_MUTATION_BYTES_BEFORE_SYNC_FLUSH = 512 * 1024;
+export const MAX_CACHED_MUTATION_CONTENT_BYTES = 256 * 1024;
+
+function normalizePath(p: string): string {
+  return nodePath.resolve(p);
+}
+
+function walDir(repoRoot: string): string {
+  return nodePath.join(normalizePath(repoRoot), ".frg", "session");
+}
+
+function walPath(repoRoot: string): string {
+  return nodePath.join(walDir(repoRoot), "aria-pending.jsonl");
+}
+
+function ensureSessionStorageDir(repoRoot: string): void {
+  fsSync.mkdirSync(walDir(repoRoot), { recursive: true });
+}
+
+function normalizeStoredContent(content?: string): string | undefined {
+  if (typeof content !== "string") {
+    return undefined;
+  }
+  return Buffer.byteLength(content, "utf8") <= MAX_CACHED_MUTATION_CONTENT_BYTES
+    ? content
+    : undefined;
+}
+
+function getRepoState(repoRoot: string): RepoState {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const existing = repoStates.get(normalizedRepoRoot);
+  if (existing) {
+    ensureRepoStateLoaded(normalizedRepoRoot, existing);
+    return existing;
+  }
+  const created: RepoState = { loaded: false, sequence: 0, pending: new Map() };
+  repoStates.set(normalizedRepoRoot, created);
+  ensureRepoStateLoaded(normalizedRepoRoot, created);
+  return created;
+}
+
+function getFlushState(repoRoot: string): FlushState {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const existing = flushStates.get(normalizedRepoRoot);
+  if (existing) return existing;
+  const created: FlushState = { timer: null, inFlight: false, retryCount: 0 };
+  flushStates.set(normalizedRepoRoot, created);
+  return created;
+}
+
+function ensureRepoStateLoaded(repoRoot: string, state?: RepoState): void {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const currentState = state ?? repoStates.get(normalizedRepoRoot);
+  if (!currentState || currentState.loaded) {
+    return;
+  }
+
+  const pendingWalPath = walPath(normalizedRepoRoot);
+  if (fsSync.existsSync(pendingWalPath)) {
+    try {
+      const lines = fsSync.readFileSync(pendingWalPath, "utf8").split(/\r?\n/).filter(Boolean);
+      for (const line of lines) {
+        const parsed = JSON.parse(line) as FrgMutationRecord;
+        const normalizedPath = normalizePath(parsed.path);
+        currentState.pending.set(normalizedPath, {
+          ...parsed,
+          repoRoot: normalizedRepoRoot,
+          path: normalizedPath,
+          content: normalizeStoredContent(parsed.content),
+        });
+        currentState.sequence = Math.max(currentState.sequence, parsed.sequence ?? 0);
+      }
+    } catch {
+      // Ignore malformed WAL and proceed with empty/in-memory state.
+    }
+  }
+
+  currentState.loaded = true;
+}
+
+function rewriteWal(repoRoot: string): void {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const state = repoStates.get(normalizedRepoRoot);
+  if (!state || state.pending.size === 0) {
+    try {
+      fsSync.rmSync(walPath(normalizedRepoRoot), { force: true });
+    } catch {
+      // ignore
+    }
+    return;
+  }
+
+  ensureSessionStorageDir(normalizedRepoRoot);
+  const records = [...state.pending.values()].sort((a, b) => a.sequence - b.sequence);
+  const content = records.map((record) => JSON.stringify(record)).join("\n") + "\n";
+  fsSync.writeFileSync(walPath(normalizedRepoRoot), content, "utf8");
+}
+
+function appendWalRecord(repoRoot: string, record: FrgMutationRecord): void {
+  ensureSessionStorageDir(repoRoot);
+  fsSync.appendFileSync(walPath(repoRoot), `${JSON.stringify(record)}\n`, "utf8");
+}
+
+function findGitRepoRoot(startPath: string): string | null {
+  let current = normalizePath(startPath);
+  try {
+    const stat = fsSync.statSync(current);
+    if (!stat.isDirectory()) {
+      current = nodePath.dirname(current);
+    }
+  } catch {
+    current = nodePath.dirname(current);
+  }
+
+  while (true) {
+    if (fsSync.existsSync(nodePath.join(current, ".git"))) {
+      return current;
+    }
+    const parent = nodePath.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+function escapeRegex(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function compilePattern(options: FrgSessionDeltaSearchOptions): RegExp {
+  let pattern = options.literal ? escapeRegex(options.pattern) : options.pattern;
+  const smartCaseInsensitive = options.smartCase && !/[A-Z]/.test(options.pattern);
+  const flags = `${options.caseInsensitive || smartCaseInsensitive ? "i" : ""}g`;
+  return new RegExp(pattern, flags);
+}
+
+function globToRegExp(glob: string): RegExp {
+  const escaped = glob
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "::DOUBLE_STAR::")
+    .replace(/\*/g, "[^/]*")
+    .replace(/::DOUBLE_STAR::/g, ".*")
+    .replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`);
+}
+
+function pathMatchesFilters(relativePath: string, options: FrgSessionDeltaSearchOptions): boolean {
+  if (options.fileType) {
+    const ext = options.fileType.startsWith(".") ? options.fileType : `.${options.fileType}`;
+    if (!relativePath.endsWith(ext)) {
+      return false;
+    }
+  }
+  if (options.glob) {
+    const re = globToRegExp(options.glob);
+    if (!re.test(relativePath)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function buildContextLines(
+  lines: string[],
+  lineIndex: number,
+  radius: number,
+): {
+  before: Array<{ line: number; content: string }>;
+  after: Array<{ line: number; content: string }>;
+} {
+  const before: Array<{ line: number; content: string }> = [];
+  const after: Array<{ line: number; content: string }> = [];
+  for (let i = Math.max(0, lineIndex - radius); i < lineIndex; i++) {
+    before.push({ line: i + 1, content: lines[i] ?? "" });
+  }
+  for (let i = lineIndex + 1; i <= Math.min(lines.length - 1, lineIndex + radius); i++) {
+    after.push({ line: i + 1, content: lines[i] ?? "" });
+  }
+  return { before, after };
+}
+
+function relativeToRepo(repoRoot: string, filePath: string): string {
+  return nodePath.relative(repoRoot, filePath).split(nodePath.sep).join("/");
+}
+
+function isBinaryBuffer(content: Buffer): boolean {
+  const checkLength = Math.min(content.length, 8192);
+  for (let i = 0; i < checkLength; i++) {
+    if (content[i] === 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function setMutationRecordForRepo(
+  repoRoot: string,
+  filePath: string,
+  operation: FrgMutationOperation,
+  content?: string,
+  options?: { persistWal?: boolean; scheduleFlush?: boolean },
+): void {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const state = getRepoState(normalizedRepoRoot);
+  state.sequence += 1;
+  const normalizedPath = normalizePath(filePath);
+  const record: FrgMutationRecord = {
+    repoRoot: normalizedRepoRoot,
+    path: normalizedPath,
+    operation,
+    sequence: state.sequence,
+    recordedAt: Date.now(),
+    content: normalizeStoredContent(content),
+  };
+  state.pending.set(normalizedPath, record);
+
+  if (options?.persistWal !== false) {
+    appendWalRecord(normalizedRepoRoot, record);
+  }
+  if (options?.scheduleFlush !== false) {
+    scheduleBackgroundFrgFlush(normalizedRepoRoot);
+  }
+}
+
+function runGit(repoRoot: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, {
+      cwd: normalizePath(repoRoot),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function getTrackedRepoRootForPath(filePath: string): string | null {
+  return findGitRepoRoot(filePath);
+}
+
+export function ensureFrgRepoStateLoaded(repoRoot: string): void {
+  void getRepoState(repoRoot);
+}
+
+export function recordFrgMutation(
+  filePath: string,
+  operation: FrgMutationOperation,
+  content?: string,
+): void {
+  const repoRoot = getTrackedRepoRootForPath(filePath);
+  if (!repoRoot) return;
+  setMutationRecordForRepo(repoRoot, filePath, operation, content);
+}
+
+export function getPendingFrgMutations(repoRoot: string): FrgMutationRecord[] {
+  const state = getRepoState(repoRoot);
+  return [...state.pending.values()].sort((a, b) => a.sequence - b.sequence);
+}
+
+export function getPendingFrgMutationBytes(repoRoot: string): number {
+  return getPendingFrgMutations(repoRoot).reduce((total, record) => {
+    if (typeof record.content === "string") {
+      return total + Buffer.byteLength(record.content, "utf8");
+    }
+    try {
+      return total + fsSync.statSync(record.path).size;
+    } catch {
+      return total;
+    }
+  }, 0);
+}
+
+export function clearPendingFrgMutations(repoRoot: string): void {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  repoStates.delete(normalizedRepoRoot);
+  try {
+    fsSync.rmSync(walPath(normalizedRepoRoot), { force: true });
+  } catch {
+    // ignore
+  }
+  const flushState = flushStates.get(normalizedRepoRoot);
+  if (flushState?.timer) {
+    clearTimeout(flushState.timer);
+  }
+  flushStates.delete(normalizedRepoRoot);
+}
+
+export function flushPendingFrgMutations(
+  repoRoot: string,
+):
+  | { flushed: false; reason: string; pendingCount: number }
+  | { flushed: true; pendingCount: number; result: unknown } {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const state = getRepoState(normalizedRepoRoot);
+  const flushState = getFlushState(normalizedRepoRoot);
+  const pendingCount = state.pending.size;
+  if (pendingCount === 0) {
+    return { flushed: false, reason: "no-pending-mutations", pendingCount };
+  }
+  if (flushState.timer) {
+    clearTimeout(flushState.timer);
+    flushState.timer = null;
+  }
+  if (flushState.inFlight) {
+    return { flushed: false, reason: "flush-in-flight", pendingCount };
+  }
+
+  flushState.inFlight = true;
+  try {
+    maybeBuildFrgIndexForRepo(normalizedRepoRoot);
+    // Targeted update: pass only changed/deleted files instead of full directory walk.
+    // O(changed_files) instead of O(all_files).
+    const pending = [...state.pending.values()];
+    const targetChanged = pending.filter((r) => r.operation === "write").map((r) => r.path);
+    const targetDeleted = pending.filter((r) => r.operation === "delete").map((r) => r.path);
+    const result =
+      targetChanged.length > 0 || targetDeleted.length > 0
+        ? frg({ command: "update", path: normalizedRepoRoot, targetChanged, targetDeleted })
+        : frg({ command: "update", path: normalizedRepoRoot });
+    state.pending.clear();
+    rewriteWal(normalizedRepoRoot);
+    flushState.lastFlushAt = Date.now();
+    flushState.lastError = undefined;
+    flushState.retryCount = 0;
+    flushState.retryDelayMs = undefined;
+    return { flushed: true, pendingCount, result };
+  } catch (error) {
+    flushState.lastError = error instanceof Error ? error.message : String(error);
+    flushState.retryCount += 1;
+    flushState.retryDelayMs = Math.min(
+      (flushState.retryDelayMs ?? DEFAULT_BACKGROUND_FRG_FLUSH_DELAY_MS) * 2,
+      BACKGROUND_FRG_MAX_FLUSH_DELAY_MS,
+    );
+    return { flushed: false, reason: "flush-failed", pendingCount };
+  } finally {
+    flushState.inFlight = false;
+  }
+}
+
+export function maybeBuildFrgIndexForRepo(repoRoot: string): void {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const frgDir = nodePath.join(normalizedRepoRoot, ".frg");
+  if (fsSync.existsSync(frgDir)) return;
+  try {
+    frg({ command: "init", path: normalizedRepoRoot });
+  } catch {
+    // best effort; search may still fall back to noIndex if init fails
+  }
+}
+
+export function scheduleBackgroundFrgFlush(
+  repoRoot: string,
+  delayMs: number = DEFAULT_BACKGROUND_FRG_FLUSH_DELAY_MS,
+): void {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const state = getRepoState(normalizedRepoRoot);
+  if (state.pending.size === 0) {
+    return;
+  }
+
+  const flushState = getFlushState(normalizedRepoRoot);
+  flushState.lastScheduledAt = Date.now();
+
+  if (flushState.inFlight) {
+    return;
+  }
+
+  if (flushState.timer) {
+    clearTimeout(flushState.timer);
+  }
+
+  const effectiveDelay = flushState.retryDelayMs ?? delayMs;
+  flushState.timer = setTimeout(() => {
+    flushState.timer = null;
+    const result = flushPendingFrgMutations(normalizedRepoRoot);
+    if (!result.flushed && result.reason === "flush-failed" && result.pendingCount > 0) {
+      scheduleBackgroundFrgFlush(normalizedRepoRoot, flushState.retryDelayMs ?? delayMs);
+    }
+  }, effectiveDelay);
+
+  if (typeof flushState.timer.unref === "function") {
+    flushState.timer.unref();
+  }
+}
+
+export function shouldForceSynchronousFrgFlush(repoRoot: string): boolean {
+  const pendingCount = getPendingFrgMutations(repoRoot).length;
+  const pendingBytes = getPendingFrgMutationBytes(repoRoot);
+  return (
+    pendingCount >= MAX_PENDING_MUTATIONS_BEFORE_SYNC_FLUSH ||
+    pendingBytes >= MAX_PENDING_MUTATION_BYTES_BEFORE_SYNC_FLUSH
+  );
+}
+
+export function getFrgFlushStatus(repoRoot: string): FrgFlushStatus {
+  const flushState = getFlushState(repoRoot);
+  return {
+    inFlight: flushState.inFlight,
+    scheduled: Boolean(flushState.timer),
+    lastScheduledAt: flushState.lastScheduledAt,
+    lastFlushAt: flushState.lastFlushAt,
+    lastError: flushState.lastError,
+    retryCount: flushState.retryCount,
+    retryDelayMs: flushState.retryDelayMs,
+  };
+}
+
+export function getGitDirtyStatus(repoRoot: string): FrgGitDirtyStatus {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const headCommit = runGit(normalizedRepoRoot, ["rev-parse", "HEAD"]) ?? undefined;
+  const headTree = runGit(normalizedRepoRoot, ["rev-parse", "HEAD^{tree}"]) ?? undefined;
+
+  const tracked: Array<{ path: string; operation: FrgMutationOperation }> = [];
+  const trackedOutput = runGit(normalizedRepoRoot, ["diff", "--name-status", "-z", "HEAD", "--"]);
+  if (trackedOutput) {
+    const tokens = trackedOutput.split("\0").filter(Boolean);
+    for (let i = 0; i < tokens.length; i++) {
+      const status = tokens[i] ?? "";
+      if (status.startsWith("R")) {
+        const oldPath = tokens[++i];
+        const newPath = tokens[++i];
+        if (oldPath)
+          tracked.push({
+            path: normalizePath(nodePath.join(normalizedRepoRoot, oldPath)),
+            operation: "delete",
+          });
+        if (newPath)
+          tracked.push({
+            path: normalizePath(nodePath.join(normalizedRepoRoot, newPath)),
+            operation: "write",
+          });
+        continue;
+      }
+      const filePath = tokens[++i];
+      if (!filePath) continue;
+      tracked.push({
+        path: normalizePath(nodePath.join(normalizedRepoRoot, filePath)),
+        operation: status.startsWith("D") ? "delete" : "write",
+      });
+    }
+  }
+
+  const untracked: string[] = [];
+  const untrackedOutput = runGit(normalizedRepoRoot, [
+    "ls-files",
+    "-o",
+    "--exclude-standard",
+    "-z",
+  ]);
+  if (untrackedOutput) {
+    for (const token of untrackedOutput.split("\0").filter(Boolean)) {
+      untracked.push(normalizePath(nodePath.join(normalizedRepoRoot, token)));
+    }
+  }
+
+  return { headCommit, headTree, tracked, untracked };
+}
+
+export function reconcileGitDirtyMutations(repoRoot: string): FrgGitDirtyStatus {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const status = getGitDirtyStatus(normalizedRepoRoot);
+  const state = getRepoState(normalizedRepoRoot);
+  let changed = false;
+
+  for (const entry of status.tracked) {
+    const existing = state.pending.get(entry.path);
+    if (!existing || existing.operation !== entry.operation) {
+      setMutationRecordForRepo(normalizedRepoRoot, entry.path, entry.operation, undefined, {
+        persistWal: false,
+        scheduleFlush: false,
+      });
+      changed = true;
+    }
+  }
+
+  for (const filePath of status.untracked) {
+    const existing = state.pending.get(filePath);
+    if (!existing || existing.operation !== "write") {
+      setMutationRecordForRepo(normalizedRepoRoot, filePath, "write", undefined, {
+        persistWal: false,
+        scheduleFlush: false,
+      });
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    rewriteWal(normalizedRepoRoot);
+    scheduleBackgroundFrgFlush(normalizedRepoRoot);
+  }
+
+  return status;
+}
+
+export function getFrgFreshnessSnapshot(
+  repoRoot: string,
+  indexed?: { commit_hash?: string | null; tree_hash?: string | null; age_seconds?: number },
+): FrgFreshnessSnapshot {
+  const normalizedRepoRoot = normalizePath(repoRoot);
+  const gitStatus = getGitDirtyStatus(normalizedRepoRoot);
+  const flush = getFrgFlushStatus(normalizedRepoRoot);
+  const sessionPendingCount = getPendingFrgMutations(normalizedRepoRoot).length;
+  const sessionPendingBytes = getPendingFrgMutationBytes(normalizedRepoRoot);
+
+  let freshnessState: FrgFreshnessSnapshot["freshnessState"] = "fresh";
+  if (!indexed) {
+    freshnessState = "missing";
+  } else if (flush.inFlight) {
+    freshnessState = "syncing";
+  } else if (flush.scheduled) {
+    freshnessState = "sync-scheduled";
+  } else if (
+    (indexed.tree_hash ?? null) &&
+    gitStatus.headTree &&
+    indexed.tree_hash !== gitStatus.headTree
+  ) {
+    freshnessState = "head-mismatch";
+  } else if (sessionPendingCount > 0) {
+    freshnessState = "session-dirty";
+  } else if (gitStatus.tracked.length > 0 || gitStatus.untracked.length > 0) {
+    freshnessState = "overlay-dirty";
+  } else if ((indexed.age_seconds ?? 0) > 86400) {
+    freshnessState = "stale";
+  }
+
+  return {
+    headCommit: gitStatus.headCommit,
+    headTree: gitStatus.headTree,
+    dirtyTrackedCount: gitStatus.tracked.length,
+    dirtyUntrackedCount: gitStatus.untracked.length,
+    sessionPendingCount,
+    sessionPendingBytes,
+    flush,
+    freshnessState,
+  };
+}
+
+export async function searchPendingFrgMutations(
+  repoRoot: string,
+  options: FrgSessionDeltaSearchOptions,
+): Promise<FrgSessionDeltaSearchResult | null> {
+  const pending = getPendingFrgMutations(repoRoot);
+  if (pending.length === 0) {
+    return null;
+  }
+
+  const regex = compilePattern(options);
+  const fileSet = new Set<string>();
+  const counts = new Map<string, number>();
+  const matches: FrgSearchMatch[] = [];
+  let matched = false;
+
+  for (const record of pending) {
+    if (record.operation === "delete") {
+      continue;
+    }
+
+    const relativePath = relativeToRepo(repoRoot, record.path);
+    if (!pathMatchesFilters(relativePath, options)) {
+      continue;
+    }
+
+    let content: string;
+    if (typeof record.content === "string") {
+      content = record.content;
+    } else {
+      let raw: Buffer;
+      try {
+        raw = await fs.readFile(record.path);
+      } catch {
+        continue;
+      }
+      if (isBinaryBuffer(raw)) {
+        continue;
+      }
+      content = raw.toString("utf8");
+    }
+
+    const lines = content.split(/\r?\n/);
+    let fileMatchCount = 0;
+
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex] ?? "";
+      regex.lastIndex = 0;
+      let lineMatched = false;
+      let execMatch: RegExpExecArray | null;
+      while ((execMatch = regex.exec(line)) !== null) {
+        matched = true;
+        lineMatched = true;
+        fileMatchCount += 1;
+        if (!options.filesOnly && !options.count && !options.quiet) {
+          const context = buildContextLines(lines, lineIndex, options.context ?? 0);
+          matches.push({
+            file: relativePath,
+            line: lineIndex + 1,
+            content: line,
+            match_start: execMatch.index,
+            match_end: execMatch.index + execMatch[0].length,
+            context_before: context.before,
+            context_after: context.after,
+          });
+        }
+        if ((options.maxCount ?? Number.POSITIVE_INFINITY) <= fileMatchCount) {
+          break;
+        }
+        if (execMatch[0].length === 0) {
+          regex.lastIndex += 1;
+        }
+      }
+      if (options.filesOnly && lineMatched) {
+        fileSet.add(relativePath);
+        break;
+      }
+      if ((options.maxCount ?? Number.POSITIVE_INFINITY) <= fileMatchCount) {
+        break;
+      }
+    }
+
+    if (options.count && fileMatchCount > 0) {
+      counts.set(relativePath, fileMatchCount);
+    }
+    if (options.filesOnly && fileMatchCount > 0) {
+      fileSet.add(relativePath);
+    }
+    if (options.quiet && fileMatchCount > 0) {
+      return { mode: "quiet", matched: true };
+    }
+  }
+
+  if (options.quiet) {
+    return { mode: "quiet", matched };
+  }
+  if (options.filesOnly) {
+    return { mode: "files", files: [...fileSet].sort() };
+  }
+  if (options.count) {
+    return {
+      mode: "counts",
+      counts: [...counts.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([file, count]) => ({ file, count })),
+    };
+  }
+  return { mode: "matches", matches };
+}