@flyingrobots/graft 0.6.1 → 0.7.0

package/src/mcp/tools/file-outline.ts

@@ -31,7 +31,7 @@ export const fileOutlineTool: ToolDefinition = {
       if (rawContent !== null && outlineSupported) {
         const cacheResult = ctx.cache.check(filePath, rawContent);
         if (cacheResult.hit) {
-          cacheResult.obs.touch();
+          cacheResult.obs.touch(ctx.cache.now());
           ctx.metrics.recordCacheHit(cacheResult.obs.actual.bytes);
           ctx.recordFootprint({
             symbols: cacheResult.obs.outline.map((e) => e.name),

package/src/mcp/tools/graft-edit.ts

@@ -0,0 +1,276 @@
+import { z } from "zod";
+import { evaluateMcpPolicy } from "../policy.js";
+import { RefusedResult } from "../../policy/types.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+type GraftEditReason =
+  | "NOT_FOUND"
+  | "OLD_STRING_NOT_FOUND"
+  | "OLD_STRING_AMBIGUOUS"
+  | RefusedResult["reason"];
+
+type DriftPattern = "jsdoc_typedef";
+type DriftDirection = "removed" | "added";
+
+interface GraftEditDriftObservation {
+  readonly pattern: DriftPattern;
+  readonly path: string;
+  readonly direction: DriftDirection;
+}
+
+interface GraftEditDriftWarning {
+  readonly kind: "structural_pattern_reintroduced";
+  readonly severity: "advisory";
+  readonly pattern: DriftPattern;
+  readonly basis: "session_local_graft_edit";
+  readonly message: string;
+  readonly current: {
+    readonly path: string;
+    readonly direction: "added";
+  };
+  readonly previous: {
+    readonly path: string;
+    readonly direction: "removed";
+  };
+}
+
+interface GraftEditResponse {
+  readonly path: string;
+  readonly operation: "replace";
+  readonly projection: "edited" | "refused";
+  readonly status: "edited" | "refused";
+  readonly changed: boolean;
+  readonly matches: number;
+  readonly replacements: number;
+  readonly reason?: GraftEditReason;
+  readonly reasonDetail?: string;
+  readonly next?: readonly string[];
+  readonly actual?: {
+    readonly lines: number;
+    readonly bytes: number;
+  };
+  readonly driftWarnings?: readonly GraftEditDriftWarning[];
+}
+
+function countOccurrences(content: string, needle: string): number {
+  if (needle.length === 0) {
+    return content.length + 1;
+  }
+
+  let count = 0;
+  let offset = 0;
+  while (offset <= content.length) {
+    const index = content.indexOf(needle, offset);
+    if (index === -1) {
+      return count;
+    }
+    count += 1;
+    offset = index + needle.length;
+  }
+  return count;
+}
+
+async function actualForFile(
+  content: string,
+  stat: () => Promise<{ size: number }>,
+): Promise<{ lines: number; bytes: number }> {
+  const fileStat = await stat();
+  return {
+    lines: content.split("\n").length,
+    bytes: fileStat.size,
+  };
+}
+
+function refused(input: {
+  readonly path: string;
+  readonly reason: GraftEditReason;
+  readonly reasonDetail?: string;
+  readonly next?: readonly string[];
+  readonly actual?: { readonly lines: number; readonly bytes: number };
+  readonly matches?: number;
+}): GraftEditResponse {
+  return {
+    path: input.path,
+    operation: "replace",
+    projection: "refused",
+    status: "refused",
+    changed: false,
+    matches: input.matches ?? 0,
+    replacements: 0,
+    reason: input.reason,
+    ...(input.reasonDetail !== undefined ? { reasonDetail: input.reasonDetail } : {}),
+    ...(input.next !== undefined ? { next: [...input.next] } : {}),
+    ...(input.actual !== undefined ? { actual: input.actual } : {}),
+  };
+}
+
+function containsJsdocTypedef(content: string): boolean {
+  return content
+    .split(/\r?\n/u)
+    .some((line) => line.trimStart().startsWith("* @typedef "));
+}
+
+function classifyStructuralEdit(input: {
+  readonly path: string;
+  readonly oldString: string;
+  readonly newString: string;
+}): GraftEditDriftObservation | null {
+  const oldHasTypedef = containsJsdocTypedef(input.oldString);
+  const newHasTypedef = containsJsdocTypedef(input.newString);
+  if (oldHasTypedef === newHasTypedef) {
+    return null;
+  }
+  return {
+    path: input.path,
+    pattern: "jsdoc_typedef",
+    direction: oldHasTypedef ? "removed" : "added",
+  };
+}
+
+function buildDriftWarnings(
+  observation: GraftEditDriftObservation | null,
+  priorObservations: readonly GraftEditDriftObservation[],
+): GraftEditDriftWarning[] {
+  if (observation?.direction !== "added") {
+    return [];
+  }
+
+  let previous: GraftEditDriftObservation | undefined;
+  for (let i = priorObservations.length - 1; i >= 0; i--) {
+    const candidate = priorObservations[i];
+    if (candidate?.pattern === observation.pattern && candidate.direction === "removed") {
+      previous = candidate;
+      break;
+    }
+  }
+  if (previous === undefined) {
+    return [];
+  }
+
+  return [{
+    kind: "structural_pattern_reintroduced",
+    severity: "advisory",
+    pattern: observation.pattern,
+    basis: "session_local_graft_edit",
+    message: "You are adding a typedef in a session that has been removing typedefs.",
+    current: {
+      path: observation.path,
+      direction: "added",
+    },
+    previous: {
+      path: previous.path,
+      direction: "removed",
+    },
+  }];
+}
+
+export const graftEditTool: ToolDefinition = {
+  name: "graft_edit",
+  description:
+    "Perform one governed exact string replacement in a repo file. " +
+    "Requires path, old_string, and new_string. Refuses missing or " +
+    "ambiguous old_string matches and policy-denied paths.",
+  schema: {
+    path: z.string(),
+    old_string: z.string(),
+    new_string: z.string(),
+  },
+  createHandler(): ToolHandler {
+    const structuralEditObservations: GraftEditDriftObservation[] = [];
+
+    return async (args, ctx) => {
+      const filePath = ctx.resolvePath(args["path"] as string);
+      const oldString = args["old_string"] as string;
+      const newString = args["new_string"] as string;
+      ctx.recordFootprint({ paths: [filePath] });
+
+      let content: string;
+      try {
+        content = await ctx.fs.readFile(filePath, "utf-8");
+      } catch {
+        ctx.metrics.recordRefusal();
+        return ctx.respond("graft_edit", {
+          ...refused({
+            path: filePath,
+            reason: "NOT_FOUND",
+            reasonDetail: "File does not exist or cannot be read",
+            next: ["Choose an existing file; graft_edit does not create files"],
+          }),
+        });
+      }
+
+      const actual = await actualForFile(content, () => ctx.fs.stat(filePath));
+      const policy = evaluateMcpPolicy(ctx, filePath, actual);
+      if (policy instanceof RefusedResult) {
+        ctx.metrics.recordRefusal();
+        return ctx.respond("graft_edit", {
+          ...refused({
+            path: filePath,
+            reason: policy.reason,
+            reasonDetail: policy.reasonDetail,
+            next: policy.next,
+            actual,
+          }),
+        });
+      }
+
+      const matches = countOccurrences(content, oldString);
+      if (matches === 0) {
+        ctx.metrics.recordRefusal();
+        return ctx.respond("graft_edit", {
+          ...refused({
+            path: filePath,
+            reason: "OLD_STRING_NOT_FOUND",
+            reasonDetail: "old_string does not occur in the target file",
+            next: ["Inspect the current file content and provide an exact old_string"],
+            actual,
+            matches,
+          }),
+        });
+      }
+
+      if (matches !== 1) {
+        ctx.metrics.recordRefusal();
+        return ctx.respond("graft_edit", {
+          ...refused({
+            path: filePath,
+            reason: "OLD_STRING_AMBIGUOUS",
+            reasonDetail: "old_string must occur exactly once",
+            next: ["Provide a longer old_string that uniquely identifies the edit site"],
+            actual,
+            matches,
+          }),
+        });
+      }
+
+      const nextContent = content.replace(oldString, newString);
+      const changed = nextContent !== content;
+      if (changed) {
+        await ctx.fs.writeFile(filePath, nextContent, "utf-8");
+      }
+
+      const observation = classifyStructuralEdit({
+        path: filePath,
+        oldString,
+        newString,
+      });
+      const driftWarnings = buildDriftWarnings(observation, structuralEditObservations);
+      if (observation !== null) {
+        structuralEditObservations.push(observation);
+      }
+
+      const response: GraftEditResponse = {
+        path: filePath,
+        operation: "replace",
+        projection: "edited",
+        status: "edited",
+        changed,
+        matches,
+        replacements: 1,
+        actual,
+        ...(driftWarnings.length > 0 ? { driftWarnings } : {}),
+      };
+      return ctx.respond("graft_edit", { ...response });
+    };
+  },
+};

package/src/mcp/tools/knowledge-map.ts

@@ -0,0 +1,34 @@
+import { buildKnowledgeMap } from "../../operations/knowledge-map.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const knowledgeMapTool: ToolDefinition = {
+  name: "knowledge_map",
+  description:
+    "Session knowledge map — answers \"what do I already know?\" " +
+    "Lists all files and symbols observed this session, flags stale " +
+    "files (changed since last read), and shows directory coverage. " +
+    "Use before reading more files to avoid redundant context consumption.",
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
+      const result = await buildKnowledgeMap({
+        cache: ctx.cache,
+        fs: ctx.fs,
+        projectRoot: ctx.projectRoot,
+      });
+
+      return ctx.respond("knowledge_map", {
+        totalFiles: result.totalFiles,
+        totalSymbols: result.totalSymbols,
+        files: result.files.map((f) => ({
+          path: f.path,
+          symbols: [...f.symbols],
+          readCount: f.readCount,
+          lastReadAt: f.lastReadAt,
+          stale: f.stale,
+        })),
+        staleFiles: [...result.staleFiles],
+        directoryCoverage: result.directoryCoverage,
+      });
+    };
+  },
+};

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

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const monitorNudgeTool: ToolDefinition = {
+  name: "monitor_nudge",
+  description:
+    "Trigger an immediate re-index tick for a running monitor. " +
+    "Use from post-commit hooks to notify graft that HEAD changed.",
+  schema: {
+    cwd: z.string(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      return ctx.respond("monitor_nudge", { ...await ctx.nudgeMonitor({
+        cwd: args["cwd"] as string,
+      }) });
+    };
+  },
+};

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

@@ -1,4 +1,6 @@
-import type { WarpHandle } from "../../ports/warp.js";
+import type { QueryResultV1 } from "@git-stunts/git-warp";
+import type { WarpContext } from "../../warp/context.js";
+import { observeGraph } from "../../warp/context.js";
 import { allSymbolsLens, commitsLens, fileSymbolsLens, symbolByNameLens } from "../../warp/observers.js";
 import type { RankedPrecisionSymbolMatch } from "./precision-query.js";
 import { PrecisionSearchRequest } from "./precision-query.js";
@@ -34,15 +36,20 @@ function toMatch(
   });
 }
 
