@flyingrobots/graft 0.6.0 → 0.7.0

package/src/warp/ast-import-resolver.ts

@@ -0,0 +1,333 @@
+// ---------------------------------------------------------------------------
+// AST Import Resolver — adds cross-file reference edges to the WARP graph
+// ---------------------------------------------------------------------------
+
+import { createHash } from "node:crypto";
+import type { PatchBuilderV2 } from "@git-stunts/git-warp";
+import type { PathOps } from "../ports/paths.js";
+
+type TSNode = import("web-tree-sitter").SyntaxNode;
+
+function hashId(input: string): string {
+  return createHash("sha1").update(input).digest("hex").slice(0, 12);
+}
+
+function astNodeId(filePath: string, node: TSNode): string {
+  const hash = hashId(`${filePath}:${node.type}:${String(node.startIndex)}:${String(node.endIndex)}`);
+  return `ast:${filePath}:${hash}`;
+}
+
+function resolveModulePath(
+  importSource: string,
+  importingFilePath: string,
+  pathOps: PathOps,
+  knownFiles: ReadonlySet<string>,
+): string | null {
+  // Skip non-relative imports (bare specifiers like "@pkg/foo" or "node:path")
+  if (!importSource.startsWith(".") && !importSource.startsWith("/")) {
+    return null;
+  }
+
+  // Resolve relative to the importing file's directory
+  const dir = importingFilePath.includes("/")
+    ? importingFilePath.slice(0, importingFilePath.lastIndexOf("/"))
+    : "";
+  const raw = dir.length > 0
+    ? pathOps.join(dir, importSource)
+    : pathOps.normalize(importSource);
+
+  const sourceExtensionCandidates = compiledSpecifierSourceCandidates(raw);
+
+  // Try exact match, then with extensions
+  const candidates = [
+    raw,
+    ...sourceExtensionCandidates,
+    `${raw}.ts`,
+    `${raw}.tsx`,
+    `${raw}.js`,
+    `${raw}.jsx`,
+    `${raw}/index.ts`,
+    `${raw}/index.tsx`,
+    `${raw}/index.js`,
+  ];
+
+  for (const candidate of candidates) {
+    if (knownFiles.has(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function compiledSpecifierSourceCandidates(resolvedImportSource: string): readonly string[] {
+  const compiledToSourceExtensions: readonly [string, readonly string[]][] = [
+    [".js", [".ts", ".tsx"]],
+    [".jsx", [".tsx", ".ts"]],
+    [".mjs", [".mts", ".ts"]],
+    [".cjs", [".cts", ".ts"]],
+  ];
+
+  for (const [compiledExtension, sourceExtensions] of compiledToSourceExtensions) {
+    if (!resolvedImportSource.endsWith(compiledExtension)) continue;
+
+    const base = resolvedImportSource.slice(0, -compiledExtension.length);
+    return sourceExtensions.map((sourceExtension) => `${base}${sourceExtension}`);
+  }
+
+  return [];
+}
+
+function symNodeId(filePath: string, symbolName: string): string {
+  return `sym:${filePath}:${symbolName}`;
+}
+
+interface ImportInfo {
+  readonly specifierNodeId: string;
+  readonly node: TSNode;
+  readonly importedName: string;
+  readonly localName: string;
+}
+
+function emitAstAnchor(patch: PatchBuilderV2, filePath: string, node: TSNode): string {
+  const nodeId = astNodeId(filePath, node);
+  patch.addNode(nodeId);
+  patch.setProperty(nodeId, "type", node.type);
+  patch.setProperty(nodeId, "named", node.isNamed());
+  patch.setProperty(nodeId, "startRow", node.startPosition.row);
+  patch.setProperty(nodeId, "startCol", node.startPosition.column);
+  patch.setProperty(nodeId, "endRow", node.endPosition.row);
+  patch.setProperty(nodeId, "endCol", node.endPosition.column);
+  patch.setProperty(nodeId, "filePath", filePath);
+  return nodeId;
+}
+
+function extractImportSpecifiers(
+  importNode: TSNode,
+  filePath: string,
+): ImportInfo[] {
+  const results: ImportInfo[] = [];
+  const importClause = importNode.namedChildren.find((c) => c.type === "import_clause");
+  if (importClause === undefined) return results;
+
+  for (const child of importClause.namedChildren) {
+    switch (child.type) {
+      case "named_imports": {
+        // import { foo, bar as baz } from "..."
+        for (const spec of child.namedChildren) {
+          if (spec.type === "import_specifier") {
+            const nameNode = spec.childForFieldName("name");
+            const aliasNode = spec.childForFieldName("alias");
+            if (nameNode !== null) {
+              results.push({
+                specifierNodeId: astNodeId(filePath, spec),
+                node: spec,
+                importedName: nameNode.text,
+                localName: aliasNode !== null ? aliasNode.text : nameNode.text,
+              });
+            }
+          }
+        }
+        break;
+      }
+      case "identifier": {
+        // import foo from "..." (default import)
+        results.push({
+          specifierNodeId: astNodeId(filePath, child),
+          node: child,
+          importedName: "default",
+          localName: child.text,
+        });
+        break;
+      }
+      case "namespace_import": {
+        // import * as ns from "..."
+        const aliasNode = child.namedChildren.find((c) => c.type === "identifier");
+        if (aliasNode !== undefined) {
+          results.push({
+            specifierNodeId: astNodeId(filePath, child),
+            node: child,
+            importedName: "*",
+            localName: aliasNode.text,
+          });
+        }
+        break;
+      }
+    }
+  }
+
+  return results;
+}
+
+function extractExportSpecifiers(
+  exportNode: TSNode,
+  filePath: string,
+): ImportInfo[] {
+  const results: ImportInfo[] = [];
+  const exportClause = exportNode.namedChildren.find((c) => c.type === "export_clause");
+  if (exportClause === undefined) return results;
+
+  for (const spec of exportClause.namedChildren) {
+    if (spec.type === "export_specifier") {
+      const nameNode = spec.childForFieldName("name");
+      const aliasNode = spec.childForFieldName("alias");
+      if (nameNode !== null) {
+        results.push({
+          specifierNodeId: astNodeId(filePath, spec),
+          node: spec,
+          importedName: nameNode.text,
+          localName: aliasNode !== null ? aliasNode.text : nameNode.text,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+function getModuleSource(node: TSNode): string | null {
+  const stringNode = node.namedChildren.find((c) => c.type === "string");
+  if (stringNode === undefined) return null;
+  const fragment = stringNode.namedChildren.find((c) => c.type === "string_fragment");
+  return fragment !== undefined ? fragment.text : null;
+}
+
+/**
+ * Resolve import/export statements and emit cross-file reference edges.
+ *
+ * Call this inside a patch callback after emitAstNodes has run for a file.
+ * Handles: named imports, aliased imports, default imports, namespace imports,
+ * re-exports, and dynamic imports.
+ */
+export function resolveImportEdges(
+  patch: PatchBuilderV2,
+  filePath: string,
+  root: TSNode,
+  pathOps: PathOps,
+  knownFiles: ReadonlySet<string>,
+): void {
+  for (const child of root.namedChildren) {
+    if (child.type === "import_statement") {
+      handleImportStatement(patch, filePath, child, pathOps, knownFiles);
+    } else if (child.type === "export_statement") {
+      handleExportStatement(patch, filePath, child, pathOps, knownFiles);
+    }
+  }
+
+  // Dynamic imports: find call_expression nodes with `import` function
+  walkForDynamicImports(patch, filePath, root, pathOps, knownFiles);
+}
+
+function handleImportStatement(
+  patch: PatchBuilderV2,
+  filePath: string,
+  node: TSNode,
+  pathOps: PathOps,
+  knownFiles: ReadonlySet<string>,
+): void {
+  const source = getModuleSource(node);
+  if (source === null) return;
+
+  const resolvedPath = resolveModulePath(source, filePath, pathOps, knownFiles);
+
+  // Emit resolves_to edge from the string node to the target file
+  const stringNode = node.namedChildren.find((c) => c.type === "string");
+  if (stringNode !== undefined && resolvedPath !== null) {
+    const stringId = emitAstAnchor(patch, filePath, stringNode);
+    patch.addEdge(stringId, `file:${resolvedPath}`, "resolves_to");
+  }
+
+  // Emit reference edges from specifiers to sym: nodes
+  const specifiers = extractImportSpecifiers(node, filePath);
+  for (const spec of specifiers) {
+    emitAstAnchor(patch, filePath, spec.node);
+    patch.setProperty(spec.specifierNodeId, "importedName", spec.importedName);
+    patch.setProperty(spec.specifierNodeId, "localName", spec.localName);
+    patch.setProperty(spec.specifierNodeId, "filePath", filePath);
+
+    if (resolvedPath !== null) {
+      if (spec.importedName === "*") {
+        // Namespace import references the whole file
+        patch.addEdge(spec.specifierNodeId, `file:${resolvedPath}`, "references");
+      } else {
+        // Named/default import references a specific symbol
+        patch.addEdge(spec.specifierNodeId, symNodeId(resolvedPath, spec.importedName), "references");
+      }
+    }
+  }
+}
+
+function handleExportStatement(
+  patch: PatchBuilderV2,
+  filePath: string,
+  node: TSNode,
+  pathOps: PathOps,
+  knownFiles: ReadonlySet<string>,
+): void {
+  // Only handle re-exports (export { ... } from "...")
+  const source = getModuleSource(node);
+  if (source === null) return;
+
+  const resolvedPath = resolveModulePath(source, filePath, pathOps, knownFiles);
+
+  const stringNode = node.namedChildren.find((c) => c.type === "string");
+  if (stringNode !== undefined && resolvedPath !== null) {
+    const stringId = emitAstAnchor(patch, filePath, stringNode);
+    patch.addEdge(stringId, `file:${resolvedPath}`, "resolves_to");
+  }
+
+  // Check for wildcard re-export: export * from "..."
+  const hasWildcard = node.children.some((c) => c.type === "*" || c.type === "namespace_export");
+  if (hasWildcard && resolvedPath !== null) {
+    const nodeId = emitAstAnchor(patch, filePath, node);
+    patch.addEdge(nodeId, `file:${resolvedPath}`, "reexports");
+    return;
+  }
+
+  // Named re-exports: export { foo, bar as baz } from "..."
+  const specifiers = extractExportSpecifiers(node, filePath);
+  for (const spec of specifiers) {
+    emitAstAnchor(patch, filePath, spec.node);
+    patch.setProperty(spec.specifierNodeId, "importedName", spec.importedName);
+    patch.setProperty(spec.specifierNodeId, "localName", spec.localName);
+    patch.setProperty(spec.specifierNodeId, "filePath", filePath);
+
+    if (resolvedPath !== null) {
+      patch.addEdge(spec.specifierNodeId, symNodeId(resolvedPath, spec.importedName), "references");
+    }
+  }
+}
+
+function walkForDynamicImports(
+  patch: PatchBuilderV2,
+  filePath: string,
+  node: TSNode,
+  pathOps: PathOps,
+  knownFiles: ReadonlySet<string>,
+): void {
+  if (node.type === "call_expression") {
+    const funcNode = node.namedChildren[0];
+    if (funcNode?.type === "import") {
+      // Dynamic import: import("./foo")
+      const args = node.namedChildren.find((c) => c.type === "arguments");
+      if (args !== undefined) {
+        const stringArg = args.namedChildren.find((c) => c.type === "string");
+        if (stringArg !== undefined) {
+          const fragment = stringArg.namedChildren.find((c) => c.type === "string_fragment");
+          if (fragment !== undefined) {
+            const resolved = resolveModulePath(fragment.text, filePath, pathOps, knownFiles);
+            if (resolved !== null) {
+              const stringId = emitAstAnchor(patch, filePath, stringArg);
+              patch.addEdge(stringId, `file:${resolved}`, "resolves_to");
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Recurse
+  for (const child of node.namedChildren) {
+    walkForDynamicImports(patch, filePath, child, pathOps, knownFiles);
+  }
+}

package/src/warp/commit-meta.ts

@@ -0,0 +1,19 @@
+import type { GitClient } from "../ports/git.js";
+
+async function git(gitClient: GitClient, cwd: string, args: readonly string[]): Promise<string> {
+  const result = await gitClient.run({ cwd, args });
+  if (result.error !== undefined || result.status !== 0) {
+    throw result.error ?? new Error(result.stderr.trim() || `git exited with status ${String(result.status)}`);
+  }
+  return result.stdout;
+}
+
+export async function getCommitMeta(
+  gitClient: GitClient,
+  sha: string,
+  cwd: string,
+): Promise<{ message: string; author: string; email: string; timestamp: string }> {
+  const output = await git(gitClient, cwd, ["log", "-1", "--format=%s%n%aN%n%aE%n%aI", sha]);
+  const lines = output.trim().split("\n");
+  return { message: lines[0] ?? "", author: lines[1] ?? "", email: lines[2] ?? "", timestamp: lines[3] ?? "" };
+}

package/src/warp/context.ts

@@ -0,0 +1,48 @@
+// ---------------------------------------------------------------------------
+// WarpContext — session-scoped DI bag for all graph access.
+//
+// Every graph interaction (reads AND writes) routes through this context.
+// A strand scopes the agent's entire worldview — strand-local writes are
+// invisible from live reads, so routing must be uniform.
+// ---------------------------------------------------------------------------
+
+import type WarpApp from "@git-stunts/git-warp";
+import type { Lens, Observer, ObserverOptions, PatchBuilderV2 } from "@git-stunts/git-warp";
+
+export interface WarpContext {
+  readonly app: WarpApp;
+  readonly strandId: string | null;
+}
+
+function assertNoStrand(ctx: WarpContext): void {
+  if (ctx.strandId !== null) {
+    throw new Error(
+      `Strand isolation not yet supported (strandId: ${ctx.strandId}). ` +
+      `git-warp strand merging is not ready.`,
+    );
+  }
+}
+
+export async function patchGraph(
+  ctx: WarpContext,
+  build: (patch: PatchBuilderV2) => void | Promise<void>,
+): Promise<string> {
+  assertNoStrand(ctx);
+  return ctx.app.patch(build);
+}
+
+export async function observeGraph(
+  ctx: WarpContext,
+  lens: Lens,
+  options?: ObserverOptions,
+): Promise<Observer> {
+  assertNoStrand(ctx);
+  return ctx.app.observer(lens, options);
+}
+
+export async function materializeGraph(
+  ctx: WarpContext,
+): Promise<void> {
+  assertNoStrand(ctx);
+  await ctx.app.core().materialize();
+}

package/src/warp/dead-symbols.ts

@@ -0,0 +1,174 @@
+/**
+ * Dead Symbol Detection — find symbols removed and never re-added.
+ *
+ * A symbol is "dead" when it existed at one tick but is absent at a
+ * later tick and never reappears. This identifies cleanup candidates,
+ * tracks deprecations, and measures API surface shrinkage.
+ *
+ * Uses the WARP graph's temporal observer to compare symbol snapshots
+ * across ticks. Walks commits in tick order, detects removals by
+ * diff, then filters out any symbol that reappears later.
+ */
+
+import type { Lens } from "@git-stunts/git-warp";
+import { observeGraph, type WarpContext } from "./context.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A symbol that was removed and never re-added. */
+export interface DeadSymbol {
+  /** The symbol name (e.g. "myFunction"). */
+  readonly name: string;
+  /** The kind of symbol (e.g. "function", "class"). */
+  readonly kind: string;
+  /** The file path the symbol belonged to. */
+  readonly filePath: string;
+  /** Whether the symbol was exported. */
+  readonly exported: boolean;
+  /** The commit SHA that removed the symbol. */
+  readonly removedInCommit: string;
+}
+
+/** Options for the dead-symbol query. */
+export interface DeadSymbolOptions {
+  /** Limit the search to the last N commits (by tick order). */
+  readonly maxCommits?: number | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Extract the file path from a sym node id like "sym:path/to/file.ts:symbolName". */
+function filePathFromSymId(symId: string): string {
+  const withoutPrefix = symId.slice("sym:".length);
+  const lastColon = withoutPrefix.lastIndexOf(":");
+  if (lastColon === -1) {
+    return withoutPrefix;
+  }
+  return withoutPrefix.slice(0, lastColon);
+}
+
+const SYM_LENS: Lens = {
+  match: "sym:*",
+  expose: ["name", "kind", "signature", "exported"],
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Find symbols that were removed and never re-added.
+ *
+ * For each commit in tick order, compares the sym-node set at the previous
+ * indexed commit tick vs this commit's tick to find removals (present before,
+ * absent after). A single Git commit can span multiple WARP Lamport ticks
+ * because lazy indexing writes one bounded patch per file.
+ */
+export async function findDeadSymbols(
+  ctx: WarpContext,
+  options?: DeadSymbolOptions,
+): Promise<DeadSymbol[]> {
+  // Discover all commit nodes and read their ticks.
+  const commitLens: Lens = {
+    match: "commit:*",
+    expose: ["sha", "tick"],
+  };
+  const commitObs = await observeGraph(ctx, commitLens);
+  const commitNodeIds = await commitObs.getNodes();
+
+  const commits: { id: string; sha: string; tick: number }[] = [];
+  for (const id of commitNodeIds) {
+    const props = await commitObs.getNodeProps(id);
+    const tick = typeof props?.["tick"] === "number" ? props["tick"] : null;
+    if (tick === null) continue;
+    const sha = typeof props?.["sha"] === "string"
+      ? props["sha"]
+      : id.slice("commit:".length);
+    commits.push({ id, sha, tick });
+  }
+
+  // Sort by tick ascending.
+  commits.sort((a, b) => a.tick - b.tick);
+
+  if (commits.length === 0) return [];
+
+  // Apply maxCommits limit — scope to the last N commits.
+  const limit = options?.maxCommits;
+  const scopedCommits = limit !== undefined && limit > 0
+    ? commits.slice(-limit)
+    : commits;
+
+  // For each scoped commit, detect removals by diffing sym nodes at the
+  // previous indexed commit boundary vs this commit's boundary. Per-file lazy
+  // index patches inside the same Git commit are deliberately treated as one
+  // commit window.
+  // Track removed symbols with the pre-removal boundary needed to recover props.
+  // If a symbol reappears at a later tick, remove it from the map.
+  const removals = new Map<string, { sha: string; tick: number; beforeTick: number }>();
+
+  for (const commit of scopedCommits) {
+    const commitIndex = commits.indexOf(commit);
+    const previousCommit = commitIndex > 0 ? commits[commitIndex - 1] : undefined;
+    const beforeTick = commitIndex > 0
+      ? previousCommit?.tick ?? 0
+      : 0;
+
+    const [beforeObs, afterObs] = await Promise.all([
+      observeGraph(ctx, SYM_LENS, { source: { kind: "live", ceiling: beforeTick } }),
+      observeGraph(ctx, SYM_LENS, { source: { kind: "live", ceiling: commit.tick } }),
+    ]);
+
+    const [beforeNodes, afterNodes] = await Promise.all([
+      beforeObs.getNodes(),
+      afterObs.getNodes(),
+    ]);
+
+    const afterSet = new Set(afterNodes);
+    const beforeSet = new Set(beforeNodes);
+
+    // Symbols present before but absent after = removed in this commit.
+    for (const symId of beforeNodes) {
+      if (!afterSet.has(symId)) {
+        removals.set(symId, { sha: commit.sha, tick: commit.tick, beforeTick });
+      }
+    }
+
+    // Symbols absent before but present after = re-added in this commit.
+    for (const symId of afterNodes) {
+      if (!beforeSet.has(symId) && removals.has(symId)) {
+        removals.delete(symId);
+      }
+    }
+  }
+
+  if (removals.size === 0) return [];
+
+  // Read props for dead symbols from a ceiling just before removal.
+  const dead: DeadSymbol[] = [];
+
+  for (const [symId, removal] of removals) {
+    const beforeObs = await observeGraph(ctx, SYM_LENS, {
+      source: { kind: "live", ceiling: removal.beforeTick },
+    });
+
+    const props = await beforeObs.getNodeProps(symId);
+    const name = typeof props?.["name"] === "string" ? props["name"] : symId;
+    const kind = typeof props?.["kind"] === "string" ? props["kind"] : "unknown";
+    const exported = typeof props?.["exported"] === "boolean" ? props["exported"] : false;
+    const filePath = filePathFromSymId(symId);
+
+    dead.push({
+      name,
+      kind,
+      filePath,
+      exported,
+      removedInCommit: removal.sha,
+    });
+  }
+
+  return dead;
+}

package/src/warp/drift-sentinel.ts

@@ -0,0 +1,101 @@
+// ---------------------------------------------------------------------------
+// Drift Sentinel — scan all markdown files for stale symbol references
+// ---------------------------------------------------------------------------
+
+import type { WarpContext } from "./context.js";
+import { checkStaleDocs, type StaleDocReport } from "./stale-docs.js";
+import type { GitClient } from "../ports/git.js";
+import picomatch from "picomatch";
+
+/** Options for the drift sentinel scan. */
+export interface DriftSentinelOptions {
+  readonly cwd: string;
+  readonly git: GitClient;
+  /** Glob pattern for markdown files to check. Defaults to all tracked .md files. */
+  readonly pattern?: string;
+}
+
+/** Full drift report across all scanned doc files. */
+export interface DriftSentinelReport {
+  /** True if no stale or unknown symbols were found in any doc. */
+  readonly passed: boolean;
+  /** Per-file results. */
+  readonly results: readonly StaleDocReport[];
+  /** Total stale symbol count across all files. */
+  readonly totalStale: number;
+  /** Total unknown symbol count across all files. */
+  readonly totalUnknown: number;
+}
+
+/**
+ * Scan all markdown files in the repo for stale symbol references.
+ *
+ * For each tracked `.md` file, runs `checkStaleDocs` against the WARP
+ * graph. Returns a structured report with pass/fail verdict suitable
+ * for pre-commit hook exit codes.
+ */
+export async function runDriftSentinel(
+  ctx: WarpContext,
+  options: DriftSentinelOptions,
+): Promise<DriftSentinelReport> {
+  const { cwd, git } = options;
+
+  // List all tracked markdown files
+  const lsResult = await git.run({
+    cwd,
+    args: ["ls-files", "--cached", "*.md", "**/*.md"],
+  });
+
+  if (lsResult.error !== undefined || lsResult.status !== 0) {
+    return { passed: true, results: [], totalStale: 0, totalUnknown: 0 };
+  }
+
+  const pattern = options.pattern?.trim();
+  const matchesPattern = pattern !== undefined && pattern.length > 0
+    ? picomatch(pattern)
+    : null;
+
+  const mdFiles = lsResult.stdout
+    .split("\n")
+    .map((f) => f.trim())
+    .filter((f) => f.length > 0 && f.endsWith(".md"))
+    .filter((f) => matchesPattern === null || matchesPattern(f));
+
+  if (mdFiles.length === 0) {
+    return { passed: true, results: [], totalStale: 0, totalUnknown: 0 };
+  }
+
+  // For each markdown file, get its last-modified commit SHA and content
+  const results: StaleDocReport[] = [];
+
+  for (const mdFile of mdFiles) {
+    // Get the commit SHA that last modified this file
+    const logResult = await git.run({
+      cwd,
+      args: ["log", "-1", "--format=%H", "--", mdFile],
+    });
+    const docCommitSha = logResult.stdout.trim();
+    if (docCommitSha.length === 0) continue;
+
+    // Read file content
+    const showResult = await git.run({
+      cwd,
+      args: ["show", `HEAD:${mdFile}`],
+    });
+    const docContent = showResult.stdout;
+    if (docContent.length === 0) continue;
+
+    const report = await checkStaleDocs(ctx, mdFile, docCommitSha, docContent);
+
+    // Only include files that have symbol references
+    if (report.staleSymbols.length > 0 || report.unknownSymbols.length > 0) {
+      results.push(report);
+    }
+  }
+
+  const totalStale = results.reduce((sum, r) => sum + r.staleSymbols.length, 0);
+  const totalUnknown = results.reduce((sum, r) => sum + r.unknownSymbols.length, 0);
+  const passed = totalStale === 0 && totalUnknown === 0;
+
+  return { passed, results, totalStale, totalUnknown };
+}