@flyingrobots/graft 0.4.0 → 0.6.0

package/src/mcp/tools/code-find.ts

@@ -0,0 +1,169 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { GitFileQuery, listGitFiles } from "./git-files.js";
+import {
+  evaluatePrecisionPolicy,
+  getIndexedCommitCeilings,
+  loadFileContent,
+  normalizeRepoPath,
+  PrecisionSearchRequest,
+  type PrecisionSymbolMatch,
+  resolveGitRef,
+  searchLiveSymbols,
+  searchWarpSymbols,
+} from "./precision.js";
+
+class CodeFindRequest {
+  readonly query: string;
+  readonly kind?: string;
+  readonly dirPath: string;
+
+  constructor(args: Record<string, unknown>, projectRoot: string) {
+    const query = args["query"];
+    const kind = args["kind"];
+    const rawPath = args["path"];
+    if (typeof query !== "string" || query.trim().length === 0) {
+      throw new Error("CodeFindRequest: query must be a non-empty string");
+    }
+    if (kind !== undefined && typeof kind !== "string") {
+      throw new Error("CodeFindRequest: kind must be a string when provided");
+    }
+    if (rawPath !== undefined && typeof rawPath !== "string") {
+      throw new Error("CodeFindRequest: path must be a string when provided");
+    }
+
+    this.query = query.trim();
+    if (kind !== undefined && kind.trim().length > 0) this.kind = kind.trim();
+    this.dirPath = rawPath !== undefined && rawPath.trim().length > 0
+      ? normalizeRepoPath(projectRoot, rawPath)
+      : "";
+    Object.freeze(this);
+  }
+
+  toPrecisionSearchRequest(): PrecisionSearchRequest {
+    return new PrecisionSearchRequest({
+      query: this.query,
+      ...(this.kind !== undefined ? { kind: this.kind } : {}),
+      ...(this.dirPath.length > 0 ? { pathPrefix: this.dirPath } : {}),
+    });
+  }
+
+  toProjectFileQuery(projectRoot: string): GitFileQuery {
+    return GitFileQuery.project(projectRoot, this.dirPath);
+  }
+}
+
+interface CodeFindOptions {
+  readonly allowWarp: boolean;
+}
+
+export async function runCodeFind(
+  ctx: ToolContext,
+  args: Record<string, unknown>,
+  options: CodeFindOptions,
+) {
+  const request = new CodeFindRequest(args, ctx.projectRoot);
+  const precisionRequest = request.toPrecisionSearchRequest();
+  const repoState = ctx.getRepoState();
+  const layer = repoState.dirty ? "workspace_overlay" : "ref_view";
+
+  let allMatches: PrecisionSymbolMatch[] = [];
+  let source: "warp" | "live" = "live";
+
+  if (options.allowWarp && !repoState.dirty) {
+    try {
+      const warp = await ctx.getWarp();
+      const ceilings = await getIndexedCommitCeilings(warp);
+      const headSha = await resolveGitRef("HEAD", ctx.git, ctx.projectRoot);
+      if (ceilings.has(headSha)) {
+        allMatches = await searchWarpSymbols(warp, precisionRequest);
+        source = "warp";
+      }
+    } catch {
+      source = "live";
+    }
+  }
+
+  if (source === "live") {
+    allMatches = await searchLiveSymbols(
+      ctx,
+      (await listGitFiles(request.toProjectFileQuery(ctx.projectRoot), ctx.git)).paths,
+      precisionRequest,
+    );
+  }
+
+  const visibleMatches: PrecisionSymbolMatch[] = [];
+  const fileCache = new Map<string, string>();
+  let firstRefusal:
+    | {
+      path: string;
+      reason: string;
+      reasonDetail: string;
+      next: readonly string[];
+      actual: { lines: number; bytes: number };
+    }
+    | undefined;
+
+  for (const match of allMatches) {
+    let content = fileCache.get(match.path);
+    if (content === undefined) {
+      const loaded = await loadFileContent(ctx, match.path);
+      if (loaded === null) continue;
+      fileCache.set(match.path, loaded);
+      content = loaded;
+    }
+
+    const refusal = evaluatePrecisionPolicy(ctx, match.path, content);
+    if (refusal !== null) {
+      firstRefusal ??= refusal;
+      continue;
+    }
+    visibleMatches.push(match);
+  }
+
+  if (visibleMatches.length === 0 && firstRefusal !== undefined) {
+    return ctx.respond("code_find", {
+      query: request.query,
+      kind: request.kind ?? null,
+      path: firstRefusal.path,
+      projection: "refused",
+      reason: firstRefusal.reason,
+      reasonDetail: firstRefusal.reasonDetail,
+      next: [...firstRefusal.next],
+      actual: firstRefusal.actual,
+      source,
+      layer,
+    });
+  }
+
+  ctx.recordFootprint({
+    paths: [...new Set(visibleMatches.map((m) => m.path))],
+    symbols: visibleMatches.map((m) => m.name),
+  });
+
+  return ctx.respond("code_find", {
+    query: request.query,
+    kind: request.kind ?? null,
+    matches: visibleMatches,
+    total: visibleMatches.length,
+    source,
+    layer,
+  });
+}
+
+export const codeFindTool: ToolDefinition = {
+  name: "code_find",
+  description:
+    "Search for symbols across the project by approximate name or glob " +
+    "pattern. Returns matches with file path, kind, signature, and " +
+    "line range. Use code_show to read the source of a specific match.",
+  schema: {
+    query: z.string(),
+    kind: z.string().optional(),
+    path: z.string().optional(),
+  },
+  policyCheck: true,
+  createHandler(): ToolHandler {
+    return (args, ctx) => runCodeFind(ctx, args, { allowWarp: true });
+  },
+};

