@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/report.ts

@@ -30,9 +30,14 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { changeSetDigest, composeChangeSet, type ChangeSetAction, type ChangeSetAttribute, type ChangeSetEntry, type ChangeSetPlanner } from "@intentius/chant/change-set";
+import { changeSetDigest, composeChangeSet, type ChangeSetAction, type ChangeSetDocument, type ChangeSetAttribute, type ChangeSetEntry, type ChangeSetPlanner } from "@intentius/chant/change-set";
 import { groupChangeSet } from "@intentius/chant/plan-summary";
 import { plannerForBinary, terraformChangeSetPart } from "./change-set";
+import { moduleChanges, stripModule, topModule } from "./compose/module-address";
+import { stateResources } from "./applied-state";
+import { isJsonConfigFile, jsonLiveBlocks, listConfigFiles } from "./hcl/files";
+
+export { topModule } from "./compose/module-address";
 
 type Json = Record<string, unknown>;
 const isObject = (v: unknown): v is Json => v !== null && typeof v === "object" && !Array.isArray(v);
@@ -139,40 +144,15 @@ export interface IndexRow {
 // Slicing the composed plan into one plan per module.
 // ---------------------------------------------------------------------------
 
-const TOP_MODULE = /^module\.([^.[\]]+)(?:\[(?:"(?:[^"\\]|\\.)*"|\d+)\])?(?:\.|$)/;
-
-/** The top-level module an address or module address is in, or undefined for the composed root's own. */
-export function topModule(address: string): string | undefined {
-  return TOP_MODULE.exec(address)?.[1];
-}
-
-/** `address` with its leading `module.<m>` (and index) taken off. */
-function unprefix(address: string): string {
-  const m = TOP_MODULE.exec(address);
-  return m ? address.slice(m[0].length) : address;
-}
-
 /** The plan's `resource_changes` that belong to module `m` (undefined: the root's own), each with the module taken off its address. */
 export function slicePlan(plan: unknown, m: string | undefined): Json {
   const p = isObject(plan) ? plan : {};
-  const list = Array.isArray(p.resource_changes) ? p.resource_changes : [];
-  const mine = list.filter((r) => isObject(r) && topModule(String(r.module_address ?? r.address ?? "")) === m);
-  const resource_changes = mine.map((r) => {
-    const rc = r as Json;
-    const out: Json = { ...rc, address: unprefix(String(rc.address)) };
-    if (typeof rc.previous_address === "string") out.previous_address = unprefix(rc.previous_address);
-    if (typeof rc.module_address === "string") {
-      const rest = unprefix(rc.module_address);
-      if (rest === "" || rest === rc.module_address) delete out.module_address;
-      else out.module_address = rest;
-    }
-    return out;
-  });
-  return { ...(p.errored === true ? { errored: true } : {}), resource_changes };
+  return { ...(p.errored === true ? { errored: true } : {}), resource_changes: moduleChanges(p.resource_changes, m) };
 }
 
 // ---------------------------------------------------------------------------
-// Applied values: the state after the apply gives the values the plan left unknown.
+// Applied values: the state after the apply gives the values the plan left unknown,
+// read through `./applied-state`, as the composed estate run reads them.
 // ---------------------------------------------------------------------------
 
 /** Whether a sensitivity map marks anything under it `true`. */
@@ -183,25 +163,6 @@ function marks(v: unknown): boolean {
   return false;
 }
 
-/** Every resource of a `show -json` state, by address. A deposed object is left out. */
-function stateResources(show: unknown): Map<string, { values: Json; sensitive: Json }> {
-  const out = new Map<string, { values: Json; sensitive: Json }>();
-  const walk = (mod: unknown): void => {
-    if (!isObject(mod)) return;
-    for (const r of Array.isArray(mod.resources) ? mod.resources : []) {
-      if (!isObject(r) || typeof r.address !== "string" || r.deposed_key !== undefined) continue;
-      out.set(r.address, { values: isObject(r.values) ? r.values : {}, sensitive: isObject(r.sensitive_values) ? r.sensitive_values : {} });
-    }
-    for (const c of Array.isArray(mod.child_modules) ? mod.child_modules : []) walk(c);
-  };
-  const root = isObject(show) ? show : {};
-  // A plan's `prior_state` is the state; a `show -json` of state has `values` itself.
-  const state = isObject(root.prior_state) ? root.prior_state : root;
-  const values = isObject(state.values) ? state.values : {};
-  walk(values.root_module);
-  return out;
-}
-
 /** Each unknown attribute given the value the state holds. One the state lacks stays unknown; a sensitive one stays `sensitive`. */
 function resolveUnknowns(attributes: ChangeSetAttribute[], res: { values: Json; sensitive: Json } | undefined): ChangeSetAttribute[] {
   if (!res || !attributes.some((a) => a.unknown)) return attributes;
@@ -230,15 +191,27 @@ export interface ReportRead {
   composed: true;
 }
 
-/** The estate named by the first `live { estate = "..." }` block in a directory's `.tf` files, or undefined. */
-export function estateOfDir(dir: string): string | undefined {
+/**
+ * The estate named by the first `live { estate = "..." }` block in a
+ * directory's configuration files, in filename order, or undefined. A `live`
+ * block takes effect only under choudoufu, so the files are the ones
+ * choudoufu reads (`.tf`, `.tf.json`, `.tofu` and `.tofu.json`, chant#4457)
+ * unless `binary` names another. A JSON-syntax file's `live` block is the one
+ * nested in its `terraform` block (chant#4504).
+ */
+export function estateOfDir(dir: string, binary = "choudoufu"): string | undefined {
   let files: string[];
   try {
-    files = readdirSync(dir).filter((f) => f.endsWith(".tf")).sort();
+    files = listConfigFiles(dir, binary);
   } catch {
     return undefined;
   }
   for (const f of files) {
+    if (isJsonConfigFile(f)) {
+      const estate = jsonLiveBlocks(readFileSync(join(dir, f), "utf8")).map((b) => b.estate).find((e): e is string => typeof e === "string" && e !== "");
+      if (estate) return estate;
+      continue;
+    }
     const text = readFileSync(join(dir, f), "utf8").replace(/^\s*(#|\/\/).*$/gm, "");
     const live = /\blive\s*\{/.exec(text);
     if (!live) continue;
@@ -309,7 +282,7 @@ function unknownOutputsOf(plan: Json, u: string): Set<string> {
       const data = parts[0] === "data";
       const [type, rname, attr] = data ? [parts[1], parts[2], parts[3]] : [parts[0], parts[1], parts[2]];
       if (!type || !rname) continue;
-      const unprefixed = (c: Json): string => unprefix(String(c.address)).replace(/\[[^\]]*\]$/, "");
+      const unprefixed = (c: Json): string => stripModule(String(c.address)).replace(/\[[^\]]*\]$/, "");
       for (const c of changes) {
         if (unprefixed(c) !== `${data ? "data." : ""}${type}.${rname}`) continue;
         const after = isObject(c.change) ? c.change.after_unknown : undefined;
@@ -494,6 +467,8 @@ function rawChanges(plan: Json): Map<string, RawChange> {
 
 export interface TerraformReport {
   report: Json;
+  /** The change set whose digest `report.change_set` names: what behold reads beside the report. */
+  changeSet: ChangeSetDocument;
   /** The run's directory, relative to the project's own index: `yyyy/mm/<commit>/<stage>`. */
   path: string;
   row: IndexRow;
@@ -680,7 +655,7 @@ export function terraformReport(input: TerraformReportInput): TerraformReport {
     ...(run.pull_request_url ? { pull_request_url: run.pull_request_url } : {}),
     ...(run.job_url ? { job_url: run.job_url } : {}),
   };
-  return { report, path, row };
+  return { report, changeSet: doc, path, row };
 }
 
 // ---------------------------------------------------------------------------
@@ -716,7 +691,8 @@ export interface ReportStore {
 }
 
 /**
- * Write the run's `report.json` and add its row to the project's index
+ * Write the run's `report.json` and `change-set.json` (the document whose
+ * digest the report names, as `chant change-set` writes it), and add its row to the project's index
  * (`<project>/index.json`, paths relative to it) and to the prefix's
  * (`index.json`, paths starting at the project), the two places terragucci
  * writes. Returns the keys written.
@@ -729,6 +705,7 @@ export async function writeReport(store: ReportStore, r: TerraformReport): Promi
     keys.push(key);
   };
   await put(`${project}/${r.path}/report.json`, r.report);
+  await put(`${project}/${r.path}/change-set.json`, r.changeSet);
   for (const [key, path] of [[`${project}/index.json`, r.path], ["index.json", `${project}/${r.path}`]] as const) {
     await put(key, addToIndex(await store.read(key), { ...r.row, path }));
   }

package/src/signal-only-root.test.ts

@@ -0,0 +1,72 @@
+/**
+ * A `signalOnly` root (#4484, C5 of #4477). The dns member declares the azure
+ * estate's root only so an azure change brings dns into the change. Change
+ * detection counts it; the build and the live reads leave it out, so dns's
+ * graph draws only dns's own root and dns's live reads never list azure.
+ */
+
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { terraformConfigSchema, ownRoots } from "./config";
+import { terraformPlugin } from "./plugin";
+import { liveRootNames } from "./describe-resources";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+const TERRAFORM: { binary: "choudoufu"; roots: Record<string, { dir: string; signalOnly?: boolean }> } = {
+  binary: "choudoufu",
+  roots: {
+    dns: { dir: "estate" },
+    azure: { dir: "../azure", signalOnly: true },
+  },
+};
+
+/** A workspace slice: `dns/` (the chant member, with its own root under `estate/`) beside `azure/`. */
+function estate(): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-signal-only-")));
+  scratch.push(root);
+  const files: Record<string, string> = {
+    "dns/chant.config.json": JSON.stringify({ lexicons: ["terraform"], terraform: TERRAFORM }),
+    "dns/estate/main.tf": 'resource "null_resource" "zone" {}\n',
+    "dns/estate/estate.chdf.hcl": 'estate = "dns"\n',
+    "azure/main.tf": 'resource "null_resource" "vnet" {}\n',
+    "azure/estate.chdf.hcl": 'estate = "azure"\n',
+  };
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return join(root, "dns");
+}
+
+describe("a signalOnly root (#4484)", () => {
+  test("the config schema takes the marker", () => {
+    expect(terraformConfigSchema.safeParse(TERRAFORM).success).toBe(true);
+    expect(Object.keys(ownRoots(TERRAFORM.roots))).toEqual(["dns"]);
+  });
+
+  test("the build draws only dns's own root, so the azure estate is not drawn under dns", async () => {
+    const dns = estate();
+    const { entities } = await terraformPlugin.buildRoots!({ projectRoot: dns, config: { terraform: TERRAFORM }, entities: new Map() });
+    const keys = [...entities.keys()];
+    expect(keys.length).toBeGreaterThan(0);
+    expect(keys.every((k) => k.startsWith("dns/"))).toBe(true);
+    expect(keys.some((k) => k.startsWith("azure/"))).toBe(false);
+  });
+
+  test("the live reads list dns's root and not the azure estate", async () => {
+    const dns = estate();
+    expect(await liveRootNames(dns)).toEqual([{ root: "dns", estate: "dns" }]);
+  });
+
+  test("an azure change still brings dns into the change", async () => {
+    const dns = estate();
+    const touched = await terraformPlugin.changedUnits!({ projectRoot: dns, config: { terraform: TERRAFORM }, changedFiles: ["../azure/main.tf"] });
+    expect(touched).toEqual(["azure"]);
+  });
+});

package/src/skills/chant-terraform.md

@@ -33,7 +33,7 @@ export default {
 
 ## What a build produces
 
-Every block of every configured root becomes one entity, keyed `<root>/<address>`: `terraform { }` -> `Terraform::Terraform`, `provider "x" {}` -> `Terraform::Provider`, `resource "x" "y" {}` -> `Terraform::Resource`, `data "x" "y" {}` -> `Terraform::Data`, `module "x" {}` -> `Terraform::Module`, `variable "x" {}` -> `Terraform::Variable`, `output "x" {}` -> `Terraform::Output`, `locals {}` -> `Terraform::Locals`. Each carries `props.address`, `props.body` (the block, verbatim), `props.file` and `props.root`. A root whose `dir` doesn't exist, or whose HCL the parser refuses, warns and contributes no entities — the rest of the build is unaffected.
+Every block of every configured root becomes one entity, keyed `<root>/<address>`: `terraform { }` -> `Terraform::Terraform`, `provider "x" {}` -> `Terraform::Provider`, `resource "x" "y" {}` -> `Terraform::Resource`, `data "x" "y" {}` -> `Terraform::Data`, `module "x" {}` -> `Terraform::Module`, `variable "x" {}` -> `Terraform::Variable`, `output "x" {}` -> `Terraform::Output`, `locals {}` -> `Terraform::Locals`, `moved {}` -> `Terraform::Moved`, `import {}` -> `Terraform::Import`, `removed {}` -> `Terraform::Removed`, `check "x" {}` -> `Terraform::Check`. Each carries `props.address`, `props.body` (the block, verbatim), `props.file` and `props.root`. A root whose `dir` doesn't exist, or whose HCL the parser refuses, warns and contributes no entities — the rest of the build is unaffected.
 
 ## The one thing to check before anything else
 

package/src/state/azure-blob.ts

@@ -0,0 +1,8 @@
+/**
+ * The Azure Blob Storage client an azurerm backend's state uses: chant
+ * core's (#4554, `@intentius/chant/object-store`): a blob's properties and
+ * metadata, a snapshot, a block blob put, and the blob lease the backend
+ * locks a state with, signed with Shared Key, a SAS, or an Entra token for
+ * the job's OIDC identity.
+ */
+export { AZURE_AUTHORITY, AZURE_VERSION, AzureBlobClient, sharedKey, type AzureLocation, type AzureOidc, type AzureTarget, type BlobHead } from "@intentius/chant/object-store";

package/src/state/backend-verdict.test.ts

@@ -0,0 +1,187 @@
+/**
+ * One backend verdict for compose and state (chant#4478). The composition's
+ * `backend` fallback (#4438) and the state refusals (#4437) both come from
+ * `lockRefusal(readBackend(...))`, so the same root gets the same answer from
+ * each, before init (the code and flags) and after (what init recorded,
+ * compared with the code).
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { compositionFor, type CompositionInput } from "../compose";
+import { rootState } from "../compose/hcl";
+import type { TerraformConfig } from "../config";
+import { LOCKABLE_BACKENDS, LOCKS, cliBackendConfig, declaredBackend, isRefused, lockRefusal, readBackend, stateObject } from "./backend";
+
+const made: string[] = [];
+afterAll(() => {
+  for (const d of made) rmSync(d, { recursive: true, force: true });
+});
+
+function project(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-4478-"));
+  made.push(dir);
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    writeFileSync(join(dir, path), text);
+  }
+  return dir;
+}
+
+const EMPTY = 'resource "terraform_data" "x" {}\n';
+const tf = (name: string): DriverComponent => ({ name, dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: name }] }] });
+const record = (type: string, config: Record<string, unknown>): string => JSON.stringify({ version: 3, backend: { type, config, hash: 1 } });
+
+/** Credentials for every lockable backend, so a lockable root resolves to a state rather than a credentials refusal. */
+const CREDS: NodeJS.ProcessEnv = { AWS_ACCESS_KEY_ID: "AK", AWS_SECRET_ACCESS_KEY: "SK", GOOGLE_OAUTH_ACCESS_TOKEN: "t", ARM_ACCESS_KEY: Buffer.from("k").toString("base64") };
+
+interface Case {
+  name: string;
+  /** Root `c`'s files, beside the plain roots `a` and `b`. */
+  files: Record<string, string>;
+  env?: NodeJS.ProcessEnv;
+  terraform?: Partial<TerraformConfig>;
+  /** The refusal kind both sides give, or undefined when chant locks it. */
+  refused?: string;
+}
+
+const s3 = (body: string): string => `terraform {\n  backend "s3" {\n    bucket = "b"\n    key    = "c.tfstate"\n${body}  }\n}\n`;
+
+const CASES: Case[] = [
+  { name: "s3 with use_lockfile = true in the code", files: { "main.tf": s3("    use_lockfile = true\n") } },
+  { name: "s3 with no lock file", files: { "main.tf": s3("") }, refused: "no-lockfile" },
+  { name: "s3 whose use_lockfile = true reaches init only through TF_CLI_ARGS_init", files: { "main.tf": s3("") }, env: { TF_CLI_ARGS_init: "-input=false -backend-config=use_lockfile=true" } },
+  { name: "s3 whose use_lockfile = true is in backendConfig", files: { "main.tf": s3("") }, terraform: { roots: { a: { dir: "roots/a" }, b: { dir: "roots/b" }, c: { dir: "roots/c", backendConfig: { use_lockfile: "true" } } } } },
+  { name: "gcs", files: { "main.tf": 'terraform {\n  backend "gcs" {\n    bucket = "b"\n    prefix = "c"\n  }\n}\n' } },
+  { name: "azurerm", files: { "main.tf": 'terraform {\n  backend "azurerm" {\n    storage_account_name = "acct"\n    container_name = "tfstate"\n    key = "c.tfstate"\n  }\n}\n' } },
+  { name: "local, declared", files: { "main.tf": 'terraform {\n  backend "local" {}\n}\n' } },
+  { name: "local, by declaring nothing", files: { "main.tf": EMPTY } },
+  { name: "a cloud block", files: { "main.tf": 'terraform {\n  cloud {\n    organization = "o"\n  }\n}\n' }, refused: "cloud" },
+  { name: "a cloud block in a .tofu file of a tofu root", files: { "main.tofu": 'terraform {\n  cloud {\n    organization = "o"\n  }\n}\n' }, terraform: { binary: "tofu" }, refused: "cloud" },
+  { name: "another backend", files: { "main.tf": 'terraform {\n  backend "consul" {\n    path = "c"\n  }\n}\n' }, refused: "backend" },
+  {
+    name: "s3 whose use_lockfile = true is only in a backend-config file (chant#4459)",
+    files: { "main.tf": s3(""), "backend.hcl": "# the lock\nuse_lockfile = true\n" },
+    terraform: { roots: { a: { dir: "roots/a" }, b: { dir: "roots/b" }, c: { dir: "roots/c", backendConfigFiles: ["backend.hcl"] } } },
+  },
+  {
+    name: "init recorded another bucket than the code names",
+    files: { "main.tf": s3("    use_lockfile = true\n"), ".terraform/terraform.tfstate": record("s3", { bucket: "elsewhere", key: "c.tfstate", use_lockfile: true }) },
+    refused: "disagree",
+  },
+  {
+    name: "init recorded s3 and the code now names gcs",
+    files: { "main.tf": 'terraform {\n  backend "gcs" {\n    bucket = "b"\n  }\n}\n', ".terraform/terraform.tfstate": record("s3", { bucket: "b", key: "k", use_lockfile: true }) },
+    refused: "disagree",
+  },
+  {
+    name: "init recorded what the code names, plus defaults the code leaves out",
+    files: { "main.tf": s3("    use_lockfile = true\n"), ".terraform/terraform.tfstate": record("s3", { bucket: "b", key: "c.tfstate", use_lockfile: true, region: "us-east-1", workspace_key_prefix: null }) },
+  },
+];
+
+function both(c: Case): { fallback?: string; state: ReturnType<typeof stateObject> } {
+  const dir = project({ "roots/a/main.tf": EMPTY, "roots/b/main.tf": EMPTY, ...Object.fromEntries(Object.entries(c.files).map(([f, t]) => [`roots/c/${f}`, t])) });
+  const env = { ...CREDS, ...c.env };
+  const terraform: TerraformConfig = { roots: { a: { dir: "roots/a" }, b: { dir: "roots/b" }, c: { dir: "roots/c" } }, compose: { enabled: true }, ...c.terraform } as TerraformConfig;
+  const input: CompositionInput = { projectRoot: dir, components: [tf("a"), tf("b"), tf("c")], env, terraform };
+  const fallback = compositionFor(input).fallbacks.find((f) => f.member === "c" && f.kind === "backend")?.reason;
+  const state = stateObject(join(dir, "roots/c"), env, undefined, terraform.binary, {
+    ...(terraform.roots.c?.backendConfig ? { backendConfig: terraform.roots.c.backendConfig } : {}),
+    ...(terraform.roots.c?.backendConfigFiles ? { backendConfigFiles: terraform.roots.c.backendConfigFiles } : {}),
+  });
+  return { ...(fallback ? { fallback } : {}), state };
+}
+
+describe("compose and state give one verdict per root (chant#4478)", () => {
+  for (const c of CASES) {
+    test(c.name, () => {
+      const { fallback, state } = both(c);
+      if (c.refused === undefined) {
+        expect(fallback).toBeUndefined();
+        expect(isRefused(state)).toBe(false);
+        return;
+      }
+      expect(state).toMatchObject({ refused: c.refused });
+      expect(fallback).toBe(`\`c\`: ${isRefused(state) ? state.reason : ""}`);
+    });
+  }
+
+  test("a disagreement names both sides", () => {
+    const { state } = both(CASES.find((c) => c.name.startsWith("init recorded another bucket"))!);
+    expect(isRefused(state) && state.reason).toContain('bucket = "b" in the code and flags, bucket = "elsewhere" in what init recorded');
+  });
+
+  test("a disagreement over a secret names the key, not its values", () => {
+    const dir = project({ "main.tf": 'terraform {\n  backend "s3" {\n    bucket = "b"\n    key = "k"\n    use_lockfile = true\n    secret_key = "one"\n  }\n}\n' });
+    const reading = readBackend(dir, { recorded: { type: "s3", config: { bucket: "b", key: "k", use_lockfile: true, secret_key: "two" } } });
+    expect(reading.disagreement).toContain("secret_key (value hidden)");
+    expect(reading.disagreement).not.toContain("one");
+    expect(reading.disagreement).not.toContain("two");
+  });
+});
+
+describe("the parts of the verdict", () => {
+  test("the lockable list is the one LOCKS spells", () => {
+    expect(LOCKABLE_BACKENDS).toEqual(["s3", "gcs", "azurerm", "local"]);
+    expect(LOCKS).toBe("chant locks and writes s3 (with use_lockfile = true), gcs, azurerm and local states");
+    for (const type of LOCKABLE_BACKENDS) expect(lockRefusal({ backend: { type, config: { use_lockfile: true } } })).toBeUndefined();
+  });
+
+  test("TF_CLI_ARGS and TF_CLI_ARGS_init -backend-config flags, pairs and files, later over earlier", () => {
+    expect(cliBackendConfig({ TF_CLI_ARGS: "-backend-config=region=eu-west-1 -backend-config backend.hcl", TF_CLI_ARGS_init: '-backend-config="region=us-east-2" --backend-config=use_lockfile=true' })).toMatchObject({
+      pairs: { region: "us-east-2", use_lockfile: "true" },
+      files: ["backend.hcl"],
+    });
+  });
+
+  test("the declared backend: code, then TF_CLI_ARGS*, then backendConfig", () => {
+    const dir = project({ "main.tf": 'terraform {\n  backend "s3" {\n    bucket = "b"\n    key = "k"\n    assume_role {\n      role_arn = "nested"\n    }\n  }\n}\n' });
+    expect(declaredBackend(dir, { env: { TF_CLI_ARGS_init: "-backend-config=key=from-env" }, backendConfig: { use_lockfile: "true" } })).toEqual({
+      type: "s3",
+      config: { bucket: "b", key: "from-env", use_lockfile: true },
+    });
+  });
+
+  test("the declared backend in Terraform's JSON syntax", () => {
+    const dir = project({ "main.tf.json": JSON.stringify({ terraform: { backend: { s3: { bucket: "b", key: "k", use_lockfile: true } } } }) });
+    expect(declaredBackend(dir)).toEqual({ type: "s3", config: { bucket: "b", key: "k", use_lockfile: true } });
+  });
+});
+
+describe("compose's state address comes from the same verdict (chant#4478 round 2)", () => {
+  const S3_NO_KEY = 'terraform {\n  backend "s3" {\n    bucket = "b"\n    use_lockfile = true\n  }\n}\n';
+  const reader = 'data "terraform_remote_state" "a" {\n  backend = "s3"\n  config = {\n    bucket = "b"\n    key    = "a.tfstate"\n  }\n}\n\nresource "terraform_data" "x" {\n  input = data.terraform_remote_state.a.outputs.id\n}\n';
+
+  test("a key only TF_CLI_ARGS_init gives is the root's state address, as stateObject reads it", () => {
+    const dir = project({ "main.tf": S3_NO_KEY });
+    const env = { ...CREDS, TF_CLI_ARGS_init: "-backend-config=key=from-init-args.tfstate" };
+    expect(rootState(dir, "app", { env, recorded: null }).own).toEqual({ bucket: "b", key: "from-init-args.tfstate" });
+    expect(stateObject(dir, env, undefined)).toMatchObject({ backend: "s3", bucket: "b", key: "from-init-args.tfstate" });
+    expect(rootState(dir, "app", { env: {}, recorded: null }).own).toBeUndefined();
+  });
+
+  test("a key TF_CLI_ARGS gives is overridden by TF_CLI_ARGS_init, as init applies them", () => {
+    const dir = project({ "main.tf": S3_NO_KEY });
+    const env = { TF_CLI_ARGS: "-backend-config=key=first.tfstate", TF_CLI_ARGS_init: "-backend-config=key=second.tfstate" };
+    expect(rootState(dir, "app", { env, recorded: null }).own).toEqual({ bucket: "b", key: "second.tfstate" });
+  });
+
+  test("after init, the recorded configuration names the state", () => {
+    const dir = project({ "main.tf": S3_NO_KEY, ".terraform/terraform.tfstate": record("s3", { bucket: "b", key: "recorded.tfstate", use_lockfile: true, region: null }) });
+    expect(rootState(dir, "app", { env: {} }).own).toEqual({ bucket: "b", key: "recorded.tfstate" });
+  });
+
+  test("a composition lines a read up with a member whose key comes only from TF_CLI_ARGS_init", () => {
+    const dir = project({ "roots/a/main.tf": S3_NO_KEY, "roots/b/main.tf": S3_NO_KEY + reader });
+    const c = compositionFor({
+      projectRoot: dir,
+      env: { TF_CLI_ARGS_init: "-backend-config=key=a.tfstate" },
+      components: [tf("a"), tf("b")],
+      terraform: { roots: { a: { dir: "roots/a" }, b: { dir: "roots/b" } }, compose: { enabled: true } },
+    });
+    expect(c.reads.get("b")).toEqual([{ via: "remote-state", upstream: "a", name: "a" }]);
+  });
+});

package/src/state/backend.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Where a root's state is (#4437). Carried over from terragucci at c493e0e:
+ * test/state-versions.test.ts "where a root's state is" and
+ * test/state-stores.test.ts "where a gcs or azurerm root's state is", with
+ * the refusals chant adds (no lock file, a cloud block, any other backend).
+ */
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { initialisedBackend, isRefused, s3StateKey, stateLocation, stateObject, workspaceOf } from "./backend";
+
+const tmp = (): string => mkdtempSync(join(tmpdir(), "chant-state-"));
+const write = (dir: string, files: Record<string, string>): string => {
+  for (const [f, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, f)), { recursive: true });
+    writeFileSync(join(dir, f), text);
+  }
+  return dir;
+};
+/** A root whose `.terraform` records `type` and `config`, as init leaves it. */
+const initialised = (type: string, config: Record<string, unknown>, files: Record<string, string> = {}): string =>
+  write(tmp(), { ".terraform/terraform.tfstate": JSON.stringify({ version: 3, backend: { type, config, hash: 1 } }), ...files });
+
+const ENV = { AWS_ACCESS_KEY_ID: "AK", AWS_SECRET_ACCESS_KEY: "SK", AWS_REGION: "us-east-1" };
+const S3_CONFIG = { bucket: "acme-state", key: "envs/dev/platform.tfstate", region: "eu-west-1", use_lockfile: true, endpoints: { s3: "http://floci:4566", dynamodb: null }, access_key: null, workspace_key_prefix: null };
+const GCS = { bucket: "acme-state", prefix: "envs/dev/app", storage_custom_endpoint: "http://gcs.test/storage/v1/", access_token: "backend-token" };
+const AZ = { storage_account_name: "acme", container_name: "tfstate", key: "app.tfstate", access_key: Buffer.from("key").toString("base64") };
+
+describe("where an s3 or local root's state is", () => {
+  it("reads the backend init recorded, s3 with its bucket, key, region and endpoint", () => {
+    const dir = initialised("s3", S3_CONFIG);
+    expect(initialisedBackend(dir)?.type).toBe("s3");
+    const o = stateObject(dir, ENV);
+    expect(o).toMatchObject({ backend: "s3", bucket: "acme-state", key: "envs/dev/platform.tfstate", region: "eu-west-1", endpoint: "http://floci:4566", lockfile: true });
+    expect(stateLocation(o)).toBe("s3://acme-state/envs/dev/platform.tfstate");
+  });
+
+  it("takes the endpoint from AWS_ENDPOINT_URL when the backend names none, and the key of another workspace", () => {
+    const dir = initialised("s3", { ...S3_CONFIG, endpoints: null, workspace_key_prefix: "ws" });
+    expect(stateObject(dir, { ...ENV, AWS_ENDPOINT_URL: "http://floci:4566/", TF_WORKSPACE: "blue" })).toMatchObject({ endpoint: "http://floci:4566", key: "ws/blue/envs/dev/platform.tfstate" });
+    expect(s3StateKey("k", "default")).toBe("k");
+    expect(s3StateKey("k", "green")).toBe("env:/green/k");
+  });
+
+  it("reads the workspace select recorded, and TF_DATA_DIR in place of .terraform", () => {
+    const dir = write(tmp(), { "data/terraform.tfstate": JSON.stringify({ backend: { type: "s3", config: S3_CONFIG } }), "data/environment": "green\n" });
+    expect(workspaceOf(dir, { TF_DATA_DIR: "data" })).toBe("green");
+    expect(stateObject(dir, { ...ENV, TF_DATA_DIR: "data" })).toMatchObject({ key: "env:/green/envs/dev/platform.tfstate" });
+  });
+
+  it("signs with the backend's own static keys when its configuration names them", () => {
+    const o = stateObject(initialised("s3", { ...S3_CONFIG, access_key: "BACKENDKEY", secret_key: "s" }), ENV);
+    expect(o).toMatchObject({ target: { accessKeyId: "BACKENDKEY", secretAccessKey: "s" } });
+  });
+
+  it("is a local file when init recorded no backend or a local one", () => {
+    expect(stateObject(tmp(), ENV)).toEqual({ backend: "local", path: "terraform.tfstate" });
+    expect(stateObject(initialised("local", { path: "state/x.tfstate" }), ENV)).toEqual({ backend: "local", path: "state/x.tfstate" });
+    expect(stateObject(initialised("local", {}), { TF_WORKSPACE: "blue" })).toEqual({ backend: "local", path: join("terraform.tfstate.d", "blue", "terraform.tfstate") });
+  });
+});
+
+describe("where a gcs or azurerm root's state is", () => {
+  it("names a gcs state <prefix>/<workspace>.tfstate, its lock beside it, with the backend's own credentials first", () => {
+    expect(stateObject(initialised("gcs", GCS), { GOOGLE_APPLICATION_CREDENTIALS: "/job/creds.json" })).toMatchObject({ backend: "gcs", bucket: "acme-state", key: "envs/dev/app/default.tfstate", lock: "envs/dev/app/default.tflock", target: { endpoint: "http://gcs.test", accessToken: "backend-token" } });
+    expect(stateObject(initialised("gcs", { bucket: "b", prefix: "p/" }), { TF_WORKSPACE: "blue", GOOGLE_APPLICATION_CREDENTIALS: "/job/creds.json" })).toMatchObject({ key: "p/blue.tfstate", lock: "p/blue.tflock", target: { endpoint: "https://storage.googleapis.com", credentialsFile: "/job/creds.json" } });
+    expect(stateObject(initialised("gcs", { bucket: "b" }), { GOOGLE_CREDENTIALS: '{"type":"service_account"}' })).toMatchObject({ key: "default.tfstate", target: { credentialsJson: '{"type":"service_account"}' } });
+    expect(stateObject(initialised("gcs", { bucket: "b", impersonate_service_account: "sa@p.iam.gserviceaccount.com" }), { GOOGLE_OAUTH_ACCESS_TOKEN: "t" })).toMatchObject({ target: { accessToken: "t", impersonate: "sa@p.iam.gserviceaccount.com" } });
+    expect(stateObject(initialised("gcs", { bucket: "b" }), {})).toMatchObject({ backend: "gcs", refused: "credentials" });
+  });
+
+  it("names an azurerm blob by its key, <key>env:<workspace> in another workspace, at the cloud's endpoint, with the key, a SAS or the job's OIDC identity", () => {
+    expect(stateObject(initialised("azurerm", AZ), {})).toMatchObject({ backend: "azurerm", account: "acme", container: "tfstate", key: "app.tfstate", endpoint: "https://acme.blob.core.windows.net", auth: { accountKey: AZ.access_key } });
+    expect(stateObject(initialised("azurerm", { ...AZ, access_key: null, environment: "usgovernment" }), { TF_WORKSPACE: "blue", ARM_SAS_TOKEN: "sv=x&sig=y" })).toMatchObject({ key: "app.tfstateenv:blue", endpoint: "https://acme.blob.core.usgovcloudapi.net", auth: { sas: "sv=x&sig=y" } });
+    const oidc = { ARM_TENANT_ID: "tenant", ARM_CLIENT_ID: "client", ARM_OIDC_TOKEN_FILE_PATH: "/t" };
+    expect(stateObject(initialised("azurerm", { ...AZ, access_key: null, snapshot: true }), oidc)).toMatchObject({ snapshot: true, auth: { oidc: { tenantId: "tenant", clientId: "client", tokenFile: "/t", authority: "https://login.microsoftonline.com" } } });
+    expect(stateObject(initialised("azurerm", { ...AZ, access_key: null }), {})).toMatchObject({ refused: "credentials" });
+    expect(stateObject(initialised("azurerm", { key: "k" }), {})).toMatchObject({ refused: "config", reason: expect.stringContaining("storage_account_name, container_name or key") });
+  });
+});
+
+describe("a state chant does not lock", () => {
+  it("is an s3 backend without use_lockfile, named as such", () => {
+    for (const use_lockfile of [undefined, false]) {
+      const o = stateObject(initialised("s3", { ...S3_CONFIG, use_lockfile }), ENV);
+      expect(o).toMatchObject({ backend: "s3", refused: "no-lockfile", reason: expect.stringContaining("use_lockfile = true is unset") });
+      expect(stateLocation(o)).toBeUndefined();
+    }
+  });
+
+  it("is a root with a cloud block, in .tf or .tf.json code, or one init recorded as cloud", () => {
+    const hcl = write(tmp(), { "main.tf": 'terraform {\n  cloud {\n    organization = "acme"\n  }\n}\n' });
+    expect(stateObject(hcl, ENV)).toMatchObject({ refused: "cloud", reason: expect.stringContaining("cloud block") });
+    const json = write(tmp(), { "cdk.tf.json": JSON.stringify({ terraform: [{ required_version: ">= 1.10" }, { cloud: { organization: "acme" } }] }) });
+    expect(stateObject(json, ENV)).toMatchObject({ refused: "cloud" });
+    expect(stateObject(initialised("cloud", { organization: "acme" }), ENV)).toMatchObject({ backend: "cloud", refused: "cloud" });
+    // A cloud block added after init recorded s3: the code and the record disagree, and the refusal names both (chant#4478).
+    expect(stateObject(initialised("s3", S3_CONFIG, { "main.tf": "terraform {\n  cloud {}\n}\n" }), ENV)).toMatchObject({
+      refused: "disagree",
+      reason: expect.stringContaining("names the cloud backend and init recorded s3"),
+    });
+  });
+
+  it("is any other backend, named by its type", () => {
+    for (const type of ["pg", "kubernetes", "consul", "http", "remote", "cos"]) {
+      const o = stateObject(initialised(type, {}), ENV);
+      expect(isRefused(o)).toBe(true);
+      expect(o).toMatchObject({ backend: type, refused: "backend", reason: expect.stringContaining(`backend is ${type}`) });
+    }
+  });
+
+  it("is an s3 backend without its bucket or key, or without credentials", () => {
+    expect(stateObject(initialised("s3", { ...S3_CONFIG, key: null }), ENV)).toMatchObject({ refused: "config" });
+    expect(stateObject(initialised("s3", S3_CONFIG), {})).toMatchObject({ refused: "credentials", reason: expect.stringContaining("s3://acme-state") });
+  });
+});
+
+describe("the state module", () => {
+  it("is plain lexicon code: nothing in it imports from @intentius/chant/components", () => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const sources = readdirSync(here).filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts"));
+    expect(sources.length).toBeGreaterThan(5);
+    for (const f of sources) expect(readFileSync(join(here, f), "utf-8"), f).not.toMatch(/@intentius\/chant\/components/);
+  });
+});