@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/op-wave-step.test.ts

@@ -0,0 +1,109 @@
+/**
+ * The terraform side of op waves through capabilities (#4545): lock
+ * timeouts, choudoufu cone plans, reads from another root's state and the
+ * cost hold preset, moved here from terragucci's wave callbacks.
+ */
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { DEFAULT_LOCK_TIMEOUT, isLockTimeout, lockTimeoutArgs } from "./lock-timeout";
+import { coneArgs, conePlanDigest, coneRecordPath, coneText, readPlanCone } from "./cone";
+import { atmosStateReads, fillStateReads, readOutputValue, stateReadsProblems, waitingReadsReason } from "./state-reads";
+import { INFRACOST_ARGV, terraformCostHold } from "./cost-hold";
+import { terraformApplyCommand, terraformPlanCommand } from "./op/activities/terraform";
+
+describe("lock timeout (#4545)", () => {
+  test("adds -lock-timeout unless the job sets one", () => {
+    expect(lockTimeoutArgs("plan", DEFAULT_LOCK_TIMEOUT, {})).toEqual(["-lock-timeout=5m"]);
+    expect(lockTimeoutArgs("apply", "30s", { TF_CLI_ARGS: "-no-color" })).toEqual(["-lock-timeout=30s"]);
+    expect(lockTimeoutArgs("plan", "5m", { TF_CLI_ARGS_plan: "-lock-timeout=1m" })).toEqual([]);
+    expect(lockTimeoutArgs("apply", "5m", { TF_CLI_ARGS: "--lock-timeout 2m" })).toEqual([]);
+    expect(lockTimeoutArgs("plan", false, {})).toEqual([]);
+    expect(() => lockTimeoutArgs("plan", "five", {})).toThrow(/not a duration/);
+    expect(isLockTimeout("1h30m")).toBe(true);
+  });
+
+  test("the plan and apply commands carry the extra flags", () => {
+    expect(terraformPlanCommand({ binary: "tofu", planFile: "chant.tfplan", extra: ["-cone=origin/main", "-lock-timeout=5m"] })).toBe(
+      "tofu plan -input=false -detailed-exitcode -cone=origin/main -lock-timeout=5m -out=chant.tfplan",
+    );
+    expect(terraformApplyCommand({ binary: "tofu", planFile: "chant.tfplan", extra: ["-lock-timeout=5m"] })).toBe("tofu apply -input=false -lock-timeout=5m chant.tfplan");
+    expect(terraformApplyCommand({ binary: "tofu", planFile: "chant.tfplan" })).toBe("tofu apply -input=false chant.tfplan");
+  });
+});
+
+describe("cone plans (#4545)", () => {
+  test("only choudoufu on a live root, and never beside -target or -destroy", () => {
+    expect(coneArgs("choudoufu", "origin/main", [], true)).toEqual(["-cone=origin/main"]);
+    expect(coneArgs("/usr/local/bin/choudoufu", "origin/main", [], true)).toEqual(["-cone=origin/main"]);
+    expect(coneArgs("tofu", "origin/main", [], true)).toEqual([]);
+    expect(coneArgs("choudoufu", "origin/main", [], false)).toEqual([]);
+    expect(coneArgs("choudoufu", "origin/main", ["-target"], true)).toEqual([]);
+    expect(coneArgs("choudoufu", undefined, [], true)).toEqual([]);
+  });
+
+  test("reads the record beside the plan, or the guard's fallback", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cone-"));
+    const plan = join(dir, "chant.tfplan");
+    writeFileSync(coneRecordPath(plan), JSON.stringify({ base: "origin/main", base_sha: "abc", targets: ["b.x", "a.y"] }));
+    const cone = readPlanCone("Warning: Cone plan\n\nThis plan covers the cone: 2 of the estate's 40 blocks\n\nPlan: 1 to add", plan, "origin/main");
+    expect(cone).toEqual({ base: "origin/main", blocks: 2, of: 40, record: { base: "origin/main", base_sha: "abc", targets: ["a.y", "b.x"] } });
+    expect(coneText(cone)).toBe("the cone of the change since origin/main, 2 of the estate's 40 blocks");
+    const fell = readPlanCone("Warning: Cone plan fell back to a full plan\n\nThis plan covers the whole estate (guard lockfile): the lock file changed.\n", plan, "origin/main");
+    expect(fell).toEqual({ base: "origin/main", fallback: { kind: "lockfile", reason: "the lock file changed" } });
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("the cone's targets join the digest; a full plan keeps its own", () => {
+    const d = `sha256:${"1".repeat(64)}`;
+    expect(conePlanDigest(d, undefined)).toBe(d);
+    expect(conePlanDigest(d, { base: "origin/main", fallback: { kind: "x", reason: "y" } })).toBe(d);
+    const a = conePlanDigest(d, { base: "origin/main", record: { base: "origin/main", base_sha: "", targets: ["a"] } });
+    const b = conePlanDigest(d, { base: "origin/main", record: { base: "origin/main", base_sha: "", targets: ["b"] } });
+    expect(a).not.toBe(d);
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("reads from another root's state (#4545)", () => {
+  test("fills each read once per upstream, and waits on a missing output", async () => {
+    let reads = 0;
+    const filled = await fillStateReads(
+      [
+        { var: "vpc_id", root: "network", output: ["vpc", "id"] },
+        { var: "subnets", root: "network", output: ["subnets"] },
+        { var: "db", root: "data", output: ["endpoint"] },
+      ],
+      async (root) => {
+        reads++;
+        return root === "network" ? { vpc: { id: "vpc-1" }, subnets: ["a", "b"] } : {};
+      },
+    );
+    expect(reads).toBe(2);
+    expect(filled.vars).toEqual({ vpc_id: "vpc-1", subnets: ["a", "b"] });
+    expect(filled.waiting.map((w) => w.why)).toEqual(["has no state yet"]);
+    expect(waitingReadsReason(filled.waiting)).toBe("not planned: it reads db from data, which has no state yet; apply data first");
+  });
+
+  test("a state that cannot be read is an error, not a wait", async () => {
+    const filled = await fillStateReads([{ var: "x", root: "up", output: ["x"] }], async () => {
+      throw new Error("init failed");
+    });
+    expect(filled.errors).toEqual(["it reads x from up, whose state could not be read: init failed"]);
+  });
+
+  test("checks the reads, reads a nested output, and maps Atmos edges", () => {
+    expect(stateReadsProblems([{ var: "a", root: "r", output: ["o"] }, { var: "a", root: "", output: [] }])).toHaveLength(3);
+    expect(readOutputValue({ o: { k: 1 } }, ["o", "k"])).toEqual({ value: 1 });
+    expect(readOutputValue({ o: { k: 1 } }, ["o", "j"])).toBeUndefined();
+    expect(atmosStateReads({ reads: [{ var: "v", upstream: "dev/vpc", output: ["id"], function: "!terraform.state vpc id" }] }, (u) => u.replace("/", "-"))).toEqual([{ var: "v", root: "dev-vpc", output: ["id"] }]);
+  });
+});
+
+describe("cost hold preset (#4545)", () => {
+  test("prices each root's plan document with infracost", () => {
+    expect(terraformCostHold({ approveAbove: 100 })).toEqual({ command: [...INFRACOST_ARGV], approveAbove: 100, format: "infracost" });
+    expect(() => terraformCostHold({ approveAbove: 1, command: ["infracost"] })).toThrow(/\{planJson\}/);
+  });
+});

package/src/pin/__fixtures__/consumers/live/dev/main.tf

@@ -0,0 +1,4 @@
+module "vpc" {
+  source  = "REGISTRY.acme.dev/acme/vpc/aws"
+  version = "v2.0.0"
+}

package/src/pin/__fixtures__/consumers/live/prod/main.tf

@@ -0,0 +1,21 @@
+module "vpc" {
+  source  = "registry.acme.dev/acme/vpc/aws"
+  version = "1.0.0"
+}
+
+module "eks" {
+  source  = "acme/eks/aws"
+  version = "~> 2.0"
+}
+
+module "net" {
+  source = "git::https://git.acme.dev/acme/net.git?ref=v1.2.0"
+}
+
+module "cache" {
+  source = "oci://registry.acme.dev/modules/cache?tag=3.1.0"
+}
+
+module "local" {
+  source = "./modules/local"
+}

package/src/pin/__fixtures__/consumers/units/vpc/terragrunt.hcl

@@ -0,0 +1,7 @@
+terraform {
+  source = "tfr://registry.acme.dev/acme/vpc/aws?version=1.1.0"
+}
+
+inputs = {
+  cidr = "10.0.0.0/16"
+}

package/src/pin/bundle.test.ts

@@ -38,6 +38,8 @@ describe("the pin bundle", () => {
       expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
     }
     expect(inputs.map((i) => i.replace(/^.*?(packages|lexicons)\//, "$1/")).sort()).toEqual([
+      // The one config-file lister (chant#4457): node built-ins only, kept apart from the HCL parser.
+      "lexicons/terraform/src/hcl/files.ts",
       "lexicons/terraform/src/pin/edit.ts",
       "lexicons/terraform/src/pin/forge.ts",
       "lexicons/terraform/src/pin/index.ts",

package/src/pin/consumers.test.ts

@@ -0,0 +1,57 @@
+/**
+ * The consumer scan (chant#4599): registry, git ref and OCI tag pins, a
+ * constraint left unpinned, a Terragrunt unit's `terraform { source }`, and
+ * local calls left out, all read from source files.
+ */
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { isLocalSource, moduleConsumers, normalizeModuleSource } from "./consumers";
+
+const REPO = join(import.meta.dirname, "__fixtures__", "consumers");
+
+describe("moduleConsumers", () => {
+  test("lists every published module call in the roots, sorted", async () => {
+    const calls = await moduleConsumers(REPO, ["live/prod", "live/dev", "units/vpc"]);
+    expect(calls.map((c) => [c.root, c.address, c.module, c.pin])).toEqual([
+      ["live/dev", "module.vpc", "registry.acme.dev/acme/vpc/aws", "v2.0.0"],
+      ["live/prod", "module.cache", "oci://registry.acme.dev/modules/cache", "3.1.0"],
+      ["live/prod", "module.eks", "registry.terraform.io/acme/eks/aws", null],
+      ["live/prod", "module.net", "git::https://git.acme.dev/acme/net.git", "v1.2.0"],
+      ["live/prod", "module.vpc", "registry.acme.dev/acme/vpc/aws", "1.0.0"],
+      ["units/vpc", "terragrunt.terraform", "registry.acme.dev/acme/vpc/aws", "1.1.0"],
+    ]);
+  });
+
+  test("keeps where each pin sits and why a call has none", async () => {
+    const calls = await moduleConsumers(REPO, ["live/prod", "units/vpc"]);
+    const by = (a: string, root = "live/prod") => calls.find((c) => c.address === a && c.root === root)!;
+    expect(by("module.vpc")).toMatchObject({ kind: "terraform", file: "live/prod/main.tf", at: "version", source: "registry.acme.dev/acme/vpc/aws" });
+    expect(by("module.net")).toMatchObject({ at: "source", param: "ref" });
+    expect(by("module.cache")).toMatchObject({ at: "source", param: "tag" });
+    expect(by("module.eks").unpinned).toContain("constraint");
+    expect(by("terragrunt.terraform", "units/vpc")).toMatchObject({ kind: "terragrunt", file: "units/vpc/terragrunt.hcl", at: "source", param: "version" });
+  });
+
+  test("leaves local calls out", async () => {
+    const calls = await moduleConsumers(REPO, ["live/prod"]);
+    expect(calls.find((c) => c.address === "module.local")).toBeUndefined();
+    expect(isLocalSource("./modules/local")).toBe(true);
+    expect(isLocalSource("../shared")).toBe(true);
+    expect(isLocalSource("acme/vpc/aws")).toBe(false);
+  });
+});
+
+describe("normalizeModuleSource", () => {
+  test.each([
+    ["acme/vpc/aws", "registry.terraform.io/acme/vpc/aws"],
+    ["acme/vpc/aws//modules/x", "registry.terraform.io/acme/vpc/aws//modules/x"],
+    ["Registry.Acme.dev/acme/vpc/aws", "registry.acme.dev/acme/vpc/aws"],
+    ["tfr:///terraform-aws-modules/vpc/aws", "registry.terraform.io/terraform-aws-modules/vpc/aws"],
+    ["tfr://registry.acme.dev/acme/vpc/aws", "registry.acme.dev/acme/vpc/aws"],
+    ["github.com/acme/vpc", "github.com/acme/vpc"],
+    ["git::https://git.acme.dev/acme/net.git", "git::https://git.acme.dev/acme/net.git"],
+    ["oci://registry.acme.dev/modules/cache", "oci://registry.acme.dev/modules/cache"],
+  ])("%s is %s", (from, to) => {
+    expect(normalizeModuleSource(from)).toBe(to);
+  });
+});

package/src/pin/consumers.ts

@@ -0,0 +1,95 @@
+/**
+ * Where a repo calls its modules (chant#4599, terragucci#1289 bundle B): one
+ * entry per module call in the roots given, Terragrunt units included, read
+ * from the source files with chant's HCL parse and never from a plan, so the
+ * scan runs in a check job before anything is planned.
+ *
+ * Each call carries its root, file and block path, the source as written,
+ * the module it names with the pin taken out and normalised
+ * ({@link normalizeModuleSource}), and the pin `readModulePin` (./source.ts)
+ * reads. A local call (`./`, `../`) names no published module and is left
+ * out. The release catalog lists these as a version's consumers, and
+ * `deprecatedPins` (../registry/deprecated.ts) checks them against it.
+ *
+ * The `terragucci_module_pin` metric keeps reading the plan; this is the
+ * source-side view of the same calls. The normal form is chant#3924's
+ * (../registry/source-forms.ts), shared with `usedSources` (../sources.ts).
+ */
+import { join, relative } from "node:path";
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import { MODULE_TYPE, TERRAGRUNT_SOURCE_TYPE, parseTerraformRootDir, type TerraformEntity } from "../hcl/parse";
+import { normalizeModuleSource, PUBLIC_REGISTRY_HOST } from "../registry/source-forms";
+import { readModulePin, type ModuleCallPin } from "./source";
+
+export { normalizeModuleSource, PUBLIC_REGISTRY_HOST };
+
+/** One module call in a consuming repo. */
+export interface ModuleConsumer {
+  /** The root (or Terragrunt unit) directory, from the repo's top, `/`-separated. */
+  root: string;
+  /** The file holding the call, from the repo's top. */
+  file: string;
+  /** The block: `module.<name>`, or `terragrunt.terraform` for a unit's source. */
+  address: string;
+  /** `terraform` for a module block, `terragrunt` for a unit's `terraform { source }`. */
+  kind: "terraform" | "terragrunt";
+  /** The `source` as written. */
+  source: string;
+  /** The module the call names: the source with the pin taken out, normalised. */
+  module: string;
+  /** The pinned version, tag, digest or ref, or null when the call pins none. */
+  pin: string | null;
+  /** Where the pin is, as `readModulePin` reads it. */
+  at: ModuleCallPin["at"];
+  param?: ModuleCallPin["param"];
+  /** Why there is no pin, when `pin` is null. */
+  unpinned?: string;
+}
+
+/** A source names a local directory, not a published module. */
+export function isLocalSource(source: string): boolean {
+  return source.startsWith("./") || source.startsWith("../");
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+/**
+ * Every module call in `roots` (directories from `repo`), sorted by root,
+ * file and address. A root whose files cannot be parsed throws, naming the
+ * root, so a check job fails loudly instead of listing fewer consumers.
+ */
+export async function moduleConsumers(repo: string, roots: readonly string[], parser?: Hcl2Json): Promise<ModuleConsumer[]> {
+  const out: ModuleConsumer[] = [];
+  for (const root of [...new Set(roots)].sort()) {
+    const dir = join(repo, root);
+    const rel = relative(repo, dir).split("\\").join("/") || ".";
+    let entities: TerraformEntity[];
+    try {
+      entities = [...(await parseTerraformRootDir(dir, "consumers", parser)).values()] as TerraformEntity[];
+    } catch (e) {
+      throw new Error(`${rel}: ${(e as Error).message}`);
+    }
+    for (const e of entities) {
+      if (e.entityType !== MODULE_TYPE && e.entityType !== TERRAGRUNT_SOURCE_TYPE) continue;
+      const source = str(e.props.body.source);
+      if (source === undefined || isLocalSource(source)) continue;
+      const version = e.entityType === MODULE_TYPE ? str(e.props.body.version) : undefined;
+      const pin = readModulePin(source, version);
+      out.push({
+        root: rel,
+        file: rel === "." ? e.props.file : `${rel}/${e.props.file}`,
+        address: e.props.address,
+        kind: e.entityType === MODULE_TYPE ? "terraform" : "terragrunt",
+        source,
+        module: normalizeModuleSource(pin.module),
+        pin: pin.pin,
+        at: pin.at,
+        ...(pin.param ? { param: pin.param } : {}),
+        ...(pin.unpinned ? { unpinned: pin.unpinned } : {}),
+      });
+    }
+  }
+  return out.sort((a, b) => a.root.localeCompare(b.root) || a.file.localeCompare(b.file) || a.address.localeCompare(b.address));
+}

package/src/pin/edit.ts

@@ -24,6 +24,7 @@
 
 import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
 import { movePin, type PinMove } from "./source";
+import { isJsonConfigFile, jsonConfigTree } from "../hcl/files";
 import { escapeHcl, scanBlocks, unescapeHcl, type ScannedAttribute, type ScannedBlock } from "./scan";
 
 /** What to move: a module, named by its source without the pin, from one pin to another. */
@@ -99,6 +100,7 @@ interface Splice {
  * is reported with its reason and left as it was.
  */
 export async function editPins(text: string, file: string, request: PinRequest, parser: Hcl2Json): Promise<PinEditResult> {
+  if (isJsonConfigFile(file)) return jsonPins(text, file, request);
   const terragrunt = isTerragruntFile(file);
   const tree = (await parser.parse(file, text)) as Tree;
   const blocks = scanBlocks(text, file);
@@ -155,3 +157,31 @@ export async function editPins(text: string, file: string, request: PinRequest,
 function rewriteLiteral(raw: string, was: string, value: string): string {
   return raw === was ? value : escapeHcl(value);
 }
+
+/**
+ * The calls of the module in a `.tf.json` or `.tofu.json` file (chant#4457).
+ * The pin edit splices HCL text and has no splice for JSON syntax, so a call
+ * that would move is refused by name and the file is left as it is; a call
+ * already at the new pin, or at another one, reads as it does in HCL.
+ */
+function jsonPins(text: string, file: string, request: PinRequest): PinEditResult {
+  const calls: PinCallResult[] = [];
+  let tree: Record<string, unknown>;
+  try {
+    tree = jsonConfigTree(text);
+  } catch (err) {
+    return { content: text, calls: [{ outcome: "refused", reason: `not JSON the binary reads: ${err instanceof Error ? err.message : String(err)}`, file, call: "(file)" }] };
+  }
+  const modules = (tree.module && typeof tree.module === "object" ? tree.module : {}) as Record<string, unknown>;
+  for (const [name, bodies] of Object.entries(modules)) {
+    for (const body of Array.isArray(bodies) ? (bodies as Record<string, unknown>[]) : []) {
+      if (typeof body.source !== "string") continue;
+      const move = movePin(body.source, typeof body.version === "string" ? body.version : undefined, request);
+      if (!move) continue;
+      const at = { file, call: `module.${name}` };
+      if (move.outcome === "moved") calls.push({ outcome: "refused", reason: "the call is in Terraform's JSON syntax, which the pin edit does not write; move its pin by hand", ...at });
+      else calls.push({ ...move, ...at });
+    }
+  }
+  return { content: text, calls };
+}

package/src/pin/rollout.ts

@@ -48,6 +48,7 @@ import { editPins, type PinCallResult, type PinEditResult, type PinRequest } fro
 import { checkPinRequest, moduleOf } from "./source";
 import { planPinWaves, restrictWaves, terragruntDependencies, type PinRoot, type PinWave } from "./waves";
 import { ghPinForge, type PinForge } from "./forge";
+import { isConfigFileFor, listConfigFilesSafe } from "../hcl/files";
 
 const execFileAsync = /* @__PURE__ */ promisify(execFile);
 
@@ -83,6 +84,8 @@ export interface PinRolloutOptions extends PinRequest {
   editTs?: TsPinEditor;
   /** Markdown appended to a wave's PR body, such as the grouped plan summary of #3188 once a caller has the wave's plans. */
   planSummary?: (wave: PinWave) => Promise<string | undefined>;
+  /** The binary the roots run: `tofu` or `choudoufu` reads `.tofu` files too (chant#4457). Default `terraform`. */
+  binary?: string;
 }
 
 /** Where one root's pin stood on the base branch. */
@@ -169,22 +172,24 @@ export function pinWaveBranch(request: PinRequest, wave: number): string {
   return `chant/pin/${slug(request.module)}/${slug(request.to)}/wave-${wave}`;
 }
 
-/** The files the pin edit reads in a root directory: its `.tf` files and its `terragrunt.hcl`. */
-function rootFiles(worktree: string, root: string): string[] {
+/**
+ * The files the pin edit reads in a root directory: the configuration files
+ * the root's binary reads (the lexicon's one lister, chant#4457) and its
+ * `terragrunt.hcl`.
+ */
+function rootFiles(worktree: string, root: string, binary?: string): string[] {
   const dir = join(worktree, root);
   if (!existsSync(dir)) return [];
-  return readdirSync(dir)
-    .filter((f) => f.endsWith(".tf") || f === "terragrunt.hcl")
-    .sort()
-    .map((f) => posix.join(root, f));
+  const names = [...listConfigFilesSafe(dir, binary), ...(existsSync(join(dir, "terragrunt.hcl")) ? ["terragrunt.hcl"] : [])];
+  return names.sort().map((f) => posix.join(root, f));
 }
 
-/** Every directory under the worktree with a `.tf` file or a `terragrunt.hcl`. */
-function candidateRoots(worktree: string): string[] {
+/** Every directory under the worktree with a configuration file the binary reads, or a `terragrunt.hcl`. */
+function candidateRoots(worktree: string, binary?: string): string[] {
   const out: string[] = [];
   const walk = (rel: string) => {
     const entries = readdirSync(join(worktree, rel), { withFileTypes: true });
-    if (entries.some((e) => e.isFile() && (e.name.endsWith(".tf") || e.name === "terragrunt.hcl"))) out.push(rel || ".");
+    if (entries.some((e) => e.isFile() && (isConfigFileFor(e.name, binary) || e.name === "terragrunt.hcl"))) out.push(rel || ".");
     for (const e of entries) if (e.isDirectory() && !SKIP_DIRS.has(e.name)) walk(rel ? posix.join(rel, e.name) : e.name);
   };
   walk("");
@@ -201,7 +206,7 @@ async function editRoot(worktree: string, root: PinRoot, request: PinRequest, op
       return { state: { root: root.root, state: "refused", files, calls, reason: `generated from ${root.tsSource}, and this caller has no TypeScript editor` }, edits };
     }
   } else {
-    files = rootFiles(worktree, root.root);
+    files = rootFiles(worktree, root.root, options.binary);
   }
   for (const file of files) {
     const path = join(worktree, file);
@@ -302,7 +307,7 @@ export async function runPinRollout(options: PinRolloutOptions): Promise<PinRoll
   await run("git", ["worktree", "add", "--quiet", "--detach", worktree, baseRef], repo);
   try {
     // 1. Every root's pin on the base branch.
-    const declared = (options.roots ?? candidateRoots(worktree).map((root): PinRoot => ({ root }))).map((r) => ({
+    const declared = (options.roots ?? candidateRoots(worktree, options.binary).map((root): PinRoot => ({ root }))).map((r) => ({
       ...r,
       root: dirOf(r.root),
       ...(r.dependsOn ? { dependsOn: r.dependsOn.map(dirOf) } : {}),

package/src/plan-shape.test.ts

@@ -0,0 +1,148 @@
+/**
+ * `terraformPlanShape` (#4436), against the recorded `show -json` plans of
+ * terraform, tofu and choudoufu in `__fixtures__/change-set/` (see
+ * change-set.test.ts for how they were recorded).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { planShapeCovers, planShapeDigest, type PlanShapeEntry } from "@intentius/chant/components/covered-round";
+import { terraformPlanShape } from "./plan-shape";
+
+const DIR = join(import.meta.dirname, "__fixtures__", "change-set");
+const read = (name: string): unknown => JSON.parse(readFileSync(join(DIR, name), "utf-8"));
+
+const T = "terraform_data";
+
+/** The fixture plan: a no-op, an update, an update of a sensitive value, a delete, a replace, two creates under a module. */
+const FIXTURE_ENTRIES: PlanShapeEntry[] = [
+  { logicalId: "module.app.terraform_data.instance[0]", action: "create", type: T, properties: ["id", "input", "output"], unknown: ["id", "output"] },
+  { logicalId: "module.app.terraform_data.instance[1]", action: "create", type: T, properties: ["id", "input", "output"], unknown: ["id", "output"] },
+  { logicalId: "terraform_data.config", action: "update", replacement: "false", type: T, properties: ["input", "output"], unknown: ["output"] },
+  { logicalId: "terraform_data.old", action: "delete", type: T, properties: [], unknown: [] },
+  { logicalId: "terraform_data.secret", action: "update", replacement: "false", type: T, properties: ["input", "output"], unknown: ["output"] },
+  { logicalId: "terraform_data.worker", action: "replace", replacement: "true", type: T, properties: ["id", "output", "triggers_replace"], unknown: ["id", "output"] },
+];
+
+describe("terraformPlanShape, on real plans", () => {
+  test.each(["terraform", "tofu", "choudoufu"] as const)("%s: one entry per change, none for the no-op", (planner) => {
+    expect(terraformPlanShape(read(`${planner}.plan.json`), "estate")).toEqual({ member: "estate", entries: FIXTURE_ENTRIES, unknownInputs: [] });
+  });
+
+  test("a table of the actions, replacement and attributes the fixture gives", () => {
+    const shape = terraformPlanShape(read("terraform.plan.json"), "estate");
+    expect(shape.entries.map((e) => [e.logicalId, e.action, e.replacement, e.properties, e.unknown])).toEqual(
+      FIXTURE_ENTRIES.map((e) => [e.logicalId, e.action, e.replacement, e.properties, e.unknown]),
+    );
+    // terraform_data.keep is a no-op, so it has no entry.
+    expect(shape.entries.some((e) => e.logicalId === "terraform_data.keep")).toBe(false);
+  });
+
+  test("the choudoufu set plan's embedded plan gives a shape too", () => {
+    const doc = read("choudoufu-set-plan.json") as { roots: Array<{ plan?: unknown }> };
+    expect(terraformPlanShape(doc.roots[0]!.plan, "estates/e01")).toEqual({
+      member: "estates/e01",
+      entries: [{ logicalId: "terraform_data.x", action: "create", properties: [], unknown: [] }],
+      unknownInputs: [],
+    });
+  });
+
+  test("a forget has an entry with no properties", () => {
+    const shape = terraformPlanShape(read("terraform.import-forget.plan.json"), "estate");
+    expect(shape.entries.find((e) => e.logicalId === "terraform_data.a")).toMatchObject({ action: "forget", properties: [], unknown: [] });
+  });
+
+  test("the digest of the same plan JSON is equal across two runs", () => {
+    const one = planShapeDigest(terraformPlanShape(read("terraform.plan.json"), "estate"));
+    const two = planShapeDigest(terraformPlanShape(read("terraform.plan.json"), "estate"));
+    expect(one).toBe(two);
+    expect(planShapeDigest(terraformPlanShape(read("tofu.plan.json"), "estate"))).toBe(one);
+  });
+
+  test("a shape is covered by itself, and not by a plan that adds a resource", () => {
+    const first = terraformPlanShape(read("terraform.plan.json"), "estate");
+    expect(planShapeCovers(first, terraformPlanShape(read("terraform.plan.json"), "estate"))).toBeUndefined();
+    const plan = read("terraform.plan.json") as { resource_changes: unknown[] };
+    const more = { ...plan, resource_changes: [...plan.resource_changes, { address: "terraform_data.extra", type: T, change: { actions: ["create"], before: null, after: { input: "x" }, after_unknown: {} } }] };
+    expect(planShapeCovers(first, terraformPlanShape(more, "estate"))).toContain("terraform_data.extra");
+  });
+
+  test("unknown and known inputs are the caller's, and enter the digest", () => {
+    const plan = read("terraform.plan.json");
+    const shape = terraformPlanShape(plan, "app", { unknownInputs: ["a.id"], knownInputs: { "net.cidr": "10.0.0.0/16" } });
+    expect(shape.unknownInputs).toEqual(["a.id"]);
+    expect(shape.knownInputs).toEqual({ "net.cidr": "10.0.0.0/16" });
+    expect(planShapeDigest(shape)).not.toBe(planShapeDigest(terraformPlanShape(plan, "app")));
+  });
+});
+
+/** A plan with one update whose `replace_paths` and `after_unknown` are as given. */
+function updatePlan(change: Record<string, unknown>, extra: Record<string, unknown> = {}): unknown {
+  return { resource_changes: [{ address: "aws_instance.web", type: "aws_instance", ...extra, change: { actions: ["update"], ...change } }] };
+}
+
+describe("terraformPlanShape replacement", () => {
+  test("an update with a replace_paths entry replaces", () => {
+    const plan = updatePlan({ before: { ami: "a" }, after: { ami: "b" }, after_unknown: {}, replace_paths: [["ami"]] });
+    expect(terraformPlanShape(plan, "m").entries[0]).toMatchObject({ action: "update", replacement: "true", type: "aws_instance", properties: ["ami"] });
+  });
+
+  test("an update whose replaced path is unknown after apply is conditional", () => {
+    const plan = updatePlan({ before: { ami: "a" }, after: {}, after_unknown: { ami: true }, replace_paths: [["ami"]] });
+    expect(terraformPlanShape(plan, "m").entries[0]).toMatchObject({ replacement: "conditional", properties: ["ami"], unknown: ["ami"] });
+  });
+
+  test("a nested replaced path is unknown when its own leaf is", () => {
+    const plan = updatePlan({ before: { tags: { env: "a" } }, after: { tags: {} }, after_unknown: { tags: { env: true } }, replace_paths: [["tags", "env"]] });
+    expect(terraformPlanShape(plan, "m").entries[0]!.replacement).toBe("conditional");
+  });
+
+  test("one known replaced path is enough to replace", () => {
+    const plan = updatePlan({
+      before: { ami: "a", zone: "x" },
+      after: { zone: "y" },
+      after_unknown: { ami: true },
+      replace_paths: [["ami"], ["zone"]],
+    });
+    expect(terraformPlanShape(plan, "m").entries[0]!.replacement).toBe("true");
+  });
+
+  test("an update with no replace_paths replaces nothing", () => {
+    const plan = updatePlan({ before: { ami: "a" }, after: { ami: "b" }, after_unknown: {} });
+    expect(terraformPlanShape(plan, "m").entries[0]!.replacement).toBe("false");
+  });
+
+  test("a delete and create pair with no replace_paths replaces", () => {
+    const plan = { resource_changes: [{ address: "x.y", type: "x", change: { actions: ["create", "delete"], before: { a: 1 }, after: { a: 2 }, after_unknown: {} } }] };
+    expect(terraformPlanShape(plan, "m").entries[0]).toMatchObject({ action: "replace", replacement: "true" });
+  });
+});
+
+describe("terraformPlanShape, edge cases", () => {
+  test("a deposed object's logical id carries its key", () => {
+    const plan = updatePlan({ before: { a: 1 }, after: null, actions: ["delete"] }, { deposed: "0123abcd" });
+    const [entry] = terraformPlanShape(plan, "m").entries;
+    expect(entry).toMatchObject({ logicalId: "aws_instance.web#0123abcd", action: "delete" });
+  });
+
+  test("read and no-op entries are left out", () => {
+    const plan = {
+      resource_changes: [
+        { address: "data.x.a", type: "x", change: { actions: ["read"] } },
+        { address: "x.b", type: "x", change: { actions: ["no-op"], before: {}, after: {} } },
+      ],
+    };
+    expect(terraformPlanShape(plan, "m").entries).toEqual([]);
+  });
+
+  test("anything that is not a plan has no entries", () => {
+    expect(terraformPlanShape(undefined, "m")).toEqual({ member: "m", entries: [], unknownInputs: [] });
+    expect(terraformPlanShape({}, "m").entries).toEqual([]);
+  });
+
+  test("sensitive values never enter the shape", () => {
+    const shape = terraformPlanShape(read("terraform.plan.json"), "estate");
+    expect(JSON.stringify(shape)).not.toContain("s3cr3t");
+  });
+});