@intentius/chant-lexicon-terraform 0.124.51 → 0.124.54

package/src/behaviour/reference-catalog.ts

@@ -16,11 +16,22 @@
  * Every terraform `resource` block is `Terraform::Resource` to chant. A rule
  * keyed on that would apply to a VPC and an instance alike, so the nodes
  * `./request.ts` builds for the resolver carry the **provider type** as their
- * `kind` — `aws_subnet` — and the rules here are keyed the same way. That is
- * also why this catalog is not declared on the plugin as `referenceCatalog`:
- * `chant graph --live` builds its nodes with `kind: "Terraform::Resource"`
- * and attributes that carry no arguments at all, so declaring it there would
- * be a catalog that matched nothing and looked like coverage.
+ * `kind` — `aws_subnet` — and the rules here are keyed the same way.
+ *
+ * ## On the plugin (#4535)
+ *
+ * The plugin declares it as `referenceCatalog` since #4535, so a reader that
+ * asks every lexicon of a graph for its catalog (behold#1030's gate, before
+ * behold#1005 retires behold's name matcher) finds terraform's. What it
+ * matches depends on the nodes. A declared or live `chant graph` node is
+ * `Terraform::Resource`, with its provider type in `attrs.type` and no
+ * arguments in `attrs`, so no rule here reads it: those graphs keep the edges
+ * the HCL references and the state dependencies give them, and gain none. A
+ * node whose `kind` is the provider type and whose `attrs` are the block's
+ * arguments (`./request.ts`'s, an engine's instance roster) is what the rules
+ * are for. `chant graph --live` merges a catalog's edges with the
+ * observation's own since #4535; before, any catalog replaced them, which is
+ * what kept this one off the plugin.
  *
  * ## Two relations, and why the split matters to an engine
  *

package/src/behaviour/request.ts

@@ -329,8 +329,9 @@ function liveVerdictOf(address: string, plan: LivePlanIndex): LiveVerdict {
       kind: "unobserved",
       instances,
       // `no-credentials` is an observation reason and not a prediction one;
-      // the credential wording stays in the detail.
-      reason: unobserved.reason === "no-credentials" ? "read-failed" : unobserved.reason,
+      // the credential wording stays in the detail. `not-reached` is a
+      // stream's reason (#4451) and a live-plan omission never gives it.
+      reason: unobserved.reason === "no-credentials" || unobserved.reason === "not-reached" ? "read-failed" : unobserved.reason,
       detail: unobserved.detail,
     };
   }

package/src/change-set-instances.test.ts

