@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/drift-rows.ts

@@ -0,0 +1,137 @@
+/**
+ * Drift rows (#4580): one row per object a plan found drifted, by address,
+ * with its action and the object's real name, counted the way a product's
+ * drift report counts. `./drift-record.ts` answers a different question (the
+ * status of each instance the plan names), so it skips create rows, carries
+ * no names and stays as it is.
+ *
+ * A stock root's refresh-only plan reports drift as `resource_drift`, and
+ * every entry there is one row, data blocks and creates included. A full
+ * plan of a root under live resource markers (`live: true`) reads drift from
+ * `resource_changes` instead, seen from the other side: a create there is an
+ * object that no longer exists (delete), a delete one that exists outside
+ * the code (create), a replacement or any other pair of actions an update.
+ * Data blocks, no-op and read entries are not drift.
+ *
+ * These are terragucci's rules (packages/terragucci/src/report/drift.ts:
+ * `liveDrift`, `driftCount`, `driftNames`), so a row count here equals the
+ * count its report gives for the same plan.
+ *
+ * A row carries no attribute values. Its `name` is the first non-empty
+ * string among `name`, `id`, `bucket`, `function_name` and `arn`, read from
+ * the object as found and then as the code has it; a deleted object has no
+ * other place its name survives.
+ *
+ * The module imports nothing, so a product can load it behind a
+ * feature-detect without pulling the lexicon's entry point.
+ */
+
+type Json = Record<string, unknown>;
+
+const isObject = (v: unknown): v is Json => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** One drifted object. */
+export interface TerraformDriftRow {
+  /** The resource address, `""` when the plan's entry has none. */
+  address: string;
+  /**
+   * What happened outside the code: `update`, `delete` (the object is gone),
+   * `create` (an object exists that state or code does not hold), or on a
+   * stock root whatever single action the plan's entry names. On a stock
+   * root a delete-and-create pair is `replace`, and any other pair `update`.
+   */
+  action: string;
+  /** The resource type, when the entry names one. */
+  type?: string;
+  /** The object's real name, by the rule in this module's header. */
+  name?: string;
+}
+
+export interface TerraformPlanDriftRowsOptions {
+  /**
+   * The plan is a full plan of a root under live resource markers, whose
+   * changes are its drift. Default false: a refresh-only plan's
+   * `resource_drift`.
+   */
+  live?: boolean;
+}
+
+const FLIP: Record<string, string> = { create: "delete", delete: "create" };
+const NAME_KEYS = ["name", "id", "bucket", "function_name", "arn"] as const;
+
+function nameOf(values: readonly unknown[]): string | undefined {
+  const objects = values.filter(isObject);
+  for (const key of NAME_KEYS) {
+    const v = objects.map((x) => x[key]).find((x) => typeof x === "string" && x !== "");
+    if (typeof v === "string") return v;
+  }
+  return undefined;
+}
+
+function rowOf(entry: unknown, action: string, values: readonly unknown[]): TerraformDriftRow {
+  const r = isObject(entry) ? entry : {};
+  const name = nameOf(values);
+  return {
+    address: typeof r.address === "string" ? r.address : "",
+    action,
+    ...(typeof r.type === "string" && r.type !== "" ? { type: r.type } : {}),
+    ...(name !== undefined ? { name } : {}),
+  };
+}
+
+function stockAction(actions: readonly string[]): string {
+  if (actions.length === 1) return actions[0]!;
+  if (actions.length === 2 && actions.includes("delete") && actions.includes("create")) return "replace";
+  return "update";
+}
+
+/** A refresh-only plan's `resource_drift`, one row per entry. */
+function stockRows(doc: Json): TerraformDriftRow[] {
+  const list = Array.isArray(doc.resource_drift) ? doc.resource_drift : [];
+  return list.map((entry) => {
+    const ch = isObject(entry) && isObject(entry.change) ? entry.change : {};
+    const actions = Array.isArray(ch.actions) ? ch.actions.map(String) : [];
+    return rowOf(entry, stockAction(actions), [ch.after, ch.before]);
+  });
+}
+
+/** A live root's full plan, its changes read as drift. */
+function liveRows(doc: Json): TerraformDriftRow[] {
+  const list = Array.isArray(doc.resource_changes) ? doc.resource_changes : [];
+  const out: TerraformDriftRow[] = [];
+  for (const entry of list) {
+    if (!isObject(entry) || entry.mode === "data") continue;
+    const ch = isObject(entry.change) ? entry.change : {};
+    const actions = Array.isArray(ch.actions) ? ch.actions.map(String) : [];
+    if (actions.length === 0 || actions.every((a) => a === "no-op" || a === "read")) continue;
+    const action = actions.length === 1 ? (FLIP[actions[0]!] ?? actions[0]!) : "update";
+    const live = isObject(ch.before) ? ch.before : null;
+    let code = isObject(ch.after) ? ch.after : null;
+    // A value the plan knows only after the apply is not a difference: the live one stands for it.
+    const unknown = isObject(ch.after_unknown) ? ch.after_unknown : {};
+    if (code && live) code = { ...code, ...Object.fromEntries(Object.keys(unknown).filter((k) => unknown[k] === true && k in live).map((k) => [k, live[k]])) };
+    out.push(rowOf(entry, action, [live, code]));
+  }
+  return out;
+}
+
+/**
+ * The drift a plan (`show -json`, parsed) found, one row per drifted object
+ * in the plan's order. Its length is the drift count.
+ */
+export function terraformPlanDriftRows(plan: unknown, options: TerraformPlanDriftRowsOptions = {}): TerraformDriftRow[] {
+  if (!isObject(plan)) return [];
+  return options.live ? liveRows(plan) : stockRows(plan);
+}
+
+/** How many objects a plan found drifted: `terraformPlanDriftRows(plan, options).length`. */
+export function terraformPlanDriftCount(plan: unknown, options: TerraformPlanDriftRowsOptions = {}): number {
+  return terraformPlanDriftRows(plan, options).length;
+}
+
+/** Each drifted object's real name by address, for the rows that have one. */
+export function terraformPlanDriftNames(plan: unknown, options: TerraformPlanDriftRowsOptions = {}): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const row of terraformPlanDriftRows(plan, options)) if (row.name !== undefined) out.set(row.address, row.name);
+  return out;
+}

