@intentius/chant 0.52.2 → 0.53.0

package/src/cdk/advise.test.ts

@@ -0,0 +1,208 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, readFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { carveAdvise, carveJson, formatCarveReport, CARVE_REPORT_VERSION } from "../cli/commands/carve";
+import { carveEmit } from "../cli/commands/carve-emit";
+import { carveBridge } from "../cli/commands/carve-bridge";
+import { carveApply } from "../cli/commands/carve-apply";
+
+const FIXTURES = join(__dirname, "__fixtures__");
+const ASSEMBLY = join(FIXTURES, "cdk.out");
+const DUMMY = join(FIXTURES, "cdk.out-dummy");
+
+/**
+ * `chant carve advise` over a committed CDK cloud assembly (#1056). No CDK CLI,
+ * no network, no wasm parser — the assembly is JSON and it is in the repo.
+ */
+describe("carve advise --from <cdk.out>", () => {
+  test("routes on the directory's contents, not a second flag", async () => {
+    const r = await carveAdvise({ from: ASSEMBLY });
+    expect(r.ok).toBe(true);
+    expect(r.source).toBe("cdk");
+  });
+
+  test("ranks constructs into the same bands the Terraform path uses", async () => {
+    const r = await carveAdvise({ from: ASSEMBLY });
+    const byAddress = new Map((r.results ?? []).map((x) => [x.address, x]));
+
+    // 100 - 12 inbound (the cross-stack import) on a tier-1 bucket.
+    expect(byAddress.get("DataStack/Assets")).toMatchObject({ score: 88, band: "clean leaf", mapsTo: "AWS::S3::Bucket" });
+    // 100 - 4x2 outbound - 15 tier2 - 10 asset.
+    expect(byAddress.get("AppStack/Handler")).toMatchObject({ score: 67, band: "carvable w/ edits" });
+    // A module (an L3 subtree) takes the same tier-2 penalty a Terraform module does.
+    expect(byAddress.get("AppStack/Api")).toMatchObject({ score: 69, kind: "module" });
+    expect(byAddress.get("AppStack/Api")?.mapsTo).toBeUndefined();
+  });
+
+  test("a construct ranks once, with its CloudFormation resources folded in", async () => {
+    const r = await carveAdvise({ from: ASSEMBLY });
+    const addresses = (r.results ?? []).map((x) => x.address);
+    expect(addresses).toContain("AppStack/Handler");
+    expect(addresses.filter((a) => a.startsWith("AppStack/Handler"))).toHaveLength(1);
+
+    const handler = r.results?.find((x) => x.address === "AppStack/Handler");
+    expect(handler?.members?.map((m) => m.id).sort()).toEqual([
+      "Handler886CB40B",
+      "HandlerServiceRoleDefaultPolicy4C43A1F9",
+      "HandlerServiceRoleFCDC14AE",
+    ]);
+  });
+
+  test("scaffolding does not appear in the report", async () => {
+    const r = await carveAdvise({ from: ASSEMBLY });
+    const text = JSON.stringify(carveJson(r));
+    expect(text).not.toContain("CDKMetadata");
+    expect(text).not.toContain("AWS::CDK::Metadata");
+    expect(text).not.toContain("BootstrapVersion");
+  });
+
+  test("a cross-stack Fn::ImportValue is a boundary edge from both ends", async () => {
+    const payload = carveJson(await carveAdvise({ from: ASSEMBLY }));
+    const producer = payload.resources.find((x) => x.address === "DataStack/Assets");
+    const consumer = payload.resources.find((x) => x.address === "AppStack/Handler");
+
+    expect(producer?.boundary?.inbound).toContainEqual({
+      direction: "inbound",
+      survivor: "AppStack/Handler",
+      carved: "DataStack/Assets",
+      attrs: ["Export"],
+      via: ["PolicyDocument"],
+      bridge: "cdk-import",
+      required: "immediately",
+      crossStack: true,
+    });
+    expect(consumer?.boundary?.outbound).toContainEqual({
+      direction: "outbound",
+      survivor: "DataStack/Assets",
+      carved: "AppStack/Handler",
+      attrs: ["Export"],
+      via: ["PolicyDocument"],
+      bridge: "deferred-input",
+      required: "at-apply",
+      crossStack: true,
+    });
+  });
+
+  test("a stack Output reading a construct bridges as an output rewrite", async () => {
+    const payload = carveJson(await carveAdvise({ from: ASSEMBLY }));
+    const table = payload.resources.find((x) => x.address === "DataStack/Table");
+    expect(table?.boundary?.inbound).toContainEqual({
+      direction: "inbound",
+      survivor: "output.DataStack.TableName",
+      carved: "DataStack/Table",
+      attrs: ["Ref"],
+      via: ["Value"],
+      bridge: "cfn-output-rewrite",
+      required: "immediately",
+    });
+    expect(table?.breakdown).toMatchObject({ inbound: 0, outputs: 1 });
+  });
+
+  test("a dummy-value assembly scores 0 with the reason, not a plausible score", async () => {
+    const r = await carveAdvise({ from: DUMMY });
+    expect(r.ok).toBe(true);
+    expect(r.results?.length).toBeGreaterThan(0);
+    for (const scored of r.results ?? []) {
+      expect(scored.score).toBe(0);
+      expect(scored.notes?.join(" ")).toContain("unresolved context lookup");
+    }
+    const payload = carveJson(r);
+    expect(payload.diagnostics?.join(" ")).toContain("unresolved context lookup");
+    expect(formatCarveReport(r)).toContain("unresolved context lookup");
+  });
+
+  test("the report advises and never suggests a mutation", async () => {
+    const r = await carveAdvise({ from: ASSEMBLY });
+    const text = formatCarveReport(r);
+    expect(text).toContain("CDK cloud-assembly carve-out advisory");
+    expect(text).toContain("Advises only");
+    expect(text).toContain("LEAVE IN CDK");
+    expect(text).not.toMatch(/cdk deploy|cdk destroy|terraform state rm/i);
+  });
+
+  test("--report writes the same payload to a file", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-cdk-carve-"));
+    try {
+      const reportFile = join(dir, "report.json");
+      const r = await carveAdvise({ from: ASSEMBLY, reportFile });
+      expect(r.ok).toBe(true);
+      const payload = JSON.parse(readFileSync(reportFile, "utf-8"));
+      expect(payload).toEqual(carveJson(r));
+      expect(payload.count).toBe(r.results?.length);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("--state is a Terraform option and is refused, not ignored", async () => {
+    const r = await carveAdvise({ from: ASSEMBLY, statePath: join(ASSEMBLY, "manifest.json") });
+    expect(r.ok).toBe(false);
+    expect(r.error).toContain("--state is a Terraform option");
+  });
+});
+
+/**
+ * The report is a cross-tool contract (behold's carve lens reads it). The CDK
+ * source is additive within schema version 1: it introduces no field an
+ * existing reader keys on, and changes no field's type or meaning.
+ */
+describe("the versioned report contract", () => {
+  test("the CDK source does not bump the schema version", async () => {
+    const payload = carveJson(await carveAdvise({ from: ASSEMBLY }));
+    expect(payload.version).toBe(CARVE_REPORT_VERSION);
+    expect(CARVE_REPORT_VERSION).toBe(1);
+  });
+
+  test("every field an existing reader validates keeps its type", async () => {
+    const payload = carveJson(await carveAdvise({ from: ASSEMBLY }));
+    // behold refuses a report whose entries are not {address: string, score:
+    // number, band: string}, and reads `kind` as "resource" | "module".
+    expect(Array.isArray(payload.resources)).toBe(true);
+    for (const resource of payload.resources) {
+      expect(typeof resource.address).toBe("string");
+      expect(typeof resource.score).toBe("number");
+      expect(typeof resource.band).toBe("string");
+      expect(["resource", "module"]).toContain(resource.kind);
+      expect(["clean leaf", "carvable w/ edits", "leave in Terraform"]).toContain(resource.band);
+    }
+  });
+
+  test("the score arithmetic still adds up from the penalty terms", async () => {
+    // behold reproduces a score as `100 + sum(penalties)`, so an added term
+    // (the CDK asset penalty) has to be summable rather than special-cased.
+    const payload = carveJson(await carveAdvise({ from: ASSEMBLY }));
+    for (const resource of payload.resources) {
+      if (resource.breakdown.tier === null || resource.score === 0) continue;
+      const total = Object.values(resource.breakdown.penalties).reduce((sum, n) => sum + n, 0);
+      expect(100 + total).toBe(resource.score);
+    }
+  });
+
+  test("the source discriminator is present on both paths", async () => {
+    expect(carveJson(await carveAdvise({ from: ASSEMBLY })).source).toBe("cdk");
+    // A result with no source at all (an older caller) still reads as Terraform.
+    expect(carveJson({ ok: true, from: "x", results: [] }).source).toBe("terraform");
+  });
+});
+
+describe("the Terraform-only phases", () => {
+  test("refuse a cloud assembly by name instead of reporting an empty estate", async () => {
+    const emit = await carveEmit(
+      { from: ASSEMBLY, select: "AppStack/Handler", statePath: "unused.tfstate" },
+      // Refused before anything is read, so neither dependency is reached.
+      { plugins: [], liveImport: async () => { throw new Error("no cloud call in an advise-only path"); } },
+    );
+    expect(emit.ok).toBe(false);
+    expect(emit.error).toContain("carve emit");
+    expect(emit.error).toContain("carve advise");
+
+    const bridge = await carveBridge({ from: ASSEMBLY, select: "AppStack/Handler" });
+    expect(bridge.ok).toBe(false);
+    expect(bridge.error).toContain("carve bridge");
+
+    const apply = await carveApply({ from: ASSEMBLY, select: "AppStack/Handler", env: "prod" });
+    expect(apply.ok).toBe(false);
+    expect(apply.error).toContain("carve apply");
+  });
+});

package/src/cdk/advise.ts

@@ -0,0 +1,44 @@
+/**
+ * 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";
+import { buildCdkGraph } from "./graph";
+import { resolveCfnTier } from "./tier-map";
+import type { CarveDialect } from "../terraform/carve";
+import type { Peelability, ScoreOptions } from "../terraform/score";
+import { scoreEstate } from "../terraform/score";
+import type { TfGraph } from "../terraform/types";
+
+export interface CdkAdvice {
+  graph: TfGraph;
+  results: Peelability[];
+  /** The hooks that produced `results`, so the boundary pass agrees with it. */
+  scoreOptions: ScoreOptions;
+  diagnostics: string[];
+}
+
+/** The bridge vocabulary a CDK report's boundary edges are named in. */
+export const CDK_DIALECT: CarveDialect = "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: string): CdkAdvice {
+  const assembly = readCloudAssembly(dir);
+  const { graph, signals, diagnostics } = buildCdkGraph(assembly);
+  const scoreOptions: ScoreOptions = {
+    tierOf: resolveCfnTier,
+    signalsFor: (node) => signals.get(node.address) ?? {},
+  };
+  return { graph, results: scoreEstate(graph, scoreOptions), scoreOptions, diagnostics };
+}