-export async function getIndexedCommitCeilings(warp: WarpHandle): Promise<ReadonlyMap<string, number>> {
+export async function getIndexedCommitCeilings(ctx: WarpContext): Promise<ReadonlyMap<string, number>> {
   const ceilings = new Map<string, number>();
-  const observer = await warp.observer(commitsLens());
-  const nodeIds = await observer.getNodes();
+  const observer = await observeGraph(ctx, commitsLens());
 
-  for (const nodeId of nodeIds) {
-    const props = await observer.getNodeProps(nodeId);
-    const sha = typeof props?.["sha"] === "string" ? props["sha"] : null;
-    const tick = typeof props?.["tick"] === "number" ? props["tick"] : null;
+  // Slice-first: use query API instead of getNodes() + per-node getNodeProps()
+  const result = await observer.query()
+    .match("commit:*")
+    .select(["id", "props"])
+    .run() as QueryResultV1;
+
+  for (const node of result.nodes) {
+    const props = node.props ?? {};
+    const sha = typeof props["sha"] === "string" ? props["sha"] : null;
+    const tick = typeof props["tick"] === "number" ? props["tick"] : null;
     if (sha !== null && tick !== null) {
       ceilings.set(sha, tick);
     }
@@ -52,7 +59,7 @@ export async function getIndexedCommitCeilings(warp: WarpHandle): Promise<Readon
 }
 
 export async function searchWarpSymbols(
-  warp: WarpHandle,
+  ctx: WarpContext,
   request: PrecisionSearchRequest,
 ): Promise<PrecisionSymbolMatch[]> {
   const lensMode = request.selectLens();
@@ -71,19 +78,23 @@ export async function searchWarpSymbols(
     lens = allSymbolsLens();
   }
 
-  const observer = await warp.observer(
+  const observer = await observeGraph(ctx, 
     lens,
     request.ceiling !== undefined ? { source: { kind: "live", ceiling: request.ceiling } } : undefined,
   );
-  const nodeIds = await observer.getNodes();
+  // Slice-first: use query API instead of getNodes() + per-node getNodeProps()
+  const queryResult = await observer.query()
+    .match("*")
+    .select(["id", "props"])
+    .run() as QueryResultV1;
 
-  const matches = await Promise.all(nodeIds.map(async (nodeId) => {
-    const props = await observer.getNodeProps(nodeId);
-    if (props === null) return null;
-    const match = toMatch(nodeId, props);
+  const matches = queryResult.nodes.map((node) => {
+    const props = node.props ?? {};
+    if (node.id === undefined) return null;
+    const match = toMatch(node.id, props);
     if (match === null) return null;
     return request.rank(match);
-  }));
+  });
 
   const visibleMatches = matches.filter((match): match is RankedPrecisionSymbolMatch => match !== null);
   return request.sort(visibleMatches);

package/src/mcp/tools/refactor-difficulty.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { toJsonObject } from "../../operations/result-dto.js";
+import { refactorDifficultyFromGraph } from "../../warp/refactor-difficulty.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const refactorDifficultyTool: ToolDefinition = {
+  name: "graft_difficulty",
+  description:
+    "Refactor difficulty score for a symbol. Combines WARP aggregate " +
+    "churn curvature with WARP reference-edge friction so agents can " +
+    "choose refactor vs workaround.",
+  schema: {
+    symbol: z.string(),
+    path: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const symbol = args["symbol"];
+      const rawPath = args["path"];
+      const rawLimit = args["limit"];
+
+      if (typeof symbol !== "string" || symbol.trim().length === 0) {
+        throw new Error("graft_difficulty: symbol must be a non-empty string");
+      }
+
+      const warp = await ctx.getWarp();
+      const result = await refactorDifficultyFromGraph(warp, {
+        symbol,
+        ...(typeof rawPath === "string" ? { path: rawPath } : {}),
+        ...(typeof rawLimit === "number" ? { limit: rawLimit } : {}),
+      });
+
+      ctx.recordFootprint({
+        symbols: [symbol.trim()],
+        paths: result.entries.map((entry) => entry.filePath),
+      });
+
+      return ctx.respond("graft_difficulty", toJsonObject(result));
+    };
+  },
+};

package/src/mcp/tools/safe-read.ts

@@ -58,7 +58,7 @@ export const safeReadTool: ToolDefinition = {
             });
           }
 
-          cacheResult.obs.touch();
+          cacheResult.obs.touch(ctx.cache.now());
           ctx.metrics.recordCacheHit(cf.actual.bytes);
           ctx.recordFootprint({
             symbols: cacheResult.obs.outline.map((e) => e.name),
@@ -108,7 +108,7 @@ export const safeReadTool: ToolDefinition = {
             jumpTable: cf.jumpTable,
             actual: cf.actual,
             readCount: newReadCount,
-            lastReadAt: updatedObs?.lastReadAt ?? new Date().toISOString(),
+            lastReadAt: updatedObs?.lastReadAt ?? ctx.cache.now(),
           });
         }
       }

