@flyingrobots/graft 0.6.0 → 0.7.0

package/src/operations/cross-session-resume.ts

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// Cross-session resume — structural diff from saved HEAD to current HEAD
+// ---------------------------------------------------------------------------
+
+import type { GitClient } from "../ports/git.js";
+
+/** A file that changed between saved HEAD and current HEAD. */
+export interface ResumeChangedFile {
+  readonly path: string;
+  readonly status: "added" | "modified" | "deleted" | "renamed";
+}
+
+/** Result of attempting to resume from a saved session state. */
+export interface SessionResumeResult {
+  readonly resumable: boolean;
+  readonly currentHead: string;
+  readonly savedHead: string;
+  readonly changedFiles: readonly ResumeChangedFile[];
+  readonly commitsBehind: number;
+  readonly error?: string;
+}
+
+export interface SessionResumeOptions {
+  readonly cwd: string;
+  readonly savedHeadSha: string;
+  readonly git: GitClient;
+}
+
+/**
+ * Build a structural resume from a saved HEAD to current HEAD.
+ *
+ * Uses plumbing-safe git commands (diff-tree, rev-list, log) to
+ * find changed files and count commits between two points.
+ */
+export async function buildSessionResume(
+  options: SessionResumeOptions,
+): Promise<SessionResumeResult> {
+  const { cwd, savedHeadSha, git } = options;
+
+  const headResult = await git.run({ cwd, args: ["rev-parse", "HEAD"] });
+  const currentHead = headResult.stdout.trim();
+  if (headResult.status !== 0 || currentHead.length === 0) {
+    return {
+      resumable: false, currentHead: "", savedHead: savedHeadSha,
+      changedFiles: [], commitsBehind: 0,
+      error: "Cannot resolve current HEAD",
+    };
+  }
+
+  // Check if saved HEAD exists in the repo
+  const verifyResult = await git.run({ cwd, args: ["cat-file", "-t", savedHeadSha] });
+  if (verifyResult.stdout.trim() !== "commit") {
+    return {
+      resumable: false, currentHead, savedHead: savedHeadSha,
+      changedFiles: [], commitsBehind: 0,
+      error: "Saved HEAD SHA not found in repository",
+    };
+  }
+
+  if (currentHead === savedHeadSha) {
+    return {
+      resumable: true, currentHead, savedHead: savedHeadSha,
+      changedFiles: [], commitsBehind: 0,
+    };
+  }
+
+  // Use diff-tree (plumbing-safe) with -r for recursive
+  const diffResult = await git.run({
+    cwd,
+    args: ["diff-tree", "-r", "--name-status", "--no-commit-id", savedHeadSha, currentHead],
+  });
+  const changedFiles: ResumeChangedFile[] = [];
+  const diffOutput = diffResult.stdout.trim();
+
+  if (diffOutput.length > 0) {
+    for (const line of diffOutput.split("\n")) {
+      const parts = line.split("\t");
+      if (parts.length < 2) continue;
+      const statusChar = (parts[0] ?? "").charAt(0);
+      const filePath = parts[parts.length - 1] ?? "";
+
+      let status: ResumeChangedFile["status"];
+      switch (statusChar) {
+        case "A": status = "added"; break;
+        case "D": status = "deleted"; break;
+        case "R": status = "renamed"; break;
+        default: status = "modified"; break;
+      }
+      changedFiles.push({ path: filePath, status });
+    }
+  }
+
+  // Count commits
+  const countResult = await git.run({
+    cwd,
+    args: ["rev-list", "--count", `${savedHeadSha}..${currentHead}`],
+  });
+  const commitsBehind = parseInt(countResult.stdout.trim(), 10) || 0;
+
+  return {
+    resumable: true, currentHead, savedHead: savedHeadSha,
+    changedFiles, commitsBehind,
+  };
+}

package/src/operations/deterministic-replay.ts

