@intentius/chant-lexicon-terraform 0.124.51 → 0.124.54

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,223 @@
+/**
+ * Azure Blob Storage for an azurerm backend's state, over its REST API with
+ * `fetch` and `node:crypto`: a blob's properties and metadata, its text, a
+ * write (under a lease when one holds it), a snapshot, a delete, and the
+ * blob lease the backend locks a state with.
+ *
+ * Requests are signed with Shared Key for an account key, carry a SAS as it
+ * is, or carry a storage token the job's OIDC identity is traded for at Entra
+ * ID (a client assertion, the way the azurerm backend does it).
+ *
+ * Lifted from terragucci's `report/azure-blob.ts` (c493e0e), without SAS
+ * links, version reads and version listing.
+ */
+import { createHmac } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { defaultFetch, encodePath, StoreError, xmlText, type StoreFetch } from "./object-store";
+
+/** The REST version every request names. */
+export const AZURE_VERSION = "2021-08-06";
+
+/** Entra ID's public cloud. */
+export const AZURE_AUTHORITY = "https://login.microsoftonline.com";
+
+const STORAGE_SCOPE = "https://storage.azure.com/.default";
+
+export interface AzureLocation {
+  account: string;
+  container: string;
+  /** The account's blob endpoint, no trailing slash: https://<account>.blob.core.windows.net, or an emulator's http://host:10000/<account>. */
+  endpoint: string;
+}
+
+/** The job's federated identity: an Entra app or managed identity that trusts the forge's token. */
+export interface AzureOidc {
+  tenantId: string;
+  clientId: string;
+  tokenFile: string;
+  /** Entra ID's address, https://host, no path. */
+  authority: string;
+}
+
+export type AzureTarget = AzureLocation & ({ accountKey: string } | { oidc: AzureOidc } | { sas: string });
+
+/** A blob's properties, as a HEAD answers them: never its body. */
+export interface BlobHead {
+  exists: boolean;
+  etag?: string;
+  /** x-ms-lease-state: `leased` while a lease holds it. */
+  leaseState?: string;
+  /** Its metadata, by name without the x-ms-meta- prefix. */
+  metadata: Record<string, string>;
+}
+
+const hmac64 = (key: string, s: string): string => createHmac("sha256", Buffer.from(key, "base64")).update(s, "utf8").digest("base64");
+
+/** The headers whose values Shared Key signs by position, in order. */
+const SIGNED = ["content-encoding", "content-language", "content-length", "content-md5", "content-type", "date", "if-modified-since", "if-match", "if-none-match", "if-unmodified-since", "range"];
+
+/** The Shared Key Authorization header for a request. */
+export function sharedKey(account: string, accountKey: string, method: string, rawUrl: string, headers: Record<string, string>): string {
+  const url = new URL(rawUrl);
+  const h = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+  const fixed = SIGNED.map((n) => (n === "content-length" && h[n] === "0" ? "" : (h[n] ?? "")));
+  const ms = Object.keys(h).filter((n) => n.startsWith("x-ms-")).sort().map((n) => `${n}:${h[n]!.trim()}\n`).join("");
+  const params = new Map<string, string[]>();
+  for (const [k, v] of url.searchParams) params.set(k.toLowerCase(), [...(params.get(k.toLowerCase()) ?? []), v]);
+  const query = [...params.keys()].sort().map((k) => `\n${k}:${params.get(k)!.sort().join(",")}`).join("");
+  const toSign = [method, ...fixed].join("\n") + "\n" + ms + `/${account}${url.pathname}` + query;
+  return `SharedKey ${account}:${hmac64(accountKey, toSign)}`;
+}
+
+/** Entra ID's error, or the start of the body. */
+const why = (text: string): string => {
+  try {
+    const j = JSON.parse(text) as { error?: string; error_description?: string };
+    if (j.error) return [j.error, j.error_description?.split("\r\n")[0]].filter(Boolean).join(": ");
+  } catch {
+    // Not JSON: Blob Storage answers in XML.
+  }
+  return [xmlText(text, "Code"), xmlText(text, "Message")?.split("\n")[0]].filter(Boolean).join(": ") || text.slice(0, 300);
+};
+
+export class AzureBlobClient {
+  private token?: Promise<{ token: string; expires: number }>;
+
+  constructor(readonly target: AzureTarget, private readonly fetchFn: StoreFetch = defaultFetch, private readonly readToken: (file: string) => string = (f) => readFileSync(f, "utf-8")) {}
+
+  private where(key: string): string {
+    return `az://${this.target.account}/${this.target.container}/${key}`;
+  }
+
+  private blobUrl(key: string, query = ""): string {
+    const t = this.target;
+    const q = [query, "sas" in t ? t.sas.replace(/^\?/, "") : ""].filter(Boolean).join("&");
+    return `${t.endpoint}/${t.container}/${encodePath(key)}${q ? `?${q}` : ""}`;
+  }
+
+  /** The storage token for the OIDC identity: once per client, again a minute before it expires. */
+  private async bearer(o: AzureOidc): Promise<string> {
+    const fetchToken = async (): Promise<{ token: string; expires: number }> => {
+      let assertion: string;
+      try {
+        assertion = this.readToken(o.tokenFile).trim();
+      } catch (e) {
+        throw new StoreError(`cannot read the OIDC token in ${o.tokenFile}: ${(e as Error).message}`);
+      }
+      if (!assertion) throw new StoreError(`the OIDC token file ${o.tokenFile} is empty`);
+      const body = new URLSearchParams({
+        client_id: o.clientId,
+        scope: STORAGE_SCOPE,
+        grant_type: "client_credentials",
+        client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+        client_assertion: assertion,
+      }).toString();
+      const res = await this.fetchFn(`${o.authority}/${o.tenantId}/oauth2/v2.0/token`, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body });
+      const text = await res.text();
+      if (!res.ok) throw new StoreError(`Entra ID refused the OIDC token for client ${o.clientId}: ${res.status} ${why(text)}`);
+      let j: { access_token?: string; expires_in?: number | string } = {};
+      try {
+        j = JSON.parse(text) as typeof j;
+      } catch {
+        // Reported below as no token.
+      }
+      if (!j.access_token) throw new StoreError(`Entra ID answered client ${o.clientId} without a token`);
+      return { token: j.access_token, expires: Date.now() + Number(j.expires_in ?? 3600) * 1000 };
+    };
+    const again = (): Promise<{ token: string; expires: number }> =>
+      (this.token = fetchToken().catch((e: unknown) => {
+        this.token = undefined;
+        throw e;
+      }));
+    let held = await (this.token ?? again());
+    if (held.expires - Date.now() < 60_000) held = await again();
+    return held.token;
+  }
+
+  /** The headers for one request, signed or with the bearer token. */
+  private async headers(method: string, url: string, extra: Record<string, string>): Promise<Record<string, string>> {
+    const h: Record<string, string> = { "x-ms-date": new Date().toUTCString(), "x-ms-version": AZURE_VERSION, ...extra };
+    const t = this.target;
+    if ("accountKey" in t) return { ...h, authorization: sharedKey(t.account, t.accountKey, method, url, h) };
+    if ("sas" in t) return h;
+    return { ...h, authorization: `Bearer ${await this.bearer(t.oidc)}` };
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    const url = this.blobUrl(key);
+    const res = await this.fetchFn(url, { method: "GET", headers: await this.headers("GET", url, {}) });
+    if (res.status === 404) return undefined;
+    if (!res.ok) throw new StoreError(`GET ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+    return res.text();
+  }
+
+  /** A blob's properties and metadata, from a HEAD. */
+  async head(key: string): Promise<BlobHead> {
+    const url = this.blobUrl(key);
+    const res = await this.fetchFn(url, { method: "HEAD", headers: await this.headers("HEAD", url, {}) });
+    if (res.status === 404) return { exists: false, metadata: {} };
+    if (!res.ok) throw new StoreError(`HEAD ${this.where(key)}: ${res.status}`);
+    const get = (n: string): string | undefined => res.headers?.get(n) ?? undefined;
+    const metadata: Record<string, string> = {};
+    const all = res.headers as unknown as { forEach?: (fn: (v: string, k: string) => void) => void } | undefined;
+    all?.forEach?.((v, k) => {
+      if (k.toLowerCase().startsWith("x-ms-meta-")) metadata[k.toLowerCase().slice("x-ms-meta-".length)] = v;
+    });
+    const etag = get("etag");
+    const leaseState = get("x-ms-lease-state");
+    return { exists: true, ...(etag ? { etag } : {}), ...(leaseState ? { leaseState } : {}), metadata };
+  }
+
+  /** Take a snapshot of a blob: its id, the time Azure gives it. */
+  async snapshot(key: string): Promise<string> {
+    const url = this.blobUrl(key, "comp=snapshot");
+    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, { "content-length": "0" }) });
+    if (!res.ok) throw new StoreError(`snapshot of ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+    const id = res.headers?.get("x-ms-snapshot");
+    if (!id) throw new StoreError(`snapshot of ${this.where(key)}: Azure answered without x-ms-snapshot`);
+    return id;
+  }
+
+  /** Write a block blob with metadata, under a lease when one holds it; with `ifNoneMatch`, only when there is none (false when one was there). */
+  async putBlob(key: string, body: string, contentType: string, options: { leaseId?: string; metadata?: Record<string, string>; ifNoneMatch?: boolean } = {}): Promise<boolean> {
+    const url = this.blobUrl(key);
+    const meta = Object.fromEntries(Object.entries(options.metadata ?? {}).map(([k, v]) => [`x-ms-meta-${k}`, v]));
+    const extra: Record<string, string> = {
+      "x-ms-blob-type": "BlockBlob",
+      "content-type": contentType,
+      "content-length": String(Buffer.byteLength(body)),
+      ...meta,
+      ...(options.leaseId ? { "x-ms-lease-id": options.leaseId } : {}),
+      ...(options.ifNoneMatch ? { "if-none-match": "*" } : {}),
+    };
+    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, extra), body });
+    if (options.ifNoneMatch && (res.status === 409 || res.status === 412)) return false;
+    if (!res.ok) throw new StoreError(`PUT ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+    return true;
+  }
+
+  /** Delete a blob. One that is not there is deleted already. */
+  async remove(key: string): Promise<void> {
+    const url = this.blobUrl(key);
+    const res = await this.fetchFn(url, { method: "DELETE", headers: await this.headers("DELETE", url, {}) });
+    if (!res.ok && res.status !== 404) throw new StoreError(`DELETE ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+  }
+
+  /** A blob lease: acquire one that never expires with the id given (false when one holds it), or release it. */
+  async lease(key: string, action: "acquire" | "release", id: string): Promise<boolean> {
+    const url = this.blobUrl(key, "comp=lease");
+    const extra: Record<string, string> = { "x-ms-lease-action": action, "content-length": "0", ...(action === "acquire" ? { "x-ms-lease-duration": "-1", "x-ms-proposed-lease-id": id } : { "x-ms-lease-id": id }) };
+    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, extra) });
+    if (action === "acquire" && res.status === 409) return false;
+    if (!res.ok) throw new StoreError(`${action} the lease of ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+    return true;
+  }
+
+  /** Set a blob's metadata, all of it, under its lease when one holds it. */
+  async setMetadata(key: string, metadata: Record<string, string>, leaseId?: string): Promise<void> {
+    const url = this.blobUrl(key, "comp=metadata");
+    const extra = { "content-length": "0", ...Object.fromEntries(Object.entries(metadata).map(([k, v]) => [`x-ms-meta-${k}`, v])), ...(leaseId ? { "x-ms-lease-id": leaseId } : {}) };
+    const res = await this.fetchFn(url, { method: "PUT", headers: await this.headers("PUT", url, extra) });
+    if (!res.ok) throw new StoreError(`set the metadata of ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+  }
+}

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/);
+  });
+});