@flyingrobots/graft 0.3.1

package/src/parser/diff.ts

@@ -0,0 +1,142 @@
+import { OutlineEntry } from "./types.js";
+
+export class DiffEntry {
+  /** @internal */
+  private readonly _brand = "DiffEntry" as const;
+  readonly name: string;
+  readonly kind: OutlineEntry["kind"];
+  readonly signature?: string;
+  readonly oldSignature?: string;
+  readonly childDiff?: OutlineDiff;
+
+  constructor(opts: {
+    name: string;
+    kind: OutlineEntry["kind"];
+    signature?: string;
+    oldSignature?: string;
+    childDiff?: OutlineDiff;
+  }) {
+    if (opts.name.trim().length === 0) {
+      throw new Error("DiffEntry: name must be non-empty");
+    }
+    this.name = opts.name.trim();
+    this.kind = opts.kind;
+    if (opts.signature !== undefined) this.signature = opts.signature;
+    if (opts.oldSignature !== undefined) this.oldSignature = opts.oldSignature;
+    if (opts.childDiff !== undefined) this.childDiff = opts.childDiff;
+    Object.freeze(this);
+  }
+}
+
+export class OutlineDiff {
+  /** @internal */
+  private readonly _brand = "OutlineDiff" as const;
+  readonly added: readonly DiffEntry[];
+  readonly removed: readonly DiffEntry[];
+  readonly changed: readonly DiffEntry[];
+  readonly unchangedCount: number;
+
+  constructor(opts: {
+    added: DiffEntry[];
+    removed: DiffEntry[];
+    changed: DiffEntry[];
+    unchangedCount: number;
+  }) {
+    if (!Number.isInteger(opts.unchangedCount) || opts.unchangedCount < 0) {
+      throw new Error("OutlineDiff: unchangedCount must be a non-negative integer");
+    }
+    this.added = Object.freeze([...opts.added]);
+    this.removed = Object.freeze([...opts.removed]);
+    this.changed = Object.freeze([...opts.changed]);
+    this.unchangedCount = opts.unchangedCount;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Returns the effective signature for comparison and reporting.
+ * Falls back to the entry's name when no explicit signature exists
+ * (e.g., for classes, interfaces, and plain exports).
+ */
+function entrySignature(entry: OutlineEntry): string {
+  return entry.signature ?? entry.name;
+}
+
+export function diffOutlines(
+  oldEntries: readonly OutlineEntry[],
+  newEntries: readonly OutlineEntry[],
+): OutlineDiff {
+  // Note: duplicate names are clobbered by Map.set — only the last
+  // entry with a given name survives. This is acceptable because
+  // tree-sitter outlines rarely produce duplicate top-level names,
+  // and symbol identity tracking (WARP Level 2+) will handle that case.
+  const oldByName = new Map<string, OutlineEntry>();
+  for (const entry of oldEntries) {
+    oldByName.set(entry.name, entry);
+  }
+
+  const newByName = new Map<string, OutlineEntry>();
+  for (const entry of newEntries) {
+    newByName.set(entry.name, entry);
+  }
+
+  const added: DiffEntry[] = [];
+  const removed: DiffEntry[] = [];
+  const changed: DiffEntry[] = [];
+  let unchangedCount = 0;
+
+  // Check new entries against old
+  for (const [name, newEntry] of newByName) {
+    const oldEntry = oldByName.get(name);
+    if (oldEntry === undefined) {
+      added.push(new DiffEntry({
+        name,
+        kind: newEntry.kind,
+        ...(newEntry.signature !== undefined ? { signature: newEntry.signature } : {}),
+      }));
+    } else {
+      const oldSig = entrySignature(oldEntry);
+      const newSig = entrySignature(newEntry);
+      if (oldSig !== newSig) {
+        changed.push(new DiffEntry({
+          name,
+          kind: newEntry.kind,
+          oldSignature: entrySignature(oldEntry),
+          ...(newEntry.signature !== undefined ? { signature: newEntry.signature } : {}),
+        }));
+      } else {
+        // Same name and signature — check children recursively
+        const oldChildren = oldEntry.children ?? [];
+        const newChildren = newEntry.children ?? [];
+        if (oldChildren.length > 0 || newChildren.length > 0) {
+          const childDiff = diffOutlines(oldChildren, newChildren);
+          if (childDiff.added.length > 0 || childDiff.removed.length > 0 || childDiff.changed.length > 0) {
+            changed.push(new DiffEntry({
+              name,
+              kind: newEntry.kind,
+              childDiff,
+              ...(newEntry.signature !== undefined ? { signature: newEntry.signature } : {}),
+            }));
+          } else {
+            unchangedCount++;
+          }
+        } else {
+          unchangedCount++;
+        }
+      }
+    }
+  }
+
+  // Check for removed (in old but not in new)
+  for (const [name, oldEntry] of oldByName) {
+    if (!newByName.has(name)) {
+      removed.push(new DiffEntry({
+        name,
+        kind: oldEntry.kind,
+        ...(oldEntry.signature !== undefined ? { signature: oldEntry.signature } : {}),
+      }));
+    }
+  }
+
+  return new OutlineDiff({ added, removed, changed, unchangedCount });
+}

package/src/parser/lang.ts

@@ -0,0 +1,12 @@
+import * as path from "node:path";
+
+/**
+ * Detect the tree-sitter language from a file extension.
+ * Returns null for unsupported file types.
+ */
+export function detectLang(filePath: string): "ts" | "js" | null {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === ".ts" || ext === ".tsx") return "ts";
+  if (ext === ".js" || ext === ".jsx") return "js";
+  return null;
+}

package/src/parser/outline.ts

@@ -0,0 +1,327 @@
+import Parser from "web-tree-sitter";
+import { createRequire } from "node:module";
+import { OutlineEntry, JumpEntry } from "./types.js";
+import type { OutlineResult } from "./types.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
+// ---------------------------------------------------------------------------
+
+/** Compact object-literal default values: `= { ... }` becomes `= {…}`. */
+function compactObjectDefaults(sig: string): string {
+  return sig.replace(/=\s*\{[^}]*\}/g, "= {…}");
+}
+
+/** Truncate a signature to fit within MAX_SIGNATURE_LENGTH. */
+function boundSignature(raw: string): string {
+  let sig = compactObjectDefaults(raw);
+  if (sig.length >= MAX_SIGNATURE_LENGTH) {
+    sig = sig.slice(0, MAX_SIGNATURE_LENGTH - 1) + "…";
+  }
+  return sig;
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+// ---------------------------------------------------------------------------
+// Node kind mapping
+// ---------------------------------------------------------------------------
+
+type EntryKind = OutlineEntry["kind"];
+
+function nodeKind(nodeType: string): EntryKind | undefined {
+  switch (nodeType) {
+    case "function_declaration":
+    case "generator_function_declaration":
+      return "function";
+    case "class_declaration":
+      return "class";
+    case "method_definition":
+      return "method";
+    case "interface_declaration":
+      return "interface";
+    case "type_alias_declaration":
+      return "type";
+    case "enum_declaration":
+      return "enum";
+    default:
+      return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Extraction helpers
+// ---------------------------------------------------------------------------
+
+function extractFunctionSignature(node: TSNode): string | undefined {
+  const nameNode = node.childForFieldName("name");
+  if (!nameNode) return undefined;
+
+  const params = node.childForFieldName("parameters");
+  const returnType = node.childForFieldName("return_type");
+
+  let sig = nameNode.text;
+  if (params) {
+    sig += params.text;
+  }
+  if (returnType) {
+    // return_type node text includes the leading `: ` in some grammars
+    const rt = returnType.text.replace(/^:\s*/, "");
+    sig += ": " + rt;
+  }
+
+  return boundSignature(sig);
+}
+
+function extractName(node: TSNode): string | undefined {
+  const nameNode = node.childForFieldName("name");
+  return nameNode?.text;
+}
+
+function extractClassChildren(node: TSNode): OutlineEntry[] {
+  const body = node.childForFieldName("body");
+  if (!body) return [];
+
+  const children: OutlineEntry[] = [];
+  for (const child of body.namedChildren) {
+    if (child.type === "method_definition") {
+      const name = extractName(child);
+      if (!name) continue;
+
+      const sig = extractFunctionSignature(child);
+      children.push(new OutlineEntry({
+        kind: "method",
+        name,
+        exported: false,
+        ...(sig !== undefined ? { signature: sig } : {}),
+      }));
+    }
+  }
+  return children;
+}
+
+function processDeclaration(
+  node: TSNode,
+  exported: boolean,
+): OutlineEntry | undefined {
+  const kind = nodeKind(node.type);
+  if (!kind) return undefined;
+
+  const name = extractName(node);
+  if (!name) return undefined;
+
+  const sig = kind === "function" ? extractFunctionSignature(node) : undefined;
+  const children = kind === "class" ? extractClassChildren(node) : undefined;
+
+  return new OutlineEntry({
+    kind,
+    name,
+    exported,
+    ...(sig !== undefined ? { signature: sig } : {}),
+    ...(children !== undefined && children.length > 0 ? { children } : {}),
+  });
+}
+
+function extractArrowSignature(name: string, arrowNode: TSNode): string | undefined {
+  const params = arrowNode.childForFieldName("parameters");
+  const returnType = arrowNode.childForFieldName("return_type");
+
+  let sig = name;
+  if (params) {
+    sig += params.text;
+  }
+  if (returnType) {
+    const rt = returnType.text.replace(/^:\s*/, "");
+    sig += ": " + rt;
+  }
+
+  return boundSignature(sig);
+}
+
+function processLexicalExport(node: TSNode): OutlineEntry[] {
+  const entries: OutlineEntry[] = [];
+  for (const child of node.namedChildren) {
+    if (child.type === "variable_declarator") {
+      const name = extractName(child);
+      if (!name) continue;
+
+      // Check if the value is an arrow function or function expression
+      const value = child.childForFieldName("value");
+      if (value && (value.type === "arrow_function" || value.type === "function")) {
+        const sig = extractArrowSignature(name, value);
+        entries.push(new OutlineEntry({
+          kind: "function",
+          name,
+          exported: true,
+          ...(sig !== undefined ? { signature: sig } : {}),
+        }));
+      } else {
+        entries.push(new OutlineEntry({ kind: "export", name, exported: true }));
+      }
+    }
+  }
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Jump table builder
+// ---------------------------------------------------------------------------
+
+function buildJumpEntry(
+  name: string,
+  kind: string,
+  node: TSNode,
+): JumpEntry {
+  return new JumpEntry({
+    symbol: name,
+    kind,
+    start: node.startPosition.row + 1,
+    end: node.endPosition.row + 1,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a structural outline from source code.
+ *
+ * @param source - The source code text.
+ * @param lang - Language identifier: `"ts"` or `"js"`. Defaults to `"ts"`.
+ * @returns An {@link OutlineResult} with entries, jump table, and partial flag.
+ */
+export function extractOutline(
+  source: string,
+  lang: "ts" | "js" = "ts",
+): OutlineResult {
+  const parser = new Parser();
+  parser.setLanguage(lang === "ts" ? tsLang : jsLang);
+
+  const tree = parser.parse(source);
+  const root = tree.rootNode as unknown as TSNode;
+
+  const entries: OutlineEntry[] = [];
+  const jumpTable: JumpEntry[] = [];
+  const hasError = root.hasError;
+
+  for (const child of root.children) {
+    if (child.type === "export_statement") {
+      // export_statement wraps a declaration
+      const inner = child.namedChildren.find(
+        (c) =>
+          c.type === "function_declaration" ||
+          c.type === "generator_function_declaration" ||
+          c.type === "class_declaration" ||
+          c.type === "interface_declaration" ||
+          c.type === "type_alias_declaration" ||
+          c.type === "enum_declaration",
+      );
+
+      if (inner) {
+        const entry = processDeclaration(inner, true);
+        if (entry) {
+          entries.push(entry);
+          jumpTable.push(buildJumpEntry(entry.name, entry.kind, child));
+        }
+        continue;
+      }
+
+      // Check for lexical declaration (const/let exports)
+      const lexical = child.namedChildren.find(
+        (c) => c.type === "lexical_declaration",
+      );
+      if (lexical) {
+        const lexEntries = processLexicalExport(lexical);
+        for (const entry of lexEntries) {
+          entries.push(entry);
+          jumpTable.push(buildJumpEntry(entry.name, entry.kind, child));
+        }
+        continue;
+      }
+
+      // Re-exports: export { A, B } from './x'
+      const exportClause = child.namedChildren.find(
+        (c) => c.type === "export_clause",
+      );
+      if (exportClause) {
+        for (const spec of exportClause.namedChildren) {
+          if (spec.type === "export_specifier") {
+            const nameNode = spec.childForFieldName("alias") ?? spec.childForFieldName("name");
+            if (nameNode) {
+              entries.push(new OutlineEntry({ kind: "export", name: nameNode.text, exported: true }));
+              jumpTable.push(buildJumpEntry(nameNode.text, "export", child));
+            }
+          }
+        }
+        continue;
+      }
+
+      // Wildcard re-export: export * from './x'
+      const moduleSpecifier = child.namedChildren.find((c) => c.type === "string");
+      const hasWildcard = child.children.some((c) => c.type === "*" || c.type === "namespace_export");
+      if (hasWildcard && moduleSpecifier) {
+        const name = `* from ${moduleSpecifier.text}`;
+        entries.push(new OutlineEntry({ kind: "export", name, exported: true }));
+        jumpTable.push(buildJumpEntry(name, "export", child));
+        continue;
+      }
+
+      // Other export forms — skip
+    } else {
+      // Non-exported top-level declaration
+      const kind = nodeKind(child.type);
+      if (kind) {
+        const entry = processDeclaration(child, false);
+        if (entry) {
+          entries.push(entry);
+          jumpTable.push(buildJumpEntry(entry.name, entry.kind, child));
+        }
+      }
+    }
+  }
+
+  parser.delete();
+  tree.delete();
+
+  const result: OutlineResult = {
+    entries,
+    jumpTable,
+  };
+
+  if (hasError) {
+    result.partial = true;
+  }
+
+  return result;
+}

package/src/parser/types.ts

@@ -0,0 +1,67 @@
+/** The kind of a top-level or member declaration. */
+export type EntryKind = "function" | "class" | "method" | "interface" | "type" | "enum" | "export";
+
+/** A single entry in a file outline. */
+export class OutlineEntry {
+  /** @internal Brand prevents structural forgery from plain objects. */
+  private readonly _brand = "OutlineEntry" as const;
+  readonly kind: EntryKind;
+  readonly name: string;
+  readonly signature?: string;
+  readonly exported: boolean;
+  readonly children?: readonly OutlineEntry[];
+
+  constructor(opts: {
+    kind: EntryKind;
+    name: string;
+    exported: boolean;
+    signature?: string;
+    children?: readonly OutlineEntry[];
+  }) {
+    if (opts.name.trim().length === 0) {
+      throw new Error("OutlineEntry: name must be non-empty");
+    }
+    this.kind = opts.kind;
+    this.name = opts.name.trim();
+    this.exported = opts.exported;
+    if (opts.signature !== undefined) this.signature = opts.signature;
+    if (opts.children !== undefined) this.children = Object.freeze([...opts.children]);
+    Object.freeze(this);
+  }
+}
+
+/** A jump-table entry mapping a symbol to its 1-based line range. */
+export class JumpEntry {
+  /** @internal Brand prevents structural forgery from plain objects. */
+  private readonly _brand = "JumpEntry" as const;
+  readonly symbol: string;
+  readonly kind: string;
+  readonly start: number; // 1-based line
+  readonly end: number; // 1-based line
+
+  constructor(opts: {
+    symbol: string;
+    kind: string;
+    start: number;
+    end: number;
+  }) {
+    if (!Number.isInteger(opts.start) || opts.start < 1) {
+      throw new Error("JumpEntry: start must be an integer >= 1");
+    }
+    if (!Number.isInteger(opts.end) || opts.end < opts.start) {
+      throw new Error("JumpEntry: end must be an integer >= start");
+    }
+    this.symbol = opts.symbol;
+    this.kind = opts.kind;
+    this.start = opts.start;
+    this.end = opts.end;
+    Object.freeze(this);
+  }
+}
+
+/** Result of outline extraction. */
+export interface OutlineResult {
+  entries: OutlineEntry[];
+  jumpTable?: JumpEntry[];
+  partial?: boolean;
+}