@intentius/chant 0.124.12 → 0.124.14

package/dist/builder.js

@@ -0,0 +1,44 @@
+/**
+ * Base class for builder pattern implementations
+ *
+ * Provides a fluent API for constructing Declarable entities.
+ * Subclasses should implement the build() method to return
+ * a fully constructed Declarable entity.
+ *
+ * @example
+ * ```ts
+ * class ResourceBuilder extends Builder<MyResource> {
+ *   private name?: string;
+ *   private type?: string;
+ *
+ *   withName(name: string): this {
+ *     this.name = name;
+ *     return this;
+ *   }
+ *
+ *   withType(type: string): this {
+ *     this.type = type;
+ *     return this;
+ *   }
+ *
+ *   build(): MyResource {
+ *     if (!this.name || !this.type) {
+ *       throw new Error("Name and type are required");
+ *     }
+ *     return {
+ *       entityType: "MyResource",
+ *       [DECLARABLE_MARKER]: true,
+ *       name: this.name,
+ *       type: this.type,
+ *     };
+ *   }
+ * }
+ *
+ * const resource = new ResourceBuilder()
+ *   .withName("myResource")
+ *   .withType("custom")
+ *   .build();
+ * ```
+ */
+export class Builder {
+}

package/dist/cdk/advise.js

@@ -0,0 +1,30 @@
+/**
+ * The CDK half of `chant carve advise` (#1056): read a cloud assembly, rank its
+ * constructs with the same model the Terraform advisor uses.
+ *
+ * Read-only, like the Terraform path — it emits nothing, patches nothing, and
+ * touches no live resource. `carve emit`, `carve bridge` and `carve apply` are
+ * deliberately Terraform-only: bridging a CDK carve means rewriting the
+ * surviving app's source, which does not generalize across jsii languages.
+ */
+import { readCloudAssembly } from "./assembly.js";
+import { buildCdkGraph } from "./graph.js";
+import { resolveCfnTier } from "./tier-map.js";
+import { scoreEstate } from "../terraform/score.js";
+/** The bridge vocabulary a CDK report's boundary edges are named in. */
+export const CDK_DIALECT = "cdk";
+/**
+ * Rank a cloud assembly. The scoring model, the bands and the report shape are
+ * the Terraform path's, verbatim; what changes is the tier lookup (already in
+ * CloudFormation type space, so no translation) and the signals only a CDK
+ * reader can see — assets, nested stacks, L3 subtrees, a dummy-value assembly.
+ */
+export function adviseCloudAssembly(dir) {
+    const assembly = readCloudAssembly(dir);
+    const { graph, signals, diagnostics } = buildCdkGraph(assembly);
+    const scoreOptions = {
+        tierOf: resolveCfnTier,
+        signalsFor: (node) => signals.get(node.address) ?? {},
+    };
+    return { graph, results: scoreEstate(graph, scoreOptions), scoreOptions, diagnostics };
+}

package/dist/cdk/assembly.js