package/src/exit-codes.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "vitest";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+import { terraformExitOf, terraformPlanMoved } from "./exit-codes";
+
+describe("terraform, tofu and choudoufu exit statuses on chant's table (#4553)", () => {
+  test("choudoufu's refusals of a moved plan are chant's moved code", () => {
+    expect(terraformExitOf({ command: "live-wave-apply", code: 3 })).toBe(CHANT_EXIT.moved);
+    expect(terraformExitOf({ command: "apply", code: 3, refusal: "approval-mismatch" })).toBe(CHANT_EXIT.moved);
+    expect(terraformPlanMoved({ command: "live-wave-apply", code: 3 })).toBe(true);
+  });
+
+  test("a plan made against another estate is a failure, and so is a root that failed", () => {
+    expect(terraformExitOf({ command: "apply", code: 3, refusal: "wrong-estate" })).toBe(CHANT_EXIT.failed);
+    expect(terraformExitOf({ command: "live-wave-apply", code: 4 })).toBe(CHANT_EXIT.failed);
+    expect(terraformExitOf({ command: "live-plan-set", code: 4 })).toBe(CHANT_EXIT.failed);
+  });
+
+  test("a plan's 2 is drift only under a drift check", () => {
+    expect(terraformExitOf({ command: "plan", code: 2 })).toBe(CHANT_EXIT.done);
+    expect(terraformExitOf({ command: "plan", code: 2, drift: true })).toBe(CHANT_EXIT.drift);
+    expect(terraformExitOf({ command: "plan", code: 1 })).toBe(CHANT_EXIT.failed);
+  });
+});

package/src/exit-codes.ts