@@ -0,0 +1,98 @@
+/**
+ * A `count = 3` resource's stored change set carries three node ids (#4454).
+ *
+ * The graph is read in process the way `chant graph --format ir` builds it
+ * for a terraform root: the root's entities, `buildGraphIr`, then
+ * `withInstanceNodes`. The plan is a `show -json` shape with one
+ * `resource_changes` row per instance, as terraform prints a `count` block.
+ */
+
+import { describe, expect, test } from "vitest";
+import { composeChangeSet, verifyChangeSetDigest } from "@intentius/chant/change-set";
+import { graphNodeFor, mapChangeSetToGraph } from "@intentius/chant/change-set-graph";
+import { buildGraphIr, withInstanceNodes } from "@intentius/chant/graph-ir";
+import { terraformChangeSetPart } from "./change-set";
+import { literalInstanceKeys, parseTerraformRootContent } from "./hcl/parse";
+
+const SOURCE = `resource "aws_eip" "pool" {
+  count  = 3
+  domain = "vpc"
+}
+
+resource "aws_s3_bucket" "logs" {
+  bucket = "logs"
+}
+`;
+
+const create = (address: string, index?: number) => ({
+  address,
+  mode: "managed",
+  type: address.split(".")[0],
+  name: address.split(".")[1]!.replace(/\[.*$/, ""),
+  ...(index !== undefined ? { index } : {}),
+  change: { actions: ["create"], before: null, after: { domain: "vpc" }, after_unknown: { id: true } },
+});
+
+const PLAN = {
+  format_version: "1.2",
+  resource_changes: [create("aws_eip.pool[0]", 0), create("aws_eip.pool[1]", 1), create("aws_eip.pool[2]", 2), create("aws_s3_bucket.logs")],
+};
+
+describe("instance nodes for a count block", () => {
+  test("a literal count gives the block three instance keys", () => {
+    expect(literalInstanceKeys({ count: 3 })).toEqual(["[0]", "[1]", "[2]"]);
+    expect(literalInstanceKeys({ count: "${var.n}" })).toBeUndefined();
+    expect(literalInstanceKeys({ for_each: { b: 1, a: 2 } })).toEqual(['["a"]', '["b"]']);
+    expect(literalInstanceKeys({ for_each: '${toset(["x", "y"])}' })).toEqual(['["x"]', '["y"]']);
+  });
+
+  test("the graph has the block node and one instance node per index, each naming the block", async () => {
+    const entities = await parseTerraformRootContent(SOURCE, "estate");
+    const ir = withInstanceNodes(buildGraphIr(entities), entities);
+    const pool = ir.nodes.filter((n) => n.id.startsWith("estate/aws_eip.pool"));
+    expect(pool.map((n) => [n.id, n.instanceOf ?? null, n.instanceKey ?? null])).toEqual([
+      ["estate/aws_eip.pool", null, null],
+      ["estate/aws_eip.pool[0]", "estate/aws_eip.pool", "[0]"],
+      ["estate/aws_eip.pool[1]", "estate/aws_eip.pool", "[1]"],
+      ["estate/aws_eip.pool[2]", "estate/aws_eip.pool", "[2]"],
+    ]);
+    expect(ir.groups.byStack?.estate).toEqual(expect.arrayContaining(["estate/aws_eip.pool[0]", "estate/aws_eip.pool[2]"]));
+  });
+
+  test("the stored change set carries three node ids for the three instances", async () => {
+    const entities = await parseTerraformRootContent(SOURCE, "estate");
+    const ir = withInstanceNodes(buildGraphIr(entities), entities);
+    const doc = composeChangeSet([terraformChangeSetPart({ member: "estate", plan: PLAN })]);
+    const mapped = mapChangeSetToGraph(doc, { member: "infra", at: null, ids: ir.nodes.map((n) => n.id) });
+
+    const pool = mapped.entries.filter((e) => e.type === "aws_eip");
+    expect(pool.map((e) => [e.address, e.node, e.instanceOf])).toEqual([
+      ["aws_eip.pool[0]", "infra/estate/aws_eip.pool[0]", "infra/estate/aws_eip.pool"],
+      ["aws_eip.pool[1]", "infra/estate/aws_eip.pool[1]", "infra/estate/aws_eip.pool"],
+      ["aws_eip.pool[2]", "infra/estate/aws_eip.pool[2]", "infra/estate/aws_eip.pool"],
+    ]);
+    expect(new Set(pool.map((e) => e.node)).size).toBe(3);
+    const logs = mapped.entries.find((e) => e.address === "aws_s3_bucket.logs")!;
+    expect(logs.node).toBe("infra/estate/aws_s3_bucket.logs");
+    expect(logs.instanceOf).toBeUndefined();
+    // Node ids are not hashed.
+    expect(mapped.digest).toBe(doc.digest);
+    expect(verifyChangeSetDigest(mapped)).toBe(true);
+  });
+
+  test("an instance the graph cannot count still gets its instance id, and a drift row the same", async () => {
+    const entities = await parseTerraformRootContent(SOURCE.replace("count  = 3", "count  = var.n"), "estate");
+    const ir = withInstanceNodes(buildGraphIr(entities), entities);
+    expect(ir.nodes.some((n) => n.instanceOf)).toBe(false);
+    const graph = { member: null, at: null, ids: ir.nodes.map((n) => n.id) };
+    expect(graphNodeFor({ member: "estate", planner: "terraform", address: "aws_eip.pool[1]" }, graph)).toMatchObject({
+      node: "estate/aws_eip.pool[1]",
+      instanceOf: "estate/aws_eip.pool",
+    });
+    // Under an expanded module call the module key sits on the call's segment (#4486).
+    expect(graphNodeFor({ member: "estate", planner: "terraform", address: "module.app[0].aws_eip.pool[1]" }, { ...graph, ids: ["estate/module.app/aws_eip.pool"] })).toEqual({
+      node: "estate/module.app[0]/aws_eip.pool[1]",
+      instanceOf: "estate/module.app/aws_eip.pool",
+    });
+  });
+});

package/src/changed-roots.ts

@@ -9,16 +9,19 @@
  * in a local module it calls (followed through modules that call modules),
  * or is one of its var files.
  *
- * The module calls are read with a regex over the root's `.tf` and `.tofu`
+ * The module calls are read with a regex over the root's HCL configuration
  * files, the way `./op/activities/live-detect.ts` reads a live block, so
- * this stays out of the HCL parser's dependency graph. Only a `source` that
+ * this stays out of the HCL parser's dependency graph. Which files those are
+ * follows the root's binary through the lexicon's one lister (chant#4457):
+ * `.tf`, plus `.tofu` for a tofu or choudoufu root. Only a `source` that
  * starts with `./` or `../` is followed; a registry or git source is a
  * version pin in the root's own files, which a change to it already touches.
  */
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, posix, relative, resolve, sep } from "node:path";
 import type { TerraformRootConfig } from "./config";
+import { isJsonConfigFile, listConfigFilesSafe } from "./hcl/files";
 
 /** `source = "./..."` or `"../..."` inside a module block. Other sources are not on disk here. */
 const LOCAL_SOURCE = /\bsource\s*=\s*"(\.{1,2}\/[^"]*)"/g;
