@flyingrobots/graft 0.7.0 → 0.8.0

package/src/warp/dead-symbols.ts

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

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

package/src/warp/index-head.ts

@@ -1,348 +0,0 @@
-// ---------------------------------------------------------------------------
-// Index HEAD — emit compact structural facts into WARP.
-//
-// Also emits a commit node and commit→sym edges (adds/changes/removes)
-// so the structural query layer can detect what changed between ticks.
-// ---------------------------------------------------------------------------
-
-import { Buffer } from "node:buffer";
-import type { GitClient } from "../ports/git.js";
-import type { PathOps } from "../ports/paths.js";
-import type { WarpContext } from "./context.js";
-import type { PatchBuilderV2 } from "@git-stunts/git-warp";
-import { patchGraph, observeGraph, materializeGraph } from "./context.js";
-import { detectLang } from "../parser/lang.js";
-import { parseStructuredTree } from "../parser/runtime.js";
-import { extractOutlineForFile } from "../parser/outline.js";
-import { attachAstSnapshot, emitAstNodes } from "./ast-emitter.js";
-import { resolveImportEdges } from "./ast-import-resolver.js";
-import type { OutlineEntry } from "../parser/types.js";
-import { getCommitMeta } from "./commit-meta.js";
-
-export const DEFAULT_INDEX_MAX_FILES_PER_CALL = 64;
-export const DEFAULT_INDEX_MAX_PATCH_JSON_BYTES = 2 * 1024 * 1024;
-
-// ---------------------------------------------------------------------------
-// Sym-node emission from outline entries (richer than the AST-only walker:
-// includes signatures for change detection).
-// ---------------------------------------------------------------------------
-
-function emitOutlineSyms(
-  patch: PatchBuilderV2,
-  filePath: string,
-  entries: readonly OutlineEntry[],
-  jumpLookup: ReadonlyMap<string, { start: number; end: number }>,
-  parentPath = "",
-): Set<string> {
-  const emitted = new Set<string>();
-  const fileId = `file:${filePath}`;
-
-  for (const entry of entries) {
-    const symbolPath = parentPath.length > 0 ? `${parentPath}.${entry.name}` : entry.name;
-    const symId = `sym:${filePath}:${symbolPath}`;
-    emitted.add(symId);
-
-    patch.addNode(symId);
-    patch.setProperty(symId, "name", entry.name);
-    patch.setProperty(symId, "kind", entry.kind);
-    patch.setProperty(symId, "exported", entry.exported);
-    patch.setProperty(symId, "filePath", filePath);
-    if (entry.signature !== undefined) {
-      patch.setProperty(symId, "signature", entry.signature);
-    }
-    const jump = jumpLookup.get(entry.name);
-    if (jump !== undefined) {
-      patch.setProperty(symId, "startLine", jump.start);
-      patch.setProperty(symId, "endLine", jump.end);
-    }
-    patch.addEdge(fileId, symId, "contains");
-
-    if (entry.children !== undefined && entry.children.length > 0) {
-      for (const childId of emitOutlineSyms(patch, filePath, entry.children, jumpLookup, symbolPath)) {
-        emitted.add(childId);
-      }
-    }
-  }
-  return emitted;
-}
-
-
-// ---------------------------------------------------------------------------
-// Directory chain emission (inlined from indexer-graph.ts to avoid dep on
-// the legacy indexer module).
-// ---------------------------------------------------------------------------
-
-function emitDirectoryChain(patch: PatchBuilderV2, filePath: string): void {
-  const parts = filePath.split("/");
-  if (parts.length <= 1) return;
-
-  let current = "";
-  for (let index = 0; index < parts.length - 1; index++) {
-    const parent = current;
-    const part = parts[index] ?? "";
-    current = current.length > 0 ? `${current}/${part}` : part;
-    const dirId = `dir:${current}`;
-    patch.addNode(dirId);
-    patch.setProperty(dirId, "path", current);
-
-    if (parent.length > 0) {
-      patch.addEdge(`dir:${parent}`, dirId, "contains");
-    }
-  }
-
-  patch.addEdge(`dir:${current}`, `file:${filePath}`, "contains");
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-export interface IndexHeadOptions {
-  readonly cwd: string;
-  readonly git: GitClient;
-  readonly pathOps: PathOps;
-  readonly ctx: WarpContext;
-  readonly paths?: readonly string[] | undefined;
-  readonly maxFilesPerCall?: number | undefined;
-  readonly maxPatchJsonBytes?: number | undefined;
-}
-
-export interface IndexHeadResult {
-  readonly ok: true;
-  readonly filesIndexed: number;
-  readonly nodesEmitted: number;
-}
-
-interface HeadCommitMetadata {
-  readonly message: string;
-  readonly author: string;
-  readonly email: string;
-  readonly timestamp: string;
-}
-
-/**
- * Index the current HEAD by writing one bounded patch per file.
- *
- * Full tree-sitter syntax is attached as file-node blob content. The graph
- * itself only stores compact query facts: files, symbols, import/reference
- * anchors, directories, and commit-to-symbol touch edges.
- *
- * Emits a `commit:{sha}` node with edges to sym nodes labelled
- * "adds", "changes", or "removes" so structural queries can detect
- * what changed between ticks.
- */
-export async function indexHead(opts: IndexHeadOptions): Promise<IndexHeadResult> {
-  const { cwd, git, pathOps, ctx } = opts;
-  const maxFilesPerCall = opts.maxFilesPerCall ?? DEFAULT_INDEX_MAX_FILES_PER_CALL;
-  const maxPatchJsonBytes = opts.maxPatchJsonBytes ?? DEFAULT_INDEX_MAX_PATCH_JSON_BYTES;
-
-  const headResult = await git.run({ args: ["rev-parse", "HEAD"], cwd });
-  if (headResult.status !== 0) {
-    throw new Error(`git rev-parse HEAD failed: ${headResult.stderr}`);
-  }
-  const headSha = headResult.stdout.trim();
-  const commitMeta = await getCommitMeta(git, headSha, cwd);
-
-  const allFiles = await listTrackedFiles(cwd, git);
-  const knownFiles = new Set(allFiles);
-  const parseableFiles = selectParseableFiles(allFiles, opts.paths);
-
-  if (parseableFiles.length > maxFilesPerCall) {
-    throw new Error(
-      `indexHead refused to index ${String(parseableFiles.length)} files in one call. ` +
-      `Lazy indexing policy allows at most ${String(maxFilesPerCall)} files; ` +
-      `pass explicit paths or index on read.`,
-    );
-  }
-
-  let filesIndexed = 0;
-  for (const filePath of parseableFiles) {
-    const indexed = await indexHeadFile({
-      cwd,
-      git,
-      pathOps,
-      ctx,
-      headSha,
-      commitMeta,
-      knownFiles,
-      filePath,
-      maxPatchJsonBytes,
-    });
-    if (indexed) filesIndexed++;
-  }
-
-  return { ok: true, filesIndexed, nodesEmitted: filesIndexed };
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function collectSymIds(
-  target: Map<string, string | undefined>,
-  filePath: string,
-  entries: readonly OutlineEntry[],
-  parentPath = "",
-): void {
-  for (const entry of entries) {
-    const symbolPath = parentPath.length > 0 ? `${parentPath}.${entry.name}` : entry.name;
-    target.set(`sym:${filePath}:${symbolPath}`, entry.signature);
-    if (entry.children !== undefined && entry.children.length > 0) {
-      collectSymIds(target, filePath, entry.children, symbolPath);
-    }
-  }
-}
-
-async function listTrackedFiles(cwd: string, git: GitClient): Promise<readonly string[]> {
-  const result = await git.run({ args: ["ls-files"], cwd });
-  if (result.status !== 0) {
-    throw new Error(`git ls-files failed: ${result.stderr}`);
-  }
-  return result.stdout.trim().split("\n").filter((filePath) => filePath.length > 0);
-}
-
-function selectParseableFiles(
-  allFiles: readonly string[],
-  requestedPaths: readonly string[] | undefined,
-): readonly string[] {
-  const tracked = new Set(allFiles);
-  const candidates = requestedPaths !== undefined && requestedPaths.length > 0
-    ? requestedPaths.map((filePath) => filePath.trim()).filter((filePath) => filePath.length > 0 && tracked.has(filePath))
-    : allFiles;
-
-  return candidates.filter((filePath) => detectLang(filePath) !== null);
-}
-
-async function readPriorSymsForFile(
-  ctx: WarpContext,
-  filePath: string,
-): Promise<Map<string, string | undefined>> {
-  const priorSyms = new Map<string, string | undefined>();
-  const priorObs = await observeGraph(ctx, { match: `sym:${filePath}:*`, expose: ["signature"] });
-  const priorNodes = await priorObs.getNodes();
-  for (const nodeId of priorNodes) {
-    const props = await priorObs.getNodeProps(nodeId);
-    const sig = typeof props?.["signature"] === "string" ? props["signature"] : undefined;
-    priorSyms.set(nodeId, sig);
-  }
-  return priorSyms;
-}
-
-async function readPriorAstAnchorsForFile(
-  ctx: WarpContext,
-  filePath: string,
-): Promise<readonly string[]> {
-  const obs = await observeGraph(ctx, { match: `ast:${filePath}:*`, expose: [] });
-  return obs.getNodes();
-}
-
-function patchJsonByteLength(patch: PatchBuilderV2): number {
-  return Buffer.byteLength(JSON.stringify(patch.build()), "utf8");
-}
-
-function assertPatchWithinBudget(
-  patch: PatchBuilderV2,
-  filePath: string,
-  maxPatchJsonBytes: number,
-): void {
-  const bytes = patchJsonByteLength(patch);
-  if (bytes > maxPatchJsonBytes) {
-    throw new Error(
-      `indexHead refused to write ${filePath}: estimated patch payload ${String(bytes)} bytes ` +
-      `exceeds ${String(maxPatchJsonBytes)} bytes. Index smaller slices or attach bulky data as blobs.`,
-    );
-  }
-}
-
-async function indexHeadFile(input: {
-  readonly cwd: string;
-  readonly git: GitClient;
-  readonly pathOps: PathOps;
-  readonly ctx: WarpContext;
-  readonly headSha: string;
-  readonly commitMeta: HeadCommitMetadata;
-  readonly knownFiles: ReadonlySet<string>;
-  readonly filePath: string;
-  readonly maxPatchJsonBytes: number;
-}): Promise<boolean> {
-  const { cwd, git, pathOps, ctx, headSha, commitMeta, knownFiles, filePath, maxPatchJsonBytes } = input;
-  const lang = detectLang(filePath);
-  if (lang === null) return false;
-
-  const contentResult = await git.run({ args: ["show", `HEAD:${filePath}`], cwd });
-  if (contentResult.status !== 0) return false;
-
-  const tree = parseStructuredTree(lang, contentResult.stdout);
-  try {
-    const outlineResult = extractOutlineForFile(filePath, contentResult.stdout);
-    const outline = outlineResult?.entries ?? [];
-    const jumpLookup = new Map<string, { start: number; end: number }>();
-    for (const jt of outlineResult?.jumpTable ?? []) {
-      jumpLookup.set(jt.symbol, { start: jt.start, end: jt.end });
-    }
-
-    const currentSyms = new Map<string, string | undefined>();
-    collectSymIds(currentSyms, filePath, outline);
-
-    let priorSyms = new Map<string, string | undefined>();
-    let priorAstAnchors: readonly string[] = [];
-    try {
-      await materializeGraph(ctx);
-      priorSyms = await readPriorSymsForFile(ctx, filePath);
-      priorAstAnchors = await readPriorAstAnchorsForFile(ctx, filePath);
-    } catch {
-      // No prior state: first lazy index writes adds only.
-    }
-
-    await patchGraph(ctx, async (patch) => {
-      const tick = patch.build().lamport;
-      const commitId = `commit:${headSha}`;
-      const fileId = `file:${filePath}`;
-
-      patch.addNode(commitId);
-      patch.setProperty(commitId, "sha", headSha);
-      patch.setProperty(commitId, "tick", tick);
-      patch.setProperty(commitId, "message", commitMeta.message);
-      patch.setProperty(commitId, "author", commitMeta.author);
-      patch.setProperty(commitId, "email", commitMeta.email);
-      patch.setProperty(commitId, "date", commitMeta.timestamp);
-      patch.setProperty(commitId, "timestamp", commitMeta.timestamp);
-
-      patch.addNode(fileId);
-      patch.setProperty(fileId, "path", filePath);
-      patch.setProperty(fileId, "lang", lang);
-      patch.setProperty(fileId, "indexedCommit", headSha);
-      patch.addEdge(commitId, fileId, "touches");
-
-      emitDirectoryChain(patch, filePath);
-      for (const anchorId of priorAstAnchors) {
-        patch.removeNode(anchorId);
-      }
-      emitOutlineSyms(patch, filePath, outline, jumpLookup);
-      emitAstNodes(patch, filePath, tree.root);
-      resolveImportEdges(patch, filePath, tree.root, pathOps, knownFiles);
-      await attachAstSnapshot(patch, filePath, tree.root);
-
-      for (const [symId, sig] of currentSyms) {
-        if (!priorSyms.has(symId)) {
-          patch.addEdge(commitId, symId, "adds");
-        } else if (priorSyms.get(symId) !== sig) {
-          patch.addEdge(commitId, symId, "changes");
-        }
-      }
-
-      for (const symId of priorSyms.keys()) {
-        if (!currentSyms.has(symId)) {
-          patch.addEdge(commitId, symId, "removes");
-          patch.removeNode(symId);
-        }
-      }
-
-      assertPatchWithinBudget(patch, filePath, maxPatchJsonBytes);
-    });
-
-    return true;
-  } finally {
-    tree.delete();
-  }
-}