@abhinav2203/codeflow-analysis 0.1.0 → 0.1.1

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,33 @@
+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;
+}, z.core.$strip>;
+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;;;;;;;;;;;;;;;;;;;;iBAoB7B,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();
+    });
+});

package/dist/refactor.d.ts

@@ -0,0 +1,84 @@
+import type { BlueprintEdgeKind, BlueprintGraph, FeatureMaturity, OutputProvenance } from "@abhinav2203/codeflow-core/schema";
+/** 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[];
+}
+/**
+ * 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 declare const detectDrift: (graph: BlueprintGraph) => RefactorReport;
+/**
+ * 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 declare const healGraph: (graph: BlueprintGraph, report: RefactorReport) => HealResult;
+//# sourceMappingURL=refactor.d.ts.map

package/dist/refactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refactor.d.ts","sourceRoot":"","sources":["../src/refactor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,iBAAiB,EACjB,cAAc,EAEd,eAAe,EACf,gBAAgB,EACjB,MAAM,mCAAmC,CAAC;AAI3C,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,cAAc,GAAG,iBAAiB,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,uDAAuD;IACvD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,cAAc,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAsBD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,cAAc,KAAG,cAuFnD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,cAAc,EAAE,QAAQ,cAAc,KAAG,UAqFzE,CAAC"}