package/src/mcp/tools/structural-blame.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { structuralBlameFromGraph } from "../../warp/warp-structural-blame.js";
+import { toJsonObject } from "../../operations/result-dto.js";
+
+export const structuralBlameTool: ToolDefinition = {
+  name: "graft_blame",
+  description:
+    "Symbol-level blame: who last changed a symbol's signature, when " +
+    "it was created, and its full change history. Returns creation " +
+    "commit, last signature change, change count, reference count, " +
+    "and chronological history.",
+  schema: {
+    symbol: z.string(),
+    path: z.string().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const symbol = args["symbol"];
+      const rawPath = args["path"];
+
+      if (typeof symbol !== "string" || symbol.trim().length === 0) {
+        throw new Error("graft_blame: symbol must be a non-empty string");
+      }
+
+      const symbolName = symbol.trim();
+      const filePath = typeof rawPath === "string" ? rawPath : undefined;
+      const warp = await ctx.getWarp();
+
+      const blame = await structuralBlameFromGraph(
+        warp,
+        symbolName,
+        filePath ?? "",
+      );
+
+      ctx.recordFootprint({ symbols: [symbolName] });
+
+      return ctx.respond("graft_blame", toJsonObject({
+        symbol: blame.symbol,
+        filePath: blame.filePath,
+        changeCount: blame.changeCount,
+        createdInCommit: blame.createdInCommit ?? null,
+        lastSignatureChange: blame.lastSignatureChange ?? null,
+        referenceCount: blame.referenceCount,
+        history: blame.history.map((v) => ({
+          sha: v.sha,
+          tick: v.tick,
+          changeKind: v.changeKind,
+          present: v.present,
+          signature: v.signature ?? null,
+        })),
+      }));
+    };
+  },
+};

