@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/src/hcl/parse.ts

@@ -1,11 +1,13 @@
 /**
  * The one shared HCL parse for the terraform lexicon.
  *
- * Two entry points, one entity shape. `parseTerraformRootDir` reads the `.tf`
- * files of a directory (non-recursive, matching Terraform's own module
- * scoping) and is what `buildRoots()` calls. `parseTerraformRootContent` takes
- * the joined-file string `chant audit` hands a lexicon for a discovered root
- * module: every `.tf` in filename order behind a `# file: <name>` line comment.
+ * Two entry points, one entity shape. `parseTerraformRootDir` reads the
+ * configuration files of a directory (non-recursive, matching Terraform's own
+ * module scoping; `.tf` and `.tf.json`, plus `.tofu` and `.tofu.json` for a
+ * tofu or choudoufu root, see `./files.ts`) and is what `buildRoots()` calls.
+ * `parseTerraformRootContent` takes the joined-file string `chant audit` hands
+ * a lexicon for a discovered root module: every configuration file in filename
+ * order behind a `# file: <name>` line comment, narrowed to the same set.
  * Both funnel through `blocksToEntities`, so an entity the audit path sees is
  * the entity the build path sees.
  *
@@ -18,7 +20,7 @@
  * changed in `packages/core/package.json` for this.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/hcl2json";
 import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
@@ -27,6 +29,20 @@ import type { SuppressionDirective } from "@intentius/chant/lint/suppressions";
 import type { TerraformDeleteMode } from "../config";
 import { redactSensitiveBody, redactSensitiveSource } from "./redact";
 import { scanSuppressions, directivesFor, type FileScan } from "./suppressions";
+import { isJsonConfigFile, jsonConfigTree, listConfigFiles, selectConfigFiles } from "./files";
+
+export {
+  TERRAFORM_SUFFIXES,
+  TOFU_SUFFIXES,
+  isConfigFileFor,
+  isJsonConfigFile,
+  isTofuConfigFile,
+  jsonConfigTree,
+  listConfigFiles,
+  listConfigFilesSafe,
+  readsTofuFiles,
+  selectConfigFiles,
+} from "./files";
 
 /** A parsed HCL block body, as `@cdktn/hcl2json` encodes it. */
 export type BlockBody = Record<string, unknown>;
@@ -40,6 +56,10 @@ export type BlockBody = Record<string, unknown>;
  * the instance count is a plan-time answer and often a state-time one, but it
  * is a shape a reader should be told rather than left to infer from a node
  * count that never grows.
+ *
+ * Since #4454 a literal expansion also gets its instance nodes, children of
+ * the block's node (`TerraformEntity.instanceKeys`). The block node stays,
+ * and the edges stay block to block.
  */
 export type TerraformExpansion = "count" | "for_each";
 