@@ -0,0 +1,122 @@
+/**
+ * Read a CDK cloud assembly off disk (#1056).
+ *
+ * The only filesystem layer the CDK advisor needs. Detection is by content, not
+ * a flag: a directory holding `manifest.json` plus at least one
+ * `*.template.json` is a cloud assembly, so `chant carve advise --from ./cdk.out`
+ * routes itself.
+ *
+ * A malformed or truncated assembly degrades rather than throws — a stack whose
+ * template will not parse is dropped with a diagnostic, and the rest is still
+ * ranked. The advisor is read-only, so a partial read costs nothing but a
+ * shorter report.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+/** Every `*.template.json` directly under `dir`. */
+function listTemplates(dir) {
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".template.json"))
+        .sort();
+}
+/**
+ * Is `dir` a CDK cloud assembly? `manifest.json` plus at least one synthesized
+ * template. Both are required: `manifest.json` alone is far too common a
+ * filename to claim on sight.
+ */
+export function isCloudAssembly(dir) {
+    try {
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            return false;
+        if (!existsSync(join(dir, "manifest.json")))
+            return false;
+        return listTemplates(dir).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Why a Terraform-only carve phase refuses a cloud assembly (#1056).
+ *
+ * Advise is the only phase that reads CDK. Bridging a carve means rewriting the
+ * surviving app's source so it reimports what was taken, and CDK source is
+ * TypeScript, Python, Java or C# depending on who wrote it — nothing that
+ * generalizes the way patching HCL does. Better to say so than to parse the
+ * assembly's `.tf` files, find none, and report an empty estate.
+ */
+export function cdkNotSupported(dir, phase) {
+    return (`${dir} is a CDK cloud assembly, and \`chant carve ${phase}\` reads Terraform. ` +
+        `\`chant carve advise --from ${dir}\` ranks it read-only; emit, bridge and apply are Terraform-only.`);
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The stack's construct path. `displayName` carries it when the stack sits in a
+ * Stage (`Stage/AppStack` for artifact id `Stage-AppStack`); otherwise the
+ * artifact id is the path.
+ */
+function stackPath(id, displayName) {
+    return typeof displayName === "string" && displayName.length > 0 ? displayName : id;
+}
+/** Index `tree.json` by construct path, so a resource's path resolves in one lookup. */
+export function indexTree(root) {
+    const byPath = new Map();
+    const visit = (node) => {
+        if (typeof node.path === "string")
+            byPath.set(node.path, node);
+        for (const child of Object.values(node.children ?? {}))
+            visit(child);
+    };
+    if (root)
+        visit(root);
+    return byPath;
+}
+/**
+ * Read the assembly at `dir`. Throws only when the directory is not an assembly
+ * at all — everything past that point is a diagnostic.
+ */
+export function readCloudAssembly(dir) {
+    const diagnostics = [];
+    const manifest = readJson(join(dir, "manifest.json"));
+    if (!manifest) {
+        throw new Error(`${join(dir, "manifest.json")} is not readable JSON — not a CDK cloud assembly.`);
+    }
+    const tree = readJson(join(dir, "tree.json"))?.tree;
+    if (!tree) {
+        diagnostics.push("No tree.json in the assembly — CloudFormation resources are grouped by their construct path alone, " +
+            "so sibling constructs of one L2 (a function's role and policy, say) rank separately instead of folding in.");
+    }
+    const stacks = [];
+    const artifacts = Object.entries(manifest.artifacts ?? {});
+    for (const [id, artifact] of artifacts) {
+        if (artifact?.type !== "aws:cloudformation:stack")
+            continue;
+        const templateFile = artifact.properties?.templateFile;
+        if (typeof templateFile !== "string") {
+            diagnostics.push(`Stack artifact ${id} names no templateFile — skipped.`);
+            continue;
+        }
+        const template = readJson(join(dir, templateFile));
+        if (!template) {
+            diagnostics.push(`Could not read ${templateFile} for stack ${id} — skipped.`);
+            continue;
+        }
+        stacks.push({ id, path: stackPath(id, artifact.displayName), templateFile, template });
+    }
+    if (stacks.length === 0) {
+        // Templates exist (isCloudAssembly said so) but no artifact claims them —
+        // an assembly written by something other than `cdk synth`, or a manifest
+        // from a version this does not understand. Say so rather than reporting an
+        // empty estate as if the app were empty.
+        diagnostics.push("The manifest declares no aws:cloudformation:stack artifacts, so no template was ranked. " +
+            "Re-synthesize with `cdk synth` and point --from at the resulting cdk.out.");
+    }
+    return { dir, manifest, tree, stacks: stacks.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)), diagnostics };
+}

package/dist/cdk/graph.js

@@ -0,0 +1,444 @@
+/**
+ * Turn a CDK cloud assembly into the same dependency graph the Terraform
+ * advisor scores (#1056).
+ *
+ * Two jobs, both exact rather than heuristic:
+ *
+ * **Grouping.** CloudFormation resources are the wrong unit to rank. One L2
+ * construct emits several of them — a `Function` emits a role, a policy and the
+ * function — and they carve together or not at all. Every resource carries its
+ * emitting construct in `Metadata["aws:cdk:path"]`, and `tree.json` says which
+ * ancestor of that path is the construct a person actually wrote. So resources
+ * fold up to the shallowest L2 (or L3) ancestor and that construct ranks once.
+ * This is the CDK analogue of Terraform sub-resources folding into their parent.
+ *
+ * **Edges.** `Ref`, `Fn::GetAtt` and `Fn::Sub` are intra-stack; `Fn::ImportValue`
+ * resolves through the exporting stack's `Outputs` to the construct that
+ * actually produces the value, so a cross-stack dependency lands as a real edge
+ * between two constructs in both directions rather than a dangling name. There
+ * is no expression AST to consult and no regex over HCL: the template is JSON,
+ * and an intrinsic is a JSON object with a known key.
+ *
+ * Pure — no filesystem, no CDK CLI. `assembly.ts` does the reading.
+ */
+import { indexTree } from "./assembly.js";
+import { NESTED_STACK_TYPE, SCAFFOLDING_TYPES, isScaffoldingParameter, resolveCfnTier } from "./tier-map.js";
+const CONTAINER_FQNS = new Set([
+    "aws-cdk-lib.App",
+    "aws-cdk-lib.Stack",
+    "aws-cdk-lib.Stage",
+    "aws-cdk-lib.TreeMetadata",
+    "@aws-cdk/core.App",
+    "@aws-cdk/core.Stack",
+    "@aws-cdk/core.Stage",
+]);
+const NESTED_STACK_FQNS = new Set(["aws-cdk-lib.NestedStack", "@aws-cdk/core.NestedStack"]);
+/** The leaf ids CDK gives an L2's own L1 child. Not constructs anyone wrote. */
+const IMPLICIT_LEAF_IDS = new Set(["Resource", "Default"]);
+export function constructLevel(fqn) {
+    if (!fqn)
+        return "unknown";
+    if (CONTAINER_FQNS.has(fqn))
+        return "container";
+    if (NESTED_STACK_FQNS.has(fqn))
+        return "nested";
+    const cls = fqn.slice(fqn.lastIndexOf(".") + 1);
+    if (cls.startsWith("Cfn"))
+        return "l1";
+    if (/^(aws-cdk-lib\.aws_|@aws-cdk\/aws-)/.test(fqn))
+        return "l2";
+    return "l3";
+}
+const AWS_PSEUDO = /^AWS::/;
+/**
+ * Every reference in a JSON value, plus whether the value carries a construct
+ * that makes it dynamic (`Fn::If`, a template `Condition`). Walks the JSON
+ * looking for CloudFormation intrinsics — the whole grammar is `{"Fn::X": ...}`
+ * and `{"Ref": "..."}`, so there is nothing to tokenize.
+ */
+function refsIn(value, via, out, flags) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            refsIn(item, via, out, flags);
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    const obj = value;
+    const keys = Object.keys(obj);
+    if (keys.length === 1) {
+        const [key] = keys;
+        const arg = obj[key];
+        if (key === "Ref" && typeof arg === "string") {
+            if (!AWS_PSEUDO.test(arg))
+                out.push({ target: arg, attr: "Ref", via });
+            return;
+        }
+        if (key === "Fn::GetAtt") {
+            // Both encodings: ["LogicalId", "Attr"] and the "LogicalId.Attr" shorthand.
+            const parts = Array.isArray(arg) ? arg : typeof arg === "string" ? arg.split(".") : [];
+            const [id, ...rest] = parts;
+            if (typeof id === "string" && !AWS_PSEUDO.test(id)) {
+                out.push({ target: id, attr: rest.filter((p) => typeof p === "string").join(".") || "Ref", via });
+            }
+            // A GetAtt argument can itself be an intrinsic in the array form.
+            if (Array.isArray(arg))
+                for (const item of arg)
+                    if (typeof item !== "string")
+                        refsIn(item, via, out, flags);
+            return;
+        }
+        if (key === "Fn::ImportValue") {
+            if (typeof arg === "string")
+                out.push({ target: arg, attr: "Export", via, crossStack: true });
+            else
+                refsIn(arg, via, out, flags);
+            return;
+        }
+        if (key === "Fn::Sub") {
+            // `"...${LogicalId.Attr}..."` or `["...", { var: <expr> }]`.
+            const body = Array.isArray(arg) ? arg[0] : arg;
+            const vars = Array.isArray(arg) && arg[1] && typeof arg[1] === "object" ? arg[1] : {};
+            const declared = new Set(Object.keys(vars));
+            if (typeof body === "string") {
+                for (const match of body.matchAll(/\$\{([^}]+)\}/g)) {
+                    const token = match[1].trim();
+                    if (AWS_PSEUDO.test(token) || declared.has(token) || token.startsWith("!"))
+                        continue;
+                    const dot = token.indexOf(".");
+                    const id = dot > 0 ? token.slice(0, dot) : token;
+                    out.push({ target: id, attr: dot > 0 ? token.slice(dot + 1) : "Ref", via });
+                }
+            }
+            for (const inner of Object.values(vars))
+                refsIn(inner, via, out, flags);
+            return;
+        }
+        if (key === "Fn::If") {
+            flags.conditional = true;
+            // The condition name is not a resource; its branches are.
+            if (Array.isArray(arg))
+                for (const branch of arg.slice(1))
+                    refsIn(branch, via, out, flags);
+            return;
+        }
+    }
+    for (const [key, inner] of Object.entries(obj))
+        refsIn(inner, via ?? key, out, flags);
+}
+/** The construct path a resource declares, normalized (CDK writes a leading `/` in places). */
+function declaredPath(resource) {
+    const raw = resource.Metadata?.["aws:cdk:path"];
+    if (typeof raw !== "string" || raw.length === 0)
+        return undefined;
+    return raw.replace(/^\/+/, "");
+}
+/**
+ * The property a CDK asset backs, when the resource is asset-backed at all.
+ * `""` means asset metadata is present but names no property; `undefined` means
+ * the resource carries no asset.
+ */
+function assetProperty(resource) {
+    const metadata = resource.Metadata ?? {};
+    const prop = metadata["aws:asset:property"];
+    if (typeof prop === "string")
+        return prop;
+    return Object.keys(metadata).some((k) => k.startsWith("aws:asset:")) ? "" : undefined;
+}
+/**
+ * Strip an implicit `Resource`/`Default` leaf: the construct a person wrote is
+ * the parent. Used only when tree metadata cannot say better.
+ */
+function ownerOf(path) {
+    const segments = path.split("/");
+    if (segments.length > 1 && IMPLICIT_LEAF_IDS.has(segments[segments.length - 1]))
+        segments.pop();
+    return segments.join("/");
+}
+/**
+ * The construct a resource ranks under: the shallowest ancestor inside the
+ * stack that is an L2, an L3 or a nested stack. With no such ancestor (a bare
+ * L1, or no tree metadata at all) it is the construct that owns the resource.
+ */
+function resolveUnit(resourcePath, stackPath, tree) {
+    const inStack = resourcePath.startsWith(`${stackPath}/`) ? resourcePath.slice(stackPath.length + 1) : undefined;
+    if (inStack) {
+        const segments = inStack.split("/");
+        for (let i = 1; i <= segments.length; i++) {
+            const candidate = `${stackPath}/${segments.slice(0, i).join("/")}`;
+            const level = constructLevel(tree.get(candidate)?.constructInfo?.fqn);
+            if (level === "l2" || level === "l3" || level === "nested")
+                return { path: candidate, level };
+        }
+    }
+    const owner = ownerOf(resourcePath);
+    return { path: owner, level: constructLevel(tree.get(owner)?.constructInfo?.fqn) };
+}
+/** Every resource in a stack that describes infrastructure rather than synthesis. */
+function realResources(stack) {
+    const entries = [];
+    for (const [logicalId, resource] of Object.entries(stack.template.Resources ?? {})) {
+        const type = typeof resource?.Type === "string" ? resource.Type : "";
+        if (!type || SCAFFOLDING_TYPES.has(type))
+            continue;
+        entries.push({
+            logicalId,
+            type,
+            stack: stack.path,
+            path: declaredPath(resource) ?? `${stack.path}/${logicalId}`,
+            resource: resource ?? {},
+        });
+    }
+    return entries;
+}
+/**
+ * The unit's primary CloudFormation type — the one a carve would target. A
+ * construct's own resource sits at `<construct>/Resource` or `<construct>/Default`
+ * (or is the construct, for an L1); anything else is a supporting resource that
+ * carves along with it. With no obvious principal, the shallowest member wins,
+ * tie-broken by type so the answer does not depend on template key order.
+ */
+function primaryMember(unit) {
+    const principal = unit.members.find((m) => m.path === unit.path || IMPLICIT_LEAF_IDS.has(m.path.slice(unit.path.length + 1)));
+    if (principal)
+        return principal;
+    return [...unit.members].sort((a, b) => a.path.split("/").length - b.path.split("/").length || (a.type < b.type ? -1 : a.type > b.type ? 1 : 0))[0];
+}
+/**
+ * Placeholder values `cdk synth` writes when a context lookup could not be
+ * answered. A template holding one describes an account that does not exist.
+ */
+const DUMMY_MARKERS = ["dummy-value-for-", "vpc-12345678", "dummy1a", "ami-1234", "s-12345"];
+/**
+ * Is the assembly a faithful picture of an account, or a guess? Either the
+ * manifest admits an unresolved context query, or a template still carries the
+ * placeholder that query would have replaced.
+ */
+export function dummyAssemblyReason(assembly) {
+    const missing = assembly.manifest.missing ?? [];
+    if (missing.length > 0) {
+        const providers = [...new Set(missing.map((m) => m.provider).filter((p) => !!p))].sort();
+        return (`The assembly was synthesized with ${missing.length} unresolved context lookup(s)` +
+            `${providers.length ? ` (${providers.join(", ")})` : ""}, so its templates hold placeholder values rather ` +
+            "than this account's. Prime the context and re-synthesize before advising.");
+    }
+    for (const stack of assembly.stacks) {
+        const text = JSON.stringify(stack.template);
+        const hit = DUMMY_MARKERS.find((marker) => text.includes(marker));
+        if (hit) {
+            return (`${stack.templateFile} still holds the context placeholder \`${hit}\`, so it describes a lookup that ` +
+                "never resolved. Prime the context and re-synthesize before advising.");
+        }
+    }
+    return undefined;
+}
+/**
+ * Build the graph and the per-construct signals from a read assembly.
+ *
+ * Every resource folds into a construct, every construct becomes one node, and
+ * every intrinsic becomes an edge between two nodes. Nothing is inferred: a
+ * reference with no resolvable target is dropped rather than drawn.
+ */
+export function buildCdkGraph(assembly) {
+    const tree = indexTree(assembly.tree);
+    const diagnostics = [...assembly.diagnostics];
+    // Resources, grouped into units.
+    const units = new Map();
+    /** logical ID → unit address, per stack. */
+    const unitOfLogicalId = new Map();
+    const resourcesOf = new Map();
+    for (const stack of assembly.stacks) {
+        const byLogicalId = new Map();
+        unitOfLogicalId.set(stack.path, byLogicalId);
+        const entries = realResources(stack);
+        resourcesOf.set(stack.path, entries);
+        for (const entry of entries) {
+            const { path, level } = resolveUnit(entry.path, stack.path, tree);
+            const unit = units.get(path) ?? { path, kind: level === "l3" ? "module" : "resource", level, members: [] };
+            unit.members.push(entry);
+            units.set(path, unit);
+            byLogicalId.set(entry.logicalId, path);
+        }
+    }
+    const exports = new Map();
+    for (const stack of assembly.stacks) {
+        for (const output of Object.values(stack.template.Outputs ?? {})) {
+            const name = output?.Export?.Name;
+            if (typeof name !== "string")
+                continue;
+            const refs = [];
+            refsIn(output.Value, "Value", refs, { conditional: false });
+            exports.set(name, { stack: stack.path, refs });
+        }
+    }
+    // Edges.
+    const rawEdges = [];
+    const consumedExports = new Set();
+    const push = (from, to, attrs, via, crossStack) => {
+        if (!from || !to || from === to)
+            return;
+        rawEdges.push({ from, to, attrs, via, ...(crossStack ? { crossStack: true } : {}) });
+    };
+    /** Resolve a raw ref to the unit(s) it names, following exports across stacks. */
+    const targetsOf = (ref, stackPath) => {
+        if (ref.crossStack) {
+            const entry = exports.get(ref.target);
+            if (!entry)
+                return [];
+            consumedExports.add(ref.target);
+            const local = unitOfLogicalId.get(entry.stack);
+            return entry.refs
+                .map((inner) => local?.get(inner.target))
+                .filter((address) => !!address)
+                .map((address) => ({ address, crossStack: true }));
+        }
+        const address = unitOfLogicalId.get(stackPath)?.get(ref.target);
+        return address ? [{ address, crossStack: false }] : [];
+    };
+    const dynamicUnits = new Set();
+    /** unit address → the property the asset backs, `""` when CDK did not name one. */
+    const assetUnits = new Map();
+    for (const stack of assembly.stacks) {
+        const parameters = new Set(Object.keys(stack.template.Parameters ?? {}));
+        for (const entry of resourcesOf.get(stack.path) ?? []) {
+            const from = unitOfLogicalId.get(stack.path)?.get(entry.logicalId);
+            if (!from)
+                continue;
+            const refs = [];
+            const flags = { conditional: !!entry.resource.Condition };
+            refsIn(entry.resource.Properties, undefined, refs, flags);
+            const asset = assetProperty(entry.resource);
+            if (asset !== undefined && !assetUnits.get(from))
+                assetUnits.set(from, asset);
+            for (const ref of refs) {
+                if (!ref.crossStack && parameters.has(ref.target)) {
+                    // A template parameter, not a resource. The synthesizer's own
+                    // bootstrap/asset parameters say nothing about the author's design.
+                    if (isScaffoldingParameter(ref.target)) {
+                        if (ref.target.startsWith("AssetParameters") && !assetUnits.has(from))
+                            assetUnits.set(from, "");
+                    }
+                    else {
+                        flags.conditional = true;
+                    }
+                    continue;
+                }
+                for (const target of targetsOf(ref, stack.path)) {
+                    push(from, target.address, [ref.attr], ref.via ? [ref.via] : [], target.crossStack);
+                }
+            }
+            // `DependsOn` is an ordering dependency, and just as real a cut.
+            const dependsOn = entry.resource.DependsOn;
+            for (const id of Array.isArray(dependsOn) ? dependsOn : dependsOn ? [dependsOn] : []) {
+                if (typeof id !== "string")
+                    continue;
+                const address = unitOfLogicalId.get(stack.path)?.get(id);
+                if (address)
+                    push(from, address, ["DependsOn"], ["DependsOn"]);
+            }
+            if (flags.conditional)
+                dynamicUnits.add(from);
+        }
+    }
+    // `Outputs` blocks reference without being nodes — the CloudFormation twin of
+    // a Terraform `output` (#1638). An output whose export something imports is
+    // skipped: the direct cross-stack edge already stands for that cut, and
+    // counting both would charge one dependency twice.
+    const outputEdges = [];
+    for (const stack of assembly.stacks) {
+        for (const [outputName, output] of Object.entries(stack.template.Outputs ?? {})) {
+            const exportName = output?.Export?.Name;
+            if (typeof exportName === "string" && consumedExports.has(exportName))
+                continue;
+            const refs = [];
+            refsIn(output?.Value, "Value", refs, { conditional: false });
+            for (const ref of refs) {
+                for (const target of targetsOf(ref, stack.path)) {
+                    outputEdges.push({
+                        from: `output.${stack.path}.${outputName}`,
+                        to: target.address,
+                        attrs: [ref.attr],
+                        via: ["Value"],
+                        fromKind: "output",
+                    });
+                }
+            }
+        }
+    }
+    // Nodes.
+    const nodes = [];
+    const signals = new Map();
+    const dummyReason = dummyAssemblyReason(assembly);
+    for (const unit of units.values()) {
+        const primary = primaryMember(unit);
+        const type = unit.kind === "module" ? undefined : primary?.type;
+        const nested = unit.level === "nested" || primary?.type === NESTED_STACK_TYPE;
+        const assetProp = assetUnits.get(unit.path);
+        const stacks = [...new Set(unit.members.map((m) => m.stack))].sort();
+        nodes.push({
+            address: unit.path,
+            kind: unit.kind,
+            ...(type ? { type } : {}),
+            name: unit.path.split("/").pop() ?? unit.path,
+            instances: 1,
+            hasDynamic: dynamicUnits.has(unit.path),
+        });
+        const members = [...unit.members]
+            .sort((a, b) => (a.logicalId < b.logicalId ? -1 : a.logicalId > b.logicalId ? 1 : 0))
+            .map((m) => ({ id: m.logicalId, type: m.type, stack: m.stack, path: m.path }));
+        const notes = [];
+        if (unit.kind === "module") {
+            notes.push("L3 construct subtree — a Composite candidate (#1000). Its leaves rank here as one unit rather than separately.");
+        }
+        if (assetProp !== undefined) {
+            notes.push(`Asset-backed${assetProp ? ` (${assetProp})` : ""} — carving it moves the CDK bundling too, not just the resource.`);
+        }
+        if (unit.members.length > 1) {
+            notes.push(`${unit.members.length} CloudFormation resources fold into this construct.`);
+        }
+        if (stacks.length > 1)
+            notes.push(`Spans ${stacks.length} stacks: ${stacks.join(", ")}.`);
+        if (type && !nested && resolveCfnTier(type) === null) {
+            notes.push(`No chant AWS lexicon target for ${type}.`);
+        }
+        const disqualified = dummyReason
+            ? dummyReason
+            : nested
+                ? "Nested stack — its resources live in a template this advisor does not descend into, so carving it means " +
+                    "carving that whole template. Advise the nested assembly on its own."
+                : undefined;
+        signals.set(unit.path, {
+            ...(assetProp !== undefined && !disqualified ? { penalties: { asset: -10 } } : {}),
+            ...(notes.length ? { notes } : {}),
+            members,
+            ...(disqualified ? { disqualified } : {}),
+        });
+    }
+    if (dummyReason)
+        diagnostics.push(dummyReason);
+    // Merge duplicate edges (same pair), then order by code point so the report
+    // is stable across platforms and template key order.
+    const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    const merged = new Map();
+    for (const edge of [...rawEdges, ...outputEdges]) {
+        const key = `${edge.from}|${edge.to}|${edge.fromKind ?? ""}`;
+        const prev = merged.get(key);
+        if (prev) {
+            prev.attrs = [...new Set([...prev.attrs, ...edge.attrs])].sort(cmp);
+            prev.via = [...new Set([...prev.via, ...edge.via])].sort(cmp);
+            if (edge.crossStack)
+                prev.crossStack = true;
+        }
+        else {
+            merged.set(key, { ...edge, attrs: [...new Set(edge.attrs)].sort(cmp), via: [...new Set(edge.via)].sort(cmp) });
+        }
+    }
+    return {
+        graph: {
+            nodes: nodes.sort((a, b) => cmp(a.address, b.address)),
+            edges: [...merged.values()].sort((a, b) => cmp(a.from, b.from) || cmp(a.to, b.to)),
+        },
+        signals,
+        diagnostics,
+    };
+}