@flyingrobots/graft 0.7.0 → 0.8.0

package/src/warp/observers.ts

@@ -1,101 +0,0 @@
-/**
- * WARP Observer Factory — canonical observer lenses for graft queries.
- *
- * Observer Law: this module READS through observers. It never
- * walks the graph directly, maintains shadow state, or implements
- * traversal algorithms.
- *
- * Each function returns a lens or an observer with a focused lens.
- * The lens determines the aperture — what the observer can see.
- */
-
-import type { Lens, Observer } from "@git-stunts/git-warp";
-import type { WarpContext } from "./context.js";
-import { observeGraph } from "./context.js";
-
-export type { Lens };
-
-/**
- * Observe all symbols in a specific file.
- * Aperture: sym:<path>:*
- */
-export function fileSymbolsLens(filePath: string): Lens {
-  return {
-    match: `sym:${filePath}:*`,
-    expose: ["name", "kind", "signature", "exported", "startLine", "endLine", "symbolPath", "identityId"],
-  };
-}
-
-/**
- * Observe all symbols in the project.
- * Aperture: sym:*
- */
-export function allSymbolsLens(): Lens {
-  return {
-    match: "sym:*",
-    expose: ["name", "kind", "signature", "exported", "startLine", "endLine", "symbolPath", "identityId"],
-  };
-}
-
-/**
- * Observe all files in the project.
- * Aperture: file:*
- */
-export function allFilesLens(): Lens {
-  return {
-    match: "file:*",
-    expose: ["path", "lang"],
-  };
-}
-
-/**
- * Observe a single symbol by name across all files.
- * Aperture: sym:*:<name>
- */
-export function symbolByNameLens(symbolName: string): Lens {
-  return {
-    match: `sym:*:${symbolName}`,
-    expose: ["name", "kind", "signature", "exported", "startLine", "endLine", "symbolPath", "identityId"],
-  };
-}
-
-/**
- * Observe a directory subtree.
- * Aperture: dir:<path>*
- */
-export function directoryLens(dirPath: string): Lens {
-  return {
-    match: `dir:${dirPath}*`,
-    expose: ["path"],
-  };
-}
-
-/**
- * Observe all files under a directory.
- * Aperture: file:<path>/*
- */
-export function directoryFilesLens(dirPath: string): Lens {
-  return {
-    match: `file:${dirPath}/*`,
-    expose: ["path", "lang"],
-  };
-}
-
-/**
- * Observe commit metadata.
- * Aperture: commit:*
- */
-export function commitsLens(): Lens {
-  return {
-    match: "commit:*",
-    expose: ["sha", "message", "timestamp", "author", "email", "tick"],
-  };
-}
-
-/**
- * Create an observer on the current frontier with a given lens.
- * Observers are static snapshots — create a new one after writes.
- */
-export function observe(ctx: WarpContext, lens: Lens): Promise<Observer> {
-  return observeGraph(ctx, lens);
-}

package/src/warp/open.ts

