@intentius/chant-lexicon-aws 0.124.50 → 0.124.52

package/src/components/apply.ts

@@ -24,6 +24,16 @@ import { readFileSync } from "node:fs";
 import type { Capability, CapabilityPlan, DeployContext, PlannedOutputs } from "@intentius/chant/components/capability";
 import type { ChangeSetEntry, ChangeSetHole, ChangeSetPart } from "@intentius/chant/change-set";
 import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+import {
+  normalizePlanShape,
+  PlanShapeMovedError,
+  planShapeDifferences,
+  planShapeDigest,
+  type PlanShape,
+  type PlanShapeArtifact,
+  type PlanShapeEntry,
+  type ShapeReplacement,
+} from "@intentius/chant/components/covered-round";
 import { defaultCloudExecutor, type CfnChange, type CfnChangeSet, type CloudExecutor } from "./cloud-executor";
 
 /** CloudFormation's wording when a change set has nothing to apply — the stack
@@ -65,8 +75,11 @@ export function cfnChangeReplaces(change: CfnChange): boolean {
  * replace, `Remove` a delete, `Import` an import that changes nothing else,
  * and `Dynamic` an update CloudFormation could not describe further.
  */
-export function cfnChangeEntry(member: string, change: CfnChange): ChangeSetEntry {
-  const attributes = [...new Set(change.details ?? [])].sort().map((path) => ({ path }));
+export function cfnChangeEntry(member: string, change: CfnChange, unknown: readonly string[] = []): ChangeSetEntry {
+  // A property an unknown input drives is known after apply (#4419); one the
+  // change set did not list (a create names no properties) is added for it.
+  const paths = [...new Set([...(change.details ?? []), ...unknown])].sort();
+  const attributes = paths.map((path) => (unknown.includes(path) ? { path, unknown: true as const } : { path }));
   // A change inside a nested stack (#3997) sits under the nested stacks'
   // logical ids, the way a terraform address sits under its module.
   const module = change.nestedStack?.length ? change.nestedStack.join("/") : undefined;
@@ -177,6 +190,8 @@ function cfnPlanDigest(
   input: CfnDeployInput,
   parameters: Record<string, string | null>,
   unresolved: string[],
+  /** The digest of the preview's shape (#4423), so an approval binds what the reviewer saw of a member planned before its inputs were known. */
+  preview?: string,
 ): string {
   return computePlanDigest("cfn-deploy-plan", {
     env: ctx.env,
@@ -185,6 +200,7 @@ function cfnPlanDigest(
     templateDigest: templateDigest(input.template),
     parameters,
     unresolved,
+    ...(preview ? { preview } : {}),
   });
 }
 
@@ -227,7 +243,7 @@ async function planCfnDeploy(executor: CloudExecutor, ctx: DeployContext, input:
     } else parameters[key] = typeof value === "string" ? value : JSON.stringify(value);
   }
   const unresolved = [...(ctx.unresolvedInputs ?? [])].sort();
-  const planDigest = cfnPlanDigest(ctx, stack, input, parameters, unresolved);
+  let planDigest = cfnPlanDigest(ctx, stack, input, parameters, unresolved);
   const member = (holes: ChangeSetHole[]): ChangeSetPart["member"] => ({
     member: stack,
     lexicon: "aws",
@@ -238,15 +254,25 @@ async function planCfnDeploy(executor: CloudExecutor, ctx: DeployContext, input:
   });
 
   if (unresolved.length > 0 || missing.length > 0) {
-    const reason =
-      unresolved.length > 0
-        ? `inputs from ${unresolved.join(", ")}; re-checked on apply`
-        : `inputs ${missing.sort().join(", ")} are known only at apply; re-checked on apply`;
-    return {
+    const hole = (why: string): CapabilityPlan => ({
       member: stack,
       planDigest,
-      changeSet: { member: member([{ address: stack, type: "AWS::CloudFormation::Stack", reason }]), entries: [] },
-    };
+      changeSet: { member: member([{ address: stack, type: "AWS::CloudFormation::Stack", reason: why }]), entries: [] },
+    });
+    const fallback =
+      unresolved.length > 0
+        ? `inputs from ${unresolved.join(", ")}; re-checked on apply`
+        : `inputs ${[...missing].sort().join(", ")} are known only at apply; re-checked on apply`;
+    // Which parameters are unknown: the inputs that hold nothing yet. When the
+    // upstream is unresolved but no input says which, nothing can be previewed.
+    if (missing.length === 0) return hole(fallback);
+    const preview = await previewCfnDeploy(executor, stack, input, [...missing].sort(), unresolved.length > 0 ? unresolved : undefined);
+    if (typeof preview === "string") return hole(`${fallback}; no preview: ${preview}`);
+    const { entries, shape, outputs } = preview;
+    const artifact: CfnShapeArtifact = { kind: "cfn-deploy-shape", member: stack, shape, digest: planShapeDigest(shape) };
+    // The preview's shape enters the digest (#4423); `member` reads it when called below.
+    planDigest = cfnPlanDigest(ctx, stack, input, parameters, unresolved, artifact.digest);
+    return { member: stack, planDigest, artifact, shape, changeSet: { member: member([]), entries }, ...(outputs ? { outputs } : {}) };
   }
 
   const changeSet = await executor.cloudformation.createChangeSet({
@@ -271,8 +297,184 @@ async function planCfnDeploy(executor: CloudExecutor, ctx: DeployContext, input:
     if (blocked.length > 0 && (input.onReplace ?? "block") === "block") throw new CfnReplacementBlockedError(stack, blocked);
     const entries = changeSet.changes.map((c) => cfnChangeEntry(stack, c));
     const artifact: CfnPlanArtifact = { kind: "cfn-deploy-plan", stack, changesDigest: cfnChangesDigest(stack, changeSet) };
-    const outputs = changeSet.stackCreated ? undefined : await plannedStackOutputs(executor, stack, input.template, changeSet.changes);
-    return { member: stack, planDigest, artifact, changeSet: { member: member([]), entries }, ...(outputs ? { outputs } : {}) };
+    const outputs = changeSet.stackCreated ? undefined : await plannedStackOutputs(executor, stack, input.template, changeSet.changes, knownParameters(parameters));
+    // The real change set's shape, with the replacement CloudFormation reports,
+    // for a round that checks it against a preview (#4419).
+    const shape = cfnPlanShape(stack, changeSet, []);
+    return { member: stack, planDigest, artifact, shape, changeSet: { member: member([]), entries }, ...(outputs ? { outputs } : {}) };
+  } finally {
+    await cleanUpPlanChangeSet(executor, changeSet);
+  }
+}
+
+// ── preview of a member whose inputs are unknown (#4419) ────────────────────
+
+/** What a previewed member hands `run`: the shape its change set had against stand-in values. */
+export interface CfnShapeArtifact extends PlanShapeArtifact {
+  kind: "cfn-deploy-shape";
+}
+
+function isCfnShapeArtifact(value: unknown): value is CfnShapeArtifact {
+  const v = value as Partial<CfnShapeArtifact> | undefined;
+  return v?.kind === "cfn-deploy-shape" && typeof v.digest === "string" && typeof v.shape === "object" && v.shape !== null;
+}
+
+/** The marker every stand-in carries, so a reader of a change set can tell it from a real value. */
+export const CFN_UNKNOWN_MARK = "known-after-apply";
+
+const ID_PREFIX: Record<string, string> = {
+  "AWS::EC2::Subnet::Id": "subnet",
+  "AWS::EC2::VPC::Id": "vpc",
+  "AWS::EC2::SecurityGroup::Id": "sg",
+  "AWS::EC2::Instance::Id": "i",
+  "AWS::EC2::Image::Id": "ami",
+  "AWS::EC2::Volume::Id": "vol",
+};
+
+/**
+ * A stand-in for a parameter whose value is not known yet: valid for the
+ * parameter's type and recognisable. An EC2 id type gets the id's prefix
+ * (`subnet-00000000known-after-apply`), a number gets 0, anything else gets
+ * `known-after-apply`. Real CloudFormation checks the AWS-specific types
+ * against the account and refuses an id that does not exist; the preview
+ * then falls back to a hole. Floci does not check.
+ */
+export function cfnPlaceholder(type: string | undefined): string {
+  if (type && ID_PREFIX[type]) return `${ID_PREFIX[type]}-00000000${CFN_UNKNOWN_MARK}`;
+  if (type === "Number") return "0";
+  if (type?.startsWith("AWS::SSM::Parameter::Value<")) return `/${CFN_UNKNOWN_MARK}`;
+  return CFN_UNKNOWN_MARK;
+}
+
+interface TemplateFacts {
+  parameterTypes: Record<string, string>;
+  /** Per logical id, the top-level properties whose value reads one of the keys. */
+  driven: Map<string, Set<string>>;
+}
+
+function readsParameter(value: unknown, key: string): boolean {
+  if (typeof value === "string") return false;
+  if (Array.isArray(value)) return value.some((v) => readsParameter(v, key));
+  if (value && typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    if (obj.Ref === key) return true;
+    const sub = obj["Fn::Sub"];
+    const text = typeof sub === "string" ? sub : Array.isArray(sub) && typeof sub[0] === "string" ? sub[0] : undefined;
+    if (text !== undefined && (text.includes("${" + key + "}") || text.includes("${" + key + "."))) return true;
+    return Object.values(obj).some((v) => readsParameter(v, key));
+  }
+  return false;
+}
+
+/** The parameter types and the properties that read `keys`, from the template. A template that cannot be read gives no facts. */
+function templateFacts(path: string, keys: string[]): TemplateFacts {
+  const facts: TemplateFacts = { parameterTypes: {}, driven: new Map() };
+  try {
+    const t = JSON.parse(readFileSync(path, "utf8")) as {
+      Parameters?: Record<string, { Type?: string }>;
+      Resources?: Record<string, { Properties?: Record<string, unknown> }>;
+    };
+    for (const k of keys) if (t.Parameters?.[k]?.Type) facts.parameterTypes[k] = t.Parameters[k].Type!;
+    for (const [id, r] of Object.entries(t.Resources ?? {})) {
+      for (const [prop, value] of Object.entries(r.Properties ?? {})) {
+        if (keys.some((k) => readsParameter(value, k))) (facts.driven.get(id) ?? facts.driven.set(id, new Set()).get(id)!).add(prop);
+      }
+    }
+  } catch {
+    /* unreadable or not JSON: the change set reports why, and no property is attributed */
+  }
+  return facts;
+}
+
+/** The properties of one change that the unknown parameters drive. */
+function drivenProperties(change: CfnChange, keys: string[], facts: TemplateFacts): string[] {
+  const out = new Set<string>();
+  for (const d of change.drivers ?? []) {
+    if (d.changeSource === "ParameterReference" && d.causingEntity && keys.some((k) => d.causingEntity === k || d.causingEntity!.startsWith(`${k}.`))) {
+      out.add(d.property);
+    }
+  }
+  const scanned = facts.driven.get(change.logicalResourceId);
+  if (scanned && change.action !== "Remove") {
+    const listed = change.details ?? [];
+    for (const p of scanned) if (change.action === "Add" || listed.length === 0 || listed.includes(p)) out.add(p);
+  }
+  return [...out].sort();
+}
+
+function shapeReplacement(change: CfnChange): ShapeReplacement {
+  if (change.replacementMode === "True" || change.replacement) return "true";
+  return change.replacementMode === "Conditional" ? "conditional" : "false";
+}
+
+/**
+ * A change set's shape: each change's resource, action, replacement and
+ * properties, with the ones the `unknown` parameters drive marked. `unknown`
+ * is empty for the change set made against real values. `refs` are the
+ * inputs the shape names as unknown (`<component>.<output>`), the parameters
+ * themselves when nothing says better.
+ */
+export function cfnPlanShape(stack: string, changeSet: CfnChangeSet, unknown: string[], templatePath?: string, refs: string[] = unknown): PlanShape {
+  const facts = unknown.length > 0 && templatePath ? templateFacts(templatePath, unknown) : { parameterTypes: {}, driven: new Map() };
+  const entries: PlanShapeEntry[] = isNoopChangeSet(changeSet)
+    ? []
+    : changeSet.changes.map((c) => {
+        const e = cfnChangeEntry(stack, c);
+        return {
+          logicalId: e.address,
+          action: e.action,
+          replacement: shapeReplacement(c),
+          type: c.resourceType,
+          properties: [...new Set(c.details ?? [])],
+          unknown: drivenProperties(c, unknown, facts),
+        };
+      });
+  return normalizePlanShape({ member: stack, unknownInputs: refs, entries });
+}
+
+/**
+ * Preview a stack whose parameters `unknown` are not known yet: create its
+ * change set with a stand-in for each, read the changes into entries that
+ * mark the properties those parameters drive as known after apply, take the
+ * shape, and delete the change set. Returns why instead when CloudFormation
+ * would not make the change set (real CloudFormation refuses an id that does
+ * not exist), so the caller plans a hole.
+ *
+ * Floci accepts a change set that real CloudFormation refuses (a missing
+ * export, an id that does not exist), reports `Parameters: null`, and says
+ * `Replacement: False` for a change that replaces. So a cross-stack value
+ * goes through a parameter here, never an export, and the replacement a
+ * preview reports is whatever the backend says; the shape check at apply
+ * compares like with like.
+ */
+async function previewCfnDeploy(
+  executor: CloudExecutor,
+  stack: string,
+  input: CfnDeployInput,
+  unknown: string[],
+  refs: string[] = unknown,
+): Promise<{ entries: ChangeSetEntry[]; shape: PlanShape; outputs?: PlannedOutputs } | string> {
+  const facts = templateFacts(input.template, unknown);
+  const parameters: Record<string, string> = { ...(flattenCfnInputs(input) ?? {}) };
+  for (const k of unknown) parameters[k] = cfnPlaceholder(facts.parameterTypes[k]);
+  let changeSet: CfnChangeSet;
+  try {
+    changeSet = await executor.cloudformation.createChangeSet({ stackName: stack, templatePath: input.template, parameters });
+  } catch (err) {
+    return `CloudFormation refused the change set with stand-in values: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  try {
+    if (changeSet.status === "FAILED" && !isNoopChangeSet(changeSet)) {
+      return `CloudFormation could not create the change set with stand-in values${changeSet.statusReason ? `: ${changeSet.statusReason}` : ""}`;
+    }
+    const noop = isNoopChangeSet(changeSet);
+    const entries = noop ? [] : changeSet.changes.map((c) => cfnChangeEntry(stack, c, drivenProperties(c, unknown, facts)));
+    // What the stack's outputs will be, for the members that read them: an
+    // output that reads one of the unknown parameters is unknown, one that
+    // reads a known parameter or states its value is not (#4419).
+    const given = Object.fromEntries(Object.entries(parameters).filter(([k]) => !unknown.includes(k)));
+    const outputs = noop || changeSet.stackCreated ? undefined : await plannedStackOutputs(executor, stack, input.template, changeSet.changes, given);
+    return { entries, shape: cfnPlanShape(stack, changeSet, unknown, input.template, refs), ...(outputs ? { outputs } : {}) };
   } finally {
     await cleanUpPlanChangeSet(executor, changeSet);
   }
@@ -312,11 +514,17 @@ async function standingOutputs(executor: CloudExecutor, stack: string): Promise<
  * What the plan says of the stack's outputs once `changes` apply: none to
  * say for a template with no `Outputs`, which needs no `DescribeStacks`.
  */
-async function plannedStackOutputs(executor: CloudExecutor, stack: string, templatePath: string, changes: readonly CfnChange[]): Promise<PlannedOutputs | undefined> {
+async function plannedStackOutputs(
+  executor: CloudExecutor,
+  stack: string,
+  templatePath: string,
+  changes: readonly CfnChange[],
+  parameters: Record<string, string> = {},
+): Promise<PlannedOutputs | undefined> {
   const template = readTemplate(templatePath) as { Outputs?: Record<string, unknown> } | undefined;
   if (!template || typeof template !== "object") return undefined;
   if (Object.keys(template.Outputs ?? {}).length === 0) return { known: {}, unknown: [] };
-  return cfnPlannedOutputs(template, changes, await standingOutputs(executor, stack));
+  return cfnPlannedOutputs(template, changes, await standingOutputs(executor, stack), parameters);
 }
 
 /** The template at `path` as JSON, or `undefined` when it cannot be read or parsed here. */
@@ -386,9 +594,21 @@ function valueReads(value: unknown): { ids: Set<string>; opaque: boolean } {
  * `Dynamic`, no replacement, no change in a nested stack under it). One
  * that reads a parameter, an import or a condition, one the stack does not
  * have yet, and every output of a template this cannot read, is unknown.
+ *
+ * Two kinds of output need no standing value. An output whose `Value` is a
+ * plain string is known at that string, changed or new: the template says it.
+ * An output that is a `Ref` to a parameter the plan was given a value for is
+ * known at that value (`given`, the inputs of this plan). Both are what
+ * the stack's outputs will be, whatever they are now.
+ *
  * `undefined` when there is no template or no standing stack to read from.
  */
-export function cfnPlannedOutputs(template: unknown, changes: readonly CfnChange[], standing: Record<string, string> | undefined): PlannedOutputs | undefined {
+export function cfnPlannedOutputs(
+  template: unknown,
+  changes: readonly CfnChange[],
+  standing: Record<string, string> | undefined,
+  given: Record<string, string> = {},
+): PlannedOutputs | undefined {
   if (!standing || template === null || typeof template !== "object") return undefined;
   const t = template as { Outputs?: Record<string, { Value?: unknown; Condition?: unknown }>; Parameters?: Record<string, unknown> };
   const parameters = new Set(Object.keys(t.Parameters ?? {}));
@@ -401,6 +621,11 @@ export function cfnPlannedOutputs(template: unknown, changes: readonly CfnChange
   const known: Record<string, unknown> = {};
   const unknown: string[] = [];
   for (const [name, output] of Object.entries(t.Outputs ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+    const stated = statedOutput(output, given, t.Parameters);
+    if (stated !== undefined) {
+      known[name] = stated;
+      continue;
+    }
     const { ids, opaque } = valueReads(output?.Value);
     const stays =
       !opaque && output?.Condition === undefined && name in standing &&
@@ -411,6 +636,32 @@ export function cfnPlannedOutputs(template: unknown, changes: readonly CfnChange
   return { known, unknown };
 }
 
+/** The inputs a plan was given a value for: every parameter that is not null. */
+function knownParameters(parameters: Record<string, string | null>): Record<string, string> {
+  return Object.fromEntries(Object.entries(parameters).filter((e): e is [string, string] => e[1] !== null));
+}
+
+/**
+ * What an output's `Value` says outright: a plain string, or a `Ref` to a
+ * parameter this plan has a value for. `undefined` for anything that reads a
+ * resource, an import or a condition, which the standing outputs speak for.
+ */
+function statedOutput(
+  output: { Value?: unknown; Condition?: unknown } | undefined,
+  parameters: Record<string, string>,
+  declared: Record<string, unknown> | undefined,
+): string | undefined {
+  if (output?.Condition !== undefined) return undefined;
+  const value = output?.Value;
+  if (typeof value === "string") return value;
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>);
+    const [key, arg] = entries[0] ?? [];
+    if (entries.length === 1 && key === "Ref" && typeof arg === "string" && declared && arg in declared && arg in parameters) return parameters[arg];
+  }
+  return undefined;
+}
+
 /** Whether a CloudFormation error says the stack does not exist. */
 const STACK_MISSING = /does not exist/i;
 
@@ -530,7 +781,16 @@ export function createCfnDeployCapability(
       // set that proposes the same changes. Anything else means the stack,
       // the template or the parameters moved since the plan.
       const planned = ctx.plans?.[stack];
-      if (isCfnPlanArtifact(planned)) {
+      if (isCfnShapeArtifact(planned)) {
+        // A member planned before its inputs were known (#4419): the change
+        // set made now is against the real values. It must have the shape the
+        // preview had, differing only in what the unknown inputs drive.
+        const differences = planShapeDifferences(planned.shape, cfnPlanShape(stack, changeSet, []));
+        if (differences.length > 0) {
+          await cleanUpPlanChangeSet(executor, changeSet);
+          throw new PlanShapeMovedError(stack, differences);
+        }
+      } else if (isCfnPlanArtifact(planned)) {
         const now = cfnChangesDigest(stack, changeSet);
         if (now !== planned.changesDigest) {
           await cleanUpPlanChangeSet(executor, changeSet);

package/src/components/cfn-plan-floci.e2e.test.ts

@@ -11,6 +11,7 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { CfnPlanMovedError, createCfnDeployCapability } from "./apply";
+import { PlanShapeMovedError } from "@intentius/chant/components/covered-round";
 import { defaultCloudExecutor } from "./cloud-executor";
 
 const endpoint = process.env.CHANT_FLOCI_ENDPOINT;
@@ -74,3 +75,55 @@ describe.skipIf(!endpoint)("cfn-deploy plan against Floci (#3997)", () => {
     expect(changeSets()).toEqual([]);
   }, 600_000); // each `aws` call takes seconds, and a plan or a run makes several
 });
+
+describe.skipIf(!endpoint)("cfn-deploy preview against Floci (#4423)", () => {
+  const stack = `zz-4419-prev-${process.pid}`;
+  const ctx = { env: "local", component: stack, unresolvedInputs: ["network"] };
+  const saved = { ...process.env };
+  let dir: string;
+  let template: string;
+  const aws = (...args: string[]): string => execFileSync("aws", ["--endpoint-url", endpoint!, ...args], { encoding: "utf8" });
+  const open = (): string[] =>
+    ((JSON.parse(aws("cloudformation", "list-change-sets", "--stack-name", stack)) as { Summaries?: Array<{ ChangeSetName: string; ExecutionStatus?: string }> }).Summaries ?? [])
+      .filter((c) => c.ExecutionStatus !== "EXECUTE_COMPLETE")
+      .map((c) => c.ChangeSetName);
+  const queue = (extra: Record<string, unknown> = {}) => ({
+    Parameters: { Prefix: { Type: "String" } },
+    Resources: { Queue: { Type: "AWS::SQS::Queue", Properties: { QueueName: { "Fn::Sub": "${Prefix}-q" } } }, ...extra },
+  });
+  const input = (prefix?: string) => ({ stack, template, inputs: { Prefix: prefix as never } });
+
+  beforeAll(() => {
+    Object.assign(process.env, { AWS_ENDPOINT_URL: endpoint, AWS_ACCESS_KEY_ID: "test", AWS_SECRET_ACCESS_KEY: "test", AWS_REGION: "us-east-1" });
+    dir = mkdtempSync(join(tmpdir(), "cfn-preview-floci-"));
+    template = join(dir, "stack.template.json");
+  });
+
+  afterAll(() => {
+    try {
+      aws("cloudformation", "delete-stack", "--stack-name", stack);
+    } catch { /* never created */ }
+    process.env = saved;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("previews a stack that does not exist yet, leaves nothing behind, refuses a real change set that adds a resource, and executes one with the previewed shape", async () => {
+    const capability = createCfnDeployCapability(defaultCloudExecutor());
+    writeFileSync(template, JSON.stringify(queue()));
+    const planned = await capability.plan!(ctx, input());
+    expect(planned.artifact).toMatchObject({ kind: "cfn-deploy-shape" });
+    expect(planned.changeSet!.entries.map((e) => [e.address, e.action])).toEqual([["Queue", "create"]]);
+    expect(open()).toEqual([]);
+    await expect(capability.outputs!(ctx, { stack, template })).resolves.toEqual({});
+    // The same template and inputs plan to the same digest.
+    expect((await capability.plan!(ctx, input())).planDigest).toBe(planned.planDigest);
+
+    writeFileSync(template, JSON.stringify(queue({ Extra: { Type: "AWS::SQS::Queue" } })));
+    await expect(capability.run({ ...ctx, plans: { [stack]: planned.artifact } }, input("p"))).rejects.toBeInstanceOf(PlanShapeMovedError);
+    expect(open()).toEqual([]);
+
+    writeFileSync(template, JSON.stringify(queue()));
+    const done = await capability.run({ ...ctx, plans: { [stack]: planned.artifact } }, input("p"));
+    expect(done.stackStatus).toBe("CREATE_COMPLETE");
+  }, 600_000);
+});