@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/src/compose/slice.test.ts

@@ -0,0 +1,184 @@
+/**
+ * The composed plan cut back into one plan per member (#4442), on recorded
+ * `show -json` fixtures in `../__fixtures__/compose`: a composed plan of
+ * three modules beside each root's plan alone on the same state, and a
+ * composed plan where one member reads an output another creates.
+ */
+
+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, ComposedRead } from "../compose";
+import { terraformChangeSetPart } from "../change-set";
+import { terraformPlannedOutputs } from "../components/capability-plugin";
+import { terraformPlanShape } from "../plan-shape";
+import { slicePlan as reportSlicePlan } from "../report";
+import { moduleChanges, stripChange, stripModule, topModule } from "./module-address";
+import { composedMemberPlans, composedReads, planCounts, slicePlan, sliceText } from "./slice";
+
+const FIX = join(import.meta.dirname, "..", "__fixtures__", "compose");
+const fixture = (name: string): unknown => JSON.parse(readFileSync(join(FIX, name), "utf-8"));
+
+const made: string[] = [];
+afterAll(() => {
+  for (const d of made) rmSync(d, { recursive: true, force: true });
+});
+
+/** A composition of `members` in that order, each its own module and root, reading as `reads` says. */
+function composition(members: string[], reads: Record<string, ComposedRead[]> = {}, dirs: Record<string, string> = {}): Composition {
+  return {
+    candidates: [...members].sort(),
+    members: [...members].sort(),
+    order: members,
+    max: 10,
+    roots: new Map(members.map((m) => [m, m])),
+    dirs: new Map(Object.entries(dirs)),
+    modules: new Map(members.map((m) => [m, m])),
+    reads: new Map(Object.entries(reads)),
+    fallbacks: [],
+  };
+}
+
+describe("one change-set part per member", () => {
+  const composed = fixture("three-composed.plan.json");
+  const c = composition(["net", "app", "edge"], { app: [{ via: "vars", upstream: "net", variable: "vpc_id", output: "vpc_id" }] });
+  const plans = composedMemberPlans(c, composed);
+
+  test.each(["net", "app", "edge"])("%s's part of the composed plan is the part its root planned alone gives", (m) => {
+    const alone = fixture(`three-${m}.plan.json`);
+    expect(plans[m]!.changeSet).toEqual(terraformChangeSetPart({ member: m, plan: alone }));
+    expect(plans[m]!.planDigest).toBe(terraformChangeSetPart({ member: m, plan: alone }).member.planDigest);
+    expect(plans[m]!.outputs).toEqual(terraformPlannedOutputs(alone));
+    expect(plans[m]!.shape).toEqual(terraformPlanShape(alone, m));
+  });
+
+  test("a slice reads as the root alone: addresses, module addresses, outputs, values and configuration unprefixed", () => {
+    const app = slicePlan(composed, "app") as any;
+    const alone = fixture("three-app.plan.json") as any;
+    expect(app.resource_changes).toEqual(alone.resource_changes);
+    expect(app.output_changes).toEqual(alone.output_changes);
+    expect(app.planned_values.root_module).toEqual(alone.planned_values.root_module);
+    expect(app.planned_values.outputs).toEqual(alone.planned_values.outputs);
+    expect(app.configuration.root_module).toEqual(alone.configuration.root_module);
+    const net = slicePlan(composed, "net") as any;
+    expect(net.prior_state.values.root_module).toEqual((fixture("three-net.plan.json") as any).prior_state.values.root_module);
+    expect(net.relevant_attributes).toEqual([{ resource: "terraform_data.vpc", attribute: ["id"] }]);
+    expect(net.checks).toBeUndefined();
+    expect(net.variables).toBeUndefined();
+  });
+
+  test("the counts are each member's own, a no-op not counted", () => {
+    expect(plans.net!.counts).toEqual({ add: 0, change: 1, destroy: 0, changes: 1, destroys: 0 });
+    expect(plans.app!.counts).toEqual({ add: 2, change: 0, destroy: 0, changes: 2, destroys: 0 });
+    expect(plans.edge!.counts).toEqual(planCounts(fixture("three-edge.plan.json")));
+    expect(plans.edge!.counts.changes).toBe(0);
+  });
+
+  test("a known read is a read with nothing unknown, and the reader's shape lists no unknown inputs", () => {
+    expect(plans.app!.reads).toEqual([{ upstream: "net", via: "vars", name: "vpc_id", outputs: ["vpc_id"], unknown: [] }]);
+    expect(plans.app!.shape.unknownInputs).toEqual([]);
+    expect(plans.net!.reads).toEqual([]);
+  });
+});
+
+describe("an output one member creates and another reads", () => {
+  const composed = fixture("unknown-composed.plan.json");
+
+  test("is unknown in the upstream's planned outputs and in the reader's reads and shape", () => {
+    const c = composition(["queue", "worker"], { worker: [{ via: "vars", upstream: "queue", variable: "queue_id", output: "queue_id" }] });
+    const plans = composedMemberPlans(c, composed);
+    expect(plans.queue!.outputs).toEqual({ known: { queue_name: "jobs" }, unknown: ["queue_id"] });
+    expect(plans.worker!.reads).toEqual([{ upstream: "queue", via: "vars", name: "queue_id", outputs: ["queue_id"], unknown: ["queue_id"] }]);
+    expect(plans.worker!.shape.unknownInputs).toEqual(["queue.queue_id"]);
+    expect(plans.worker!.shape.entries).toEqual([expect.objectContaining({ logicalId: "terraform_data.consumer", action: "create", unknown: expect.arrayContaining(["input"]) })]);
+  });
+
+  test("a read of a known output of the same upstream is not unknown", () => {
+    const c = composition(["queue", "worker"], { worker: [{ via: "vars", upstream: "queue", variable: "name", output: "queue_name" }] });
+    expect(composedMemberPlans(c, composed).worker!.reads).toEqual([{ upstream: "queue", via: "vars", name: "name", outputs: ["queue_name"], unknown: [] }]);
+  });
+
+  test("a terraform_remote_state block names the outputs its root's files read; reading the whole object counts every output", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-compose-slice-"));
+    made.push(dir);
+    mkdirSync(join(dir, "worker"));
+    mkdirSync(join(dir, "whole"));
+    writeFileSync(join(dir, "worker", "main.tf"), 'data "terraform_remote_state" "q" {}\nresource "terraform_data" "consumer" { input = data.terraform_remote_state.q.outputs.queue_id }\n');
+    writeFileSync(join(dir, "whole", "main.tf"), 'data "terraform_remote_state" "q" {}\nresource "terraform_data" "consumer" { input = data.terraform_remote_state.q.outputs }\n');
+    const outputs = new Map([["queue", terraformPlannedOutputs(slicePlan(composed, "queue"))]]);
+    const read: ComposedRead = { via: "remote-state", upstream: "queue", name: "q" };
+    const reads = composedReads({ members: ["whole", "worker"], reads: new Map([["worker", [read]], ["whole", [read]]]), dirs: new Map([["worker", join(dir, "worker")], ["whole", join(dir, "whole")]]) }, outputs);
+    expect(reads.get("worker")).toEqual([{ upstream: "queue", via: "remote-state", name: "q", outputs: ["queue_id"], unknown: ["queue_id"] }]);
+    expect(reads.get("whole")).toEqual([{ upstream: "queue", via: "remote-state", name: "q", unknown: ["queue_id"] }]);
+  });
+
+  test("a remote state read the composed root rewrote to var.chant_read_<label> names the same outputs", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-compose-slice-"));
+    made.push(dir);
+    writeFileSync(join(dir, "main.tf"), 'resource "terraform_data" "consumer" { input = var.chant_read_q.outputs.queue_id }\n');
+    writeFileSync(join(dir, "chant_compose.tf"), 'variable "chant_read_q" {\n  type = any\n}\n');
+    const outputs = new Map([["queue", terraformPlannedOutputs(slicePlan(composed, "queue"))]]);
+    const reads = composedReads({ members: ["worker"], reads: new Map([["worker", [{ via: "remote-state", upstream: "queue", name: "q" } as ComposedRead]]]), dirs: new Map([["worker", dir]]) }, outputs);
+    expect(reads.get("worker")).toEqual([{ upstream: "queue", via: "remote-state", name: "q", outputs: ["queue_id"], unknown: ["queue_id"] }]);
+  });
+});
+
+describe("one strip function for the report and the slicer", () => {
+  test("a top module, with or without an index, is taken off; an address in no module is as it was", () => {
+    expect(topModule("module.app.module.logs.terraform_data.group")).toBe("app");
+    expect(stripModule("module.app.module.logs.terraform_data.group")).toBe("module.logs.terraform_data.group");
+    expect(stripModule('module.net["a"].terraform_data.vpc')).toBe("terraform_data.vpc");
+    expect(stripModule("module.net")).toBe("");
+    expect(stripModule("terraform_data.vpc")).toBe("terraform_data.vpc");
+    expect(stripChange({ address: "module.app.terraform_data.service", module_address: "module.app" })).toEqual({ address: "terraform_data.service" });
+  });
+
+  test("report.ts's slice and the composed slice give the same resource changes", () => {
+    const composed = fixture("three-composed.plan.json") as any;
+    for (const m of ["net", "app", "edge"]) {
+      const fromReport = reportSlicePlan(composed, m).resource_changes;
+      expect(fromReport).toEqual((slicePlan(composed, m) as any).resource_changes);
+      expect(fromReport).toEqual(moduleChanges(composed.resource_changes, m));
+    }
+  });
+});
+
+describe("sliceText", () => {
+  const text = [
+    "Terraform used the selected providers to generate the following execution",
+    "plan. Resource actions are indicated with the following symbols:",
+    "  + create",
+    "  ~ update in-place",
+    "",
+    "Terraform will perform the following actions:",
+    "",
+    "  # module.app.terraform_data.service will be created",
+    '  + resource "terraform_data" "service" {',
+    "      + id     = (known after apply)",
+    "    }",
+    "",
+    "  # module.net.terraform_data.vpc will be updated in-place",
+    '  ~ resource "terraform_data" "vpc" {',
+    '        id     = "6f2b6c1e"',
+    "    }",
+    "",
+    "Plan: 1 to add, 1 to change, 0 to destroy.",
+    "",
+    "Changes to Outputs:",
+    "  + app__service_id = (known after apply)",
+    "",
+  ].join("\n");
+
+  test("a member's resource blocks unprefixed, its counts and its outputs by their own names", () => {
+    const s = sliceText(text, "app", { add: 1, change: 0, destroy: 0 });
+    expect(s).toContain("  # terraform_data.service will be created");
+    expect(s).not.toContain("terraform_data.vpc");
+    expect(s).toContain("Plan: 1 to add, 0 to change, 0 to destroy.");
+    expect(s).toContain("Changes to Outputs:\n  + service_id = (known after apply)");
+  });
+
+  test("a member with nothing in the text says it has no changes", () => {
+    expect(sliceText(text, "edge", { add: 0, change: 0, destroy: 0 })).toContain("No changes. Its part of the composed run matches the configuration.");
+  });
+});

