@abhinav2203/codeflow-analysis 0.1.0

package/src/refactor.test.ts

@@ -0,0 +1,362 @@
+import { describe, expect, it } from "vitest";
+
+import { detectDrift, healGraph } from "./refactor";
+import type { BlueprintEdge, BlueprintGraph } from "@/lib/blueprint/schema";
+import { emptyContract } from "@/lib/blueprint/schema";
+
+// ── Fixtures ───────────────────────────────────────────────────────────────
+
+const makeNode = (
+  id: string,
+  overrides: Partial<{
+    contractCalls: { target: string; kind?: string }[];
+    signature: string;
+    firstMethodSignature: string;
+  }> = {}
+): BlueprintGraph["nodes"][number] => {
+  const calls = overrides.contractCalls?.map((c) => ({
+    target: c.target,
+    kind: c.kind as "calls" | "imports" | "reads-state" | "writes-state" | "inherits" | "renders" | "emits" | "consumes",
+    description: undefined,
+  })) ?? [];
+
+  const methods = overrides.firstMethodSignature
+    ? [
+        {
+          name: id,
+          signature: overrides.firstMethodSignature,
+          summary: "Method.",
+          inputs: [] as { name: string; type: string; description?: string }[],
+          outputs: [] as { name: string; type: string; description?: string }[],
+          sideEffects: [] as string[],
+          calls: [] as { target: string; kind?: string; description?: string }[],
+        },
+      ]
+    : [];
+
+  return {
+    id,
+    kind: "function",
+    name: id,
+    summary: `${id} summary.`,
+    signature: overrides.signature,
+    contract: {
+      ...emptyContract(),
+      ...(calls.length > 0 ? { calls } : {}),
+      ...(methods.length > 0 ? { methods } : {}),
+    },
+    sourceRefs: [],
+    generatedRefs: [],
+    traceRefs: [],
+  };
+};
+
+const edge = (from: string, to: string, kind = "calls"): BlueprintEdge => ({
+  from,
+  to,
+  kind,
+  required: false,
+  confidence: 1,
+});
+
+const makeGraph = (
+  overrides: Partial<{
+    nodes: BlueprintGraph["nodes"];
+    edges: BlueprintGraph["edges"];
+  }> = {}
+): BlueprintGraph => ({
+  projectName: "TestApp",
+  mode: "essential",
+  phase: "spec",
+  generatedAt: "2026-03-14T00:00:00.000Z",
+  warnings: [],
+  workflows: [],
+  edges: [],
+  nodes: [
+    makeNode("function:auth", {
+      contractCalls: [],
+    }),
+    makeNode("api:users", { contractCalls: [] }),
+    makeNode("function:checkout", { contractCalls: [] }),
+  ],
+  ...overrides,
+});
+
+// ── detectDrift ─────────────────────────────────────────────────────────────
+
+describe("detectDrift", () => {
+  it("reports a healthy graph with no issues", () => {
+    const report = detectDrift(makeGraph());
+
+    expect(report.isHealthy).toBe(true);
+    expect(report.issues).toHaveLength(0);
+    expect(report.totalIssues).toBe(0);
+    expect(report.driftedNodeIds).toHaveLength(0);
+    expect(report.provenance).toBe("deterministic");
+    expect(report.maturity).toBe("preview");
+    expect(report.scope).toBe("graph");
+  });
+
+  it("detects a broken edge whose source node does not exist", () => {
+    const graph = makeGraph({
+      edges: [edge("node:ghost", "function:auth")],
+    });
+
+    const report = detectDrift(graph);
+
+    expect(report.isHealthy).toBe(false);
+    const brokenIssues = report.issues.filter((i) => i.kind === "broken-edge");
+    expect(brokenIssues.length).toBeGreaterThanOrEqual(1);
+    // Anchored on the existing endpoint.
+    expect(brokenIssues[0].nodeId).toBe("function:auth");
+    expect(brokenIssues[0].missingNodeId).toBe("node:ghost");
+    // driftedNodeIds only contains real node IDs.
+    expect(report.driftedNodeIds).toContain("function:auth");
+    expect(report.driftedNodeIds).not.toContain("node:ghost");
+  });
+
+  it("detects a broken edge whose target node does not exist", () => {
+    const graph = makeGraph({
+      edges: [edge("function:auth", "node:deleted")],
+    });
+
+    const report = detectDrift(graph);
+    const brokenIssues = report.issues.filter((i) => i.kind === "broken-edge");
+    expect(brokenIssues.length).toBeGreaterThanOrEqual(1);
+    expect(brokenIssues[0].nodeId).toBe("function:auth");
+    expect(brokenIssues[0].missingNodeId).toBe("node:deleted");
+    expect(report.driftedNodeIds).toContain("function:auth");
+    expect(report.driftedNodeIds).not.toContain("node:deleted");
+  });
+
+  it("detects a missing edge when a contract call has no graph edge", () => {
+    const graph = makeGraph({
+      nodes: makeGraph().nodes.map((n) =>
+        n.id === "function:auth"
+          ? makeNode("function:auth", { contractCalls: [{ target: "api:users", kind: "calls" }] })
+          : n
+      ),
+    });
+
+    const report = detectDrift(graph);
+    const missingIssues = report.issues.filter((i) => i.kind === "missing-edge");
+    expect(missingIssues.length).toBeGreaterThanOrEqual(1);
+    expect(missingIssues[0].edgeFrom).toBe("function:auth");
+    expect(missingIssues[0].edgeTo).toBe("api:users");
+  });
+
+  it("does NOT report a missing-edge when the edge already exists", () => {
+    const graph = makeGraph({
+      nodes: makeGraph().nodes.map((n) =>
+        n.id === "function:auth"
+          ? makeNode("function:auth", { contractCalls: [{ target: "api:users", kind: "calls" }] })
+          : n
+      ),
+      edges: [edge("function:auth", "api:users", "calls")],
+    });
+
+    const report = detectDrift(graph);
+    expect(report.issues.filter((i) => i.kind === "missing-edge")).toHaveLength(0);
+  });
+
+  it("detects signature drift when node signature does not match first method", () => {
+    const graph = makeGraph({
+      nodes: makeGraph().nodes.map((n) =>
+        n.id === "function:auth"
+          ? makeNode("function:auth", {
+              signature: "authenticate(token: string): void",
+              firstMethodSignature: "authenticate(token: string, opts?: Options): string",
+            })
+          : n
+      ),
+    });
+
+    const report = detectDrift(graph);
+    const driftIssues = report.issues.filter((i) => i.kind === "signature-drift");
+    expect(driftIssues.length).toBeGreaterThanOrEqual(1);
+    expect(driftIssues[0].nodeId).toBe("function:auth");
+  });
+
+  it("does NOT report signature drift when signatures match", () => {
+    const sig = "authenticate(token: string): string";
+    const graph = makeGraph({
+      nodes: makeGraph().nodes.map((n) =>
+        n.id === "function:auth"
+          ? makeNode("function:auth", {
+              signature: sig,
+              firstMethodSignature: sig,
+            })
+          : n
+      ),
+    });
+
+    const report = detectDrift(graph);
+    expect(report.issues.filter((i) => i.kind === "signature-drift")).toHaveLength(0);
+  });
+
+  it("populates driftedNodeIds with unique node IDs", () => {
+    const graph = makeGraph({
+      edges: [edge("node:ghost", "function:auth")],
+    });
+
+    const report = detectDrift(graph);
+    expect(report.driftedNodeIds).toContain("function:auth");
+    expect(report.driftedNodeIds).not.toContain("node:ghost");
+    expect(
+      report.driftedNodeIds.filter((id) => id === "function:auth")
+    ).toHaveLength(1);
+  });
+
+  it("includes projectName and detectedAt in the report", () => {
+    const report = detectDrift(makeGraph());
+    expect(report.projectName).toBe("TestApp");
+    expect(report.detectedAt).toBeTruthy();
+  });
+});
+
+// ── healGraph ────────────────────────────────────────────────────────────────
+
+describe("healGraph", () => {
+  it("returns unchanged graph when the report is healthy", () => {
+    const graph = makeGraph();
+    const report = detectDrift(graph);
+    const result = healGraph(graph, report);
+
+    expect(result.issuesFixed).toBe(0);
+    expect(result.graph.edges).toHaveLength(0);
+    expect(result.graph.nodes).toHaveLength(graph.nodes.length);
+  });
+
+  it("removes broken edges", () => {
+    const graph = makeGraph({
+      edges: [edge("node:ghost", "function:auth"), edge("function:auth", "api:users")],
+    });
+
+    const report = detectDrift(graph);
+    const result = healGraph(graph, report);
+
+    expect(result.graph.edges.some((e) => e.from === "node:ghost")).toBe(false);
+    expect(
+      result.graph.edges.some((e) => e.from === "function:auth" && e.to === "api:users")
+    ).toBe(true);
+    expect(result.issuesFixed).toBeGreaterThanOrEqual(1);
+    expect(result.summary.some((s) => s.includes("Removed broken edge"))).toBe(true);
+  });
+
+  it("adds missing edges from contract calls", () => {
+    const graph = makeGraph({
+      nodes: makeGraph().nodes.map((n) =>
+        n.id === "function:auth"
+          ? makeNode("function:auth", { contractCalls: [{ target: "api:users", kind: "calls" }] })
+          : n
+      ),
+    });
+
+    const report = detectDrift(graph);
+    const result = healGraph(graph, report);
+
+    expect(
+      result.graph.edges.some(
+        (e) => e.from === "function:auth" && e.to === "api:users" && e.kind === "calls"
+      )
+    ).toBe(true);
+    expect(result.issuesFixed).toBeGreaterThanOrEqual(1);
+    expect(result.summary.some((s) => s.includes("Added missing edge"))).toBe(true);
+  });
+
+  it("does not duplicate edges when healing the same missing edge twice", () => {
+    const graph = makeGraph({
+      nodes: makeGraph().nodes.map((n) =>
+        n.id === "function:auth"
+          ? makeNode("function:auth", { contractCalls: [{ target: "api:users", kind: "calls" }] })
+          : n
+      ),
+    });
+
+    const report = detectDrift(graph);
+    const result = healGraph(graph, report);
+
+    const edgesFromAuth = result.graph.edges.filter(
+      (e) => e.from === "function:auth" && e.to === "api:users"
+    );
+    expect(edgesFromAuth).toHaveLength(1);
+  });
+
+  it("syncs signature drift to the first contract method signature", () => {
+    const correctedSig = "authenticate(token: string, opts?: Options): string";
+    const graph = makeGraph({
+      nodes: makeGraph().nodes.map((n) =>
+        n.id === "function:auth"
+          ? makeNode("function:auth", {
+              signature: "authenticate(token: string): void",
+              firstMethodSignature: correctedSig,
+            })
+          : n
+      ),
+    });
+
+    const report = detectDrift(graph);
+    const result = healGraph(graph, report);
+
+    const authNode = result.graph.nodes.find((n) => n.id === "function:auth");
+    expect(authNode?.signature).toBe(correctedSig);
+    expect(result.issuesFixed).toBeGreaterThanOrEqual(1);
+    expect(result.summary.some((s) => s.includes("Synced signature"))).toBe(true);
+  });
+
+  it("does not mutate the original graph", () => {
+    const graph = makeGraph({
+      edges: [edge("node:ghost", "function:auth")],
+    });
+    const originalEdgeCount = graph.edges.length;
+
+    const report = detectDrift(graph);
+    healGraph(graph, report);
+
+    expect(graph.edges).toHaveLength(originalEdgeCount);
+  });
+
+  it("includes provenance and maturity in the result", () => {
+    const graph = makeGraph();
+    const report = detectDrift(graph);
+    const result = healGraph(graph, report);
+
+    expect(result.projectName).toBe("TestApp");
+    expect(result.healedAt).toBeTruthy();
+    expect(result.provenance).toBe("deterministic");
+    expect(result.maturity).toBe("preview");
+    expect(result.scope).toBe("graph");
+  });
+
+  it("synthesises one edge per distinct (from, to, kind) when multiple calls have different kinds", () => {
+    const graph = makeGraph({
+      nodes: makeGraph().nodes.map((n) =>
+        n.id === "function:auth"
+          ? makeNode("function:auth", {
+              contractCalls: [
+                { target: "api:users", kind: "calls" },
+                { target: "api:users", kind: "reads-state" },
+              ],
+            })
+          : n
+      ),
+    });
+
+    const report = detectDrift(graph);
+    const missingIssues = report.issues.filter((i) => i.kind === "missing-edge");
+    // Two distinct kinds → two distinct missing-edge issues.
+    expect(missingIssues).toHaveLength(2);
+
+    const result = healGraph(graph, report);
+
+    const callsEdges = result.graph.edges.filter(
+      (e) => e.from === "function:auth" && e.to === "api:users" && e.kind === "calls"
+    );
+    const readsEdges = result.graph.edges.filter(
+      (e) => e.from === "function:auth" && e.to === "api:users" && e.kind === "reads-state"
+    );
+    expect(callsEdges).toHaveLength(1);
+    expect(readsEdges).toHaveLength(1);
+    expect(result.issuesFixed).toBe(2);
+  });
+});

