@flyingrobots/graft 0.7.0 → 0.8.0

package/src/warp/stale-docs.ts

@@ -1,210 +0,0 @@
-/**
- * Stale Docs Checker — cross-references doc symbol mentions against
- * the WARP graph to detect documentation that may be outdated.
- *
- * Walks markdown for backtick-quoted identifiers and code block
- * contents. For each referenced symbol, queries the WARP graph to
- * determine whether the symbol changed after the doc was last modified.
- *
- * Also detects version number drift between package.json and CHANGELOG.
- */
-
-import type { WarpContext } from "./context.js";
-import { symbolTimeline } from "./symbol-timeline.js";
-import { observeGraph } from "./context.js";
-
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** A symbol in a doc that is stale relative to the WARP graph. */
-export interface StaleSymbolEntry {
-  readonly symbol: string;
-  readonly changeKind: "changed" | "removed";
-  readonly lastChangeSha: string;
-}
-
-/** Result of checking a single doc for staleness. */
-export interface StaleDocReport {
-  readonly docPath: string;
-  /** Symbols referenced in the doc that changed after the doc was last modified. */
-  readonly staleSymbols: readonly StaleSymbolEntry[];
-  /** Symbols referenced in the doc that do not exist in the WARP graph. */
-  readonly unknownSymbols: readonly string[];
-}
-
-/** Result of checking version drift between package.json and CHANGELOG. */
-export interface VersionDriftReport {
-  readonly drifted: boolean;
-  readonly packageVersion: string;
-  readonly changelogVersion: string | null;
-}
-
-// ---------------------------------------------------------------------------
-// Symbol extraction
-// ---------------------------------------------------------------------------
-
-/** Match single-backtick content that looks like an identifier (no spaces, no dots). */
-const INLINE_CODE_RE = /`([A-Za-z_$][A-Za-z0-9_$]*)`/g;
-
-/**
- * Match identifiers inside fenced code blocks.
- * We look for function/class/const/let/var/type/interface/import declarations
- * and bare identifiers that look like symbol names.
- */
-const CODE_BLOCK_RE = /```[\s\S]*?```/g;
-
-/**
- * Inside code blocks, match identifiers from destructured imports/exports
- * and direct declarations.
- */
-const CODE_BLOCK_DECL_RE =
-  /(?:import|export|function|class|const|let|var|type|interface)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
-
-/**
- * Match identifiers inside braces of import/export destructuring.
- * e.g. import { evaluatePolicy, runCheck } from '...'
- */
-const DESTRUCTURE_RE = /(?:import|export)\s+\{([^}]+)\}/g;
-const DESTRUCTURE_IDENT_RE = /([A-Za-z_$][A-Za-z0-9_$]*)/g;
-
-/**
- * Extract symbol name references from markdown content.
- *
- * Sources:
- * 1. Backtick-quoted identifiers (single backtick, must be valid JS/TS identifier)
- * 2. Declaration identifiers inside fenced code blocks
- *
- * Returns a deduplicated array of symbol names.
- */
-export function extractDocSymbolReferences(markdown: string): string[] {
-  const symbols = new Set<string>();
-
-  // 1. Inline backtick identifiers
-  let match: RegExpExecArray | null;
-  while ((match = INLINE_CODE_RE.exec(markdown)) !== null) {
-    if (match[1] !== undefined) symbols.add(match[1]);
-  }
-
-  // 2. Identifiers inside fenced code blocks
-  for (const blockMatch of markdown.matchAll(CODE_BLOCK_RE)) {
-    const block = blockMatch[0];
-
-    // Direct declarations: function foo, class Bar, etc.
-    while ((match = CODE_BLOCK_DECL_RE.exec(block)) !== null) {
-      if (match[1] !== undefined) symbols.add(match[1]);
-    }
-
-    // Destructured imports/exports: import { foo, bar } from ...
-    for (const destructMatch of block.matchAll(DESTRUCTURE_RE)) {
-      const inner = destructMatch[1];
-      if (inner === undefined) continue;
-      let identMatch: RegExpExecArray | null;
-      while ((identMatch = DESTRUCTURE_IDENT_RE.exec(inner)) !== null) {
-        // Skip "as" keyword in "foo as bar" patterns — keep both identifiers
-        const identifier = identMatch[1];
-        if (identifier !== undefined && identifier !== "as") {
-          symbols.add(identifier);
-        }
-      }
-    }
-  }
-
-  return [...symbols];
-}
-
-// ---------------------------------------------------------------------------
-// Stale doc check
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve the tick (lamport clock) for a given commit SHA.
- * Returns null if the commit is not in the graph.
- */
-async function getCommitTick(
-  ctx: WarpContext,
-  sha: string,
-): Promise<number | null> {
-  const obs = await observeGraph(ctx, { match: "commit:*", expose: ["sha", "tick"] });
-  const props = await obs.getNodeProps(`commit:${sha}`);
-  return typeof props?.["tick"] === "number" ? props["tick"] : null;
-}
-
-/**
- * Check a markdown document for stale symbol references.
- *
- * @param ctx - WARP context
- * @param docPath - relative path of the doc (for the report)
- * @param docCommitSha - SHA of the commit when the doc was last modified
- * @param docContent - raw markdown content of the doc
- */
-export async function checkStaleDocs(
-  ctx: WarpContext,
-  docPath: string,
-  docCommitSha: string,
-  docContent: string,
-): Promise<StaleDocReport> {
-  const symbolNames = extractDocSymbolReferences(docContent);
-  const docTick = await getCommitTick(ctx, docCommitSha);
-
-  const staleSymbols: StaleSymbolEntry[] = [];
-  const unknownSymbols: string[] = [];
-
-  for (const symbolName of symbolNames) {
-    const timeline = await symbolTimeline(ctx, symbolName);
-
-    if (timeline.versions.length === 0) {
-      unknownSymbols.push(symbolName);
-      continue;
-    }
-
-    // If we cannot resolve the doc commit tick, we cannot compare —
-    // treat the doc as fresh (conservative).
-    if (docTick === null) continue;
-
-    // Check if any version has a tick after the doc's commit tick.
-    // symbolTimeline returns versions in tick order with accurate
-    // per-commit data (unlike commitsForSymbol which returns HEAD
-    // signature for all entries).
-    for (const version of timeline.versions) {
-      if (version.tick > docTick) {
-        if (version.changeKind === "changed" || version.changeKind === "removed") {
-          staleSymbols.push({
-            symbol: symbolName,
-            changeKind: version.changeKind,
-            lastChangeSha: version.sha,
-          });
-          break;
-        }
-      }
-    }
-  }
-
-  return { docPath, staleSymbols, unknownSymbols };
-}
-
-// ---------------------------------------------------------------------------
-// Version drift check
-// ---------------------------------------------------------------------------
-
-/** Match the first semver-looking heading in a CHANGELOG. */
-const CHANGELOG_VERSION_RE = /^##\s+\[?v?(\d+\.\d+\.\d+(?:-[A-Za-z0-9.]+)?)\]?/m;
-
-/**
- * Check whether the latest version in a CHANGELOG matches
- * the version in package.json.
- */
-export function checkVersionDrift(
-  packageVersion: string,
-  changelogContent: string,
-): VersionDriftReport {
-  const match = CHANGELOG_VERSION_RE.exec(changelogContent);
-  const changelogVersion = match?.[1] ?? null;
-
-  return {
-    drifted: changelogVersion !== packageVersion,
-    packageVersion,
-    changelogVersion,
-  };
-}

