@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/dist/report.js

@@ -32,6 +32,10 @@ import { dirname, join } from "node:path";
 import { changeSetDigest, composeChangeSet } from "@intentius/chant/change-set";
 import { groupChangeSet } from "@intentius/chant/plan-summary";
 import { plannerForBinary, terraformChangeSetPart } from "./change-set.js";
+import { moduleChanges, stripModule, topModule } from "./compose/module-address.js";
+import { stateResources } from "./applied-state.js";
+import { isJsonConfigFile, jsonLiveBlocks, listConfigFiles } from "./hcl/files.js";
+export { topModule } from "./compose/module-address.js";
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 export const REPORT_SCHEMA = "terragucci.report/v1";
 export const INDEX_SCHEMA = "terragucci.report-index/v1";
@@ -66,39 +70,14 @@ export function runFactsFromEnv(env, over = {}) {
 // ---------------------------------------------------------------------------
 // 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) {
-    return TOP_MODULE.exec(address)?.[1];
-}
-/** `address` with its leading `module.<m>` (and index) taken off. */
-function unprefix(address) {
-    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, m) {
     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;
-        const out = { ...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`. */
 function marks(v) {
@@ -110,27 +89,6 @@ function marks(v) {
         return Object.values(v).some(marks);
     return false;
 }
-/** Every resource of a `show -json` state, by address. A deposed object is left out. */
-function stateResources(show) {
-    const out = new Map();
-    const walk = (mod) => {
-        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, res) {
     if (!res || !attributes.some((a) => a.unknown))
@@ -147,16 +105,29 @@ function resolveUnknowns(attributes, res) {
         return { ...rest, ...(a.before !== undefined ? { before: a.before } : {}), after: value };
     });
 }
-/** The estate named by the first `live { estate = "..." }` block in a directory's `.tf` files, or undefined. */
-export function estateOfDir(dir) {
+/**
+ * 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, binary = "choudoufu") {
     let files;
     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) => 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)
@@ -240,7 +211,7 @@ function unknownOutputsOf(plan, u) {
             const [type, rname, attr] = data ? [parts[1], parts[2], parts[3]] : [parts[0], parts[1], parts[2]];
             if (!type || !rname)
                 continue;
-            const unprefixed = (c) => unprefix(String(c.address)).replace(/\[[^\]]*\]$/, "");
+            const unprefixed = (c) => stripModule(String(c.address)).replace(/\[[^\]]*\]$/, "");
             for (const c of changes) {
                 if (unprefixed(c) !== `${data ? "data." : ""}${type}.${rname}`)
                     continue;
@@ -604,7 +575,7 @@ export function terraformReport(input) {
         ...(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 };
 }
 // ---------------------------------------------------------------------------
 // The indexes.
@@ -632,7 +603,8 @@ export function addToIndex(existing, row) {
     return { schema: INDEX_SCHEMA, reports: reports.slice(0, INDEX_ROWS) };
 }
 /**
- * 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.
@@ -645,6 +617,7 @@ export async function writeReport(store, r) {
         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}`]]) {
         await put(key, addToIndex(await store.read(key), { ...r.row, path }));
     }

package/dist/rules/record-store.ts

