@intentius/chant-lexicon-aws 0.124.51 → 0.124.54

package/src/components/cfn-exports-in-use.test.ts

@@ -0,0 +1,146 @@
+/**
+ * An export another stack still imports (#4466c): CloudFormation refuses to
+ * change or remove it at apply, so a plan that would is refused at plan
+ * time, naming both stacks. A change the plan cannot say about is a hole.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CapabilityRegistry } from "@intentius/chant/components/capability";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { planFanOut } from "@intentius/chant/components/fan-out";
+import { planPrSet } from "@intentius/chant/components/pr-run";
+import { CfnExportInUseError, createCfnDeployCapability } from "./apply";
+import { createMockCloudExecutor, type FakeStackConfig } from "./__tests__/mock-cloud-executor";
+
+let dir: string;
+let template: string;
+const write = (t: unknown) => writeFileSync(template, JSON.stringify(t));
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "cfn-exports-"));
+  template = join(dir, "network.json");
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+const exported = (value: unknown = { Ref: "Vpc" }) => ({
+  Resources: { Vpc: { Type: "AWS::EC2::VPC" }, Topic: { Type: "AWS::SNS::Topic" } },
+  Outputs: { VpcId: { Value: value, Export: { Name: { "Fn::Sub": "${AWS::StackName}-VpcId" } } } },
+});
+const topicChange = { action: "Modify" as const, logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false, replacementMode: "False" as const };
+const network = (extra: Partial<FakeStackConfig> = {}, importers: string[] = ["app"]): FakeStackConfig => ({
+  outputs: { VpcId: "vpc-1" },
+  exports: { "network-VpcId": "VpcId" },
+  importedBy: { "network-VpcId": importers },
+  changes: [topicChange],
+  ...extra,
+});
+
+async function plan(config: FakeStackConfig, extra: Record<string, unknown> = {}) {
+  const mock = createMockCloudExecutor({ stacks: { network: config } });
+  const result = await createCfnDeployCapability(mock.executor)
+    .plan!({ env: "local", component: "network" }, { stack: "network", template, ...extra })
+    .catch((e: unknown) => e);
+  return { mock, result };
+}
+const methods = (mock: ReturnType<typeof createMockCloudExecutor>) => mock.calls.map((c) => c.method);
+
+describe("a plan that changes or removes an export in use (#4466c)", () => {
+  it("removing an export app imports is refused at plan time, naming both stacks, and nothing is executed", async () => {
+    write({ Resources: { Vpc: { Type: "AWS::EC2::VPC" }, Topic: { Type: "AWS::SNS::Topic" } } });
+    const { mock, result } = await plan(network());
+    expect(result).toBeInstanceOf(CfnExportInUseError);
+    expect((result as CfnExportInUseError).uses).toEqual([{ exportName: "network-VpcId", change: "removes {export}", importers: ["app"] }]);
+    expect((result as Error).message).toBe(
+      'cfn-deploy "network": refusing the plan: it removes export network-VpcId, which stack app still imports. ' +
+        "CloudFormation refuses to change or remove an export another stack imports. Change app to stop importing it first, then change network.",
+    );
+    expect(methods(mock)).toContain("deleteChangeSet");
+    expect(methods(mock)).not.toContain("executeChangeSet");
+  });
+
+  it("changing an export's value is refused, with the value it has and the one it would get", async () => {
+    write(exported("vpc-2"));
+    const { result } = await plan(network());
+    expect(result).toBeInstanceOf(CfnExportInUseError);
+    expect((result as Error).message).toContain("it changes export network-VpcId from vpc-1 to vpc-2, which stack app still imports");
+  });
+
+  it("renaming an export is removing it", async () => {
+    write({ ...exported(), Outputs: { VpcId: { Value: { Ref: "Vpc" }, Export: { Name: "renamed-VpcId" } } } });
+    const { result } = await plan(network());
+    expect((result as CfnExportInUseError).uses?.[0]).toMatchObject({ exportName: "network-VpcId", change: "removes {export}" });
+  });
+
+  it("every importer is named", async () => {
+    write({ Resources: { Topic: { Type: "AWS::SNS::Topic" } } });
+    const { result } = await plan(network({}, ["edge", "app"]));
+    expect((result as Error).message).toContain("which stacks app, edge still import");
+  });
+
+  it("an export whose value stays plans as before, and only that export's importers are asked for", async () => {
+    write(exported());
+    const { mock, result } = await plan(network());
+    expect(result).not.toBeInstanceOf(Error);
+    expect((result as { changeSet: { member: { holes: unknown[] } } }).changeSet.member.holes).toEqual([]);
+    expect(methods(mock)).not.toContain("listImports");
+  });
+
+  it("an export nobody imports can change", async () => {
+    write(exported("vpc-2"));
+    const { result } = await plan(network({}, []));
+    expect(result).not.toBeInstanceOf(Error);
+  });
+
+  it("an export whose new value is known only after apply is a hole naming its importers, not a refusal", async () => {
+    write(exported());
+    const { result } = await plan(
+      network({ changes: [{ action: "Modify", logicalResourceId: "Vpc", resourceType: "AWS::EC2::VPC", replacement: true, replacementMode: "True" }] }),
+      { onReplace: "allow" },
+    );
+    expect(result).not.toBeInstanceOf(Error);
+    expect((result as { changeSet: { member: { holes: unknown[] } } }).changeSet.member.holes).toEqual([
+      {
+        address: "Outputs.VpcId",
+        reason:
+          "the plan may change export network-VpcId: the value of output VpcId is known only after apply, and app still imports it; CloudFormation refuses the apply if it changes",
+      },
+    ]);
+  });
+});
+
+describe("in a pull request's plan (#4466c)", () => {
+  it("the exporter's member fails to plan with the refusal, and the set is failed", async () => {
+    write({ Resources: { Topic: { Type: "AWS::SNS::Topic" } } });
+    const mock = createMockCloudExecutor({ stacks: { network: network() } });
+    const registry = new CapabilityRegistry();
+    registry.register(createCfnDeployCapability(mock.executor));
+    const components: DriverComponent[] = [
+      { name: "network", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: "network", template }] }] },
+    ];
+    const set = await planPrSet({ components, plan: planFanOut({ components, changed: ["network"] }), registry, env: "local" });
+    expect(set.failed).toBe(true);
+    const member = set.members.find((m) => m.member === "network")!;
+    expect(member.status).toBe("plan-failed");
+    expect(member.error).toContain("it removes export network-VpcId, which stack app still imports");
+  });
+});
+
+describe("a backend that cannot list imports (#4466d)", () => {
+  it("is a hole on the export at stake, not a failed plan", async () => {
+    write({ Resources: { Topic: { Type: "AWS::SNS::Topic" } } });
+    const mock = createMockCloudExecutor({ stacks: { network: network() } });
+    mock.executor.cloudformation.listImports = async () => {
+      throw new Error("UnknownAction: ListImports");
+    };
+    const result = await createCfnDeployCapability(mock.executor).plan!({ env: "local", component: "network" }, { stack: "network", template });
+    expect(result.changeSet!.member.holes).toEqual([
+      {
+        address: "Outputs.VpcId",
+        reason: "the plan removes export network-VpcId, and the stacks that import it could not be listed: UnknownAction: ListImports",
+      },
+    ]);
+  });
+});

package/src/components/cfn-imports-preview.test.ts

@@ -0,0 +1,178 @@
+/**
+ * The preview of an importer whose export is not known yet (#4466b): its
+ * change set is made from a copy of its template in which each such import
+ * is a stand-in parameter (`cfnPlaceholder`), with entries and a PlanShape
+ * as #4423 gives a member whose parameters are unknown. Once the exporter
+ * applies, the real change set is checked with `planShapeDifferences`
+ * before it executes.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CapabilityRegistry } from "@intentius/chant/components/capability";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { withDeclaredReads } from "@intentius/chant/components/declared-reads";
+import { planFanOut } from "@intentius/chant/components/fan-out";
+import { applyPrSet, planPrSet } from "@intentius/chant/components/pr-run";
+import { CFN_UNKNOWN_MARK, createCfnDeployCapability } from "./apply";
+import { cfnStandInParameter, cfnTemplateWithStandIns } from "./cfn-imports";
+import { createMockCloudExecutor, type FakeStackConfig } from "./__tests__/mock-cloud-executor";
+
+let dir: string;
+const write = (name: string, template: unknown): string => {
+  const path = join(dir, name);
+  writeFileSync(path, JSON.stringify(template));
+  return path;
+};
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "cfn-imports-preview-"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+const NETWORK = {
+  Resources: { Vpc: { Type: "AWS::EC2::VPC" } },
+  Outputs: { VpcId: { Value: { Ref: "Vpc" }, Export: { Name: { "Fn::Sub": "${AWS::StackName}-VpcId" } } } },
+};
+const APP = {
+  Resources: {
+    Group: { Type: "AWS::EC2::SecurityGroup", Properties: { GroupDescription: "app", VpcId: { "Fn::ImportValue": "network-VpcId" } } },
+  },
+  Outputs: { Vpc: { Value: { "Fn::ImportValue": "network-VpcId" } } },
+};
+const STAND_IN = cfnStandInParameter("network-VpcId");
+
+describe("the template copy (#4466b)", () => {
+  it("each import of a waiting name is a Ref to a String stand-in parameter; other imports stay", () => {
+    const template = { ...APP, Resources: { ...APP.Resources, Other: { Type: "AWS::SNS::Topic", Properties: { TopicName: { "Fn::ImportValue": "elsewhere" } } } } };
+    const { template: copy, standIns } = cfnTemplateWithStandIns(template, ["network-VpcId"], {});
+    expect(standIns).toEqual({ [STAND_IN]: "network-VpcId" });
+    expect(copy.Resources).toEqual({
+      Group: { Type: "AWS::EC2::SecurityGroup", Properties: { GroupDescription: "app", VpcId: { Ref: STAND_IN } } },
+      Other: { Type: "AWS::SNS::Topic", Properties: { TopicName: { "Fn::ImportValue": "elsewhere" } } },
+    });
+    expect(copy.Outputs).toEqual({ Vpc: { Value: { Ref: STAND_IN } } });
+    expect((copy.Parameters as Record<string, { Type: string }>)[STAND_IN]!.Type).toBe("String");
+    // The original is untouched.
+    expect(template.Resources.Group.Properties.VpcId).toEqual({ "Fn::ImportValue": "network-VpcId" });
+  });
+
+  it("a stand-in name keeps only letters and digits, and two names never share one", () => {
+    expect(cfnStandInParameter("a-b")).toMatch(/^ChantImportab[0-9a-f]{8}$/);
+    expect(cfnStandInParameter("a-b")).not.toBe(cfnStandInParameter("a:b"));
+  });
+});
+
+describe("cfn-deploy previews an importer whose export is not known yet (#4466b)", () => {
+  it("creates its change set from the copy with a stand-in value, marks what the import drives, and removes the copy", async () => {
+    const template = write("app.json", APP);
+    const mock = createMockCloudExecutor({
+      stacks: { app: { changes: [{ action: "Add", logicalResourceId: "Group", resourceType: "AWS::EC2::SecurityGroup", replacement: false }] } },
+    });
+    const planned = await createCfnDeployCapability(mock.executor).plan!(
+      { env: "local", component: "app", unresolvedInputs: ["network"] },
+      { stack: "app", template, imports: { "network-VpcId": undefined } },
+    );
+    const created = mock.calls.find((c) => c.method === "createChangeSet")!.args as { templatePath: string; parameters: Record<string, string> };
+    expect(created.templatePath).not.toBe(template);
+    expect(created.templatePath).toMatch(/app\.preview\.template\.json$/);
+    expect(created.parameters).toEqual({ [STAND_IN]: CFN_UNKNOWN_MARK });
+    expect(existsSync(created.templatePath)).toBe(false);
+    expect(planned.artifact).toMatchObject({ kind: "cfn-deploy-shape", member: "app" });
+    expect(planned.shape).toMatchObject({ member: "app", unknownInputs: ["network"] });
+    expect(planned.shape!.entries).toEqual([
+      expect.objectContaining({ logicalId: "Group", action: "create", unknown: ["VpcId"] }),
+    ]);
+    expect(planned.changeSet!.member.holes).toEqual([]);
+    expect(planned.changeSet!.entries).toHaveLength(1);
+    expect(mock.calls.map((c) => c.method)).not.toContain("executeChangeSet");
+  });
+
+  it("the preview's shape enters the digest, so a different preview is a different plan", async () => {
+    const template = write("app.json", APP);
+    const plan = async (changes: FakeStackConfig["changes"]) =>
+      createCfnDeployCapability(createMockCloudExecutor({ stacks: { app: { changes } } }).executor).plan!(
+        { env: "local", component: "app", unresolvedInputs: ["network"] },
+        { stack: "app", template, imports: { "network-VpcId": undefined } },
+      );
+    const one = await plan([{ action: "Add", logicalResourceId: "Group", resourceType: "AWS::EC2::SecurityGroup", replacement: false }]);
+    const two = await plan([
+      { action: "Add", logicalResourceId: "Group", resourceType: "AWS::EC2::SecurityGroup", replacement: false },
+      { action: "Add", logicalResourceId: "Extra", resourceType: "AWS::SNS::Topic", replacement: false },
+    ]);
+    expect(one.planDigest).not.toBe(two.planDigest);
+  });
+});
+
+describe("pr-apply over two stacks wired only by an import (#4466b)", () => {
+  const approvedFirst = { status: "approved" as const, approvedBy: ["github:rev"] };
+  const groupAdd = { action: "Add" as const, logicalResourceId: "Group", resourceType: "AWS::EC2::SecurityGroup", replacement: false };
+  const extraAdd = { action: "Add" as const, logicalResourceId: "Extra", resourceType: "AWS::SNS::Topic", replacement: false };
+  const stacks = (): Record<string, FakeStackConfig> => ({
+    network: { outputs: { VpcId: "vpc-1" }, changes: [{ action: "Add", logicalResourceId: "Vpc", resourceType: "AWS::EC2::VPC", replacement: false }] },
+    app: { changes: [groupAdd] },
+  });
+  const executed = (mock: ReturnType<typeof createMockCloudExecutor>) =>
+    mock.calls.filter((c) => c.method === "executeChangeSet").map((c) => (c.args as { stackName: string }).stackName);
+
+  async function planned(config: Record<string, FakeStackConfig>) {
+    const declared: DriverComponent[] = [
+      { name: "network", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: "network", template: write("network.json", NETWORK) }] }] },
+      { name: "app", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: "app", template: write("app.json", APP) }] }] },
+    ];
+    const mock = createMockCloudExecutor({ stacks: config });
+    const registry = new CapabilityRegistry();
+    registry.register(createCfnDeployCapability(mock.executor));
+    const components = await withDeclaredReads(declared, registry, dir);
+    const plan = planFanOut({ components, changed: ["network", "app"] });
+    const set = await planPrSet({ components, plan, registry, env: "local" });
+    return { mock, registry, components, plan, set };
+  }
+
+  it("the plan previews app with entries and a shape that names the import as unknown", async () => {
+    const { set } = await planned(stacks());
+    expect(set.shapes?.app).toMatchObject({ member: "app", unknownInputs: ["network"] });
+    expect(set.plans.app?.app).toMatchObject({ kind: "cfn-deploy-shape" });
+    expect(set.doc.entries.filter((e) => e.member === "app").map((e) => e.address)).toEqual(["Group"]);
+  });
+
+  it("the real change set has the previewed shape: one approval covers the round, and both stacks execute in order", async () => {
+    const { mock, registry, components, plan, set } = await planned(stacks());
+    let asked = 0;
+    const applied = await applyPrSet({
+      components,
+      plan,
+      registry,
+      env: "local",
+      set,
+      approval: approvedFirst,
+      decideRound: async () => {
+        asked++;
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(asked).toBe(0);
+    expect(applied.status).toBe("applied");
+    expect(executed(mock)).toEqual(["network", "app"]);
+    expect(applied.rounds?.[0]).toMatchObject({ round: 2, status: "applied", covered: { digest: set.doc.digest, filledInputs: ["network.VpcId"] } });
+  });
+
+  it("a real change set the preview did not show is not executed: app waits at the next round", async () => {
+    const { mock, registry, components, plan, set } = await planned(stacks());
+    mock.setStack("app", { changes: [groupAdd, extraAdd] });
+    const applied = await applyPrSet({
+      components,
+      plan,
+      registry,
+      env: "local",
+      set,
+      approval: approvedFirst,
+      decideRound: async () => ({ satisfied: false, approval: { status: "pending" } }),
+    });
+    expect(applied.status).toBe("waiting");
+    expect(executed(mock)).toEqual(["network"]);
+    expect(applied.rounds?.[0]).toMatchObject({ round: 2, status: "waiting", notCovered: "app now plans to create Extra, which the first plan did not" });
+  });
+});

package/src/components/cfn-imports-three-stacks.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Three stacks wired only by exports and imports need one approval
+ * (#4466d), as #4430 shows for parameters: the shape of
+ * `examples/demo-composed-stacks`'s `chant-compose-imports` scenario,
+ * against the mock executor. The same scenario runs on Floci in
+ * demo-composed-stacks-floci.e2e.test.ts.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CapabilityRegistry } from "@intentius/chant/components/capability";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { withDeclaredReads } from "@intentius/chant/components/declared-reads";
+import { planFanOut } from "@intentius/chant/components/fan-out";
+import { applyPrSet, planPrSet } from "@intentius/chant/components/pr-run";
+import { createCfnDeployCapability } from "./apply";
+import { createMockCloudExecutor, type FakeStackConfig } from "./__tests__/mock-cloud-executor";
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "cfn-imports-three-"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+const TEMPLATES = {
+  network: {
+    Resources: { mainVpc: { Type: "AWS::EC2::VPC" }, subnetC: { Type: "AWS::EC2::Subnet", Properties: { VpcId: { Ref: "mainVpc" }, CidrBlock: "10.0.3.0/24" } } },
+    Outputs: { SubnetCId: { Value: { Ref: "subnetC" }, Export: { Name: "chant-compose-subnet-c-id" } } },
+  },
+  app: {
+    Resources: { importsInterface: { Type: "AWS::EC2::NetworkInterface", Properties: { SubnetId: { "Fn::ImportValue": "chant-compose-subnet-c-id" } } } },
+    Outputs: { ImportsInterfaceId: { Value: { Ref: "importsInterface" }, Export: { Name: "chant-compose-imports-interface" } } },
+  },
+  edge: {
+    Resources: {
+      importsInterfaceRecord: {
+        Type: "AWS::SSM::Parameter",
+        Properties: { Name: "/chant-compose/imports-interface", Type: "String", Value: { "Fn::ImportValue": "chant-compose-imports-interface" } },
+      },
+    },
+  },
+};
+
+const add = (logicalResourceId: string, resourceType: string) => ({ action: "Add" as const, logicalResourceId, resourceType, replacement: false });
+const stacks = (): Record<string, FakeStackConfig> => ({
+  network: { outputs: { SubnetCId: "subnet-c" }, changes: [add("subnetC", "AWS::EC2::Subnet")] },
+  app: { outputs: { ImportsInterfaceId: "eni-1" }, changes: [add("importsInterface", "AWS::EC2::NetworkInterface")] },
+  edge: { changes: [add("importsInterfaceRecord", "AWS::SSM::Parameter")] },
+});
+const executed = (mock: ReturnType<typeof createMockCloudExecutor>) =>
+  mock.calls.filter((c) => c.method === "executeChangeSet").map((c) => (c.args as { stackName: string }).stackName);
+
+async function planned() {
+  // No dependsOn and no inputs: the imports are the only wiring.
+  const declared: DriverComponent[] = (["edge", "app", "network"] as const).map((name) => {
+    const template = join(dir, `${name}.template.json`);
+    writeFileSync(template, JSON.stringify(TEMPLATES[name]));
+    return { name, dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: name, template }] }] };
+  });
+  const mock = createMockCloudExecutor({ stacks: stacks() });
+  const registry = new CapabilityRegistry();
+  registry.register(createCfnDeployCapability(mock.executor));
+  const components = await withDeclaredReads(declared, registry, dir);
+  const plan = planFanOut({ components, changed: ["network", "app", "edge"] });
+  const set = await planPrSet({ components, plan, registry, env: "local" });
+  return { mock, registry, components, plan, set };
+}
+
+describe("three stacks wired only by imports (#4466d)", () => {
+  it("are ordered by the imports, with each import known after apply and each importer previewed", async () => {
+    const { plan, set } = await planned();
+    expect(plan.waves).toEqual([["network"], ["app"], ["edge"]]);
+    const by = Object.fromEntries(set.members.map((m) => [m.component, m]));
+    expect(by.app!.unknownInputs).toEqual(["network.SubnetCId"]);
+    expect(by.edge!.unknownInputs).toEqual(["app.ImportsInterfaceId"]);
+    expect(set.plans.app?.app).toMatchObject({ kind: "cfn-deploy-shape" });
+    expect(set.plans.edge?.edge).toMatchObject({ kind: "cfn-deploy-shape" });
+    expect(set.doc.members.every((m) => m.holes.length === 0)).toBe(true);
+    expect(set.doc.entries.map((e) => `${e.member}/${e.address}`).sort()).toEqual(["app/importsInterface", "edge/importsInterfaceRecord", "network/subnetC"]);
+  });
+
+  it("need one approval: both rounds are covered and the three stacks execute in order", async () => {
+    const { mock, registry, components, plan, set } = await planned();
+    let asked = 0;
+    const applied = await applyPrSet({
+      components,
+      plan,
+      registry,
+      env: "local",
+      set,
+      approval: { status: "approved", approvedBy: ["github:rev"] },
+      decideRound: async () => {
+        asked++;
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(asked).toBe(0);
+    expect(applied.status).toBe("applied");
+    expect(executed(mock)).toEqual(["network", "app", "edge"]);
+    const rounds = applied.rounds ?? [];
+    expect(rounds.find((r) => r.components.includes("app"))?.covered?.filledInputs).toContain("network.SubnetCId");
+    // Round 2 plans app and edge, and edge waits for app; the last round with edge is the one that applies it.
+    expect([...rounds].reverse().find((r) => r.components.includes("edge"))?.covered?.filledInputs).toContain("app.ImportsInterfaceId");
+  });
+});

package/src/components/cfn-imports.test.ts

@@ -0,0 +1,213 @@
+/**
+ * `Fn::ImportValue` between stacks (#4466a): an import of a name another
+ * `cfn-deploy` step's template exports is a read of `<component>.<output>`,
+ * which orders the importer after the exporter, lists it under
+ * `unknownInputs` and plans it as waiting on that stack. A name the plan
+ * cannot resolve is a hole that says why.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CapabilityRegistry } from "@intentius/chant/components/capability";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { withDeclaredReads } from "@intentius/chant/components/declared-reads";
+import { planFanOut } from "@intentius/chant/components/fan-out";
+import { planPrSet } from "@intentius/chant/components/pr-run";
+import { capabilitySteps } from "@intentius/chant/components/wave-plan";
+import { cfnDeclaredReads, cfnPlannedOutputs, createCfnDeployCapability } from "./apply";
+import { cfnExports, cfnImportPointer, cfnImports, cfnKnownValues, cfnPseudoParameters, resolveCfnName } from "./cfn-imports";
+import { createMockCloudExecutor } from "./__tests__/mock-cloud-executor";
+
+let dir: string;
+const write = (name: string, template: unknown): string => {
+  const path = join(dir, name);
+  writeFileSync(path, JSON.stringify(template));
+  return path;
+};
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "cfn-imports-"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+const NETWORK = {
+  Resources: { Vpc: { Type: "AWS::EC2::VPC" } },
+  Outputs: {
+    VpcId: { Value: { Ref: "Vpc" }, Export: { Name: { "Fn::Sub": "${AWS::StackName}-VpcId" } } },
+    Internal: { Value: { Ref: "Vpc" } },
+  },
+};
+const APP = {
+  Parameters: { NetworkStack: { Type: "String", Default: "network" } },
+  Resources: {
+    Group: { Type: "AWS::EC2::SecurityGroup", Properties: { VpcId: { "Fn::ImportValue": { "Fn::Sub": "${NetworkStack}-VpcId" } } } },
+  },
+  Outputs: { GroupId: { Value: { Ref: "Group" }, Export: { Name: "app-GroupId" } } },
+};
+
+describe("export and import names (#4466a)", () => {
+  const known = { NetworkStack: "network", "AWS::StackName": "app" };
+
+  it("a string is itself; Fn::Sub, Ref and Fn::Join resolve from what is known", () => {
+    expect(resolveCfnName("x", known)).toEqual({ name: "x" });
+    expect(resolveCfnName({ "Fn::Sub": "${NetworkStack}-VpcId" }, known)).toEqual({ name: "network-VpcId" });
+    expect(resolveCfnName({ "Fn::Sub": ["${Prefix}-${AWS::StackName}", { Prefix: { Ref: "NetworkStack" } }] }, known)).toEqual({ name: "network-app" });
+    expect(resolveCfnName({ "Fn::Sub": "${!Literal}-x" }, known)).toEqual({ name: "${Literal}-x" });
+    expect(resolveCfnName({ Ref: "NetworkStack" }, known)).toEqual({ name: "network" });
+    expect(resolveCfnName({ "Fn::Join": ["-", [{ Ref: "NetworkStack" }, "VpcId"]] }, known)).toEqual({ name: "network-VpcId" });
+  });
+
+  it("a name that reads what the plan does not know is unresolved, and says what it reads", () => {
+    expect(resolveCfnName({ "Fn::Sub": "${Missing}-VpcId" }, known)).toEqual({ unresolved: "reads parameter Missing, which has no value the plan knows" });
+    expect(resolveCfnName({ "Fn::Sub": "${AWS::AccountId}-VpcId" }, known)).toEqual({ unresolved: "reads AWS::AccountId, which is known only at apply" });
+    expect(resolveCfnName({ "Fn::Sub": "${Vpc.Arn}" }, known)).toEqual({ unresolved: "reads Vpc.Arn, a resource attribute" });
+    expect(resolveCfnName({ "Fn::Select": [0, ["a"]] }, known)).toEqual({ unresolved: "uses Fn::Select, which this plan does not follow" });
+  });
+
+  it("the pseudo parameters: the stack name always, the region's when the environment names it", () => {
+    expect(cfnPseudoParameters("app", {})).toEqual({ "AWS::StackName": "app" });
+    expect(cfnPseudoParameters("app", { AWS_REGION: "cn-north-1" })).toEqual({
+      "AWS::StackName": "app",
+      "AWS::Region": "cn-north-1",
+      "AWS::Partition": "aws-cn",
+      "AWS::URLSuffix": "amazonaws.com.cn",
+    });
+  });
+
+  it("known values are the defaults, overlaid by plain inputs; a wired input is not known", () => {
+    const values = cfnKnownValues(APP, "app", { NetworkStack: "shared", Other: { stackOutput: { stack: "x", name: "y" } } }, {});
+    expect(values).toEqual({ NetworkStack: "shared", "AWS::StackName": "app" });
+  });
+
+  it("lists exports by output and imports by place", () => {
+    expect(cfnExports(NETWORK, cfnKnownValues(NETWORK, "network", {}, {}))).toEqual([{ output: "VpcId", name: "network-VpcId" }]);
+    expect(cfnImports(APP, cfnKnownValues(APP, "app", {}, {}))).toEqual([{ at: "Resources.Group.Properties.VpcId", logicalId: "Group", name: "network-VpcId" }]);
+  });
+
+  it("an export name's pointer escapes / and ~", () => {
+    expect(cfnImportPointer("a/b~c")).toBe("/imports/a~1b~0c");
+  });
+});
+
+describe("cfn-deploy's declared reads (#4466a)", () => {
+  it("an import of a name another step exports is a read of that component's output", () => {
+    const network = write("network.json", NETWORK);
+    const app = write("app.json", APP);
+    const reads = cfnDeclaredReads(dir, [
+      { component: "network", index: 0, step: { stack: "network", template: network } },
+      { component: "app", index: 0, step: { stack: "app", template: app } },
+    ]);
+    expect(reads).toEqual([{ reader: "app", index: 0, upstream: "network", output: "VpcId", at: "/imports/network-VpcId" }]);
+  });
+
+  it("a relative template path is read against the root", () => {
+    write("network.json", NETWORK);
+    write("app.json", APP);
+    const reads = cfnDeclaredReads(dir, [
+      { component: "network", index: 0, step: { template: "network.json" } },
+      { component: "app", index: 0, step: { template: "app.json" } },
+    ]);
+    expect(reads.map((r) => `${r.reader}<-${r.upstream}.${r.output}`)).toEqual(["app<-network.VpcId"]);
+  });
+
+  it("no read for a name no step exports, a name two steps export, or a name the step cannot resolve", () => {
+    const network = write("network.json", NETWORK);
+    const twin = write("twin.json", NETWORK);
+    const app = write("app.json", APP);
+    // network and twin both default AWS::StackName to the same stack name: two exports of one name.
+    expect(
+      cfnDeclaredReads(dir, [
+        { component: "network", index: 0, step: { stack: "network", template: network } },
+        { component: "twin", index: 0, step: { stack: "network", template: twin } },
+        { component: "app", index: 0, step: { stack: "app", template: app } },
+      ]),
+    ).toEqual([]);
+    expect(cfnDeclaredReads(dir, [{ component: "app", index: 0, step: { stack: "app", template: app } }])).toEqual([]);
+    const wired = write("wired.json", { ...APP, Parameters: { NetworkStack: { Type: "String" } } });
+    expect(
+      cfnDeclaredReads(dir, [
+        { component: "network", index: 0, step: { stack: "network", template: network } },
+        { component: "app", index: 0, step: { stack: "app", template: wired, inputs: { NetworkStack: { stackOutput: { stack: "x", name: "y" } } } } },
+      ]),
+    ).toEqual([]);
+  });
+
+  it("an output that passes an import through is known at the import's value", () => {
+    const template = { Outputs: { Vpc: { Value: { "Fn::ImportValue": "network-VpcId" } }, Other: { Value: { "Fn::ImportValue": "elsewhere" } } } };
+    expect(cfnPlannedOutputs(template, [], { Vpc: "old", Other: "x" }, {}, { "network-VpcId": "vpc-123" })).toEqual({ known: { Vpc: "vpc-123" }, unknown: ["Other"] });
+  });
+});
+
+describe("a pull request's plan over stacks wired only by imports (#4466a)", () => {
+  async function planned() {
+    const network = write("network.json", NETWORK);
+    const app = write("app.json", APP);
+    const declared: DriverComponent[] = [
+      { name: "network", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: "network", template: network }] }] },
+      { name: "app", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: "app", template: app }] }] },
+    ];
+    const mock = createMockCloudExecutor({ stacks: { network: { missing: true }, app: { missing: true } } });
+    const registry = new CapabilityRegistry();
+    registry.register(createCfnDeployCapability(mock.executor));
+    const components = await withDeclaredReads(declared, registry, dir);
+    const plan = planFanOut({ components, changed: ["network", "app"] });
+    const set = await planPrSet({ components, plan, registry, env: "local" });
+    return { components, plan, set, mock };
+  }
+
+  it("orders the importer after the exporter and writes the read into its step", async () => {
+    const { components, plan } = await planned();
+    expect(plan.waves).toEqual([["network"], ["app"]]);
+    const app = components.find((c) => c.name === "app")!;
+    expect(app.dependsOn).toEqual(["network"]);
+    expect(capabilitySteps(app.deploy)[0]).toMatchObject({ imports: { "network-VpcId": { stackOutput: { stack: "network", name: "VpcId" } } } });
+  });
+
+  it("lists the import under unknownInputs and reads, while network's plan cannot say the value", async () => {
+    const { set } = await planned();
+    const app = set.members.find((m) => m.component === "app")!;
+    expect(app.unknownInputs).toEqual(["network.VpcId"]);
+    expect(app.reads).toEqual([{ upstream: "network", outputs: ["VpcId"], unknown: ["VpcId"] }]);
+  });
+
+  it("an importer whose template cannot be read as JSON plans as waiting on the exporter (no preview, #4466b)", async () => {
+    const { set, components } = await planned();
+    const app = components.find((c) => c.name === "app")!;
+    const step = capabilitySteps(app.deploy)[0]! as Record<string, unknown>;
+    writeFileSync(step.template as string, "not json");
+    const mock = createMockCloudExecutor({ stacks: { app: { missing: true } } });
+    const planned2 = await createCfnDeployCapability(mock.executor).plan!(
+      { env: "local", component: "app", unresolvedInputs: ["network"] },
+      { stack: "app", template: step.template as string, imports: { "network-VpcId": undefined } },
+    );
+    expect(planned2.changeSet!.member.holes).toEqual([
+      {
+        address: "app",
+        type: "AWS::CloudFormation::Stack",
+        reason: "imports network-VpcId, exported by network, which apply first; re-checked on apply; no preview: the template could not be read as JSON to stand in for its imports",
+      },
+    ]);
+    expect(set.doc.members.find((m) => m.member === "app")).toBeDefined();
+  });
+});
+
+describe("an import whose name the plan cannot resolve (#4466a)", () => {
+  it("is a hole on the importer's member that says what the name reads", async () => {
+    const template = write("app.json", {
+      Resources: { Group: { Type: "AWS::EC2::SecurityGroup", Properties: { VpcId: { "Fn::ImportValue": { "Fn::Sub": "${AWS::AccountId}-VpcId" } } } } },
+    });
+    const mock = createMockCloudExecutor({ stacks: { app: { changes: [{ action: "Add", logicalResourceId: "Group", resourceType: "AWS::EC2::SecurityGroup", replacement: false }] } } });
+    const planned = await createCfnDeployCapability(mock.executor).plan!({ env: "local", component: "app" }, { stack: "app", template });
+    expect(planned.changeSet!.member.holes).toEqual([
+      {
+        address: "Group",
+        type: "AWS::EC2::SecurityGroup",
+        reason:
+          "the Fn::ImportValue at Resources.Group.Properties.VpcId reads AWS::AccountId, which is known only at apply, so the plan cannot say which export it reads or whether a stack in this change exports it",
+      },
+    ]);
+    expect(planned.changeSet!.entries).toHaveLength(1);
+  });
+});