@abhinav2203/codeflow-analysis 0.1.0

package/dist/bin/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * CLI entry-point shim for @abhinav2203/codeflow-analysis.
+ *
+ * This file is the executable referenced in the `bin` field of package.json.
+ * It delegates to the TypeScript source via tsx so no build step is required
+ * during development. After running `npm run build`, you can replace the
+ * tsx invocation below with a direct `node` call to dist/invoke.js.
+ */
+
+import { execFileSync } from "node:child_process";
+import { accessSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageDir = path.resolve(__dirname, "..");
+
+// Determine the entrypoint: compiled JS if built, otherwise TypeScript source.
+let entrypoint;
+try {
+  entrypoint = path.resolve(packageDir, "dist/invoke.js");
+  accessSync(entrypoint);
+} catch {
+  entrypoint = path.resolve(packageDir, "src/invoke.ts");
+}
+
+// Prefer locally installed tsx in the monorepo.
+const tsxBin = path.resolve(packageDir, "node_modules/.bin/tsx");
+
+const useNode = process.env.CLI_FORCE_NODE === "true";
+const execPath = useNode ? process.execPath : tsxBin;
+const execArgs = useNode ? [entrypoint, ...process.argv.slice(2)] : [entrypoint, ...process.argv.slice(2)];
+
+try {
+  execFileSync(execPath, execArgs, { stdio: "inherit" });
+} catch (error) {
+  if (error.status != null) {
+    process.exit(error.status);
+  }
+  console.error(error);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@abhinav2203/codeflow-analysis",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./cycles": { "types": "./dist/cycles.d.ts", "default": "./dist/cycles.js" },
+    "./smells": { "types": "./dist/smells.d.ts", "default": "./dist/smells.js" },
+    "./metrics": { "types": "./dist/metrics.d.ts", "default": "./dist/metrics.js" },
+    "./refactor": { "types": "./dist/refactor.d.ts", "default": "./dist/refactor.js" },
+    "./conflicts": { "types": "./dist/conflicts.d.ts", "default": "./dist/conflicts.js" }
+  },
+  "bin": {
+    "codeflow-analysis": "./dist/bin/cli.js"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc --outDir dist --declaration --declarationMap --noEmit false"
+  },
+  "dependencies": {
+    "@abhinav2203/codeflow-core": "workspace:*",
+    "@abhinav2203/codeflow-store": "workspace:*",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/app/api/analysis/cycles/route.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+
+import { POST } from "../../../../handlers/cycles";
+import type { BlueprintGraph } from "@/lib/blueprint/schema";
+import { emptyContract } from "@/lib/blueprint/schema";
+
+const minimalNode = (id: string): BlueprintGraph["nodes"][number] => ({
+  id,
+  kind: "function",
+  name: id,
+  summary: "A node.",
+  contract: emptyContract(),
+  sourceRefs: [],
+  generatedRefs: [],
+  traceRefs: [],
+});
+
+const minimalEdge = (from: string, to: string): BlueprintGraph["edges"][number] => ({
+  from,
+  to,
+  kind: "calls",
+  required: true,
+  confidence: 1,
+});
+
+const baseGraph: BlueprintGraph = {
+  projectName: "Cycles Route Test",
+  mode: "essential",
+  generatedAt: "2026-03-14T00:00:00.000Z",
+  warnings: [],
+  workflows: [],
+  nodes: [],
+  edges: [],
+};
+
+describe("POST /api/analysis/cycles", () => {
+  it("returns a cycle report with no cycles for a clean DAG", async () => {
+    const graph: BlueprintGraph = {
+      ...baseGraph,
+      nodes: [minimalNode("function:a"), minimalNode("function:b"), minimalNode("function:c")],
+      edges: [minimalEdge("function:a", "function:b"), minimalEdge("function:b", "function:c")],
+    };
+
+    const response = await POST(
+      new Request("http://localhost/api/analysis/cycles", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(graph),
+      })
+    );
+    const body = await response.json() as { report: { totalCycles: number; hasCycles: boolean } };
+
+    expect(response.status).toBe(200);
+    expect(body.report.totalCycles).toBe(0);
+    expect(body.report.hasCycles).toBe(false);
+  });
+
+  it("detects a cycle between two mutually dependent nodes", async () => {
+    const graph: BlueprintGraph = {
+      ...baseGraph,
+      nodes: [minimalNode("function:a"), minimalNode("function:b")],
+      edges: [minimalEdge("function:a", "function:b"), minimalEdge("function:b", "function:a")],
+    };
+
+    const response = await POST(
+      new Request("http://localhost/api/analysis/cycles", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(graph),
+      })
+    );
+    const body = await response.json() as {
+      report: {
+        totalCycles: number;
+        cycles: Array<{ nodeIds: string[] }>;
+        affectedNodeIds: string[];
+        analyzedAt: string;
+        hasCycles: boolean;
+      };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.report.totalCycles).toBe(1);
+    expect(body.report.affectedNodeIds).toContain("function:a");
+    expect(body.report.affectedNodeIds).toContain("function:b");
+    expect(body.report.hasCycles).toBe(true);
+    expect(body.report.analyzedAt).toBeTruthy();
+  });
+
+  it("detects a self-loop as a cycle", async () => {
+    const graph: BlueprintGraph = {
+      ...baseGraph,
+      nodes: [minimalNode("function:a")],
+      edges: [{ from: "function:a", to: "function:a", kind: "calls", required: true, confidence: 1 }],
+    };
+
+    const response = await POST(
+      new Request("http://localhost/api/analysis/cycles", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(graph),
+      })
+    );
+    const body = await response.json() as { report: { totalCycles: number; hasCycles: boolean } };
+
+    expect(response.status).toBe(200);
+    expect(body.report.totalCycles).toBe(1);
+    expect(body.report.hasCycles).toBe(true);
+  });
+
+  it("returns 400 for an invalid request body", async () => {
+    const response = await POST(
+      new Request("http://localhost/api/analysis/cycles", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ invalid: true }),
+      })
+    );
+    const body = await response.json() as { error: string };
+
+    expect(response.status).toBe(400);
+    expect(body.error).toBeTruthy();
+  });
+});