@@ -0,0 +1,59 @@
+/**
+ * OpenTofu, Terraform and choudoufu outcomes mapped onto chant's exit-code
+ * table (#4553, `CHANT_EXIT` in `@intentius/chant/exit-codes`).
+ *
+ * The lexicon never picks the process's exit code itself: for a moved plan it
+ * throws an error core marks as moved (`planMoved: true`, read by
+ * `isPlanMovedError`), and core exits `CHANT_EXIT.moved`. This mapping says
+ * which engine outcome is which row of the table, so the throw sites and the
+ * reference page agree.
+ *
+ * | Engine outcome | Table |
+ * |---|---|
+ * | `plan -detailed-exitcode` 0 or 2 | not an exit: the plan's answer. 2 under a drift check is `drift` |
+ * | any 1 | `failed` |
+ * | choudoufu `apply <planfile>` 3, approval mismatch | `moved` |
+ * | choudoufu `apply <planfile>` 3, plan made against another estate | `failed`: the pipeline handed the wrong file, and no approval fixes that |
+ * | choudoufu `live-wave-apply` 3, set moved | `moved` |
+ * | choudoufu `live-wave-apply` 4 or `live-plan-set` 4, a root failed | `failed` |
+ * | a composed plan that moved | `moved` |
+ * | `live-affected` 2, `live-cone` 2 | planner answers, never a job's exit |
+ */
+import { CHANT_EXIT, type ChantExitCode } from "@intentius/chant/exit-codes";
+import { CHOUDOUFU_APPROVAL_EXIT_CODE, CHOUDOUFU_WAVE_EXIT, type TerraformApprovalRefusal } from "./op/activities/terraform";
+
+/** The command whose exit status is mapped. */
+export type TerraformExitSource =
+  /** `terraform|tofu|choudoufu plan -detailed-exitcode`; `drift` says a drift check asked for it. */
+  | { command: "plan"; code: number; drift?: boolean }
+  /** `choudoufu apply <planfile>` on a live root; `refusal` is `classifyApprovalRefusal`'s answer for its output. */
+  | { command: "apply"; code: number; refusal?: TerraformApprovalRefusal }
+  /** `choudoufu live-wave-apply`. */
+  | { command: "live-wave-apply"; code: number }
+  /** `choudoufu live-plan-set`. */
+  | { command: "live-plan-set"; code: number };
+
+/**
+ * The table's code for a terraform, tofu or choudoufu exit status. A plan's
+ * 0 and 2 are both `done` unless a drift check asked, when 2 is `drift`.
+ */
+export function terraformExitOf(source: TerraformExitSource): ChantExitCode {
+  const { code } = source;
+  if (code === 0) return CHANT_EXIT.done;
+  switch (source.command) {
+    case "plan":
+      if (code === 2) return source.drift ? CHANT_EXIT.drift : CHANT_EXIT.done;
+      return CHANT_EXIT.failed;
+    case "apply":
+      return code === CHOUDOUFU_APPROVAL_EXIT_CODE && source.refusal === "approval-mismatch" ? CHANT_EXIT.moved : CHANT_EXIT.failed;
+    case "live-wave-apply":
+      return code === CHOUDOUFU_WAVE_EXIT.setMoved ? CHANT_EXIT.moved : CHANT_EXIT.failed;
+    case "live-plan-set":
+      return code === 2 ? CHANT_EXIT.done : CHANT_EXIT.failed;
+  }
+}
+
+/** Whether `source` is a plan that moved since its approval: the outcomes the lexicon throws a `planMoved` error for. */
+export function terraformPlanMoved(source: TerraformExitSource): boolean {
+  return terraformExitOf(source) === CHANT_EXIT.moved;
+}

package/src/hcl/config-blocks.test.ts

