@flyingrobots/graft 0.5.0 → 0.6.1

package/src/parser/outline.ts

@@ -1,27 +1,12 @@
-import Parser from "web-tree-sitter";
-import { createRequire } from "node:module";
 import { detectStructuredFormat } from "./lang.js";
 import type { SupportedStructuredFormat } from "./lang.js";
 import { OutlineEntry, JumpEntry } from "./types.js";
 import type { OutlineResult } from "./types.js";
+import { parseStructuredTree } from "./runtime.js";
+import { extractMarkdownOutline } from "./markdown.js";
 
 const MAX_SIGNATURE_LENGTH = 199;
 
-// ---------------------------------------------------------------------------
-// WASM initialisation (top-level await — ESM only)
-// ---------------------------------------------------------------------------
-
-const esmRequire = createRequire(import.meta.url);
-
-await Parser.init();
-
-const tsLang = await Parser.Language.load(
-  esmRequire.resolve("tree-sitter-wasms/out/tree-sitter-typescript.wasm"),
-);
-const jsLang = await Parser.Language.load(
-  esmRequire.resolve("tree-sitter-wasms/out/tree-sitter-javascript.wasm"),
-);
-
 // ---------------------------------------------------------------------------
 // Signature helpers
 // ---------------------------------------------------------------------------
@@ -44,27 +29,7 @@ function boundSignature(raw: string): string {
 // Tree-sitter node interface (avoids importing the Node class directly)
 // ---------------------------------------------------------------------------
 
-interface TSNode {
-  readonly type: string;
-  readonly text: string;
-  readonly startPosition: { readonly row: number; readonly column: number };
-  readonly endPosition: { readonly row: number; readonly column: number };
-  readonly children: TSNode[];
-  readonly namedChildren: TSNode[];
-  readonly hasError: boolean;
-  childForFieldName(name: string): TSNode | null;
-}
-
-interface MarkdownHeading {
-  level: number;
-  name: string;
-  start: number;
-  end: number;
-}
-
-interface MarkdownHeadingNode extends MarkdownHeading {
-  children: MarkdownHeadingNode[];
-}
+type TSNode = import("web-tree-sitter").SyntaxNode;
 
 // ---------------------------------------------------------------------------
 // Node kind mapping
@@ -93,7 +58,7 @@ function nodeKind(nodeType: string): EntryKind | undefined {
 }
 
 // ---------------------------------------------------------------------------
-// Extraction helpers
+// Tree-sitter extraction helpers
 // ---------------------------------------------------------------------------
 
 function extractFunctionSignature(node: TSNode): string | undefined {
@@ -223,166 +188,6 @@ function buildJumpEntry(
   });
 }
 
