@flyingrobots/graft 0.6.0 → 0.7.0

package/src/operations/structural-review.ts

@@ -0,0 +1,317 @@
+// ---------------------------------------------------------------------------
+// Structural Review — zero-noise PR review separating signal from formatting
+// ---------------------------------------------------------------------------
+
+import type { FileSystem } from "../ports/filesystem.js";
+import type { GitClient } from "../ports/git.js";
+import { graftDiff, type FileDiff, type GraftDiffOptions } from "./graft-diff.js";
+import { getChangedFilesWithStatus } from "../git/diff.js";
+
+// ---- Public types ---------------------------------------------------------
+
+export interface ReferenceCountResult {
+  readonly referenceCount: number;
+  readonly referencingFiles: readonly string[];
+}
+
+export type ReferenceCounter = (
+  symbolName: string,
+  filePath: string,
+) => Promise<ReferenceCountResult>;
+
+
+export type ReviewCategory = "structural" | "formatting" | "test" | "docs" | "config";
+
+export interface ReviewFile {
+  readonly path: string;
+  readonly category: ReviewCategory;
+  readonly structuralChanges?: { added: number; removed: number; changed: number };
+}
+
+export interface BreakingChange {
+  readonly symbol: string;
+  readonly kind: string;
+  readonly filePath: string;
+  readonly changeType: "removed_export" | "signature_changed" | "type_changed";
+  readonly previousSignature?: string;
+  readonly newSignature?: string;
+  readonly impactedFiles: number;
+  readonly impactedFilePaths: readonly string[];
+}
+
+export interface StructuralReviewResult {
+  readonly base: string;
+  readonly head: string;
+  readonly totalFiles: number;
+  readonly categories: Record<ReviewCategory, number>;
+  readonly files: readonly ReviewFile[];
+  readonly breakingChanges: readonly BreakingChange[];
+  readonly summary: string;
+}
+
+export interface StructuralReviewOptions {
+  readonly cwd: string;
+  readonly fs: FileSystem;
+  readonly git: GitClient;
+  readonly resolveWorkingTreePath: (filePath: string) => string;
+  readonly base?: string | undefined;
+  readonly head?: string | undefined;
+  readonly countReferences: ReferenceCounter;
+}
+
+// ---- File categorization --------------------------------------------------
+
+const CONFIG_PATTERNS = [
+  "package.json",
+  "tsconfig",
+  "eslint",
+  ".prettierrc",
+  ".editorconfig",
+  "vitest.config",
+  "jest.config",
+  "rollup.config",
+  "vite.config",
+  "webpack.config",
+  "babel.config",
+  ".babelrc",
+  ".npmrc",
+  ".nvmrc",
+  ".gitignore",
+  ".gitattributes",
+  "pnpm-lock.yaml",
+  "pnpm-workspace.yaml",
+  "yarn.lock",
+  "package-lock.json",
+  "Makefile",
+  "Dockerfile",
+  "docker-compose",
+];
+
+const TEST_PATTERNS = [
+  "/test/",
+  "/tests/",
+  "/__tests__/",
+  ".test.",
+  ".spec.",
+  "_test.",
+];
+
+function isTestFile(filePath: string): boolean {
+  return TEST_PATTERNS.some((p) => filePath.includes(p));
+}
+
+function isDocsFile(filePath: string): boolean {
+  return filePath.endsWith(".md") || filePath.endsWith(".txt") || filePath.endsWith(".rst");
+}
+
+function isConfigFile(filePath: string): boolean {
+  const lower = filePath.toLowerCase();
+  return CONFIG_PATTERNS.some((p) => lower.includes(p));
+}
+
+// ---- Breaking change detection --------------------------------------------
+
+async function detectBreakingChanges(
+  structuralFiles: readonly FileDiff[],
+  countReferences: ReferenceCounter,
+): Promise<BreakingChange[]> {
+  const breaking: BreakingChange[] = [];
+
+  for (const file of structuralFiles) {
+    // Removed exports → breaking
+    for (const removed of file.diff.removed) {
+      if (removed.exported !== true) continue;
+      const refs = await countReferences(removed.name, file.path);
+      breaking.push({
+        symbol: removed.name,
+        kind: removed.kind,
+        filePath: file.path,
+        changeType: "removed_export",
+        ...(removed.signature !== undefined ? { previousSignature: removed.signature } : {}),
+        impactedFiles: refs.referenceCount,
+        impactedFilePaths: refs.referencingFiles,
+      });
+    }
+
+    // Changed exported symbol signatures → potentially breaking
+    for (const changed of file.diff.changed) {
+      if (changed.exported !== true) continue;
+      if (changed.oldSignature !== undefined && changed.signature !== undefined &&
+          changed.oldSignature !== changed.signature) {
+        const refs = await countReferences(changed.name, file.path);
+        breaking.push({
+          symbol: changed.name,
+          kind: changed.kind,
+          filePath: file.path,
+          changeType: "signature_changed",
+          previousSignature: changed.oldSignature,
+          newSignature: changed.signature,
+          impactedFiles: refs.referenceCount,
+          impactedFilePaths: refs.referencingFiles,
+        });
+      }
+    }
+  }
+
+  return breaking;
+}
+
+// ---- Summary rendering ----------------------------------------------------
+
+function renderSummary(
+  base: string,
+  head: string,
+  categories: Record<ReviewCategory, number>,
+  breakingChanges: readonly BreakingChange[],
+  totalFiles: number,
+  structuralFiles: readonly FileDiff[],
+): string {
+  const parts: string[] = [];
+  parts.push(`PR Review: ${base}..${head} — ${String(totalFiles)} files changed`);
+  parts.push("");
+
+  // Structural details
+  if (categories.structural > 0) {
+    const totalAdded = structuralFiles.reduce((n, f) => n + f.diff.added.length, 0);
+    const totalChanged = structuralFiles.reduce((n, f) => n + f.diff.changed.length, 0);
+    const totalRemoved = structuralFiles.reduce((n, f) => n + f.diff.removed.length, 0);
+    const details: string[] = [];
+    if (totalAdded > 0) details.push(`${String(totalAdded)} new exports`);
+    if (totalChanged > 0) details.push(`${String(totalChanged)} sig changes`);
+    if (totalRemoved > 0) details.push(`${String(totalRemoved)} removed`);
+    const suffix = details.length > 0 ? ` (${details.join(", ")})` : "";
+    parts.push(`  Structural: ${String(categories.structural)} files${suffix}`);
+  }
+  if (categories.formatting > 0) {
+    parts.push(`  Formatting: ${String(categories.formatting)} files`);
+  }
+  if (categories.test > 0) {
+    parts.push(`  Tests: ${String(categories.test)} files`);
+  }
+  if (categories.docs > 0) {
+    parts.push(`  Docs: ${String(categories.docs)} files`);
+  }
+  if (categories.config > 0) {
+    parts.push(`  Config: ${String(categories.config)} files`);
+  }
+
+  // Breaking changes
+  for (const bc of breakingChanges) {
+    parts.push("");
+    if (bc.changeType === "removed_export") {
+      parts.push(`  ⚠ BREAKING: ${bc.symbol} — removed export`);
+      if (bc.previousSignature !== undefined) {
+        parts.push(`    Was: ${bc.previousSignature}`);
+      }
+    } else {
+      parts.push(`  ⚠ BREAKING: ${bc.symbol} — signature changed`);
+      if (bc.previousSignature !== undefined) {
+        parts.push(`    Was: ${bc.previousSignature}`);
+      }
+      if (bc.newSignature !== undefined) {
+        parts.push(`    Now: ${bc.newSignature}`);
+      }
+    }
+    parts.push(`    Impact: referenced by ${String(bc.impactedFiles)} files`);
+  }
+
+  return parts.join("\n");
+}
+
+// ---- Public API -----------------------------------------------------------
+
+export async function structuralReview(
+  opts: StructuralReviewOptions,
+): Promise<StructuralReviewResult> {
+  const base = opts.base ?? "main";
+  const head = opts.head ?? "HEAD";
+
+  // 1. Get structural diff
+  const diffOpts: GraftDiffOptions = {
+    cwd: opts.cwd,
+    fs: opts.fs,
+    git: opts.git,
+    resolveWorkingTreePath: opts.resolveWorkingTreePath,
+    base,
+    head,
+  };
+  const structDiff = await graftDiff(diffOpts);
+
+  // 2. Get ALL changed files with rename detection
+  const allChangedEntries = await getChangedFilesWithStatus({
+    cwd: opts.cwd,
+    git: opts.git,
+    base,
+    head,
+  });
+  const allChangedPaths = allChangedEntries.map((e) => e.path);
+
+  // 3. Build set of structurally-changed file paths
+  const structuralPaths = new Set(structDiff.files.map((f) => f.path));
+
+  // 4. Categorize each changed file
+  const files: ReviewFile[] = [];
+  for (const filePath of allChangedPaths) {
+    // Check if the file has actual structural (symbol-level) changes
+    const fileDiff = structuralPaths.has(filePath)
+      ? structDiff.files.find((f) => f.path === filePath)
+      : undefined;
+    const diff = fileDiff?.diff;
+    const hasStructuralChanges = diff !== undefined &&
+      (diff.added.length > 0 || diff.removed.length > 0 || diff.changed.length > 0);
+
+    if (hasStructuralChanges) {
+      files.push({
+        path: filePath,
+        category: "structural",
+        structuralChanges: { added: diff.added.length, removed: diff.removed.length, changed: diff.changed.length },
+      });
+    } else if (isTestFile(filePath)) {
+      files.push({ path: filePath, category: "test" });
+    } else if (isDocsFile(filePath)) {
+      files.push({ path: filePath, category: "docs" });
+    } else if (isConfigFile(filePath)) {
+      files.push({ path: filePath, category: "config" });
+    } else {
+      files.push({ path: filePath, category: "formatting" });
+    }
+  }
+
+  // 5. Count categories
+  const categories: Record<ReviewCategory, number> = {
+    structural: 0,
+    formatting: 0,
+    test: 0,
+    docs: 0,
+    config: 0,
+  };
+  for (const file of files) {
+    categories[file.category]++;
+  }
+
+  // 6. Detect breaking changes in structural files
+  const structuralFileDiffs = structDiff.files.filter((f) =>
+    f.diff.removed.length > 0 || f.diff.changed.length > 0,
+  );
+  const breakingChanges = await detectBreakingChanges(structuralFileDiffs, opts.countReferences);
+
+  // 7. Render summary
+  const summary = renderSummary(
+    base,
+    head,
+    categories,
+    breakingChanges,
+    allChangedPaths.length,
+    structDiff.files,
+  );
+
+  return {
+    base,
+    head,
+    totalFiles: allChangedPaths.length,
+    categories,
+    files,
+    breakingChanges,
+    summary,
+  };
+}