@@ -31,17 +34,11 @@ function projectRelative(projectRoot: string, dir: string): string {
   return rel === "" ? "." : posix.normalize(rel).replace(/\/+$/, "");
 }
 
-/** Local module directories `dir` calls, read from its HCL files. */
-function localModuleDirs(dir: string): string[] {
-  let names: string[];
-  try {
-    names = readdirSync(dir);
-  } catch {
-    return [];
-  }
+/** Local module directories `dir` calls, read from the HCL configuration files `binary` reads. */
+function localModuleDirs(dir: string, binary?: string): string[] {
   const out: string[] = [];
-  for (const name of names) {
-    if (!name.endsWith(".tf") && !name.endsWith(".tofu")) continue;
+  for (const name of listConfigFilesSafe(dir, binary)) {
+    if (isJsonConfigFile(name)) continue;
     let text: string;
     try {
       text = readFileSync(join(dir, name), "utf8");
@@ -61,7 +58,7 @@ function localModuleDirs(dir: string): string[] {
  * Every path, relative to `projectRoot`, whose change touches `root`: its
  * directory, each local module it reaches, and its var files.
  */
-export function rootWatchPaths(projectRoot: string, root: Pick<TerraformRootConfig, "dir" | "varFiles">): string[] {
+export function rootWatchPaths(projectRoot: string, root: Pick<TerraformRootConfig, "dir" | "varFiles">, binary?: string): string[] {
   const rootDir = resolve(projectRoot, root.dir);
   const seen = new Set<string>();
   const queue = [rootDir];
@@ -69,7 +66,7 @@ export function rootWatchPaths(projectRoot: string, root: Pick<TerraformRootConf
     const dir = queue.shift()!;
     if (seen.has(dir)) continue;
     seen.add(dir);
-    queue.push(...localModuleDirs(dir));
+    queue.push(...localModuleDirs(dir, binary));
   }
   const paths = [...seen].map((d) => projectRelative(projectRoot, d));
   for (const file of root.varFiles ?? []) paths.push(projectRelative(projectRoot, resolve(rootDir, file)));
@@ -91,11 +88,12 @@ export function changedRoots(
   projectRoot: string,
   roots: Record<string, Pick<TerraformRootConfig, "dir" | "varFiles">>,
   changedFiles: readonly string[],
+  binary?: string,
 ): string[] {
   const files = changedFiles.map((f) => posix.normalize(f));
   const touched: string[] = [];
   for (const [name, root] of Object.entries(roots)) {
-    const watch = rootWatchPaths(projectRoot, root);
+    const watch = rootWatchPaths(projectRoot, root, binary);
     if (files.some((f) => watch.some((p) => covers(p, f)))) touched.push(name);
   }
   return touched.sort();

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") };
 }
@@ -105,8 +106,87 @@ async function runPinRolloutVerb(ctx: CommandGroupContext): Promise<number> {
   }
 }
 
+const REPORT_USAGE =
+  "usage: chant terraform report --stage tf-plan|tf-apply --plan <show.json> [--applied <show-after-apply.json>] (--out <dir> | --to <url>) " +
+  "[--project <host/path>] [--commit <sha>] [--pull-request <n>] [--binary <name>] [--binary-version <v>] [--root-dir <dir>] [--self-root <dir>] [--repo <dir>] " +
+  "[--started <iso>] [--finished <iso>] [--json]";
+
+const REPORT_VALUE_FLAGS = new Set(["--stage", "--plan", "--applied", "--out", "--to", "--project", "--commit", "--pull-request", "--binary", "--binary-version", "--root-dir", "--self-root", "--repo", "--started", "--finished"]);
+
+/** Parse `chant terraform report`'s flags. Throws on an unknown flag, a missing value or a missing required flag. */
+export function parseReportArgs(rawArgs: string[]): { values: Map<string, string>; json: boolean } {
+  const tokens = splitJoinedFlags(rawArgs, new Set(["--json"]));
+  const values = new Map<string, string>();
+  let json = false;
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i]!;
+    if (t === "--json") {
+      json = true;
+      continue;
+    }
+    if (!REPORT_VALUE_FLAGS.has(t)) throw t.startsWith("-") ? unknownFlagError(t, REPORT_USAGE) : new Error(`unexpected argument "${t}"\n${REPORT_USAGE}`);
+    const v = tokens[++i];
+    if (v === undefined || v.startsWith("--")) throw new Error(`${t} needs a value\n${REPORT_USAGE}`);
+    values.set(t, v);
+  }
+  const stage = values.get("--stage");
+  if (stage !== "tf-plan" && stage !== "tf-apply") throw new Error(`--stage is tf-plan or tf-apply\n${REPORT_USAGE}`);
+  if (!values.has("--plan")) throw new Error(`--plan is required\n${REPORT_USAGE}`);
+  if (stage === "tf-apply" && !values.has("--applied")) throw new Error(`--stage tf-apply needs --applied, the show -json of a plan made after the apply\n${REPORT_USAGE}`);
+  if (values.has("--out") === values.has("--to")) throw new Error(`give one of --out <dir> and --to <url>\n${REPORT_USAGE}`);
+  return { values, json };
+}
+
+async function runReportVerb(ctx: CommandGroupContext): Promise<number> {
+  try {
+    const { values, json } = parseReportArgs(ctx.rawArgs);
+    const { readFileSync } = await import("node:fs");
+    const { runFactsFromEnv, terraformReport, writeReport, httpStore, dirStore, moduleEstates, atmosStackReads, topModule } = await import("./report");
+    const read = (flag: string): unknown => {
+      const file = values.get(flag)!;
+      try {
+        return JSON.parse(readFileSync(file, "utf8"));
+      } catch (err) {
+        throw new Error(`${flag} ${file}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    };
+    const run = runFactsFromEnv(process.env, { pullRequest: values.get("--pull-request"), project: values.get("--project"), commit: values.get("--commit") });
+    const plan = read("--plan");
+    // The plan holds no `live` block: each module's estate is read from its directory, <repo>/<root-dir>/<module>.
+    const repo = values.get("--repo") ?? process.env.GITHUB_WORKSPACE ?? process.cwd();
+    const modules = [...new Set(((plan as { resource_changes?: { address?: string; module_address?: string }[] }).resource_changes ?? []).map((r) => topModule(String(r.module_address ?? r.address ?? ""))).filter((m): m is string => m !== undefined))];
+    const estates = moduleEstates(repo, values.get("--root-dir") ?? "", modules);
+    // An Atmos repo wires its components with !terraform.output in the stack manifests, which the plan does not keep.
+    const componentReads = atmosStackReads(repo);
+    const result = terraformReport({
+      stage: values.get("--stage") as "tf-plan" | "tf-apply",
+      plan,
+      ...(Object.keys(estates).length > 0 ? { estates } : {}),
+      ...(Object.keys(componentReads).length > 0 ? { componentReads } : {}),
+      ...(values.has("--applied") ? { applied: read("--applied") } : {}),
+      run,
+      ...(values.has("--binary") ? { binary: values.get("--binary")! } : {}),
+      ...(values.has("--binary-version") ? { binaryVersion: values.get("--binary-version")! } : {}),
+      ...(values.has("--root-dir") ? { rootDir: values.get("--root-dir")! } : {}),
+      ...(values.has("--self-root") ? { selfRoot: values.get("--self-root")! } : {}),
+      ...(values.has("--started") ? { started: values.get("--started")! } : {}),
+      finished: values.get("--finished") ?? new Date().toISOString().replace(/\.\d+Z$/, "Z"),
+    });
+    const store = values.has("--out") ? dirStore(values.get("--out")!) : httpStore(values.get("--to")!);
+    const keys = await writeReport(store, result);
+    console.log(json ? JSON.stringify({ path: result.path, keys, row: result.row }, null, 2) : `wrote ${keys.join(", ")}`);
+    return 0;
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}
+
 export const terraformCommands: CommandGroup = {
   name: "terraform",
-  description: "Terraform and OpenTofu roots: roll a module version out as one pin-bump PR per wave",
-  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 }],
+  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, 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,6 +18,10 @@ 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", () => ({
   choudoufuWaveRoot: vi.fn(async () => waveRoot),
@@ -25,7 +32,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,9 +47,11 @@ 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);
+    planTexts.push(args.text);
+    if (planError) throw planError;
     return { planFile: "chant.tfplan", planDigest: `jcs1-sha256:${args.root}`, json: planJson, ...(changeSet ? { changeSet } : {}) };
   }),
   terraformApply: vi.fn(async (args: { root: string; planFile: string }) => {
@@ -67,6 +76,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)", () => {
@@ -191,10 +213,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 +256,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);
@@ -306,3 +360,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);
+  });
+});