@flyingrobots/graft 0.6.0 → 0.7.0

package/src/warp/structural-queries.ts

@@ -0,0 +1,258 @@
+/**
+ * WARP Structural Query Helpers — commit-symbol traversals.
+ *
+ * Shared infrastructure for graft log, graft blame, and graft churn.
+ * Uses traverse for edge-following and QueryBuilder for pattern matching
+ * and batch prop reads. No getEdges() — filtering stays substrate-side.
+ */
+
+import type { Lens, QueryResultV1 } from "@git-stunts/git-warp";
+import type { WarpContext } from "./context.js";
+import { observeGraph } from "./context.js";
+import { symbolTimeline } from "./symbol-timeline.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A symbol that was added, removed, or changed in a commit. */
+export interface SymbolChange {
+  readonly name: string;
+  readonly kind: string;
+  readonly signature?: string | undefined;
+  readonly exported: boolean;
+  readonly filePath: string;
+}
+
+/** All symbol changes for a single commit. */
+export interface CommitSymbols {
+  readonly sha: string;
+  readonly added: readonly SymbolChange[];
+  readonly removed: readonly SymbolChange[];
+  readonly changed: readonly SymbolChange[];
+}
+
+/** The kind of change a commit made to a symbol. */
+export type ChangeKind = "added" | "removed" | "changed";
+
+/** A single commit entry in a symbol's history. */
+export interface SymbolCommit {
+  readonly sha: string;
+  readonly changeKind: ChangeKind;
+  readonly signature?: string | undefined;
+}
+
+/** Full change history for a symbol across commits. */
+export interface SymbolHistory {
+  readonly symbol: string;
+  readonly filePath?: string | undefined;
+  readonly commits: readonly SymbolCommit[];
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Lens that spans both commit and symbol nodes so the observer
+ * can see the edges between them.
+ */
+function commitSymbolLens(): Lens {
+  return {
+    match: ["commit:*", "sym:*"],
+    expose: ["sha", "name", "kind", "signature", "exported"],
+  };
+}
+
+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);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Given a commit SHA, return all symbols that were added, removed,
+ * or changed in that commit.
+ *
+ * Uses traverse for edge-following (substrate-side), then QueryBuilder
+ * for batch prop reads. Removals are detected by temporal diff at
+ * tick N-1 vs tick N.
+ */
+export async function symbolsForCommit(
+  ctx: WarpContext,
+  commitSha: string,
+): Promise<CommitSymbols> {
+  const commitId = `commit:${commitSha}`;
+
+  // Read the commit's tick for removal detection.
+  const commitObs = await observeGraph(ctx,
+    { match: commitId, expose: ["tick"] },
+  );
+  const commitProps = await commitObs.getNodeProps(commitId);
+  const tick = typeof commitProps?.["tick"] === "number" ? commitProps["tick"] : null;
+
+  // Observer scoped to commit + symbol nodes.
+  const obs = await observeGraph(ctx, commitSymbolLens());
+
+  // Check if the commit node exists before traversing.
+  const commitExists = await obs.hasNode(commitId);
+  if (!commitExists) {
+    return { sha: commitSha, added: [], removed: [], changed: [] };
+  }
+
+  // Traverse: follow outgoing edges from this commit by label.
+  const [addedIds, changedIds] = await Promise.all([
+    obs.traverse.bfs(commitId, { dir: "out", labelFilter: "adds", maxDepth: 1 }),
+    obs.traverse.bfs(commitId, { dir: "out", labelFilter: "changes", maxDepth: 1 }),
+  ]);
+
+  // Batch prop read for discovered sym nodes.
+  const allSymIds = [...addedIds, ...changedIds].filter((id) => id.startsWith("sym:"));
+
+  const symPropsMap = new Map<string, Record<string, unknown>>();
+  if (allSymIds.length > 0) {
+    const propsResult = await obs.query()
+      .match(allSymIds)
+      .select(["id", "props"])
+      .run() as QueryResultV1;
+    for (const node of propsResult.nodes) {
+      if (node.id !== undefined && node.props !== undefined) {
+        symPropsMap.set(node.id, node.props);
+      }
+    }
+  }
+
+  function toSymbolChange(symId: string): SymbolChange {
+    const props = symPropsMap.get(symId) ?? {};
+    const name = typeof props["name"] === "string" ? props["name"] : symId;
+    const kind = typeof props["kind"] === "string" ? props["kind"] : "unknown";
+    const signature = typeof props["signature"] === "string" ? props["signature"] : undefined;
+    const exported = typeof props["exported"] === "boolean" ? props["exported"] : false;
+    const filePath = filePathFromSymId(symId);
+    return { name, kind, signature, exported, filePath };
+  }
+
+  const added = addedIds.filter((id) => id.startsWith("sym:")).map(toSymbolChange);
+  const changed = changedIds.filter((id) => id.startsWith("sym:")).map(toSymbolChange);
+
+  // Detect removals by temporal receipts across the Git commit's indexed
+  // Lamport window. Lazy indexing can write one WARP patch per file, so one
+  // Git commit may span multiple Lamport ticks.
+  let removed: SymbolChange[] = [];
+  if (tick !== null) {
+    removed = await detectRemovals(ctx, await previousCommitTick(ctx, commitSha, tick), tick);
+  }
+
+  return { sha: commitSha, added, removed, changed };
+}
+
+async function previousCommitTick(
+  ctx: WarpContext,
+  commitSha: string,
+  tick: number,
+): Promise<number> {
+  const obs = await observeGraph(ctx, { match: "commit:*", expose: ["sha", "tick"] });
+  const nodeIds = await obs.getNodes();
+  let previous = 0;
+
+  for (const nodeId of nodeIds) {
+    const props = await obs.getNodeProps(nodeId);
+    const sha = typeof props?.["sha"] === "string"
+      ? props["sha"]
+      : nodeId.slice("commit:".length);
+    if (sha === commitSha) continue;
+
+    const candidate = typeof props?.["tick"] === "number" ? props["tick"] : null;
+    if (candidate !== null && candidate < tick && candidate > previous) {
+      previous = candidate;
+    }
+  }
+
+  return previous;
+}
+
+/**
+ * Detect symbol removals via tick receipts.
+ *
+ * Instead of scanning all sym:* nodes at two ceilings (which assumes
+ * the full graph fits in memory), we materialize with receipts and inspect
+ * receipts in one Git commit's indexed Lamport window for NodeTombstone ops
+ * on sym nodes. O(ops in indexed file patches), not O(all sym nodes).
+ */
+async function detectRemovals(
+  ctx: WarpContext,
+  previousTick: number,
+  tick: number,
+): Promise<SymbolChange[]> {
+  // Use latest materialization and filter receipts locally. A ceiling
+  // materialization on the shared core would leave the app cached at an old
+  // tick, corrupting later live reads in the same operation.
+  const { receipts } = await ctx.app.core().materialize({ receipts: true });
+
+  const scopedReceipts = receipts.filter((receipt) =>
+    receipt.lamport > previousTick && receipt.lamport <= tick,
+  );
+  if (scopedReceipts.length === 0) return [];
+
+  // Tombstoned sym nodes = removals.
+  const removed = new Map<string, number>();
+  for (const receipt of scopedReceipts) {
+    for (const op of receipt.ops) {
+      if (op.op === "NodeTombstone" && op.target.startsWith("sym:") && op.result === "applied") {
+        removed.set(op.target, receipt.lamport);
+      }
+    }
+  }
+
+  if (removed.size === 0) return [];
+
+  // Read props from the pre-removal observer (nodes are gone at current tick).
+  const symLens: Lens = {
+    match: "sym:*",
+    expose: ["name", "kind", "signature", "exported"],
+  };
+
+  // Targeted per-node reads — bounded by removals in one commit.
+  const changes: SymbolChange[] = [];
+  for (const [id, removalTick] of removed) {
+    const beforeObs = await observeGraph(ctx, symLens, {
+      source: { kind: "live", ceiling: removalTick - 1 },
+    });
+    const props = await beforeObs.getNodeProps(id);
+    if (props === null) continue;
+
+    const name = typeof props["name"] === "string" ? props["name"] : id;
+    const kind = typeof props["kind"] === "string" ? props["kind"] : "unknown";
+    const signature = typeof props["signature"] === "string" ? props["signature"] : undefined;
+    const exported = typeof props["exported"] === "boolean" ? props["exported"] : false;
+    const filePath = filePathFromSymId(id);
+
+    changes.push({ name, kind, signature, exported, filePath });
+  }
+  return changes;
+}
+
+/** @deprecated Use symbolTimeline() from ./symbol-timeline.ts instead. */
+export async function commitsForSymbol(
+  ctx: WarpContext,
+  symbolName: string,
+  filePath?: string,
+): Promise<SymbolHistory> {
+  const timeline = await symbolTimeline(ctx, symbolName, filePath);
+  return {
+    symbol: symbolName,
+    filePath,
+    commits: timeline.versions.map((version) => ({
+      sha: version.sha,
+      changeKind: version.changeKind,
+      signature: version.signature,
+    })),
+  };
+}