package/src/operations/teaching-hints.ts

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// Teaching Hints — contextual guidance for suboptimal read decisions
+// ---------------------------------------------------------------------------
+
+/** Context about a projection decision for hint generation. */
+export interface ProjectionContext {
+  readonly projection: "content" | "outline" | "refused";
+  readonly reason: string;
+  readonly filePath: string;
+  readonly fileLines: number;
+  readonly fileBytes: number;
+  readonly readCount: number;
+  readonly changedSinceLastRead?: boolean;
+}
+
+const LARGE_FILE_THRESHOLD = 150;
+const BUILD_OUTPUT_DIRS = ["dist/", "build/", "out/", ".next/", "coverage/"];
+
+/**
+ * Generate a teaching hint for a projection decision.
+ *
+ * Returns undefined when the decision was already optimal (no noise).
+ * Pure function — no I/O, no latency impact.
+ */
+export function generateTeachingHint(ctx: ProjectionContext): string | undefined {
+  // Refused — suggest the source location
+  if (ctx.projection === "refused") {
+    if (BUILD_OUTPUT_DIRS.some((dir) => ctx.filePath.startsWith(dir))) {
+      return `This build output was refused. Source lives in src/, not ${ctx.filePath.split("/")[0] ?? "dist"}/. Read the source instead.`;
+    }
+    return `This file was refused (${ctx.reason}). Check if the content you need lives elsewhere.`;
+  }
+
+  // Outline-projected — suggest file_outline + read_range
+  if (ctx.projection === "outline") {
+    return `This file was outline-projected (${ctx.reason}). Try file_outline first to see the jump table, then read_range for the specific symbol you need.`;
+  }
+
+
+  // Re-read of unchanged file
+  if (ctx.readCount > 1 && ctx.changedSinceLastRead === false) {
+    return `You already read this file ${String(ctx.readCount)} times and it hasn't changed. Use changed_since to check before re-reading.`;
+  }
+
+  // Large file that could benefit from outline-first
+  if (ctx.fileLines > LARGE_FILE_THRESHOLD) {
+    return `This file is ${String(ctx.fileLines)} lines. Consider file_outline first for orientation, then read_range for the specific section you need.`;
+  }
+
+  // Optimal decision — no hint needed
+  return undefined;
+}