@@ -0,0 +1,174 @@
+/**
+ * `moved`, `import`, `removed` and `check` blocks as entities (chant #4458).
+ *
+ * The fixture is `src/__fixtures__/config-blocks/app/`: one root holding two
+ * `moved` blocks, an `import`, a `removed` and a `check` with a scoped `data`
+ * block, rendered through `renderTerraformRoots` and core's `buildGraphIr`,
+ * the pair `chant graph --format ir` runs.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+import { buildGraphIr, type GraphIR, type IREdge } from "@intentius/chant/graph-ir";
+import type { Declarable } from "@intentius/chant/declarable";
+import { renderTerraformRoots } from "./roots";
+import {
+  CHECK_TYPE,
+  IMPORT_TYPE,
+  MOVED_TYPE,
+  REMOVED_TYPE,
+  blocksToEntities,
+  type TerraformEntity,
+} from "./parse";
+
+const TREE = join(dirname(fileURLToPath(import.meta.url)), "..", "__fixtures__", "config-blocks");
+
+let entities: Map<string, Declarable>;
+let warnings: string[];
+let ir: GraphIR;
+
+beforeAll(async () => {
+  const rendered = await renderTerraformRoots({ projectRoot: TREE, roots: { app: { dir: "./app" } } });
+  entities = rendered.entities;
+  warnings = rendered.warnings;
+  ir = buildGraphIr(entities);
+});
+
+function entity(key: string): TerraformEntity {
+  const e = entities.get(key);
+  expect(e, key).toBeDefined();
+  return e as TerraformEntity;
+}
+
+function edgesFrom(from: string): Array<[string, string]> {
+  return ir.edges
+    .filter((e: IREdge) => e.from === from)
+    .map((e: IREdge) => [e.to, e.viaAttr ?? ""] as [string, string])
+    .sort();
+}
+
+describe("moved blocks", () => {
+  it("become Terraform::Moved entities", () => {
+    expect(entity("app/moved").entityType).toBe(MOVED_TYPE);
+    expect(entity("app/moved").props.address).toBe("moved");
+  });
+
+  it("get distinct keys when a root holds two", () => {
+    expect(entity("app/moved~2").entityType).toBe(MOVED_TYPE);
+    expect([...entities.keys()].filter((k) => entities.get(k)!.entityType === MOVED_TYPE).sort()).toEqual([
+      "app/moved",
+      "app/moved~2",
+    ]);
+    expect(entity("app/moved").props.line).not.toBe(entity("app/moved~2").props.line);
+  });
+
+  it("have an edge to `to`, and to `from` when `from` is still declared", () => {
+    // `aws_instance.old` and `module.legacy` are not declared, so only `to` draws.
+    expect(edgesFrom("app/moved")).toEqual([["app/aws_instance.web", "to"]]);
+    expect(edgesFrom("app/moved~2")).toEqual([["app/module.network", "to"]]);
+  });
+
+  it("draws the `from` edge when the address it names is declared", async () => {
+    const parsed = await blocksToEntities(
+      [
+        {
+          name: "main.tf",
+          source: [
+            'resource "aws_instance" "a" {}',
+            'resource "aws_instance" "b" {}',
+            "moved {",
+            "  from = aws_instance.a",
+            "  to   = aws_instance.b",
+            "}",
+          ].join("\n"),
+        },
+      ],
+      "app",
+    );
+    const { resolveEntityReferences } = await import("./edges");
+    await resolveEntityReferences(parsed);
+    const moved = parsed.get("app/moved") as TerraformEntity;
+    expect(moved.references).toEqual([
+      { to: "app/aws_instance.a", viaAttr: "from" },
+      { to: "app/aws_instance.b", viaAttr: "to" },
+    ]);
+  });
+});
+
+describe("import blocks", () => {
+  it("become a Terraform::Import entity with an edge to `to`", () => {
+    expect(entity("app/import").entityType).toBe(IMPORT_TYPE);
+    expect(edgesFrom("app/import")).toEqual([["app/aws_lb.front", "to"]]);
+  });
+});
+
+describe("removed blocks", () => {
+  it("become a Terraform::Removed entity", () => {
+    expect(entity("app/removed").entityType).toBe(REMOVED_TYPE);
+    expect(entity("app/removed").props.body["from"]).toBe("${aws_instance.gone}");
+  });
+
+  it("draw a `from` edge only when the address is still declared", async () => {
+    expect(edgesFrom("app/removed")).toEqual([]);
+    const parsed = await blocksToEntities(
+      [{ name: "main.tf", source: 'resource "aws_instance" "a" {}\nremoved {\n  from = aws_instance.a\n}\n' }],
+      "app",
+    );
+    const { resolveEntityReferences } = await import("./edges");
+    await resolveEntityReferences(parsed);
+    expect((parsed.get("app/removed") as TerraformEntity).references).toEqual([
+      { to: "app/aws_instance.a", viaAttr: "from" },
+    ]);
+  });
+});
+
+describe("check blocks", () => {
+  it("become a Terraform::Check entity keyed by its name", () => {
+    expect(entity("app/check.health").entityType).toBe(CHECK_TYPE);
+    expect(entity("app/check.health").props.address).toBe("check.health");
+  });
+
+  it("have an edge per reference, including the scoped data block's", () => {
+    expect(edgesFrom("app/check.health")).toEqual([
+      ["app/aws_lb.front", "data"],
+      ["app/var.region", "assert"],
+    ]);
+  });
+
+  it("read the scoped data block, never the root-level one of the same address", () => {
+    expect(ir.edges.some((e) => e.from === "app/check.health" && e.to === "app/data.http.site")).toBe(false);
+  });
+});
+
+describe("a `from` naming an undeclared address", () => {
+  it("does not fail the build", () => {
+    expect(warnings).toEqual([]);
+  });
+
+  it("raises no dangling reference", () => {
+    expect(ir.dangling ?? []).toEqual([]);
+    for (const e of ir.edges) expect(entities.has(e.to)).toBe(true);
+  });
+});
+
+describe("the same blocks in Terraform's JSON syntax (chant#4457)", () => {
+  /** Each config block's entity as the acceptance compares it: type, address and body, by key. */
+  const configBlocks = (all: Map<string, Declarable>): Record<string, { type: string; address: string; body: unknown }> =>
+    Object.fromEntries(
+      [...all]
+        .filter(([, e]) => [MOVED_TYPE, IMPORT_TYPE, REMOVED_TYPE, CHECK_TYPE].includes(e.entityType))
+        .map(([key, e]) => {
+          const p = (e as TerraformEntity).props;
+          return [key, { type: e.entityType, address: p.address, body: p.body }];
+        }),
+    );
+
+  it("main.tf.json's moved, import, removed and check blocks are the entities main.tf's are", async () => {
+    const json = (await renderTerraformRoots({ projectRoot: TREE, roots: { app: { dir: "./app-json" } } })).entities;
+    const fromJson = configBlocks(json);
+    expect(Object.keys(fromJson).sort()).toEqual(["app/check.health", "app/import", "app/moved", "app/moved~2", "app/removed"]);
+    expect(fromJson).toEqual(configBlocks(entities));
+    for (const key of Object.keys(fromJson)) expect((json.get(key) as TerraformEntity).props.file).toBe("main.tf.json");
+  });
+});