package/src/refactor.ts

@@ -0,0 +1,290 @@
+import type {
+  BlueprintEdge,
+  BlueprintEdgeKind,
+  BlueprintGraph,
+  BlueprintNode,
+  FeatureMaturity,
+  OutputProvenance,
+} from "@/lib/blueprint/schema";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/** The category of architectural drift that was detected. */
+export type DriftKind = "broken-edge" | "missing-edge" | "signature-drift";
+
+/**
+ * A single detected drift issue in the architecture graph.
+ *
+ * - `broken-edge`     – An edge references a node ID that no longer exists.
+ * - `missing-edge`    – A node's contract `calls` entry has no corresponding
+ *                       graph edge to the resolved target node.
+ * - `signature-drift` – The node's top-level `signature` field doesn't match
+ *                       the `signature` of its first contract method.
+ */
+export interface DriftIssue {
+  kind: DriftKind;
+  /** ID of the existing node most closely associated with this issue. */
+  nodeId: string;
+  nodeName: string;
+  description: string;
+  /** Source node ID of the affected edge (present for edge-related issues). */
+  edgeFrom?: string;
+  /** Target node ID of the affected edge (present for edge-related issues). */
+  edgeTo?: string;
+  /**
+   * The node ID referenced by the edge that no longer exists in the graph
+   * (only set for `broken-edge` issues where the missing ID differs from `nodeId`).
+   */
+  missingNodeId?: string;
+  /**
+   * For `missing-edge` issues: the edge `kind` declared in the contract call.
+   * Used during healing to distinguish multiple calls between the same pair of
+   * nodes with different relationship kinds (e.g. `calls` vs `reads-state`).
+   */
+  edgeKind?: BlueprintEdgeKind;
+}
+
+/** Summary of all drift issues detected in a graph. */
+export interface RefactorReport {
+  projectName: string;
+  detectedAt: string;
+  provenance: OutputProvenance;
+  maturity: FeatureMaturity;
+  scope: "graph";
+  issues: DriftIssue[];
+  /** IDs of nodes that have at least one drift issue. */
+  driftedNodeIds: string[];
+  totalIssues: number;
+  /** `true` when no drift was found. */
+  isHealthy: boolean;
+}
+
+/** Result of a heal operation that auto-fixed drift issues. */
+export interface HealResult {
+  projectName: string;
+  healedAt: string;
+  provenance: OutputProvenance;
+  maturity: FeatureMaturity;
+  scope: "graph";
+  issuesFixed: number;
+  graph: BlueprintGraph;
+  summary: string[];
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+const buildNodeIndex = (graph: BlueprintGraph): Map<string, BlueprintNode> =>
+  new Map(graph.nodes.map((n) => [n.id, n]));
+
+/**
+ * Resolve a contract call `target` (which may be a node ID or node name) to
+ * the matching blueprint node.
+ */
+const resolveCallTarget = (
+  graph: BlueprintGraph,
+  target: string
+): BlueprintNode | undefined => {
+  const byId = graph.nodes.find((n) => n.id === target);
+  if (byId) return byId;
+  return graph.nodes.find((n) => n.name === target);
+};
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Detect architectural drift in a blueprint graph.
+ *
+ * Three kinds of drift are checked:
+ * 1. **Broken edges** – an edge's `from` or `to` points to a node ID that no
+ *    longer exists in the graph.
+ * 2. **Missing edges** – a node's contract `calls` entry references a target
+ *    that exists in the graph but has no corresponding edge.
+ * 3. **Signature drift** – the node's top-level `signature` field doesn't
+ *    match the `signature` of its first contract method.
+ */
+export const detectDrift = (graph: BlueprintGraph): RefactorReport => {
+  const issues: DriftIssue[] = [];
+  const index = buildNodeIndex(graph);
+
+  // ── 1. Broken edges ────────────────────────────────────────────────────────
+  for (const edge of graph.edges) {
+    if (!index.has(edge.from)) {
+      const existingNode = index.get(edge.to);
+      issues.push({
+        kind: "broken-edge",
+        nodeId: existingNode?.id ?? edge.to,
+        nodeName: existingNode?.name ?? edge.to,
+        description: `Edge "${edge.from}" → "${edge.to}" references a non-existent source node.`,
+        edgeFrom: edge.from,
+        edgeTo: edge.to,
+        missingNodeId: edge.from,
+      });
+    }
+
+    if (!index.has(edge.to)) {
+      const existingNode = index.get(edge.from);
+      issues.push({
+        kind: "broken-edge",
+        nodeId: existingNode?.id ?? edge.from,
+        nodeName: existingNode?.name ?? edge.from,
+        description: `Edge "${edge.from}" → "${edge.to}" references a non-existent target node.`,
+        edgeFrom: edge.from,
+        edgeTo: edge.to,
+        missingNodeId: edge.to,
+      });
+    }
+  }
+
+  // ── 2. Missing edges + signature drift ────────────────────────────────────
+  for (const node of graph.nodes) {
+    // Signature drift: top-level signature doesn't match the first method's.
+    const firstMethod = node.contract.methods?.[0];
+    if (
+      node.signature &&
+      firstMethod?.signature &&
+      node.signature !== firstMethod.signature
+    ) {
+      issues.push({
+        kind: "signature-drift",
+        nodeId: node.id,
+        nodeName: node.name,
+        description: `Node "${node.name}" signature "${node.signature}" does not match contract method "${firstMethod.signature}".`,
+      });
+    }
+
+    // Missing edges: contract calls with no corresponding graph edge.
+    for (const call of node.contract.calls ?? []) {
+      const targetNode = resolveCallTarget(graph, call.target);
+      if (!targetNode) continue; // target not in graph – not our responsibility here
+
+      const edgeKind = call.kind ?? "calls";
+      const edgeExists = graph.edges.some(
+        (e) => e.from === node.id && e.to === targetNode.id && e.kind === edgeKind
+      );
+
+      if (!edgeExists) {
+        issues.push({
+          kind: "missing-edge",
+          nodeId: node.id,
+          nodeName: node.name,
+          description: `Node "${node.name}" declares a "${edgeKind}" call to "${call.target}" in its contract but no graph edge exists.`,
+          edgeFrom: node.id,
+          edgeTo: targetNode.id,
+          edgeKind,
+        });
+      }
+    }
+  }
+
+  const driftedNodeIds = [...new Set(issues.map((i) => i.nodeId))];
+
+  return {
+    projectName: graph.projectName,
+    detectedAt: new Date().toISOString(),
+    provenance: "deterministic",
+    maturity: "preview",
+    scope: "graph",
+    issues,
+    driftedNodeIds,
+    totalIssues: issues.length,
+    isHealthy: issues.length === 0,
+  };
+};
+
+/**
+ * Auto-heal a blueprint graph based on a previously computed {@link RefactorReport}.
+ *
+ * Healing actions:
+ * - **Broken edges** are removed.
+ * - **Missing edges** are synthesised from the contract call definitions.
+ * - **Signature drift** is resolved by syncing the node's top-level
+ *   `signature` to match its first contract method.
+ *
+ * The original graph is not mutated; a new graph object is returned.
+ */
+export const healGraph = (graph: BlueprintGraph, report: RefactorReport): HealResult => {
+  const index = buildNodeIndex(graph);
+  const summary: string[] = [];
+  let issuesFixed = 0;
+
+  // ── Remove broken edges ─────────────────────────────────────────────────────
+  const healedEdges = graph.edges.filter((edge) => {
+    if (!index.has(edge.from) || !index.has(edge.to)) {
+      summary.push(`Removed broken edge: ${edge.from} → ${edge.to}`);
+      issuesFixed++;
+      return false;
+    }
+    return true;
+  });
+
+  // ── Synthesise missing edges ────────────────────────────────────────────────
+  const newEdges: BlueprintEdge[] = [];
+
+  const missingEdgeIssues = report.issues.filter((i) => i.kind === "missing-edge");
+
+  for (const issue of missingEdgeIssues) {
+    if (!issue.edgeFrom || !issue.edgeTo) continue;
+
+    const issueEdgeKind = issue.edgeKind ?? "calls";
+    const alreadyAdded = newEdges.some(
+      (e) => e.from === issue.edgeFrom && e.to === issue.edgeTo && e.kind === issueEdgeKind
+    );
+    if (alreadyAdded) continue;
+
+    // Find the original contract call to preserve kind/label. Match on both
+    // target node ID and kind so that multiple calls between the same pair with
+    // different kinds each resolve to their own contract entry.
+    const fromNode = index.get(issue.edgeFrom);
+    const call = fromNode?.contract.calls?.find((c) => {
+      const target = resolveCallTarget(graph, c.target);
+      return target?.id === issue.edgeTo && (c.kind ?? "calls") === issueEdgeKind;
+    });
+
+    newEdges.push({
+      from: issue.edgeFrom,
+      to: issue.edgeTo,
+      kind: issueEdgeKind,
+      required: false,
+      confidence: 0.8,
+      label: call?.description,
+    });
+
+    const fromName = fromNode?.name ?? issue.edgeFrom;
+    const toName = index.get(issue.edgeTo)?.name ?? issue.edgeTo;
+    summary.push(`Added missing edge: ${fromName} → ${toName}`);
+    issuesFixed++;
+  }
+
+  // ── Fix signature drift ────────────────────────────────────────────────────
+  const healedNodes = graph.nodes.map((node) => {
+    const hasDrift = report.issues.some(
+      (i) => i.kind === "signature-drift" && i.nodeId === node.id
+    );
+    if (!hasDrift) return node;
+
+    const firstMethod = node.contract.methods?.[0];
+    if (!firstMethod?.signature) return node;
+
+    summary.push(
+      `Synced signature for "${node.name}": "${node.signature}" → "${firstMethod.signature}"`
+    );
+    issuesFixed++;
+
+    return { ...node, signature: firstMethod.signature };
+  });
+
+  return {
+    projectName: graph.projectName,
+    healedAt: new Date().toISOString(),
+    provenance: "deterministic",
+    maturity: "preview",
+    scope: "graph",
+    issuesFixed,
+    graph: {
+      ...graph,
+      nodes: healedNodes,
+      edges: [...healedEdges, ...newEdges],
+    },
+    summary,
+  };
+};