package/src/app/api/analysis/metrics/route.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+
+import { POST } from "../../../../handlers/metrics";
+import type { BlueprintGraph } from "@/lib/blueprint/schema";
+import { emptyContract } from "@/lib/blueprint/schema";
+
+const minimalNode = (
+  id: string,
+  kind: BlueprintGraph["nodes"][number]["kind"] = "function"
+): BlueprintGraph["nodes"][number] => ({
+  id,
+  kind,
+  name: id,
+  summary: "A node.",
+  contract: emptyContract(),
+  sourceRefs: [],
+  generatedRefs: [],
+  traceRefs: [],
+});
+
+const baseGraph: BlueprintGraph = {
+  projectName: "Metrics Route Test",
+  mode: "essential",
+  generatedAt: "2026-03-14T00:00:00.000Z",
+  warnings: [],
+  workflows: [],
+  nodes: [],
+  edges: [],
+};
+
+describe("POST /api/analysis/metrics", () => {
+  it("returns zero metrics for an empty graph", async () => {
+    const response = await POST(
+      new Request("http://localhost/api/analysis/metrics", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(baseGraph),
+      })
+    );
+    const body = await response.json() as {
+      metrics: {
+        nodeCount: number;
+        edgeCount: number;
+        density: number;
+        connectedComponents: number;
+        analyzedAt: string;
+      };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.metrics.nodeCount).toBe(0);
+    expect(body.metrics.edgeCount).toBe(0);
+    expect(body.metrics.density).toBe(0);
+    expect(body.metrics.connectedComponents).toBe(0);
+    expect(body.metrics.analyzedAt).toBeTruthy();
+  });
+
+  it("computes correct metrics for a graph with mixed node kinds and edges", async () => {
+    const graph: BlueprintGraph = {
+      ...baseGraph,
+      nodes: [
+        minimalNode("module:a", "module"),
+        minimalNode("api:b", "api"),
+        minimalNode("function:c", "function"),
+        minimalNode("function:d", "function"),
+      ],
+      edges: [
+        { from: "module:a", to: "api:b", kind: "calls", required: true, confidence: 1 },
+        { from: "api:b", to: "function:c", kind: "calls", required: true, confidence: 1 },
+        { from: "api:b", to: "function:d", kind: "calls", required: true, confidence: 1 },
+      ],
+    };
+
+    const response = await POST(
+      new Request("http://localhost/api/analysis/metrics", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(graph),
+      })
+    );
+    const body = await response.json() as {
+      metrics: {
+        nodeCount: number;
+        edgeCount: number;
+        density: number;
+        nodesByKind: Record<string, number>;
+        edgesByKind: Record<string, number>;
+        maxInDegreeNodeId?: string;
+        connectedComponents: number;
+        isolatedNodes: number;
+        leafNodes: number;
+      };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.metrics.nodeCount).toBe(4);
+    expect(body.metrics.edgeCount).toBe(3);
+    expect(body.metrics.density).toBeGreaterThan(0);
+    expect(body.metrics.nodesByKind["module"]).toBe(1);
+    expect(body.metrics.nodesByKind["api"]).toBe(1);
+    expect(body.metrics.nodesByKind["function"]).toBe(2);
+    expect(body.metrics.edgesByKind["calls"]).toBe(3);
+    expect(body.metrics.connectedComponents).toBe(1);
+    expect(body.metrics.isolatedNodes).toBe(0);
+    // module:a has out=1, api:b has out=2 in=1, function:c has in=1, function:d has in=1
+    expect(body.metrics.leafNodes).toBe(3);
+  });
+
+  it("returns 400 for an invalid request body", async () => {
+    const response = await POST(
+      new Request("http://localhost/api/analysis/metrics", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(42),
+      })
+    );
+    const body = await response.json() as { error: string };
+
+    expect(response.status).toBe(400);
+    expect(body.error).toBeTruthy();
+  });
+});

