@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/commands.ts

@@ -22,9 +22,9 @@ import type { PinRoot } from "./pin";
 const USAGE =
   "usage: chant terraform pin-rollout --module <source> --from <pin> --to <pin> [--root <dir>]... [--depends-on <dir>=<dir>]... " +
   "[--ts-source <dir>=<file>]... [--canary <dir>]... [--waves-from <file> [--waves-prefix <dir>]] [--pull-request] " +
-  "[--base <branch>] [--remote <name>] [--applied-check <name>] [--json]";
+  "[--base <branch>] [--remote <name>] [--applied-check <name>] [--binary <terraform|tofu|choudoufu>] [--json]";
 
-const VALUE_FLAGS = new Set(["--module", "--from", "--to", "--root", "--depends-on", "--ts-source", "--canary", "--waves-from", "--waves-prefix", "--base", "--remote", "--applied-check"]);
+const VALUE_FLAGS = new Set(["--module", "--from", "--to", "--root", "--depends-on", "--ts-source", "--canary", "--waves-from", "--waves-prefix", "--base", "--remote", "--applied-check", "--binary"]);
 const BOOLEAN_FLAGS = new Set(["--pull-request", "--json"]);
 
 /** Parse the verb's flags into the activity's args. Throws on an unknown flag or a missing value. */
@@ -75,6 +75,7 @@ export function parsePinRolloutArgs(rawArgs: string[]): { args: TerraformPinRoll
     ...(one("--base") ? { base: one("--base")! } : {}),
     ...(one("--remote") ? { remote: one("--remote")! } : {}),
     ...(one("--applied-check") ? { appliedCheck: one("--applied-check")! } : {}),
+    ...(one("--binary") ? { binary: one("--binary")! } : {}),
   };
   return { args, json: flags.has("--json") };
 }
@@ -186,6 +187,6 @@ export const terraformCommands: CommandGroup = {
   description: "Terraform and OpenTofu roots: roll a module version out as one pin-bump PR per wave; write a run report from a saved plan",
   commands: [
     { name: "pin-rollout", description: "Read a pin-bump rollout's state and open the next wave's PR when it is due", handler: runPinRolloutVerb },
-    { name: "report", description: "Write a terragucci.report/v1 run report and its index row from show -json of a composed plan", handler: runReportVerb },
+    { name: "report", description: "Write a terragucci.report/v1 run report, its change set and its index row from show -json of a composed plan", handler: runReportVerb },
   ],
 };

package/src/components/capability-plugin.test.ts

@@ -3,7 +3,10 @@
  * and run applies the plan a wave approved rather than planning again.
  */
 
-import { beforeEach, describe, expect, test, vi } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 const calls: string[] = [];
 let applyResult: Record<string, unknown> = { applied: true };