@@ -0,0 +1,122 @@
+/**
+ * The record store a live root resolves to, read from its HCL the way
+ * choudoufu resolves it (INTENTIUS/choudoufu#2293, `internal/configs/live_derive.go`
+ * at choudoufu 74ffde956bfd97f44b8ad444424584e23321adc2). Shared by TF024,
+ * which names where records go, and TF046, which guards a CI root that ends
+ * up on the local store, so the two never disagree.
+ *
+ * The order is choudoufu's:
+ *
+ * 1. A `record_store "<kind>"` block in the `live` block or the
+ *    `estate.chdf.hcl` sidecar always wins (`source: "record_store"`).
+ * 2. Otherwise the backend block choudoufu ignores under live gives the store,
+ *    s3 to s3, gcs to gcs, azurerm to azurerm (`source: "backend"`). s3 and gcs
+ *    need a literal `bucket`; azurerm needs literal `storage_account_name`,
+ *    `container_name` and `resource_group_name`. A value passed only with
+ *    `-backend-config` is not in the configuration, so choudoufu does not see
+ *    it either.
+ * 3. Otherwise the store is local (`source: "implied"`), with `note` saying
+ *    why a backend that was there was not used.
+ *
+ * This mirrors `record_store.source` and `record_store.note` in
+ * `choudoufu live-check -json`. A literal here is a string hcl2json hands back
+ * with no `${...}` in it, the same "not determined" reading the Terragrunt
+ * rules use (`./terragrunt.ts`).
+ */
+
+import type { BlockBody } from "../../hcl/parse";
+import { backendTypes } from "./tf001";
+import { isExpression } from "./terragrunt";
+
+export type RecordStoreSource = "record_store" | "backend" | "implied";
+
+export interface ResolvedRecordStore {
+  /** `local`, `s3`, `gcs`, `azurerm` or `kubernetes`, or whatever label a `record_store` block carries. */
+  kind: string;
+  source: RecordStoreSource;
+  /** The backend type the store came from, or was not derived from, when there is a backend block. */
+  backend?: string;
+  /** Why a backend block that was present did not give a store. Set only with `source: "implied"`. */
+  note?: string;
+}
+
+/** Backend types choudoufu derives a record store from (INTENTIUS/choudoufu#2293). */
+export const DERIVABLE_BACKENDS: ReadonlySet<string> = new Set(["s3", "gcs", "azurerm"]);
+
+const asRecord = (v: unknown): BlockBody =>
+  typeof v === "object" && v !== null && !Array.isArray(v) ? (v as BlockBody) : {};
+
+const firstBody = (v: unknown): BlockBody => asRecord(Array.isArray(v) ? v[0] : v);
+
+/**
+ * The label of a `record_store "<kind>"` block in a live declaration body, or
+ * undefined when it declares none. hcl2json nests the label one level down,
+ * as it does for `backend` (see `backendTypes` in `./tf001.ts`).
+ */
+export function recordStoreKind(liveBody: BlockBody): string | undefined {
+  const raw = liveBody["record_store"];
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const labels = Object.keys(raw as BlockBody);
+  return labels[0];
+}
+
+/** A top-level backend argument as a literal string, or undefined when it is absent, empty or an expression. */
+function literal(body: BlockBody, name: string): string | undefined {
+  const v = body[name];
+  if (typeof v !== "string" || v === "" || isExpression(v)) return undefined;
+  return v;
+}
+
+/**
+ * Why a backend block gives no record store, or undefined when it gives one.
+ * The wording follows choudoufu's `Live.RecordStoreNote`; an empty string
+ * means no store and nothing to say (a `local` backend).
+ */
+function derivationNote(type: string, body: BlockBody): string | undefined {
+  const where = `backend "${type}"`;
+  switch (type) {
+    case "s3":
+    case "gcs":
+      return literal(body, "bucket") === undefined
+        ? `${where} sets no literal bucket; values passed with -backend-config are not read`
+        : undefined;
+    case "azurerm":
+      for (const name of ["storage_account_name", "container_name", "resource_group_name"]) {
+        if (literal(body, name) === undefined) return `${where} sets no literal ${name}, which the azurerm record store needs`;
+      }
+      return undefined;
+    case "local":
+      // choudoufu leaves no note here: a local backend and the local store agree.
+      return "";
+    default:
+      return `${where} has no record store counterpart`;
+  }
+}
+
+/**
+ * Resolve one live root's record store.
+ *
+ * `terraformBodies` are the bodies of every `terraform` block in the root (a
+ * backend can sit in a separate `backend.tf`). `liveBodies` are the root's
+ * live declarations: its `live` block and its sidecar, if any. choudoufu
+ * refuses a root that has both, so the first `record_store` found is the one.
+ */
+export function resolveRecordStore(
+  terraformBodies: readonly BlockBody[],
+  liveBodies: readonly BlockBody[],
+): ResolvedRecordStore {
+  for (const live of liveBodies) {
+    const kind = recordStoreKind(live);
+    if (kind !== undefined) return { kind, source: "record_store" };
+  }
+  for (const tf of terraformBodies) {
+    const type = backendTypes(tf)[0];
+    if (type === undefined) continue;
+    const body = firstBody(asRecord(tf["backend"])[type]);
+    const note = derivationNote(type, body);
+    if (note === undefined) return { kind: type, source: "backend", backend: type };
+    return { kind: "local", source: "implied", backend: type, ...(note ? { note } : {}) };
+  }
+  return { kind: "local", source: "implied" };
+}

package/dist/rules/tf001.ts

@@ -30,8 +30,8 @@
  * module's `terraform` block is skipped here rather than read as if it were
  * the root's.
  *
