@abhinav2203/codeflow-analysis 0.1.0 → 0.1.2

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"}

package/dist/refactor.js

@@ -0,0 +1,183 @@
+// ── Internal helpers ──────────────────────────────────────────────────────────
+const buildNodeIndex = (graph) => new Map(graph.nodes.map((n) => [n.id, n]));
+/**
+ * Resolve a contract call `target` (which may be a node ID or node name) to
+ * the matching blueprint node.
+ */
+const resolveCallTarget = (graph, target) => {
+    const byId = graph.nodes.find((n) => n.id === target);
+    if (byId)
+        return byId;
+    return graph.nodes.find((n) => n.name === target);
+};
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Detect architectural drift in a blueprint graph.
+ *
+ * Three kinds of drift are checked:
+ * 1. **Broken edges** – an edge's `from` or `to` points to a node ID that no
+ *    longer exists in the graph.
+ * 2. **Missing edges** – a node's contract `calls` entry references a target
+ *    that exists in the graph but has no corresponding edge.
+ * 3. **Signature drift** – the node's top-level `signature` field doesn't
+ *    match the `signature` of its first contract method.
+ */
+export const detectDrift = (graph) => {
+    const issues = [];
+    const index = buildNodeIndex(graph);
+    // ── 1. Broken edges ────────────────────────────────────────────────────────
+    for (const edge of graph.edges) {
+        if (!index.has(edge.from)) {
+            const existingNode = index.get(edge.to);
+            issues.push({
+                kind: "broken-edge",
+                nodeId: existingNode?.id ?? edge.to,
+                nodeName: existingNode?.name ?? edge.to,
+                description: `Edge "${edge.from}" → "${edge.to}" references a non-existent source node.`,
+                edgeFrom: edge.from,
+                edgeTo: edge.to,
+                missingNodeId: edge.from,
+            });
+        }
+        if (!index.has(edge.to)) {
+            const existingNode = index.get(edge.from);
+            issues.push({
+                kind: "broken-edge",
+                nodeId: existingNode?.id ?? edge.from,
+                nodeName: existingNode?.name ?? edge.from,
+                description: `Edge "${edge.from}" → "${edge.to}" references a non-existent target node.`,
+                edgeFrom: edge.from,
+                edgeTo: edge.to,
+                missingNodeId: edge.to,
+            });
+        }
+    }
+    // ── 2. Missing edges + signature drift ────────────────────────────────────
+    for (const node of graph.nodes) {
+        // Signature drift: top-level signature doesn't match the first method's.
+        const firstMethod = node.contract.methods?.[0];
+        if (node.signature &&
+            firstMethod?.signature &&
+            node.signature !== firstMethod.signature) {
+            issues.push({
+                kind: "signature-drift",
+                nodeId: node.id,
+                nodeName: node.name,
+                description: `Node "${node.name}" signature "${node.signature}" does not match contract method "${firstMethod.signature}".`,
+            });
+        }
+        // Missing edges: contract calls with no corresponding graph edge.
+        for (const call of node.contract.calls ?? []) {
+            const targetNode = resolveCallTarget(graph, call.target);
+            if (!targetNode)
+                continue; // target not in graph – not our responsibility here
+            const edgeKind = call.kind ?? "calls";
+            const edgeExists = graph.edges.some((e) => e.from === node.id && e.to === targetNode.id && e.kind === edgeKind);
+            if (!edgeExists) {
+                issues.push({
+                    kind: "missing-edge",
+                    nodeId: node.id,
+                    nodeName: node.name,
+                    description: `Node "${node.name}" declares a "${edgeKind}" call to "${call.target}" in its contract but no graph edge exists.`,
+                    edgeFrom: node.id,
+                    edgeTo: targetNode.id,
+                    edgeKind,
+                });
+            }
+        }
+    }
+    const driftedNodeIds = [...new Set(issues.map((i) => i.nodeId))];
+    return {
+        projectName: graph.projectName,
+        detectedAt: new Date().toISOString(),
+        provenance: "deterministic",
+        maturity: "preview",
+        scope: "graph",
+        issues,
+        driftedNodeIds,
+        totalIssues: issues.length,
+        isHealthy: issues.length === 0,
+    };
+};
+/**
+ * Auto-heal a blueprint graph based on a previously computed {@link RefactorReport}.
+ *
+ * Healing actions:
+ * - **Broken edges** are removed.
+ * - **Missing edges** are synthesised from the contract call definitions.
+ * - **Signature drift** is resolved by syncing the node's top-level
+ *   `signature` to match its first contract method.
+ *
+ * The original graph is not mutated; a new graph object is returned.
+ */
+export const healGraph = (graph, report) => {
+    const index = buildNodeIndex(graph);
+    const summary = [];
+    let issuesFixed = 0;
+    // ── Remove broken edges ─────────────────────────────────────────────────────
+    const healedEdges = graph.edges.filter((edge) => {
+        if (!index.has(edge.from) || !index.has(edge.to)) {
+            summary.push(`Removed broken edge: ${edge.from} → ${edge.to}`);
+            issuesFixed++;
+            return false;
+        }
+        return true;
+    });
+    // ── Synthesise missing edges ────────────────────────────────────────────────
+    const newEdges = [];
+    const missingEdgeIssues = report.issues.filter((i) => i.kind === "missing-edge");
+    for (const issue of missingEdgeIssues) {
+        if (!issue.edgeFrom || !issue.edgeTo)
+            continue;
+        const issueEdgeKind = issue.edgeKind ?? "calls";
+        const alreadyAdded = newEdges.some((e) => e.from === issue.edgeFrom && e.to === issue.edgeTo && e.kind === issueEdgeKind);
+        if (alreadyAdded)
+            continue;
+        // Find the original contract call to preserve kind/label. Match on both
+        // target node ID and kind so that multiple calls between the same pair with
+        // different kinds each resolve to their own contract entry.
+        const fromNode = index.get(issue.edgeFrom);
+        const call = fromNode?.contract.calls?.find((c) => {
+            const target = resolveCallTarget(graph, c.target);
+            return target?.id === issue.edgeTo && (c.kind ?? "calls") === issueEdgeKind;
+        });
+        newEdges.push({
+            from: issue.edgeFrom,
+            to: issue.edgeTo,
+            kind: issueEdgeKind,
+            required: false,
+            confidence: 0.8,
+            label: call?.description,
+        });
+        const fromName = fromNode?.name ?? issue.edgeFrom;
+        const toName = index.get(issue.edgeTo)?.name ?? issue.edgeTo;
+        summary.push(`Added missing edge: ${fromName} → ${toName}`);
+        issuesFixed++;
+    }
+    // ── Fix signature drift ────────────────────────────────────────────────────
+    const healedNodes = graph.nodes.map((node) => {
+        const hasDrift = report.issues.some((i) => i.kind === "signature-drift" && i.nodeId === node.id);
+        if (!hasDrift)
+            return node;
+        const firstMethod = node.contract.methods?.[0];
+        if (!firstMethod?.signature)
+            return node;
+        summary.push(`Synced signature for "${node.name}": "${node.signature}" → "${firstMethod.signature}"`);
+        issuesFixed++;
+        return { ...node, signature: firstMethod.signature };
+    });
+    return {
+        projectName: graph.projectName,
+        healedAt: new Date().toISOString(),
+        provenance: "deterministic",
+        maturity: "preview",
+        scope: "graph",
+        issuesFixed,
+        graph: {
+            ...graph,
+            nodes: healedNodes,
+            edges: [...healedEdges, ...newEdges],
+        },
+        summary,
+    };
+};

