@flyingrobots/graft 0.7.0 → 0.8.0

package/src/warp/symbol-timeline.ts

@@ -1,209 +0,0 @@
-/**
- * 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

@@ -1,61 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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

@@ -1,47 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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

@@ -1,65 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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,
-  };
-}

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

@@ -1,309 +0,0 @@
-// ---------------------------------------------------------------------------
-// WARP-based Structural Churn — aggregate-backed graph query
-// ---------------------------------------------------------------------------
-
-import type { AggregateResult, QueryResultV1, TickReceipt } from "@git-stunts/git-warp";
-import type { WarpContext } from "./context.js";
-import { observeGraph } from "./context.js";
-
-export interface ChurnEntry {
-  readonly symbol: string;
-  readonly filePath: string;
-  readonly kind: string;
-  readonly changeCount: number;
-  readonly lastChangedSha: string;
-  readonly lastChangedDate: string;
-}
-
-export interface StructuralChurnResult {
-  readonly entries: readonly ChurnEntry[];
-  readonly totalSymbols: number;
-  readonly totalCommitsAnalyzed: number;
-  readonly summary: string;
-}
-
-/** Options for WARP-based churn analysis. */
-export interface WarpChurnOptions {
-  readonly limit?: number;
-  readonly path?: string;
-}
-
-const CHANGE_EDGE_LABELS = ["adds", "changes", "removes"] as const;
-type ChangeEdgeLabel = typeof CHANGE_EDGE_LABELS[number];
-
-interface ChurnCandidate {
-  readonly id: string;
-  readonly symbol: string;
-  readonly filePath: string;
-  readonly kind: string;
-}
-
-interface ChurnDiscovery {
-  readonly candidates: readonly ChurnCandidate[];
-  readonly receipts: readonly TickReceipt[];
-}
-
-/**
- * Compute structural churn entirely from the WARP graph.
- *
- * The count itself is computed with QueryBuilder.aggregate() over
- * commit nodes whose outgoing structural-change edges touch each symbol.
- * This keeps commit enumeration and per-symbol count accumulation inside
- * WARP instead of walking every commit in this operation.
- */
-export async function structuralChurnFromGraph(
-  ctx: WarpContext,
-  options?: WarpChurnOptions,
-): Promise<StructuralChurnResult> {
-  const limit = options?.limit ?? 20;
-  const pathFilter = options?.path;
-
-  const obs = await observeGraph(ctx, {
-    match: ["commit:*", "sym:*"],
-    expose: ["sha", "tick", "name", "kind"],
-  });
-
-  const totalCommitsAnalyzed = await countCommits(obs);
-  if (totalCommitsAnalyzed === 0) {
-    return { entries: [], totalSymbols: 0, totalCommitsAnalyzed: 0, summary: "No indexed commits." };
-  }
-
-  const discovery = await discoverChurnCandidates(ctx, obs, pathFilter);
-  const scored = await Promise.all(discovery.candidates.map(async (candidate): Promise<ChurnEntry | null> => {
-    const touch = await aggregateTouchesForSymbol(obs, candidate.id, discovery.receipts);
-    if (touch.changeCount === 0 || touch.lastChangedTick === null) return null;
-
-    return {
-      symbol: candidate.symbol,
-      filePath: candidate.filePath,
-      kind: candidate.kind,
-      changeCount: touch.changeCount,
-      lastChangedSha: await shaForTick(obs, touch.lastChangedTick),
-      lastChangedDate: "",
-    };
-  }));
-
-  const sorted = scored
-    .filter((entry): entry is ChurnEntry => entry !== null)
-    .sort((a, b) => b.changeCount - a.changeCount);
-
-  const entries = sorted.slice(0, limit);
-  const top = entries[0];
-  const topName = top?.symbol ?? "none";
-  const topCount = top?.changeCount ?? 0;
-  const summary = entries.length === 0
-    ? "No structural changes found."
-    : `${String(sorted.length)} symbols across ${String(totalCommitsAnalyzed)} commits. Hottest: ${topName} (${String(topCount)} changes).`;
-
-  return {
-    entries,
-    totalSymbols: sorted.length,
-    totalCommitsAnalyzed,
-    summary,
-  };
-}
-
-async function countCommits(
-  obs: Awaited<ReturnType<typeof observeGraph>>,
-): Promise<number> {
-  const result = await obs.query()
-    .match("commit:*")
-    .aggregate({ count: true })
-    .run() as AggregateResult;
-  return result.count ?? 0;
-}
-
-async function discoverChurnCandidates(
-  ctx: WarpContext,
-  obs: Awaited<ReturnType<typeof observeGraph>>,
-  pathFilter: string | undefined,
-): Promise<ChurnDiscovery> {
-  const candidates: ChurnCandidate[] = [];
-
-  const current = await obs.query()
-    .match("sym:*")
-    .select(["id", "props"])
-    .run() as QueryResultV1;
-
-  for (const node of current.nodes) {
-    if (node.id === undefined) continue;
-    const parsed = parseSymId(node.id);
-    if (parsed === null) continue;
-    if (!matchesPathFilter(parsed.filePath, pathFilter)) continue;
-
-    candidates.push({
-      id: node.id,
-      symbol: parsed.symbol,
-      filePath: parsed.filePath,
-      kind: typeof node.props?.["kind"] === "string" ? node.props["kind"] : "unknown",
-    });
-  }
-
-  const { receipts } = await ctx.app.core().materialize({ receipts: true });
-  for (const symId of removedSymIds(receipts)) {
-    if (candidates.some((candidate) => candidate.id === symId)) continue;
-
-    const parsed = parseSymId(symId);
-    if (parsed === null) continue;
-    if (!matchesPathFilter(parsed.filePath, pathFilter)) continue;
-
-    candidates.push({
-      id: symId,
-      symbol: parsed.symbol,
-      filePath: parsed.filePath,
-      kind: await removedSymbolKind(ctx, symId, receipts),
-    });
-  }
-
-  return { candidates, receipts };
-}
-
-function removedSymIds(receipts: readonly TickReceipt[]): string[] {
-  const ids: string[] = [];
-  for (const receipt of receipts) {
-    for (const op of receipt.ops) {
-      if (op.op !== "NodeTombstone" || op.result !== "applied" || !op.target.startsWith("sym:")) continue;
-      if (!ids.includes(op.target)) {
-        ids.push(op.target);
-      }
-    }
-  }
-  return ids;
-}
-
-async function removedSymbolKind(
-  ctx: WarpContext,
-  symId: string,
-  receipts: readonly TickReceipt[],
-): Promise<string> {
-  const removalTicks = receipts
-    .filter((receipt) => receipt.ops.some((op) =>
-      op.op === "NodeTombstone" &&
-      op.result === "applied" &&
-      op.target === symId,
-    ))
-    .map((receipt) => receipt.lamport)
-    .sort((a, b) => b - a);
-
-  const lastRemovalTick = removalTicks[0];
-  if (lastRemovalTick === undefined || lastRemovalTick <= 1) return "unknown";
-
-  const beforeRemoval = await observeGraph(
-    ctx,
-    { match: symId, expose: ["kind"] },
-    { source: { kind: "live", ceiling: lastRemovalTick - 1 } },
-  );
-  const props = await beforeRemoval.getNodeProps(symId);
-  return typeof props?.["kind"] === "string" ? props["kind"] : "unknown";
-}
-
-async function aggregateTouchesForSymbol(
-  obs: Awaited<ReturnType<typeof observeGraph>>,
-  symId: string,
-  receipts: readonly TickReceipt[],
-): Promise<{ changeCount: number; lastChangedTick: number | null }> {
-  const aggregates = await Promise.all(
-    CHANGE_EDGE_LABELS.map((label) => aggregateTouchesForLabel(obs, symId, label)),
-  );
-
-  const changeCount = aggregates.reduce((sum, result) => sum + result.count, 0);
-  const lastChangedTick = aggregates.reduce<number | null>((latest, result) => {
-    if (result.maxTick === null) return latest;
-    if (latest === null || result.maxTick > latest) return result.maxTick;
-    return latest;
-  }, null);
-
-  if (changeCount > 0) {
-    return { changeCount, lastChangedTick };
-  }
-
-  // QueryBuilder starts from live node sets; a tombstoned sym can be
-  // discovered from tick receipts but cannot be matched as a live node.
-  // Use the receipt edge-add outcomes as the WARP-native fallback for
-  // symbols whose final state is removed.
-  return receiptTouchesForSymbol(symId, receipts);
-}
-
-async function aggregateTouchesForLabel(
-  obs: Awaited<ReturnType<typeof observeGraph>>,
-  symId: string,
-  label: ChangeEdgeLabel,
-): Promise<{ count: number; maxTick: number | null }> {
-  const result = await obs.query()
-    .match("commit:*")
-    .where((node) => node.edgesOut.some((edge) => edge.label === label && edge.to === symId))
-    .aggregate({ count: true, max: "tick" })
-    .run() as AggregateResult;
-
-  return {
-    count: result.count ?? 0,
-    maxTick: typeof result.max === "number" && result.max > 0 ? result.max : null,
-  };
-}
-
-async function shaForTick(
-  obs: Awaited<ReturnType<typeof observeGraph>>,
-  tick: number,
-): Promise<string> {
-  const result = await obs.query()
-    .match("commit:*")
-    .where({ tick })
-    .select(["id", "props"])
-    .run() as QueryResultV1;
-
-  const commit = result.nodes[0];
-  if (commit === undefined) return "";
-  return typeof commit.props?.["sha"] === "string"
-    ? commit.props["sha"]
-    : commit.id?.slice("commit:".length) ?? "";
-}
-
-function parseSymId(symId: string): { filePath: string; symbol: string } | null {
-  if (!symId.startsWith("sym:")) return null;
-
-  const withoutPrefix = symId.slice("sym:".length);
-  const lastColon = withoutPrefix.lastIndexOf(":");
-  if (lastColon === -1) return null;
-
-  return {
-    filePath: withoutPrefix.slice(0, lastColon),
-    symbol: withoutPrefix.slice(lastColon + 1),
-  };
-}
-
-function matchesPathFilter(filePath: string, pathFilter: string | undefined): boolean {
-  return pathFilter === undefined || filePath.startsWith(pathFilter);
-}
-
-function receiptTouchesForSymbol(
-  symId: string,
-  receipts: readonly TickReceipt[],
-): { changeCount: number; lastChangedTick: number | null } {
-  let changeCount = 0;
-  let lastChangedTick: number | null = null;
-
-  for (const receipt of receipts) {
-    for (const op of receipt.ops) {
-      if (op.op !== "EdgeAdd" || op.result !== "applied") continue;
-      if (!isChangeEdgeToSymbol(op.target, symId)) continue;
-
-      changeCount++;
-      if (lastChangedTick === null || receipt.lamport > lastChangedTick) {
-        lastChangedTick = receipt.lamport;
-      }
-    }
-  }
-
-  return { changeCount, lastChangedTick };
-}
-
-function isChangeEdgeToSymbol(edgeKey: string, symId: string): boolean {
-  const [from, to, label] = edgeKey.split("\0");
-  return from?.startsWith("commit:") === true &&
-    to === symId &&
-    isChangeEdgeLabel(label);
-}
-
-function isChangeEdgeLabel(label: string | undefined): label is ChangeEdgeLabel {
-  return CHANGE_EDGE_LABELS.some((candidate) => candidate === label);
-}