package/src/hcl/edges.ts

@@ -88,7 +88,7 @@ import { isResourceDeclarable, type Declarable } from "@intentius/chant/declarab
 import type { EntityReference } from "@intentius/chant/graph-ir";
 import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/hcl2json";
 import { refFromAccessor } from "@intentius/chant/terraform/graph";
-import { LOCALS_TYPE, scopeOfKey, type BlockBody, type TerraformEntity } from "./parse";
+import { CHECK_TYPE, LOCALS_TYPE, scopeOfKey, type BlockBody, type TerraformEntity } from "./parse";
 
 /** An identifier as Terraform's grammar allows it. Same as `./references.ts`. */
 const NAME = "[A-Za-z_][A-Za-z0-9_-]*";
@@ -244,8 +244,12 @@ export function referencesOfEntity(
   const index = scopes.get(scopeOfKey(key));
   if (!index) return [];
 
+  const shadowed = entity.entityType === CHECK_TYPE ? scopedDataAddresses(bodyOf(entity)) : undefined;
   const grouped = new Map<string, { to: string; viaAttr: string; attrs: Set<string> }>();
   for (const raw of rawReferences(bodyOf(entity), accessors)) {
+    // An assertion reading the check's own scoped `data` block reads that
+    // block, never a root-level data source of the same address (#4458).
+    if (shadowed?.has(raw.address)) continue;
     const to = resolveAddress(raw.address, index);
     if (!to || to === key) continue;
     const groupKey = `${to}${raw.via}`;
@@ -270,6 +274,22 @@ export function referencesOfEntity(
   return out.sort((a, b) => cmp(a.to, b.to) || cmp(a.viaAttr ?? "", b.viaAttr ?? ""));
 }
 
+/**
+ * The `data.<type>.<name>` addresses a `check` block declares in its own
+ * scope (#4458). hcl2json gives them as `data: { <type>: { <name>: [...] } }`
+ * inside the check's body.
+ */
+function scopedDataAddresses(body: BlockBody): Set<string> {
+  const out = new Set<string>();
+  const data = body["data"];
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return out;
+  for (const [type, named] of Object.entries(data as Record<string, unknown>)) {
+    if (typeof named !== "object" || named === null || Array.isArray(named)) continue;
+    for (const name of Object.keys(named as Record<string, unknown>)) out.add(`data.${type}.${name}`);
+  }
+  return out;
+}
+
 /** Code-point ordering, so output does not depend on the machine's locale. */
 function cmp(a: string, b: string): number {
   return a < b ? -1 : a > b ? 1 : 0;

package/src/hcl/files.ts

@@ -0,0 +1,234 @@
+/**
+ * Which files of a directory are a root's configuration, and how a JSON-syntax
+ * one reads (chant#4457). Every lister in the lexicon asks here, so the parser,
+ * change detection, the backend readers, the report and the rollout pin all
+ * see the same file set for one root.
+ *
+ * The set follows the root's binary. Terraform reads `.tf` and `.tf.json`.
+ * OpenTofu (and choudoufu, which is OpenTofu) also reads `.tofu` and
+ * `.tofu.json`, and when `x.tofu` and `x.tf` both exist it reads `x.tofu`
+ * only (likewise `x.tofu.json` over `x.tf.json`). A binary that is not given
+ * is `terraform`, the config's default.
+ *
+ * `parse.ts` re-exports all of this; the module is separate so the readers
+ * that never parse HCL (`state/backend.ts`, `changed-roots.ts`) do not load
+ * the parser's dependencies.
+ */
+
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** The configuration file suffixes Terraform reads. */
+export const TERRAFORM_SUFFIXES: readonly string[] = [".tf", ".tf.json"];
+/** The ones OpenTofu reads as well. */
+export const TOFU_SUFFIXES: readonly string[] = [".tofu", ".tofu.json"];
+
+/** Whether a root run by `binary` reads `.tofu` files: `tofu` and `choudoufu` do (by name or path), `terraform` and an unset binary do not. */
+export function readsTofuFiles(binary?: string): boolean {
+  const base = (binary ?? "terraform").split(/[\\/]/).pop() ?? "";
+  return base.startsWith("tofu") || base.startsWith("choudoufu");
+}
+
+/** Whether `name` is a configuration file in Terraform's JSON syntax (`.tf.json`, `.tofu.json`). */
+export function isJsonConfigFile(name: string): boolean {
+  return name.endsWith(".tf.json") || name.endsWith(".tofu.json");
+}
+
+/** Whether `name` is a `.tofu` or `.tofu.json` file. */
+export function isTofuConfigFile(name: string): boolean {
+  return TOFU_SUFFIXES.some((s) => name.endsWith(s));
+}
+
+/** Whether `name` is a configuration file a root run by `binary` reads, before the `.tofu`-over-`.tf` rule. */
+export function isConfigFileFor(name: string, binary?: string): boolean {
+  if (TERRAFORM_SUFFIXES.some((s) => name.endsWith(s))) return true;
+  return readsTofuFiles(binary) && isTofuConfigFile(name);
+}
+
+/**
+ * The configuration files among `names` a root run by `binary` reads, in
+ * filename order. For a tofu or choudoufu root, `x.tf` is dropped when
+ * `x.tofu` is present and `x.tf.json` when `x.tofu.json` is, which is
+ * OpenTofu's own rule. Names may carry a directory; the rule compares names
+ * in the same directory.
+ */
+export function selectConfigFiles(names: Iterable<string>, binary?: string): string[] {
+  const kept = [...names].filter((n) => isConfigFileFor(n, binary));
+  const present = new Set(kept);
+  return kept
+    .filter((n) => {
+      if (n.endsWith(".tf")) return !present.has(`${n.slice(0, -".tf".length)}.tofu`);
+      if (n.endsWith(".tf.json")) return !present.has(`${n.slice(0, -".tf.json".length)}.tofu.json`);
+      return true;
+    })
+    .sort();
+}
+
+/**
+ * The configuration files directly under `dir` a root run by `binary` reads,
+ * by name, in filename order. Non-recursive, matching Terraform's module
+ * scoping; directories named like a file are left out. Throws when `dir`
+ * cannot be read.
+ */
+export function listConfigFiles(dir: string, binary?: string): string[] {
+  const files = readdirSync(dir).filter((n) => {
+    if (!isConfigFileFor(n, binary)) return false;
+    try {
+      return statSync(join(dir, n)).isFile();
+    } catch {
+      return false;
+    }
+  });
+  return selectConfigFiles(files, binary);
+}
+
+/** {@link listConfigFiles}, empty when `dir` cannot be read. */
+export function listConfigFilesSafe(dir: string, binary?: string): string[] {
+  try {
+    return listConfigFiles(dir, binary);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The nested blocks a JSON-syntax body can carry that hcl2json would give as
+ * arrays, by block type: each entry is the nested block's label count and its
+ * own nested blocks. Anything not named here is an attribute and is kept as
+ * written, since JSON syntax cannot tell a nested block from an object
+ * attribute without the provider's schema.
+ */
+interface BlockShape {
+  labels: number;
+  nested?: Record<string, BlockShape>;
+  /**
+   * Attributes JSON syntax writes as a bare expression in a string (a type,
+   * a reference), where HCL writes the expression itself and hcl2json gives
+   * it as `"${...}"`. Their strings are wrapped the same way.
+   */
+  exprs?: readonly string[];
+}
+
+const LIFECYCLE: BlockShape = { labels: 0, exprs: ["ignore_changes", "replace_triggered_by"] };
+const RESOURCE_NESTED: Record<string, BlockShape> = {
+  lifecycle: LIFECYCLE,
+  provisioner: { labels: 1, nested: { connection: { labels: 0 } } },
+  connection: { labels: 0 },
+};
+const REFERS = ["provider", "depends_on"];
+
+const TOP_LEVEL: Record<string, BlockShape> = {
+  terraform: {
+    labels: 0,
+    nested: {
+      backend: { labels: 1 },
+      cloud: { labels: 0, nested: { workspaces: { labels: 0 } } },
+      required_providers: { labels: 0 },
+      provider_meta: { labels: 1 },
+      live: { labels: 0 },
+    },
+  },
+  locals: { labels: 0 },
+  provider: { labels: 1 },
+  module: { labels: 1, exprs: ["depends_on", "providers"] },
+  variable: { labels: 1, nested: { validation: { labels: 0 } }, exprs: ["type"] },
+  output: { labels: 1, nested: { precondition: { labels: 0 } }, exprs: ["depends_on"] },
+  resource: { labels: 2, nested: RESOURCE_NESTED, exprs: REFERS },
+  data: { labels: 2, nested: { lifecycle: LIFECYCLE }, exprs: REFERS },
+  moved: { labels: 0, exprs: ["from", "to"] },
+  import: { labels: 0, exprs: ["to", "provider"] },
+  removed: { labels: 0, nested: { lifecycle: LIFECYCLE, provisioner: RESOURCE_NESTED.provisioner! }, exprs: ["from"] },
+  check: { labels: 1, nested: { data: { labels: 2 }, assert: { labels: 0 } } },
+};
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** A bare expression string as hcl2json writes the expression: `aws.west` becomes `${aws.west}`; a template is kept. */
+function asExpression(v: unknown): unknown {
+  if (typeof v === "string") return v.includes("${") ? v : `\${${v}}`;
+  if (Array.isArray(v)) return v.map(asExpression);
+  if (isObject(v)) return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, asExpression(x)]));
+  return v;
+}
+
+/** A JSON body with its `"//"` comment keys dropped (Terraform ignores them), its known nested blocks wrapped and its expression attributes written as hcl2json writes them. */
+function normaliseBody(body: unknown, shape: BlockShape): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!isObject(body)) return out;
+  for (const [k, v] of Object.entries(body)) {
+    if (k === "//") continue;
+    const inner = shape.nested?.[k];
+    out[k] = inner ? wrapBlock(v, inner) : shape.exprs?.includes(k) ? asExpression(v) : v;
+  }
+  return out;
+}
+
+/**
+ * A block in JSON syntax as hcl2json gives the same block in HCL: one object
+ * level per label, then an array of bodies. JSON syntax writes a single body
+ * as an object or several as an array, and allows an array of objects at a
+ * label level to be merged, so both are read.
+ */
+function wrapBlock(value: unknown, shape: BlockShape, labels = shape.labels): unknown {
+  if (labels === 0) return (Array.isArray(value) ? value : [value]).filter(isObject).map((b) => normaliseBody(b, shape));
+  const out: Record<string, unknown> = {};
+  for (const part of Array.isArray(value) ? value : [value]) {
+    if (!isObject(part)) continue;
+    for (const [label, inner] of Object.entries(part)) {
+      if (label === "//") continue;
+      const wrapped = wrapBlock(inner, shape, labels - 1);
+      const had = out[label];
+      if (Array.isArray(had) && Array.isArray(wrapped)) out[label] = [...had, ...wrapped];
+      else if (isObject(had) && isObject(wrapped)) out[label] = mergeLabelled(had, wrapped);
+      else out[label] = wrapped;
+    }
+  }
+  return out;
+}
+
+function mergeLabelled(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    const had = out[k];
+    if (Array.isArray(had) && Array.isArray(v)) out[k] = [...had, ...v];
+    else if (isObject(had) && isObject(v)) out[k] = mergeLabelled(had, v);
+    else out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * A `.tf.json` or `.tofu.json` document in the tree shape hcl2json gives an
+ * HCL file, so `blocksToEntities` reads both the same way. Top-level keys it
+ * does not know are kept as written. Throws on malformed JSON, as hcl2json
+ * throws on malformed HCL.
+ */
+export function jsonConfigTree(source: string): Record<string, unknown> {
+  const doc: unknown = JSON.parse(source);
+  if (!isObject(doc)) throw new Error("a JSON configuration file must hold an object");
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(doc)) {
+    if (k === "//") continue;
+    const shape = TOP_LEVEL[k];
+    out[k] = shape ? wrapBlock(v, shape) : v;
+  }
+  return out;
+}
+
+/**
+ * The bodies of the `live` blocks nested in the `terraform` blocks of a
+ * `.tf.json` or `.tofu.json` document, in the order written (chant#4504).
+ * The fast live readers (`report.ts`'s `estateOfDir`, `op/activities/live-detect.ts`)
+ * read HCL by text and a JSON file through this. Malformed JSON reads as no
+ * `live` block, as those readers treat any file they cannot read.
+ */
+export function jsonLiveBlocks(source: string): Record<string, unknown>[] {
+  let tree: Record<string, unknown>;
+  try {
+    tree = jsonConfigTree(source);
+  } catch {
+    return [];
+  }
+  const terraform = Array.isArray(tree.terraform) ? tree.terraform : [];
+  return terraform.flatMap((t) => (isObject(t) && Array.isArray(t.live) ? t.live.filter(isObject) : []));
+}