@@ -1,67 +0,0 @@
-/**
- * WARP graph initialization — opens the graft-ast graph backed by
- * the repo's own .git directory.
- *
- * Sole construction adapter. After this, git-warp types flow directly.
- */
-
-import WarpApp, { GitGraphAdapter } from "@git-stunts/git-warp";
-import GitPlumbing from "@git-stunts/plumbing";
-import { DEFAULT_WARP_WRITER_ID } from "./writer-id.js";
-
-export const GRAPH_NAME = "graft-ast";
-export const DEFAULT_WARP_CHECKPOINT_EVERY = 128;
-const WARP_GIT_MAX_BUFFER_BYTES = 128 * 1024 * 1024;
-
-interface GitExecuteOptions {
-  readonly args: string[];
-  readonly input?: string | Uint8Array;
-  readonly env?: Record<string, string>;
-  readonly maxBytes?: number;
-}
-
-interface GitStreamLike {
-  readonly finished: Promise<{ code: number; stderr: string; error?: Error | undefined }>;
-  collect(opts?: { maxBytes?: number; asString?: boolean; encoding?: string }): Promise<Uint8Array | string>;
-  [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
-}
-
-function raiseWarpGitBufferLimit(plumbing: GitPlumbing): GitPlumbing {
-  const execute = plumbing.execute.bind(plumbing);
-  plumbing.execute = ((options: GitExecuteOptions) => execute({
-    ...options,
-    maxBytes: options.maxBytes ?? WARP_GIT_MAX_BUFFER_BYTES,
-  })) as GitPlumbing["execute"];
-
-  const executeStream = plumbing.executeStream.bind(plumbing);
-  plumbing.executeStream = (async (options: { args: string[]; input?: string | Uint8Array; env?: Record<string, string> }) => {
-    const stream = await executeStream(options);
-    const collect = stream.collect.bind(stream);
-    stream.collect = (opts = {}) => collect({
-      ...opts,
-      maxBytes: opts.maxBytes ?? WARP_GIT_MAX_BUFFER_BYTES,
-    });
-    return stream as GitStreamLike;
-  }) as GitPlumbing["executeStream"];
-
-  return plumbing;
-}
-
-export interface OpenWarpOptions {
-  readonly cwd: string;
-  readonly writerId?: string;
-  readonly checkpointEvery?: number;
-}
-
-export async function openWarp(options: OpenWarpOptions): Promise<WarpApp> {
-  const plumbing = raiseWarpGitBufferLimit(GitPlumbing.createDefault({ cwd: options.cwd }));
-  const persistence = new GitGraphAdapter({ plumbing });
-
-  return WarpApp.open({
-    persistence,
-    graphName: GRAPH_NAME,
-    writerId: options.writerId ?? DEFAULT_WARP_WRITER_ID,
-    checkpointPolicy: { every: options.checkpointEvery ?? DEFAULT_WARP_CHECKPOINT_EVERY },
-    onDeleteWithData: "cascade",
-  });
-}

package/src/warp/outline-diff-trailer.ts

@@ -1,100 +0,0 @@
-// ---------------------------------------------------------------------------
-// Outline Diff Commit Trailer — structural summary in git commit messages
-// ---------------------------------------------------------------------------
-
-/** A single symbol change to include in the trailer. */
-export interface SymbolDiffEntry {
-  readonly name: string;
-  readonly kind: string;
-  readonly changeKind: "added" | "removed" | "changed";
-}
-
-/** Options for trailer formatting. */
-export interface TrailerOptions {
-  /** Maximum entries before truncation. Default: 20. */
-  readonly maxEntries?: number;
-}
-
-/** Short kind abbreviations for the trailer format. */
-const KIND_ABBREV: Readonly<Record<string, string>> = {
-  function: "fn",
-  class: "class",
-  interface: "iface",
-  type: "type",
-  variable: "var",
-  method: "method",
-  property: "prop",
-};
-
-function abbrevKind(kind: string): string {
-  return KIND_ABBREV[kind] ?? kind;
-}
-
-/**
- * Format a list of symbol changes as a Git commit trailer.
- *
- * Format: `Structural-Diff: added fn:X; removed class:Y; changed fn:Z`
- *
- * Returns empty string if there are no changes.
- */
-export function formatStructuralDiffTrailer(
-  entries: readonly SymbolDiffEntry[],
-  options?: TrailerOptions,
-): string {
-  if (entries.length === 0) return "";
-
-  const max = options?.maxEntries ?? 20;
-  const display = entries.slice(0, max);
-  const parts = display.map(
-    (e) => `${e.changeKind} ${abbrevKind(e.kind)}:${e.name}`,
-  );
-
-  let trailer = `Structural-Diff: ${parts.join("; ")}`;
-
-  if (entries.length > max) {
-    trailer += `; ... (${String(entries.length)} total)`;
-  }
-
-  return trailer;
-}
-
-// ---------------------------------------------------------------------------
-// Parser
-// ---------------------------------------------------------------------------
-
-const TRAILER_PREFIX = "Structural-Diff:";
-
-const ENTRY_RE = /^(added|removed|changed)\s+(\w+):(\w+)$/;
-
-/**
- * Parse a Structural-Diff trailer back into structured entries.
- *
- * Skips malformed entries gracefully.
- */
-export function parseStructuralDiffTrailer(text: string): SymbolDiffEntry[] {
-  const idx = text.indexOf(TRAILER_PREFIX);
-  if (idx === -1) return [];
-
-  const body = text.slice(idx + TRAILER_PREFIX.length).trim();
-  const parts = body.split(";").map((p) => p.trim());
-  const results: SymbolDiffEntry[] = [];
-
-  for (const part of parts) {
-    if (part.startsWith("...")) continue;
-    const match = ENTRY_RE.exec(part);
-    if (match === null) continue;
-
-    const changeKind = match[1] as "added" | "removed" | "changed";
-    const abbrev = match[2] ?? "unknown";
-    const name = match[3] ?? "unknown";
-
-    // Reverse the abbreviation
-    const kind = Object.entries(KIND_ABBREV).find(
-      ([, v]) => v === abbrev,
-    )?.[0] ?? abbrev;
-
-    results.push({ name, kind, changeKind });
-  }
-
-  return results;
-}

package/src/warp/plumbing.d.ts

@@ -1,24 +0,0 @@
-declare module "@git-stunts/plumbing" {
-  import type { GitPlumbing as GitPlumbingInterface } from "@git-stunts/git-warp";
-
-  export default class GitPlumbing implements GitPlumbingInterface {
-    readonly emptyTree: string;
-    constructor(options: { runner: unknown; cwd?: string });
-    static createDefault(options?: { cwd?: string; env?: string }): GitPlumbing;
-    execute(options: {
-      args: string[];
-      input?: string | Uint8Array;
-      env?: Record<string, string>;
-      maxBytes?: number;
-    }): Promise<string>;
-    executeStream(options: {
-      args: string[];
-      input?: string | Uint8Array;
-      env?: Record<string, string>;
-    }): Promise<{
-      finished: Promise<{ code: number; stderr: string; error?: Error }>;
-      collect(opts?: { maxBytes?: number; asString?: boolean; encoding?: string }): Promise<Uint8Array | string>;
-      [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
-    }>;
-  }
-}

package/src/warp/refactor-difficulty.ts

@@ -1,257 +0,0 @@
-// ---------------------------------------------------------------------------
-// Refactor Difficulty — curvature x friction over WARP facts
-// ---------------------------------------------------------------------------
-
-import type { AggregateResult, QueryResultV1 } from "@git-stunts/git-warp";
-import type { WarpContext } from "./context.js";
-import { observeGraph } from "./context.js";
-import { symbolTimeline, type SymbolVersion } from "./symbol-timeline.js";
-import { countSymbolReferencesFromGraph } from "./warp-reference-count.js";
-
-const CHANGE_EDGE_LABELS = ["adds", "changes", "removes"] as const;
-
-export type RefactorDifficultyRisk = "low" | "medium" | "high";
-
-export type RefactorDifficultyRecommendation =
-  | "refactor_freely"
-  | "refactor_with_tests"
-  | "plan_before_refactor";
-
-export interface RefactorDifficultyOptions {
-  readonly symbol: string;
-  readonly path?: string | undefined;
-  readonly limit?: number | undefined;
-}
-
-export interface RefactorDifficultyAxis {
-  readonly score: number;
-}
-
-export interface RefactorDifficultyCurvature extends RefactorDifficultyAxis {
-  readonly changeCount: number;
-  readonly signatureChangeCount: number;
-}
-
-export interface RefactorDifficultyFriction extends RefactorDifficultyAxis {
-  readonly referenceCount: number;
-  readonly referencingFiles: readonly string[];
-}
-
-export interface RefactorDifficultyEntry {
-  readonly symbol: string;
-  readonly filePath: string;
-  readonly kind: string;
-  readonly score: number;
-  readonly risk: RefactorDifficultyRisk;
-  readonly recommendation: RefactorDifficultyRecommendation;
-  readonly curvature: RefactorDifficultyCurvature;
-  readonly friction: RefactorDifficultyFriction;
-}
-
-export interface RefactorDifficultyResult {
-  readonly symbol: string;
-  readonly path?: string | undefined;
-  readonly entries: readonly RefactorDifficultyEntry[];
-  readonly total: number;
-  readonly summary: string;
-}
-
-interface SymbolCandidate {
-  readonly id: string;
-  readonly symbol: string;
-  readonly filePath: string;
-  readonly kind: string;
-}
-
-export async function refactorDifficultyFromGraph(
-  ctx: WarpContext,
-  options: RefactorDifficultyOptions,
-): Promise<RefactorDifficultyResult> {
-  const symbol = options.symbol.trim();
-  if (symbol.length === 0) {
-    throw new Error("refactorDifficultyFromGraph: symbol must be non-empty");
-  }
-
-  const pathFilter = normalizeOptionalPath(options.path);
-  const limit = options.limit ?? 20;
-  const candidates = await findSymbolCandidates(ctx, symbol, pathFilter);
-  const entries = await Promise.all(
-    candidates.map((candidate) => scoreCandidate(ctx, candidate)),
-  );
-
-  const sorted = entries.sort(compareDifficultyEntries).slice(0, limit);
-  const top = sorted[0];
-  const summary = top === undefined
-    ? `No indexed symbols matched ${symbol}.`
-    : `${String(entries.length)} symbol matches. Highest difficulty: ${top.symbol} in ${top.filePath} (${String(top.score)}).`;
-
-  return {
-    symbol,
-    ...(pathFilter !== undefined ? { path: pathFilter } : {}),
-    entries: sorted,
-    total: entries.length,
-    summary,
-  };
-}
-
-async function findSymbolCandidates(
-  ctx: WarpContext,
-  symbol: string,
-  pathFilter: string | undefined,
-): Promise<SymbolCandidate[]> {
-  const obs = await observeGraph(ctx, {
-    match: "sym:*",
-    expose: ["name", "kind", "filePath"],
-  });
-
-  const result = await obs.query()
-    .match("sym:*")
-    .where((node) => {
-      const parsed = parseSymId(node.id);
-      if (parsed === null) return false;
-      if (!matchesPathFilter(parsed.filePath, pathFilter)) return false;
-
-      const propName = typeof node.props["name"] === "string" ? node.props["name"] : "";
-      return parsed.symbol === symbol || propName === symbol;
-    })
-    .select(["id", "props"])
-    .run() as QueryResultV1;
-
-  const candidates: SymbolCandidate[] = [];
-  for (const node of result.nodes) {
-    if (node.id === undefined) continue;
-    const parsed = parseSymId(node.id);
-    if (parsed === null) continue;
-
-    candidates.push({
-      id: node.id,
-      symbol: parsed.symbol,
-      filePath: parsed.filePath,
-      kind: typeof node.props?.["kind"] === "string" ? node.props["kind"] : "unknown",
-    });
-  }
-  return candidates;
-}
-
-async function scoreCandidate(
-  ctx: WarpContext,
-  candidate: SymbolCandidate,
-): Promise<RefactorDifficultyEntry> {
-  const [changeCount, timeline, references] = await Promise.all([
-    countSymbolTouches(ctx, candidate.id),
-    symbolTimeline(ctx, candidate.symbol, candidate.filePath),
-    countSymbolReferencesFromGraph(ctx, candidate.symbol, candidate.filePath),
-  ]);
-
-  const signatureChangeCount = countSignatureChanges(timeline.versions);
-  const curvatureScore = changeCount + signatureChangeCount;
-  const frictionScore = references.referenceCount;
-  const score = curvatureScore * frictionScore;
-
-  return {
-    symbol: candidate.symbol,
-    filePath: candidate.filePath,
-    kind: candidate.kind,
-    score,
-    risk: riskForScore(score),
-    recommendation: recommendationForScore(score),
-    curvature: {
-      changeCount,
-      signatureChangeCount,
-      score: curvatureScore,
-    },
-    friction: {
-      referenceCount: references.referenceCount,
-      referencingFiles: references.referencingFiles,
-      score: frictionScore,
-    },
-  };
-}
-
-async function countSymbolTouches(
-  ctx: WarpContext,
-  symId: string,
-): Promise<number> {
-  const obs = await observeGraph(ctx, {
-    match: ["commit:*", "sym:*"],
-    expose: ["tick"],
-  });
-
-  const counts = await Promise.all(CHANGE_EDGE_LABELS.map(async (label): Promise<number> => {
-    const result = await obs.query()
-      .match("commit:*")
-      .where((node) => node.edgesOut.some((edge) => edge.label === label && edge.to === symId))
-      .aggregate({ count: true })
-      .run() as AggregateResult;
-    return result.count ?? 0;
-  }));
-
-  return counts.reduce((sum, count) => sum + count, 0);
-}
-
-function countSignatureChanges(versions: readonly SymbolVersion[]): number {
-  let lastSignature: string | undefined;
-  let changes = 0;
-
-  for (const version of versions) {
-    if (version.signature === undefined) continue;
-    if (lastSignature === undefined) {
-      lastSignature = version.signature;
-      continue;
-    }
-    if (version.signature !== lastSignature) {
-      changes++;
-      lastSignature = version.signature;
-    }
-  }
-
-  return changes;
-}
-
-function riskForScore(score: number): RefactorDifficultyRisk {
-  if (score >= 12) return "high";
-  if (score >= 4) return "medium";
-  return "low";
-}
-
-function recommendationForScore(score: number): RefactorDifficultyRecommendation {
-  if (score >= 12) return "plan_before_refactor";
-  if (score >= 4) return "refactor_with_tests";
-  return "refactor_freely";
-}
-
-function compareDifficultyEntries(
-  left: RefactorDifficultyEntry,
-  right: RefactorDifficultyEntry,
-): number {
-  return right.score - left.score ||
-    right.curvature.score - left.curvature.score ||
-    right.friction.score - left.friction.score ||
-    left.filePath.localeCompare(right.filePath) ||
-    left.symbol.localeCompare(right.symbol);
-}
-
-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 normalizeOptionalPath(path: string | undefined): string | undefined {
-  if (path === undefined) return undefined;
-  const trimmed = path.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}
-
-function matchesPathFilter(filePath: string, pathFilter: string | undefined): boolean {
-  return pathFilter === undefined ||
-    filePath === pathFilter ||
-    filePath.startsWith(`${pathFilter}/`);
-}

package/src/warp/references.ts

@@ -1,77 +0,0 @@
-// ---------------------------------------------------------------------------
-// Symbol reference queries — find what depends on a symbol via the WARP graph
-// ---------------------------------------------------------------------------
-
-import type { QueryResultV1 } from "@git-stunts/git-warp";
-import type { WarpContext } from "./context.js";
-import { observeGraph } from "./context.js";
-
-export interface SymbolReference {
-  readonly filePath: string;
-  readonly importedName: string;
-  readonly localName: string;
-}
-
-/**
- * Find all files that reference a symbol, by querying the WARP graph's
- * cross-file import resolution edges.
- *
- * Uses traverse.bfs for edge discovery (substrate-side) and QueryBuilder
- * for batch prop reads. No getEdges() — never assumes all edges fit in
- * memory.
- *
- * For named symbols: finds import_specifier/export_specifier nodes that
- * have a `references` edge pointing at `sym:<filePath>:<symbolName>`.
- *
- * For namespace imports ("*"): finds namespace_import nodes that have a
- * `references` edge pointing at `file:<filePath>`.
- */
-export async function referencesForSymbol(
-  ctx: WarpContext,
-  symbolName: string,
-  filePath: string,
-): Promise<SymbolReference[]> {
-  const obs = await observeGraph(ctx, { match: ["ast:*", "file:*", "sym:*"] });
-
-  // Determine the target node ID
-  const targetId = symbolName === "*"
-    ? `file:${filePath}`
-    : `sym:${filePath}:${symbolName}`;
-
-  // Guard: target must exist for traverse to work.
-  const targetExists = await obs.hasNode(targetId);
-  if (!targetExists) return [];
-
-  // Traverse: find AST nodes with incoming `references` edges to the target.
-  const referrerIds = await obs.traverse.bfs(targetId, {
-    dir: "in",
-    labelFilter: "references",
-    maxDepth: 1,
-  });
-
-  const astReferrerIds = referrerIds.filter((id) => id.startsWith("ast:"));
-  if (astReferrerIds.length === 0) return [];
-
-  // Batch prop read for all referencing nodes.
-  const propsResult = await obs.query()
-    .match(astReferrerIds)
-    .select(["id", "props"])
-    .run() as QueryResultV1;
-
-  const results: SymbolReference[] = [];
-
-  for (const node of propsResult.nodes) {
-    if (node.id === undefined) continue;
-    const props = node.props ?? {};
-
-    const importedName = typeof props["importedName"] === "string" ? props["importedName"] : symbolName;
-    const localName = typeof props["localName"] === "string" ? props["localName"] : importedName;
-    const nodeFilePath = typeof props["filePath"] === "string" ? props["filePath"] : null;
-
-    if (nodeFilePath !== null) {
-      results.push({ filePath: nodeFilePath, importedName, localName });
-    }
-  }
-
-  return results;
-}