package/src/cdk/assembly.ts

@@ -0,0 +1,133 @@
+/**
+ * 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";
+import type { CdkManifest, CdkStack, CdkTreeFile, CdkTreeNode, CfnTemplate, CloudAssembly } from "./types";
+
+/** Every `*.template.json` directly under `dir`. */
+function listTemplates(dir: string): string[] {
+  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: string): boolean {
+  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: string, phase: "emit" | "bridge" | "apply"): string {
+  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<T>(path: string): T | undefined {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as T;
+  } 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: string, displayName?: string): string {
+  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: CdkTreeNode | undefined): Map<string, CdkTreeNode> {
+  const byPath = new Map<string, CdkTreeNode>();
+  const visit = (node: CdkTreeNode): void => {
+    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: string): CloudAssembly {
+  const diagnostics: string[] = [];
+  const manifest = readJson<CdkManifest>(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<CdkTreeFile>(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: CdkStack[] = [];
+  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<CfnTemplate>(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/src/cdk/graph.test.ts

@@ -0,0 +1,206 @@
+import { describe, test, expect } from "vitest";
+import { join } from "path";
+import { cdkNotSupported, isCloudAssembly, readCloudAssembly } from "./assembly";
+import { buildCdkGraph, constructLevel, dummyAssemblyReason } from "./graph";
+import { CFN_TIER_MAP, isScaffoldingParameter, resolveCfnTier } from "./tier-map";
+import { AWS_CARVE_TYPES } from "../terraform/aws-resources";
+
+const FIXTURES = join(__dirname, "__fixtures__");
+const ASSEMBLY = join(FIXTURES, "cdk.out");
+const DUMMY = join(FIXTURES, "cdk.out-dummy");
+
+describe("cloud assembly detection", () => {
+  test("a directory with a manifest and a synthesized template is an assembly", () => {
+    expect(isCloudAssembly(ASSEMBLY)).toBe(true);
+    expect(isCloudAssembly(DUMMY)).toBe(true);
+  });
+
+  test("a directory that is not one is not claimed", () => {
+    // manifest.json alone is far too common a filename to claim on sight; a
+    // Terraform estate and a missing directory are both plainly not assemblies.
+    expect(isCloudAssembly(join(__dirname, "..", "terraform", "__fixtures__", "sample-estate"))).toBe(false);
+    expect(isCloudAssembly(join(FIXTURES, "definitely-not-here"))).toBe(false);
+  });
+
+  test("the Terraform-only phases refuse an assembly by name", () => {
+    const message = cdkNotSupported("./cdk.out", "emit");
+    expect(message).toContain("carve emit");
+    expect(message).toContain("carve advise --from ./cdk.out");
+  });
+});
+
+describe("the CloudFormation tier map", () => {
+  test("is the AWS carve-out table read from the other end", () => {
+    // Every carvable Terraform type names a CloudFormation type, and that type
+    // resolves to the same tier from this side. No second table to keep in step.
+    for (const entry of AWS_CARVE_TYPES) {
+      expect(resolveCfnTier(entry.nativeType)).toEqual({ tier: entry.tier, mapsTo: entry.nativeType });
+    }
+    expect(Object.keys(CFN_TIER_MAP).length).toBeGreaterThan(70);
+  });
+
+  test("an unmapped CloudFormation type resolves to nothing", () => {
+    expect(resolveCfnTier("AWS::CloudFormation::Stack")).toBeNull();
+    expect(resolveCfnTier("AWS::S3::BucketPolicy")).toBeNull();
+  });
+
+  test("synthesizer parameters are told apart from an author's", () => {
+    expect(isScaffoldingParameter("BootstrapVersion")).toBe(true);
+    expect(isScaffoldingParameter("AssetParameters1a2b3c4dS3BucketA1B2C3")).toBe(true);
+    expect(isScaffoldingParameter("EnvName")).toBe(false);
+  });
+});
+
+describe("construct levels", () => {
+  test("classify by jsii class", () => {
+    expect(constructLevel("aws-cdk-lib.aws_s3.CfnBucket")).toBe("l1");
+    expect(constructLevel("aws-cdk-lib.aws_s3.Bucket")).toBe("l2");
+    expect(constructLevel("@aws-cdk/aws-s3.Bucket")).toBe("l2");
+    expect(constructLevel("constructs.Construct")).toBe("l3");
+    expect(constructLevel("my-app.ApiConstruct")).toBe("l3");
+    expect(constructLevel("aws-cdk-lib.NestedStack")).toBe("nested");
+    expect(constructLevel("aws-cdk-lib.Stack")).toBe("container");
+    expect(constructLevel(undefined)).toBe("unknown");
+  });
+});
+
+describe("buildCdkGraph", () => {
+  const { graph, signals, diagnostics } = buildCdkGraph(readCloudAssembly(ASSEMBLY));
+  const addresses = graph.nodes.map((n) => n.address);
+  const node = (address: string) => graph.nodes.find((n) => n.address === address);
+
+  test("ranks constructs, not CloudFormation resources", () => {
+    expect(addresses).toEqual([
+      "AppStack/Api",
+      "AppStack/Handler",
+      "AppStack/Legacy",
+      "AppStack/Reports.NestedStack",
+      "DataStack/Assets",
+      "DataStack/Table",
+    ]);
+  });
+
+  test("one L2 emitting three resources is one node, with its members named", () => {
+    expect(node("AppStack/Handler")).toMatchObject({ kind: "resource", type: "AWS::Lambda::Function" });
+    expect(signals.get("AppStack/Handler")?.members?.map((m) => m.type)).toEqual([
+      "AWS::Lambda::Function",
+      "AWS::IAM::Policy",
+      "AWS::IAM::Role",
+    ]);
+    // The role and the policy are not separately rankable — they carve with it.
+    expect(addresses).not.toContain("AppStack/Handler/ServiceRole");
+  });
+
+  test("an L3 subtree is one Composite candidate, ranked as a module", () => {
+    expect(node("AppStack/Api")).toMatchObject({ kind: "module" });
+    expect(node("AppStack/Api")?.type).toBeUndefined();
+    expect(signals.get("AppStack/Api")?.members).toHaveLength(3);
+    expect(signals.get("AppStack/Api")?.notes?.join(" ")).toContain("Composite candidate");
+    expect(addresses).not.toContain("AppStack/Api/Queue");
+  });
+
+  test("a bare L1 stands on its own", () => {
+    expect(node("AppStack/Legacy")).toMatchObject({ kind: "resource", type: "AWS::S3::Bucket" });
+  });
+
+  test("synthesis scaffolding never appears", () => {
+    expect(addresses.some((a) => a.includes("CDKMetadata"))).toBe(false);
+    for (const members of [...signals.values()].map((s) => s.members ?? [])) {
+      expect(members.some((m) => m.type === "AWS::CDK::Metadata")).toBe(false);
+    }
+  });
+
+  test("references inside one construct are not edges", () => {
+    // The bucket policy Refs its bucket and the function Refs its own role;
+    // both are internal to a carve set, so neither is boundary work.
+    const internal = graph.edges.filter((e) => e.from === e.to);
+    expect(internal).toHaveLength(0);
+    expect(graph.edges.filter((e) => e.from === "DataStack/Assets")).toHaveLength(0);
+  });
+
+  test("an intra-stack Ref is an edge carrying the property it sits in", () => {
+    expect(graph.edges).toContainEqual({
+      from: "AppStack/Handler",
+      to: "AppStack/Api",
+      attrs: ["Ref"],
+      via: ["Environment"],
+    });
+  });
+
+  test("Fn::ImportValue resolves through the exporting stack's Outputs", () => {
+    // Not a dangling export name: the edge lands on the construct that
+    // actually produces the value, in the other stack.
+    expect(graph.edges).toContainEqual({
+      from: "AppStack/Handler",
+      to: "DataStack/Assets",
+      attrs: ["Export"],
+      via: ["PolicyDocument"],
+      crossStack: true,
+    });
+  });
+
+  test("an output whose export is imported is not counted a second time", () => {
+    // DataStack exports the bucket ARN and AppStack imports it. That is one
+    // dependency, already drawn between the two constructs, so the output
+    // block does not also charge the bucket.
+    const outputs = graph.edges.filter((e) => e.fromKind === "output");
+    expect(outputs.map((e) => e.from)).toEqual(["output.AppStack.QueueUrl", "output.DataStack.TableName"]);
+  });
+
+  test("a stack output nobody imports is an output edge on what it reads", () => {
+    expect(graph.edges).toContainEqual({
+      from: "output.DataStack.TableName",
+      to: "DataStack/Table",
+      attrs: ["Ref"],
+      via: ["Value"],
+      fromKind: "output",
+    });
+  });
+
+  test("a CloudFormation Condition or an author's parameter marks a construct dynamic", () => {
+    expect(node("AppStack/Legacy")?.hasDynamic).toBe(true);
+    expect(node("DataStack/Assets")?.hasDynamic).toBe(false);
+  });
+
+  test("an asset-backed construct carries a penalty and says why", () => {
+    expect(signals.get("AppStack/Handler")?.penalties).toEqual({ asset: -10 });
+    expect(signals.get("AppStack/Handler")?.notes?.join(" ")).toContain("Asset-backed (Code)");
+  });
+
+  test("a nested stack is disqualified rather than scored", () => {
+    expect(signals.get("AppStack/Reports.NestedStack")?.disqualified).toContain("Nested stack");
+  });
+
+  test("a complete assembly has nothing to report about the read", () => {
+    expect(diagnostics).toEqual([]);
+  });
+});
+
+describe("a dummy-value assembly", () => {
+  const assembly = readCloudAssembly(DUMMY);
+
+  test("is recognized from the manifest's unresolved lookups", () => {
+    const reason = dummyAssemblyReason(assembly);
+    expect(reason).toContain("unresolved context lookup");
+    expect(reason).toContain("vpc-provider");
+  });
+
+  test("is recognized from a placeholder left in a template", () => {
+    // The same verdict with the manifest's admission removed: the template
+    // still holds the value the lookup would have replaced.
+    const withoutMissing = { ...assembly, manifest: { ...assembly.manifest, missing: [] } };
+    expect(dummyAssemblyReason(withoutMissing)).toContain("vpc-12345678");
+  });
+
+  test("disqualifies every construct in it", () => {
+    const { signals } = buildCdkGraph(assembly);
+    expect(signals.size).toBeGreaterThan(0);
+    for (const signal of signals.values()) expect(signal.disqualified).toContain("unresolved context lookup");
+  });
+
+  test("without tree.json, grouping falls back to the construct path and says so", () => {
+    const { graph, diagnostics } = buildCdkGraph(assembly);
+    expect(graph.nodes.map((n) => n.address)).toEqual(["LookupStack/AppBucket", "LookupStack/AppSg"]);
+    expect(diagnostics.join(" ")).toContain("No tree.json");
+  });
+});