package/src/warp/structural-drift-detection.ts

@@ -1,97 +0,0 @@
-// ---------------------------------------------------------------------------
-// Structural Drift Detection — verify doc claims against reality
-// ---------------------------------------------------------------------------
-
-/** Result of checking a single drift rule. */
-export interface DriftResult {
-  readonly drifted: boolean;
-  readonly docPath: string;
-  readonly claim: string;
-  readonly expected: string;
-  readonly actual: string;
-}
-
-/** Options for numeric claim checking. */
-export interface NumericClaimOptions {
-  readonly docPath: string;
-  /** The text containing the numeric claim (e.g., "12 MCP tools"). */
-  readonly claim: string;
-  /** Regex with a capture group for the number. */
-  readonly pattern: RegExp;
-  /** The actual count from reality. */
-  readonly actual: number;
-}
-
-/**
- * Check whether a numeric claim in a doc matches reality.
- *
- * Parses the claim text with the given pattern to extract the stated
- * number, then compares against the actual count.
- */
-export function checkNumericClaim(options: NumericClaimOptions): DriftResult {
-  const { docPath, claim, pattern, actual } = options;
-  const match = pattern.exec(claim);
-
-  if (match?.[1] === undefined) {
-    return {
-      drifted: true,
-      docPath,
-      claim,
-      expected: "no match",
-      actual: String(actual),
-    };
-  }
-
-  const stated = parseInt(match[1], 10);
-  return {
-    drifted: stated !== actual,
-    docPath,
-    claim,
-    expected: match[1],
-    actual: String(actual),
-  };
-}
-
-/** Result of checking a pattern prohibition. */
-export interface PatternProhibitionResult {
-  readonly drifted: boolean;
-  readonly docPath: string;
-  readonly rule: string;
-  readonly violations: readonly string[];
-}
-
-/** Options for pattern prohibition checking. */
-export interface PatternProhibitionOptions {
-  readonly docPath: string;
-  /** Human-readable description of the rule (e.g., "no getNodes calls in src/"). */
-  readonly rule: string;
-  /** Regex to search for in file contents. */
-  readonly pattern: RegExp;
-  /** Map of file path → content to check. */
-  readonly files: Readonly<Record<string, string>>;
-}
-
-/**
- * Check whether a prohibited pattern appears in any of the given files.
- *
- * Returns the list of files that violate the prohibition.
- */
-export function checkPatternProhibition(
-  options: PatternProhibitionOptions,
-): PatternProhibitionResult {
-  const { docPath, rule, pattern, files } = options;
-  const violations: string[] = [];
-
-  for (const [filePath, content] of Object.entries(files)) {
-    if (pattern.test(content)) {
-      violations.push(filePath);
-    }
-  }
-
-  return {
-    drifted: violations.length > 0,
-    docPath,
-    rule,
-    violations,
-  };
-}

package/src/warp/structural-queries.ts

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