package/src/warp/symbol-timeline.ts

@@ -0,0 +1,209 @@
+/**
+ * WARP Symbol Timeline — ordered history of a symbol across commits.
+ *
+ * Reads WARP provenance for symbol ids and reconstructs versions from
+ * patches that touched the symbol. Callers that need removed-symbol
+ * history must pass filePath so the symbol id is explicit.
+ */
+
+import type { PatchV2 } from "@git-stunts/git-warp";
+import { observeGraph, type WarpContext } from "./context.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single version of a symbol at a specific commit. */
+export interface SymbolVersion {
+  readonly sha: string;
+  readonly tick: number;
+  readonly changeKind: "added" | "changed" | "removed";
+  readonly present: boolean;
+  readonly signature?: string | undefined;
+  readonly startLine?: number | undefined;
+  readonly endLine?: number | undefined;
+  readonly filePath: string;
+}
+
+/** Full ordered timeline for a symbol across commits. */
+export interface SymbolTimelineResult {
+  readonly symbol: string;
+  readonly filePath?: string | undefined;
+  readonly versions: readonly SymbolVersion[];
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+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);
+}
+
+type ChangeKind = SymbolVersion["changeKind"];
+
+interface PatchOpView {
+  readonly type?: unknown;
+  readonly from?: unknown;
+  readonly to?: unknown;
+  readonly label?: unknown;
+}
+
+interface ProvenanceTimelineCore {
+  patchesFor(entityId: string): Promise<string[]>;
+  loadPatchBySha(sha: string): Promise<PatchV2>;
+}
+
+const EDGE_CHANGE_KIND = new Map<string, ChangeKind>([
+  ["adds", "added"],
+  ["changes", "changed"],
+  ["removes", "removed"],
+]);
+
+function symIdFor(filePath: string, symbolName: string): string {
+  return `sym:${filePath}:${symbolName}`;
+}
+
+function patchOps(patch: PatchV2): readonly PatchOpView[] {
+  return Array.isArray(patch.ops) ? patch.ops as readonly PatchOpView[] : [];
+}
+
+interface SymbolTouch {
+  readonly sha: string;
+  readonly tick: number;
+  readonly changeKind: ChangeKind;
+}
+
+function touchFromPatch(symId: string, patch: PatchV2): SymbolTouch | null {
+  const ops = patchOps(patch);
+
+  for (const op of ops) {
+    if (op.type !== "EdgeAdd") continue;
+    if (typeof op.from !== "string" || !op.from.startsWith("commit:")) continue;
+    if (op.to !== symId || typeof op.label !== "string") continue;
+
+    const changeKind = EDGE_CHANGE_KIND.get(op.label);
+    if (changeKind === undefined) continue;
+
+    return {
+      sha: op.from.slice("commit:".length),
+      tick: patch.lamport,
+      changeKind,
+    };
+  }
+
+  return null;
+}
+
+async function readSymbolPropsAtTick(
+  ctx: WarpContext,
+  symId: string,
+  tick: number,
+): Promise<Record<string, unknown> | null> {
+  const worldline = await ctx.app.worldline().seek({
+    source: { kind: "live", ceiling: tick },
+  });
+  return worldline.getNodeProps(symId);
+}
+
+async function versionFromPatch(
+  ctx: WarpContext,
+  symId: string,
+  patch: PatchV2,
+): Promise<SymbolVersion | null> {
+  const touch = touchFromPatch(symId, patch);
+  if (touch === null) {
+    return null;
+  }
+
+  const props = touch.changeKind === "removed"
+    ? null
+    : await readSymbolPropsAtTick(ctx, symId, touch.tick);
+  const signature = props?.["signature"];
+  const startLine = props?.["startLine"];
+  const endLine = props?.["endLine"];
+
+  return {
+    sha: touch.sha,
+    tick: touch.tick,
+    changeKind: touch.changeKind,
+    present: touch.changeKind !== "removed",
+    signature: typeof signature === "string" ? signature : undefined,
+    startLine: typeof startLine === "number" ? startLine : undefined,
+    endLine: typeof endLine === "number" ? endLine : undefined,
+    filePath: filePathFromSymId(symId),
+  };
+}
+
+async function liveSymbolIds(
+  ctx: WarpContext,
+  symbolName: string,
+  filePath: string | undefined,
+): Promise<readonly string[]> {
+  if (filePath !== undefined) {
+    return [symIdFor(filePath, symbolName)];
+  }
+
+  const obs = await observeGraph(ctx, { match: `sym:*:${symbolName}`, expose: [] });
+  return obs.getNodes();
+}
+
+async function readTimelineVersions(
+  ctx: WarpContext,
+  symbolName: string,
+  filePath: string | undefined,
+): Promise<SymbolVersion[]> {
+  const core = ctx.app.core() as unknown as ProvenanceTimelineCore;
+  const symIds = await liveSymbolIds(ctx, symbolName, filePath);
+  if (symIds.length === 0) return [];
+
+  const versions: SymbolVersion[] = [];
+  const seen = new Set<string>();
+
+  for (const symId of symIds) {
+    const patchShas = await core.patchesFor(symId);
+    const patches = await Promise.all(patchShas.map(async (sha) => core.loadPatchBySha(sha)));
+
+    for (const patch of patches) {
+      const version = await versionFromPatch(ctx, symId, patch);
+      if (version === null) continue;
+
+      const key = `${String(version.tick)}:${version.sha}:${symId}:${version.changeKind}`;
+      if (seen.has(key)) continue;
+
+      versions.push(version);
+      seen.add(key);
+    }
+  }
+
+  versions.sort((a, b) => a.tick - b.tick || a.filePath.localeCompare(b.filePath));
+  return versions;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an ordered timeline of every version of a symbol across commits.
+ *
+ * For each commit that touched the symbol (adds, changes, removes), the
+ * returned array includes the commit SHA, tick, change kind, presence
+ * flag, signature, and line range. Entries are sorted by tick ascending.
+ */
+export async function symbolTimeline(
+  ctx: WarpContext,
+  symbolName: string,
+  filePath?: string,
+): Promise<SymbolTimelineResult> {
+  return {
+    symbol: symbolName,
+    filePath,
+    versions: await readTimelineVersions(ctx, symbolName, filePath),
+  };
+}

package/src/warp/traverse-hydrate.ts

@@ -0,0 +1,61 @@
+// ---------------------------------------------------------------------------
+// Traverse + Query Batch Hydration Helper
+// ---------------------------------------------------------------------------
+
+import type { Observer, QueryResultV1 } from "@git-stunts/git-warp";
+
+/** A hydrated node with its ID and properties. */
+export interface HydratedNode {
+  readonly id: string;
+  readonly props: Readonly<Record<string, unknown>>;
+}
+
+/** Traversal options matching observer.traverse.bfs. */
+export interface TraverseOptions {
+  readonly dir: "out" | "in";
+  readonly labelFilter?: string;
+  readonly maxDepth?: number;
+}
+
+/**
+ * BFS traversal followed by batch property hydration.
+ *
+ * Combines two common operations into one call:
+ * 1. `observer.traverse.bfs()` for topology discovery
+ * 2. `observer.query().match(ids).select(["id", "props"]).run()` for batch hydration
+ *
+ * Returns hydrated nodes with both IDs and properties.
+ */
+export async function traverseAndHydrate(
+  observer: Observer,
+  startId: string,
+  options: TraverseOptions,
+): Promise<readonly HydratedNode[]> {
+  let ids: string[];
+  try {
+    const bfsOptions: {
+      dir: "out" | "in";
+      labelFilter?: string;
+      maxDepth?: number;
+    } = { dir: options.dir };
+    if (options.labelFilter !== undefined) bfsOptions.labelFilter = options.labelFilter;
+    if (options.maxDepth !== undefined) bfsOptions.maxDepth = options.maxDepth;
+    ids = await observer.traverse.bfs(startId, bfsOptions);
+  } catch {
+    return [];
+  }
+
+  if (ids.length === 0) return [];
+
+  const result = await observer.query()
+    .match(ids)
+    .select(["id", "props"])
+    .run() as QueryResultV1;
+
+  return result.nodes
+    .filter((n): n is { id: string; props?: Record<string, unknown> } => n.id !== undefined)
+    .map((n) => ({
+      id: n.id,
+      props: n.props ?? {},
+    }));
+}

package/src/warp/warp-reference-count.ts

@@ -0,0 +1,47 @@
+// ---------------------------------------------------------------------------
+// WARP-based symbol reference counting
+// ---------------------------------------------------------------------------
+
+import type { WarpContext } from "./context.js";
+import { referencesForSymbol } from "./references.js";
+
+export interface ReferenceCountResult {
+  readonly symbol: string;
+  readonly referenceCount: number;
+  readonly referencingFiles: readonly string[];
+}
+
+/**
+ * Count how many files reference a symbol via WARP graph edges.
+ *
+ * Uses `referencesForSymbol` which traverses incoming `references`
+ * edges from import/export specifier AST nodes to the target sym node.
+ * Uses actual imports, not text matches, and does not spawn subprocesses.
+ *
+ * @param ctx - WARP context
+ * @param symbolName - The symbol to count references for
+ * @param filePath - The file where the symbol is defined (required for sym node ID)
+ */
+export async function countSymbolReferencesFromGraph(
+  ctx: WarpContext,
+  symbolName: string,
+  filePath?: string,
+): Promise<ReferenceCountResult> {
+  if (filePath === undefined) {
+    // Without filePath we can't construct the sym node ID.
+    // Return empty — caller should provide filePath for accurate results.
+    return { symbol: symbolName, referenceCount: 0, referencingFiles: [] };
+  }
+
+  const refs = await referencesForSymbol(ctx, symbolName, filePath);
+
+  // Deduplicate by file path (multiple imports from the same file
+  // count as one referencing file).
+  const uniqueFiles = [...new Set(refs.map((r) => r.filePath))];
+
+  return {
+    symbol: symbolName,
+    referenceCount: uniqueFiles.length,
+    referencingFiles: uniqueFiles,
+  };
+}

package/src/warp/warp-structural-blame.ts

@@ -0,0 +1,65 @@
+// ---------------------------------------------------------------------------
+// WARP-based Structural Blame — replaces git-dependent blame pipeline
+// ---------------------------------------------------------------------------
+
+import type { WarpContext } from "./context.js";
+import { symbolTimeline, type SymbolVersion } from "./symbol-timeline.js";
+import { countSymbolReferencesFromGraph } from "./warp-reference-count.js";
+
+/** Blame result for a single symbol. */
+export interface WarpBlameResult {
+  readonly symbol: string;
+  readonly filePath: string;
+  readonly history: readonly SymbolVersion[];
+  readonly changeCount: number;
+  readonly createdInCommit: string | undefined;
+  readonly lastSignatureChange: string | undefined;
+  readonly referenceCount: number;
+}
+
+/**
+ * Compute structural blame for a symbol entirely from the WARP graph.
+ *
+ * Uses symbolTimeline for history, countSymbolReferencesFromGraph for
+ * reference counting. Zero git subprocess calls.
+ */
+export async function structuralBlameFromGraph(
+  ctx: WarpContext,
+  symbolName: string,
+  filePath: string,
+): Promise<WarpBlameResult> {
+  // Get full timeline from WARP
+  const timeline = await symbolTimeline(ctx, symbolName, filePath);
+
+  if (timeline.versions.length === 0) {
+    return {
+      symbol: symbolName,
+      filePath,
+      history: [],
+      changeCount: 0,
+      createdInCommit: undefined,
+      lastSignatureChange: undefined,
+      referenceCount: 0,
+    };
+  }
+
+  // Find creation commit (first "added" entry)
+  const created = timeline.versions.find((v) => v.changeKind === "added");
+
+  // Find last signature change (last "changed" entry)
+  const changes = timeline.versions.filter((v) => v.changeKind === "changed");
+  const lastChange = changes.length > 0 ? changes[changes.length - 1] : undefined;
+
+  // Count references from WARP graph
+  const refs = await countSymbolReferencesFromGraph(ctx, symbolName, filePath);
+
+  return {
+    symbol: symbolName,
+    filePath,
+    history: timeline.versions,
+    changeCount: timeline.versions.length,
+    createdInCommit: created?.sha,
+    lastSignatureChange: lastChange?.sha,
+    referenceCount: refs.referenceCount,
+  };
+}