package/src/app/api/analysis/smells/route.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+
+import { POST } from "../../../../handlers/smells";
+import type { BlueprintGraph } from "@/lib/blueprint/schema";
+import { emptyContract } from "@/lib/blueprint/schema";
+
+const baseGraph: BlueprintGraph = {
+  projectName: "Smells Route Test",
+  mode: "essential",
+  generatedAt: "2026-03-14T00:00:00.000Z",
+  warnings: [],
+  workflows: [],
+  nodes: [],
+  edges: [],
+};
+
+const makeMethod = (name: string) => ({
+  name,
+  summary: `Does ${name}.`,
+  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 }[],
+});
+
+describe("POST /api/analysis/smells", () => {
+  it("returns a clean smell report with health score near 100 for an empty graph", async () => {
+    const response = await POST(
+      new Request("http://localhost/api/analysis/smells", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(baseGraph),
+      })
+    );
+    const body = await response.json() as {
+      report: { totalSmells: number; healthScore: number; analyzedAt: string };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.report.totalSmells).toBeGreaterThanOrEqual(0);
+    expect(body.report.analyzedAt).toBeTruthy();
+  });
+
+  it("detects a god-node with too many methods and responsibilities", async () => {
+    const graph: BlueprintGraph = {
+      ...baseGraph,
+      nodes: [
+        {
+          id: "module:god",
+          kind: "module",
+          name: "GodModule",
+          summary: "Does everything.",
+          contract: {
+            ...emptyContract(),
+            methods: Array.from({ length: 8 }, (_, i) => makeMethod(`method${i}`)),
+            responsibilities: ["r1", "r2", "r3", "r4", "r5", "r6"],
+          },
+          sourceRefs: [],
+          generatedRefs: [],
+          traceRefs: [],
+        },
+      ],
+    };
+
+    const response = await POST(
+      new Request("http://localhost/api/analysis/smells", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(graph),
+      })
+    );
+    const body = await response.json() as {
+      report: {
+        totalSmells: number;
+        healthScore: number;
+        smells: Array<{ code: string; severity: string; nodeId?: string }>;
+      };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.report.totalSmells).toBeGreaterThan(0);
+    expect(body.report.healthScore).toBeLessThan(100);
+    const godNodeSmell = body.report.smells.find((s) => s.code === "god-node");
+    expect(godNodeSmell).toBeDefined();
+    expect(godNodeSmell?.severity).toBe("critical");
+    expect(godNodeSmell?.nodeId).toBe("module:god");
+  });
+
+  it("detects orphan nodes with no edges", async () => {
+    const graph: BlueprintGraph = {
+      ...baseGraph,
+      nodes: [
+        {
+          id: "function:orphan",
+          kind: "function",
+          name: "orphanFn",
+          summary: "Nobody calls this.",
+          contract: emptyContract(),
+          sourceRefs: [],
+          generatedRefs: [],
+          traceRefs: [],
+        },
+      ],
+    };
+
+    const response = await POST(
+      new Request("http://localhost/api/analysis/smells", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(graph),
+      })
+    );
+    const body = await response.json() as {
+      report: { smells: Array<{ code: string; nodeId?: string }> };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.report.smells.some((s) => s.code === "orphan-node")).toBe(true);
+  });
+
+  it("returns 400 for an invalid request body", async () => {
+    const response = await POST(
+      new Request("http://localhost/api/analysis/smells", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ not: "a graph" }),
+      })
+    );
+    const body = await response.json() as { error: string };
+
+    expect(response.status).toBe(400);
+    expect(body.error).toBeTruthy();
+  });
+});

