@intentius/chant-lexicon-aws 0.124.52 → 0.124.54

package/src/components/cfn-imports.ts

@@ -0,0 +1,246 @@
+/**
+ * `Fn::ImportValue` between stacks (#4466): which exports a template
+ * declares, which it imports, and the names they go by.
+ *
+ * A stack that imports another stack's export reads that stack, the way a
+ * CDK app wires its stacks. The read sits inside the template, so core does
+ * not see it in the step. `cfn-deploy`'s `declaredReads` finds it here: an
+ * import of a name another `cfn-deploy` step's template exports is a read of
+ * `<component>.<output>`, which core writes into the importer's step under
+ * `imports` (`CfnDeployInput.imports`) and orders, holds and lists like any
+ * other read.
+ *
+ * A name is a string, or an `Fn::Sub` (or `Fn::Join`, or `Ref`) over
+ * parameters and pseudo parameters. It resolves where the values it reads
+ * are known: a parameter with a plain value in the step's `inputs` or a
+ * `Default` in the template, `AWS::StackName`, and the region's pseudo
+ * parameters when `AWS_REGION` or `AWS_DEFAULT_REGION` names the region.
+ * Anything else (`AWS::AccountId`, a resource attribute, a parameter wired
+ * from another stack, an intrinsic this does not follow) leaves the name
+ * unresolved, and the plan says so in a hole.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+/** A name an export or import goes by: resolved, or why not. */
+export type CfnName = { name: string } | { unresolved: string };
+
+/** One export a template declares: the output it is, and its name. */
+export type CfnExport = { output: string } & CfnName;
+
+/** One import in a template: where it sits, as a dotted path, the logical id it sits under, and its name. */
+export type CfnImport = { at: string; logicalId: string } & CfnName;
+
+/** The template at `path`, read against `root` when relative, as JSON; `undefined` for one that cannot be read or parsed, or an archive reference. */
+export function readCfnTemplate(path: unknown, root?: string): Record<string, unknown> | undefined {
+  if (typeof path !== "string" || path.startsWith("archive:")) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(root && !isAbsolute(path) ? resolve(root, path) : path, "utf8")) as unknown;
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The region the plan runs against, when the environment names it. */
+function regionOf(env: NodeJS.ProcessEnv): string | undefined {
+  return env.AWS_REGION || env.AWS_DEFAULT_REGION || undefined;
+}
+
+/**
+ * The pseudo parameters this plan knows for `stack`: `AWS::StackName`, and
+ * `AWS::Region`, `AWS::Partition` and `AWS::URLSuffix` when the region is
+ * named. `AWS::AccountId` and `AWS::StackId` are not known before apply.
+ */
+export function cfnPseudoParameters(stack: string, env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const out: Record<string, string> = { "AWS::StackName": stack };
+  const region = regionOf(env);
+  if (region) {
+    out["AWS::Region"] = region;
+    out["AWS::Partition"] = region.startsWith("cn-") ? "aws-cn" : region.startsWith("us-gov-") ? "aws-us-gov" : "aws";
+    out["AWS::URLSuffix"] = region.startsWith("cn-") ? "amazonaws.com.cn" : "amazonaws.com";
+  }
+  return out;
+}
+
+/**
+ * The values a name in `template` can read for `stack`: each parameter's
+ * `Default`, overlaid by the step's plain inputs (a string, a number or a
+ * boolean; a wired reference or `undefined` is not known), and the pseudo
+ * parameters.
+ */
+export function cfnKnownValues(
+  template: Record<string, unknown> | undefined,
+  stack: string,
+  inputs: Record<string, unknown> | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const plain = (v: unknown): string | undefined =>
+    typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : undefined;
+  const params = (template?.Parameters ?? {}) as Record<string, { Default?: unknown } | undefined>;
+  for (const [k, p] of Object.entries(params)) {
+    const d = plain(p?.Default);
+    if (d !== undefined) out[k] = d;
+  }
+  for (const [k, v] of Object.entries(inputs ?? {})) {
+    const s = plain(v);
+    if (s !== undefined) out[k] = s;
+  }
+  return { ...out, ...cfnPseudoParameters(stack, env) };
+}
+
+/** Why a variable a name reads has no value here. */
+function unknownVariable(v: string, known: Record<string, string>): string | undefined {
+  if (v in known) return undefined;
+  if (v.includes(".")) return `reads ${v}, a resource attribute`;
+  if (v.startsWith("AWS::")) return `reads ${v}, which is known only at apply`;
+  return `reads parameter ${v}, which has no value the plan knows`;
+}
+
+/**
+ * The name `value` resolves to against `known`, or why it does not. A
+ * string is itself; `Fn::Sub` substitutes `${X}` from `known` and its own
+ * variables (`${!X}` is the literal `${X}`); `Ref` reads `known`;
+ * `Fn::Join` joins what it resolves. Any other shape is unresolved.
+ */
+export function resolveCfnName(value: unknown, known: Record<string, string>): CfnName {
+  if (typeof value === "string") return { name: value };
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return { unresolved: "is not a string or an intrinsic" };
+  const entries = Object.entries(value as Record<string, unknown>);
+  if (entries.length !== 1) return { unresolved: "is not a string or an intrinsic" };
+  const [key, arg] = entries[0]!;
+  if (key === "Ref") {
+    if (typeof arg !== "string") return { unresolved: "is a Ref without a name" };
+    const why = unknownVariable(arg, known);
+    return why ? { unresolved: why } : { name: known[arg]! };
+  }
+  if (key === "Fn::Sub") {
+    const text = typeof arg === "string" ? arg : Array.isArray(arg) && typeof arg[0] === "string" ? arg[0] : undefined;
+    if (text === undefined) return { unresolved: "is an Fn::Sub this plan cannot read" };
+    const vars: Record<string, string> = { ...known };
+    if (Array.isArray(arg) && arg[1] && typeof arg[1] === "object") {
+      for (const [k, v] of Object.entries(arg[1] as Record<string, unknown>)) {
+        const r = resolveCfnName(v, known);
+        if ("unresolved" in r) return { unresolved: `its Fn::Sub variable ${k} ${r.unresolved}` };
+        vars[k] = r.name;
+      }
+    }
+    let why: string | undefined;
+    const name = text.replace(/\$\{(!?)([^}]*)\}/g, (whole, bang: string, v: string) => {
+      if (bang) return "${" + v + "}";
+      const w = unknownVariable(v, vars);
+      if (w) {
+        why ??= w;
+        return whole;
+      }
+      return vars[v]!;
+    });
+    return why ? { unresolved: why } : { name };
+  }
+  if (key === "Fn::Join") {
+    if (!Array.isArray(arg) || typeof arg[0] !== "string" || !Array.isArray(arg[1])) return { unresolved: "is an Fn::Join this plan cannot read" };
+    const parts: string[] = [];
+    for (const part of arg[1] as unknown[]) {
+      const r = resolveCfnName(part, known);
+      if ("unresolved" in r) return r;
+      parts.push(r.name);
+    }
+    return { name: parts.join(arg[0]) };
+  }
+  return { unresolved: `uses ${key}, which this plan does not follow` };
+}
+
+/** Every export `template` declares (`Outputs.<name>.Export.Name`), by output, sorted. */
+export function cfnExports(template: Record<string, unknown> | undefined, known: Record<string, string>): CfnExport[] {
+  const outputs = (template?.Outputs ?? {}) as Record<string, { Export?: { Name?: unknown } } | undefined>;
+  const out: CfnExport[] = [];
+  for (const [output, o] of Object.entries(outputs).sort(([a], [b]) => a.localeCompare(b))) {
+    if (o?.Export === undefined) continue;
+    out.push({ output, ...resolveCfnName(o.Export.Name, known) });
+  }
+  return out;
+}
+
+/**
+ * Every `Fn::ImportValue` in `template`'s resources, outputs and conditions,
+ * with where it sits and the name it imports, in template order. An import
+ * whose argument is itself an import is listed once, unresolved.
+ */
+export function cfnImports(template: Record<string, unknown> | undefined, known: Record<string, string>): CfnImport[] {
+  const out: CfnImport[] = [];
+  const walk = (v: unknown, path: string, logicalId: string): void => {
+    if (Array.isArray(v)) return v.forEach((x, i) => walk(x, `${path}.${i}`, logicalId));
+    if (v === null || typeof v !== "object") return;
+    for (const [k, x] of Object.entries(v as Record<string, unknown>)) {
+      if (k === "Fn::ImportValue") {
+        out.push({ at: path, logicalId, ...resolveCfnName(x, known) });
+        continue;
+      }
+      walk(x, `${path}.${k}`, logicalId);
+    }
+  };
+  for (const section of ["Resources", "Outputs", "Conditions"] as const) {
+    const s = template?.[section];
+    if (s === null || typeof s !== "object") continue;
+    for (const [id, body] of Object.entries(s as Record<string, unknown>)) walk(body, `${section}.${id}`, id);
+  }
+  return out;
+}
+
+/** The JSON Pointer `CfnDeployInput.imports[name]` sits at in a `cfn-deploy` step. */
+export function cfnImportPointer(name: string): string {
+  return "/imports/" + name.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+/** The stand-in parameter that takes an import's place in a preview: `ChantImport`, the name's letters and digits, and a short digest so two names never share one. */
+export function cfnStandInParameter(name: string): string {
+  return `ChantImport${name.replace(/[^A-Za-z0-9]/g, "").slice(0, 200)}${createHash("sha256").update(name).digest("hex").slice(0, 8)}`;
+}
+
+/**
+ * A copy of `template` for a preview (#4466b): each `Fn::ImportValue` of a
+ * name in `names` is a `Ref` to a stand-in `String` parameter, which the
+ * preview fills with `cfnPlaceholder`. CloudFormation refuses a change set
+ * that imports an export that does not exist yet, so the importer of a stack
+ * the same change creates is planned against this copy. `standIns` maps each
+ * stand-in parameter to the export it stands for; a name the template never
+ * imports gets none.
+ */
+export function cfnTemplateWithStandIns(
+  template: Record<string, unknown>,
+  names: readonly string[],
+  known: Record<string, string>,
+): { template: Record<string, unknown>; standIns: Record<string, string> } {
+  const wanted = new Set(names);
+  const standIns: Record<string, string> = {};
+  const swap = (v: unknown): unknown => {
+    if (Array.isArray(v)) return v.map(swap);
+    if (v === null || typeof v !== "object") return v;
+    const entries = Object.entries(v as Record<string, unknown>);
+    if (entries.length === 1 && entries[0]![0] === "Fn::ImportValue") {
+      const r = resolveCfnName(entries[0]![1], known);
+      if ("name" in r && wanted.has(r.name)) {
+        const param = cfnStandInParameter(r.name);
+        standIns[param] = r.name;
+        return { Ref: param };
+      }
+      return v;
+    }
+    return Object.fromEntries(entries.map(([k, x]) => [k, swap(x)]));
+  };
+  const out: Record<string, unknown> = { ...template };
+  for (const section of ["Resources", "Outputs", "Conditions"] as const) {
+    if (template[section] !== undefined) out[section] = swap(template[section]);
+  }
+  if (Object.keys(standIns).length > 0) {
+    const params = { ...((template.Parameters ?? {}) as Record<string, unknown>) };
+    for (const [param, name] of Object.entries(standIns).sort(([a], [b]) => a.localeCompare(b))) {
+      params[param] = { Type: "String", Description: `chant preview: stands in for Fn::ImportValue ${name}, known after its stack applies` };
+    }
+    out.Parameters = params;
+  }
+  return { template: out, standIns };
+}

package/src/components/cfn-plan-shape-conformance.test.ts

@@ -0,0 +1,83 @@
+/**
+ * `cfn-deploy`'s plan shapes pass core's plan shape conformance (#4425):
+ * the preview with a stand-in parameter, the real change set planned after
+ * the upstream applied, and real change sets that add, drop or replace a
+ * resource, all made by `plan` against the mock executor.
+ */
+
+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 { checkPlanShapeConformance } from "@intentius/chant/components";
+import type { CfnChange } from "./cloud-executor";
+import { createCfnDeployCapability } from "./apply";
+import { createMockCloudExecutor } from "./__tests__/mock-cloud-executor";
+
+let dir: string;
+let template: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "cfn-shape-conformance-"));
+  template = join(dir, "stack.template.json");
+  writeFileSync(
+    template,
+    JSON.stringify({
+      Parameters: { SubnetId: { Type: "AWS::EC2::Subnet::Id" } },
+      Resources: {
+        Eni: { Type: "AWS::EC2::NetworkInterface", Properties: { SubnetId: { Ref: "SubnetId" }, Description: "d" } },
+        Q: { Type: "AWS::SQS::Queue", Properties: { QueueName: { "Fn::Sub": "q-${SubnetId}" } } },
+      },
+    }),
+  );
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+const ctx = { env: "local", component: "network" };
+
+const eni: CfnChange = {
+  action: "Modify",
+  logicalResourceId: "Eni",
+  resourceType: "AWS::EC2::NetworkInterface",
+  replacement: false,
+  replacementMode: "False",
+  details: ["SubnetId", "Description"],
+  drivers: [
+    { property: "SubnetId", changeSource: "ParameterReference", causingEntity: "SubnetId" },
+    { property: "Description", changeSource: "DirectModification" },
+  ],
+};
+const q: CfnChange = { action: "Add", logicalResourceId: "Q", resourceType: "AWS::SQS::Queue", replacement: false };
+const topic: CfnChange = { action: "Add", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false };
+
+/** The member previewed: `SubnetId` holds nothing yet, so the plan uses a stand-in. */
+async function preview() {
+  const mock = createMockCloudExecutor({ stacks: { net: { changes: [eni, q] } } });
+  const planned = await createCfnDeployCapability(mock.executor).plan!(
+    { ...ctx, unresolvedInputs: ["vpc.SubnetId"] },
+    { stack: "net", template, inputs: { SubnetId: undefined as never } },
+  );
+  return planned.shape;
+}
+
+/** The member planned again once the upstream applied, with the real change set `changes`. */
+async function real(changes: CfnChange[]) {
+  const mock = createMockCloudExecutor({ stacks: { net: { changes } } });
+  const planned = await createCfnDeployCapability(mock.executor).plan!(ctx, { stack: "net", template, inputs: { SubnetId: "subnet-1" }, onReplace: "allow" });
+  return planned.shape;
+}
+
+describe("cfn-deploy plan shape conformance (#4425)", () => {
+  it("passes", async () => {
+    const problems = await checkPlanShapeConformance({
+      lexicon: "aws",
+      preview,
+      fresh: () => real([eni, q]),
+      added: () => real([eni, q, topic]),
+      missing: () => real([q]),
+      replaced: () => real([{ ...eni, replacement: true, replacementMode: "True" }, q]),
+    });
+    expect(problems).toEqual([]);
+  });
+});

