@flyingrobots/graft 0.4.0 → 0.5.0

package/src/mcp/tools/map.ts

@@ -3,26 +3,69 @@ import { z } from "zod";
 import { extractOutline } from "../../parser/outline.js";
 import { detectLang } from "../../parser/lang.js";
 import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
-import { execFileSync } from "node:child_process";
+import { GitFileQuery, listGitFiles } from "./git-files.js";
+import { evaluateMcpRefusal, type McpPolicyRefusal } from "../policy.js";
+import { collectSymbols, normalizeRepoPath } from "./precision.js";
 
-interface FileEntry {
+class StructuralMapRequest {
+  readonly directory: string;
+
+  constructor(args: Record<string, unknown>, projectRoot: string) {
+    const rawPath = args["path"];
+    if (rawPath !== undefined && typeof rawPath !== "string") {
+      throw new Error("StructuralMapRequest: path must be a string when provided");
+    }
+    this.directory = rawPath !== undefined && rawPath.trim().length > 0
+      ? normalizeRepoPath(projectRoot, rawPath)
+      : ".";
+    Object.freeze(this);
+  }
+
+  toGitFileQuery(projectRoot: string): GitFileQuery {
+    return GitFileQuery.project(projectRoot, this.directory === "." ? "" : this.directory);
+  }
+}
+
+class StructuralMapSymbol {
+  readonly name: string;
+  readonly kind: string;
+  readonly signature?: string;
+  readonly exported: boolean;
+  readonly startLine?: number;
+  readonly endLine?: number;
+
+  constructor(opts: {
+    name: string;
+    kind: string;
+    signature?: string;
+    exported: boolean;
+    startLine?: number;
+    endLine?: number;
+  }) {
+    this.name = opts.name;
+    this.kind = opts.kind;
+    this.exported = opts.exported;
+    if (opts.signature !== undefined) this.signature = opts.signature;
+    if (opts.startLine !== undefined) this.startLine = opts.startLine;
+    if (opts.endLine !== undefined) this.endLine = opts.endLine;
+    Object.freeze(this);
+  }
+}
+
+class StructuralMapFile {
   path: string;
   lang: string;
-  symbols: { name: string; kind: string; signature?: string | undefined; exported: boolean; startLine?: number | undefined; endLine?: number | undefined }[];
-}
+  symbols: readonly StructuralMapSymbol[];
 
-/**
- * List files in a directory (git ls-files for tracked files).
- */
-function listFiles(dirPath: string, cwd: string): string[] {
-  try {
-    const args = dirPath.length > 0
-      ? ["ls-files", "--", dirPath]
-      : ["ls-files"];
-    return execFileSync("git", args, { cwd, encoding: "utf-8" })
-      .trim().split("\n").filter((l) => l.length > 0);
-  } catch {
-    return [];
+  constructor(opts: {
+    path: string;
+    lang: string;
+    symbols: readonly StructuralMapSymbol[];
+  }) {
+    this.path = opts.path;
+    this.lang = opts.lang;
+    this.symbols = Object.freeze([...opts.symbols]);
+    Object.freeze(this);
   }
 }
 
@@ -36,45 +79,56 @@ export const mapTool: ToolDefinition = {
     path: z.string().optional(),
   },
   createHandler(ctx: ToolContext): ToolHandler {
-    return (args) => {
-      const dirPath = (args["path"] as string | undefined) ?? "";
+    return async (args) => {
+      const request = new StructuralMapRequest(args, ctx.projectRoot);
 
-      const filePaths = listFiles(dirPath, ctx.projectRoot);
-      const files: FileEntry[] = [];
+      const filePaths = (await listGitFiles(request.toGitFileQuery(ctx.projectRoot), ctx.git)).paths;
+      const files: StructuralMapFile[] = [];
+      const refused: McpPolicyRefusal[] = [];
 
       for (const filePath of filePaths) {
-        const lang = detectLang(filePath);
-        if (lang === null) continue;
-
         let content: string;
         try {
-          content = ctx.fs.readFileSync(path.join(ctx.projectRoot, filePath), "utf-8");
+          content = await ctx.fs.readFile(path.join(ctx.projectRoot, filePath), "utf-8");
         } catch {
           continue;
         }
 
+        const actual = {
+          lines: content.split("\n").length,
+          bytes: Buffer.byteLength(content),
+        };
+        const refusal = evaluateMcpRefusal(ctx, filePath, actual);
+        if (refusal !== null) {
+          refused.push(refusal);
+          continue;
+        }
+
+        const lang = detectLang(filePath);
+        if (lang === null) continue;
+
         const result = extractOutline(content, lang);
-        const symbols: FileEntry["symbols"] = result.entries.map((entry) => {
-          const jump = result.jumpTable?.find((j) => j.symbol === entry.name);
-          return {
-            name: entry.name,
-            kind: entry.kind,
-            signature: entry.signature,
-            exported: entry.exported,
-            startLine: jump?.start,
-            endLine: jump?.end,
-          };
-        });
-
-        files.push({ path: filePath, lang, symbols });
+        const symbols = collectSymbols(result.entries, filePath, result.jumpTable ?? []).map((symbol) =>
+          new StructuralMapSymbol({
+            name: symbol.name,
+            kind: symbol.kind,
+            exported: symbol.exported,
+            ...(symbol.signature !== undefined ? { signature: symbol.signature } : {}),
+            ...(symbol.startLine !== undefined ? { startLine: symbol.startLine } : {}),
+            ...(symbol.endLine !== undefined ? { endLine: symbol.endLine } : {}),
+          })
+        );
+
+        files.push(new StructuralMapFile({ path: filePath, lang, symbols }));
       }
 
       files.sort((a, b) => a.path.localeCompare(b.path));
       const totalSymbols = files.reduce((n, f) => n + f.symbols.length, 0);
 
       return ctx.respond("graft_map", {
-        directory: dirPath.length > 0 ? dirPath : ".",
+        directory: request.directory,
         files,
+        ...(refused.length > 0 ? { refused } : {}),
         summary: `${String(files.length)} files, ${String(totalSymbols)} symbols`,
       });
     };

package/src/mcp/tools/monitor-pause.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const monitorPauseTool: ToolDefinition = {
+  name: "monitor_pause",
+  description:
+    "Pause the repo-scoped background index monitor for an authorized workspace.",
+  schema: {
+    cwd: z.string(),
+  },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      return ctx.respond("monitor_pause", { ...await ctx.pauseMonitor({
+        cwd: args["cwd"] as string,
+      }) });
+    };
+  },
+};

package/src/mcp/tools/monitor-resume.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const monitorResumeTool: ToolDefinition = {
+  name: "monitor_resume",
+  description:
+    "Resume a paused repo-scoped background index monitor for an authorized workspace.",
+  schema: {
+    cwd: z.string(),
+  },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      return ctx.respond("monitor_resume", { ...await ctx.resumeMonitor({
+        cwd: args["cwd"] as string,
+      }) });
+    };
+  },
+};