@@ -0,0 +1,143 @@
+// ---------------------------------------------------------------------------
+// Deterministic Scenario Replay — re-drive sessions for CI regression
+// ---------------------------------------------------------------------------
+
+import type { FileSystem } from "../ports/filesystem.js";
+
+/** A recorded tool call with its expected result. */
+export interface RecordedToolCall {
+  readonly tool: string;
+  readonly args: Readonly<Record<string, unknown>>;
+  readonly expectedResult: Readonly<Record<string, unknown>>;
+}
+
+/** A replay scenario: filesystem snapshot + recorded calls. */
+interface _ReplayScenario {
+  readonly files: Readonly<Record<string, string>>;
+  readonly calls: readonly RecordedToolCall[];
+}
+
+/** A single mismatch between expected and actual. */
+export interface ReplayFailure {
+  readonly index: number;
+  readonly tool: string;
+  readonly expected: Readonly<Record<string, unknown>>;
+  readonly actual: Readonly<Record<string, unknown>>;
+}
+
+/** Result of replaying a scenario. */
+export interface ReplayResult {
+  readonly passed: boolean;
+  readonly total: number;
+  readonly matched: number;
+  readonly mismatched: number;
+  readonly failures: readonly ReplayFailure[];
+}
+
+/** Handler that executes a tool call and returns the result. */
+export type ToolCallHandler = (
+  tool: string,
+  args: Readonly<Record<string, unknown>>,
+) => Promise<Readonly<Record<string, unknown>>>;
+
+/**
+ * Create a mock FileSystem from a snapshot map.
+ *
+ * Keys are file paths, values are file contents. Provides readFile,
+ * readdir, stat, and other FileSystem methods backed by the map.
+ */
+export function createSnapshotFs(
+  files: Readonly<Record<string, string>>,
+): FileSystem {
+  const fileMap = new Map(Object.entries(files));
+
+  return {
+    readFile(path: string, _encoding?: string): Promise<string> {
+      const content = fileMap.get(path);
+      if (content === undefined) {
+        return Promise.reject(new Error(`File not found in snapshot: ${path}`));
+      }
+      return Promise.resolve(content);
+    },
+
+    readFileSync(path: string): string {
+      const content = fileMap.get(path);
+      if (content === undefined) {
+        throw new Error(`File not found in snapshot: ${path}`);
+      }
+      return content;
+    },
+
+    readdir(dirPath: string): Promise<string[]> {
+      const prefix = dirPath.endsWith("/") ? dirPath : `${dirPath}/`;
+      const entries = new Set<string>();
+      for (const key of fileMap.keys()) {
+        if (key.startsWith(prefix)) {
+          const rest = key.slice(prefix.length);
+          const firstSegment = rest.split("/")[0];
+          if (firstSegment !== undefined && firstSegment.length > 0) {
+            entries.add(firstSegment);
+          }
+        }
+      }
+      return Promise.resolve([...entries].sort());
+    },
+
+    writeFile(): Promise<void> {
+      return Promise.resolve();
+    },
+
+    appendFile(): Promise<void> {
+      return Promise.resolve();
+    },
+
+    mkdir(): Promise<void> {
+      return Promise.resolve();
+    },
+
+    stat(path: string): Promise<{ size: number }> {
+      const content = fileMap.get(path);
+      return Promise.resolve({ size: content?.length ?? 0 });
+    },
+  } as unknown as FileSystem;
+}
+
+/**
+ * Replay a sequence of recorded tool calls against a handler.
+ *
+ * Compares each actual result to the expected result from the
+ * recording. Returns pass/fail with details on mismatches.
+ */
+export async function replayToolCalls(
+  calls: readonly RecordedToolCall[],
+  handler: ToolCallHandler,
+): Promise<ReplayResult> {
+  const failures: ReplayFailure[] = [];
+  let matched = 0;
+
+  for (let i = 0; i < calls.length; i++) {
+    const call = calls[i] ?? { tool: "", args: {}, expectedResult: {} };
+    const actual = await handler(call.tool, call.args);
+    const expectedJson = JSON.stringify(call.expectedResult);
+    const actualJson = JSON.stringify(actual);
+
+    if (expectedJson === actualJson) {
+      matched++;
+    } else {
+      failures.push({
+        index: i,
+        tool: call.tool,
+        expected: call.expectedResult,
+        actual,
+      });
+    }
+  }
+
+  return {
+    passed: failures.length === 0,
+    total: calls.length,
+    matched,
+    mismatched: failures.length,
+    failures,
+  };
+}

package/src/operations/export-surface-diff.ts