package/src/mcp/tools/structural-churn.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { toJsonObject } from "../../operations/result-dto.js";
+import { structuralChurnFromGraph } from "../../warp/warp-structural-churn.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const structuralChurnTool: ToolDefinition = {
+  name: "graft_churn",
+  description:
+    "Structural churn report — which symbols change most frequently? " +
+    "Identifies maintenance hotspots by walking indexed commits and " +
+    "counting per-symbol change frequency.",
+  schema: {
+    path: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const warp = await ctx.getWarp();
+      const options: { path?: string; limit?: number } = {};
+      const pathArg = args["path"];
+      const limitArg = args["limit"];
+      if (typeof pathArg === "string") options.path = pathArg;
+      if (typeof limitArg === "number") options.limit = limitArg;
+      const result = await structuralChurnFromGraph(warp, options);
+      return ctx.respond("graft_churn", toJsonObject(result));
+    };
+  },
+};

package/src/mcp/tools/structural-log.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { structuralLogFromGraph } from "../../warp/warp-structural-log.js";
+import { toJsonObject } from "../../operations/result-dto.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+
+export const structuralLogTool: ToolDefinition = {
+  name: "graft_log",
+  description:
+    "Structural git log — shows symbol-level changes (added, removed, " +
+    "changed) per commit. Like `git log` but for code structure, not lines.",
+  schema: {
+    path: z.string().optional(),
+    limit: z.number().optional(),
+  },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const filePath = args["path"] as string | undefined;
+      const limit = args["limit"] as number | undefined;
+      const warp = await ctx.getWarp();
+
+      const options: { path?: string; limit?: number } = {};
+      if (filePath !== undefined) options.path = filePath;
+      if (limit !== undefined) options.limit = limit;
+      const entries = await structuralLogFromGraph(warp, options);
+
+      ctx.recordFootprint({
+        symbols: entries.flatMap((e) => [
+          ...e.symbols.added.map((s) => s.name),
+          ...e.symbols.removed.map((s) => s.name),
+          ...e.symbols.changed.map((s) => s.name),
+        ]),
+      });
+
+      return ctx.respond("graft_log", toJsonObject({
+        entries,
+        count: entries.length,
+        layer: "commit_worldline",
+      }));
+    };
+  },
+};

