@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/dist/compose.js

@@ -0,0 +1,482 @@
+/**
+ * Which roots a change composes, in what order, and why the others fall back
+ * (chant#4438, epic #4419). Pure functions over a project's config, its
+ * components and its roots' files: nothing here runs a binary.
+ *
+ * A composed run plans the `terraform-apply` components a change reaches,
+ * and the ones they read, as one plan of a composed root of `module` calls,
+ * and applies it as one apply, so a value one root creates reaches the roots
+ * that read it inside that apply. Writing the composed root is #4441;
+ * splitting its state is #4442; running it is #4444.
+ *
+ * Lifted from terragucci's `packages/terragucci/src/compose.ts` at c493e0e
+ * (`Composition`, `composeSet`, `readOrder`, `moduleNames`, `compositionFor`,
+ * `fallbackOf`, `fallbackLine`), with chant's inputs in place of terragucci's:
+ *
+ * - The roots are `terraform.roots`, each deployed by a component whose step
+ *   is `{ kind: "terraform-apply", root }`. A member is a component.
+ * - A read between members is a `stackOutput()` in the step's `vars`, a
+ *   `terraform_remote_state` block whose address is another member's
+ *   backend, or a `terraform_estate_outputs` block naming another member's
+ *   estate.
+ * - `waves.after` is the component's `dependsOn`; `oidc.roles` is the apply
+ *   identity the caller resolves per member (`ci.identity.cloud`, #4296);
+ *   `TF_CLI_ARGS*` is read from the environment as before.
+ *
+ * Unlike terragucci, part of a change can compose (#4419 ruling 1): each
+ * member that cannot is left out with its own reason, and the rest compose
+ * when two or more remain. A component of another kind, or a root left out,
+ * on a dependency path between two members splits them (ruling 2), and only
+ * a component whose deploy is that one step joins (ruling 3).
+ *
+ * Off unless `terraform.compose.enabled` is set: {@link compositionIfEnabled}
+ * is the entry point, and calls nothing when it is not.
+ */
+import { isAbsolute, resolve } from "node:path";
+import { wiringReads } from "@intentius/chant/components/driver";
+import { lockRefusal, readBackend } from "./state/backend.js";
+import { estateOutputReads, importLiteral, jsonImportRefused, liveEstate, localModules, lockedProviders, relPath, rootState, rootTexts, sameState, blockBody, } from "./compose/hcl.js";
+export { blankComments, lockedProviders, blockBody, hclAttr, rootState, liveEstate, estateOutputReads } from "./compose/hcl.js";
+/** `terraform.compose.max` when unset. */
+export const DEFAULT_COMPOSE_MAX = 10;
+/** The step kind a member's deploy is. */
+export const COMPOSE_STEP_KIND = "terraform-apply";
+/** A member's identity as {@link CompositionInput.identity} compares it: its apply trade, or `""` for none. */
+export function identityKey(identity) {
+    return identity ? JSON.stringify(identity.apply) : "";
+}
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const list = (xs) => xs.map((x) => `\`${x}\``).join(", ");
+/**
+ * The module name of each root: its name with every character a name cannot
+ * hold as `_` (`envs/prod-app` is `envs_prod_app`), `root` for an empty one,
+ * `r_` before a leading digit, and `_2`, `_3` on a clash, given in name order.
+ */
+export function moduleNames(roots) {
+    const out = new Map();
+    const taken = new Set();
+    for (const r of [...new Set(roots)].sort()) {
+        let base = r === "." || r === "" ? "root" : r.replace(/[^A-Za-z0-9_]/g, "_").replace(/^_+|_+$/g, "") || "root";
+        if (/^[0-9]/.test(base))
+            base = `r_${base}`;
+        let name = base;
+        for (let i = 2; taken.has(name); i++)
+            name = `${base}_${i}`;
+        taken.add(name);
+        out.set(r, name);
+    }
+    return out;
+}
+/** The members of `set`, each after every member of the set it reads; members that read none of each other in name order. */
+export function readOrder(set, deps) {
+    const left = new Set(set);
+    const out = [];
+    while (left.size > 0) {
+        const ready = [...left].filter((r) => [...(deps.get(r) ?? [])].every((u) => !left.has(u))).sort();
+        // A cycle the waves would refuse: take the rest in name order rather than stop.
+        const take = ready.length > 0 ? ready : [...left].sort();
+        for (const r of take) {
+            out.push(r);
+            left.delete(r);
+        }
+    }
+    return out;
+}
+/** The members a composed run covers: those of `all` the change reaches and every one of `all` they read, followed upstream. */
+export function composeSet(all, selected, deps) {
+    const set = new Set(selected ? [...selected].filter((r) => all.includes(r)) : all);
+    const queue = [...set];
+    while (queue.length > 0) {
+        const r = queue.pop();
+        for (const u of deps.get(r) ?? []) {
+            if (!set.has(u) && all.includes(u)) {
+                set.add(u);
+                queue.push(u);
+            }
+        }
+    }
+    return [...set].sort();
+}
+// ── components ────────────────────────────────────────────────────────────
+/** Every leaf step of a deploy, gates included, in order. */
+function leafSteps(phases) {
+    const out = [];
+    const walk = (steps) => {
+        for (const s of steps) {
+            if (typeof s.phase === "string" && Array.isArray(s.steps))
+                walk(s.steps);
+            else
+                out.push(s);
+        }
+    };
+    for (const p of phases)
+        walk(p.steps);
+    return out;
+}
+/** A component's kind, for a reason: its first step's kind. */
+const kindOf = (c) => leafSteps(c.deploy)[0]?.kind ?? "empty";
+/** The top-level vars of a step and the members' outputs each reads through `stackOutput()` or `@<component>.publish.*`. */
+function varsReads(step) {
+    const vars = step.vars && typeof step.vars === "object" && !Array.isArray(step.vars) ? step.vars : {};
+    const out = [];
+    for (const [variable, value] of Object.entries(vars)) {
+        for (const r of wiringReads({ [variable]: value }, {}))
+            out.push({ variable, upstream: r.source, output: r.ref.slice(r.source.length + 1) });
+    }
+    return out;
+}
+/** Every component another reads or depends on, from any step's wiring and its `dependsOn`, plus the HCL reads between roots. */
+function dependencyGraph(components, hcl) {
+    const names = new Set(components.map((c) => c.name));
+    const out = new Map();
+    for (const c of components) {
+        const deps = new Set((c.dependsOn ?? []).filter((d) => names.has(d)));
+        for (const step of leafSteps(c.deploy)) {
+            for (const r of wiringReads(step, {}))
+                if (names.has(r.source) && r.source !== c.name)
+                    deps.add(r.source);
+        }
+        for (const r of hcl.get(c.name) ?? [])
+            deps.add(r.upstream);
+        out.set(c.name, deps);
+    }
+    return out;
+}
+/** Each root component's HCL reads of another root component. */
+function hclReads(rcs) {
+    const out = new Map();
+    for (const r of rcs) {
+        const reads = [];
+        if (r.state && r.dir) {
+            for (const read of r.state.reads) {
+                for (const o of rcs)
+                    if (o.name !== r.name && o.state?.own && sameState(o.state.own, read))
+                        reads.push({ via: "remote-state", upstream: o.name, name: read.name });
+            }
+            for (const read of estateOutputReads(r.dir, r.binary)) {
+                for (const o of rcs)
+                    if (o.name !== r.name && o.estate === read.estate)
+                        reads.push({ via: "estate-outputs", upstream: o.name, name: read.name });
+            }
+        }
+        out.set(r.name, reads);
+    }
+    return out;
+}
+/** Every component of `input` that deploys a root, its files read once. */
+function rootComponents(input) {
+    const tf = input.terraform;
+    const projectRoot = resolve(input.projectRoot);
+    const rcs = [];
+    for (const c of input.components) {
+        const steps = leafSteps(c.deploy);
+        const step = steps.find((s) => s.kind === COMPOSE_STEP_KIND);
+        if (!step)
+            continue;
+        const root = typeof step.root === "string" ? step.root : undefined;
+        const config = root !== undefined ? tf.roots[root] : undefined;
+        const rc = { name: c.name, step, steps: steps.length, live: false, ...(root !== undefined ? { root } : {}) };
+        if (config && step.cwd === undefined) {
+            const dir = isAbsolute(config.dir) ? config.dir : resolve(projectRoot, config.dir);
+            const rel = relPath(projectRoot, dir);
+            const binary = tf.binary;
+            const live = liveEstate(dir, binary ?? "terraform");
+            const estate = config.estate ?? live.estate;
+            // The state address from the one backend verdict (chant#4478): the code, TF_CLI_ARGS*, the backend-config files and pairs, and what init recorded.
+            const state = rootState(dir, rel, {
+                ...(input.env ? { env: input.env } : {}),
+                ...(binary ? { binary } : {}),
+                ...(config.backendConfig ? { backendConfig: config.backendConfig } : {}),
+                ...(config.backendConfigFiles ? { backendConfigFiles: config.backendConfigFiles } : {}),
+            });
+            Object.assign(rc, { config, dir, rel, state, live: live.live, ...(estate ? { estate } : {}), ...(binary ? { binary } : {}) });
+        }
+        rcs.push(rc);
+    }
+    return rcs;
+}
+/**
+ * Each component's `terraform_remote_state` and `terraform_estate_outputs`
+ * reads of another component of `input` that deploys a root, as the
+ * composition finds them (#4447): what `terraform-apply`'s `groupReads`
+ * reports to core. Components with no such read are left out.
+ */
+export function rootHclReads(input) {
+    return new Map([...hclReads(rootComponents(input))].filter(([, reads]) => reads.length > 0));
+}
+const readKey = (r) => `${r.upstream}\0${r.via}\0${r.via === "vars" ? `${r.variable}\0${r.output}` : r.name}`;
+// ── the composition ───────────────────────────────────────────────────────
+/** `TF_CLI_ARGS*` flags a composed run cannot take: their addresses name a root's resources without the module in front, and `-var` names no root. */
+const CLI_REFUSED = /(^|\s)-{1,2}(target|exclude|replace|var)(=|\s|$)/;
+/**
+ * The `off` fallback when `terraform.compose` is not enabled, else undefined:
+ * what `terraform-apply`'s `groupFallback` answers first (ws-107).
+ */
+export function composeOff(terraform) {
+    return terraform.compose?.enabled === true ? undefined : { kind: "off", reason: "`terraform.compose` is not enabled" };
+}
+/**
+ * The composition when `terraform.compose.enabled` is set, else undefined
+ * without reading anything. The only caller of {@link compositionFor} a run
+ * should use.
+ */
+export function compositionIfEnabled(input) {
+    if (input.terraform.compose?.enabled !== true)
+        return undefined;
+    return compositionFor(input);
+}
+/**
+ * What `terraform.compose` comes to for a change: the members, their order,
+ * modules and reads, each candidate left out with its reason, or why nothing
+ * composes. Per-member checks run first (root, steps, targets, binary,
+ * backend, identity, provider lock, reads, imports and paths, order, split);
+ * a member left out gets the first that applies to it. `cli-args`,
+ * `too-many-roots` and `one-root` then judge what is left as a whole.
+ */
+export function compositionFor(input) {
+    const tf = input.terraform;
+    const max = tf.compose?.max ?? DEFAULT_COMPOSE_MAX;
+    const projectRoot = resolve(input.projectRoot);
+    const byName = new Map(input.components.map((c) => [c.name, c]));
+    const rcs = rootComponents(input);
+    const rcOf = new Map(rcs.map((r) => [r.name, r]));
+    const hcl = hclReads(rcs);
+    const graph = dependencyGraph(input.components, hcl);
+    const candidates = composeSet(rcs.map((r) => r.name), input.selected, graph);
+    const roots = new Map(candidates.flatMap((m) => (rcOf.get(m).root !== undefined ? [[m, rcOf.get(m).root]] : [])));
+    const dirs = new Map(candidates.flatMap((m) => (rcOf.get(m).dir ? [[m, rcOf.get(m).dir]] : [])));
+    // Each member's reads of every other candidate; narrowed to members at the end.
+    const allReads = new Map();
+    for (const m of candidates) {
+        const rc = rcOf.get(m);
+        const reads = [...varsReads(rc.step).map((r) => ({ via: "vars", ...r })), ...(hcl.get(m) ?? [])];
+        allReads.set(m, reads.filter((r) => r.upstream !== m && rcOf.has(r.upstream)));
+    }
+    const left = new Map();
+    let members = [...candidates];
+    const drop = (m, kind, reason) => {
+        left.set(m, { kind, member: m, reason });
+        members = members.filter((x) => x !== m);
+    };
+    const each = (check) => {
+        for (const m of [...members]) {
+            const hit = check(m, rcOf.get(m));
+            if (hit)
+                drop(m, hit[0], hit[1]);
+        }
+    };
+    // Where the root is, and that its deploy is that one step.
+    each((m, rc) => {
+        if (rc.root === undefined)
+            return ["path", `\`${m}\`'s terraform-apply step names no \`root\``];
+        if (rc.step.cwd !== undefined)
+            return ["path", `\`${m}\`'s terraform-apply step sets \`cwd\`, so its root is read from another chant.config`];
+        if (!rc.config)
+            return ["path", `\`${m}\` deploys root \`${rc.root}\`, which \`terraform.roots\` does not list`];
+        return undefined;
+    });
+    const rootTaken = new Map();
+    each((m, rc) => {
+        const had = rootTaken.get(rc.root);
+        if (had)
+            return ["same-root", `\`${m}\` deploys root \`${rc.root}\`, which \`${had}\` deploys too, and a composed run calls each root once`];
+        rootTaken.set(rc.root, m);
+        return undefined;
+    });
+    each((m, rc) => rc.steps !== 1 ? ["steps", `\`${m}\`'s deploy has ${plural(rc.steps, "step")}, and only a component whose deploy is one terraform-apply step composes`] : undefined);
+    each((m) => {
+        const t = input.targets?.[m] ?? [];
+        return t.length > 0 ? ["targets", `\`${m}\` is given ${plural(t.length, "target")} (\`--target\`), and a composed run plans each member whole`] : undefined;
+    });
+    // One binary process: one binary at one version.
+    const binaryOf = (m) => input.binary?.(m) ?? { name: tf.binary ?? "terraform" };
+    const binName = (b) => `${b.name}${b.version ? ` ${b.version}` : ""}`;
+    const binRef = majority(members, (m) => binName(binaryOf(m)));
+    each((m) => {
+        if (!binRef || binName(binaryOf(m)) === binRef.key)
+            return undefined;
+        return ["binary", `\`${m}\` runs ${binName(binaryOf(m))} and \`${binRef.first}\` ${binRef.key}, and one run has one binary`];
+    });
+    // Every member runs choudoufu and one has a `live` block: the members compose as estates (choudoufu#2059).
+    const estate = members.length > 1 && members.every((m) => binaryOf(m).name === "choudoufu") && members.some((m) => rcOf.get(m).live);
+    each((m, rc) => {
+        if (estate)
+            return rc.live ? undefined : ["backend", `\`${m}\` has no \`live\` block, and a composed run of estates calls only directories that carry one`];
+        const ws = rc.config.workspace;
+        if (ws && ws !== "default")
+            return ["workspace", `\`${m}\` plans in workspace ${ws}, and a composed run plans in default`];
+        // The one backend verdict (chant#4478): the code and flags before init, compared with what init recorded after.
+        const refusal = lockRefusal(readBackend(rc.dir, {
+            env: input.env,
+            ...(rc.binary ? { binary: rc.binary } : {}),
+            ...(rc.config.backendConfig ? { backendConfig: rc.config.backendConfig } : {}),
+            ...(rc.config.backendConfigFiles ? { backendConfigFiles: rc.config.backendConfigFiles } : {}),
+        }));
+        if (refusal)
+            return ["backend", `\`${m}\`: ${refusal.reason}`];
+        return undefined;
+    });
+    // One binary process has one set of credentials. Estates take each one's role from its own provider blocks.
+    if (!estate && input.identity) {
+        const idOf = (m) => input.identity(m) ?? "";
+        const idRef = majority(members, idOf);
+        each((m) => {
+            if (!idRef || idOf(m) === idRef.key)
+                return undefined;
+            const same = members.filter((x) => idOf(x) === idRef.key);
+            return ["identity", `\`${m}\` applies under another cloud identity (\`ci.identity.cloud\`) than ${list(same)}, and one run has one set of credentials`];
+        });
+    }
+    // One run installs one version of each provider: the first member in name order to lock it sets it.
+    const locked = new Map();
+    each((m, rc) => {
+        const mine = lockedProviders(rc.dir);
+        for (const [p, v] of mine) {
+            const had = locked.get(p);
+            if (had && had.version !== v)
+                return ["provider-lock", `\`${m}\` locks ${p} at ${v} and \`${had.member}\` at ${had.version}, and one run installs one version`];
+        }
+        for (const [p, v] of mine)
+            if (!locked.has(p))
+                locked.set(p, { version: v, member: m });
+        return undefined;
+    });
+    // Reads a composed root cannot rewrite.
+    each((m, rc) => {
+        for (const r of allReads.get(m) ?? []) {
+            if (r.via !== "remote-state" || !members.includes(r.upstream))
+                continue;
+            if (rc.state.reads.find((x) => x.name === r.name)?.repeated) {
+                return ["read", `\`${m}\` reads \`${r.upstream}\` through a block with count or for_each (\`data.terraform_remote_state.${r.name}\`)`];
+            }
+        }
+        for (const mod of localModules(rc.dir, rc.binary)) {
+            const modRel = relPath(projectRoot, mod);
+            for (const read of rootState(mod, modRel, { recorded: null, env: {}, ...(rc.binary ? { binary: rc.binary } : {}) }).reads) {
+                const up = members.find((o) => o !== m && rcOf.get(o).state?.own && sameState(rcOf.get(o).state.own, read));
+                if (up)
+                    return ["read", `\`${m}\` reads \`${up}\` from its module \`${modRel}\`, and a composed run rewrites only a root's own reads`];
+            }
+        }
+        return undefined;
+    });
+    // What a module call cannot carry.
+    each((m, rc) => {
+        for (const t of rootTexts(rc.dir, rc.binary)) {
+            if (t.json) {
+                if (jsonImportRefused(t.text))
+                    return ["import", `an \`import\` block of \`${m}\` takes no literal string \`id\`, so it cannot be lifted into the composed root`];
+                continue;
+            }
+            for (const im of t.text.matchAll(/(^|\n)\s*import\s*\{/g)) {
+                if (!importLiteral(blockBody(t.text, im.index + im[1].length))) {
+                    return ["import", `an \`import\` block of \`${m}\` takes no literal string \`id\`, so it cannot be lifted into the composed root`];
+                }
+            }
+            if (/\bpath\.(root|cwd)\b/.test(t.text))
+                return ["path", `\`${m}\` uses \`path.root\` or \`path.cwd\`, which would name the composed root instead of \`${rc.rel}\``];
+        }
+        return undefined;
+    });
+    // An order with no read: a module with its own providers takes no depends_on.
+    each((m) => {
+        const reads = new Set((allReads.get(m) ?? []).map((r) => r.upstream));
+        const u = (byName.get(m)?.dependsOn ?? []).find((d) => members.includes(d) && !reads.has(d));
+        return u ? ["order-only", `\`${m}\` depends on \`${u}\` (\`dependsOn\`) with no read between them, and a module with its own providers takes no depends_on`] : undefined;
+    });
+    // A component outside the run on a path between two members splits them (#4419 ruling 2): the one after it leaves.
+    for (let moved = true; moved;) {
+        moved = false;
+        for (const m of [...members]) {
+            const hit = pathOutside(m, members, graph);
+            if (!hit)
+                continue;
+            const via = byName.get(hit.via);
+            const what = rcOf.has(hit.via) ? "which is left out of the composed run and applies between them" : `a ${via ? kindOf(via) : "other"} component that applies between them`;
+            drop(m, "split", `\`${m}\` depends on \`${hit.member}\` through \`${hit.via}\`, ${what}`);
+            moved = true;
+            break;
+        }
+    }
+    const fallbacks = candidates.flatMap((m) => (left.has(m) ? [left.get(m)] : []));
+    const base = { candidates, max, roots, dirs, fallbacks, ...(tf.binary ? { binary: tf.binary } : {}) };
+    const none = (fallback) => ({ ...base, members: [], order: [], modules: new Map(), reads: new Map(), fallback });
+    if (members.length >= 2) {
+        for (const k of ["TF_CLI_ARGS", "TF_CLI_ARGS_plan", "TF_CLI_ARGS_apply"]) {
+            const cli = (input.env[k] ?? "").match(CLI_REFUSED);
+            if (cli)
+                return none({ kind: "cli-args", reason: `\`${k}\` carries \`-${cli[2]}\`, which names a root's own addresses or variables, not the composed run's` });
+        }
+    }
+    if (members.length > max)
+        return none({ kind: "too-many-roots", reason: `this change composes ${plural(members.length, "root")}, more than \`terraform.compose.max\` (${max})` });
+    if (members.length <= 1) {
+        if (candidates.length === 0)
+            return none({ kind: "one-root", reason: "this change reaches no root" });
+        if (candidates.length === 1)
+            return none({ kind: "one-root", member: candidates[0], reason: `this change reaches one root, \`${candidates[0]}\`, which applies in its own run` });
+        return none({
+            kind: "one-root",
+            ...(members[0] ? { member: members[0] } : {}),
+            reason: members.length === 0 ? "no root of this change can compose" : `only \`${members[0]}\` of this change can compose, and one root applies in its own run`,
+        });
+    }
+    const inGroup = new Map(members.map((m) => [m, new Set([...(graph.get(m) ?? [])].filter((u) => members.includes(u)))]));
+    const order = readOrder(members, inGroup);
+    const names = moduleNames(members.map((m) => roots.get(m)));
+    const modules = new Map(members.map((m) => [m, names.get(roots.get(m))]));
+    const reads = new Map(members.map((m) => {
+        const seen = new Map();
+        for (const r of allReads.get(m) ?? [])
+            if (members.includes(r.upstream))
+                seen.set(readKey(r), r);
+        return [m, [...seen.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, r]) => r)];
+    }));
+    return { ...base, members, order, modules, reads, ...(estate ? { estate } : {}) };
+}
+/** The value most members share, and the first member in name order that has it; a tie goes to the value the earliest member has. */
+function majority(members, key) {
+    const groups = new Map();
+    for (const m of [...members].sort())
+        groups.set(key(m), [...(groups.get(key(m)) ?? []), m]);
+    let best;
+    for (const [k, ms] of groups)
+        if (!best || ms.length > best.n)
+            best = { key: k, first: ms[0], n: ms.length };
+    return best ? { key: best.key, first: best.first } : undefined;
+}
+/**
+ * A member that `m` depends on through a component that is not a member,
+ * and the first such component on the way, or undefined. Paths through
+ * another member stop there: that member is checked on its own.
+ */
+function pathOutside(m, members, graph) {
+    const seen = new Set();
+    const stack = [...(graph.get(m) ?? [])].sort().map((at) => ({ at }));
+    while (stack.length > 0) {
+        const { at, via } = stack.shift();
+        const key = `${at}\0${via ?? ""}`;
+        if (seen.has(key) || at === m)
+            continue;
+        seen.add(key);
+        if (members.includes(at)) {
+            if (via)
+                return { member: at, via };
+            continue;
+        }
+        for (const u of [...(graph.get(at) ?? [])].sort())
+            stack.push({ at: u, via: via ?? at });
+    }
+    return undefined;
+}
+/** The composition with its plan failed: nothing composes, and each member plans wave by wave. */
+export function withPlanFailed(c, message) {
+    const first = message.trim().split("\n")[0] ?? "";
+    return { ...c, members: [], order: [], modules: new Map(), reads: new Map(), fallback: { kind: "plan-failed", reason: `the composed plan failed${first ? `: ${first}` : ""}` } };
+}
+/** The one line a note, a log and the report say for a fallback: the whole change's, or one member's. */
+export function fallbackLine(f) {
+    return f.member !== undefined && f.kind !== "one-root"
+        ? `**\`${f.member}\` applies in waves** (\`terraform.compose\`): ${f.reason}.`
+        : `**Applies in waves** (\`terraform.compose\`): ${f.reason}.`;
+}