package/src/components/cloud-executor.ts

@@ -81,8 +81,8 @@ export interface CfnChangeSet {
   statusReason?: string;
   /** True the first time this stack is created (no prior stack exists). */
   isCreate: boolean;
-  /** The change set's type: CREATE for a stack that does not exist yet or was never executed, else UPDATE. */
-  changeSetType?: "CREATE" | "UPDATE";
+  /** The change set's type: CREATE for a stack that does not exist yet or was never executed, else UPDATE; IMPORT for an adoption (#4536). */
+  changeSetType?: "CREATE" | "UPDATE" | "IMPORT";
   /**
    * True when no stack existed before this change set, so CloudFormation made
    * an empty `REVIEW_IN_PROGRESS` stack to hold it. A plan that deletes the
@@ -99,6 +99,18 @@ export interface CfnCreateChangeSetArgs {
   parameters?: Record<string, string>;
 }
 
+/** One existing resource an IMPORT change set brings under a stack (#4536). */
+export interface CfnResourceToImport {
+  resourceType: string;
+  logicalResourceId: string;
+  /** The type's primary identifier properties and their values (`{ BucketName: "logs" }`). */
+  resourceIdentifier: Record<string, string>;
+}
+
+export interface CfnCreateImportChangeSetArgs extends CfnCreateChangeSetArgs {
+  resourcesToImport: CfnResourceToImport[];
+}
+
 export interface CfnExecuteChangeSetArgs {
   stackName: string;
   changeSetName: string;
@@ -107,11 +119,21 @@ export interface CfnExecuteChangeSetArgs {
 export interface CfnStackStatus {
   stackStatus: string;
   outputs: Record<string, string>;
+  /** The stack's exports by export name (#4466c): the output each is and its value. Absent when it exports nothing or the backend does not say. */
+  exports?: Record<string, { output: string; value: string }>;
 }
 
 export interface CloudFormationClient {
   /** Create (but do not execute) a changeset, returning its proposed changes for preview/safety checks. */
   createChangeSet(args: CfnCreateChangeSetArgs): Promise<CfnChangeSet>;
+  /**
+   * Create (but do not execute) an IMPORT change set that brings existing
+   * resources under the stack (#4536, chant's CloudFormation adoption). A
+   * stack that does not exist yet is created by it. No stack tags are sent:
+   * chant's markers are written by the UPDATE that follows. Optional: a
+   * client without it cannot adopt.
+   */
+  createImportChangeSet?(args: CfnCreateImportChangeSetArgs): Promise<CfnChangeSet>;
   /** Execute a previously created changeset. */
   executeChangeSet(args: CfnExecuteChangeSetArgs): Promise<void>;
   /** Delete a changeset without executing it (used when a safety policy blocks the apply). */
@@ -129,6 +151,12 @@ export interface CloudFormationClient {
    * empty stack, and the next CREATE change set reuses it.
    */
   deleteStackShell?(stackName: string): Promise<boolean>;
+  /**
+   * The stacks that import `exportName` now (`ListImports`, #4466c), sorted;
+   * empty when none does. Optional: without it, a plan cannot say whether a
+   * change to an export is in use, and refuses nothing.
+   */
+  listImports?(exportName: string): Promise<string[]>;
 }
 
 // ── ECS ──────────────────────────────────────────────────────────────────��─
@@ -577,6 +605,53 @@ const realCloudFormation: CloudFormationClient = {
       changes: await readCfnChanges(described, describeNested),
     };
   },
+  async createImportChangeSet(args) {
+    const changeSetName = `cs-import-${Date.now()}`;
+    const params = Object.entries(args.parameters ?? {})
+      .map(([k, v]) => `ParameterKey=${k},ParameterValue=${v}`)
+      .join(" ");
+    const paramFlag = params ? ` --parameters ${params}` : "";
+    let body = "";
+    try {
+      body = readFileSync(args.templatePath, "utf8");
+    } catch { /* unreadable template — create-change-set reports it */ }
+    const capabilities = awsDeployCapabilitiesForBody(body).join(" ");
+    const { existed } = await cfnChangeSetType(args.stackName);
+    const dir = mkdtempSync(join(tmpdir(), "chant-cfn-import-"));
+    try {
+      const resourcesFile = join(dir, "resources-to-import.json");
+      writeFileSync(
+        resourcesFile,
+        JSON.stringify(
+          args.resourcesToImport.map((r) => ({ ResourceType: r.resourceType, LogicalResourceId: r.logicalResourceId, ResourceIdentifier: r.resourceIdentifier })),
+        ),
+      );
+      await run(
+        `aws cloudformation create-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)} ` +
+          `--change-set-type IMPORT --resources-to-import file://${resourcesFile} ` +
+          `--template-body file://${args.templatePath} --capabilities ${capabilities}${paramFlag}`,
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+    await run(
+      `aws cloudformation wait change-set-create-complete --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)}`,
+    ).catch(() => undefined);
+    const { stdout } = await run(
+      `aws cloudformation describe-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)}`,
+    );
+    const described = JSON.parse(stdout) as DescribedCfnChangeSet;
+    return {
+      changeSetName,
+      stackName: args.stackName,
+      status: described.Status,
+      statusReason: described.StatusReason ?? undefined,
+      isCreate: false,
+      changeSetType: "IMPORT",
+      stackCreated: !existed,
+      changes: await readCfnChanges(described, async () => ({ Status: "CREATE_COMPLETE" })),
+    };
+  },
   async executeChangeSet(args) {
     await run(
       `aws cloudformation execute-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(args.changeSetName)}`,
@@ -590,12 +665,34 @@ const realCloudFormation: CloudFormationClient = {
   async describeStack(stackName) {
     const { stdout } = await run(`aws cloudformation describe-stacks --stack-name ${q(stackName)}`);
     const described = JSON.parse(stdout) as {
-      Stacks: Array<{ StackStatus: string; Outputs?: Array<{ OutputKey: string; OutputValue: string }> }>;
+      Stacks: Array<{ StackStatus: string; Outputs?: Array<{ OutputKey: string; OutputValue: string; ExportName?: string }> }>;
     };
     const stack = described.Stacks[0];
     const outputs: Record<string, string> = {};
-    for (const o of stack?.Outputs ?? []) outputs[o.OutputKey] = o.OutputValue;
-    return { stackStatus: stack?.StackStatus ?? "UNKNOWN", outputs };
+    const exports: Record<string, { output: string; value: string }> = {};
+    for (const o of stack?.Outputs ?? []) {
+      outputs[o.OutputKey] = o.OutputValue;
+      if (o.ExportName) exports[o.ExportName] = { output: o.OutputKey, value: o.OutputValue };
+    }
+    return { stackStatus: stack?.StackStatus ?? "UNKNOWN", outputs, ...(Object.keys(exports).length > 0 ? { exports } : {}) };
+  },
+  async listImports(exportName) {
+    const stacks: string[] = [];
+    let token: string | undefined;
+    do {
+      let stdout: string;
+      try {
+        ({ stdout } = await run(`aws cloudformation list-imports --export-name ${q(exportName)}${token ? ` --next-token ${q(token)}` : ""}`));
+      } catch (err) {
+        // CloudFormation answers an export nobody imports with an error, not an empty list.
+        if (/is not imported by any stack/i.test(err instanceof Error ? err.message : String(err))) return [];
+        throw err;
+      }
+      const page = JSON.parse(stdout) as { Imports?: string[]; NextToken?: string };
+      stacks.push(...(page.Imports ?? []));
+      token = page.NextToken;
+    } while (token);
+    return [...new Set(stacks)].sort();
   },
   async waitForStack(stackName, opts) {
     const intervalMs = opts?.intervalMs ?? 10_000;