package/src/app/api/conflicts/route.test.ts

@@ -0,0 +1,72 @@
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { POST } from "../../../handlers/conflicts";
+import type { BlueprintGraph } from "@/lib/blueprint/schema";
+import { emptyContract } from "@/lib/blueprint/schema";
+
+const fixturePath = path.resolve(process.cwd(), "test-fixtures/sample-repo");
+
+describe("POST /api/conflicts", () => {
+  it("returns drift conflicts against the repo fixture", async () => {
+    const graph: BlueprintGraph = {
+      projectName: "Conflict Route",
+      mode: "essential",
+      generatedAt: "2026-03-14T00:00:00.000Z",
+      warnings: [],
+      workflows: [],
+      edges: [],
+      nodes: [
+        {
+          id: "function:normalize",
+          kind: "function",
+          name: "normalizeTask",
+          path: "src/services/task-service.ts",
+          summary: "Wrong summary.",
+          signature: "normalizeTask(input: string): string",
+          contract: { ...emptyContract(), summary: "Wrong summary." },
+          sourceRefs: [
+            { kind: "repo", path: "src/services/task-service.ts", symbol: "normalizeTask" },
+          ],
+          generatedRefs: [],
+          traceRefs: [],
+        },
+      ],
+    };
+
+    const response = await POST(
+      new Request("http://localhost/api/conflicts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ graph, repoPath: fixturePath }),
+      })
+    );
+    const body = await response.json() as { report: { conflicts: Array<{ kind: string }> } };
+
+    expect(response.status).toBe(200);
+    expect(body.report.conflicts.some((conflict) => conflict.kind === "signature-mismatch")).toBe(true);
+  });
+
+  it("returns 400 when repoPath is missing", async () => {
+    const graph: BlueprintGraph = {
+      projectName: "NoRepoPath",
+      mode: "essential",
+      generatedAt: "2026-03-14T00:00:00.000Z",
+      warnings: [],
+      workflows: [],
+      edges: [],
+      nodes: [],
+    };
+
+    const response = await POST(
+      new Request("http://localhost/api/conflicts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ graph }),
+      })
+    );
+
+    expect(response.status).toBe(400);
+  });
+});