-function buildMarkdownJumpEntry(heading: MarkdownHeading): JumpEntry {
-  return new JumpEntry({
-    symbol: heading.name,
-    kind: "heading",
-    start: heading.start,
-    end: heading.end,
-  });
-}
-
-function isFenceLine(line: string): { marker: "`" | "~"; length: number } | null {
-  const match = /^\s*([`~])\1{2,}.*$/.exec(line);
-  if (match === null) return null;
-
-  const marker = match[1];
-  if (marker !== "`" && marker !== "~") return null;
-  const markerRun = /^([`~]+)/.exec(match[0].trimStart());
-  if (markerRun === null) return null;
-  const run = markerRun[1];
-  if (run === undefined) return null;
-  return { marker, length: run.length };
-}
-
-function isFenceClose(line: string, marker: "`" | "~", length: number): boolean {
-  const pattern = marker === "`"
-    ? new RegExp(`^\\s*\`{${String(length)},}\\s*$`)
-    : new RegExp(`^\\s*~{${String(length)},}\\s*$`);
-  return pattern.test(line);
-}
-
-function parseAtxHeading(line: string, lineNumber: number): MarkdownHeading | null {
-  const match = /^\s{0,3}(#{1,6})[ \t]+(.+?)\s*#*\s*$/.exec(line);
-  if (match === null) return null;
-
-  const hashes = match[1];
-  const rawName = match[2]?.trim() ?? "";
-  if (hashes === undefined || rawName.length === 0) return null;
-
-  return {
-    level: hashes.length,
-    name: rawName,
-    start: lineNumber,
-    end: lineNumber,
-  };
-}
-
-function parseSetextHeading(
-  currentLine: string,
-  nextLine: string | undefined,
-  lineNumber: number,
-): MarkdownHeading | null {
-  if (nextLine === undefined) return null;
-  if (currentLine.trim().length === 0) return null;
-  if (parseAtxHeading(currentLine, lineNumber) !== null) return null;
-
-  if (/^\s{0,3}=+\s*$/.test(nextLine)) {
-    return { level: 1, name: currentLine.trim(), start: lineNumber, end: lineNumber + 1 };
-  }
-  if (/^\s{0,3}-+\s*$/.test(nextLine)) {
-    return { level: 2, name: currentLine.trim(), start: lineNumber, end: lineNumber + 1 };
-  }
-
-  return null;
-}
-
-function finalizeMarkdownRanges(headings: MarkdownHeading[], totalLines: number): void {
-  for (let i = 0; i < headings.length; i++) {
-    const current = headings[i];
-    if (current === undefined) continue;
-    let end = totalLines;
-    for (let j = i + 1; j < headings.length; j++) {
-      const next = headings[j];
-      if (next === undefined) continue;
-      if (next.level <= current.level) {
-        end = next.start - 1;
-        break;
-      }
-    }
-    current.end = end;
-  }
-}
-
-function buildMarkdownHierarchy(headings: readonly MarkdownHeading[]): MarkdownHeadingNode[] {
-  const roots: MarkdownHeadingNode[] = [];
-  const stack: MarkdownHeadingNode[] = [];
-
-  for (const heading of headings) {
-    const node: MarkdownHeadingNode = { ...heading, children: [] };
-    while (stack.length > 0) {
-      const last = stack[stack.length - 1];
-      if (last === undefined || last.level < node.level) break;
-      stack.pop();
-    }
-    const parent = stack[stack.length - 1];
-    if (parent === undefined) roots.push(node);
-    else parent.children.push(node);
-    stack.push(node);
-  }
-
-  return roots;
-}
-
-function toOutlineEntry(node: MarkdownHeadingNode): OutlineEntry {
-  return new OutlineEntry({
-    kind: "heading",
-    name: node.name,
-    exported: false,
-    ...(node.children.length > 0
-      ? { children: node.children.map((child) => toOutlineEntry(child)) }
-      : {}),
-  });
-}
-
-function extractMarkdownOutline(source: string): OutlineResult {
-  const lines = source.split("\n");
-  const headings: MarkdownHeading[] = [];
-  let inFence = false;
-  let activeFence: { marker: "`" | "~"; length: number } | null = null;
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (line === undefined) continue;
-    const lineNumber = i + 1;
-    const fence = isFenceLine(line);
-
-    if (inFence) {
-      if (activeFence !== null && isFenceClose(line, activeFence.marker, activeFence.length)) {
-        inFence = false;
-        activeFence = null;
-      }
-      continue;
-    }
-
-    if (fence !== null) {
-      inFence = true;
-      activeFence = fence;
-      continue;
-    }
-
-    const atx = parseAtxHeading(line, lineNumber);
-    if (atx !== null) {
-      headings.push(atx);
-      continue;
-    }
-
-    const setext = parseSetextHeading(line, lines[i + 1], lineNumber);
-    if (setext !== null) {
-      headings.push(setext);
-      i++;
-    }
-  }
-
-  finalizeMarkdownRanges(headings, lines.length);
-  const hierarchy = buildMarkdownHierarchy(headings);
-
-  return {
-    entries: hierarchy.map((node) => toOutlineEntry(node)),
-    jumpTable: headings.map((heading) => buildMarkdownJumpEntry(heading)),
-  };
-}
-
 // ---------------------------------------------------------------------------
 // Main extraction
 // ---------------------------------------------------------------------------
@@ -401,16 +206,12 @@ export function extractOutline(
   if (lang === "md") {
     return extractMarkdownOutline(source);
   }
-
-  const parser = new Parser();
-  parser.setLanguage(lang === "ts" ? tsLang : jsLang);
-
-  const tree = parser.parse(source);
-  const root = tree.rootNode as unknown as TSNode;
+  const parsed = parseStructuredTree(lang, source);
+  const root = parsed.root;
 
   const entries: OutlineEntry[] = [];
   const jumpTable: JumpEntry[] = [];
-  const hasError = root.hasError;
+  const hasError = root.hasError();
 
   for (const child of root.children) {
     if (child.type === "export_statement") {
@@ -488,8 +289,7 @@ export function extractOutline(
     }
   }
 
-  parser.delete();
-  tree.delete();
+  parsed.delete();
 
   const result: OutlineResult = {
     entries,

package/src/parser/runtime.ts

@@ -0,0 +1,71 @@
+import Parser from "web-tree-sitter";
+import { createRequire } from "node:module";
+import { detectLang } from "./lang.js";
+import type { SupportedLang } from "./lang.js";
+
+const esmRequire = createRequire(import.meta.url);
+
+await Parser.init();
+
+const tsLang = await Parser.Language.load(
+  esmRequire.resolve("tree-sitter-wasms/out/tree-sitter-typescript.wasm"),
+);
+const tsxLang = await Parser.Language.load(
+  esmRequire.resolve("tree-sitter-wasms/out/tree-sitter-tsx.wasm"),
+);
+const jsLang = await Parser.Language.load(
+  esmRequire.resolve("tree-sitter-wasms/out/tree-sitter-javascript.wasm"),
+);
+
+function languageFor(format: SupportedLang): Parser.Language {
+  switch (format) {
+    case "ts":
+      return tsLang;
+    case "tsx":
+      return tsxLang;
+    case "js":
+      return jsLang;
+  }
+}
+
+export interface ParsedTree {
+  readonly format: SupportedLang;
+  readonly parser: Parser;
+  readonly tree: Parser.Tree;
+  readonly root: Parser.SyntaxNode;
+  readonly source: string;
+  delete(): void;
+}
+
+export function parseStructuredTree(
+  format: SupportedLang,
+  source: string,
+): ParsedTree {
+  const parser = new Parser();
+  parser.setLanguage(languageFor(format));
+  const tree = parser.parse(source);
+  const root = tree.rootNode;
+
+  return {
+    format,
+    parser,
+    tree,
+    root,
+    source,
+    delete() {
+      tree.delete();
+      parser.delete();
+    },
+  };
+}
+
+export function parseStructuredTreeForFile(
+  filePath: string,
+  source: string,
+): ParsedTree | null {
+  const format = detectLang(filePath);
+  if (format === null) {
+    return null;
+  }
+  return parseStructuredTree(format, source);
+}

package/src/policy/evaluate.ts

@@ -1,5 +1,5 @@
 import picomatch from "picomatch";
-import type { PolicyInput, PolicyOptions, ReasonCode, SessionDepth } from "./types.js";
+import type { PolicyInput, PolicyOptions, ReasonCode, GovernorDepth } from "./types.js";
 import { ContentResult, OutlineResult, RefusedResult } from "./types.js";
 import type { PolicyResult } from "./types.js";
 
@@ -97,7 +97,7 @@ export function evaluatePolicy(input: PolicyInput, options?: PolicyOptions): Pol
   const { path, lines, bytes } = input;
   const actual = { lines, bytes };
   const thresholds = { ...STATIC_THRESHOLDS };
-  const sessionDepth: SessionDepth | undefined = options?.sessionDepth;
+  const sessionDepth: GovernorDepth | undefined = options?.sessionDepth;
 
   // 1. Bans first
   const ban = checkBan(path);

package/src/policy/types.ts

@@ -11,7 +11,7 @@ export type ReasonCode =
   | "BUDGET_CAP"
   | "UNSUPPORTED_LANGUAGE";
 
-export type SessionDepth = "early" | "mid" | "late" | "unknown";
+export type GovernorDepth = "early" | "mid" | "late" | "unknown";
 
 export interface PolicyInput {
   path: string;
@@ -21,7 +21,7 @@ export interface PolicyInput {
 
 export interface PolicyOptions {
   graftignorePatterns?: string[] | undefined;
-  sessionDepth?: SessionDepth | undefined;
+  sessionDepth?: GovernorDepth | undefined;
   budgetRemaining?: number | undefined;
 }
 
@@ -29,7 +29,7 @@ export interface PolicyOptions {
 interface PolicyResultBase {
   readonly thresholds: { readonly lines: number; readonly bytes: number };
   readonly actual: { readonly lines: number; readonly bytes: number };
-  readonly sessionDepth?: SessionDepth | undefined;
+  readonly sessionDepth?: GovernorDepth | undefined;
 }
 
 export class ContentResult implements PolicyResultBase {
@@ -37,9 +37,9 @@ export class ContentResult implements PolicyResultBase {
   readonly reason = "CONTENT" as const;
   readonly thresholds: { readonly lines: number; readonly bytes: number };
   readonly actual: { readonly lines: number; readonly bytes: number };
-  readonly sessionDepth?: SessionDepth | undefined;
+  readonly sessionDepth?: GovernorDepth | undefined;
 
-  constructor(opts: { thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: SessionDepth | undefined }) {
+  constructor(opts: { thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: GovernorDepth | undefined }) {
     this.thresholds = Object.freeze({ ...opts.thresholds });
     this.actual = Object.freeze({ ...opts.actual });
     if (opts.sessionDepth !== undefined) this.sessionDepth = opts.sessionDepth;
@@ -52,9 +52,9 @@ export class OutlineResult implements PolicyResultBase {
   readonly reason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP" | "UNSUPPORTED_LANGUAGE";
   readonly thresholds: { readonly lines: number; readonly bytes: number };
   readonly actual: { readonly lines: number; readonly bytes: number };
-  readonly sessionDepth?: SessionDepth | undefined;
+  readonly sessionDepth?: GovernorDepth | undefined;
 
-  constructor(opts: { reason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP" | "UNSUPPORTED_LANGUAGE"; thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: SessionDepth | undefined }) {
+  constructor(opts: { reason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP" | "UNSUPPORTED_LANGUAGE"; thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: GovernorDepth | undefined }) {
     this.reason = opts.reason;
     this.thresholds = Object.freeze({ ...opts.thresholds });
     this.actual = Object.freeze({ ...opts.actual });
@@ -70,9 +70,9 @@ export class RefusedResult implements PolicyResultBase {
   readonly next: readonly string[];
   readonly thresholds: { readonly lines: number; readonly bytes: number };
   readonly actual: { readonly lines: number; readonly bytes: number };
-  readonly sessionDepth?: SessionDepth | undefined;
+  readonly sessionDepth?: GovernorDepth | undefined;
 
-  constructor(opts: { reason: ReasonCode; reasonDetail: string; next: string[]; thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: SessionDepth | undefined }) {
+  constructor(opts: { reason: ReasonCode; reasonDetail: string; next: string[]; thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: GovernorDepth | undefined }) {
     this.reason = opts.reason;
     this.reasonDetail = opts.reasonDetail;
     this.next = Object.freeze([...opts.next]);

package/src/ports/guards.ts

@@ -0,0 +1,68 @@
+// ---------------------------------------------------------------------------
+// Port runtime guards — construction-time validation for port adapters
+// ---------------------------------------------------------------------------
+
+import type { FileSystem } from "./filesystem.js";
+import type { JsonCodec } from "./codec.js";
+
+const FILESYSTEM_METHODS = [
+  "readFile",
+  "readdir",
+  "writeFile",
+  "appendFile",
+  "mkdir",
+  "stat",
+  "readFileSync",
+] as const;
+
+const CODEC_METHODS = ["encode", "decode"] as const;
+
+function assertMethodsPresent(
+  portName: string,
+  impl: Record<string, unknown>,
+  methods: readonly string[],
+): void {
+  for (const method of methods) {
+    if (typeof impl[method] !== "function") {
+      throw new TypeError(
+        `${portName} adapter missing method: ${method} (got ${typeof impl[method]})`,
+      );
+    }
+  }
+}
+
+/**
+ * Validate that an object satisfies the FileSystem port contract at
+ * runtime. Call this at adapter construction boundaries to catch
+ * broken mocks and incomplete implementations early.
+ */
+export function assertFileSystem(impl: unknown): asserts impl is FileSystem {
+  if (impl === null || typeof impl !== "object") {
+    throw new TypeError(
+      `FileSystem adapter must be an object (got ${impl === null ? "null" : typeof impl})`,
+    );
+  }
+  assertMethodsPresent(
+    "FileSystem",
+    impl as Record<string, unknown>,
+    FILESYSTEM_METHODS,
+  );
+}
+
+/**
+ * Validate that an object satisfies the JsonCodec port contract at
+ * runtime. Call this at adapter construction boundaries to catch
+ * broken mocks and incomplete implementations early.
+ */
+export function assertJsonCodec(impl: unknown): asserts impl is JsonCodec {
+  if (impl === null || typeof impl !== "object") {
+    throw new TypeError(
+      `JsonCodec adapter must be an object (got ${impl === null ? "null" : typeof impl})`,
+    );
+  }
+  assertMethodsPresent(
+    "JsonCodec",
+    impl as Record<string, unknown>,
+    CODEC_METHODS,
+  );
+}

package/src/ports/warp.ts

@@ -0,0 +1,55 @@
+// ---------------------------------------------------------------------------
+// WARP port — hexagonal boundary for graph reads and writes
+// ---------------------------------------------------------------------------
+
+export interface WarpObserverLens {
+  readonly match: string | readonly string[];
+  readonly expose?: readonly string[] | undefined;
+  readonly redact?: readonly string[] | undefined;
+}
+
+export interface WarpObserverOptions {
+  readonly source?: {
+    readonly kind: "live";
+    readonly ceiling: number | null;
+  } | undefined;
+}
+
+export interface WarpEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly label: string;
+}
+
+export interface WarpObserver {
+  getNodes(): Promise<string[]>;
+  getNodeProps(nodeId: string): Promise<Record<string, unknown> | null>;
+  getEdges(): Promise<readonly WarpEdge[]>;
+}
+
+export interface WarpPatchBuilder {
+  addNode(id: string): unknown;
+  setProperty(id: string, key: string, value: unknown): unknown;
+  addEdge(from: string, to: string, label: string): unknown;
+  removeNode(id: string): unknown;
+  removeEdge(from: string, to: string, label: string): unknown;
+}
+
+export interface WarpMaterializeReceiptOp {
+  readonly op: string;
+  readonly result: string;
+  readonly target: string;
+}
+
+export interface WarpMaterializeReceipt {
+  readonly lamport: number;
+  readonly ops: readonly WarpMaterializeReceiptOp[];
+}
+
+export interface WarpHandle {
+  hasNode(nodeId: string): Promise<boolean>;
+  observer(lens: WarpObserverLens, options?: WarpObserverOptions): Promise<WarpObserver>;
+  patch(build: (patch: WarpPatchBuilder) => void | Promise<void>): Promise<string>;
+  materialize(): Promise<void>;
+  materializeReceipts(): Promise<readonly WarpMaterializeReceipt[]>;
+}

package/src/session/tracker.ts

@@ -1,11 +1,11 @@
 import { Tripwire } from "./types.js";
-import type { SessionDepth } from "./types.js";
+import type { GovernorDepth } from "./types.js";
 
 const EDIT_BASH_TOOLS = new Set(["Edit", "Bash"]);
 const LATE_READ_BYTE_THRESHOLD = 20480;
 const LATE_READ_MESSAGE_THRESHOLD = 300;
 
-export interface SessionTrackerSnapshot {
+export interface GovernorTrackerSnapshot {
   readonly totalMessages: number;
   readonly toolCallsSinceUser: number;
   readonly editBashTransitions: number;
@@ -14,7 +14,7 @@ export interface SessionTrackerSnapshot {
   readonly consumedBytes: number;
 }
 
-export class SessionTracker {
+export class GovernorTracker {
   private totalMessages = 0;
   private toolCallsSinceUser = 0;
   private editBashTransitions = 0;
@@ -22,8 +22,8 @@ export class SessionTracker {
   private budgetBytes: number | null = null;
   private consumedBytes = 0;
 
-  static fromSnapshot(snapshot: SessionTrackerSnapshot): SessionTracker {
-    const tracker = new SessionTracker();
+  static fromSnapshot(snapshot: GovernorTrackerSnapshot): GovernorTracker {
+    const tracker = new GovernorTracker();
     tracker.totalMessages = snapshot.totalMessages;
     tracker.toolCallsSinceUser = snapshot.toolCallsSinceUser;
     tracker.editBashTransitions = snapshot.editBashTransitions;
@@ -122,7 +122,7 @@ export class SessionTracker {
     };
   }
 
-  snapshot(): SessionTrackerSnapshot {
+  snapshot(): GovernorTrackerSnapshot {
     return {
       totalMessages: this.totalMessages,
       toolCallsSinceUser: this.toolCallsSinceUser,
@@ -133,7 +133,7 @@ export class SessionTracker {
     };
   }
 
-  getSessionDepth(): SessionDepth {
+  getGovernorDepth(): GovernorDepth {
     if (this.totalMessages < 100) {
       return "early";
     }

package/src/session/types.ts

@@ -17,4 +17,7 @@ export class Tripwire {
   }
 }
 
-export type SessionDepth = "early" | "mid" | "late";
+export type GovernorDepth = "early" | "mid" | "late";
+
+/** @deprecated Use {@link GovernorDepth}. Kept as a wire-format alias. */
+export type SessionDepth = GovernorDepth;

package/src/warp/identity-resolver.ts

@@ -0,0 +1,35 @@
+/**
+ * WARP Identity Resolver — creates an IdentityResolver backed by
+ * the WARP graph. Reads symbol identityId properties through the
+ * observer lens system.
+ */
+
+import type { WarpHandle } from "../ports/warp.js";
+import type { IdentityResolver } from "../operations/diff-identity.js";
+import { fileSymbolsLens, observe } from "./observers.js";
+
+/**
+ * Create an IdentityResolver that queries WARP for canonical symbol
+ * identities. Each call reads the current frontier snapshot — the
+ * resolver is stateless between calls.
+ */
+export function createWarpIdentityResolver(warp: WarpHandle): IdentityResolver {
+  return async (filePath: string) => {
+    const lens = fileSymbolsLens(filePath);
+    const obs = await observe(warp, lens);
+    const nodes = await obs.getNodes();
+    const identities = new Map<string, string>();
+
+    for (const nodeId of nodes) {
+      const props = await obs.getNodeProps(nodeId);
+      if (props === null) continue;
+      const name = props["name"];
+      const identityId = props["identityId"];
+      if (typeof name === "string" && typeof identityId === "string") {
+        identities.set(name, identityId);
+      }
+    }
+
+    return identities;
+  };
+}