@mrclrchtr/supi-code-intelligence 1.6.0 → 1.8.0

package/src/presentation/markdown/pattern.ts

@@ -0,0 +1,239 @@
+// Pattern search markdown renderer — all formatting for literal, regex, and structured search results.
+
+import type { StructuredMatch, StructuredPatternResult } from "../../pattern-structured.ts";
+import type { RgMatch } from "../../search-helpers.ts";
+import { groupByFile } from "../../search-helpers.ts";
+import type { StructuralSubstrate } from "../../substrates/types.ts";
+
+// ── Structured search formatting ─────────────────────────────────────
+
+// biome-ignore lint/complexity/useMaxParams: structured empty-state with optional result parameter keeps partial-warning logic together
+export function renderStructuredEmptyState(
+  pattern: string,
+  kind: "definition" | "export" | "import",
+  relScope: string,
+  _structural?: StructuralSubstrate,
+  result?: StructuredPatternResult,
+): string {
+  const lines = [`No ${kind} matches found for \`${pattern}\` in \`${relScope}\`.`];
+  if (result && result.omittedCount > 0 && result.partialReason) {
+    lines.push("");
+    if (result.partialReason === "timeout") {
+      lines.push(
+        `_Partial structured results — scan timed out with +${result.omittedCount} file${result.omittedCount !== 1 ? "s" : ""} omitted. Narrow \`path\` or \`pattern\` for complete coverage._`,
+      );
+    } else {
+      lines.push(
+        `_Partial structured results — +${result.omittedCount} file${result.omittedCount !== 1 ? "s" : ""} omitted after reaching the structured scan cap. Narrow \`path\` or \`pattern\` for complete coverage._`,
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+export function renderStructuredMatches(
+  pattern: string,
+  kind: "definition" | "export" | "import",
+  relScope: string,
+  result: StructuredPatternResult,
+): string {
+  const grouped = new Map<string, StructuredMatch[]>();
+  for (const match of result.matches) {
+    const group = grouped.get(match.file) ?? [];
+    group.push(match);
+    grouped.set(match.file, group);
+  }
+
+  const kindLabel =
+    kind === "definition" ? "Definitions" : kind === "export" ? "Exports" : "Imports";
+  const lines: string[] = [];
+  lines.push(`# Pattern ${kindLabel}: \`${pattern}\``);
+  lines.push("");
+  lines.push(
+    `**${result.matches.length} match${result.matches.length !== 1 ? "es" : ""}** across **${grouped.size} file${grouped.size !== 1 ? "s" : ""}** in \`${relScope}\``,
+  );
+  const partialWarning = formatPartialStructuredWarning(result);
+  if (partialWarning) {
+    lines.push(partialWarning);
+  }
+  lines.push("");
+
+  if (kind === "definition" || kind === "export") {
+    addDuplicateSummary(lines, result.matches);
+  }
+
+  for (const [file, fileMatches] of grouped) {
+    lines.push(`### ${file}`);
+    for (const match of fileMatches.slice(0, 8)) {
+      lines.push(`- \`${match.name}\` (${match.kind}) L${match.line}`);
+    }
+    if (fileMatches.length > 8) {
+      lines.push(`- _+${fileMatches.length - 8} more in this file_`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function formatPartialStructuredWarning(result: StructuredPatternResult): string | null {
+  if (!result.partialReason || result.omittedCount <= 0) return null;
+
+  if (result.partialReason === "timeout") {
+    return `_Partial structured results — scan timed out with +${result.omittedCount} file${result.omittedCount !== 1 ? "s" : ""} omitted. Narrow \`path\` or \`pattern\` for complete coverage._`;
+  }
+
+  return `_Partial structured results — +${result.omittedCount} file${result.omittedCount !== 1 ? "s" : ""} omitted after reaching the structured scan cap. Narrow \`path\` or \`pattern\` for complete coverage._`;
+}
+
+function addDuplicateSummary(lines: string[], matches: StructuredMatch[]): void {
+  const byName = new Map<string, Set<string>>();
+  for (const match of matches) {
+    const files = byName.get(match.name) ?? new Set<string>();
+    files.add(match.file);
+    byName.set(match.name, files);
+  }
+
+  const duplicates = [...byName.entries()]
+    .map(([name, files]) => ({ name, files: [...files].sort((a, b) => a.localeCompare(b)) }))
+    .filter((entry) => entry.files.length > 1)
+    .sort((a, b) => b.files.length - a.files.length || a.name.localeCompare(b.name));
+
+  if (duplicates.length === 0) return;
+
+  lines.push("## Duplicate Definitions");
+  for (const duplicate of duplicates.slice(0, 8)) {
+    lines.push(
+      `- \`${duplicate.name}\` — defined in ${duplicate.files.length} files: ${duplicate.files
+        .map((file) => `\`${file}\``)
+        .join(", ")}`,
+    );
+  }
+  if (duplicates.length > 8) {
+    lines.push(`- _+${duplicates.length - 8} more duplicates_`);
+  }
+  lines.push("");
+}
+
+// ── Text search formatting ──────────────────────────────────────────
+
+export function renderRegexError(pattern: string, error: string): string {
+  const errLines = error
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const detail =
+    [...errLines]
+      .reverse()
+      .find((line) => line.startsWith("error:"))
+      ?.replace(/^error:\s*/, "") ??
+    errLines.at(-1) ??
+    "ripgrep rejected the regex.";
+  return `**Error:** Invalid regex pattern \`${pattern}\`: ${detail}`;
+}
+
+export function renderPatternResults(
+  pattern: string,
+  relScope: string,
+  matches: RgMatch[],
+  maxResults: number,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Pattern: \`${pattern}\``);
+  lines.push("");
+  lines.push(`**${matches.length} match${matches.length > 1 ? "es" : ""}** in \`${relScope}\``);
+  lines.push("");
+
+  const byFile = groupByFile(matches);
+  let shown = 0;
+  for (const [file, fileMatches] of byFile) {
+    if (shown >= maxResults) break;
+    lines.push(`### ${file}`);
+    const renderedLines = new Set<number>();
+    const matchLines = new Set(fileMatches.map((match) => match.line));
+    for (const m of fileMatches.slice(0, 5)) {
+      renderMatchWithContext(lines, m, renderedLines, matchLines, pattern);
+    }
+    if (fileMatches.length > 5) {
+      lines.push(`- _+${fileMatches.length - 5} more in this file_`);
+    }
+    lines.push("");
+    shown++;
+  }
+
+  if (byFile.size > maxResults) {
+    lines.push(
+      `_+${byFile.size - maxResults} more files omitted. Narrow \`path\` or increase \`maxResults\`._`,
+    );
+  }
+  lines.push("");
+  lines.push("_Text search — results may include comments, strings, or unrelated matches._");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: context-line rendering with before/after/skip logic is clearer as one function
+// biome-ignore lint/complexity/useMaxParams: options-object refactor would reduce readability for this rendering helper
+function renderMatchWithContext(
+  lines: string[],
+  m: RgMatch,
+  renderedLines: Set<number>,
+  matchLines: Set<number>,
+  _pattern: string,
+): void {
+  if (m.context) {
+    for (const c of m.context.filter((cx) => cx.line < m.line)) {
+      if (renderedLines.has(c.line) || matchLines.has(c.line)) continue;
+      lines.push(`  L${c.line}: ${c.text.slice(0, 120)}`);
+      renderedLines.add(c.line);
+    }
+  }
+  if (!renderedLines.has(m.line)) {
+    lines.push(`- L${m.line}: \`${(m.text || "").slice(0, 120)}\``);
+    renderedLines.add(m.line);
+  }
+  if (m.context) {
+    for (const c of m.context.filter((cx) => cx.line > m.line)) {
+      if (renderedLines.has(c.line) || matchLines.has(c.line)) continue;
+      lines.push(`  L${c.line}: ${c.text.slice(0, 120)}`);
+      renderedLines.add(c.line);
+    }
+  }
+}
+
+export function renderPatternSummary(
+  pattern: string,
+  relScope: string,
+  matches: RgMatch[],
+  maxResults: number,
+): string {
+  const byFile = groupByFile(matches);
+  const sorted = [...byFile.entries()].sort((a, b) => b[1].length - a[1].length);
+
+  const lines: string[] = [];
+  lines.push(`# Pattern Summary: \`${pattern}\``);
+  lines.push("");
+  lines.push(
+    `**${matches.length} match${matches.length > 1 ? "es" : ""}** across **${byFile.size} file${byFile.size > 1 ? "s" : ""}** in \`${relScope}\``,
+  );
+  lines.push("");
+
+  for (const [file, fileMatches] of sorted.slice(0, maxResults)) {
+    const lineNums = [...new Set(fileMatches.map((m) => m.line))].sort((a, b) => a - b).slice(0, 3);
+    const extra = fileMatches.length > 3 ? ` (+${fileMatches.length - 3} more)` : "";
+    const linesStr = lineNums.join(", ");
+    lines.push(
+      `- \`${file}\` — ${fileMatches.length} match${fileMatches.length > 1 ? "es" : ""}${linesStr ? ` at L${linesStr}` : ""}${extra}`,
+    );
+  }
+
+  if (sorted.length > maxResults) {
+    lines.push(`- _+${sorted.length - maxResults} more files omitted_`);
+  }
+  lines.push("");
+  lines.push("_Text search — results may include comments, strings, or unrelated matches._");
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/presentation/markdown/relations.ts

@@ -0,0 +1,121 @@
+// Relations markdown renderer — consumes use-case data and produces markdown content.
+
+import { isInProjectPath, uriToFile } from "../../search-helpers.ts";
+import type { ReferenceCollection } from "../../use-case/support/semantic-references.ts";
+import { formatReferenceList } from "../../use-case/support/semantic-references.ts";
+
+// ── Callers ──────────────────────────────────────────────────────────
+
+export function renderCallersResult(
+  symbolName: string,
+  result: ReferenceCollection,
+  cwd: string,
+  maxResults: number,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Callers of \`${symbolName}\``);
+  lines.push("");
+  lines.push(
+    `**${result.refs.length} reference${result.refs.length !== 1 ? "s" : ""}** (${result.confidence})`,
+  );
+  if (result.externalCount > 0) {
+    lines.push(
+      `_+${result.externalCount} external reference${result.externalCount !== 1 ? "s" : ""}_`,
+    );
+  }
+  lines.push("");
+
+  formatReferenceList(lines, result.refs, maxResults, cwd);
+  return lines.join("\n");
+}
+
+// ── Implementations ──────────────────────────────────────────────────
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: implementation rendering with project/external splitting and formatting is clearer as one function
+export function renderImplementationsResult(
+  locations: Array<{
+    uri?: string;
+    targetUri?: string;
+    range?: { start: { line: number } };
+    targetRange?: { start: { line: number } };
+    targetSelectionRange?: { start: { line: number } };
+  }>,
+  cwd: string,
+  maxResults: number,
+): string {
+  const projectLocs = locations.filter((loc) => {
+    const uri = loc.uri ?? loc.targetUri ?? "";
+    const filePath = uriToFile(uri);
+    return filePath && isInProjectPath(filePath, cwd);
+  });
+  const externalLocs = locations.filter((loc) => {
+    const uri = loc.uri ?? loc.targetUri ?? "";
+    const filePath = uriToFile(uri);
+    return !filePath || !isInProjectPath(filePath, cwd);
+  });
+
+  const lines: string[] = [];
+  lines.push("# Implementations (semantic)");
+  lines.push("");
+  if (projectLocs.length > 0) {
+    lines.push(
+      `**${projectLocs.length} implementation${projectLocs.length !== 1 ? "s" : ""}** in the project`,
+    );
+    lines.push("");
+    for (const loc of projectLocs.slice(0, maxResults)) {
+      const uri = loc.uri ?? loc.targetUri ?? "";
+      const filePath = uriToFile(uri);
+      const range = loc.targetSelectionRange ?? loc.targetRange ?? loc.range;
+      if (filePath && range) {
+        lines.push(`- \`${filePath}:${(range as { start: { line: number } }).start.line + 1}\``);
+      } else if (filePath) {
+        lines.push(`- \`${filePath}\``);
+      }
+    }
+    lines.push("");
+  }
+
+  if (externalLocs.length > 0) {
+    lines.push(
+      `_+${externalLocs.length} external location${externalLocs.length !== 1 ? "s" : ""} (outside this project)_`,
+    );
+    lines.push("");
+  }
+
+  lines.push(
+    "_Semantic analysis. Use `code_pattern` only when you explicitly want text-search hints for likely implementations._",
+  );
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+// ── Callees ──────────────────────────────────────────────────────────
+
+export function renderCalleesResult(
+  data: { enclosingScope: { name: string }; callees: Array<{ name: string; startLine: number }> },
+  relPath: string,
+  maxResults: number,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Callees of \`${data.enclosingScope.name}\` (structural)`);
+  lines.push("");
+  lines.push(
+    `**${data.callees.length} outgoing call${data.callees.length > 1 ? "s" : ""}** from \`${data.enclosingScope.name}\` in \`${relPath}\``,
+  );
+  lines.push("");
+
+  const shown = data.callees.slice(0, maxResults);
+  for (const c of shown) {
+    lines.push(`- \`${c.name}\` (L${c.startLine})`);
+  }
+  if (data.callees.length > maxResults) {
+    lines.push(`- _+${data.callees.length - maxResults} more_`);
+  }
+  lines.push("");
+  lines.push(
+    "_Structural analysis — may include unresolved or qualified names. Use `lsp_hover` with `file`, `line`, and `character` for precise type information._",
+  );
+  lines.push("");
+  return lines.join("\n");
+}

package/src/prioritization-signals.ts

@@ -1,5 +1,5 @@
-import * as fs from "node:fs";
 import * as path from "node:path";
+import { readJsonFile } from "@mrclrchtr/supi-core/config";
 import { getSessionLspService } from "@mrclrchtr/supi-lsp/api";
 
 export interface PrioritySignalsSummary {
@@ -106,22 +106,18 @@ function loadDiagnostics(
 
 function loadCoverageSummary(cwd: string): Map<string, number> {
   const coveragePath = path.join(cwd, "coverage", "coverage-summary.json");
-  if (!fs.existsSync(coveragePath)) return new Map();
-
-  try {
-    const parsed = JSON.parse(fs.readFileSync(coveragePath, "utf-8")) as Record<string, unknown>;
-    const map = new Map<string, number>();
-    for (const [file, value] of Object.entries(parsed)) {
-      if (file === "total" || typeof value !== "object" || value === null) continue;
-      const linesPct = getPct(value, "lines");
-      const statementsPct = getPct(value, "statements");
-      const pct = Math.min(linesPct ?? 100, statementsPct ?? 100);
-      map.set(path.resolve(cwd, file), pct);
-    }
-    return map;
-  } catch {
-    return new Map();
+  const parsed = readJsonFile(coveragePath);
+  if (!parsed) return new Map();
+
+  const map = new Map<string, number>();
+  for (const [file, value] of Object.entries(parsed)) {
+    if (file === "total" || typeof value !== "object" || value === null) continue;
+    const linesPct = getPct(value, "lines");
+    const statementsPct = getPct(value, "statements");
+    const pct = Math.min(linesPct ?? 100, statementsPct ?? 100);
+    map.set(path.resolve(cwd, file), pct);
   }
+  return map;
 }
 
 function loadUnusedFiles(cwd: string): Set<string> {
@@ -157,16 +153,7 @@ function loadUnusedExports(cwd: string): Array<{ file: string; name: string }> {
 }
 
 function loadKnipJson(cwd: string): Record<string, unknown> | null {
-  const knipPath = path.join(cwd, "knip.json");
-  if (!fs.existsSync(knipPath)) return null;
-  try {
-    const parsed = JSON.parse(fs.readFileSync(knipPath, "utf-8"));
-    return typeof parsed === "object" && parsed !== null
-      ? (parsed as Record<string, unknown>)
-      : null;
-  } catch {
-    return null;
-  }
+  return readJsonFile(path.join(cwd, "knip.json"));
 }
 
 function getPct(value: object, key: string): number | null {

package/src/query-params.ts

@@ -0,0 +1,15 @@
+/** Shared parameter bag for internal code-intelligence actions. */
+export interface CodeQueryParams {
+  path?: string;
+  file?: string;
+  line?: number;
+  character?: number;
+  symbol?: string;
+  pattern?: string;
+  regex?: boolean;
+  kind?: string;
+  exportedOnly?: boolean;
+  maxResults?: number;
+  contextLines?: number;
+  summary?: boolean;
+}

package/src/resolve-target.ts

@@ -1,3 +1,13 @@
+/**
+ * Action-facing target resolution — routes normalized queries and
+ * maps typed resolver outcomes to user-facing strings and legacy types.
+ *
+ * This is the thin orchestration layer between tool/action params and
+ * the typed targeting pipeline. Formatting of disambiguation/error
+ * outcomes happens here, at the action boundary.
+ */
+
+import type { CodeQueryParams as ActionParams } from "./query-params.ts";
 import {
   type ResolvedTarget,
   type ResolvedTargetGroup,
@@ -5,33 +15,44 @@ import {
   resolveFileTargetGroup,
   resolveSymbolTarget,
 } from "./target-resolution.ts";
-import type { ActionParams } from "./tool-actions.ts";
+import { normalizeQuery } from "./targeting/query.ts";
+import type { ResolverDeps, TargetOutcome } from "./targeting/types.ts";
 
 /**
- * Resolve a target from action params. Returns either a target, a file-level target group,
- * or a string error/disambiguation message to return directly.
+ * Resolve a target from action params.
+ *
+ * Returns either a {@link ResolvedTarget}, a {@link ResolvedTargetGroup},
+ * or a user-facing error/disambiguation string.
  */
 export async function resolveTarget(
   params: ActionParams,
   cwd: string,
+  semantic?: import("./substrates/types.ts").SemanticSubstrate,
 ): Promise<ResolvedTarget | ResolvedTargetGroup | string> {
-  if (!params.file && !params.symbol) {
-    return "**Error:** Semantic actions require either anchored coordinates (`file`, `line`, `character`) or a `symbol` for discovery.";
-  }
+  const query = normalizeQuery(params);
 
-  if (params.file && params.line != null && params.character != null) {
-    return resolveAnchored(params.file, params.line, params.character, cwd);
-  }
+  switch (query.kind) {
+    case "anchored":
+      return resolveAnchored(query.file, query.line, query.character, cwd);
 
-  if (params.file && !params.symbol) {
-    return resolveByFile(params.file, cwd);
-  }
+    case "file":
+      return resolveByFile(query.file, cwd);
 
-  if (params.symbol) {
-    return resolveBySymbol(params, cwd);
-  }
+    case "symbol": {
+      if (!semantic) {
+        return "**Error:** Symbol discovery requires active LSP. Use `file` + coordinates, or enable LSP and retry.";
+      }
+      const deps: ResolverDeps = { cwd, semantic };
+      return resolveBySymbol(query.symbol, deps, {
+        path: query.path,
+        kind: query.symbolKind,
+        exportedOnly: query.exportedOnly,
+      });
+    }
 
-  return "**Error:** Could not resolve target.";
+    case "invalid":
+      return `**Error:** ${query.reason}`;
+  }
 }
 
 function resolveAnchored(
@@ -43,7 +64,7 @@ function resolveAnchored(
   const result = resolveAnchoredTarget(file, line, character, cwd);
   if (result.kind === "error") return result.message;
   if (result.kind === "resolved") return result.target;
-  return "**Error:** Unexpected disambiguation for anchored target.";
+  return "**Error:** Unexpected resolution outcome.";
 }
 
 async function resolveByFile(file: string, cwd: string): Promise<ResolvedTargetGroup | string> {
@@ -53,38 +74,35 @@ async function resolveByFile(file: string, cwd: string): Promise<ResolvedTargetG
 }
 
 async function resolveBySymbol(
-  params: ActionParams,
-  cwd: string,
+  symbol: string,
+  deps: ResolverDeps,
+  options?: { path?: string; kind?: string; exportedOnly?: boolean },
 ): Promise<ResolvedTarget | string> {
-  const result = await resolveSymbolTarget(params.symbol ?? "", cwd, {
-    path: params.path,
-    kind: params.kind,
-    exportedOnly: params.exportedOnly,
-  });
+  const outcome: TargetOutcome = await resolveSymbolTarget(
+    symbol,
+    deps.cwd,
+    // biome-ignore lint/style/noNonNullAssertion: semantic is always set for symbol queries
+    deps.semantic!,
+    options,
+  );
 
-  if (result.kind === "error") return result.message;
-  if (result.kind === "resolved") return result.target;
+  if (outcome.kind === "resolved") {
+    return outcome.target as ResolvedTarget;
+  }
+
+  if (outcome.kind === "error") {
+    return outcome.message;
+  }
 
-  return formatDisambiguation(params, result);
+  return formatDisambiguation(symbol, outcome);
 }
 
 function formatDisambiguation(
-  params: ActionParams,
-  result: {
-    candidates: Array<{
-      name: string;
-      kind: string | null;
-      container: string | null;
-      file: string;
-      line: number;
-      character: number;
-      rank: number;
-    }>;
-    omittedCount: number;
-  },
+  symbol: string,
+  result: Extract<TargetOutcome, { kind: "disambiguation" }>,
 ): string {
   const lines: string[] = [];
-  lines.push(`# Disambiguation needed for \`${params.symbol}\``);
+  lines.push(`# Disambiguation needed for \`${symbol}\``);
   lines.push("");
   const omitNote = result.omittedCount > 0 ? ` (+${result.omittedCount} more)` : "";
   lines.push(
@@ -104,7 +122,7 @@ function formatDisambiguation(
   if (result.candidates.length > 0) {
     const first = result.candidates[0];
     lines.push(
-      `Example: \`{ "action": "${params.action}", "file": "${first.file}", "line": ${first.line}, "character": ${first.character} }\``,
+      `Example: rerun with \`file: "${first.file}"\`, \`line: ${first.line}\`, and \`character: ${first.character}\`.`,
     );
   }
 

package/src/search-helpers.ts

@@ -1,8 +1,8 @@
-// Shared search helpers for code_intel actions.
+// Shared search helpers for code-intelligence search and routing helpers.
 
 import { execFileSync } from "node:child_process";
 import * as path from "node:path";
-import { resolveToolPath, uriToFile as uriToFileShared } from "@mrclrchtr/supi-core/api";
+import { resolveToolPath, uriToFile as uriToFileShared } from "@mrclrchtr/supi-core/path";
 
 const LOW_SIGNAL_DIRS = new Set([
   "node_modules",
@@ -71,7 +71,7 @@ export interface RipgrepRunResult {
 /**
  * Run ripgrep with JSON output and parse matches, filtering low-signal paths.
  *
- * This helper preserves the historical behavior used by most `code_intel`
+ * This helper preserves the historical behavior used by internal
  * actions: any ripgrep execution failure is treated like an empty match set.
  * Call `runRipgrepDetailed()` when a caller needs to surface regex parse errors
  * or other non-no-match failures to the agent.
@@ -80,7 +80,12 @@ export function runRipgrep(
   pattern: string,
   scopePath: string,
   cwd: string,
-  opts?: { maxMatches?: number; contextLines?: number; filterLowSignal?: boolean },
+  opts?: {
+    maxMatches?: number;
+    contextLines?: number;
+    literal?: boolean;
+    filterLowSignal?: boolean;
+  },
 ): RgMatch[] {
   return runRipgrepDetailed(pattern, scopePath, cwd, opts).matches;
 }
@@ -93,7 +98,12 @@ export function runRipgrepDetailed(
   pattern: string,
   scopePath: string,
   cwd: string,
-  opts?: { maxMatches?: number; contextLines?: number; filterLowSignal?: boolean },
+  opts?: {
+    maxMatches?: number;
+    contextLines?: number;
+    literal?: boolean;
+    filterLowSignal?: boolean;
+  },
 ): RipgrepRunResult {
   const filter = opts?.filterLowSignal ?? true;
 
@@ -114,12 +124,15 @@ export function runRipgrepDetailed(
 function buildRipgrepArgs(
   pattern: string,
   scopePath: string,
-  opts?: { maxMatches?: number; contextLines?: number },
+  opts?: { maxMatches?: number; contextLines?: number; literal?: boolean },
 ): string[] {
   const args = ["--json", "-m", String(opts?.maxMatches ?? 30)];
   if ((opts?.contextLines ?? 0) > 0) {
     args.push("-C", String(opts?.contextLines ?? 0));
   }
+  if (opts?.literal) {
+    args.push("-F");
+  }
   args.push("-e", pattern, scopePath);
   return args;
 }