package/src/app/api/refactor/detect/route.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+
+import { POST } from "../../../../handlers/refactor-detect";
+import type { BlueprintGraph } from "@/lib/blueprint/schema";
+import { emptyContract } from "@/lib/blueprint/schema";
+
+const graph: BlueprintGraph = {
+  projectName: "Refactor Detect Route",
+  mode: "essential",
+  generatedAt: "2026-03-26T00:00:00.000Z",
+  warnings: [],
+  workflows: [],
+  nodes: [
+    {
+      id: "function:auth",
+      kind: "function",
+      name: "authenticate",
+      summary: "Authenticate a user.",
+      contract: {
+        ...emptyContract(),
+        calls: [{ target: "GET /users", kind: "calls", description: undefined }],
+      },
+      sourceRefs: [],
+      generatedRefs: [],
+      traceRefs: [],
+    },
+    {
+      id: "api:users",
+      kind: "api",
+      name: "GET /users",
+      summary: "Users API.",
+      contract: emptyContract(),
+      sourceRefs: [],
+      generatedRefs: [],
+      traceRefs: [],
+    },
+  ],
+  edges: [],
+};
+
+describe("POST /api/refactor/detect", () => {
+  it("returns graph-scoped drift metadata", async () => {
+    const response = await POST(
+      new Request("http://localhost/api/refactor/detect", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(graph),
+      })
+    );
+    const body = await response.json() as {
+      report: { totalIssues: number; provenance: string; maturity: string; scope: string };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.report.totalIssues).toBeGreaterThan(0);
+    expect(body.report.provenance).toBe("deterministic");
+    expect(body.report.maturity).toBe("preview");
+    expect(body.report.scope).toBe("graph");
+  });
+
+  it("returns 400 for an invalid request body", async () => {
+    const response = await POST(
+      new Request("http://localhost/api/refactor/detect", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ invalid: true }),
+      })
+    );
+    const body = await response.json() as { error: string };
+
+    expect(response.status).toBe(400);
+    expect(body.error).toBeTruthy();
+  });
+});

package/src/app/api/refactor/heal/route.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+
+import { POST } from "../../../../handlers/refactor-heal";
+import type { BlueprintGraph } from "@/lib/blueprint/schema";
+import { emptyContract } from "@/lib/blueprint/schema";
+
+const graph: BlueprintGraph = {
+  projectName: "Refactor Heal Route",
+  mode: "essential",
+  generatedAt: "2026-03-26T00:00:00.000Z",
+  warnings: [],
+  workflows: [],
+  nodes: [
+    {
+      id: "function:auth",
+      kind: "function",
+      name: "authenticate",
+      summary: "Authenticate a user.",
+      contract: {
+        ...emptyContract(),
+        calls: [{ target: "GET /users", kind: "calls", description: undefined }],
+      },
+      sourceRefs: [],
+      generatedRefs: [],
+      traceRefs: [],
+    },
+    {
+      id: "api:users",
+      kind: "api",
+      name: "GET /users",
+      summary: "Users API.",
+      contract: emptyContract(),
+      sourceRefs: [],
+      generatedRefs: [],
+      traceRefs: [],
+    },
+  ],
+  edges: [],
+};
+
+describe("POST /api/refactor/heal", () => {
+  it("heals graph drift and returns truthfulness metadata", async () => {
+    const response = await POST(
+      new Request("http://localhost/api/refactor/heal", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(graph),
+      })
+    );
+    const body = await response.json() as {
+      result: {
+        issuesFixed: number;
+        provenance: string;
+        maturity: string;
+        scope: string;
+        graph: BlueprintGraph;
+      };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.result.issuesFixed).toBeGreaterThan(0);
+    expect(body.result.provenance).toBe("deterministic");
+    expect(body.result.maturity).toBe("preview");
+    expect(body.result.scope).toBe("graph");
+    expect(
+      body.result.graph.edges.some(
+        (edge: { from: string; to: string }) => edge.from === "function:auth" && edge.to === "api:users"
+      )
+    ).toBe(true);
+  });
+
+  it("returns 400 for an invalid request body", async () => {
+    const response = await POST(
+      new Request("http://localhost/api/refactor/heal", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ invalid: true }),
+      })
+    );
+    const body = await response.json() as { error: string };
+
+    expect(response.status).toBe(400);
+    expect(body.error).toBeTruthy();
+  });
+});