package/src/mcp/tools/structural-review.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { structuralReview, type ReferenceCountResult } from "../../operations/structural-review.js";
+import { toJsonObject } from "../../operations/result-dto.js";
+import type { ToolContext, ToolDefinition, ToolHandler } from "../context.js";
+import { countSymbolReferencesFromGraph } from "../../warp/warp-reference-count.js";
+import { nodePathOps } from "../../adapters/node-paths.js";
+import { countNamedImportReferencesAtRef } from "../../operations/import-reference-impact.js";
+
+async function countReviewReferences(
+  ctx: ToolContext,
+  symbolName: string,
+  filePath: string,
+  headRef: string,
+): Promise<ReferenceCountResult> {
+  const warpCtx = await ctx.getWarp();
+  const graphResult = await countSymbolReferencesFromGraph(warpCtx, symbolName, filePath);
+  if (graphResult.referenceCount > 0) {
+    return graphResult;
+  }
+
+  try {
+    const fallbackResult = await countNamedImportReferencesAtRef({
+      cwd: ctx.projectRoot,
+      git: ctx.git,
+      pathOps: nodePathOps,
+      symbolName,
+      filePath,
+      ref: headRef,
+    });
+    return fallbackResult.referenceCount > 0 ? fallbackResult : graphResult;
+  } catch {
+    return graphResult;
+  }
+}
+
+export const structuralReviewTool: ToolDefinition = {
+  name: "graft_review",
+  description:
+    "Zero-noise structural PR review. Categorizes changed files as " +
+    "structural, formatting, test, docs, or config. Detects breaking " +
+    "changes (removed exports, changed signatures) with impact counts.",
+  schema: { base: z.string().optional(), head: z.string().optional() },
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
+      const head = args["head"] as string | undefined;
+      const result = await structuralReview({
+        cwd: ctx.projectRoot,
+        fs: ctx.fs,
+        git: ctx.git,
+        resolveWorkingTreePath: (filePath) => ctx.resolvePath(filePath),
+        base: args["base"] as string | undefined,
+        head,
+        countReferences: async (symbolName, filePath) => {
+          return countReviewReferences(ctx, symbolName, filePath, head ?? "HEAD");
+        },
+      });
+      ctx.recordFootprint({
+        paths: result.files.map((f) => f.path),
+      });
+      return ctx.respond("graft_review", toJsonObject(result));
+    };
+  },
+};