@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/compose/state-merge.test.ts

@@ -0,0 +1,131 @@
+/**
+ * The working state of a composed run (#4442): merged from each member's
+ * pulled state, split back by module address. Fixtures are `state pull`
+ * output in `../__fixtures__/compose`, and the working state an apply of the
+ * three-module plan left (net's tags changed, app and edge as they were).
+ * The lineage and serial cases are carried over from terragucci's rules
+ * (`migrate.test.ts` and `compose.ts` at c493e0e).
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import type { Composition } from "../compose";
+import type { StateFile, StateResource } from "../state/exec";
+import { COMPOSE_LINEAGE, derivedLineage, mergeStates, splitState, splitStates } from "./state-merge";
+
+const FIX = join(import.meta.dirname, "..", "__fixtures__", "compose");
+const state = (name: string): StateFile => JSON.parse(readFileSync(join(FIX, name), "utf-8")) as StateFile;
+
+const made: string[] = [];
+afterAll(() => {
+  for (const d of made) rmSync(d, { recursive: true, force: true });
+});
+
+type StateComposition = Pick<Composition, "order" | "modules" | "dirs" | "roots">;
+const composition = (members: string[], dirs: Record<string, string> = {}): StateComposition => ({
+  order: members,
+  modules: new Map(members.map((m) => [m, m])),
+  dirs: new Map(Object.entries(dirs)),
+  roots: new Map(members.map((m) => [m, `roots/${m}`])),
+});
+
+const c = composition(["net", "app", "edge"]);
+const pulled = new Map<string, StateFile | null>([
+  ["net", state("state-net.json")],
+  ["app", state("state-app.json")],
+  ["edge", state("state-edge.json")],
+]);
+
+describe("mergeStates", () => {
+  const working = mergeStates(c, pulled);
+
+  test("each member's resources under module.<m>, a nested module under it, outputs as <m>__<name>", () => {
+    expect(working.resources.map((r) => `${r.module}.${r.type}.${r.name}`)).toEqual([
+      "module.net.terraform_data.vpc",
+      "module.app.module.logs.terraform_data.group",
+      "module.app.terraform_data.service",
+      "module.edge.terraform_data.dns",
+    ]);
+    expect(Object.keys(working.outputs ?? {})).toEqual(["net__vpc_id", "app__service_id", "edge__name"]);
+    expect(working.check_results).toBeNull();
+  });
+
+  test("serial 1 and a lineage derived from the members in order", () => {
+    expect(working.serial).toBe(1);
+    expect(working.lineage).toBe(derivedLineage(COMPOSE_LINEAGE, "net", "app", "edge"));
+    expect(working.lineage).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-8[0-9a-f]{3}-[0-9a-f]{12}$/);
+  });
+
+  test("the highest terraform_version pulled", () => {
+    const newer = { ...state("state-edge.json"), terraform_version: "1.11.0" };
+    expect(mergeStates(c, new Map([...pulled, ["edge", newer]])).terraform_version).toBe("1.11.0");
+  });
+
+  test("a resource whose root configures its provider names the module's provider configuration", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-compose-state-"));
+    made.push(dir);
+    mkdirSync(join(dir, "net"));
+    writeFileSync(join(dir, "net", "providers.tf"), 'provider "aws" {\n  region = "us-east-1"\n}\n');
+    const res: StateResource = { mode: "managed", type: "aws_vpc", name: "main", provider: 'provider["registry.terraform.io/hashicorp/aws"]', instances: [] };
+    const one = composition(["net", "app"], { net: join(dir, "net"), app: join(dir, "missing") });
+    const s = (r: StateResource): StateFile => ({ version: 4, serial: 1, lineage: "L", resources: [r] });
+    const merged = mergeStates(one, new Map([["net", s(res)], ["app", s(res)]]));
+    expect(merged.resources.map((r) => r.provider)).toEqual(['module.net.provider["registry.terraform.io/hashicorp/aws"]', 'provider["registry.terraform.io/hashicorp/aws"]']);
+    const back = splitState(merged, one, "net", s(res));
+    expect(back.state.resources[0]!.provider).toBe(res.provider);
+    expect(back.same).toBe(true);
+  });
+});
+
+describe("splitState", () => {
+  test("with no apply, every member's state comes back as pulled: same", () => {
+    const working = mergeStates(c, pulled);
+    for (const [m, s] of splitStates(working, c, pulled)) {
+      expect(s.same, m).toBe(true);
+      expect(s.state.resources).toEqual(pulled.get(m)!.resources.map((r) => expect.objectContaining(r)));
+      expect(s.state.outputs).toEqual(pulled.get(m)!.outputs);
+    }
+  });
+
+  test("after an apply that changed net, net alone comes back changed", () => {
+    const split = splitStates(state("working-after-apply.json"), c, pulled);
+    expect(split.get("net")!.same).toBe(false);
+    expect(split.get("app")!.same).toBe(true);
+    expect(split.get("edge")!.same).toBe(true);
+    const net = split.get("net")!.state;
+    expect((net.resources[0]!.instances![0] as any).attributes.input.value.name).toBe("core-v2");
+    expect(net.resources[0]!.module).toBeUndefined();
+    expect(split.get("app")!.state.resources.find((r) => r.name === "group")!.module).toBe("module.logs");
+  });
+
+  test("a split state keeps its pulled lineage and takes the pulled serial plus one", () => {
+    const split = splitStates(state("working-after-apply.json"), c, pulled);
+    expect(split.get("net")!.state).toMatchObject({ version: 4, lineage: "2b1f6c0a-6a1e-4c55-9f3d-7e0a1b2c3d4e", serial: 8, terraform_version: "1.10.5", check_results: null });
+    expect(split.get("app")!.state).toMatchObject({ lineage: "8d4e2f1a-3b5c-4d6e-9f7a-1c2b3d4e5f60", serial: 4 });
+    expect(split.get("edge")!.state).toMatchObject({ lineage: "c0ffee00-1234-4abc-8def-0123456789ab", serial: 13 });
+  });
+
+  test("a member with no state gets serial 1 and a lineage derived from the composed run and its root", () => {
+    const fresh = new Map<string, StateFile | null>([...pulled, ["app", null]]);
+    const split = splitStates(state("working-after-apply.json"), c, fresh);
+    expect(split.get("app")!.state).toMatchObject({ serial: 1, lineage: derivedLineage(COMPOSE_LINEAGE, "roots/app") });
+    expect(split.get("app")!.same).toBe(false);
+    expect(derivedLineage(COMPOSE_LINEAGE, "roots/app")).toBe(derivedLineage(COMPOSE_LINEAGE, "roots/app"));
+    expect(derivedLineage(COMPOSE_LINEAGE, "roots/app")).not.toBe(derivedLineage(COMPOSE_LINEAGE, "roots/edge"));
+  });
+
+  test("a member with no state that the apply left nothing in is same", () => {
+    const empty = composition(["net", "new"]);
+    const working = mergeStates(empty, new Map([["net", state("state-net.json")], ["new", null]]));
+    expect(splitState(working, empty, "new", null)).toMatchObject({ same: true, state: { resources: [], outputs: {}, serial: 1 } });
+  });
+
+  test("a module whose name starts with another's takes only its own resources", () => {
+    const two = composition(["app", "app2"]);
+    const working = mergeStates(two, new Map([["app", state("state-app.json")], ["app2", state("state-edge.json")]]));
+    expect(splitState(working, two, "app", state("state-app.json")).state.resources.map((r) => r.name)).toEqual(["group", "service"]);
+    expect(splitState(working, two, "app2", state("state-edge.json")).same).toBe(true);
+  });
+});

package/src/compose/state-merge.ts

@@ -0,0 +1,148 @@
+/**
+ * The working state of a composed run (chant#4442, epic #4419): each
+ * member's pulled state moved under `module.<m>` in one state the composed
+ * root plans and applies against, and, once the apply is done or has failed,
+ * split back into one state per member by module address.
+ *
+ * Lifted from terragucci's `packages/terragucci/src/compose.ts` at c493e0e
+ * (`mergeStates`, `splitState`) and `migrate.ts` (`derivedLineage`), with
+ * chant's {@link Composition} in place of terragucci's: members are
+ * components, and a member's directory is `Composition.dirs`. Pulling and
+ * writing the states is `../state` (#4437).
+ *
+ * The lineage and serial rules are terragucci's: a split state keeps its
+ * pulled lineage and takes the pulled serial plus one; a member with no
+ * state yet gets a lineage derived from the composed run and its root, and
+ * serial 1. The working state itself has serial 1 and a lineage derived from
+ * the members in order.
+ */
+
+import { createHash } from "node:crypto";
+import type { Composition } from "../compose";
+import type { StateFile, StateResource } from "../state/exec";
+import { rootTexts } from "./hcl";
+import { inModule, stripModule } from "./module-address";
+
+/** What the derived lineages are derived from, beside the roots. */
+export const COMPOSE_LINEAGE = "chant terraform.compose";
+
+/** A lineage in the form Terraform writes (a version 4 UUID), derived from `parts`, so the same parts always give the same lineage. */
+export function derivedLineage(...parts: string[]): string {
+  const h = createHash("sha256").update(parts.join("\n")).digest("hex");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+
+/** Whether a root's own files configure the provider of type `type` (a `provider "<type>"` block): its resources then name the module's configuration. */
+function ownsProvider(dir: string | undefined, binary: string | undefined, type: string): boolean {
+  if (!dir) return false;
+  return rootTexts(dir, binary).some((t) => (t.json ? new RegExp(`"provider"\\s*:\\s*\\{[^]*"${type}"`).test(t.text) : new RegExp(`\\bprovider\\s+"${type}"\\s*\\{`).test(t.text)));
+}
+
+function versionAbove(a: string, b: string): boolean {
+  const pa = a.split(/[.-]/).map((x) => Number.parseInt(x, 10) || 0);
+  const pb = b.split(/[.-]/).map((x) => Number.parseInt(x, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  return false;
+}
+
+/** The members whose state the working state holds, in apply order. */
+type StateComposition = Pick<Composition, "order" | "modules" | "dirs"> & Partial<Pick<Composition, "roots" | "binary">>;
+
+/**
+ * The working state: each member's resources with `module.<m>` in front of
+ * their module, each output as `<m>__<name>` (the composed root's outputs, so
+ * an output that does not change plans no change), check results left out.
+ * A resource whose root configures its provider itself names the module's
+ * provider configuration. `pulled` is by member; a member with no state
+ * (null or absent) adds nothing. The highest `terraform_version` pulled wins.
+ */
+export function mergeStates(c: StateComposition, pulled: ReadonlyMap<string, StateFile | null>): StateFile {
+  const resources: StateResource[] = [];
+  const outputs: Record<string, unknown> = {};
+  let tfVersion: string | undefined;
+  for (const member of c.order) {
+    const s = pulled.get(member);
+    if (!s) continue;
+    const m = c.modules.get(member)!;
+    if (s.terraform_version && (!tfVersion || versionAbove(s.terraform_version, tfVersion))) tfVersion = s.terraform_version;
+    for (const res of s.resources) {
+      const provider = typeof res.provider === "string" ? res.provider : undefined;
+      const type = provider?.match(/provider\["([^"]+)"\]/)?.[1]?.split("/").pop();
+      const own = provider && type && !provider.startsWith("module.") && ownsProvider(c.dirs.get(member), c.binary, type);
+      resources.push({
+        ...structuredClone(res),
+        module: res.module ? `module.${m}.${res.module}` : `module.${m}`,
+        ...(provider ? { provider: own || provider.startsWith("module.") ? `module.${m}.${provider}` : provider } : {}),
+      });
+    }
+    for (const [k, v] of Object.entries(s.outputs ?? {})) outputs[`${m}__${k}`] = structuredClone(v);
+  }
+  return { version: 4, terraform_version: tfVersion ?? "1.0.0", serial: 1, lineage: derivedLineage(COMPOSE_LINEAGE, ...c.order), outputs, resources, check_results: null };
+}
+
+/** JSON with every object's keys sorted, so two objects that differ only in key order print the same. */
+function stable(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(stable).join(",")}]`;
+  if (v && typeof v === "object") {
+    return `{${Object.keys(v)
+      .filter((k) => (v as Record<string, unknown>)[k] !== undefined)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stable((v as Record<string, unknown>)[k])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(v) ?? "null";
+}
+
+/**
+ * A state's resources and outputs in one order, for comparing two states.
+ * Keys are sorted too: a split resource in a nested module carries `module`
+ * after its other keys, where `state pull` prints it first.
+ */
+const canonical = (s: Pick<StateFile, "resources" | "outputs">): string =>
+  JSON.stringify({
+    resources: [...s.resources].map(stable).sort(),
+    outputs: stable(s.outputs ?? {}),
+  });
+
+/** One member's state out of the working state, and whether it holds what was pulled. */
+export interface SplitState {
+  state: StateFile;
+  /** It holds what was pulled (for a member with no state: nothing), so there is nothing to write. */
+  same: boolean;
+}
+
+/**
+ * One member's state out of the working state: its resources with the module
+ * taken off, its outputs from `<m>__*`, its pulled lineage and its pulled
+ * serial plus one (a member with no state yet gets a lineage of its own,
+ * derived from its root, and serial 1). `same` when it holds what was pulled.
+ */
+export function splitState(working: StateFile, c: StateComposition, member: string, pulled: StateFile | null): SplitState {
+  const m = c.modules.get(member)!;
+  const resources: StateResource[] = [];
+  for (const res of working.resources) {
+    if (!inModule(res.module, m)) continue;
+    const module = res.module === `module.${m}` ? undefined : stripModule(res.module!);
+    const { module: _m, ...rest } = structuredClone(res);
+    const provider = typeof rest.provider === "string" && inModule(rest.provider, m) ? stripModule(rest.provider) : rest.provider;
+    resources.push({ ...rest, ...(module ? { module } : {}), ...(provider !== undefined ? { provider } : {}) });
+  }
+  const outputs: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(working.outputs ?? {})) if (k.startsWith(`${m}__`)) outputs[k.slice(m.length + 2)] = v;
+  const state: StateFile = {
+    version: 4,
+    terraform_version: working.terraform_version,
+    serial: (pulled?.serial ?? 0) + 1,
+    lineage: pulled?.lineage || derivedLineage(COMPOSE_LINEAGE, c.roots?.get(member) ?? member),
+    outputs,
+    resources,
+    check_results: null,
+  };
+  const same = pulled ? canonical(state) === canonical(pulled) : resources.length === 0 && Object.keys(outputs).length === 0;
+  return { state, same };
+}
+
+/** Every member's split state, by member, in apply order. */
+export function splitStates(working: StateFile, c: StateComposition, pulled: ReadonlyMap<string, StateFile | null>): Map<string, SplitState> {
+  return new Map(c.order.map((member) => [member, splitState(working, c, member, pulled.get(member) ?? null)] as const));
+}

package/src/compose.test.ts

@@ -0,0 +1,248 @@
+/**
+ * Which roots a change composes, in what order, and why the others fall back
+ * (#4438). Each case writes the smallest project that produces it.
+ */
+
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import type { DriverComponent, DriverPhase } from "@intentius/chant/components/driver";
+import { stackOutput } from "@intentius/chant/components/component";
+import { composeOff, compositionFor, compositionIfEnabled, fallbackLine, moduleNames, withPlanFailed, type CompositionInput } from "./compose";
+import type { TerraformConfig } from "./config";
+import { LOCKS } from "./state/backend";
+
+const made: string[] = [];
+afterAll(() => {
+  for (const d of made) rmSync(d, { recursive: true, force: true });
+});
+
+/** A project with `files` under it, each path relative to it. */
+function project(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-compose-"));
+  made.push(dir);
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    writeFileSync(join(dir, path), text);
+  }
+  return dir;
+}
+
+const EMPTY = 'resource "terraform_data" "x" {}\n';
+
+/** A component whose deploy is one terraform-apply step. */
+function tf(name: string, opts: { root?: string; dependsOn?: string[]; vars?: Record<string, unknown>; before?: DriverPhase["steps"] } = {}): DriverComponent {
+  return {
+    name,
+    dependsOn: opts.dependsOn ?? [],
+    deploy: [{ phase: "Apply", steps: [...(opts.before ?? []), { kind: "terraform-apply", root: opts.root ?? name, ...(opts.vars ? { vars: opts.vars } : {}) }] }],
+  };
+}
+
+/** Roots `names`, each at `roots/<name>`. */
+const rootsOf = (...names: string[]): TerraformConfig["roots"] => Object.fromEntries(names.map((n) => [n, { dir: `roots/${n}` }]));
+
+function input(projectRoot: string, components: DriverComponent[], over: Omit<Partial<CompositionInput>, "terraform"> & { terraform?: Partial<TerraformConfig> } = {}): CompositionInput {
+  const { terraform, ...rest } = over;
+  const roots = rootsOf(...components.flatMap((c) => c.deploy.flatMap((p) => p.steps)).flatMap((s) => {
+      const root = (s as { root?: unknown }).root;
+      return typeof root === "string" ? [root] : [];
+    }));
+  return { projectRoot, components, env: {}, terraform: { roots, compose: { enabled: true }, ...terraform }, ...rest };
+}
+
+/** Three independent roots a, b and c. */
+const threeRoots = (extra: Record<string, string> = {}): string => project({ "roots/a/main.tf": EMPTY, "roots/b/main.tf": EMPTY, "roots/c/main.tf": EMPTY, ...extra });
+
+describe("compositionFor: order, modules and reads", () => {
+  test("B reads A and C reads B: order A, B, C, module names valid HCL identifiers and stable across runs", () => {
+    const dir = project({ "roots/net-core/main.tf": EMPTY, "roots/2app/main.tf": EMPTY, "roots/edge.v1/main.tf": EMPTY });
+    const components = [
+      tf("c", { root: "edge.v1", dependsOn: ["b"], vars: { app_url: stackOutput("b", "url") } }),
+      tf("a", { root: "net-core" }),
+      tf("b", { root: "2app", dependsOn: ["a"], vars: { vpc_id: stackOutput("a", "vpc_id") } }),
+    ];
+    const first = compositionFor(input(dir, components));
+    expect(first.fallback).toBeUndefined();
+    expect(first.order).toEqual(["a", "b", "c"]);
+    for (const name of first.modules.values()) expect(name).toMatch(/^[A-Za-z_][A-Za-z0-9_]*$/);
+    expect(Object.fromEntries(first.modules)).toEqual({ a: "net_core", b: "r_2app", c: "edge_v1" });
+    const again = compositionFor(input(dir, [...components].reverse()));
+    expect(Object.fromEntries(again.modules)).toEqual(Object.fromEntries(first.modules));
+    expect(again.order).toEqual(first.order);
+  });
+
+  test("moduleNames takes `_2` on a clash, in name order", () => {
+    expect(Object.fromEntries(moduleNames(["a-b", "a_b", "."]))).toEqual({ ".": "root", "a-b": "a_b", a_b: "a_b_2" });
+  });
+
+  test("a read through vars and a read through terraform_remote_state both appear in reads", () => {
+    const dir = project({
+      "roots/a/main.tf": EMPTY,
+      "roots/b/main.tf": 'data "terraform_remote_state" "net" {\n  backend = "local"\n  config = {\n    path = "../a/terraform.tfstate"\n  }\n}\n',
+      "roots/c/main.tf": EMPTY,
+    });
+    const c = compositionFor(input(dir, [tf("a"), tf("b", { dependsOn: ["a"] }), tf("c", { dependsOn: ["a"], vars: { vpc: stackOutput("a", "vpc_id") } })]));
+    expect(c.fallback).toBeUndefined();
+    expect(c.reads.get("b")).toEqual([{ via: "remote-state", upstream: "a", name: "net" }]);
+    expect(c.reads.get("c")).toEqual([{ via: "vars", upstream: "a", variable: "vpc", output: "vpc_id" }]);
+    expect(c.order[0]).toBe("a");
+  });
+});
+
+describe("compositionFor: each fallback", () => {
+  test("too-many-roots", () => {
+    const c = compositionFor(input(threeRoots(), [tf("a"), tf("b"), tf("c")], { terraform: { compose: { enabled: true, max: 2 } } }));
+    expect(c.members).toEqual([]);
+    expect(c.fallback).toEqual({ kind: "too-many-roots", reason: "this change composes 3 roots, more than `terraform.compose.max` (2)" });
+  });
+
+  test("one-root", () => {
+    const c = compositionFor(input(project({ "roots/a/main.tf": EMPTY }), [tf("a")]));
+    expect(c.fallback).toEqual({ kind: "one-root", member: "a", reason: "this change reaches one root, `a`, which applies in its own run" });
+    expect(fallbackLine(c.fallback!)).toBe("**Applies in waves** (`terraform.compose`): this change reaches one root, `a`, which applies in its own run.");
+  });
+
+  test("binary", () => {
+    const c = compositionFor(input(threeRoots(), [tf("a"), tf("b"), tf("c")], { binary: (m) => ({ name: "tofu", version: m === "c" ? "1.9.0" : "1.8.0" }) }));
+    expect(c.members).toEqual(["a", "b"]);
+    expect(c.fallbacks).toEqual([{ kind: "binary", member: "c", reason: "`c` runs tofu 1.9.0 and `a` tofu 1.8.0, and one run has one binary" }]);
+  });
+
+  test("identity", () => {
+    const c = compositionFor(input(threeRoots(), [tf("a"), tf("b"), tf("c")], { identity: (m) => (m === "c" ? "role/other" : "role/apply") }));
+    expect(c.members).toEqual(["a", "b"]);
+    expect(c.fallbacks).toEqual([{ kind: "identity", member: "c", reason: "`c` applies under another cloud identity (`ci.identity.cloud`) than `a`, `b`, and one run has one set of credentials" }]);
+  });
+
+  test("workspace", () => {
+    const dir = threeRoots();
+    const c = compositionFor(input(dir, [tf("a"), tf("b"), tf("c")], { terraform: { roots: { ...rootsOf("a", "b"), c: { dir: "roots/c", workspace: "prod" } } } }));
+    expect(c.fallbacks).toEqual([{ kind: "workspace", member: "c", reason: "`c` plans in workspace prod, and a composed run plans in default" }]);
+  });
+
+  test("backend: a type chant does not lock", () => {
+    const c = compositionFor(input(threeRoots({ "roots/c/main.tf": 'terraform {\n  backend "consul" {\n    path = "c"\n  }\n}\n' }), [tf("a"), tf("b"), tf("c")]));
+    expect(c.fallbacks).toEqual([{ kind: "backend", member: "c", reason: `\`c\`: the root's backend is consul; ${LOCKS}` }]);
+  });
+
+  test("backend: s3 with no lock file", () => {
+    const c = compositionFor(input(threeRoots({ "roots/c/main.tf": 'terraform {\n  backend "s3" {\n    bucket = "b"\n    key = "c"\n  }\n}\n' }), [tf("a"), tf("b"), tf("c")]));
+    expect(c.fallbacks).toEqual([{ kind: "backend", member: "c", reason: `\`c\`: the s3 backend takes no lock file (use_lockfile = true is unset), so chant cannot hold its lock; ${LOCKS}` }]);
+  });
+
+  test("provider-lock", () => {
+    const lock = (v: string): string => `provider "registry.terraform.io/hashicorp/aws" {\n  version = "${v}"\n}\n`;
+    const c = compositionFor(input(threeRoots({ "roots/a/.terraform.lock.hcl": lock("5.0.0"), "roots/c/.terraform.lock.hcl": lock("5.1.0") }), [tf("a"), tf("b"), tf("c")]));
+    expect(c.fallbacks).toEqual([{ kind: "provider-lock", member: "c", reason: "`c` locks registry.terraform.io/hashicorp/aws at 5.1.0 and `a` at 5.0.0, and one run installs one version" }]);
+  });
+
+  test("cli-args", () => {
+    const c = compositionFor(input(threeRoots(), [tf("a"), tf("b"), tf("c")], { env: { TF_CLI_ARGS_plan: "-target=aws_s3_bucket.x" } }));
+    expect(c.members).toEqual([]);
+    expect(c.fallback).toEqual({ kind: "cli-args", reason: "`TF_CLI_ARGS_plan` carries `-target`, which names a root's own addresses or variables, not the composed run's" });
+  });
+
+  test("read", () => {
+    const dir = threeRoots({
+      "roots/b/main.tf": 'data "terraform_remote_state" "net" {\n  count = 1\n  backend = "local"\n  config = {\n    path = "../a/terraform.tfstate"\n  }\n}\n',
+    });
+    const c = compositionFor(input(dir, [tf("a"), tf("b", { dependsOn: ["a"] }), tf("c")]));
+    expect(c.members).toEqual(["a", "c"]);
+    expect(c.fallbacks).toEqual([{ kind: "read", member: "b", reason: "`b` reads `a` through a block with count or for_each (`data.terraform_remote_state.net`)" }]);
+  });
+
+  test("order-only: two roots ordered only by dependsOn, with no read", () => {
+    const c = compositionFor(input(threeRoots(), [tf("a"), tf("b", { dependsOn: ["a"] }), tf("c")]));
+    expect(c.members).toEqual(["a", "c"]);
+    expect(c.fallbacks).toEqual([
+      { kind: "order-only", member: "b", reason: "`b` depends on `a` (`dependsOn`) with no read between them, and a module with its own providers takes no depends_on" },
+    ]);
+  });
+
+  test("import", () => {
+    const c = compositionFor(input(threeRoots({ "roots/c/main.tf": 'import {\n  to = terraform_data.x\n  id = var.id\n}\n' }), [tf("a"), tf("b"), tf("c")]));
+    expect(c.fallbacks).toEqual([{ kind: "import", member: "c", reason: "an `import` block of `c` takes no literal string `id`, so it cannot be lifted into the composed root" }]);
+  });
+
+  test("path", () => {
+    const c = compositionFor(input(threeRoots({ "roots/c/main.tf": 'locals {\n  here = path.root\n}\n' }), [tf("a"), tf("b"), tf("c")]));
+    expect(c.fallbacks).toEqual([{ kind: "path", member: "c", reason: "`c` uses `path.root` or `path.cwd`, which would name the composed root instead of `roots/c`" }]);
+  });
+
+  test("plan-failed", () => {
+    const c = withPlanFailed(compositionFor(input(threeRoots(), [tf("a"), tf("b"), tf("c")])), "Error: boom\nat line 3");
+    expect(c.members).toEqual([]);
+    expect(c.fallback).toEqual({ kind: "plan-failed", reason: "the composed plan failed: Error: boom" });
+  });
+
+  test("targets: a member given targets falls back with its own kind", () => {
+    const c = compositionFor(input(threeRoots(), [tf("a"), tf("b"), tf("c")], { targets: { c: ["aws_s3_bucket.x"] } }));
+    expect(c.members).toEqual(["a", "b"]);
+    expect(c.fallbacks).toEqual([{ kind: "targets", member: "c", reason: "`c` is given 1 target (`--target`), and a composed run plans each member whole" }]);
+    expect(fallbackLine(c.fallbacks[0]!)).toBe("**`c` applies in waves** (`terraform.compose`): `c` is given 1 target (`--target`), and a composed run plans each member whole.");
+  });
+
+  test("steps: a deploy of more than the one step", () => {
+    const c = compositionFor(input(threeRoots(), [tf("a"), tf("b"), tf("c", { before: [{ kind: "gate", gate: "ok" }] })]));
+    expect(c.fallbacks).toEqual([{ kind: "steps", member: "c", reason: "`c`'s deploy has 2 steps, and only a component whose deploy is one terraform-apply step composes" }]);
+  });
+
+  test("same-root", () => {
+    const c = compositionFor(input(threeRoots(), [tf("a"), tf("b"), tf("c"), tf("d", { root: "c" })]));
+    expect(c.members).toEqual(["a", "b", "c"]);
+    expect(c.fallbacks).toEqual([{ kind: "same-root", member: "d", reason: "`d` deploys root `c`, which `c` deploys too, and a composed run calls each root once" }]);
+  });
+
+  test("split: a component of another kind between two roots", () => {
+    const stack: DriverComponent = { name: "s", dependsOn: ["a"], deploy: [{ phase: "Deploy", steps: [{ kind: "cfn-deploy", vars: { v: stackOutput("a", "vpc_id") } }] }] };
+    const c = compositionFor(input(threeRoots(), [tf("a"), tf("b"), stack, tf("c", { dependsOn: ["s"], vars: { q: stackOutput("s", "QueueUrl") } })]));
+    expect(c.members).toEqual(["a", "b"]);
+    expect(c.fallbacks).toEqual([
+      { kind: "split", member: "c", reason: "`c` depends on `a` through `s`, a cfn-deploy component that applies between them" },
+    ]);
+  });
+
+  test("split: a root left out between two roots", () => {
+    const c = compositionFor(
+      input(threeRoots(), [tf("a"), tf("b", { dependsOn: ["a"], vars: { v: stackOutput("a", "x") } }), tf("c", { dependsOn: ["b"], vars: { v: stackOutput("b", "y") } })], {
+        targets: { b: ["terraform_data.x"] },
+      }),
+    );
+    expect(c.fallbacks.map((f) => f.kind)).toEqual(["targets", "split"]);
+    expect(c.fallbacks[1]).toEqual({ kind: "split", member: "c", reason: "`c` depends on `a` through `b`, which is left out of the composed run and applies between them" });
+    expect(c.fallback).toEqual({ kind: "one-root", member: "a", reason: "only `a` of this change can compose, and one root applies in its own run" });
+  });
+});
+
+describe("terraform.compose is off by default", () => {
+  test("compositionIfEnabled returns nothing with the setting unset or off", () => {
+    const dir = threeRoots();
+    const base = input(dir, [tf("a"), tf("b"), tf("c")]);
+    expect(compositionIfEnabled({ ...base, terraform: { roots: base.terraform.roots } })).toBeUndefined();
+    expect(compositionIfEnabled({ ...base, terraform: { roots: base.terraform.roots, compose: { enabled: false } } })).toBeUndefined();
+    expect(compositionIfEnabled(base)?.members).toEqual(["a", "b", "c"]);
+  });
+
+  test("composeOff answers core's groupFallback with kind off until the setting is on", () => {
+    expect(composeOff({ roots: {} })).toEqual({ kind: "off", reason: "`terraform.compose` is not enabled" });
+    expect(composeOff({ roots: {}, compose: { enabled: false } })?.kind).toBe("off");
+    expect(composeOff({ roots: {}, compose: { enabled: true } })).toBeUndefined();
+  });
+
+  test("nothing in the lexicon calls compositionFor except through compositionIfEnabled", () => {
+    const src = dirname(fileURLToPath(import.meta.url));
+    const callers: string[] = [];
+    const walk = (dir: string): void => {
+      for (const n of readdirSync(dir)) {
+        const p = join(dir, n);
+        if (statSync(p).isDirectory()) walk(p);
+        else if (/\.ts$/.test(n) && !/\.test\.ts$/.test(n) && p !== join(src, "compose.ts") && /\bcompositionFor\s*\(/.test(readFileSync(p, "utf-8"))) callers.push(p);
+      }
+    };
+    walk(src);
+    expect(callers).toEqual([]);
+  });
+});