package/src/compose/slice.ts

@@ -0,0 +1,290 @@
+/**
+ * The composed plan cut back into one plan per member (chant#4442, epic
+ * #4419): each member's part of the composed root's `show -json`, as if the
+ * member's root had planned alone, and from it the member's change-set part,
+ * planned outputs, plan shape and reads of other members, so the change set,
+ * the report, policy and behold see each component and not one composed
+ * root.
+ *
+ * Lifted from terragucci's `packages/terragucci/src/compose.ts` at c493e0e
+ * (`slicePlan`, `sliceText`, `planCounts`, `composedReportReads`). Addresses
+ * are stripped by `./module-address`, which `chant terraform report` uses
+ * too. The outputs are `<m>__<name>` in the composed root, as #4441 writes
+ * them and terragucci did.
+ */
+
+import type { ChangeSetPlanner, ChangeSetPart } from "@intentius/chant/change-set";
+import type { CapabilityPlan, PlannedOutputs } from "@intentius/chant/components/capability";
+import type { PlanShape } from "@intentius/chant/components/covered-round";
+import type { Composition, ComposedRead } from "../compose";
+import { terraformChangeSetPart } from "../change-set";
+import { terraformPlannedOutputs } from "../components/capability-plugin";
+import { terraformPlanShape } from "../plan-shape";
+import { rootTexts } from "./hcl";
+import { inModule, moduleChanges, stripModule, topModule } from "./module-address";
+import { READ_VAR_PREFIX } from "./root";
+
+type Json = Record<string, unknown>;
+const isObj = (v: unknown): v is Json => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** The outputs of module `m` among a composed root's, by their own names. */
+export function moduleOutputs(outputs: unknown, m: string): Json {
+  if (!isObj(outputs)) return {};
+  return Object.fromEntries(Object.entries(outputs).filter(([k]) => k.startsWith(`${m}__`)).map(([k, v]) => [k.slice(m.length + 2), v]));
+}
+
+/** A module's part of `planned_values` or `prior_state.values`: its child module as the root module, addresses unprefixed. */
+export function moduleValues(values: unknown, m: string, outputs: Json): Json | undefined {
+  if (!isObj(values)) return undefined;
+  const root = isObj(values.root_module) ? values.root_module : {};
+  const child = (Array.isArray(root.child_modules) ? root.child_modules : []).find((x) => isObj(x) && x.address === `module.${m}`) as Json | undefined;
+  const strip = (mod: Json): Json => ({
+    ...mod,
+    ...(Array.isArray(mod.resources) ? { resources: mod.resources.map((x) => (isObj(x) ? { ...x, address: stripModule(String(x.address)) } : x)) } : {}),
+    ...(Array.isArray(mod.child_modules) ? { child_modules: mod.child_modules.map((x) => (isObj(x) ? strip({ ...x, address: stripModule(String(x.address)) }) : x)) } : {}),
+  });
+  const { address: _a, ...rest } = child ? strip(child) : { address: undefined };
+  return { ...values, outputs, root_module: rest };
+}
+
+/**
+ * One member's part of the composed plan's `show -json`, as if it had
+ * planned alone: its resource changes and drift with `module.<m>.` taken off,
+ * its outputs by their own names, its planned values, prior state and
+ * configuration as the root module. `checks` and `variables` (the composed
+ * root's) are left out.
+ */
+export function slicePlan(plan: unknown, m: string): unknown {
+  if (!isObj(plan)) return plan;
+  const out: Json = { ...plan };
+  if (Array.isArray(plan.resource_changes)) out.resource_changes = moduleChanges(plan.resource_changes, m);
+  if (Array.isArray(plan.resource_drift)) out.resource_drift = moduleChanges(plan.resource_drift, m);
+  if (isObj(plan.output_changes)) out.output_changes = moduleOutputs(plan.output_changes, m);
+  if (isObj(plan.planned_values)) out.planned_values = moduleValues(plan.planned_values, m, moduleOutputs(plan.planned_values.outputs, m));
+  if (isObj(plan.prior_state)) {
+    const values = isObj(plan.prior_state.values) ? plan.prior_state.values : undefined;
+    out.prior_state = { ...plan.prior_state, ...(values ? { values: moduleValues(values, m, moduleOutputs(values.outputs, m)) } : {}) };
+  }
+  if (isObj(plan.configuration)) {
+    const root = isObj(plan.configuration.root_module) ? plan.configuration.root_module : {};
+    const call = isObj(root.module_calls) && isObj(root.module_calls[m]) ? (root.module_calls[m] as Json) : undefined;
+    const pc = isObj(plan.configuration.provider_config) ? plan.configuration.provider_config : {};
+    out.configuration = {
+      ...plan.configuration,
+      provider_config: Object.fromEntries(
+        Object.entries(pc).flatMap(([k, v]) =>
+          k.startsWith(`module.${m}:`) ? [[k.slice(`module.${m}:`.length), isObj(v) ? { ...v, module_address: undefined } : v]] : k.includes(":") ? [] : [[k, v]],
+        ),
+      ),
+      root_module: isObj(call?.module) ? call!.module : {},
+    };
+  }
+  if (Array.isArray(plan.relevant_attributes)) {
+    out.relevant_attributes = plan.relevant_attributes
+      .filter((x) => isObj(x) && inModule(String(x.resource), m) && String(x.resource) !== `module.${m}`)
+      .map((x) => ({ ...(x as Json), resource: stripModule(String((x as Json).resource)) }));
+  }
+  delete out.checks;
+  delete out.variables;
+  return out;
+}
+
+/** A plan's counts as the binary's `Plan:` line gives them, and how many changes and destroys it holds. */
+export interface PlanCounts {
+  add: number;
+  change: number;
+  destroy: number;
+  changes: number;
+  destroys: number;
+}
+
+/** A plan's counts as the binary's `Plan:` line gives them. A no-op or read is not a change. */
+export function planCounts(plan: unknown): PlanCounts {
+  const rc = isObj(plan) && Array.isArray(plan.resource_changes) ? plan.resource_changes : [];
+  let add = 0;
+  let change = 0;
+  let destroy = 0;
+  let changes = 0;
+  for (const r of rc) {
+    const a: string[] = isObj(r) && isObj(r.change) && Array.isArray(r.change.actions) ? (r.change.actions as string[]) : [];
+    if (a.every((x) => x === "no-op" || x === "read")) continue;
+    changes++;
+    if (a.includes("create")) add++;
+    if (a.includes("delete")) destroy++;
+    if (a.includes("update")) change++;
+  }
+  return { add, change, destroy, changes, destroys: destroy };
+}
+
+/**
+ * One member's part of the composed plan's `show` text: the text before the
+ * actions, each resource block of its module with `module.<m>.` taken off,
+ * its line of counts, and its outputs by their own names.
+ */
+export function sliceText(text: string, m: string, counts: { add: number; change: number; destroy: number }): string {
+  const lines = text.split("\n");
+  const head: string[] = [];
+  const blocks: string[][] = [];
+  const outs: string[] = [];
+  let i = 0;
+  for (; i < lines.length && !/^\s{2}# /.test(lines[i]!); i++) {
+    if (/^(Plan:|No changes\.|Changes to Outputs:)/.test(lines[i]!)) break;
+    head.push(lines[i]!);
+  }
+  let cur: string[] | undefined;
+  for (; i < lines.length; i++) {
+    const l = lines[i]!;
+    if (/^\s{2}# /.test(l)) {
+      cur = [l];
+      blocks.push(cur);
+    } else if (/^(Plan:|Changes to Outputs:|─|Note:|Saved the plan)/.test(l)) {
+      cur = undefined;
+      if (l.startsWith("Changes to Outputs:")) {
+        for (i++; i < lines.length && /^\s/.test(lines[i]!); i++) if (new RegExp(`^\\s+[-+~] ${m}__`).test(lines[i]!)) outs.push(lines[i]!.replace(`${m}__`, ""));
+        i--;
+      }
+    } else if (cur) cur.push(l);
+  }
+  const mine = blocks
+    .filter((b) => topModule(b[0]!.replace(/^\s{2}# /, "")) === m)
+    .map((b) => [b[0]!.replace(`module.${m}.`, ""), ...b.slice(1)].join("\n").trimEnd());
+  const parts = [head.join("\n").trimEnd()];
+  if (mine.length === 0 && outs.length === 0) parts.push("No changes. Its part of the composed run matches the configuration.");
+  else {
+    if (mine.length) parts.push(mine.join("\n\n"));
+    parts.push(`Plan: ${counts.add} to add, ${counts.change} to change, ${counts.destroy} to destroy.`);
+    if (outs.length) parts.push(`Changes to Outputs:\n${outs.join("\n")}`);
+  }
+  return parts.filter((p) => p !== "").join("\n\n") + "\n";
+}
+
+// ── reads between members ─────────────────────────────────────────────────
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * The names a root's files read off `data.<type>.<name>.<field>`, or
+ * undefined when they read the whole object. While the root is composed
+ * (./root.ts) a `terraform_remote_state` read is `var.chant_read_<name>`,
+ * which counts the same.
+ */
+function fieldsRead(dir: string | undefined, binary: string | undefined, type: string, name: string, field: string): Set<string> | undefined {
+  const ref = type === "terraform_remote_state" ? `(?:data\\.${type}\\.|var\\.${READ_VAR_PREFIX})` : `data\\.${type}\\.`;
+  const re = new RegExp(`\\b${ref}${escapeRe(name)}(?![\\w-])(\\.${field}(?:\\.([A-Za-z_][\\w-]*)|\\[\\s*"([^"]+)"\\s*\\])?)?`, "g");
+  const read = new Set<string>();
+  for (const t of dir ? rootTexts(dir, binary) : []) {
+    for (const hit of t.text.matchAll(re)) {
+      const out = hit[2] ?? hit[3];
+      if (!out) return undefined;
+      read.add(out);
+    }
+  }
+  return read;
+}
+
+/** One member's read of another member's outputs, planned on the upstream's part of the composed plan. */
+export interface ComposedMemberRead {
+  /** The member read. */
+  upstream: string;
+  via: ComposedRead["via"];
+  /** The `vars` key, or the data block's label. */
+  name: string;
+  /** The outputs read, sorted. Undefined when the reader reads the whole object, so every output counts. */
+  outputs?: string[];
+  /** The outputs read that are known only once the upstream's part applies, sorted. */
+  unknown: string[];
+}
+
+/**
+ * Each member's reads of other members, planned on the upstream's part of
+ * the composed plan: an output read that the upstream's planned outputs
+ * ({@link terraformPlannedOutputs} of its slice) leave unknown is named
+ * unknown. A `vars` read names its output; a `terraform_remote_state` or
+ * `terraform_estate_outputs` block's outputs are read from the member's own
+ * files, as terragucci's `outputsRead` and `estateValuesRead` did.
+ */
+export function composedReads(c: Pick<Composition, "members" | "reads" | "dirs"> & Partial<Pick<Composition, "binary">>, outputs: ReadonlyMap<string, PlannedOutputs>): Map<string, ComposedMemberRead[]> {
+  const out = new Map<string, ComposedMemberRead[]>();
+  for (const member of c.members) {
+    const reads: ComposedMemberRead[] = [];
+    // Several `vars` reads of one upstream through one variable are one read.
+    const byKey = new Map<string, { r: ComposedRead; outputs?: Set<string> }>();
+    for (const r of c.reads.get(member) ?? []) {
+      const planned = outputs.get(r.upstream);
+      if (!planned) continue;
+      if (r.via === "vars") {
+        const key = `vars\u0000${r.upstream}\u0000${r.variable}`;
+        const had = byKey.get(key);
+        if (had) had.outputs!.add(r.output);
+        else byKey.set(key, { r, outputs: new Set([r.output]) });
+      } else {
+        const read = r.via === "remote-state" ? fieldsRead(c.dirs.get(member), c.binary, "terraform_remote_state", r.name, "outputs") : fieldsRead(c.dirs.get(member), c.binary, "terraform_estate_outputs", r.name, "values");
+        byKey.set(`${r.via}\u0000${r.upstream}\u0000${r.name}`, { r, ...(read ? { outputs: read } : {}) });
+      }
+    }
+    for (const { r, outputs: read } of byKey.values()) {
+      const planned = outputs.get(r.upstream)!;
+      const unknown = [...new Set(planned.unknown)].filter((o) => read === undefined || read.has(o)).sort();
+      reads.push({ upstream: r.upstream, via: r.via, name: r.via === "vars" ? r.variable : r.name, ...(read ? { outputs: [...read].sort() } : {}), unknown });
+    }
+    if (reads.length) out.set(member, reads);
+  }
+  return out;
+}
+
+// ── each member's plan ────────────────────────────────────────────────────
+
+/** One member's part of a composed plan, in the form a capability's `plan` answers it. */
+export interface ComposedMemberPlan extends CapabilityPlan {
+  /** The member's root, as `terraform.roots` names it: the change set's member. */
+  member: string;
+  changeSet: ChangeSetPart;
+  outputs: PlannedOutputs;
+  /** `unknownInputs` are this member's reads of other members that the composed plan leaves unknown, as `<component>.<output>`. */
+  shape: PlanShape;
+  /** The member's part of `show -json`, as if it had planned alone. */
+  slice: unknown;
+  counts: PlanCounts;
+  /** Its reads of other members. */
+  reads: ComposedMemberRead[];
+}
+
+export interface ComposedMemberPlansOptions {
+  /** The binary that planned. Default `terraform`. */
+  planner?: ChangeSetPlanner;
+  /** The estate or workspace each member plans into, by component. */
+  scope?: (member: string) => string | undefined;
+}
+
+/**
+ * Every member's plan out of the composed plan's `show -json`, by component:
+ * {@link terraformChangeSetPart}, {@link terraformPlannedOutputs} and
+ * {@link terraformPlanShape} of its slice, so each member's part is the part
+ * a plan of its root alone gives on the same state. The member is the root's
+ * name (`Composition.roots`), as a single `terraform-apply` plan names it.
+ */
+export function composedMemberPlans(c: Pick<Composition, "members" | "order" | "modules" | "reads" | "dirs" | "roots"> & Partial<Pick<Composition, "binary">>, plan: unknown, options: ComposedMemberPlansOptions = {}): Record<string, ComposedMemberPlan> {
+  const slices = new Map(c.order.map((member) => [member, slicePlan(plan, c.modules.get(member)!)] as const));
+  const outputs = new Map(c.order.map((member) => [member, terraformPlannedOutputs(slices.get(member))] as const));
+  const reads = composedReads(c, outputs);
+  const result: Record<string, ComposedMemberPlan> = {};
+  for (const member of c.order) {
+    const slice = slices.get(member);
+    const root = c.roots.get(member) ?? member;
+    const scope = options.scope?.(member);
+    const changeSet = terraformChangeSetPart({ member: root, plan: slice, ...(options.planner ? { planner: options.planner } : {}), ...(scope ? { scope } : {}) });
+    const mine = reads.get(member) ?? [];
+    const unknownInputs = [...new Set(mine.flatMap((r) => r.unknown.map((o) => `${r.upstream}.${o}`)))].sort();
+    result[member] = {
+      member: root,
+      planDigest: changeSet.member.planDigest ?? "",
+      changeSet,
+      outputs: outputs.get(member)!,
+      shape: terraformPlanShape(slice, root, { unknownInputs }),
+      slice,
+      counts: planCounts(slice),
+      reads: mine,
+    };
+  }
+  return result;
+}

package/src/compose/state-address.ts

@@ -0,0 +1,157 @@
+/**
+ * Lifted from terragucci's `packages/terragucci/src/state-address.ts` at c493e0e
+ * (chant#4438), unchanged but for this note.
+ *
+ * Where a state is, for each backend type, as a root's code names it: in the
+ * root's own backend block (or `cloud` block), and in a
+ * `terraform_remote_state` block that reads it. Two roots line up when the
+ * address one's backend names is the address the other's read names.
+ *
+ * s3, gcs, azurerm and any type not named here keep the address they always
+ * had: the bucket, when one is named, and the key (or `prefix`). The others
+ * get a key of their own, prefixed with the type so that no two types share
+ * one:
+ *
+ * - `local:<path>`: the state file, resolved against the root's directory and
+ *   written relative to the repo.
+ * - `pg:<host>/<database>/<schema>.<table>`: from `conn_str`, credentials left out.
+ * - `http:<address>`: the URL, credentials left out.
+ * - `consul:<address>/<path>`.
+ * - `kubernetes:<namespace>/<secret_suffix>`.
+ * - `remote:<hostname>/<organization>/<workspace>`: a `remote` backend or a `cloud` block.
+ *
+ * An address is unresolved when a part of it is not a plain string in the
+ * code: an expression such as `var.env`, or a value the backend takes from
+ * the environment or a `-backend-config` file (`PG_CONN_STR`,
+ * `TF_HTTP_ADDRESS`, `CONSUL_HTTP_ADDR`, `KUBE_NAMESPACE`,
+ * `TF_CLOUD_ORGANIZATION`, a workspace picked by tags or `TF_WORKSPACE`).
+ * Nothing can line it up with another root, so it is named instead.
+ */
+import { posix, sep } from "node:path";
+
+/** Where one state is: its bucket, when the backend names one, and its key. */
+export interface StateKey {
+  bucket?: string;
+  key: string;
+}
+
+/** An address, or why the code does not say it. */
+export type Addressed = StateKey | { unresolved: string };
+
+/**
+ * One attribute as the code writes it: the string, `null` when it is written
+ * but is not a plain string (an expression, or a string with a template in
+ * it), undefined when it is not written.
+ */
+export type Attr = (name: string) => string | null | undefined;
+
+/** The types this module gives an address of their own. */
+export const ADDRESSED_TYPES = ["local", "pg", "http", "consul", "kubernetes", "remote"] as const;
+
+const unresolved = (why: string): Addressed => ({ unresolved: why });
+
+/** A plain string with no template in it, else null. */
+export function literal(v: unknown): string | null | undefined {
+  if (v === undefined) return undefined;
+  return typeof v === "string" && !/\$\{|%\{/.test(v) ? v : null;
+}
+
+/** `scheme://user:pass@Host:port/path?q` as `host:port/path`, credentials and query left out. */
+function urlAddress(raw: string, keepScheme: boolean): string | undefined {
+  try {
+    const u = new URL(raw.includes("://") ? raw : `http://${raw}`);
+    const path = u.pathname.replace(/\/+$/, "");
+    return `${keepScheme ? `${u.protocol}//` : ""}${u.host.toLowerCase()}${path}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The host and database of a Postgres connection string, in URL or `key=value` form. */
+export function pgDatabase(conn: string): string | undefined {
+  if (/^postgres(ql)?:\/\//i.test(conn)) {
+    try {
+      const u = new URL(conn);
+      const db = u.pathname.replace(/^\/+/, "") || u.searchParams.get("dbname");
+      const host = u.host.toLowerCase() || u.searchParams.get("host");
+      return host && db ? `${host}/${db}` : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  const kv = new Map([...conn.matchAll(/(\w+)\s*=\s*('(?:[^'\\]|\\.)*'|\S+)/g)].map((m) => [m[1], m[2].replace(/^'|'$/g, "")]));
+  const host = kv.get("host")?.toLowerCase();
+  const db = kv.get("dbname");
+  if (!host || !db) return undefined;
+  return `${host}${kv.get("port") ? `:${kv.get("port")}` : ""}/${db}`;
+}
+
+/**
+ * The address of a state of backend `type`, from its attributes. `dir` is the
+ * directory the binary runs in for the block (the root's, relative to the
+ * repo), which a local path is resolved against.
+ */
+export function stateAddress(type: string, get: Attr, dir: string): Addressed {
+  const missing = (name: string, from?: string): Addressed =>
+    unresolved(get(name) === null ? `its ${type} ${name} is an expression, not a plain string` : `its ${type} backend names no ${name} in the code (${from ? `${from} or ` : ""}a -backend-config file supplies it)`);
+  switch (type) {
+    case "local": {
+      const path = get("path");
+      if (path === null) return missing("path");
+      const p = (path ?? "terraform.tfstate").split(sep).join(posix.sep);
+      // Relative to the repo, `/` between parts; a path outside the repo keeps its `..`, an absolute one stays as it is.
+      return { key: `local:${posix.isAbsolute(p) ? posix.normalize(p) : posix.normalize(posix.join(dir.split(sep).join(posix.sep) || ".", p))}` };
+    }
+    case "pg": {
+      const conn = get("conn_str");
+      if (!conn) return missing("conn_str", "PG_CONN_STR");
+      const db = pgDatabase(conn);
+      if (!db) return unresolved("its pg conn_str names no host and database");
+      const schema = get("schema_name");
+      const table = get("table_name");
+      if (schema === null) return missing("schema_name");
+      if (table === null) return missing("table_name");
+      return { key: `pg:${db}/${schema ?? "terraform_remote_state"}.${table ?? "states"}` };
+    }
+    case "http": {
+      const address = get("address");
+      if (!address) return missing("address", "TF_HTTP_ADDRESS");
+      const url = urlAddress(address, true);
+      return url ? { key: `http:${url}` } : unresolved(`its http address is not a URL`);
+    }
+    case "consul": {
+      const address = get("address");
+      const path = get("path");
+      if (!path) return missing("path");
+      if (!address) return missing("address", "CONSUL_HTTP_ADDR");
+      const host = urlAddress(address, false);
+      return host ? { key: `consul:${host}/${path.replace(/^\/+/, "")}` } : unresolved("its consul address is not a host");
+    }
+    case "kubernetes": {
+      const suffix = get("secret_suffix");
+      const namespace = get("namespace");
+      if (!suffix) return missing("secret_suffix");
+      if (!namespace) return missing("namespace", "KUBE_NAMESPACE");
+      return { key: `kubernetes:${namespace}/${suffix}` };
+    }
+    case "remote":
+    case "cloud": {
+      const host = get("hostname");
+      const org = get("organization");
+      const name = get("name");
+      if (host === null) return missing("hostname");
+      if (!org) return missing("organization", type === "cloud" ? "TF_CLOUD_ORGANIZATION" : undefined);
+      if (name === null) return unresolved(`its ${type} workspace name is an expression, not a plain string`);
+      if (name === undefined) return unresolved(`its ${type} workspaces block names no workspace by name (one picked by tags, prefix or TF_WORKSPACE cannot be read from the code)`);
+      return { key: `remote:${(host ?? "app.terraform.io").toLowerCase()}/${org}/${name}` };
+    }
+  }
+  // s3, gcs, azurerm, and the types not named above: the bucket and key, as before.
+  const k = get("key");
+  const p = get("prefix");
+  const key = k || p;
+  if (!key) return missing(k === null ? "key" : p === null ? "prefix" : type === "gcs" ? "prefix" : "key");
+  const bucket = get("bucket");
+  if (bucket === null) return missing("bucket");
+  return { ...(bucket ? { bucket } : {}), key };
+}