@@ -0,0 +1,355 @@
+// ---------------------------------------------------------------------------
+// Export surface diff — what changed in the public API between two refs?
+// ---------------------------------------------------------------------------
+
+import type { GitClient } from "../ports/git.js";
+import { getChangedFiles, getFileAtRef } from "../git/diff.js";
+import { detectLang } from "../parser/lang.js";
+import { extractOutline } from "../parser/outline.js";
+import type { OutlineEntry } from "../parser/types.js";
+import { toJsonObject } from "./result-dto.js";
+import type { JsonObject } from "../contracts/json-object.js";
+
+// ---- Public types ---------------------------------------------------------
+
+export interface ExportChange {
+  readonly symbol: string;
+  readonly filePath: string;
+  readonly kind: string;
+  readonly changeType: "added" | "removed" | "signature_changed";
+  readonly signature?: string | undefined;
+  readonly previousSignature?: string | undefined;
+}
+
+export interface ExportSurfaceDiffResult {
+  readonly base: string;
+  readonly head: string;
+  readonly added: readonly ExportChange[];
+  readonly removed: readonly ExportChange[];
+  readonly changed: readonly ExportChange[];
+  readonly semverImpact: "major" | "minor" | "patch" | "none";
+  readonly summary: string;
+}
+
+export interface ExportSurfaceDiffOptions {
+  readonly cwd: string;
+  readonly git: GitClient;
+  readonly base?: string | undefined;
+  readonly head?: string | undefined;
+}
+
+type SemverImpact = ExportSurfaceDiffResult["semverImpact"];
+
+// ---- Internal helpers -----------------------------------------------------
+
+function exportKey(entry: OutlineEntry): string {
+  return `${entry.kind}:${entry.name}`;
+}
+
+function extractExportedEntries(
+  content: string | null,
+  filePath: string,
+): Map<string, OutlineEntry> {
+  if (content === null) return new Map();
+  const lang = detectLang(filePath);
+  if (lang === null) return new Map();
+  const outline = extractOutline(content, lang);
+  const result = new Map<string, OutlineEntry>();
+  for (const entry of outline.entries) {
+    if (entry.exported) {
+      result.set(exportKey(entry), entry);
+    }
+  }
+  return result;
+}
+
+interface ParsedParameter {
+  readonly type: string;
+  readonly required: boolean;
+}
+
+interface ParsedSignature {
+  readonly parameters: readonly ParsedParameter[];
+  readonly returnType: string;
+}
+
+function normalizeSignaturePart(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function findMatchingParen(signature: string, openIndex: number): number {
+  let depth = 0;
+  for (let index = openIndex; index < signature.length; index += 1) {
+    const char = signature[index];
+    if (char === "(") {
+      depth += 1;
+    } else if (char === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return -1;
+}
+
+function splitTopLevelCommaList(value: string): string[] {
+  const parts: string[] = [];
+  let start = 0;
+  let angle = 0;
+  let brace = 0;
+  let bracket = 0;
+  let paren = 0;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (char === "<") angle += 1;
+    else if (char === ">" && angle > 0) angle -= 1;
+    else if (char === "{") brace += 1;
+    else if (char === "}" && brace > 0) brace -= 1;
+    else if (char === "[") bracket += 1;
+    else if (char === "]" && bracket > 0) bracket -= 1;
+    else if (char === "(") paren += 1;
+    else if (char === ")" && paren > 0) paren -= 1;
+    else if (char === "," && angle === 0 && brace === 0 && bracket === 0 && paren === 0) {
+      const part = value.slice(start, index).trim();
+      if (part.length > 0) parts.push(part);
+      start = index + 1;
+    }
+  }
+
+  const tail = value.slice(start).trim();
+  if (tail.length > 0) parts.push(tail);
+  return parts;
+}
+
+function findTopLevelColon(value: string): number {
+  let angle = 0;
+  let brace = 0;
+  let bracket = 0;
+  let paren = 0;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (char === "<") angle += 1;
+    else if (char === ">" && angle > 0) angle -= 1;
+    else if (char === "{") brace += 1;
+    else if (char === "}" && brace > 0) brace -= 1;
+    else if (char === "[") bracket += 1;
+    else if (char === "]" && bracket > 0) bracket -= 1;
+    else if (char === "(") paren += 1;
+    else if (char === ")" && paren > 0) paren -= 1;
+    else if (char === ":" && angle === 0 && brace === 0 && bracket === 0 && paren === 0) {
+      return index;
+    }
+  }
+
+  return -1;
+}
+
+function findTopLevelEquals(value: string): number {
+  let angle = 0;
+  let brace = 0;
+  let bracket = 0;
+  let paren = 0;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (char === "<") angle += 1;
+    else if (char === ">" && angle > 0) angle -= 1;
+    else if (char === "{") brace += 1;
+    else if (char === "}" && brace > 0) brace -= 1;
+    else if (char === "[") bracket += 1;
+    else if (char === "]" && bracket > 0) bracket -= 1;
+    else if (char === "(") paren += 1;
+    else if (char === ")" && paren > 0) paren -= 1;
+    else if (char === "=" && angle === 0 && brace === 0 && bracket === 0 && paren === 0) {
+      return index;
+    }
+  }
+
+  return -1;
+}
+
+function parseParameter(rawParameter: string): ParsedParameter {
+  const equalsIndex = findTopLevelEquals(rawParameter);
+  const declaration = equalsIndex === -1 ? rawParameter : rawParameter.slice(0, equalsIndex);
+  const normalized = normalizeSignaturePart(declaration);
+  const required = !/^\s*\.\.\./.test(declaration)
+    && !/^[^:=]+?\?\s*:/.test(declaration)
+    && equalsIndex === -1;
+  const colonIndex = findTopLevelColon(declaration);
+  const type = colonIndex === -1
+    ? normalized
+    : normalizeSignaturePart(declaration.slice(colonIndex + 1));
+  return { type, required };
+}
+
+function parseSignature(signature: string | undefined): ParsedSignature | null {
+  if (signature === undefined) {
+    return null;
+  }
+
+  const openIndex = signature.indexOf("(");
+  if (openIndex === -1) {
+    return null;
+  }
+
+  const closeIndex = findMatchingParen(signature, openIndex);
+  if (closeIndex === -1) {
+    return null;
+  }
+
+  const parameterText = signature.slice(openIndex + 1, closeIndex).trim();
+  const parameters = parameterText.length === 0
+    ? []
+    : splitTopLevelCommaList(parameterText).map(parseParameter);
+  const trailing = signature.slice(closeIndex + 1).trim();
+  const returnType = trailing.startsWith(":")
+    ? normalizeSignaturePart(trailing.slice(1))
+    : "";
+
+  return { parameters, returnType };
+}
+
+function classifySignatureImpact(change: ExportChange): SemverImpact {
+  const previous = parseSignature(change.previousSignature);
+  const next = parseSignature(change.signature);
+  if (previous === null || next === null) {
+    return "major";
+  }
+
+  if (previous.returnType !== next.returnType) {
+    return "major";
+  }
+
+  for (let index = 0; index < previous.parameters.length; index += 1) {
+    const previousParam = previous.parameters[index];
+    const nextParam = next.parameters[index];
+    if (previousParam === undefined || nextParam === undefined) {
+      return "major";
+    }
+    if (previousParam.type !== nextParam.type) {
+      return "major";
+    }
+    if (!previousParam.required && nextParam.required) {
+      return "major";
+    }
+  }
+
+  const addedParameters = next.parameters.slice(previous.parameters.length);
+  if (addedParameters.some((parameter) => parameter.required)) {
+    return "major";
+  }
+  if (addedParameters.length > 0) {
+    return "minor";
+  }
+
+  return "patch";
+}
+
+function deriveSemverImpact(
+  added: readonly ExportChange[],
+  removed: readonly ExportChange[],
+  changed: readonly ExportChange[],
+): SemverImpact {
+  if (removed.length > 0) return "major";
+  if (changed.some((change) => classifySignatureImpact(change) === "major")) return "major";
+  if (added.length > 0) return "minor";
+  if (changed.some((change) => classifySignatureImpact(change) === "minor")) return "minor";
+  if (changed.length > 0) return "patch";
+  return "none";
+}
+
+function buildSummary(
+  added: readonly ExportChange[],
+  removed: readonly ExportChange[],
+  changed: readonly ExportChange[],
+  semverImpact: string,
+): string {
+  const total = added.length + removed.length + changed.length;
+  if (total === 0) return "No exported API changes.";
+  const parts: string[] = [];
+  if (added.length > 0) parts.push(`+${String(added.length)} added`);
+  if (removed.length > 0) parts.push(`-${String(removed.length)} removed`);
+  if (changed.length > 0) parts.push(`~${String(changed.length)} changed`);
+  return `${parts.join(", ")} exported symbols. Semver impact: ${semverImpact}.`;
+}
+
+// ---- Public API -----------------------------------------------------------
+
+/**
+ * Compute the export surface diff between two git refs.
+ *
+ * Extracts outlines at both refs, filters to exported symbols, and
+ * classifies additions, removals, and signature changes. Derives
+ * the semver impact from the change set.
+ */
+export async function exportSurfaceDiff(
+  opts: ExportSurfaceDiffOptions,
+): Promise<ExportSurfaceDiffResult> {
+  const { cwd, git } = opts;
+  const base = opts.base ?? "HEAD~1";
+  const head = opts.head ?? "HEAD";
+
+  const changedFiles = await getChangedFiles({ cwd, git, base, head });
+
+  const added: ExportChange[] = [];
+  const removed: ExportChange[] = [];
+  const changed: ExportChange[] = [];
+
+  for (const filePath of changedFiles) {
+    const baseContent = await getFileAtRef(base, filePath, { cwd, git });
+
+    const headContent = await getFileAtRef(head, filePath, { cwd, git });
+
+    const baseExports = extractExportedEntries(baseContent, filePath);
+    const headExports = extractExportedEntries(headContent, filePath);
+
+    // Detect added and changed exports
+    for (const [key, headEntry] of headExports) {
+      const baseEntry = baseExports.get(key);
+      if (baseEntry === undefined) {
+        added.push({
+          symbol: headEntry.name,
+          filePath,
+          kind: headEntry.kind,
+          changeType: "added",
+          signature: headEntry.signature,
+        });
+      } else if (headEntry.signature !== baseEntry.signature) {
+        changed.push({
+          symbol: headEntry.name,
+          filePath,
+          kind: headEntry.kind,
+          changeType: "signature_changed",
+          signature: headEntry.signature,
+          previousSignature: baseEntry.signature,
+        });
+      }
+    }
+
+    // Detect removed exports
+    for (const [key, baseEntry] of baseExports) {
+      if (!headExports.has(key)) {
+        removed.push({
+          symbol: baseEntry.name,
+          filePath,
+          kind: baseEntry.kind,
+          changeType: "removed",
+          signature: baseEntry.signature,
+        });
+      }
+    }
+  }
+
+  const semverImpact = deriveSemverImpact(added, removed, changed);
+  const summary = buildSummary(added, removed, changed, semverImpact);
+
+  return { base, head, added, removed, changed, semverImpact, summary };
+}
+
+/** Serialize an ExportSurfaceDiffResult for MCP / CLI output. */
+export function exportSurfaceDiffToJson(result: ExportSurfaceDiffResult): JsonObject {
+  return toJsonObject(result);
+}

