@abhinav2203/codeflow-analysis 0.1.0 → 0.1.2

package/dist/handlers/refactor-heal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refactor-heal.d.ts","sourceRoot":"","sources":["../../src/handlers/refactor-heal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK3C;;;;;;;;;;GAUG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,OAAO;;;;;IAe1C"}

package/dist/handlers/refactor-heal.js

@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+import { detectDrift, healGraph } from "../refactor";
+import { blueprintGraphSchema } from "@abhinav2203/codeflow-core/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) {
+    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 });
+    }
+}

package/dist/handlers/smells.d.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+/**
+ * POST /api/analysis/smells
+ *
+ * Body: {@link BlueprintGraph}
+ *
+ * Returns an architecture smell report including god-node, hub-node,
+ * orphan-node, tight-coupling, unstable-dependency, and scattered-responsibility
+ * detections along with an overall health score.
+ */
+export declare function POST(request: Request): Promise<NextResponse<{
+    report: {
+        analyzedAt: string;
+        totalSmells: number;
+        smells: {
+            message: string;
+            code: string;
+            severity: "warning" | "info" | "critical";
+            suggestion: string;
+            nodeId?: string | undefined;
+        }[];
+        healthScore: number;
+    };
+}> | NextResponse<{
+    error: string;
+}>>;
+//# sourceMappingURL=smells.d.ts.map

package/dist/handlers/smells.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smells.d.ts","sourceRoot":"","sources":["../../src/handlers/smells.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK3C;;;;;;;;GAQG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,OAAO;;;;;;;;;;;;;;;IAc1C"}

package/dist/handlers/smells.js

