@abhinav2203/codeflow-analysis 0.1.0

package/src/conflicts.test.ts

@@ -0,0 +1,134 @@
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { detectGraphConflicts } from "./conflicts";
+import type { BlueprintGraph } from "@/lib/blueprint/schema";
+import { emptyContract } from "@/lib/blueprint/schema";
+
+const fixturePath = path.resolve(process.cwd(), "test-fixtures/sample-repo");
+
+const node = (
+  id: string,
+  overrides: Partial<{
+    kind: BlueprintGraph["nodes"][number]["kind"];
+    path: string;
+    name: string;
+    summary: string;
+    signature: string;
+    sourceRefsPath: string;
+  }> = {}
+): BlueprintGraph["nodes"][number] => ({
+  id,
+  kind: overrides.kind ?? "function",
+  name: overrides.name ?? id,
+  path: overrides.path,
+  summary: overrides.summary ?? id,
+  signature: overrides.signature,
+  contract: { ...emptyContract(), summary: overrides.summary ?? id },
+  sourceRefs: overrides.sourceRefsPath
+    ? [{ kind: "repo" as const, path: overrides.sourceRefsPath, symbol: overrides.name ?? id }]
+    : [],
+  generatedRefs: [],
+  traceRefs: [],
+});
+
+describe("detectGraphConflicts", () => {
+  it("finds a signature-mismatch when blueprint signature diverges from repo", async () => {
+    const graph: BlueprintGraph = {
+      projectName: "Conflicts",
+      mode: "essential",
+      generatedAt: "2026-03-14T00:00:00.000Z",
+      warnings: [],
+      workflows: [],
+      edges: [],
+      nodes: [
+        node("function:normalize", {
+          kind: "function",
+          path: "src/services/task-service.ts",
+          name: "normalizeTask",
+          summary: "Wrong summary.",
+          signature: "normalizeTask(input: string): string",
+          sourceRefsPath: "src/services/task-service.ts",
+        }),
+      ],
+    };
+
+    const report = await detectGraphConflicts(graph, fixturePath);
+
+    expect(report.conflicts.some((c) => c.kind === "signature-mismatch")).toBe(true);
+  });
+
+  it("finds missing-in-blueprint when repo has a symbol not in the blueprint", async () => {
+    const graph: BlueprintGraph = {
+      projectName: "MissingInBlueprint",
+      mode: "essential",
+      generatedAt: "2026-03-14T00:00:00.000Z",
+      warnings: [],
+      workflows: [],
+      edges: [],
+      nodes: [], // empty — all repo symbols should be reported missing
+    };
+
+    const report = await detectGraphConflicts(graph, fixturePath);
+
+    expect(report.conflicts.some((c) => c.kind === "missing-in-blueprint")).toBe(true);
+  });
+
+  it("returns empty conflicts for an empty graph and empty repo", async () => {
+    // Using a path that exists but has no matching symbols
+    const report = await detectGraphConflicts(
+      {
+        projectName: "Empty",
+        mode: "essential",
+        generatedAt: "2026-03-14T00:00:00.000Z",
+        warnings: [],
+        workflows: [],
+        edges: [],
+        nodes: [],
+      },
+      fixturePath
+    );
+
+    // sample-repo has symbols, so missing-in-blueprint will fire
+    // but there should be no signature-mismatch
+    expect(report.conflicts.every((c) => c.kind === "missing-in-blueprint")).toBe(true);
+  });
+
+  it("returns a valid checkedAt timestamp", async () => {
+    const report = await detectGraphConflicts(
+      {
+        projectName: "Timestamp",
+        mode: "essential",
+        generatedAt: "2026-03-14T00:00:00.000Z",
+        warnings: [],
+        workflows: [],
+        edges: [],
+        nodes: [],
+      },
+      fixturePath
+    );
+
+    expect(() => new Date(report.checkedAt)).not.toThrow();
+    expect(report.repoPath).toBe(path.resolve(fixturePath));
+  });
+
+  it("includes suggestedAction on every conflict", async () => {
+    const report = await detectGraphConflicts(
+      {
+        projectName: "Suggestions",
+        mode: "essential",
+        generatedAt: "2026-03-14T00:00:00.000Z",
+        warnings: [],
+        workflows: [],
+        edges: [],
+        nodes: [],
+      },
+      fixturePath
+    );
+
+    for (const conflict of report.conflicts) {
+      expect(conflict.suggestedAction.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/conflicts.ts

@@ -0,0 +1,106 @@
+import path from "node:path";
+
+import { analyzeTypeScriptRepo } from "@/lib/blueprint/repo";
+import type {
+  BlueprintGraph,
+  BlueprintNode,
+  ConflictRecord,
+  ConflictReport,
+} from "@/lib/blueprint/schema";
+
+const repoKeyForNode = (node: BlueprintNode): string =>
+  `${node.kind}:${node.path ?? ""}:${node.name}`;
+
+/**
+ * Detect structural conflicts between a blueprint graph and a live TypeScript repository.
+ *
+ * Conflicts detected:
+ * - `missing-in-repo`     – blueprint node has no corresponding symbol in the repo snapshot.
+ * - `missing-in-blueprint` – repo has a symbol not represented in the blueprint.
+ * - `signature-mismatch`  – blueprint node `signature` differs from the repo-derived signature.
+ * - `summary-mismatch`   – blueprint node `summary` differs from the repo-derived summary.
+ */
+export const detectGraphConflicts = async (
+  graph: BlueprintGraph,
+  repoPath: string
+): Promise<ConflictReport> => {
+  const repoGraph = await analyzeTypeScriptRepo(path.resolve(repoPath));
+  const conflicts: ConflictRecord[] = [];
+
+  // Only consider code-bearing nodes (not modules, which are structural containers).
+  const repoNodes = repoGraph.nodes.filter((node) => node.kind !== "module");
+  const blueprintRepoNodes = graph.nodes.filter((node) =>
+    node.sourceRefs.some((ref) => ref.kind === "repo")
+  );
+
+  const repoMap = new Map(repoNodes.map((node) => [repoKeyForNode(node), node]));
+  const blueprintMap = new Map(blueprintRepoNodes.map((node) => [repoKeyForNode(node), node]));
+
+  // Check each blueprint node against the repo snapshot.
+  for (const blueprintNode of blueprintRepoNodes) {
+    const repoNode = repoMap.get(repoKeyForNode(blueprintNode));
+
+    if (!repoNode) {
+      conflicts.push({
+        kind: "missing-in-repo",
+        nodeId: blueprintNode.id,
+        path: blueprintNode.path,
+        blueprintValue: blueprintNode.name,
+        message: `${blueprintNode.name} is in the blueprint but not in the repo snapshot.`,
+        suggestedAction:
+          "Remove the node from the blueprint or recreate it in the repo.",
+      });
+      continue;
+    }
+
+    if ((blueprintNode.signature ?? "") !== (repoNode.signature ?? "")) {
+      conflicts.push({
+        kind: "signature-mismatch",
+        nodeId: blueprintNode.id,
+        path: blueprintNode.path,
+        blueprintValue: blueprintNode.signature,
+        repoValue: repoNode.signature,
+        message: `${blueprintNode.name} has a different signature in the repo.`,
+        suggestedAction:
+          "Refresh the blueprint contract from the repo or update the implementation.",
+      });
+    }
+
+    if (
+      blueprintNode.summary &&
+      repoNode.summary &&
+      blueprintNode.summary !== repoNode.summary
+    ) {
+      conflicts.push({
+        kind: "summary-mismatch",
+        nodeId: blueprintNode.id,
+        path: blueprintNode.path,
+        blueprintValue: blueprintNode.summary,
+        repoValue: repoNode.summary,
+        message: `${blueprintNode.name} summary diverges from the repo-derived description.`,
+        suggestedAction:
+          "Review the contract summary and align it with current behavior.",
+      });
+    }
+  }
+
+  // Detect repo symbols missing from the blueprint.
+  for (const repoNode of repoNodes) {
+    if (!blueprintMap.has(repoKeyForNode(repoNode))) {
+      conflicts.push({
+        kind: "missing-in-blueprint",
+        path: repoNode.path,
+        repoValue: repoNode.name,
+        message: `${repoNode.name} exists in the repo but is not represented in the blueprint.`,
+        suggestedAction:
+          "Add the node to the blueprint or mark it intentionally out of scope.",
+      });
+    }
+  }
+
+  return {
+    checkedAt: new Date().toISOString(),
+    repoPath: path.resolve(repoPath),
+    conflicts,
+  };
+};

package/src/cycles.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+
+import { detectCycles, hasCycles } from "./cycles";
+import type { BlueprintGraph } from "@/lib/blueprint/schema";
+import { emptyContract } from "@/lib/blueprint/schema";
+
+const node = (id: string): BlueprintGraph["nodes"][number] => ({
+  id,
+  kind: "module",
+  name: id,
+  summary: id,
+  contract: emptyContract(),
+  sourceRefs: [],
+  generatedRefs: [],
+  traceRefs: [],
+});
+
+const edge = (from: string, to: string): BlueprintGraph["edges"][number] => ({
+  from,
+  to,
+  kind: "calls",
+  required: true,
+  confidence: 1,
+});
+
+const graph = (
+  projectName: string,
+  nodes: BlueprintGraph["nodes"],
+  edges: BlueprintGraph["edges"]
+): BlueprintGraph => ({
+  projectName,
+  mode: "essential",
+  generatedAt: "2026-03-14T00:00:00.000Z",
+  warnings: [],
+  workflows: [],
+  nodes,
+  edges,
+});
+
+describe("detectCycles", () => {
+  it("returns no cycles for a DAG", () => {
+    const report = detectCycles(
+      graph(
+        "DAG",
+        [node("A"), node("B"), node("C")],
+        [edge("A", "B"), edge("B", "C")]
+      )
+    );
+
+    expect(report.totalCycles).toBe(0);
+    expect(report.affectedNodeIds).toHaveLength(0);
+  });
+
+  it("detects a simple two-node cycle", () => {
+    const report = detectCycles(
+      graph("TwoNodeCycle", [node("A"), node("B")], [edge("A", "B"), edge("B", "A")])
+    );
+
+    expect(report.totalCycles).toBe(1);
+    expect(report.affectedNodeIds).toContain("A");
+    expect(report.affectedNodeIds).toContain("B");
+  });
+
+  it("detects multiple independent cycles", () => {
+    const report = detectCycles(
+      graph(
+        "MultiCycle",
+        [node("A"), node("B"), node("C"), node("D")],
+        [edge("A", "B"), edge("B", "A"), edge("C", "D"), edge("D", "C")]
+      )
+    );
+
+    expect(report.totalCycles).toBe(2);
+  });
+
+  it("handles empty graph", () => {
+    const report = detectCycles(graph("Empty", [], []));
+
+    expect(report.totalCycles).toBe(0);
+  });
+
+  it("detects a self-loop edge as a cycle", () => {
+    const report = detectCycles(
+      graph("SelfLoop", [node("A")], [{ from: "A", to: "A", kind: "calls", required: true, confidence: 1 }])
+    );
+
+    expect(report.totalCycles).toBe(1);
+    expect(report.affectedNodeIds).toContain("A");
+  });
+
+  it("returns maxCycleLength correctly", () => {
+    const report = detectCycles(
+      graph(
+        "ThreeCycle",
+        [node("A"), node("B"), node("C")],
+        [edge("A", "B"), edge("B", "C"), edge("C", "A")]
+      )
+    );
+
+    expect(report.totalCycles).toBe(1);
+    expect(report.maxCycleLength).toBe(3);
+  });
+
+  it("cycles array contains edges belonging to the SCC", () => {
+    const report = detectCycles(
+      graph("EdgeCycle", [node("X"), node("Y")], [edge("X", "Y"), edge("Y", "X")])
+    );
+
+    const cycle = report.cycles[0];
+    expect(cycle.nodeIds).toContain("X");
+    expect(cycle.nodeIds).toContain("Y");
+    expect(cycle.edges).toHaveLength(2);
+    expect(cycle.edges.map((e) => `${e.from}→${e.to}`)).toEqual(expect.arrayContaining(["X→Y", "Y→X"]));
+  });
+});
+
+describe("hasCycles", () => {
+  it("returns false for a DAG", () => {
+    expect(
+      hasCycles(
+        graph("DAG", [node("A"), node("B")], [edge("A", "B")])
+      )
+    ).toBe(false);
+  });
+
+  it("returns true when a two-node cycle exists", () => {
+    expect(
+      hasCycles(
+        graph("Cyclic", [node("A"), node("B")], [edge("A", "B"), edge("B", "A")])
+      )
+    ).toBe(true);
+  });
+
+  it("returns true for a self-loop", () => {
+    expect(
+      hasCycles(
+        graph("SelfLoop", [node("A")], [{ from: "A", to: "A", kind: "calls", required: true, confidence: 1 }])
+      )
+    ).toBe(true);
+  });
+
+  it("returns false for empty graph", () => {
+    expect(hasCycles(graph("Empty", [], []))).toBe(false);
+  });
+});

package/src/cycles.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+
+import type { BlueprintGraph } from "@/lib/blueprint/schema";
+
+export const cycleSchema = z.object({
+  nodeIds: z.array(z.string()),
+  edges: z.array(
+    z.object({
+      from: z.string(),
+      to: z.string(),
+      kind: z.string(),
+    })
+  ),
+});
+export type Cycle = z.infer<typeof cycleSchema>;
+
+export const cycleReportSchema = z.object({
+  analyzedAt: z.string(),
+  totalCycles: z.number(),
+  maxCycleLength: z.number(),
+  cycles: z.array(cycleSchema),
+  affectedNodeIds: z.array(z.string()),
+});
+export type CycleReport = z.infer<typeof cycleReportSchema>;
+
+const tarjanIterative = (nodeIds: string[], adjacency: Map<string, string[]>): string[][] => {
+  const indices = new Map<string, number>();
+  const lowlinks = new Map<string, number>();
+  const onStack = new Set<string>();
+  const stack: string[] = [];
+  const sccs: string[][] = [];
+  let index = 0;
+
+  type Frame = {
+    node: string;
+    neighborIndex: number;
+    neighbors: string[];
+  };
+
+  for (const root of nodeIds) {
+    if (indices.has(root)) continue;
+
+    const callStack: Frame[] = [{ node: root, neighborIndex: 0, neighbors: adjacency.get(root) ?? [] }];
+    indices.set(root, index);
+    lowlinks.set(root, index);
+    index++;
+    stack.push(root);
+    onStack.add(root);
+
+    while (callStack.length > 0) {
+      const frame = callStack[callStack.length - 1];
+
+      if (frame.neighborIndex < frame.neighbors.length) {
+        const neighbor = frame.neighbors[frame.neighborIndex];
+        frame.neighborIndex++;
+
+        if (!indices.has(neighbor)) {
+          indices.set(neighbor, index);
+          lowlinks.set(neighbor, index);
+          index++;
+          stack.push(neighbor);
+          onStack.add(neighbor);
+          callStack.push({ node: neighbor, neighborIndex: 0, neighbors: adjacency.get(neighbor) ?? [] });
+        } else if (onStack.has(neighbor)) {
+          lowlinks.set(frame.node, Math.min(lowlinks.get(frame.node)!, lowlinks.get(neighbor)!));
+        }
+      } else {
+        if (lowlinks.get(frame.node) === indices.get(frame.node)) {
+          const scc: string[] = [];
+          let w: string;
+          do {
+            w = stack.pop()!;
+            onStack.delete(w);
+            scc.push(w);
+          } while (w !== frame.node);
+          sccs.push(scc);
+        }
+
+        callStack.pop();
+        if (callStack.length > 0) {
+          const parent = callStack[callStack.length - 1];
+          lowlinks.set(parent.node, Math.min(lowlinks.get(parent.node)!, lowlinks.get(frame.node)!));
+        }
+      }
+    }
+  }
+
+  return sccs;
+};
+
+/**
+ * Detect all directed cycles in a blueprint graph using Tarjan's strongly-connected
+ * components algorithm (iterative, stack-safe).
+ *
+ * Self-loop edges (from === to) are detected separately and treated as single-node cycles.
+ */
+export const detectCycles = (graph: BlueprintGraph): CycleReport => {
+  const nodeIds = graph.nodes.map((n) => n.id);
+  const adjacency = new Map<string, string[]>();
+
+  for (const id of nodeIds) {
+    adjacency.set(id, []);
+  }
+  for (const edge of graph.edges) {
+    adjacency.get(edge.from)?.push(edge.to);
+  }
+
+  const sccs = tarjanIterative(nodeIds, adjacency);
+
+  // A self-loop (from === to) is a genuine cycle but Tarjan's SCC returns it as
+  // a size-1 SCC. Detect them separately and treat them as single-node cycles.
+  const selfLoopNodeIds = new Set(
+    graph.edges.filter((e) => e.from === e.to).map((e) => e.from)
+  );
+  const selfLoopSccs: string[][] = [...selfLoopNodeIds].map((id) => [id]);
+
+  const sccSet = [
+    ...sccs.filter((scc) => scc.length >= 2),
+    ...selfLoopSccs
+  ];
+
+  const cycles: Cycle[] = sccSet.map((scc) => {
+    const memberSet = new Set(scc);
+    const edges = graph.edges
+      .filter((e) => memberSet.has(e.from) && memberSet.has(e.to))
+      .map((e) => ({ from: e.from, to: e.to, kind: e.kind }));
+    return { nodeIds: scc, edges };
+  });
+
+  const affectedNodeIds = [...new Set(cycles.flatMap((c) => c.nodeIds))];
+  const maxCycleLength = cycles.reduce((max, c) => Math.max(max, c.nodeIds.length), 0);
+
+  return {
+    analyzedAt: new Date().toISOString(),
+    totalCycles: cycles.length,
+    maxCycleLength,
+    cycles,
+    affectedNodeIds,
+  };
+};
+
+/**
+ * Returns true if the graph contains at least one directed cycle.
+ * Faster than detectCycles — stops early on the first cycle found.
+ */
+export const hasCycles = (graph: BlueprintGraph): boolean => {
+  if (graph.edges.some((e) => e.from === e.to)) return true;
+
+  const nodeIds = graph.nodes.map((n) => n.id);
+  const adjacency = new Map<string, string[]>();
+
+  for (const id of nodeIds) {
+    adjacency.set(id, []);
+  }
+  for (const edge of graph.edges) {
+    adjacency.get(edge.from)?.push(edge.to);
+  }
+
+  const sccs = tarjanIterative(nodeIds, adjacency);
+  return sccs.some((scc) => scc.length >= 2);
+};

package/src/handlers/conflicts.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from "next/server";
+
+import { detectGraphConflicts } from "../conflicts";
+import { conflictCheckRequestSchema } from "@/lib/blueprint/schema";
+
+/**
+ * POST /api/conflicts
+ *
+ * Body: { graph: BlueprintGraph, repoPath: string }
+ *
+ * Compares a blueprint graph against a live TypeScript repository,
+ * detecting signature mismatches, summary mismatches, missing-in-repo
+ * nodes, and missing-in-blueprint symbols.
+ */
+export async function POST(request: Request) {
+  try {
+    const payload = conflictCheckRequestSchema.parse(await request.json());
+    const report = await detectGraphConflicts(payload.graph, payload.repoPath);
+
+    return NextResponse.json({ report });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error: error instanceof Error ? error.message : "Failed to analyze graph conflicts.",
+      },
+      { status: 400 }
+    );
+  }
+}

package/src/handlers/cycles.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from "next/server";
+
+import { detectCycles, hasCycles } from "../cycles";
+import { blueprintGraphSchema } from "@/lib/blueprint/schema";
+
+/**
+ * POST /api/analysis/cycles
+ *
+ * Body: {@link BlueprintGraph}
+ *
+ * Returns a cycle detection report for the submitted blueprint graph.
+ * Includes total cycle count, affected node IDs, per-cycle edge details,
+ * and a convenience `hasCycles` boolean.
+ */
+export async function POST(request: Request) {
+  try {
+    const payload = blueprintGraphSchema.parse(await request.json());
+    const report = detectCycles(payload);
+
+    return NextResponse.json({ report: { ...report, hasCycles: hasCycles(payload) } });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error: error instanceof Error ? error.message : "Failed to detect dependency cycles.",
+      },
+      { status: 400 }
+    );
+  }
+}

package/src/handlers/metrics.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from "next/server";
+
+import { computeGraphMetrics } from "../metrics";
+import { blueprintGraphSchema } from "@/lib/blueprint/schema";
+
+/**
+ * POST /api/analysis/metrics
+ *
+ * Body: {@link BlueprintGraph}
+ *
+ * Returns structural graph metrics: node/edge counts, degree statistics,
+ * density, connected components, and contract-level averages.
+ */
+export async function POST(request: Request) {
+  try {
+    const payload = blueprintGraphSchema.parse(await request.json());
+    const metrics = computeGraphMetrics(payload);
+
+    return NextResponse.json({ metrics });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error: error instanceof Error ? error.message : "Failed to compute graph metrics.",
+      },
+      { status: 400 }
+    );
+  }
+}