package/dist/composites/terraform-apply-op.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terraform-apply-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-apply-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AAEH,OAAO,EAA6B,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAW/F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,qGAAqG;QACrG,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CAkH1F"}
+{"version":3,"file":"terraform-apply-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-apply-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AAEH,OAAO,EAA6B,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAW/F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,qGAAqG;QACrG,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CAsH1F"}

package/dist/composites/terraform-apply-op.js

@@ -130,9 +130,13 @@ export function TerraformApplyOp(config) {
                 "answer instead of the account's.");
         }
     }
-    const phases = [
-        phase("Init", [initStep(config.root, { ...where, ...(config.upgrade ? { upgrade: true } : {}) })]),
-    ];
+    // The Init step names the root's directory in the workspace (chant#4482),
+    // so a read of the run ledger can tell which member's root this run applied
+    // when the Op is declared in another member: `chant ledger runs`'s
+    // `root_member` column comes from this outcome.
+    const init = initStep(config.root, { ...where, ...(config.upgrade ? { upgrade: true } : {}) });
+    init.outcomeAttribute = { name: "TerraformRootPath", from: "rootPath" };
+    const phases = [phase("Init", [init])];
     // `id` is what makes `plan.out` legal, and `plan.out.planFile` is how the
     // Apply step below names this step's saved plan. On a live root that file
     // is also the approval artifact the apply re-plans against, so the same