package/src/operations/footprint-parallelism.ts

@@ -0,0 +1,98 @@
+// ---------------------------------------------------------------------------
+// Footprint Parallelism — discover concurrent-safe tool calls
+// ---------------------------------------------------------------------------
+
+/** The structural footprint of a tool call. */
+export interface ToolFootprint {
+  readonly tool: string;
+  readonly files: readonly string[];
+  readonly symbols: readonly string[];
+}
+
+/** Tools that have no structural footprint (diagnostics, status). */
+const ZERO_FOOTPRINT_TOOLS = new Set([
+  "daemon_status",
+  "daemon_monitors",
+  "causal_status",
+  "knowledge_map",
+]);
+
+/**
+ * Compute the structural footprint of a tool call.
+ *
+ * Files and symbols that the call reads or writes. Two calls with
+ * non-overlapping footprints can run concurrently.
+ */
+export function computeFootprint(
+  tool: string,
+  args: Readonly<Record<string, unknown>>,
+): ToolFootprint {
+  if (ZERO_FOOTPRINT_TOOLS.has(tool)) {
+    return { tool, files: [], symbols: [] };
+  }
+
+  const files: string[] = [];
+  const symbols: string[] = [];
+
+  // Extract path from common arg patterns
+  const pathArg = args["path"];
+  if (typeof pathArg === "string") {
+    files.push(pathArg);
+  }
+
+  // Extract symbol from common arg patterns
+  const symbolArg = args["symbol"] ?? args["name"];
+  if (typeof symbolArg === "string") {
+    symbols.push(symbolArg);
+  }
+
+  return { tool, files, symbols };
+}
+
+/**
+ * Check if two footprints overlap (share files or symbols).
+ */
+function overlaps(a: ToolFootprint, b: ToolFootprint): boolean {
+  for (const file of a.files) {
+    if (b.files.includes(file)) return true;
+  }
+  for (const sym of a.symbols) {
+    if (b.symbols.includes(sym)) return true;
+  }
+  return false;
+}
+
+/**
+ * Partition footprints into parallel groups.
+ *
+ * Each group contains footprints that can run concurrently (no
+ * overlaps within the group). Groups are ordered — group N+1
+ * runs after group N.
+ *
+ * Uses greedy graph coloring: for each footprint, place it in the
+ * first group that has no conflicts.
+ */
+export function findParallelGroups(
+  footprints: readonly ToolFootprint[],
+): ToolFootprint[][] {
+  if (footprints.length === 0) return [];
+
+  const groups: ToolFootprint[][] = [];
+
+  for (const fp of footprints) {
+    let placed = false;
+    for (const group of groups) {
+      const conflicts = group.some((existing) => overlaps(existing, fp));
+      if (!conflicts) {
+        group.push(fp);
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) {
+      groups.push([fp]);
+    }
+  }
+
+  return groups;
+}