package/src/mcp/tools/monitor-start.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const monitorStartTool: ToolDefinition = {
+  name: "monitor_start",
+  description:
+    "Start or resume the repo-scoped background index monitor for an authorized workspace.",
+  schema: {
+    cwd: z.string(),
+    pollIntervalMs: z.number().int().positive().optional(),
+  },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      return ctx.respond("monitor_start", { ...await ctx.startMonitor({
+        cwd: args["cwd"] as string,
+        pollIntervalMs: args["pollIntervalMs"] as number | undefined,
+      }) });
+    };
+  },
+};

package/src/mcp/tools/monitor-stop.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const monitorStopTool: ToolDefinition = {
+  name: "monitor_stop",
+  description:
+    "Stop the repo-scoped background index monitor for an authorized workspace.",
+  schema: {
+    cwd: z.string(),
+  },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      return ctx.respond("monitor_stop", { ...await ctx.stopMonitor({
+        cwd: args["cwd"] as string,
+      }) });
+    };
+  },
+};

package/src/mcp/tools/precision-match.ts

@@ -0,0 +1,51 @@
+export class PrecisionSymbolMatch {
+  readonly name: string;
+  readonly kind: string;
+  readonly path: string;
+  readonly signature?: string;
+  readonly exported: boolean;
+  readonly startLine?: number;
+  readonly endLine?: number;
+
+  constructor(opts: {
+    name: string;
+    kind: string;
+    path: string;
+    signature?: string;
+    exported: boolean;
+    startLine?: number;
+    endLine?: number;
+  }) {
+    if (opts.name.trim().length === 0) {
+      throw new Error("PrecisionSymbolMatch: name must be non-empty");
+    }
+    if (opts.kind.trim().length === 0) {
+      throw new Error("PrecisionSymbolMatch: kind must be non-empty");
+    }
+    if (opts.path.trim().length === 0) {
+      throw new Error("PrecisionSymbolMatch: path must be non-empty");
+    }
+    if (opts.startLine !== undefined && (!Number.isInteger(opts.startLine) || opts.startLine < 1)) {
+      throw new Error("PrecisionSymbolMatch: startLine must be an integer >= 1");
+    }
+    if (opts.endLine !== undefined && (!Number.isInteger(opts.endLine) || opts.endLine < 1)) {
+      throw new Error("PrecisionSymbolMatch: endLine must be an integer >= 1");
+    }
+    if (
+      opts.startLine !== undefined &&
+      opts.endLine !== undefined &&
+      opts.endLine < opts.startLine
+    ) {
+      throw new Error("PrecisionSymbolMatch: endLine must be >= startLine");
+    }
+
+    this.name = opts.name.trim();
+    this.kind = opts.kind.trim();
+    this.path = opts.path.trim();
+    this.exported = opts.exported;
+    if (opts.signature !== undefined) this.signature = opts.signature;
+    if (opts.startLine !== undefined) this.startLine = opts.startLine;
+    if (opts.endLine !== undefined) this.endLine = opts.endLine;
+    Object.freeze(this);
+  }
+}

package/src/mcp/tools/precision-query.ts

