@flyingrobots/graft 0.6.1 → 0.7.0

package/src/warp/refactor-difficulty.ts

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

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

package/src/warp/stale-docs.ts

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

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