package/src/parser/diff.ts

@@ -48,6 +48,7 @@ export class DiffEntry {
   private readonly _brand = "DiffEntry" as const;
   readonly name: string;
   readonly kind: OutlineEntry["kind"];
+  readonly exported?: boolean;
   readonly signature?: string;
   readonly oldSignature?: string;
   readonly childDiff?: OutlineDiff;
@@ -57,6 +58,7 @@ export class DiffEntry {
   constructor(opts: {
     name: string;
     kind: OutlineEntry["kind"];
+    exported?: boolean;
     signature?: string;
     oldSignature?: string;
     childDiff?: OutlineDiff;
@@ -67,6 +69,7 @@ export class DiffEntry {
     }
     this.name = opts.name.trim();
     this.kind = opts.kind;
+    if (opts.exported !== undefined) this.exported = opts.exported;
     if (opts.signature !== undefined) this.signature = opts.signature;
     if (opts.oldSignature !== undefined) this.oldSignature = opts.oldSignature;
     if (opts.childDiff !== undefined) this.childDiff = opts.childDiff;
@@ -255,6 +258,7 @@ export function diffOutlines(
       added.push(new DiffEntry({
         name,
         kind: newEntry.kind,
+        exported: newEntry.exported,
         ...(newEntry.signature !== undefined ? { signature: newEntry.signature } : {}),
       }));
       addedEntries.push(newEntry);
@@ -265,6 +269,7 @@ export function diffOutlines(
         changed.push(new DiffEntry({
           name,
           kind: newEntry.kind,
+          exported: newEntry.exported,
           oldSignature: entrySignature(oldEntry),
           ...(newEntry.signature !== undefined ? { signature: newEntry.signature } : {}),
         }));
@@ -276,6 +281,7 @@ export function diffOutlines(
           const childDiff = diffOutlines(oldChildren, newChildren);
           if (childDiff.added.length > 0 || childDiff.removed.length > 0 || childDiff.changed.length > 0) {
             changed.push(new DiffEntry({
+              exported: newEntry.exported,
               name,
               kind: newEntry.kind,
               childDiff,
@@ -297,6 +303,7 @@ export function diffOutlines(
       removed.push(new DiffEntry({
         name,
         kind: oldEntry.kind,
+        exported: oldEntry.exported,
         ...(oldEntry.signature !== undefined ? { signature: oldEntry.signature } : {}),
       }));
       removedEntries.push(oldEntry);

package/src/ports/paths.ts

@@ -0,0 +1,22 @@
+// ---------------------------------------------------------------------------
+// PathOps port — hexagonal boundary for path operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Portable path operations. Core logic imports this port, not node:path.
+ * Node adapter implements it; tests can substitute a mock.
+ *
+ * All methods accept and return forward-slash paths. Normalization
+ * (collapsing `//`, resolving `..`, stripping trailing slashes) happens
+ * inside the adapter so callers never see raw platform paths.
+ */
+export interface PathOps {
+  /** Normalize a path: collapse `//`, resolve `..`, strip trailing `/`. */
+  normalize(p: string): string;
+
+  /** True when `filePath` is exactly `directory` or nested inside it. */
+  isWithin(filePath: string, directory: string): boolean;
+
+  /** Join path segments with forward slashes, normalized. */
+  join(...segments: string[]): string;
+}

package/src/warp/ast-emitter.ts

@@ -0,0 +1,133 @@
+// ---------------------------------------------------------------------------
+// AST snapshot attachment — keeps bulky syntax trees out of graph state
+// ---------------------------------------------------------------------------
+
+import { createHash } from "node:crypto";
+import { Buffer } from "node:buffer";
+import type { PatchBuilderV2 } from "@git-stunts/git-warp";
+import type { WarpContext } from "./context.js";
+import { patchGraph } from "./context.js";
+
+type TSNode = import("web-tree-sitter").SyntaxNode;
+
+const AST_SNAPSHOT_MIME = "application/vnd.graft.ast+json";
+
+function hashId(input: string): string {
+  return createHash("sha1").update(input).digest("hex").slice(0, 12);
+}
+
+function astNodeId(filePath: string, node: TSNode): string {
+  const hash = hashId(`${filePath}:${node.type}:${String(node.startIndex)}:${String(node.endIndex)}`);
+  return `ast:${filePath}:${hash}`;
+}
+
+interface AstSnapshotNode {
+  readonly type: string;
+  readonly named: boolean;
+  readonly startRow: number;
+  readonly startCol: number;
+  readonly endRow: number;
+  readonly endCol: number;
+  readonly text?: string | undefined;
+  readonly children?: readonly AstSnapshotNode[] | undefined;
+}
+
+interface AstSnapshot {
+  readonly schema: "graft.ast-snapshot.v1";
+  readonly filePath: string;
+  readonly root: AstSnapshotNode;
+}
+
+function astSnapshotNode(node: TSNode): AstSnapshotNode {
+  const children: AstSnapshotNode[] = [];
+  for (let index = 0; index < node.childCount; index++) {
+    const child = node.child(index);
+    if (child !== null) children.push(astSnapshotNode(child));
+  }
+
+  return {
+    type: node.type,
+    named: node.isNamed(),
+    startRow: node.startPosition.row,
+    startCol: node.startPosition.column,
+    endRow: node.endPosition.row,
+    endCol: node.endPosition.column,
+    ...(children.length === 0 ? { text: node.text } : {}),
+    ...(children.length > 0 ? { children } : {}),
+  };
+}
+
+function astSnapshot(filePath: string, root: TSNode): AstSnapshot {
+  return {
+    schema: "graft.ast-snapshot.v1",
+    filePath,
+    root: astSnapshotNode(root),
+  };
+}
+
+/**
+ * Emit a tiny AST root anchor into graph state.
+ *
+ * The full tree belongs in an attached blob, not materialized WARP graph
+ * state. This anchor preserves a stable graph join point for tools that need
+ * to know a file has an attached AST snapshot.
+ *
+ * Call this inside a `warp.patch()` callback to co-locate AST emission
+ * with other graph operations in the same atomic commit.
+ */
+export function emitAstNodes(
+  patch: PatchBuilderV2,
+  filePath: string,
+  root: TSNode,
+): void {
+  const fileId = `file:${filePath}`;
+
+  const rootId = astNodeId(filePath, root);
+  patch.addNode(rootId);
+  patch.setProperty(rootId, "type", root.type);
+  patch.setProperty(rootId, "named", root.isNamed());
+  patch.setProperty(rootId, "startRow", root.startPosition.row);
+  patch.setProperty(rootId, "startCol", root.startPosition.column);
+  patch.setProperty(rootId, "endRow", root.endPosition.row);
+  patch.setProperty(rootId, "endCol", root.endPosition.column);
+  patch.setProperty(rootId, "filePath", filePath);
+  patch.setProperty(rootId, "summaryOnly", true);
+
+  patch.addEdge(fileId, rootId, "contains_ast");
+}
+
+/**
+ * Attach the complete tree-sitter CST as node content on the file node.
+ *
+ * The blob remains reachable through the WARP patch commit tree, but the
+ * materialized graph only carries the `_content` OID and metadata.
+ */
+export async function attachAstSnapshot(
+  patch: PatchBuilderV2,
+  filePath: string,
+  root: TSNode,
+): Promise<void> {
+  const fileId = `file:${filePath}`;
+  const content = Buffer.from(JSON.stringify(astSnapshot(filePath, root)), "utf8");
+  await patch.attachContent(fileId, content, {
+    mime: AST_SNAPSHOT_MIME,
+  });
+}
+
+/**
+ * Standalone convenience: emit the AST root anchor and attach the full AST
+ * snapshot as blob content in one patch.
+ */
+export async function emitFullAst(
+  ctx: WarpContext,
+  filePath: string,
+  root: TSNode,
+): Promise<void> {
+  await patchGraph(ctx, async (patch) => {
+    const fileId = `file:${filePath}`;
+    patch.addNode(fileId);
+    patch.setProperty(fileId, "path", filePath);
+    emitAstNodes(patch, filePath, root);
+    await attachAstSnapshot(patch, filePath, root);
+  });
+}