@@ -0,0 +1,127 @@
+import picomatch from "picomatch";
+import { PrecisionSymbolMatch } from "./precision-match.js";
+
+type SymbolQueryMode = "glob" | "plain";
+
+export class RankedPrecisionSymbolMatch {
+  readonly match: PrecisionSymbolMatch;
+  readonly score: number;
+
+  constructor(opts: {
+    match: PrecisionSymbolMatch;
+    score: number;
+  }) {
+    if (opts.score < 0) {
+      throw new Error("RankedPrecisionSymbolMatch: score must be >= 0");
+    }
+    this.match = opts.match;
+    this.score = opts.score;
+    Object.freeze(this);
+  }
+}
+
+class PrecisionSymbolQuery {
+  readonly text: string;
+  readonly mode: SymbolQueryMode;
+  readonly #globMatcher?: (name: string) => boolean;
+
+  constructor(query: string) {
+    const normalizedQuery = query.trim();
+    if (normalizedQuery.length === 0) {
+      throw new Error("PrecisionSymbolQuery: query must be non-empty");
+    }
+    this.text = normalizedQuery;
+    if (picomatch.scan(normalizedQuery).isGlob) {
+      this.mode = "glob";
+      this.#globMatcher = picomatch(normalizedQuery, { nocase: true });
+    } else {
+      this.mode = "plain";
+    }
+    Object.freeze(this);
+  }
+
+  score(name: string): number | null {
+    if (this.mode === "glob") {
+      return this.#globMatcher?.(name) === true ? 0 : null;
+    }
+
+    const loweredName = name.toLowerCase();
+    const loweredQuery = this.text.toLowerCase();
+    if (name === this.text) return 0;
+    if (loweredName === loweredQuery) return 1;
+    if (name.startsWith(this.text)) return 2;
+    if (loweredName.startsWith(loweredQuery)) return 3;
+    return loweredName.includes(loweredQuery) ? 4 : null;
+  }
+}
+
+export class PrecisionSearchRequest {
+  readonly exactName?: string;
+  readonly query?: PrecisionSymbolQuery;
+  readonly kind?: string;
+  readonly filePath?: string;
+  readonly pathPrefix?: string;
+  readonly ceiling?: number;
+
+  constructor(opts: {
+    exactName?: string;
+    query?: string;
+    kind?: string;
+    filePath?: string;
+    pathPrefix?: string;
+    ceiling?: number;
+  }) {
+    const exactName = opts.exactName?.trim();
+    const query = opts.query?.trim();
+    const kind = opts.kind?.trim().toLowerCase();
+    const filePath = opts.filePath?.trim();
+    const pathPrefix = opts.pathPrefix?.trim();
+
+    if ((exactName?.length ?? 0) === 0 && (query?.length ?? 0) === 0) {
+      throw new Error("PrecisionSearchRequest: exactName or query is required");
+    }
+    if (
+      opts.ceiling !== undefined &&
+      (!Number.isInteger(opts.ceiling) || opts.ceiling < 1)
+    ) {
+      throw new Error("PrecisionSearchRequest: ceiling must be an integer >= 1");
+    }
+
+    if (exactName !== undefined && exactName.length > 0) this.exactName = exactName;
+    if (query !== undefined && query.length > 0) this.query = new PrecisionSymbolQuery(query);
+    if (kind !== undefined && kind.length > 0) this.kind = kind;
+    if (filePath !== undefined && filePath.length > 0) this.filePath = filePath;
+    if (pathPrefix !== undefined && pathPrefix.length > 0) this.pathPrefix = pathPrefix;
+    if (opts.ceiling !== undefined) this.ceiling = opts.ceiling;
+    Object.freeze(this);
+  }
+
+  selectLens(): "file" | "exact" | "all" {
+    if (this.filePath !== undefined) return "file";
+    if (this.exactName !== undefined) return "exact";
+    return "all";
+  }
+
+  rank(match: PrecisionSymbolMatch): RankedPrecisionSymbolMatch | null {
+    if (this.exactName !== undefined && match.name !== this.exactName) return null;
+    if (this.kind !== undefined && match.kind.toLowerCase() !== this.kind) return null;
+    if (this.filePath !== undefined && match.path !== this.filePath) return null;
+    if (this.pathPrefix !== undefined && !match.path.startsWith(this.pathPrefix)) return null;
+    if (this.query === undefined) {
+      return new RankedPrecisionSymbolMatch({ match, score: 0 });
+    }
+    const score = this.query.score(match.name);
+    return score === null ? null : new RankedPrecisionSymbolMatch({ match, score });
+  }
+
+  sort(matches: readonly RankedPrecisionSymbolMatch[]): PrecisionSymbolMatch[] {
+    return [...matches]
+      .sort((a, b) =>
+        a.score - b.score ||
+        (this.query?.mode === "plain" ? a.match.name.length - b.match.name.length : 0) ||
+        a.match.path.localeCompare(b.match.path) ||
+        a.match.name.localeCompare(b.match.name)
+      )
+      .map((entry) => entry.match);
+  }
+}