package/src/mcp/tools/code-refs.ts

@@ -0,0 +1,470 @@
+import * as path from "node:path";
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import type { ProcessRunner } from "../../ports/process-runner.js";
+import { GitFileQuery, listGitFiles } from "./git-files.js";
+import {
+  evaluatePrecisionPolicy,
+  loadFileContent,
+  normalizeRepoPath,
+} from "./precision.js";
+
+const CODE_REFS_MODES = ["text", "import", "call", "property"] as const;
+
+type CodeRefsMode = typeof CODE_REFS_MODES[number];
+type SearchEngine = "ripgrep" | "grep";
+
+class CodeRefsRequest {
+  readonly query: string;
+  readonly mode: CodeRefsMode;
+  readonly dirPath: string;
+
+  constructor(args: Record<string, unknown>, projectRoot: string) {
+    const rawQuery = args["query"];
+    const rawMode = args["mode"];
+    const rawPath = args["path"];
+
+    if (typeof rawQuery !== "string" || rawQuery.trim().length === 0) {
+      throw new Error("CodeRefsRequest: query must be a non-empty string");
+    }
+    if (rawMode !== undefined && (typeof rawMode !== "string" || !CODE_REFS_MODES.includes(rawMode as CodeRefsMode))) {
+      throw new Error("CodeRefsRequest: mode must be one of text, import, call, property");
+    }
+    if (rawPath !== undefined && typeof rawPath !== "string") {
+      throw new Error("CodeRefsRequest: path must be a string when provided");
+    }
+
+    this.query = rawQuery.trim();
+    this.mode = inferCodeRefsMode(this.query, rawMode as CodeRefsMode | undefined);
+    this.dirPath = normalizeScopePath(projectRoot, rawPath);
+    Object.freeze(this);
+  }
+
+  toProjectFileQuery(projectRoot: string): GitFileQuery {
+    return GitFileQuery.project(projectRoot, this.dirPath);
+  }
+
+  scope(): string {
+    return this.dirPath.length > 0 ? this.dirPath : ".";
+  }
+}
+
+class CodeRefsMatch {
+  readonly path: string;
+  readonly line: number;
+  readonly column?: number;
+  readonly preview: string;
+
+  constructor(opts: {
+    path: string;
+    line: number;
+    column?: number;
+    preview: string;
+  }) {
+    if (opts.path.trim().length === 0) {
+      throw new Error("CodeRefsMatch: path must be non-empty");
+    }
+    if (!Number.isInteger(opts.line) || opts.line < 1) {
+      throw new Error("CodeRefsMatch: line must be an integer >= 1");
+    }
+    if (opts.column !== undefined && (!Number.isInteger(opts.column) || opts.column < 1)) {
+      throw new Error("CodeRefsMatch: column must be an integer >= 1");
+    }
+    if (opts.preview.length === 0) {
+      throw new Error("CodeRefsMatch: preview must be non-empty");
+    }
+
+    this.path = opts.path.trim();
+    this.line = opts.line;
+    if (opts.column !== undefined) this.column = opts.column;
+    this.preview = opts.preview;
+    Object.freeze(this);
+  }
+}
+
+class CodeRefsPattern {
+  readonly mode: CodeRefsMode;
+  readonly query: string;
+  readonly pattern: string;
+  readonly fixedStrings: boolean;
+  readonly highlight: string;
+
+  constructor(opts: {
+    mode: CodeRefsMode;
+    query: string;
+    pattern: string;
+    fixedStrings: boolean;
+    highlight: string;
+  }) {
+    this.mode = opts.mode;
+    this.query = opts.query;
+    this.pattern = opts.pattern;
+    this.fixedStrings = opts.fixedStrings;
+    this.highlight = opts.highlight;
+    Object.freeze(this);
+  }
+}
+
+function inferCodeRefsMode(query: string, explicitMode?: CodeRefsMode): CodeRefsMode {
+  if (explicitMode !== undefined) return explicitMode;
+  if (query.startsWith(".")) return "property";
+  if (query.endsWith("(")) return "call";
+  return "text";
+}
+
+function normalizeScopePath(projectRoot: string, rawPath: unknown): string {
+  if (typeof rawPath !== "string" || rawPath.trim().length === 0) {
+    return "";
+  }
+
+  const normalized = normalizeRepoPath(projectRoot, rawPath);
+  if (path.isAbsolute(normalized)) {
+    throw new Error(`Path must stay inside the repository: ${rawPath}`);
+  }
+
+  const resolved = path.resolve(projectRoot, normalized);
+  const rel = path.relative(projectRoot, resolved);
+  if (rel.startsWith("..")) {
+    throw new Error(`Path must stay inside the repository: ${rawPath}`);
+  }
+
+  return rel === "" || rel === "." ? "" : rel;
+}
+
+function escapeRegex(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function buildCodeRefsPattern(request: CodeRefsRequest): CodeRefsPattern {
+  if (request.mode === "text") {
+    return new CodeRefsPattern({
+      mode: request.mode,
+      query: request.query,
+      pattern: request.query,
+      fixedStrings: true,
+      highlight: request.query,
+    });
+  }
+
+  if (request.mode === "import") {
+    const escaped = escapeRegex(request.query);
+    return new CodeRefsPattern({
+      mode: request.mode,
+      query: request.query,
+      pattern: `(\\bimport\\b.*\\b${escaped}\\b|\\bexport\\b.*\\b${escaped}\\b.*\\bfrom\\b)`,
+      fixedStrings: false,
+      highlight: request.query,
+    });
+  }
+
+  if (request.mode === "call") {
+    const normalizedQuery = request.query.endsWith("(")
+      ? request.query.slice(0, -1).trim()
+      : request.query;
+    const escaped = escapeRegex(normalizedQuery);
+    return new CodeRefsPattern({
+      mode: request.mode,
+      query: normalizedQuery,
+      pattern: `\\b${escaped}\\s*\\(`,
+      fixedStrings: false,
+      highlight: normalizedQuery,
+    });
+  }
+
+  const propertyName = request.query.startsWith(".")
+    ? request.query.slice(1)
+    : request.query.includes(".")
+      ? request.query.split(".").at(-1) ?? request.query
+      : request.query;
+  const escaped = escapeRegex(propertyName);
+  return new CodeRefsPattern({
+    mode: request.mode,
+    query: propertyName,
+    pattern: `[?]?\\.${escaped}\\b`,
+    fixedStrings: false,
+    highlight: `.${propertyName}`,
+  });
+}
+
+function buildRipgrepArgs(pattern: CodeRefsPattern, filePaths: readonly string[]): string[] {
+  return [
+    "--no-heading",
+    "--line-number",
+    "--column",
+    "--color",
+    "never",
+    "--with-filename",
+    ...(pattern.fixedStrings ? ["-F"] : []),
+    "-e",
+    pattern.pattern,
+    "--",
+    ...filePaths,
+  ];
+}
+
+function buildGrepArgs(pattern: CodeRefsPattern, filePaths: readonly string[]): string[] {
+  return [
+    "-nH",
+    "-F",
+    pattern.highlight,
+    "--",
+    ...filePaths,
+  ];
+}
+
+function computeColumn(preview: string, highlight: string): number | undefined {
+  const index = preview.indexOf(highlight);
+  return index >= 0 ? index + 1 : undefined;
+}
+
+function parseRipgrepLine(line: string): CodeRefsMatch | null {
+  const match = /^(.*?):(\d+):(\d+):(.*)$/.exec(line);
+  if (match === null) return null;
+  const filePath = match[1];
+  const rawLine = match[2];
+  const rawColumn = match[3];
+  const preview = match[4];
+  if (filePath === undefined || rawLine === undefined || rawColumn === undefined || preview === undefined) {
+    return null;
+  }
+  return new CodeRefsMatch({
+    path: filePath,
+    line: Number(rawLine),
+    column: Number(rawColumn),
+    preview,
+  });
+}
+
+function parseGrepLine(line: string, highlight: string): CodeRefsMatch | null {
+  const match = /^(.*?):(\d+):(.*)$/.exec(line);
+  if (match === null) return null;
+  const filePath = match[1];
+  const rawLine = match[2];
+  const preview = match[3];
+  if (filePath === undefined || rawLine === undefined || preview === undefined) {
+    return null;
+  }
+  const column = computeColumn(preview, highlight);
+  return new CodeRefsMatch({
+    path: filePath,
+    line: Number(rawLine),
+    ...(column !== undefined ? { column } : {}),
+    preview,
+  });
+}
+
+function parseSearchOutput(
+  stdout: string,
+  parser: (line: string, highlight: string) => CodeRefsMatch | null,
+  highlight: string,
+): CodeRefsMatch[] {
+  if (stdout.trim().length === 0) return [];
+  return stdout
+    .trim()
+    .split("\n")
+    .map((line) => parser(line, highlight))
+    .filter((match): match is CodeRefsMatch => match !== null);
+}
+
+function parseRipgrepOutput(stdout: string): CodeRefsMatch[] {
+  return parseSearchOutput(stdout, (line) => parseRipgrepLine(line), "");
+}
+
+function isRelevantReferencePreview(pattern: CodeRefsPattern, preview: string): boolean {
+  const trimmed = preview.trim();
+
+  if (pattern.mode === "text") {
+    return true;
+  }
+
+  if (pattern.mode === "import") {
+    return /\bimport\b/.test(trimmed) || (/\bexport\b/.test(trimmed) && /\bfrom\b/.test(trimmed));
+  }
+
+  if (pattern.mode === "call") {
+    if (/^\s*import\b/.test(trimmed)) {
+      return false;
+    }
+    if (/^\s*export\b/.test(trimmed) && /\bfrom\b/.test(trimmed)) {
+      return false;
+    }
+
+    const escaped = escapeRegex(pattern.query);
+    const functionDeclaration = new RegExp(`\\bfunction\\s+${escaped}\\s*\\(`);
+    if (functionDeclaration.test(trimmed)) {
+      return false;
+    }
+
+    const methodDeclaration = new RegExp(
+      `^(?:export\\s+)?(?:async\\s+)?${escaped}\\s*\\([^)]*\\)\\s*(?::[^=]+)?\\{`,
+    );
+    return !methodDeclaration.test(trimmed);
+  }
+
+  return trimmed.includes(`.${pattern.query}`) || trimmed.includes(`?.${pattern.query}`);
+}
+
+function filterReferenceMatches(
+  matches: readonly CodeRefsMatch[],
+  pattern: CodeRefsPattern,
+): CodeRefsMatch[] {
+  return matches.filter((match) => isRelevantReferencePreview(pattern, match.preview));
+}
+
+function runSearchCommand(
+  command: string,
+  args: readonly string[],
+  cwd: string,
+  process: ProcessRunner,
+): {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+} {
+  return process.run({ command, args, cwd });
+}
+
+function runTextFallbackSearch(
+  projectRoot: string,
+  pattern: CodeRefsPattern,
+  filePaths: readonly string[],
+  process: ProcessRunner,
+): {
+  engine: SearchEngine;
+  matches: readonly CodeRefsMatch[];
+} {
+  if (filePaths.length === 0) {
+    return { engine: "ripgrep", matches: [] };
+  }
+
+  const rg = runSearchCommand("rg", buildRipgrepArgs(pattern, filePaths), projectRoot, process);
+  if (rg.error === undefined) {
+    if (rg.status === 0) {
+      return {
+        engine: "ripgrep",
+        matches: filterReferenceMatches(parseRipgrepOutput(rg.stdout), pattern),
+      };
+    }
+    if (rg.status === 1) {
+      return { engine: "ripgrep", matches: [] };
+    }
+    throw new Error(`ripgrep search failed: ${rg.stderr.trim()}`);
+  }
+
+  const grep = runSearchCommand("grep", buildGrepArgs(pattern, filePaths), projectRoot, process);
+  if (grep.error === undefined) {
+    if (grep.status === 0) {
+      return {
+        engine: "grep",
+        matches: filterReferenceMatches(
+          parseSearchOutput(grep.stdout, parseGrepLine, pattern.highlight),
+          pattern,
+        ),
+      };
+    }
+    if (grep.status === 1) {
+      return { engine: "grep", matches: [] };
+    }
+    throw new Error(`grep search failed: ${grep.stderr.trim()}`);
+  }
+
+  const rgMessage = rg.error instanceof Error ? rg.error.message : String(rg.error);
+  const grepMessage = grep.error instanceof Error ? grep.error.message : String(grep.error);
+  throw new Error(`reference search failed: ripgrep unavailable (${rgMessage}); grep unavailable (${grepMessage})`);
+}
+
+export const codeRefsTool: ToolDefinition = {
+  name: "code_refs",
+  description:
+    "Search for import sites, callsites, property access, or literal text " +
+    "references across the working tree. Returns explicit text-fallback " +
+    "matches with the engine, pattern, and scope used.",
+  schema: {
+    query: z.string(),
+    mode: z.enum(CODE_REFS_MODES).optional(),
+    path: z.string().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const request = new CodeRefsRequest(args, ctx.projectRoot);
+      const pattern = buildCodeRefsPattern(request);
+      const repoState = ctx.getRepoState();
+      const layer = repoState.dirty ? "workspace_overlay" : "ref_view";
+      const filePaths = (await listGitFiles(request.toProjectFileQuery(ctx.projectRoot), ctx.git)).paths;
+      const fallback = runTextFallbackSearch(ctx.projectRoot, pattern, filePaths, ctx.process);
+
+      const visibleMatches: CodeRefsMatch[] = [];
+      const fileCache = new Map<string, string>();
+      let firstRefusal:
+        | {
+          path: string;
+          reason: string;
+          reasonDetail: string;
+          next: readonly string[];
+          actual: { lines: number; bytes: number };
+        }
+        | undefined;
+
+      for (const match of fallback.matches) {
+        let content = fileCache.get(match.path);
+        if (content === undefined) {
+          const loaded = await loadFileContent(ctx, match.path);
+          if (loaded === null) continue;
+          fileCache.set(match.path, loaded);
+          content = loaded;
+        }
+
+        const refusal = evaluatePrecisionPolicy(ctx, match.path, content);
+        if (refusal !== null) {
+          firstRefusal ??= refusal;
+          continue;
+        }
+
+        visibleMatches.push(match);
+      }
+
+      if (visibleMatches.length === 0 && firstRefusal !== undefined) {
+        return ctx.respond("code_refs", {
+          query: request.query,
+          mode: request.mode,
+          scope: request.scope(),
+          path: firstRefusal.path,
+          projection: "refused",
+          reason: firstRefusal.reason,
+          reasonDetail: firstRefusal.reasonDetail,
+          next: [...firstRefusal.next],
+          actual: firstRefusal.actual,
+          source: "text_fallback",
+          provenance: {
+            engine: fallback.engine,
+            pattern: pattern.pattern,
+            approximate: true,
+            filesSearched: filePaths.length,
+          },
+          layer,
+        });
+      }
+
+      ctx.recordFootprint({
+        paths: [...new Set(visibleMatches.map((m) => m.path))],
+      });
+
+      return ctx.respond("code_refs", {
+        query: request.query,
+        mode: request.mode,
+        scope: request.scope(),
+        matches: visibleMatches,
+        total: visibleMatches.length,
+        source: "text_fallback",
+        provenance: {
+          engine: fallback.engine,
+          pattern: pattern.pattern,
+          approximate: true,
+          filesSearched: filePaths.length,
+        },
+        layer,
+      });
+    };
+  },
+};