@@ -15,8 +18,15 @@ let waveApply: Record<string, unknown> = { exitCode: 0, landed: true, message: "
 const waveApplyArgs: Array<Record<string, unknown>> = [];
 // #4300: the targets each plan was asked for.
 const planTargets: Array<string[] | undefined> = [];
+// #4479: the `text` each plan was asked for.
+const planTexts: Array<boolean | undefined> = [];
+// #4463: a plan that fails, as one with a stand-in a validation block rejects does.
+let planError: Error | undefined;
 
 vi.mock("../op/activities/terraform", () => ({
+  // The exit constants exit-codes.ts maps choudoufu's statuses with (#4553), as the module has them.
+  CHOUDOUFU_APPROVAL_EXIT_CODE: 3,
+  CHOUDOUFU_WAVE_EXIT: { landed: 0, error: 1, setMoved: 3, rootFailed: 4 },
   choudoufuWaveRoot: vi.fn(async () => waveRoot),
   choudoufuPlanSet: vi.fn(async (args: { root: string }) => {
     calls.push(`plan-set ${args.root}`);
@@ -25,7 +35,7 @@ vi.mock("../op/activities/terraform", () => ({
       rootDigest: `sha256:root-${args.root}`,
       planDigest: `jcs1-sha256:${args.root}`,
       changed: true,
-      json: {},
+      json: planJson,
       changeSet: { member: { member: args.root, nativeDigest: `sha256:root-${args.root}` }, entries: [] },
       planSetFile: `/x/.chant/choudoufu-waves/${args.root}/plan-set.json`,
       root: `estates/${args.root}`,
@@ -40,10 +50,13 @@ vi.mock("../op/activities/terraform", () => ({
     calls.push(`init ${args.root}`);
     return { dir: `/x/${args.root}` };
   }),
-  terraformPlan: vi.fn(async (args: { root: string; vars?: Record<string, unknown>; targets?: string[] }) => {
+  terraformPlan: vi.fn(async (args: { root: string; vars?: Record<string, unknown>; targets?: string[]; text?: boolean }) => {
     calls.push(`plan ${args.root} ${JSON.stringify(args.vars ?? {})}`);
     planTargets.push(args.targets);
-    return { planFile: "chant.tfplan", planDigest: `jcs1-sha256:${args.root}`, json: planJson, ...(changeSet ? { changeSet } : {}) };
+    planTexts.push(args.text);
+    if (planError) throw planError;
+    // `dir` as the real result has it (#4545 writes the plan document beside the plan file there).
+    return { planFile: "chant.tfplan", dir: `/x/${args.root}`, planDigest: `jcs1-sha256:${args.root}`, json: planJson, ...(changeSet ? { changeSet } : {}) };
   }),
   terraformApply: vi.fn(async (args: { root: string; planFile: string }) => {
     calls.push(`apply ${args.root} ${args.planFile}`);
@@ -67,6 +80,19 @@ beforeEach(() => {
   waveApply = { exitCode: 0, landed: true, message: "landed" };
   waveApplyArgs.length = 0;
   planTargets.length = 0;
+  planTexts.length = 0;
+  planError = undefined;
+});
+
+describe("terraform-apply plans with one show -json (#4479)", () => {
+  test("plan and run ask terraformPlan to skip the -no-color render, and plan takes outputs and shape off the one json", async () => {
+    planJson = { planned_values: { outputs: { id: { value: "x" } } }, resource_changes: [] };
+    const planned = await terraformApplyCapability.plan!({ env: "test", component: "e01" }, { root: "e01" });
+    await terraformApplyCapability.run({ env: "test", component: "e01" }, { root: "e01" });
+    expect(planTexts).toEqual([false, false]);
+    expect(planned.outputs).toEqual({ known: { id: "x" }, unknown: [] });
+    expect(planned.shape).toBeDefined();
+  });
 });
 
 describe("terraform-apply targets (#4300)", () => {
@@ -111,7 +137,8 @@ describe("terraform-apply on a choudoufu root in a gated wave (#3459)", () => {
     expect(calls).toEqual(["plan-set e01"]);
     expect(planned.member).toBe("e01");
     expect(planned.planDigest).toBe("jcs1-sha256:e01");
-    expect(planned.artifact).toEqual(wavePlan);
+    // #4552: the set path keeps the root's lock rows beside the plan (none here: the fake set's plan has no changes).
+    expect(planned.artifact).toEqual({ ...wavePlan, lockRows: [] });
     expect(planned.changeSet).toEqual({ member: { member: "e01", nativeDigest: "sha256:root-e01" }, entries: [] });
   });
 
@@ -181,7 +208,7 @@ describe("terraform-apply on a choudoufu root in a gated wave (#3459)", () => {
 
 describe("terraform-apply", () => {
   test("the plugin contributes it", () => {
-    expect(terraformCapabilityPlugin.capabilities().map((c) => c.kind)).toEqual(["terraform-apply"]);
+    expect(terraformCapabilityPlugin.capabilities().map((c) => c.kind)).toEqual(["terraform-apply", "terraform-state-unlock", "terraform-state-push", "terraform-copy"]);
   });
 
   test("plan inits and plans the root, with its vars, and names the root as the member", async () => {
@@ -191,10 +218,35 @@ describe("terraform-apply", () => {
       planDigest: "jcs1-sha256:app",
       artifact: { planFile: "chant.tfplan", planDigest: "jcs1-sha256:app" },
       outputs: { known: {}, unknown: [] },
+      shape: { member: "app", entries: [], unknownInputs: [] },
     });
     expect(calls).toEqual(["init app", 'plan app {"vpc":"v-1"}']);
   });
 
+  test("plan returns the shape of the plan's show -json, on the plain path and the choudoufu set path (#4436)", async () => {
+    planJson = {
+      resource_changes: [
+        { address: "terraform_data.keep", type: "terraform_data", change: { actions: ["no-op"] } },
+        { address: "terraform_data.web", type: "terraform_data", change: { actions: ["create"], before: null, after: { input: "x" }, after_unknown: { id: true } } },
+      ],
+    };
+    const expected = {
+      member: "app",
+      entries: [{ logicalId: "terraform_data.web", action: "create", type: "terraform_data", properties: ["id", "input"], unknown: ["id"] }],
+      unknownInputs: [],
+    };
+    const plain = await terraformApplyCapability.plan!({ env: "test", component: "app" }, { root: "app" });
+    expect(plain.shape).toEqual(expected);
+    waveRoot = { wave: true, root: "estates/app" };
+    const set = await terraformApplyCapability.plan!({ env: "test", component: "app" }, { root: "app" });
+    expect(set.shape).toEqual(expected);
+  });
+
+  test("a root waiting on unknown outputs that cannot be previewed returns no shape, so it stays uncovered (#4436)", async () => {
+    const planned = await terraformApplyCapability.plan!({ env: "test", component: "app", unresolvedInputs: ["net"] }, { root: "app", vars: { vpc: undefined } });
+    expect(planned.shape).toBeUndefined();
+  });
+
   test("plan answers the outputs the root will have, from the plan's planned values (#3999)", async () => {
     planJson = {
       planned_values: { outputs: { cidr: { sensitive: false, value: "10.1.0.0/16" }, id: { sensitive: false } } },
@@ -209,14 +261,21 @@ describe("terraform-apply", () => {
     expect(planned.artifact).toEqual({ planFile: "chant.tfplan", planDigest: "jcs1-sha256:net" });
   });
 
-  test("a root whose vars read outputs not known yet is not planned: a hole names whose (#3999)", async () => {
+  test("a root whose vars read outputs not known yet and that cannot be previewed is not planned: a hole names whose (#3999, #4463)", async () => {
+    // No chant.config.* above the working directory, so the root's variables cannot be read.
     const ctx = { env: "test", component: "app", unresolvedInputs: ["net"] };
     const planned = await terraformApplyCapability.plan!(ctx, { root: "app", vars: { vpc: undefined, name: "app" } });
     expect(calls).toEqual([]);
     expect(planned.artifact).toBeUndefined();
     expect(planned.outputs).toBeUndefined();
     expect(planned.changeSet?.entries).toEqual([]);
-    expect(planned.changeSet?.member.holes).toEqual([{ address: "app", type: "terraform_root", reason: "inputs from net; planned again once they apply" }]);
+    expect(planned.changeSet?.member.holes).toEqual([
+      {
+        address: "app",
+        type: "terraform_root",
+        reason: 'inputs from net; planned again once they apply; no preview: no root named "app" in terraform.roots to read its variables from',
+      },
+    ]);
     expect(planned.planDigest).toBe(planned.changeSet?.member.planDigest);
     const again = await terraformApplyCapability.plan!(ctx, { root: "app", vars: { vpc: undefined, name: "app" } });
     expect(again.planDigest).toBe(planned.planDigest);
@@ -287,17 +346,24 @@ describe("terraform-apply, continued", () => {
     expect(calls).not.toContain("output app");
   });
 
-  test.each(["approval-mismatch", "wrong-estate"])(
-    "choudoufu's %s refusal of the wave's plan throws core's plan-moved mark, so the command exits 3 (#3997)",
-    async (refused) => {
-      applyResult = { applied: false, refused, refusal: "refused" };
-      const err = await terraformApplyCapability
-        .run({ env: "test", component: "app", plans: { app: { planFile: "chant.tfplan", planDigest: "d" } } }, { root: "app" })
-        .catch((e: unknown) => e);
-      expect(err).toBeInstanceOf(TerraformPlanMovedError);
-      expect(isPlanMovedError(err)).toBe(true);
-    },
-  );
+  test("choudoufu's approval-mismatch refusal of the wave's plan throws core's plan-moved mark, so the command exits moved (#3997, #4553)", async () => {
+    applyResult = { applied: false, refused: "approval-mismatch", refusal: "refused" };
+    const err = await terraformApplyCapability
+      .run({ env: "test", component: "app", plans: { app: { planFile: "chant.tfplan", planDigest: "d" } } }, { root: "app" })
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(TerraformPlanMovedError);
+    expect(isPlanMovedError(err)).toBe(true);
+  });
+
+  test("choudoufu's wrong-estate refusal is an ordinary failure: the pipeline handed the wrong file, and no approval fixes that (#4553)", async () => {
+    applyResult = { applied: false, refused: "wrong-estate", refusal: "refused" };
+    const err = await terraformApplyCapability
+      .run({ env: "test", component: "app", plans: { app: { planFile: "chant.tfplan", planDigest: "d" } } }, { root: "app" })
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect(err).not.toBeInstanceOf(TerraformPlanMovedError);
+    expect(isPlanMovedError(err)).toBe(false);
+  });
 
   test("a refusal of a plan this run made itself is an ordinary failure: the next run plans afresh", async () => {
     applyResult = { applied: false, refused: "approval-mismatch", refusal: "refused" };
@@ -306,3 +372,116 @@ describe("terraform-apply, continued", () => {
     expect(isPlanMovedError(err)).toBe(false);
   });
 });
+
+describe("terraform-apply previews a root outside a group with placeholders (#4463)", () => {
+  let project: string;
+
+  beforeEach(() => {
+    project = mkdtempSync(join(tmpdir(), "chant-tf-preview-"));
+    mkdirSync(join(project, "app"));
+    writeFileSync(join(project, "chant.config.json"), JSON.stringify({ lexicons: ["terraform"], terraform: { roots: { app: { dir: "app" } } } }));
+    writeFileSync(
+      join(project, "app", "variables.tf"),
+      'variable "vpc_id" {\n  type = string\n}\n\nvariable "name" {\n  type = string\n}\n',
+    );
+  });
+
+  afterEach(() => rmSync(project, { recursive: true, force: true }));
+
+  const subnetPlan = (vpcAfter: unknown) => ({
+    configuration: {
+      root_module: {
+        resources: [
+          {
+            address: "aws_subnet.a",
+            mode: "managed",
+            type: "aws_subnet",
+            name: "a",
+            expressions: { vpc_id: { references: ["var.vpc_id"] }, tags: { references: ["var.name"] } },
+          },
+        ],
+        outputs: { subnet_vpc: { expression: { references: ["var.vpc_id"] } } },
+      },
+    },
+    resource_changes: [
+      {
+        address: "aws_subnet.a",
+        mode: "managed",
+        type: "aws_subnet",
+        name: "a",
+        change: { actions: ["create"], before: null, after: { vpc_id: vpcAfter, tags: { Name: "app" } }, after_unknown: { id: true } },
+      },
+    ],
+    planned_values: { outputs: { subnet_vpc: { value: vpcAfter } } },
+    output_changes: { subnet_vpc: { actions: ["create"], after: vpcAfter, after_unknown: false } },
+  });
+
+  const ctx = () => ({ env: "test", component: "app", unresolvedInputs: ["net"] });
+  const input = () => ({ root: "app", cwd: project, vars: { vpc_id: undefined, name: "app" } });
+
+  test("plans with a typed stand-in, marks what it drives unknown, and says which reads were placeholders", async () => {
+    planJson = subnetPlan("known-after-apply");
+    const planned = await terraformApplyCapability.plan!(ctx(), input());
+    expect(calls).toEqual(["init app", 'plan app {"vpc_id":"known-after-apply","name":"app"}']);
+    expect(planned.changeSet?.member.holes).toEqual([]);
+    expect(planned.changeSet?.member.placeholders).toEqual(["var.vpc_id"]);
+    expect(planned.changeSet?.member.planDigest).toBe(planned.planDigest);
+    const attrs = planned.changeSet?.entries[0]?.attributes ?? [];
+    expect(attrs.find((a) => a.path === "vpc_id")).toEqual({ path: "vpc_id", unknown: true });
+    // No stand-in value reaches the note.
+    expect(JSON.stringify(planned.changeSet)).not.toContain("known-after-apply");
+    expect(planned.outputs).toEqual({ known: {}, unknown: ["subnet_vpc"] });
+    expect(planned.shape?.unknownInputs).toEqual(["net"]);
+    expect(planned.shape?.entries[0]).toMatchObject({ logicalId: "aws_subnet.a", action: "create", unknown: ["id", "vpc_id"] });
+    // The artifact is the shape, never a plan file a stand-in could apply from.
+    expect(planned.artifact).toMatchObject({ kind: "terraform-apply-shape", member: "app" });
+    expect((planned.artifact as { planFile?: string }).planFile).toBeUndefined();
+    const again = await terraformApplyCapability.plan!(ctx(), input());
+    expect(again.planDigest).toBe(planned.planDigest);
+  });
+
+  test("a placeholder plan that fails leaves the member a hole, and the hole says why (ruling 2026-10-25)", async () => {
+    planError = new Error("terraform plan failed in /x/app (exit 1)\nError: Invalid value for variable\n  on variables.tf line 1: vpc_id must start with vpc-");
+    const planned = await terraformApplyCapability.plan!(ctx(), input());
+    expect(planned.artifact).toBeUndefined();
+    expect(planned.shape).toBeUndefined();
+    expect(planned.changeSet?.entries).toEqual([]);
+    expect(planned.changeSet?.member.placeholders).toBeUndefined();
+    const [hole] = planned.changeSet?.member.holes ?? [];
+    expect(hole?.reason).toMatch(/^inputs from net; planned again once they apply; no preview: the plan with stand-in values failed: /);
+    expect(hole?.reason).toContain("Invalid value for variable");
+  });
+
+  test("a count over a stand-in leaves the member a hole, and the hole says why", async () => {
+    const plan = subnetPlan("known-after-apply") as Record<string, any>;
+    plan.configuration.root_module.resources[0].count_expression = { references: ["var.vpc_id"] };
+    planJson = plan;
+    const planned = await terraformApplyCapability.plan!(ctx(), input());
+    expect(planned.changeSet?.member.holes[0]?.reason).toContain("no preview: the count or for_each of aws_subnet.a reads a stand-in");
+  });
+
+  test("run holds the real plan to the preview's shape: a match applies it", async () => {
+    planJson = subnetPlan("known-after-apply");
+    const planned = await terraformApplyCapability.plan!(ctx(), input());
+    calls.length = 0;
+    planJson = subnetPlan("vpc-123");
+    const out = await terraformApplyCapability.run({ env: "test", component: "app", plans: { app: planned.artifact } }, { root: "app", cwd: project, vars: { vpc_id: "vpc-123", name: "app" } });
+    expect(calls).toEqual(["init app", 'plan app {"vpc_id":"vpc-123","name":"app"}', "apply app chant.tfplan", "output app"]);
+    expect(out.fromWavePlan).toBe(false);
+  });
+
+  test("run refuses a real plan that goes beyond the preview's shape, and applies nothing", async () => {
+    planJson = subnetPlan("known-after-apply");
+    const planned = await terraformApplyCapability.plan!(ctx(), input());
+    calls.length = 0;
+    const real = subnetPlan("vpc-123") as Record<string, any>;
+    real.resource_changes.push({ address: "aws_route.r", mode: "managed", type: "aws_route", name: "r", change: { actions: ["create"], before: null, after: { cidr: "0.0.0.0/0" }, after_unknown: {} } });
+    planJson = real;
+    const err = await terraformApplyCapability
+      .run({ env: "test", component: "app", plans: { app: planned.artifact } }, { root: "app", cwd: project, vars: { vpc_id: "vpc-123", name: "app" } })
+      .catch((e: unknown) => e);
+    expect(isPlanMovedError(err)).toBe(true);
+    expect((err as Error).message).toContain("aws_route.r");
+    expect(calls.some((c) => c.startsWith("apply"))).toBe(false);
+  });
+});