package/dist/config.d.ts

@@ -65,8 +65,15 @@ export declare const terraformRootSchema: z.ZodObject<{
     workspace: z.ZodOptional<z.ZodString>;
     /** `-var-file` arguments, in order, relative to `dir`. */
     varFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    /** `-backend-config` key/value pairs handed to `init`. */
+    /** `-backend-config` key/value pairs handed to `init`, after {@link backendConfigFiles}. */
     backendConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /**
+     * Backend-config files handed to `init` as `-backend-config=<path>`, in
+     * order and before the {@link backendConfig} pairs, relative to `dir`
+     * (chant#4459). The composition reads their `key = "value"` lines as it
+     * reads the pairs, to find a root's state before init.
+     */
+    backendConfigFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
     /**
      * The choudoufu estate this root runs against, for a live root whose HCL
      * does not declare one of its own (#2479).
@@ -118,6 +125,16 @@ export declare const terraformRootSchema: z.ZodObject<{
         plan: "plan";
         state: "state";
     }>>;
+    /**
+     * The root is declared only so a change to it brings this project into the
+     * change (#4484). A dns member that declares another cloud's root, so that
+     * an azure change reaches dns, sets it on that root. Change detection
+     * (`changedUnits`) still counts the root; the build and every live read
+     * skip it, so it is never drawn or read as this project's own: its entities
+     * are not built, and `describeResources`, drift and the owned-resource
+     * reads leave it out. An Op step that names the root still runs against it.
+     */
+    signalOnly: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const terraformConfigSchema: z.ZodObject<{
     /**
@@ -164,6 +181,21 @@ export declare const terraformConfigSchema: z.ZodObject<{
         plan: "plan";
         state: "state";
     }>>;
+    /**
+     * Composed runs (#4419, #4438), off unless `enabled` is true. When on, the
+     * `terraform-apply` components a change reaches, and the ones they read,
+     * plan as one plan and apply as one apply of a composed root of `module`
+     * calls, so a value one root creates reaches its readers in that apply. A
+     * component that cannot compose plans wave by wave as without the setting,
+     * and the report says why (`compositionFor` in `compose.ts`).
+     *
+     * `max` caps how many roots compose; a change over it applies wholly in
+     * waves. Default 10.
+     */
+    compose: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        max: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
     /** Named root modules. The name is the entity-key prefix, so keep it stable. */
     roots: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         /** Root module directory, relative to the project root (where `chant.config.*` lives). */
@@ -172,8 +204,15 @@ export declare const terraformConfigSchema: z.ZodObject<{
         workspace: z.ZodOptional<z.ZodString>;
         /** `-var-file` arguments, in order, relative to `dir`. */
         varFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        /** `-backend-config` key/value pairs handed to `init`. */
+        /** `-backend-config` key/value pairs handed to `init`, after {@link backendConfigFiles}. */
         backendConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /**
+         * Backend-config files handed to `init` as `-backend-config=<path>`, in
+         * order and before the {@link backendConfig} pairs, relative to `dir`
+         * (chant#4459). The composition reads their `key = "value"` lines as it
+         * reads the pairs, to find a root's state before init.
+         */
+        backendConfigFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
         /**
          * The choudoufu estate this root runs against, for a live root whose HCL
          * does not declare one of its own (#2479).
@@ -225,20 +264,27 @@ export declare const terraformConfigSchema: z.ZodObject<{
             plan: "plan";
             state: "state";
         }>>;
+        /**
+         * The root is declared only so a change to it brings this project into the
+         * change (#4484). A dns member that declares another cloud's root, so that
+         * an azure change reaches dns, sets it on that root. Change detection
+         * (`changedUnits`) still counts the root; the build and every live read
+         * skip it, so it is never drawn or read as this project's own: its entities
+         * are not built, and `describeResources`, drift and the owned-resource
+         * reads leave it out. An Op step that names the root still runs against it.
+         */
+        signalOnly: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
-    /**
-     * One pulumi workspace member read into the graph (#3179). `chant workspace
-     * graph` writes this into the reader project it makes for a `pulumi` member;
-     * it is not meant to be written by hand. `dir` is the member's directory,
-     * absolute; `label` names the entities. The graph is the checked-in
-     * `stack-export.json` there; the program is never run.
-     */
-    pulumiMember: z.ZodOptional<z.ZodObject<{
-        dir: z.ZodString;
-        label: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type TerraformRootConfig = z.infer<typeof terraformRootSchema>;
+/**
+ * The roots a project owns: `roots` without the ones marked `signalOnly`
+ * (#4484), which only feed change detection. The build and the live reads
+ * take these; `changedUnits` takes every root.
+ */
+export declare function ownRoots<R extends {
+    signalOnly?: boolean;
+}>(roots: Record<string, R> | undefined): Record<string, R>;
 export type TerraformConfig = z.infer<typeof terraformConfigSchema>;
 declare module "@intentius/chant/config" {
     interface ChantConfig {

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB;;;;EAA2C,CAAC;AAClF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH;;;GAGG;AACH,eAAO,MAAM,2BAA2B;;;EAA4B,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,mBAAmB;IAC9B,0FAA0F;;IAE1F,4EAA4E;;IAE5E,0DAA0D;;IAE1D,0DAA0D;;IAE1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;;IAEH,+EAA+E;;;;;;IAE/E;;;;;;;;;;;;;;OAcG;;;;;kBAEH,CAAC;AAEH,eAAO,MAAM,qBAAqB;IAChC;;;;;;;OAOG;;;;;;IAEH;;;;;;;OAOG;;;;;;IAEH;;;;;;;;;;;OAWG;;IAEH,6FAA6F;;;;;IAE7F,gFAAgF;;QAxFhF,0FAA0F;;QAE1F,4EAA4E;;QAE5E,0DAA0D;;QAE1D,0DAA0D;;QAE1D;;;;;;;;;;;;;;;;;;;;;;;;WAwBG;;QAEH,+EAA+E;;;;;;QAE/E;;;;;;;;;;;;;;WAcG;;;;;;IAwCH;;;;;;OAMG;;;;;kBAEH,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB;;;;EAA2C,CAAC;AAClF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH;;;GAGG;AACH,eAAO,MAAM,2BAA2B;;;EAA4B,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,mBAAmB;IAC9B,0FAA0F;;IAE1F,4EAA4E;;IAE5E,0DAA0D;;IAE1D,4FAA4F;;IAE5F;;;;;OAKG;;IAEH;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;;IAEH,+EAA+E;;;;;;IAE/E;;;;;;;;;;;;;;OAcG;;;;;IAEH;;;;;;;;OAQG;;kBAEH,CAAC;AAEH,eAAO,MAAM,qBAAqB;IAChC;;;;;;;OAOG;;;;;;IAEH;;;;;;;OAOG;;;;;;IAEH;;;;;;;;;;;OAWG;;IAEH,6FAA6F;;;;;IAE7F;;;;;;;;;;OAUG;;;;;IAOH,gFAAgF;;QA1HhF,0FAA0F;;QAE1F,4EAA4E;;QAE5E,0DAA0D;;QAE1D,4FAA4F;;QAE5F;;;;;WAKG;;QAEH;;;;;;;;;;;;;;;;;;;;;;;;WAwBG;;QAEH,+EAA+E;;;;;;QAE/E;;;;;;;;;;;;;;WAcG;;;;;QAEH;;;;;;;;WAQG;;;kBAyDH,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAEpH;AACD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC"}