@@ -0,0 +1,24 @@
+import { NextResponse } from "next/server";
+import { detectSmells } from "../smells";
+import { blueprintGraphSchema } from "@abhinav2203/codeflow-core/schema";
+/**
+ * POST /api/analysis/smells
+ *
+ * Body: {@link BlueprintGraph}
+ *
+ * Returns an architecture smell report including god-node, hub-node,
+ * orphan-node, tight-coupling, unstable-dependency, and scattered-responsibility
+ * detections along with an overall health score.
+ */
+export async function POST(request) {
+    try {
+        const payload = blueprintGraphSchema.parse(await request.json());
+        const report = detectSmells(payload);
+        return NextResponse.json({ report });
+    }
+    catch (error) {
+        return NextResponse.json({
+            error: error instanceof Error ? error.message : "Failed to detect architecture smells.",
+        }, { status: 400 });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { detectCycles, hasCycles } from "./cycles.js";
+export type { Cycle, CycleReport } from "./cycles.js";
+export { detectSmells } from "./smells.js";
+export type { Smell, SmellReport } from "./smells.js";
+export { computeGraphMetrics } from "./metrics.js";
+export type { GraphMetrics } from "./metrics.js";
+export { detectDrift, healGraph } from "./refactor.js";
+export type { DriftIssue, DriftKind, HealResult, RefactorReport } from "./refactor.js";
+export { detectGraphConflicts } from "./conflicts.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGvF,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// cycles
+export { detectCycles, hasCycles } from "./cycles.js";
+// smells
+export { detectSmells } from "./smells.js";
+// metrics
+export { computeGraphMetrics } from "./metrics.js";
+// refactor
+export { detectDrift, healGraph } from "./refactor.js";
+// conflicts
+export { detectGraphConflicts } from "./conflicts.js";

package/dist/invoke.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare const runCLI: () => Promise<void>;
+//# sourceMappingURL=invoke.d.ts.map

package/dist/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../src/invoke.ts"],"names":[],"mappings":";AAcA,eAAO,MAAM,MAAM,qBAiKlB,CAAC"}

package/dist/invoke.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { detectCycles, hasCycles } from "./cycles.js";
+import { detectSmells } from "./smells.js";
+import { computeGraphMetrics } from "./metrics.js";
+import { detectDrift, healGraph } from "./refactor.js";
+import { detectGraphConflicts } from "./conflicts.js";
+import { blueprintGraphSchema } from "@abhinav2203/codeflow-core/schema";
+// ── CLI ─────────────────────────────────────────────────────────────────────
+export const runCLI = async () => {
+    const [command, ...args] = process.argv.slice(2);
+    const readBlueprint = (arg) => {
+        const filePath = resolve(arg);
+        return readFileSync(filePath, "utf-8");
+    };
+    const parseBlueprint = (content) => blueprintGraphSchema.parse(JSON.parse(content));
+    const printJson = (data) => {
+        console.log(JSON.stringify(data, null, 2));
+    };
+    const exit = (code, message) => {
+        if (message)
+            console.error(message);
+        process.exit(code);
+    };
+    const MISSING_ARG = (cmd) => `codeflow-analysis ${cmd}: missing required argument <blueprint-path>`;
+    const UNREADABLE = (path) => `codeflow-analysis: could not read file "${path}"`;
+    const INVALID_BLUEPRINT = (path, error) => `codeflow-analysis: invalid blueprint at "${path}": ${error instanceof Error ? error.message : error}`;
+    try {
+        switch (command) {
+            // ── cycles ────────────────────────────────────────────────────────────────
+            case "cycles": {
+                const [blueprintPath] = args;
+                if (!blueprintPath)
+                    exit(1, MISSING_ARG("cycles"));
+                let graph;
+                try {
+                    graph = parseBlueprint(readBlueprint(blueprintPath));
+                }
+                catch (e) {
+                    if (e.code === "ENOENT")
+                        exit(1, UNREADABLE(blueprintPath));
+                    exit(1, INVALID_BLUEPRINT(blueprintPath, e));
+                }
+                const report = detectCycles(graph);
+                printJson({ report, hasCycles: hasCycles(graph) });
+                break;
+            }
+            // ── smells ───────────────────────────────────────────────────────────────
+            case "smells": {
+                const [blueprintPath] = args;
+                if (!blueprintPath)
+                    exit(1, MISSING_ARG("smells"));
+                let graph;
+                try {
+                    graph = parseBlueprint(readBlueprint(blueprintPath));
+                }
+                catch (e) {
+                    if (e.code === "ENOENT")
+                        exit(1, UNREADABLE(blueprintPath));
+                    exit(1, INVALID_BLUEPRINT(blueprintPath, e));
+                }
+                const report = detectSmells(graph);
+                printJson({ report });
+                break;
+            }
+            // ── metrics ─────────────────────────────────────────────────────────────
+            case "metrics": {
+                const [blueprintPath] = args;
+                if (!blueprintPath)
+                    exit(1, MISSING_ARG("metrics"));
+                let graph;
+                try {
+                    graph = parseBlueprint(readBlueprint(blueprintPath));
+                }
+                catch (e) {
+                    if (e.code === "ENOENT")
+                        exit(1, UNREADABLE(blueprintPath));
+                    exit(1, INVALID_BLUEPRINT(blueprintPath, e));
+                }
+                const metrics = computeGraphMetrics(graph);
+                printJson({ metrics });
+                break;
+            }
+            // ── refactor detect ──────────────────────────────────────────────────────
+            case "refactor": {
+                const sub = args[0];
+                const [blueprintPath] = args.slice(1);
+                if (sub === "detect") {
+                    if (!blueprintPath)
+                        exit(1, MISSING_ARG("refactor detect"));
+                    let graph;
+                    try {
+                        graph = parseBlueprint(readBlueprint(blueprintPath));
+                    }
+                    catch (e) {
+                        if (e.code === "ENOENT")
+                            exit(1, UNREADABLE(blueprintPath));
+                        exit(1, INVALID_BLUEPRINT(blueprintPath, e));
+                    }
+                    const report = detectDrift(graph);
+                    printJson({ report });
+                    break;
+                }
+                if (sub === "heal") {
+                    if (!blueprintPath)
+                        exit(1, MISSING_ARG("refactor heal"));
+                    let graph;
+                    try {
+                        graph = parseBlueprint(readBlueprint(blueprintPath));
+                    }
+                    catch (e) {
+                        if (e.code === "ENOENT")
+                            exit(1, UNREADABLE(blueprintPath));
+                        exit(1, INVALID_BLUEPRINT(blueprintPath, e));
+                    }
+                    const report = detectDrift(graph);
+                    const result = healGraph(graph, report);
+                    printJson({ report, result });
+                    break;
+                }
+                exit(1, `codeflow-analysis refactor: unknown subcommand "${sub}". Use "detect" or "heal".`);
+                break;
+            }
+            // ── conflicts ────────────────────────────────────────────────────────────
+            case "conflicts": {
+                const [blueprintPath, repoPath] = args;
+                if (!blueprintPath)
+                    exit(1, MISSING_ARG("conflicts"));
+                let graph;
+                try {
+                    graph = parseBlueprint(readBlueprint(blueprintPath));
+                }
+                catch (e) {
+                    if (e.code === "ENOENT")
+                        exit(1, UNREADABLE(blueprintPath));
+                    exit(1, INVALID_BLUEPRINT(blueprintPath, e));
+                }
+                const resolvedRepoPath = repoPath ?? process.cwd();
+                const report = await detectGraphConflicts(graph, resolvedRepoPath);
+                printJson({ report });
+                break;
+            }
+            case undefined:
+                exit(1, `codeflow-analysis: missing command. Usage:
+
+  codeflow-analysis cycles <blueprint-path>
+  codeflow-analysis smells <blueprint-path>
+  codeflow-analysis metrics <blueprint-path>
+  codeflow-analysis refactor detect <blueprint-path>
+  codeflow-analysis refactor heal <blueprint-path>
+  codeflow-analysis conflicts <blueprint-path> [repo-path]`);
+            default:
+                exit(1, `codeflow-analysis: unknown command "${command}". Use cycles, smells, metrics, refactor, or conflicts.`);
+        }
+    }
+    catch (error) {
+        exit(1, `codeflow-analysis: unexpected error: ${error instanceof Error ? error.message : error}`);
+    }
+};
+// Run when executed directly
+runCLI();

package/dist/metrics.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import type { BlueprintGraph } from "@abhinav2203/codeflow-core/schema";
+export declare const graphMetricsSchema: z.ZodObject<{
+    analyzedAt: z.ZodString;
+    nodeCount: z.ZodNumber;
+    edgeCount: z.ZodNumber;
+    nodesByKind: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    edgesByKind: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    nodesByStatus: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    density: z.ZodNumber;
+    avgDegree: z.ZodNumber;
+    maxInDegree: z.ZodNumber;
+    maxOutDegree: z.ZodNumber;
+    maxInDegreeNodeId: z.ZodOptional<z.ZodString>;
+    maxOutDegreeNodeId: z.ZodOptional<z.ZodString>;
+    avgMethodsPerNode: z.ZodNumber;
+    avgResponsibilitiesPerNode: z.ZodNumber;
+    totalMethods: z.ZodNumber;
+    totalResponsibilities: z.ZodNumber;
+    connectedComponents: z.ZodNumber;
+    isolatedNodes: z.ZodNumber;
+    leafNodes: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    analyzedAt: string;
+    nodeCount: number;
+    edgeCount: number;
+    nodesByKind: Record<string, number>;
+    edgesByKind: Record<string, number>;
+    nodesByStatus: Record<string, number>;
+    density: number;
+    avgDegree: number;
+    maxInDegree: number;
+    maxOutDegree: number;
+    avgMethodsPerNode: number;
+    avgResponsibilitiesPerNode: number;
+    totalMethods: number;
+    totalResponsibilities: number;
+    connectedComponents: number;
+    isolatedNodes: number;
+    leafNodes: number;
+    maxInDegreeNodeId?: string | undefined;
+    maxOutDegreeNodeId?: string | undefined;
+}, {
+    analyzedAt: string;
+    nodeCount: number;
+    edgeCount: number;
+    nodesByKind: Record<string, number>;
+    edgesByKind: Record<string, number>;
+    nodesByStatus: Record<string, number>;
+    density: number;
+    avgDegree: number;
+    maxInDegree: number;
+    maxOutDegree: number;
+    avgMethodsPerNode: number;
+    avgResponsibilitiesPerNode: number;
+    totalMethods: number;
+    totalResponsibilities: number;
+    connectedComponents: number;
+    isolatedNodes: number;
+    leafNodes: number;
+    maxInDegreeNodeId?: string | undefined;
+    maxOutDegreeNodeId?: string | undefined;
+}>;
+export type GraphMetrics = z.infer<typeof graphMetricsSchema>;
+/**
+ * Compute structural metrics for a blueprint graph.
+ *
+ * Metrics include: node/edge counts, degree statistics, graph density,
+ * connected components, isolated/leaf node counts, and contract-level
+ * averages (methods and responsibilities per node).
+ */
+export declare const computeGraphMetrics: (graph: BlueprintGraph) => GraphMetrics;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAExE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoB7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAgE9D;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,cAAc,KAAG,YAuF3D,CAAC"}

package/dist/metrics.js

@@ -0,0 +1,159 @@
+import { z } from "zod";
+export const graphMetricsSchema = z.object({
+    analyzedAt: z.string(),
+    nodeCount: z.number(),
+    edgeCount: z.number(),
+    nodesByKind: z.record(z.string(), z.number()),
+    edgesByKind: z.record(z.string(), z.number()),
+    nodesByStatus: z.record(z.string(), z.number()),
+    density: z.number(),
+    avgDegree: z.number(),
+    maxInDegree: z.number(),
+    maxOutDegree: z.number(),
+    maxInDegreeNodeId: z.string().optional(),
+    maxOutDegreeNodeId: z.string().optional(),
+    avgMethodsPerNode: z.number(),
+    avgResponsibilitiesPerNode: z.number(),
+    totalMethods: z.number(),
+    totalResponsibilities: z.number(),
+    connectedComponents: z.number(),
+    isolatedNodes: z.number(),
+    leafNodes: z.number(),
+});
+const countBy = (items, key) => {
+    const counts = {};
+    for (const item of items) {
+        const k = key(item);
+        counts[k] = (counts[k] ?? 0) + 1;
+    }
+    return counts;
+};
+/** Union-Find (disjoint set) implementation for connected components. */
+const computeConnectedComponents = (nodeIds, edges) => {
+    const parent = new Map();
+    const rank = new Map();
+    for (const id of nodeIds) {
+        parent.set(id, id);
+        rank.set(id, 0);
+    }
+    const find = (x) => {
+        let root = x;
+        while (parent.get(root) !== root) {
+            root = parent.get(root);
+        }
+        let current = x;
+        while (current !== root) {
+            const next = parent.get(current);
+            parent.set(current, root);
+            current = next;
+        }
+        return root;
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra === rb)
+            return;
+        const rankA = rank.get(ra);
+        const rankB = rank.get(rb);
+        if (rankA < rankB) {
+            parent.set(ra, rb);
+        }
+        else if (rankA > rankB) {
+            parent.set(rb, ra);
+        }
+        else {
+            parent.set(rb, ra);
+            rank.set(ra, rankA + 1);
+        }
+    };
+    for (const edge of edges) {
+        if (parent.has(edge.from) && parent.has(edge.to)) {
+            union(edge.from, edge.to);
+        }
+    }
+    const roots = new Set(nodeIds.map(find));
+    return roots.size;
+};
+/**
+ * Compute structural metrics for a blueprint graph.
+ *
+ * Metrics include: node/edge counts, degree statistics, graph density,
+ * connected components, isolated/leaf node counts, and contract-level
+ * averages (methods and responsibilities per node).
+ */
+export const computeGraphMetrics = (graph) => {
+    const { nodes, edges } = graph;
+    const nodeCount = nodes.length;
+    const edgeCount = edges.length;
+    const nodesByKind = countBy(nodes, (n) => n.kind);
+    const edgesByKind = countBy(edges, (e) => e.kind);
+    const nodesByStatus = countBy(nodes, (n) => n.status ?? "spec_only");
+    // Use unique (from,to) directed pairs for density to avoid inflated values
+    // from parallel edges between the same node pair.
+    const uniquePairCount = new Set(edges.map((e) => `${e.from}::__::${e.to}`)).size;
+    const density = nodeCount < 2 ? 0 : uniquePairCount / (nodeCount * (nodeCount - 1));
+    const inDegree = new Map();
+    const outDegree = new Map();
+    for (const node of nodes) {
+        inDegree.set(node.id, 0);
+        outDegree.set(node.id, 0);
+    }
+    for (const edge of edges) {
+        inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+        outDegree.set(edge.from, (outDegree.get(edge.from) ?? 0) + 1);
+    }
+    let maxInDegree = 0;
+    let maxOutDegree = 0;
+    let maxInDegreeNodeId;
+    let maxOutDegreeNodeId;
+    for (const node of nodes) {
+        const inD = inDegree.get(node.id);
+        const outD = outDegree.get(node.id);
+        if (inD > maxInDegree) {
+            maxInDegree = inD;
+            maxInDegreeNodeId = node.id;
+        }
+        if (outD > maxOutDegree) {
+            maxOutDegree = outD;
+            maxOutDegreeNodeId = node.id;
+        }
+    }
+    const avgDegree = nodeCount === 0 ? 0 : (2 * edgeCount) / nodeCount;
+    const totalMethods = nodes.reduce((sum, n) => sum + n.contract.methods.length, 0);
+    const totalResponsibilities = nodes.reduce((sum, n) => sum + n.contract.responsibilities.length, 0);
+    const avgMethodsPerNode = nodeCount === 0 ? 0 : totalMethods / nodeCount;
+    const avgResponsibilitiesPerNode = nodeCount === 0 ? 0 : totalResponsibilities / nodeCount;
+    const nodeIds = nodes.map((n) => n.id);
+    const connectedComponents = nodeCount === 0 ? 0 : computeConnectedComponents(nodeIds, edges);
+    let isolatedNodes = 0;
+    let leafNodes = 0;
+    for (const node of nodes) {
+        const totalDegree = inDegree.get(node.id) + outDegree.get(node.id);
+        if (totalDegree === 0)
+            isolatedNodes++;
+        else if (totalDegree === 1)
+            leafNodes++;
+    }
+    return {
+        analyzedAt: new Date().toISOString(),
+        nodeCount,
+        edgeCount,
+        nodesByKind,
+        edgesByKind,
+        nodesByStatus,
+        density,
+        avgDegree,
+        maxInDegree,
+        maxOutDegree,
+        maxInDegreeNodeId,
+        maxOutDegreeNodeId,
+        avgMethodsPerNode,
+        avgResponsibilitiesPerNode,
+        totalMethods,
+        totalResponsibilities,
+        connectedComponents,
+        isolatedNodes,
+        leafNodes,
+    };
+};

package/dist/metrics.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metrics.test.d.ts.map

package/dist/metrics.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.test.d.ts","sourceRoot":"","sources":["../src/metrics.test.ts"],"names":[],"mappings":""}

package/dist/metrics.test.js

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { computeGraphMetrics } from "./metrics";
+import { emptyContract } from "@abhinav2203/codeflow-core/schema";
+const node = (id, kind = "function") => ({
+    id,
+    kind,
+    name: id,
+    summary: "A node.",
+    contract: emptyContract(),
+    sourceRefs: [],
+    generatedRefs: [],
+    traceRefs: [],
+});
+const edge = (from, to, kind = "calls") => ({
+    from,
+    to,
+    kind,
+    required: true,
+    confidence: 1,
+});
+const graph = (projectName, nodes, edges) => ({
+    projectName,
+    mode: "essential",
+    generatedAt: "2026-03-14T00:00:00.000Z",
+    warnings: [],
+    workflows: [],
+    nodes,
+    edges,
+});
+describe("computeGraphMetrics", () => {
+    it("computes correct basic metrics for a simple graph", () => {
+        const metrics = computeGraphMetrics(graph("Simple", [node("A", "module"), node("B", "api"), node("C", "function")], [edge("A", "B"), edge("B", "C")]));
+        expect(metrics.nodeCount).toBe(3);
+        expect(metrics.edgeCount).toBe(2);
+        expect(metrics.nodesByKind["module"]).toBe(1);
+        expect(metrics.nodesByKind["api"]).toBe(1);
+        expect(metrics.nodesByKind["function"]).toBe(1);
+        expect(metrics.connectedComponents).toBe(1);
+    });
+    it("returns all zeros for an empty graph", () => {
+        const metrics = computeGraphMetrics(graph("Empty", [], []));
+        expect(metrics.nodeCount).toBe(0);
+        expect(metrics.edgeCount).toBe(0);
+        expect(metrics.density).toBe(0);
+        expect(metrics.connectedComponents).toBe(0);
+        expect(metrics.avgDegree).toBe(0);
+        expect(metrics.isolatedNodes).toBe(0);
+        expect(metrics.leafNodes).toBe(0);
+    });
+    it("counts isolated and leaf nodes correctly", () => {
+        // A → B (A: out=1, B: in=1) — C is isolated
+        const metrics = computeGraphMetrics(graph("IsolatedLeaf", [node("A", "module"), node("B", "module"), node("C", "module")], [edge("A", "B")]));
+        expect(metrics.isolatedNodes).toBe(1); // C has degree 0
+        expect(metrics.leafNodes).toBe(2); // A has out=1, B has in=1
+    });
+    it("density stays <= 1 when parallel edges exist between the same pair", () => {
+        const metrics = computeGraphMetrics(graph("ParallelEdges", [node("A", "module"), node("B", "module")], [edge("A", "B"), { from: "A", to: "B", kind: "imports", required: false, confidence: 0.9 }]));
+        expect(metrics.density).toBeLessThanOrEqual(1);
+        // One unique directed pair (A→B) out of 2 possible (A→B, B→A) = 0.5
+        expect(metrics.density).toBeCloseTo(0.5);
+    });
+    it("identifies max in-degree and max out-degree nodes", () => {
+        // A → B, A → C, D → B  → in(B)=2, out(A)=2
+        const metrics = computeGraphMetrics(graph("DegreeStats", [node("A", "module"), node("B", "module"), node("C", "module"), node("D", "module")], [edge("A", "B"), edge("A", "C"), edge("D", "B")]));
+        expect(metrics.maxInDegree).toBe(2);
+        expect(metrics.maxOutDegree).toBe(2);
+        expect(metrics.maxInDegreeNodeId).toBe("B");
+        expect(metrics.maxOutDegreeNodeId).toBe("A");
+    });
+    it("counts edges by kind correctly", () => {
+        const metrics = computeGraphMetrics(graph("EdgesByKind", [node("A", "module"), node("B", "module")], [edge("A", "B"), { from: "A", to: "B", kind: "imports", required: true, confidence: 1 }]));
+        expect(metrics.edgesByKind["calls"]).toBe(1);
+        expect(metrics.edgesByKind["imports"]).toBe(1);
+    });
+    it("avgMethodsPerNode is computed correctly", () => {
+        const metrics = computeGraphMetrics(graph("Methods", [
+            {
+                ...node("A", "class"),
+                contract: { ...emptyContract(), methods: [{}, {}] },
+            },
+            {
+                ...node("B", "class"),
+                contract: { ...emptyContract(), methods: [{}] },
+            },
+        ], []));
+        expect(metrics.totalMethods).toBe(3);
+        expect(metrics.avgMethodsPerNode).toBeCloseTo(1.5);
+    });
+    it("connectedComponents uses Union-Find correctly for a disconnected graph", () => {
+        // Two disconnected components: {A, B} and {C, D}
+        const metrics = computeGraphMetrics(graph("Disconnected", [node("A"), node("B"), node("C"), node("D")], [edge("A", "B"), edge("C", "D")]));
+        expect(metrics.connectedComponents).toBe(2);
+    });
+    it("computed at timestamp is a valid ISO string", () => {
+        const metrics = computeGraphMetrics(graph("Timestamp", [node("A")], []));
+        expect(() => new Date(metrics.analyzedAt)).not.toThrow();
+    });
+});