@@ -151,6 +171,27 @@ export interface TerraformEntity extends Declarable {
    * ROOT's name, not the module's: the module is not separately applied.
    */
   readonly stack: string;
+  /**
+   * The instance keys a `resource` or `data` block's literal `count` or
+   * `for_each` expands to (#4454), as Terraform prints them: `[0]`, `[1]`
+   * for `count = 2`, `["a"]` for a `for_each` over a literal map or
+   * `toset([...])`. Core's `withInstanceNodes` reads this lexicon-neutral
+   * field, as `buildGraphIr` reads `stack`, and draws one instance node per
+   * key under the block's node. Absent when the block is not expanded or its
+   * expansion is not a literal. Since #4486 `./instances.ts` also sets it
+   * for an expansion it can count from the root's variables (`count = var.n`
+   * with `n` known), and for a `module` call.
+   */
+  readonly instanceKeys?: readonly string[];
+  /**
+   * The instance nodes of a block under an expanded module call (#4486), by
+   * full node id: `estate/module.app[0]/aws_eip.pool[1]`, with `key` the
+   * block's own key (`[1]`, absent when the block is not expanded itself)
+   * and `scope` the module path as Terraform prints it (`module.app[0]`).
+   * Core's `entityInstances` reads this in place of `instanceKeys`, which
+   * such a block never carries. Set by `./instances.ts`.
+   */
+  readonly instances?: ReadonlyArray<{ readonly id: string; readonly key?: string; readonly scope?: string }>;
   /**
    * Every reference in this block, resolved to the entity keys it points at
    * (chant #2265), in core's lexicon-neutral {@link EntityReference} shape.
@@ -183,6 +224,23 @@ export const OUTPUT_TYPE = "Terraform::Output";
 export const LOCALS_TYPE = "Terraform::Locals";
 /** A `live { estate = "..." }` block, or an `estate.chdf.hcl` sidecar's content (#2103). */
 export const LIVE_TYPE = "Terraform::Live";
+/**
+ * The four configuration blocks that change how a plan treats addresses
+ * rather than declaring anything (#4458): `moved`, `import`, `removed` and
+ * `check`. The first three carry no label and key as `moved`, `import`,
+ * `removed` (numbered `~2`, `~3` when a root holds several, as `locals` is);
+ * a `check` keys as `check.<name>`. Their references are edges like any other
+ * block's: a `moved` block's `from` and `to`, an `import` block's `to`, a
+ * `removed` block's `from`, and everything a `check` block's assertions and
+ * scoped `data` blocks read. A `from` usually names an address that is no
+ * longer declared, which resolves to no entity and so draws no edge, and
+ * that is all that happens: an unresolved reference is dropped, never
+ * reported (`./edges.ts`).
+ */
+export const MOVED_TYPE = "Terraform::Moved";
+export const IMPORT_TYPE = "Terraform::Import";
+export const REMOVED_TYPE = "Terraform::Removed";
+export const CHECK_TYPE = "Terraform::Check";
 
 /**
  * Terragrunt config entities (#3417). A `terragrunt.hcl` or `root.hcl` is not
@@ -214,6 +272,55 @@ function expansionOf(body: BlockBody): TerraformExpansion | undefined {
   return undefined;
 }
 
+/** The most instance keys read off one literal; past it the block draws as the block alone. */
+const MAX_LITERAL_INSTANCES = 256;
+
+/**
+ * The instance keys a literal expansion gives (#4454), as Terraform prints
+ * them, or undefined when the expansion is not a literal a read of the
+ * source can count. `count` as a number (`count = 3`), `for_each` as a
+ * literal map (`{ a = 1 }`, keys in Terraform's lexical order) or
+ * `toset([...])` over string literals. Anything holding a reference is a
+ * plan-time answer.
+ */
+export function literalInstanceKeys(body: BlockBody): string[] | undefined {
+  const keys = literalKeys(body);
+  if (keys === undefined || keys.length > MAX_LITERAL_INSTANCES) return undefined;
+  return keys;
+}
+
+function literalKeys(body: BlockBody): string[] | undefined {
+  if ("count" in body) {
+    const count = body.count;
+    const n = typeof count === "number" ? count
+      : typeof count === "string" && /^\$\{\s*\d+\s*\}$/.test(count.trim()) ? Number(count.trim().slice(2, -1))
+      : undefined;
+    if (n === undefined || !Number.isInteger(n) || n < 0) return undefined;
+    return Array.from({ length: n }, (_, i) => `[${i}]`);
+  }
+  if ("for_each" in body) {
+    const each = body.for_each;
+    if (typeof each === "object" && each !== null && !Array.isArray(each)) {
+      const names = Object.keys(each);
+      if (names.some((k) => k.includes("${"))) return undefined;
+      return names.sort().map((k) => `[${JSON.stringify(k)}]`);
+    }
+    if (typeof each === "string") {
+      const m = /^\$\{\s*toset\(\s*(\[[\s\S]*\])\s*\)\s*\}$/.exec(each.trim());
+      if (!m) return undefined;
+      let list: unknown;
+      try {
+        list = JSON.parse(m[1]!.replace(/,\s*\]$/, "]"));
+      } catch {
+        return undefined;
+      }
+      if (!Array.isArray(list) || !list.every((v) => typeof v === "string")) return undefined;
+      return [...new Set(list as string[])].sort().map((k) => `[${JSON.stringify(k)}]`);
+    }
+  }
+  return undefined;
+}
+
 /**
  * Build one entity. Written out rather than run through `createResource`
  * from `@intentius/chant/runtime`: that factory is for generated resource
@@ -234,6 +341,7 @@ export function terraformEntity(
   suppressions?: readonly SuppressionDirective[],
 ): TerraformEntity {
   const expansion = expansionOf(body);
+  const instanceKeys = expansion && (entityType === RESOURCE_TYPE || entityType === DATA_TYPE) ? literalInstanceKeys(body) : undefined;
   const labels = entityType === RESOURCE_TYPE ? blockLabels(address)
     : entityType === DATA_TYPE && address.startsWith("data.") ? blockLabels(address.slice("data.".length))
     : undefined;
@@ -243,6 +351,7 @@ export function terraformEntity(
     entityType,
     kind: "resource",
     stack: root,
+    ...(instanceKeys ? { instanceKeys } : {}),
     props: {
       address,
       ...(labels ?? {}),
@@ -302,11 +411,20 @@ export function splitBundleContent(content: string, fallbackName = "main.tf"): T
   return files.filter((f) => f.source.trim() !== "");
 }
 
-/** Every `.tf` directly under `dir`, in filename order. Non-recursive. */
-export function listTerraformFiles(dir: string): string[] {
-  return readdirSync(dir)
-    .filter((f) => f.endsWith(".tf"))
-    .sort();
+/**
+ * Every configuration file directly under `dir` that a root run by `binary`
+ * reads, in filename order, non-recursive: `.tf` and `.tf.json`, plus `.tofu`
+ * and `.tofu.json` for a tofu or choudoufu root, with `x.tofu` shadowing
+ * `x.tf` (chant#4457). The shared lister is `./files.ts`'s `listConfigFiles`.
+ */
+export function listTerraformFiles(dir: string, binary?: string): string[] {
+  return listConfigFiles(dir, binary);
+}
+
+/** One file's tree in hcl2json's shape: hcl2json for HCL, {@link jsonConfigTree} for Terraform's JSON syntax. */
+export async function parseFileTree(parser: Hcl2Json, file: TerraformFile): Promise<Record<string, unknown>> {
+  if (isJsonConfigFile(file.name)) return jsonConfigTree(file.source);
+  return (await parser.parse(file.name, file.source)) as Record<string, unknown>;
 }
 
 /** The Terragrunt config files directly under `dir` (`root.hcl`, `terragrunt.hcl`), in filename order like the audit's bundle. */
@@ -488,7 +606,7 @@ export async function blocksToEntities(
   };
 
   for (const file of files) {
-    const tree = (await parser.parse(file.name, file.source)) as Record<string, unknown>;
+    const tree = await parseFileTree(parser, file);
     const scan = scanSuppressions(file.name, file.source);
     if (isTerragruntFileName(file.name)) {
       terragruntBlocks(tree, file, scan, add);
@@ -503,6 +621,10 @@ export async function blocksToEntities(
     oneLabel(tree, "output", OUTPUT_TYPE, (n) => `output.${n}`, file, scan);
     twoLabels(tree, "resource", RESOURCE_TYPE, (t, n) => `${t}.${n}`, file, scan);
     twoLabels(tree, "data", DATA_TYPE, (t, n) => `data.${t}.${n}`, file, scan);
+    unlabelled(tree, "moved", MOVED_TYPE, file, scan);
+    unlabelled(tree, "import", IMPORT_TYPE, file, scan);
+    unlabelled(tree, "removed", REMOVED_TYPE, file, scan);
+    oneLabel(tree, "check", CHECK_TYPE, (n) => `check.${n}`, file, scan);
   }
 
   if (sidecar) {
@@ -568,8 +690,9 @@ function terragruntBlocks(
 }
 
 /**
- * Parse a root module directory. Reads every `.tf` directly under `dir`, plus
- * the `estate.chdf.hcl` sidecar beside them when present. Throws whatever the
+ * Parse a root module directory. Reads the configuration files directly under
+ * `dir` that `modeOptions.binary` reads ({@link listTerraformFiles}), plus the
+ * `estate.chdf.hcl` sidecar beside them when present. Throws whatever the
  * parser throws for malformed HCL; `buildRoots()` is where that becomes a
  * warning.
  */
@@ -581,7 +704,7 @@ export async function parseTerraformRootDir(
   callers: readonly string[] = [],
 ): Promise<Map<string, Declarable>> {
   // A child module is a Terraform module, never a Terragrunt unit (#3417).
-  const names = [...listTerraformFiles(dir), ...(callers.length === 0 ? listTerragruntFiles(dir) : [])];
+  const names = [...listTerraformFiles(dir, modeOptions?.binary), ...(callers.length === 0 ? listTerragruntFiles(dir) : [])];
   const files = names.map((name) => ({
     name,
     source: readFileSync(join(dir, name), "utf-8"),
@@ -610,7 +733,17 @@ export async function parseTerraformRootContent(
   hcl2json?: Hcl2Json,
   modeOptions?: TerraformRootModeOptions,
 ): Promise<Map<string, Declarable>> {
-  return blocksToEntities(splitBundleContent(content), root, hcl2json, modeOptions);
+  return blocksToEntities(bundleFilesFor(splitBundleContent(content), modeOptions?.binary), root, hcl2json, modeOptions);
+}
+
+/**
+ * The files of a joined bundle a root run by `binary` reads: the same set
+ * {@link listTerraformFiles} gives for a directory holding them, plus the
+ * Terragrunt files, in bundle order (chant#4457).
+ */
+export function bundleFilesFor(files: readonly TerraformFile[], binary?: string): TerraformFile[] {
+  const keep = new Set(selectConfigFiles(files.map((f) => f.name), binary));
+  return files.filter((f) => keep.has(f.name) || isTerragruntFileName(f.name));
 }
 
 /** The root name an audit of the audited directory itself parses under. */

package/src/hcl/roots.ts

@@ -34,6 +34,7 @@ import type { TerraformRootConfig } from "../config";
 import { LIVE_TYPE, parseTerraformRootDir } from "./parse";
 import { descendModules, resolveCallModuleType, type CallModuleType } from "./descend";
 import { resolveEntityReferences } from "./edges";
+import { resolveInstanceNodes } from "./instances";
 
 export interface TerraformRootsResult {
   entities: Map<string, Declarable>;
@@ -111,6 +112,11 @@ export async function renderTerraformRoots(
       for (const [key, entity] of descended.entities) entities.set(key, entity);
       warnings.push(...descended.warnings);
 
+      // Instance nodes the root's variables let the declared graph count,
+      // and those under expanded module calls (#4486). Needs the root and
+      // every child scope parsed, so it runs once the descent has.
+      await resolveInstanceNodes(entities, name, { dir, ...(root.varFiles ? { varFiles: root.varFiles } : {}), hcl2json: opts.hcl2json });
+
       // A `live` block or `estate.chdf.hcl` sidecar only takes effect under
       // choudoufu; under any other binary it parses fine but is inert, which
       // is worth a warning rather than silence (#2103).

package/src/hcl/suppressions.ts

@@ -27,9 +27,9 @@
 import type { SuppressionDirective, SuppressionIds } from "@intentius/chant/lint/suppressions";
 
 /** A block header keyword with zero labels (`terraform {`, `locals {`). */
-const BARE_RE = /^\s*(terraform|locals|remote_state)\s*\{/;
+const BARE_RE = /^\s*(terraform|locals|remote_state|moved|import|removed)\s*\{/;
 /** One label (`provider "aws" {`, `module "vpc" {`, `variable "x" {`, `output "x" {`). */
-const ONE_LABEL_RE = /^\s*(provider|module|variable|output|dependency|generate)\s+"([^"]*)"\s*\{/;
+const ONE_LABEL_RE = /^\s*(provider|module|variable|output|check|dependency|generate)\s+"([^"]*)"\s*\{/;
 /** Two labels (`resource "aws_s3_bucket" "assets" {`, `data "aws_ami" "x" {`). */
 const TWO_LABEL_RE = /^\s*(resource|data)\s+"([^"]*)"\s+"([^"]*)"\s*\{/;
 
@@ -45,6 +45,12 @@ function addressFor(keyword: string, labels: string[]): string {
       return "locals";
     case "remote_state":
       return "remote_state";
+    case "moved":
+    case "import":
+    case "removed":
+      return keyword;
+    case "check":
+      return `check.${labels[0]}`;
     case "dependency":
       return `dependency.${labels[0]}`;
     case "generate":

package/src/index.ts

@@ -10,10 +10,85 @@ export {
   terraformApplyCapability,
   TerraformPlanMovedError,
   TERRAFORM_VERB_FAMILIES,
+  // #4455: a choudoufu member's outputs, read for core's `member-outputs`.
+  choudoufuOutputSource,
+  choudoufuMemberPlannedOutputs,
   type TerraformApplyStepInput,
   type TerraformApplyStepOutput,
 } from "./components/capability-plugin";
 
+// Composed runs (#4442): the working state merged and split, the composed
+// plan cut into one plan per member, and each member's apply outcome.
+export { mergeStates, splitState, splitStates, derivedLineage, COMPOSE_LINEAGE, type SplitState } from "./compose/state-merge";
+export {
+  slicePlan as sliceComposedPlan,
+  sliceText,
+  planCounts,
+  composedReads,
+  composedMemberPlans,
+  type PlanCounts,
+  type ComposedMemberRead,
+  type ComposedMemberPlan,
+  type ComposedMemberPlansOptions,
+} from "./compose/slice";
+export { readApplyEvents, memberApply, composedApplyOutcomes, type ApplyEvents, type MemberApply, type MemberApplyOutcome } from "./compose/apply-events";
+export { topModule, stripModule, stripChange, moduleChanges } from "./compose/module-address";
+
+// Composed runs of choudoufu estates (#4445): one plan and one apply, values read from a post-apply plan.
+export {
+  EstateRun,
+  estateVersionFallback,
+  estateOutcomes,
+  readEstateApplyText,
+  type ComposedRunner,
+  type ComposedRunPlan,
+  type ComposedRunApply,
+  type ComposedMemberOutcome,
+  type EstateRunOptions,
+} from "./compose/estate";
+export { priorStateValues, stateResources, stateOutputs, type StateResourceValues } from "./applied-state";
+
+// Composed runs over roots with state (#4444): one plan and one apply, each
+// state written back whatever happened. Implements `ComposedRunner` (#4445).
+export {
+  ComposedRun,
+  composedPlanDigest,
+  changesSomething,
+  type ComposedRunOptions,
+  type ComposedRunStage,
+  type StateRunPlan,
+  type StateRunApply,
+  type StateMemberOutcome,
+  type ComposedStateWrite,
+  type ComposeHook,
+  type ComposeHookMoment,
+} from "./compose/run";
+
+// The plan shape of a `show -json` plan (#4436), for core's `coveredRound`.
+export { terraformPlanShape, type TerraformPlanShapeOptions } from "./plan-shape";
+
+// Composed runs (#4419, #4438): which roots compose, in what order, and why
+// the others fall back. Off unless `terraform.compose.enabled` is set.
+export {
+  compositionFor,
+  compositionIfEnabled,
+  composeOff,
+  composeSet,
+  readOrder,
+  moduleNames,
+  fallbackLine,
+  withPlanFailed,
+  identityKey,
+  DEFAULT_COMPOSE_MAX,
+  COMPOSE_STEP_KIND,
+  type Composition,
+  type CompositionInput,
+  type ComposedRead,
+  type ComposeFallback,
+  type ComposeFallbackKind,
+  type ExpectedBinary,
+} from "./compose";
+
 // Serializer
 export { terraformSerializer } from "./serializer";
 
@@ -68,6 +143,7 @@ export {
   choudoufuLiveLs,
   choudoufuLiveCheck,
   choudoufuAdopt,
+  choudoufuPlanSet,
   terraformPinRollout,
 } from "./op/builders";
 

package/src/live-plan-reasons.ts

@@ -0,0 +1,54 @@
+/**
+ * choudoufu's live-plan omission codes, in chant's vocabulary.
+ *
+ * Its own module so the observation reader (`./describe-resources.ts`) and
+ * the drift adapters (`./drift-record.ts`) read one table, and the drift
+ * adapters bundle without the reader's process and file-system imports.
+ */
+
+import type { UnobservedReason } from "@intentius/chant/observation";
+
+/**
+ * choudoufu's omission reason codes, mapped onto chant's total vocabulary
+ * (`internal/live/projection/result.go`). `"absent"` is not an
+ * {@link UnobservedReason}: it is the tri-state's OBSERVED-ABSENT, the one
+ * omission that is a claim of knowledge rather than of ignorance.
+ *
+ * A code this table does not know maps to `read-failed`, which is the safe
+ * direction: no NOT-OBSERVED verdict ever becomes a create or a delete.
+ */
+export const LIVE_PLAN_OMISSION_REASONS: Readonly<Record<string, UnobservedReason | "absent">> = {
+  // The provider was asked and reported, normally, that nothing is there.
+  ABSENT: "absent",
+  // The provider errored, or could not be reached in a usable order.
+  FAILED: "read-failed",
+  PARENT_UNAVAILABLE: "read-failed",
+  CYCLE: "read-failed",
+  INCOMPLETE_BLOCK: "read-failed",
+  LISTED_NOT_IMPORTABLE: "read-failed",
+  // Something exists at the identity and does not carry this estate's marker.
+  // Normally answered by the `unowned[]` section before this table is read;
+  // this entry is what happens if a document ever carries the omission alone.
+  UNOWNED: "read-failed",
+  // The mode cannot name, list or tag this instance at all: a server-assigned
+  // identity with no marker to find it by, a resource with no cloud object to
+  // read, or an address another declared instance has taken over.
+  NEEDS_DISCOVERY: "unsupported-kind",
+  UNREADABLE: "unsupported-kind",
+  SUPERSEDED: "unsupported-kind",
+  // The run's own tag index saw an object at the identity and the import
+  // read could not confirm it (choudoufu #1043). The read failed; the
+  // object is not proposed for creation.
+  VERIFIED_NOT_IMPORTABLE: "read-failed",
+  // -target or -exclude left the block out of the plan graph (choudoufu
+  // #1176): nothing was read because the caller asked for it not to be.
+  OUT_OF_SCOPE: "filtered",
+};
+
+/** Does this text name a credentials or authorization failure rather than any other error? */
+export function readsAsCredentials(text: string): boolean {
+  return /\b(no valid credential|credentials?|not authorized|unauthorized|accessdenied|access denied|expiredtoken|invalidclienttokenid|signature)\b/i.test(
+    text,
+  );
+}
+

package/src/lsp/completions.test.ts

@@ -104,7 +104,7 @@ describe("LSP completions", () => {
   it("completes root-entry keys inside chant.config.ts's terraform.roots.<name>", () => {
     const content = "export default {\n  terraform: {\n    roots: {\n      app: {\n        ";
     const items = completions(ctx({ content, position: { line: 4, character: 8 } }));
-    expect(items.map((i) => i.label).sort()).toEqual(["backendConfig", "delete", "dir", "varFiles", "workspace"]);
+    expect(items.map((i) => i.label).sort()).toEqual(["backendConfig", "backendConfigFiles", "delete", "dir", "signalOnly", "varFiles", "workspace"]);
   });
 
   it("completes the terraform namespace's own top-level keys", () => {

package/src/lsp/option-keys.ts

@@ -25,7 +25,9 @@ export const ROOT_ENTRY_KEYS: OptionKey[] = [
   { key: "workspace", detail: "Terraform workspace to select for this root. Omitted means `default`." },
   { key: "varFiles", detail: "`-var-file` arguments, in order, relative to `dir`." },
   { key: "backendConfig", detail: "`-backend-config` key/value pairs handed to `init`." },
+  { key: "backendConfigFiles", detail: "Backend-config files handed to `init` as `-backend-config=<path>`, before the pairs, relative to `dir`." },
   { key: "delete", detail: '"never" | "owned-only" | "gated" — this root\'s delete mode, mapped onto choudoufu\'s policy block on a live root.' },
+  { key: "signalOnly", detail: "`true` when the root is declared only so a change to it brings this project into the change. The build and live reads skip it." },
 ];
 
 /** `TerraformApplyOpConfig`'s keys (`TerraformApplyOp({ <here> })`). */

package/src/op/activities/choudoufu-plan-set-op.test.ts

@@ -0,0 +1,111 @@
+/**
+ * `choudoufuPlanSet` as an Op activity (#4483, H3 of #4477). One Op plans two
+ * live choudoufu roots, one per cloud, and hands each root's `changeSet` to
+ * `composeChangeSet`, the shape behold's three-cloud front door takes instead
+ * of composing the change set in a script.
+ *
+ * The activity is the real one, resolved through `loadActivities`, so it runs
+ * the configured binary. A fake `choudoufu` on `PATH` answers `version` and
+ * prints a one-root set plan document for `live-plan-set`, exiting 2 as
+ * choudoufu does for a plan with changes. Nothing reaches a cloud.
+ */
+
+import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { composeChangeSet, loadActivities, runOpLocally, validateActivitySteps, validateStepOutputRefs, type ActivityProfile, type OpConfig } from "@intentius/chant/op";
+import { choudoufuPlanSet } from "../builders";
+import * as contracts from "../activity-contracts";
+import { __resetChoudoufuVersionCheckForTests } from "./terraform";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+beforeEach(() => __resetChoudoufuVersionCheckForTests());
+afterEach(() => vi.unstubAllEnvs());
+
+const PROFILES: Record<string, ActivityProfile> = {
+  longInfra: { timeout: "5m", retry: { maximumAttempts: 1 } },
+  fastIdempotent: { timeout: "5m", retry: { maximumAttempts: 1 } },
+};
+
+/** A fake choudoufu: `version`, and `live-plan-set -json -out-dir=<d> <root>` printing a one-root document. */
+const FAKE = `#!/bin/sh
+if [ "$1" = "version" ]; then echo "choudoufu v0.31.0 (based on OpenTofu v1.13.0)"; exit 0; fi
+if [ "$1" = "live-plan-set" ]; then
+  for a in "$@"; do root="$a"; done
+  name=$(basename "$root")
+  cat <<EOF
+{"format_version":"1","roots":[{"root":"$root","estate":"$name","status":"planned","error":"","changes":true,"plan":{"format_version":"1.2","resource_changes":[{"address":"null_resource.$name","mode":"managed","type":"null_resource","name":"$name","change":{"actions":["create"],"before":null,"after":{}}}]},"digest":"sha256:root-$name"}],"summary":{"roots":1,"planned":1,"changed":1,"failed":0},"digest":"sha256:set-$name","exit_code":2}
+EOF
+  exit 2
+fi
+echo "fake choudoufu: unexpected $*" >&2
+exit 1
+`;
+
+function project(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-plan-set-op-")));
+  scratch.push(dir);
+  const bin = join(dir, "bin");
+  mkdirSync(bin);
+  writeFileSync(join(bin, "choudoufu"), FAKE);
+  chmodSync(join(bin, "choudoufu"), 0o755);
+  vi.stubEnv("PATH", `${bin}:${process.env.PATH ?? ""}`);
+  for (const root of ["aws", "azure"]) {
+    mkdirSync(join(dir, "estates", root), { recursive: true });
+    writeFileSync(join(dir, "estates", root, "main.tf"), "");
+  }
+  writeFileSync(
+    join(dir, "chant.config.json"),
+    JSON.stringify({ lexicons: ["terraform"], terraform: { binary: "choudoufu", roots: { aws: { dir: "estates/aws" }, azure: { dir: "estates/azure" } } } }),
+  );
+  return dir;
+}
+
+function frontDoor(cwd: string): OpConfig {
+  const aws = choudoufuPlanSet("aws", { cwd, id: "aws" });
+  const azure = choudoufuPlanSet("azure", { cwd, id: "azure" });
+  return {
+    name: "front-door-plan",
+    overview: "",
+    phases: [
+      { name: "Plan", steps: [aws, azure] },
+      { name: "Compose", steps: [composeChangeSet({ parts: [aws.out.changeSet, azure.out.changeSet], id: "doc" })] },
+    ],
+  };
+}
+
+describe("choudoufuPlanSet as an Op activity (#4483)", () => {
+  test("is resolved from the terraform lexicon's activities", async () => {
+    const activities = await loadActivities(["terraform"]);
+    expect(typeof activities.get("choudoufuPlanSet")).toBe("function");
+  });
+
+  test("its contract validates the steps and the changeSet references", () => {
+    const map = new Map(Object.values(contracts).map((c) => [c.name, c]));
+    const config = frontDoor("/tmp/x");
+    expect(validateActivitySteps(config, map)).toEqual([]);
+    expect(validateStepOutputRefs(config, map)).toEqual([]);
+  });
+
+  test("an Op plans two clouds' roots and composes one change set from their parts", async () => {
+    const dir = project();
+    const activities = await loadActivities(["terraform"]);
+    const compose = activities.get("composeChangeSet")!;
+    const documents: Array<{ document: { members?: Array<{ member: string }> }; digest: string }> = [];
+    activities.set("composeChangeSet", async (args, signal) => {
+      const out = (await compose(args, signal)) as (typeof documents)[number];
+      documents.push(out);
+      return out;
+    });
+    const result = await runOpLocally(frontDoor(dir), activities, PROFILES);
+    expect(result.status).toBe("ok");
+    expect(result.records.filter((r) => r.fn === "choudoufuPlanSet").map((r) => r.status)).toEqual(["ok", "ok"]);
+    expect(documents).toHaveLength(1);
+    expect(documents[0]!.digest).toMatch(/^jcs1-sha256:[0-9a-f]{64}$/);
+    expect((documents[0]!.document.members ?? []).map((m) => m.member).sort()).toEqual(["aws", "azure"]);
+  });
+});

package/src/op/activities/index.ts

@@ -16,6 +16,10 @@
  *   - choudoufuLiveLs: `live-ls -estate=<estate> -json [-consistent]` (#2103).
  *   - choudoufuLiveCheck: `live-check -json`, no cloud calls (#2103).
  *   - choudoufuAdopt: the tag writes that claim an adoption ledger's matches (#2105).
+ *   - choudoufuPlanSet: `live-plan-set -json` over one live root, as a
+ *     one-root set (#3459). Its `changeSet` is the root's part, so an Op can
+ *     plan several clouds' roots and hand the parts to `composeChangeSet`
+ *     (#4483).
  *   - terraformPinRollout: one run of a pin-bump rollout, opening at most one
  *     wave's pull request (#3189). It loads the HCL parser on first call.
  *
@@ -34,6 +38,8 @@ export {
   choudoufuLiveLs,
   choudoufuLiveCheck,
   choudoufuAdopt,
+  choudoufuPlanSet,
+  choudoufuPlanSetCommand,
   terraformInitCommand,
   terraformPlanCommand,
   terraformApplyCommand,
@@ -52,6 +58,7 @@ export {
   DEFAULT_TERRAFORM_BINARY,
   DEFAULT_LIVE_PLAN_DOCUMENT_FILE,
   MIN_CHOUDOUFU_VERSION,
+  MIN_CHOUDOUFU_ESTATES_VERSION,
   classifyApprovalRefusal,
   CHOUDOUFU_LIVE_PLAN_OUT_REFUSAL,
   CHOUDOUFU_APPROVAL_EXIT_CODE,
@@ -78,6 +85,8 @@ export type {
   ChoudoufuLiveLsResult,
   ChoudoufuLiveCheckResult,
   ChoudoufuAdoptResult,
+  ChoudoufuPlanSet,
+  ChoudoufuPlanSetResult,
   AdoptionRefusal,
   PlanChangeCounts,
   LivePlanUnownedCounts,