@intentius/chant-lexicon-terraform 0.124.54 → 0.124.55

package/src/lint/post-synth/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);
+  },
+};

package/src/lint/post-synth/tf047.test.ts

@@ -0,0 +1,56 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, test } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { parseTerraformRootDir } from "../../hcl/parse";
+import { terraformPlugin } from "../../plugin";
+import { tf047 } from "./tf047";
+
+const fixtures = join(dirname(fileURLToPath(import.meta.url)), "fixtures", "TF047");
+
+async function ctxFor(fixture: string, binary: "choudoufu" | "terraform" = "choudoufu"): Promise<PostSynthContext> {
+  const entities = await parseTerraformRootDir(join(fixtures, fixture), "estate", undefined, { binary });
+  return { outputs: new Map(), entities } as unknown as PostSynthContext;
+}
+
+describe("TF047: live root pins a module version the catalog has no row for, or one with refusals", () => {
+  test("warns on a version whose static rows are refused, with IDs, links and the tier", async () => {
+    const diags = tf047.check(await ctxFor("refused"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0]).toMatchObject({ checkId: "TF047", severity: "warning", entity: "estate/module.eks" });
+    expect(diags[0].message).toContain("terraform-aws-modules/eks/aws 21.29.0");
+    expect(diags[0].message).toContain("6 of 6 examples");
+    expect(diags[0].message).toContain("static tier");
+    expect(diags[0].message).toContain("https://github.com/INTENTIUS/choudoufu/blob/main/live/LIMITATIONS.md#");
+    expect(diags[0].message).not.toMatch(/gauntlet/i);
+  });
+
+  test("is quiet when every example at the version is clear", async () => {
+    expect(tf047.check(await ctxFor("clear"))).toEqual([]);
+  });
+
+  test("reports a version with no row at info, naming the measured versions", async () => {
+    const diags = tf047.check(await ctxFor("unknown-version"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("info");
+    expect(diags[0].message).toContain("no row at this version");
+    expect(diags[0].message).toContain("6.6.1");
+  });
+
+  test("reports a module with no row at info", async () => {
+    const diags = tf047.check(await ctxFor("unknown-module"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("info");
+    expect(diags[0].message).toContain("no row for this module");
+  });
+
+  test("skips a stock root: the table measures choudoufu", async () => {
+    expect(tf047.check(await ctxFor("refused", "terraform"))).toEqual([]);
+  });
+
+  test("is off by default: in the all preset, not in recommended", () => {
+    const presets = terraformPlugin.lintPresets!();
+    expect(presets.all).toContain("TF047");
+    expect(presets.recommended).not.toContain("TF047");
+  });
+});

package/src/lint/post-synth/tf047.ts

@@ -0,0 +1,114 @@
+/**
+ * TF047: a live root pins a registry module version the known-module catalog
+ * has no row for, or one whose row carries refusals.
+ *
+ * The catalog is choudoufu's module compatibility table, vendored in
+ * `../../module-catalog/` (chant#4560, choudoufu#2292). It has one static
+ * row per terraform-aws-modules example at one tag, measured offline in the
+ * onboarded form. A module call on a root whose binary is choudoufu (the
+ * root's `mode` is `live`) with an exact `version` is looked up there:
+ *
+ * - no row for the module, or none at the pinned version: `info`, naming the
+ *   versions the static tier did measure;
+ * - at least one example at that version refused: `warning`, with each
+ *   refusal ID, its site count, the examples that carry it and its
+ *   `live/LIMITATIONS.md` link;
+ * - every example clear: quiet.
+ *
+ * Every message names the tier. The catalog holds the static tier only, and
+ * no figure here counts a gauntlet run (choudoufu#2292 ruling: two tiers,
+ * never mixed).
+ *
+ * A stock root (`mode: "state"`) is skipped: the table measures choudoufu.
+ * A range is TF039's finding and a missing `version` TF004's, so both are
+ * skipped here. A `//subdir` source is looked up by its module repository.
+ *
+ * Off by default: `report-only` in the audit catalog, as TF039 is.
+ * terragucci turns it on and holds the product wording (terragucci#1286).
+ *
+ * Scope: root and child modules of a live root alike.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { MODULE_TYPE, type BlockBody } from "../../hcl/parse";
+import { classifyModuleSource, isExactVersionConstraint } from "./module-source";
+import {
+  MODULE_CATALOG_SOURCE,
+  MODULE_COMPATIBILITY_PAGE,
+  moduleCompatibility,
+  type ModuleCompatibility,
+} from "../../module-catalog";
+
+const tierNote = (): string =>
+  `static tier of choudoufu's module table, measured ${MODULE_CATALOG_SOURCE.date} with hashicorp/aws ${MODULE_CATALOG_SOURCE.awsProvider}`;
+
+/** The TF047 message for one module call, or undefined when the call is clear. */
+export function catalogMessage(address: string, c: ModuleCompatibility): string | undefined {
+  const pin = `${c.module} ${c.version}`;
+  switch (c.status) {
+    case "clear":
+      return undefined;
+    case "unknown-module":
+      return (
+        `Module "${address}" pins ${pin}, and the ${tierNote()} has no row for this module. ` +
+        `Run \`choudoufu live-check\` on the root to see whether it plans. The table: ${MODULE_COMPATIBILITY_PAGE}`
+      );
+    case "unknown-version":
+      return (
+        `Module "${address}" pins ${pin}, and the ${tierNote()} has no row at this version. ` +
+        `It measured ${c.measuredVersions.join(", ")}. ` +
+        `Run \`choudoufu live-check\` on the root, or pin a measured version. The table: ${MODULE_COMPATIBILITY_PAGE}`
+      );
+    case "refused": {
+      const ids = c.refusals
+        .map((r) => `${r.id} (${r.sites} site${r.sites === 1 ? "" : "s"} in ${r.examples.join(", ")}; ${r.docsUrl})`)
+        .join("; ");
+      return (
+        `Module "${address}" pins ${pin}. In the ${tierNote()}, ${c.refusedExamples} of ${c.examples} ` +
+        `examples at this version are refused: ${ids}. ` +
+        "A call that uses the same features is refused the same way; `choudoufu live-check` names each site in this root."
+      );
+    }
+  }
+}
+
+export const tf047: PostSynthCheck = {
+  id: "TF047",
+  description: "Live root pins a module version the known-module catalog has no row for, or one with refusals",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [key, entity] of ctx.entities) {
+      if (entity.entityType !== MODULE_TYPE || !isResourceDeclarable(entity)) continue;
+      const props = entity.props as { address?: unknown; body?: unknown; mode?: unknown };
+      if (props.mode !== "live") continue;
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+      const source = typeof body.source === "string" ? body.source : undefined;
+      if (source === undefined || classifyModuleSource(source).kind !== "registry") continue;
+      const version = body.version;
+      if (typeof version !== "string" || !isExactVersionConstraint(version)) continue;
+
+      const compat = moduleCompatibility(source, version);
+      if (compat === undefined) continue;
+      const address = typeof props.address === "string" ? props.address : key;
+      const message = catalogMessage(address, compat);
+      if (message === undefined) continue;
+
+      diagnostics.push({
+        checkId: "TF047",
+        severity: compat.status === "refused" ? "warning" : "info",
+        message,
+        entity: key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/src/lock-rows.test.ts

@@ -0,0 +1,70 @@
+/**
+ * #4552: a choudoufu root's rows keep terragucci's format (`planRows` in
+ * terragucci's apply-rows.ts), and Terraform, tofu and Terragrunt keep the
+ * target grain and refuse the resource grain by name.
+ */
+import { describe, expect, test } from "vitest";
+import type { ChangeSetPart } from "@intentius/chant/change-set";
+import { terraformDefaultLockGrain, terraformLockGrainRefusal, terraformLockRows, terraformLockRowsFromPart } from "./lock-rows";
+
+const plan = {
+  resource_changes: [
+    { address: "aws_s3_bucket.logs", mode: "managed", change: { actions: ["update"], before: { id: "logs-1" } } },
+    { address: "aws_sqs_queue.jobs", mode: "managed", change: { actions: ["create"], before: null } },
+    { address: "aws_iam_role.app", previous_address: "aws_iam_role.old", mode: "managed", change: { actions: ["no-op"], before: { id: "app" } } },
+    { address: "aws_iam_role.svc", previous_address: "aws_iam_role.legacy", mode: "managed", change: { actions: ["delete", "create"], before: { id: "svc" } } },
+    { address: "data.aws_caller_identity.me", mode: "data", change: { actions: ["read"] } },
+  ],
+};
+
+describe("terraformLockRows", () => {
+  test("estate rows, the previous address of a moved instance, and object rows for anything but a create", () => {
+    expect(terraformLockRows("net", "e01", plan).map((r) => r.key)).toEqual([
+      "estate e01 aws_iam_role.legacy",
+      "estate e01 aws_iam_role.svc",
+      "estate e01 aws_s3_bucket.logs",
+      "estate e01 aws_sqs_queue.jobs",
+      "object logs-1",
+      "object svc",
+    ]);
+  });
+
+  test("a root with no estate is keyed by its path", () => {
+    expect(terraformLockRows("live/net", undefined, plan).map((r) => r.key)).toEqual([
+      "object logs-1",
+      "object svc",
+      "root live/net aws_iam_role.legacy",
+      "root live/net aws_iam_role.svc",
+      "root live/net aws_s3_bucket.logs",
+      "root live/net aws_sqs_queue.jobs",
+    ]);
+  });
+
+  test("from a change-set part: the same keys less the previous address", () => {
+    const part: ChangeSetPart = {
+      member: { member: "net", lexicon: "terraform", planner: "choudoufu", scope: "e01", status: "planned", planDigest: "sha256:x", holes: [] },
+      entries: [
+        { member: "net", lexicon: "terraform", planner: "choudoufu", address: "aws_s3_bucket.logs", type: "aws_s3_bucket", id: "logs-1", action: "update", attributes: [] },
+        { member: "net", lexicon: "terraform", planner: "choudoufu", address: "aws_sqs_queue.jobs", type: "aws_sqs_queue", action: "no-op", attributes: [] },
+      ],
+    };
+    expect(terraformLockRowsFromPart("net", part).map((r) => r.key)).toEqual(["estate e01 aws_s3_bucket.logs", "object logs-1"]);
+  });
+});
+
+describe("the grain", () => {
+  test("resource under choudoufu, the root under Terraform and tofu", () => {
+    expect(terraformDefaultLockGrain("choudoufu")).toBe("resource");
+    expect(terraformDefaultLockGrain("terraform")).toBe("target");
+    expect(terraformDefaultLockGrain("tofu")).toBe("target");
+  });
+
+  test("resource is refused by engine name off choudoufu; target and repo are not", () => {
+    expect(terraformLockGrainRefusal("resource", "choudoufu")).toBeUndefined();
+    expect(terraformLockGrainRefusal("resource", "terraform")).toMatch(/^Terraform keeps/);
+    expect(terraformLockGrainRefusal("resource", "tofu")).toMatch(/^tofu keeps/);
+    expect(terraformLockGrainRefusal("resource", "terraform", "/usr/local/bin/terragrunt")).toMatch(/^Terragrunt keeps/);
+    expect(terraformLockGrainRefusal("target", "terraform")).toBeUndefined();
+    expect(terraformLockGrainRefusal("repo", "tofu")).toBeUndefined();
+  });
+});

package/src/lock-rows.ts

@@ -0,0 +1,82 @@
+/**
+ * The terraform lexicon's lock grain (#4552) and the rows a choudoufu apply
+ * holds on the resource grain, in terragucci's format (`planRows` in
+ * terragucci's `apply-rows.ts` at 18f6431), unchanged:
+ *
+ * - `estate <estate> <address>` for every resource instance the apply acts
+ *   on (a create, update, delete, replace or forget), or `root <root>
+ *   <address>` when the root has no estate;
+ * - the same for `previous_address` on a moved instance;
+ * - `object <id>` for anything but a create, from the object's id before,
+ *   so two estates that meet on one object meet on its row.
+ *
+ * Data reads and no-ops hold nothing.
+ *
+ * The grain: `resource` for choudoufu, which keeps one record per resource,
+ * writes each conditionally and refuses a plan one of whose changes moved;
+ * `target` (the root, or the Terragrunt unit) for Terraform, tofu and
+ * Terragrunt, whose state is one file the backend's lock keeps whole. Those
+ * three refuse `resource` by name, since nothing in their state is per
+ * resource.
+ */
+import type { ChangeSetPart, ChangeSetPlanner } from "@intentius/chant/change-set";
+import { objectRowKey, sortedLockRows, type LockGrain, type LockRow } from "@intentius/chant/lifecycle/lock-rows";
+
+const CHANGING = new Set(["create", "update", "delete", "forget"]);
+
+/** The scope a root's rows are keyed in: its estate, else its path. */
+function rowScope(root: string, estate: string | undefined): string {
+  return estate ? `estate ${estate}` : `root ${root}`;
+}
+
+/** The rows a plan's changes key, from `show -json`'s `resource_changes` (terragucci's `planRows`). */
+export function terraformLockRows(root: string, estate: string | undefined, plan: unknown): LockRow[] {
+  const scope = rowScope(root, estate);
+  const rows: LockRow[] = [];
+  const changes = (plan as { resource_changes?: unknown[] } | undefined)?.resource_changes ?? [];
+  for (const c of changes as Array<Record<string, any>>) {
+    if (c?.mode === "data" || typeof c?.address !== "string") continue;
+    const actions: string[] = Array.isArray(c.change?.actions) ? c.change.actions : [];
+    if (!actions.some((a) => CHANGING.has(a))) continue;
+    const address = c.address as string;
+    rows.push({ key: `${scope} ${address}`, target: root, address });
+    if (typeof c.previous_address === "string" && c.previous_address !== address) rows.push({ key: `${scope} ${c.previous_address}`, target: root, address });
+    // The live object an update or a delete acts on: two estates that meet on one object meet here.
+    const id = c.change?.before?.id;
+    if (actions.some((a) => a !== "create") && (typeof id === "string" || typeof id === "number") && String(id) !== "") rows.push({ key: objectRowKey(String(id)), target: root, address });
+  }
+  return sortedLockRows(rows);
+}
+
+/**
+ * The rows from a member's change-set part, when the plan document is not
+ * at hand: the same keys, less the previous address of a moved instance,
+ * which the part does not carry. The part's `scope` is the estate.
+ */
+export function terraformLockRowsFromPart(root: string, part: ChangeSetPart): LockRow[] {
+  const scope = rowScope(root, part.member.planner === "choudoufu" ? part.member.scope : undefined);
+  const rows: LockRow[] = [];
+  for (const e of part.entries) {
+    if (e.action === "no-op" || e.action === "read") continue;
+    rows.push({ key: `${scope} ${e.address}`, target: root, address: e.address });
+    if (e.action !== "create" && e.id) rows.push({ key: objectRowKey(e.id), target: root, address: e.address });
+  }
+  return sortedLockRows(rows);
+}
+
+/** Whether a binary's name is Terragrunt's. */
+function isTerragrunt(binary: string | undefined): boolean {
+  return /^terragrunt(\.exe)?$/.test((binary ?? "").split(/[\\/]/).pop() ?? "");
+}
+
+/** The grain a root takes by default: `resource` under choudoufu, `target` under every other binary. */
+export function terraformDefaultLockGrain(planner: ChangeSetPlanner | undefined): LockGrain {
+  return planner === "choudoufu" ? "resource" : "target";
+}
+
+/** Why a root cannot take `grain`, by engine name, or undefined when it can. */
+export function terraformLockGrainRefusal(grain: LockGrain, planner: ChangeSetPlanner | undefined, binary?: string): string | undefined {
+  if (grain !== "resource" || planner === "choudoufu") return undefined;
+  const engine = isTerragrunt(binary) ? "Terragrunt" : planner === "tofu" ? "tofu" : "Terraform";
+  return `${engine} keeps a root's state in one file that its backend's lock keeps whole, so nothing in it is per resource; the resource grain needs choudoufu (ci.lockGrain: target)`;
+}

package/src/lock-timeout.ts

@@ -0,0 +1,34 @@
+/**
+ * State-lock waits for a plan or an apply (#4545): how long `plan` and
+ * `apply` wait for another run's state lock before failing. Taken from
+ * terragucci's waves, where two jobs of one pipeline can reach the same
+ * backend a moment apart and a failed lock fails the wave for nothing.
+ *
+ * A job that already sets `-lock-timeout` through `TF_CLI_ARGS` or
+ * `TF_CLI_ARGS_<command>` keeps its own: the flag is added only when neither
+ * names one. Terragrunt waves pass the same flag after `--`
+ * (`./terragrunt/wave.ts`, `extra`).
+ */
+
+/** How long a plan or an apply waits for a state lock unless the job set a `-lock-timeout` of its own. */
+export const DEFAULT_LOCK_TIMEOUT = "5m";
+
+/** A duration terraform's `-lock-timeout` takes: `0s`, `30s`, `5m`, `1h30m`. */
+const DURATION = /^(\d+(ms|s|m|h))+$/;
+
+/** Whether `value` is a `-lock-timeout` duration. */
+export function isLockTimeout(value: unknown): value is string {
+  return typeof value === "string" && DURATION.test(value);
+}
+
+/**
+ * The `-lock-timeout` flag a `command` takes: `-lock-timeout=<timeout>`, or
+ * nothing when `TF_CLI_ARGS` or `TF_CLI_ARGS_<command>` in `env` already
+ * names one, or `timeout` is `false`. Throws on a duration terraform refuses.
+ */
+export function lockTimeoutArgs(command: "plan" | "apply", timeout: string | false = DEFAULT_LOCK_TIMEOUT, env: Record<string, string | undefined> = process.env): string[] {
+  if (timeout === false) return [];
+  if (!isLockTimeout(timeout)) throw new Error(`lockTimeout "${timeout}" is not a duration terraform takes, such as "5m" or "30s"`);
+  const set = `${env.TF_CLI_ARGS ?? ""} ${env[`TF_CLI_ARGS_${command}`] ?? ""}`;
+  return /(^|\s)-{1,2}lock-timeout[=\s]/.test(set) ? [] : [`-lock-timeout=${timeout}`];
+}

package/src/module-catalog/index.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from "vitest";
+import {
+  MODULE_CATALOG_SOURCE,
+  exactModuleVersion,
+  moduleCompatibility,
+  registryModuleAddress,
+  staticRows,
+} from "./index";
+import { renderStaticTier } from "./refresh-cli";
+import { parseModuleCompat } from "./types";
+import { SOURCE_COMMIT, STATIC_MEASUREMENT } from "./static-tier";
+
+describe("known-module catalog (chant#4560)", () => {
+  test("vendors the static tier only, with its source commit", () => {
+    expect(MODULE_CATALOG_SOURCE.path).toBe("live/module-compat.json");
+    expect(MODULE_CATALOG_SOURCE.commit).toMatch(/^[0-9a-f]{40}$/);
+    expect(staticRows.length).toBeGreaterThan(0);
+    expect(staticRows.every((r) => r.tier === "static")).toBe(true);
+  });
+
+  test("every vendored row passes the refresh check", () => {
+    expect(() =>
+      parseModuleCompat({ schema: 1, static_measurement: STATIC_MEASUREMENT, static: [...staticRows] }),
+    ).not.toThrow();
+  });
+
+  test("the vendored file is what the refresh script writes", () => {
+    const rendered = renderStaticTier(SOURCE_COMMIT, STATIC_MEASUREMENT, staticRows);
+    expect(rendered).toContain(`at commit\n// ${SOURCE_COMMIT}`);
+    expect(rendered).toContain("static tier only");
+  });
+
+  test("refuses a row whose verdict disagrees with its refusals", () => {
+    const row = { ...staticRows[0], verdict: "refused" as const, refusals: [] };
+    expect(() => parseModuleCompat({ schema: 1, static_measurement: STATIC_MEASUREMENT, static: [row] })).toThrow(
+      /refused with 0 refusals/,
+    );
+  });
+
+  test.each([
+    ["terraform-aws-modules/vpc/aws", "terraform-aws-modules/vpc/aws"],
+    ["registry.terraform.io/terraform-aws-modules/vpc/aws", "terraform-aws-modules/vpc/aws"],
+    ["terraform-aws-modules/iam/aws//modules/iam-role", "terraform-aws-modules/iam/aws"],
+    ["./modules/vpc", undefined],
+    ["git::https://example.com/vpc.git?ref=v1", undefined],
+  ])("registryModuleAddress(%s)", (source, want) => {
+    expect(registryModuleAddress(source)).toBe(want);
+  });
+
+  test.each([
+    ["1.4.0", "1.4.0"],
+    ["= 1.4.0", "1.4.0"],
+    ["v1.4.0", "1.4.0"],
+    ["~> 1.4", undefined],
+  ])("exactModuleVersion(%s)", (version, want) => {
+    expect(exactModuleVersion(version)).toBe(want);
+  });
+
+  test("a clear version", () => {
+    expect(moduleCompatibility("terraform-aws-modules/sqs/aws", "5.2.2")).toMatchObject({
+      tier: "static",
+      status: "clear",
+      examples: 1,
+      clearExamples: 1,
+      refusedExamples: 0,
+      refusals: [],
+    });
+  });
+
+  test("a refused version sums sites per refusal ID and lists its examples", () => {
+    const c = moduleCompatibility("terraform-aws-modules/eks/aws", "= 21.29.0")!;
+    expect(c.status).toBe("refused");
+    expect(c.refusedExamples).toBe(c.examples);
+    expect(c.refusals.length).toBeGreaterThan(0);
+    for (const r of c.refusals) {
+      expect(r.sites).toBeGreaterThan(0);
+      expect(r.examples.length).toBeGreaterThan(0);
+      expect(r.docsUrl).toMatch(/LIMITATIONS\.md#/);
+    }
+  });
+
+  test("unknown module and unknown version", () => {
+    expect(moduleCompatibility("cloudposse/label/null", "0.25.0")?.status).toBe("unknown-module");
+    const v = moduleCompatibility("terraform-aws-modules/vpc/aws", "5.0.0")!;
+    expect(v.status).toBe("unknown-version");
+    expect(v.measuredVersions).toContain("6.6.1");
+  });
+
+  test("a range or a non-registry source has no answer", () => {
+    expect(moduleCompatibility("terraform-aws-modules/vpc/aws", "~> 6.0")).toBeUndefined();
+    expect(moduleCompatibility("./modules/vpc", "1.0.0")).toBeUndefined();
+  });
+});