- * Does not fire on a live root (#2103): a `backend` block is exactly what
- * choudoufu refuses there (TF024's territory), and the fallback to local
+ * Does not fire on a live root (#2103): choudoufu ignores a `backend` block
+ * there (TF024 reports what it still does with it), and the fallback to local
  * state this check warns about does not apply, since a live root keeps no
  * state file at all, local or remote.
  */

package/dist/rules/tf024.ts

@@ -1,18 +1,38 @@
 /**
  * TF024: a live root declares a `backend` or `cloud` block.
  *
- * choudoufu refuses this combination at `init`, before any command runs,
- * naming both blocks that collide: "Both a backend and a live configuration
- * are present" (a `backend` block) or "Both a cloud and a live configuration
- * are present" (a `cloud` block). A live root keeps no state to store, since
- * prior state is a projection rebuilt from the live system every run, so
- * either block is a contradiction about where the truth lives, not a
- * redundant setting.
+ * choudoufu used to refuse this pair at `init` (#1170). Since
+ * INTENTIUS/choudoufu#2213 it accepts both and ignores them with a warning
+ * (`internal/configs/module.go`, `ignoreStateStoreUnderLive`), because
+ * Terragrunt's `remote_state` and Atmos's `backend.tf.json` write a backend
+ * beside the live block on every run. What each block still does:
+ *
+ * - `backend "<type>"`: no state is read or written there, and
+ *   `init -migrate-state` is refused. choudoufu keeps the block as
+ *   `IgnoredBackend`: an apply publishes the estate's non-sensitive outputs
+ *   to the location it names, so `terraform_remote_state` readers keep
+ *   working, and when the live declaration has no `record_store` the record
+ *   store is derived from the backend's bucket, s3 to s3, gcs to gcs, azurerm
+ *   to azurerm (INTENTIUS/choudoufu#2293), when the bucket is a literal in
+ *   the configuration. An explicit `record_store` always wins. The resolution
+ *   is shared with TF046 in `./record-store.ts`.
+ * - `cloud {}`: dropped entirely. Nothing is published to it and no store is
+ *   derived from it.
+ *
+ * So the backend case is reported as `info` (the block is doing a job the
+ * author may want, and is the derivation source the maintainer ruled for),
+ * and the cloud case as `warning` (the block does nothing at all). Neither
+ * fails a build at default severity. The guard against a CI root that ends
+ * up on the local store is TF046 (chant#4561).
+ *
+ * The live marker is the root's `mode`, stamped from either a `live` block or
+ * an `estate.chdf.hcl` sidecar (`hcl/parse.ts`), so a sidecar estate is
+ * covered. A `record_store` is read from whichever `Terraform::Live` entity
+ * carries it: the `live` block, or the sidecar's top level.
  *
  * TF001 is the equivalent check for a stock root (no remote backend is
- * configured); it explicitly does not fire on a live root, and this check is
- * why: the two are mutually exclusive by construction; a root is flagged by
- * at most one of them.
+ * configured); it does not fire on a live root. A root is flagged by at most
+ * one of them.
  *
  * Scope: root modules only (#2112). A child module's backend or cloud block
  * is TF015's finding, whatever binary the root runs.
@@ -26,17 +46,74 @@ import type {
   PostSynthDiagnostic,
 } from "@intentius/chant/lint/post-synth";
 import { isResourceDeclarable } from "@intentius/chant/declarable";
-import { TERRAFORM_TYPE, type BlockBody } from "../../hcl/parse";
-import { hasBlock } from "./tf001";
+import { LIVE_TYPE, TERRAFORM_TYPE, type BlockBody } from "../../hcl/parse";
+import { backendTypes, hasBlock } from "./tf001";
 import { isRootScoped } from "./scope";
+import { DERIVABLE_BACKENDS, resolveRecordStore, type ResolvedRecordStore } from "./record-store";
+
+export { DERIVABLE_BACKENDS } from "./record-store";
+
+const bodyOf = (props: { body?: unknown }): BlockBody =>
+  (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+
+/** Each root's live declarations (its `live` block and its sidecar), keyed by root. */
+export function liveBodiesByRoot(ctx: PostSynthContext): Map<string, BlockBody[]> {
+  const roots = new Map<string, BlockBody[]>();
+  for (const entity of ctx.entities.values()) {
+    if (entity.entityType !== LIVE_TYPE) continue;
+    if (!isResourceDeclarable(entity) || !isRootScoped(entity)) continue;
+    const props = entity.props as { root?: unknown; body?: unknown };
+    const root = typeof props.root === "string" ? props.root : "";
+    const list = roots.get(root) ?? [];
+    list.push(bodyOf(props));
+    roots.set(root, list);
+  }
+  return roots;
+}
+
+function backendMessage(root: string, type: string, store: ResolvedRecordStore): string {
+  const label = type ? `backend "${type}"` : "backend";
+  const head =
+    `Root module "${root}" runs choudoufu with a declared estate and also declares a ${label} block. ` +
+    "choudoufu ignores it with a warning: no state is read or written there and `init -migrate-state` " +
+    "is refused. An apply publishes the estate's non-sensitive outputs to the location it names, so " +
+    "terraform_remote_state readers keep working.";
+  if (store.source === "record_store") {
+    return `${head} Records go to the record_store the live declaration names, which wins over the backend.`;
+  }
+  if (store.source === "backend") {
+    return (
+      `${head} With no record_store declared, choudoufu derives the record store from this backend's ` +
+      "bucket and prints it on every init and plan (INTENTIUS/choudoufu#2293). Declare record_store to " +
+      "put records somewhere else."
+    );
+  }
+  const why = DERIVABLE_BACKENDS.has(type) && store.note
+    ? `No record store is derived from it: ${store.note}.`
+    : `No record store is derived from a ${type ? `"${type}"` : "backend of unknown type"} (only s3, gcs and azurerm are).`;
+  return (
+    `${head} ${why} No record_store is declared, so records stay in the local ` +
+    "store. Declare record_store if more than one machine runs this root (TF046 guards this in CI)."
+  );
+}
+
+function cloudMessage(root: string): string {
+  return (
+    `Root module "${root}" runs choudoufu with a declared estate and also declares a cloud block. ` +
+    "choudoufu ignores it entirely: no state is read or written there, no outputs are published to it, " +
+    "and no record store is derived from it. Remove it, or use a backend block if " +
+    "terraform_remote_state readers need this estate's outputs."
+  );
+}
 
 export const tf024: PostSynthCheck = {
   id: "TF024",
-  description: "Live root declares a backend or cloud block, which choudoufu refuses",
+  description: "Live root declares a backend or cloud block, which choudoufu ignores",
 
   check(ctx: PostSynthContext): PostSynthDiagnostic[] {
     const diagnostics: PostSynthDiagnostic[] = [];
     const flagged = new Set<string>();
+    let liveBodies: Map<string, BlockBody[]> | undefined;
 
     for (const [name, entity] of ctx.entities) {
       if (entity.entityType !== TERRAFORM_TYPE) continue;
@@ -46,20 +123,26 @@ export const tf024: PostSynthCheck = {
       const root = typeof props.root === "string" ? props.root : "";
       if (flagged.has(root)) continue;
 
-      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
-      const hasBackend = hasBlock(body, "backend");
+      const body = bodyOf(props);
       const hasCloud = hasBlock(body, "cloud");
+      const hasBackend = hasBlock(body, "backend");
       if (!hasBackend && !hasCloud) continue;
-
       flagged.add(root);
-      const blockKind = hasBackend ? "backend" : "cloud";
+
+      // A cloud block does nothing at all, so it is the one worth a warning
+      // when a (malformed) root somehow carries both.
+      if (hasCloud) {
+        diagnostics.push({ checkId: "TF024", severity: "warning", message: cloudMessage(root), entity: name, lexicon: "terraform" });
+        continue;
+      }
+
+      liveBodies ??= liveBodiesByRoot(ctx);
+      const type = backendTypes(body)[0] ?? "";
+      const store = resolveRecordStore([body], liveBodies.get(root) ?? []);
       diagnostics.push({
         checkId: "TF024",
-        severity: "error",
-        message:
-          `Root module "${root}" runs choudoufu with a declared estate and also declares a ` +
-          `${blockKind} block. choudoufu refuses this at init: "Both a ${blockKind} and a live ` +
-          `configuration are present." Remove the ${blockKind} block; a live root keeps no state to store.`,
+        severity: "info",
+        message: backendMessage(root, type, store),
         entity: name,
         lexicon: "terraform",
       });

package/dist/rules/tf046.ts

@@ -0,0 +1,204 @@
+/**
+ * TF046: a live root's record store is local, and the lint runs in CI.
+ *
+ * A live root keeps its records (what binds a record-backed resource to the
+ * estate) in a record store. With nothing to say otherwise that store is a
+ * directory beside the module (choudoufu `live/STORAGE.md`), and on a CI
+ * runner the directory is empty on every run: an ordinary resource still binds
+ * by its marker, but a record-backed one is proposed for create again.
+ *
+ * "Local" is what choudoufu resolves, read here through `./record-store.ts`,
+ * the same resolution TF024 names in its message (INTENTIUS/choudoufu#2293):
+ *
+ * - an explicit `record_store "local"` fires;
+ * - an explicit `record_store` of any other kind is quiet, whatever backend
+ *   sits beside it;
+ * - with no `record_store`, an ignored `backend "s3"`, `"gcs"` or `"azurerm"`
+ *   block that names its bucket as a literal gives a derived store and is
+ *   quiet;
+ * - with no `record_store` and no backend, or a backend with no counterpart
+ *   (`local`, `consul`, `http`), or one whose bucket comes only from
+ *   `-backend-config`, the store is implied local and the rule fires, naming
+ *   the reason choudoufu would print.
+ *
+ * A root that is also a Terragrunt unit with a `remote_state`, a `generate`
+ * block that writes a backend, or an `include` of a parent config gets its
+ * backend file at run time, so what chant reads is not what choudoufu sees.
+ * The rule stays quiet there rather than guess; TF044 still reports a
+ * Terragrunt `backend = "local"`.
+ *
+ * CI is read from the environment chant runs in: `CI` set to anything but
+ * `false` or `0`, or `GITHUB_ACTIONS`, `GITLAB_CI`, `FORGEJO_ACTIONS`,
+ * `GITEA_ACTIONS` or `TF_BUILD` (Azure Pipelines) set to `true`. Outside CI the
+ * local store is a reasonable choice for one person or a demo, and the rule
+ * says nothing.
+ *
+ * Opt-outs, for emulator and test lanes that use the local store on purpose:
+ * `CHANT_ALLOW_LOCAL_RECORD_STORE=1` in the lane's environment, or
+ * `# chant-ignore-block: TF046` above the `terraform` block holding `live`
+ * for one root, or
+ * `lint.rules: { TF046: "off" }` for a whole project.
+ *
+ * The rule is `report-only` in the audit catalog, so it is off under the
+ * `recommended` preset: terragucci switches it on and holds the product
+ * wording (chant#4561 placement).
+ *
+ * One diagnostic per root. It fires from the `terraform` block that holds the
+ * `live` block, since suppression comments anchor on top-level blocks only,
+ * and from the sidecar's `Terraform::Live` entity for a sidecar estate, where
+ * `# chant-ignore-file: TF046` in `estate.chdf.hcl` suppresses it.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable, type ResourceDeclarable } from "@intentius/chant/declarable";
+import {
+  LIVE_TYPE,
+  TERRAFORM_TYPE,
+  TERRAGRUNT_CONFIG_TYPE,
+  TERRAGRUNT_GENERATE_TYPE,
+  TERRAGRUNT_REMOTE_STATE_TYPE,
+  type BlockBody,
+} from "../../hcl/parse";
+import { isRootScoped } from "./scope";
+import { resolveRecordStore, type ResolvedRecordStore } from "./record-store";
+
+/** The environment variable an emulator or test lane sets to keep the local store without a finding. */
+export const ALLOW_LOCAL_RECORD_STORE_ENV = "CHANT_ALLOW_LOCAL_RECORD_STORE";
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+const truthy = (v: string | undefined): boolean => v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false";
+
+/** Whether the environment is a CI job. */
+export function isCiEnvironment(env: Env): boolean {
+  if (truthy(env.CI)) return true;
+  for (const name of ["GITHUB_ACTIONS", "GITLAB_CI", "FORGEJO_ACTIONS", "GITEA_ACTIONS", "TF_BUILD"]) {
+    if (env[name]?.toLowerCase() === "true") return true;
+  }
+  return false;
+}
+
+const bodyOf = (entity: ResourceDeclarable): BlockBody => {
+  const props = entity.props as { body?: unknown };
+  return (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+};
+
+const rootOf = (entity: ResourceDeclarable): string => {
+  const root = (entity.props as { root?: unknown }).root;
+  return typeof root === "string" ? root : "";
+};
+
+interface LiveRoot {
+  /** Entity key the finding anchors on: the live declaration's entity, until a `terraform` block holding it is seen. */
+  anchor: string;
+  liveBodies: BlockBody[];
+  terraformBodies: BlockBody[];
+  /** A Terragrunt unit whose backend file is written at run time. */
+  runtimeBackend: boolean;
+}
+
+/** Whether a Terragrunt block in this root writes a backend file at run time. */
+function writesRuntimeBackend(entity: ResourceDeclarable): boolean {
+  const body = bodyOf(entity);
+  switch (entity.entityType) {
+    case TERRAGRUNT_REMOTE_STATE_TYPE:
+      return body.backend !== "local";
+    case TERRAGRUNT_GENERATE_TYPE: {
+      const contents = typeof body.contents === "string" ? body.contents : "";
+      return /\bbackend\s+"(?!local")/.test(contents);
+    }
+    case TERRAGRUNT_CONFIG_TYPE:
+      return Array.isArray(body.includes) && body.includes.length > 0;
+    default:
+      return false;
+  }
+}
+
+function liveRoots(ctx: PostSynthContext): Map<string, LiveRoot> {
+  const roots = new Map<string, LiveRoot>();
+  const terraform = new Map<string, BlockBody[]>();
+  /** Per root, the key of the first `terraform` block that holds a `live` block. */
+  const holder = new Map<string, string>();
+  const runtime = new Set<string>();
+
+  for (const [key, entity] of ctx.entities) {
+    if (!isResourceDeclarable(entity) || !isRootScoped(entity)) continue;
+    const root = rootOf(entity);
+    if (entity.entityType === TERRAFORM_TYPE) {
+      const list = terraform.get(root) ?? [];
+      const body = bodyOf(entity);
+      list.push(body);
+      terraform.set(root, list);
+      if (body.live !== undefined && !holder.has(root)) holder.set(root, key);
+      continue;
+    }
+    if (entity.entityType === LIVE_TYPE) {
+      if ((entity.props as { mode?: unknown }).mode !== "live") continue;
+      const found = roots.get(root);
+      if (found) found.liveBodies.push(bodyOf(entity));
+      else roots.set(root, { anchor: key, liveBodies: [bodyOf(entity)], terraformBodies: [], runtimeBackend: false });
+      continue;
+    }
+    if (writesRuntimeBackend(entity)) runtime.add(root);
+  }
+
+  for (const [root, live] of roots) {
+    live.terraformBodies = terraform.get(root) ?? [];
+    live.anchor = holder.get(root) ?? live.anchor;
+    live.runtimeBackend = runtime.has(root);
+  }
+  return roots;
+}
+
+function message(root: string, store: ResolvedRecordStore): string {
+  const why =
+    store.source === "record_store"
+      ? 'Its live declaration names record_store "local", a directory beside the module.'
+      : store.note
+        ? `It declares no record_store, and no store is derived from its backend: ${store.note}.`
+        : store.backend
+          ? `It declares no record_store, and its backend "${store.backend}" block keeps state on local disk, so choudoufu uses the local store.`
+          : "It declares no record_store and has no backend block to derive one from, so choudoufu uses the local store.";
+  return (
+    `Live root "${root}" keeps its records in the local store, and this is a CI run. ${why} ` +
+    "A CI runner starts with an empty directory every run, so each record-backed resource is proposed " +
+    "for create again. Keep or add a backend \"s3\", \"gcs\" or \"azurerm\" block with a literal bucket " +
+    "(choudoufu derives the store from it), or declare a record_store in the live block or " +
+    `estate.chdf.hcl. A lane that uses the local store on purpose sets ${ALLOW_LOCAL_RECORD_STORE_ENV}=1.`
+  );
+}
+
+/**
+ * TF046 against an explicit environment. `tf046.check` passes `process.env`;
+ * tests pass their own.
+ */
+export function checkLocalRecordStore(ctx: PostSynthContext, env: Env): PostSynthDiagnostic[] {
+  if (!isCiEnvironment(env) || truthy(env[ALLOW_LOCAL_RECORD_STORE_ENV])) return [];
+  const diagnostics: PostSynthDiagnostic[] = [];
+  for (const [root, live] of liveRoots(ctx)) {
+    if (live.runtimeBackend) continue;
+    const store = resolveRecordStore(live.terraformBodies, live.liveBodies);
+    if (store.kind !== "local") continue;
+    diagnostics.push({
+      checkId: "TF046",
+      severity: "error",
+      message: message(root, store),
+      entity: live.anchor,
+      lexicon: "terraform",
+    });
+  }
+  return diagnostics;
+}
+
+export const tf046: PostSynthCheck = {
+  id: "TF046",
+  description: "Live root resolves to the local record store in a CI run",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkLocalRecordStore(ctx, process.env);
+  },
+};