package/src/handlers/refactor-detect.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from "next/server";
+
+import { detectDrift } from "../refactor";
+import { blueprintGraphSchema } from "@/lib/blueprint/schema";
+
+/**
+ * POST /api/refactor/detect
+ *
+ * Body: {@link BlueprintGraph}
+ *
+ * Returns a {@link RefactorReport} describing all detected drift issues:
+ * broken edges, missing edges, and signature drift.
+ */
+export async function POST(request: Request) {
+  try {
+    const graph = blueprintGraphSchema.parse(await request.json());
+    const report = detectDrift(graph);
+
+    return NextResponse.json({ report });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error: error instanceof Error ? error.message : "Failed to detect architectural drift.",
+      },
+      { status: 400 }
+    );
+  }
+}

package/src/handlers/refactor-heal.ts

@@ -0,0 +1,32 @@
+import { NextResponse } from "next/server";
+
+import { detectDrift, healGraph } from "../refactor";
+import { blueprintGraphSchema } from "@/lib/blueprint/schema";
+
+/**
+ * POST /api/refactor/heal
+ *
+ * Body: {@link BlueprintGraph}
+ *
+ * Detects all drift issues, then auto-heals the graph:
+ * removes broken edges, synthesises missing edges from contract calls,
+ * and syncs node signatures to match their first contract method.
+ *
+ * Returns both the detection report and the healed graph.
+ */
+export async function POST(request: Request) {
+  try {
+    const graph = blueprintGraphSchema.parse(await request.json());
+    const report = detectDrift(graph);
+    const result = healGraph(graph, report);
+
+    return NextResponse.json({ report, result });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error: error instanceof Error ? error.message : "Failed to heal architectural drift.",
+      },
+      { status: 400 }
+    );
+  }
+}