package/dist/refactor.test.d.ts

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

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

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

package/dist/refactor.test.js

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

package/dist/smells.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import type { BlueprintGraph } from "@abhinav2203/codeflow-core/schema";
+export declare const smellSchema: z.ZodObject<{
+    code: z.ZodString;
+    severity: z.ZodEnum<["info", "warning", "critical"]>;
+    nodeId: z.ZodOptional<z.ZodString>;
+    message: z.ZodString;
+    suggestion: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    code: string;
+    severity: "warning" | "info" | "critical";
+    suggestion: string;
+    nodeId?: string | undefined;
+}, {
+    message: string;
+    code: string;
+    severity: "warning" | "info" | "critical";
+    suggestion: string;
+    nodeId?: string | undefined;
+}>;
+export type Smell = z.infer<typeof smellSchema>;
+export declare const smellReportSchema: z.ZodObject<{
+    analyzedAt: z.ZodString;
+    totalSmells: z.ZodNumber;
+    smells: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<["info", "warning", "critical"]>;
+        nodeId: z.ZodOptional<z.ZodString>;
+        message: z.ZodString;
+        suggestion: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        code: string;
+        severity: "warning" | "info" | "critical";
+        suggestion: string;
+        nodeId?: string | undefined;
+    }, {
+        message: string;
+        code: string;
+        severity: "warning" | "info" | "critical";
+        suggestion: string;
+        nodeId?: string | undefined;
+    }>, "many">;
+    healthScore: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    analyzedAt: string;
+    totalSmells: number;
+    smells: {
+        message: string;
+        code: string;
+        severity: "warning" | "info" | "critical";
+        suggestion: string;
+        nodeId?: string | undefined;
+    }[];
+    healthScore: number;
+}, {
+    analyzedAt: string;
+    totalSmells: number;
+    smells: {
+        message: string;
+        code: string;
+        severity: "warning" | "info" | "critical";
+        suggestion: string;
+        nodeId?: string | undefined;
+    }[];
+    healthScore: number;
+}>;
+export type SmellReport = z.infer<typeof smellReportSchema>;
+/**
+ * Detect all architecture smells in a blueprint graph.
+ *
+ * Smell categories: god-node, hub-node, orphan-node, tight-coupling,
+ * unstable-dependency, scattered-responsibility.
+ */
+export declare const detectSmells: (graph: BlueprintGraph) => SmellReport;
+//# sourceMappingURL=smells.d.ts.map

package/dist/smells.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smells.d.ts","sourceRoot":"","sources":["../src/smells.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAExE,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;EAMtB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAmL5D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,cAAc,KAAG,WAgBpD,CAAC"}