@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

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

@@ -0,0 +1,137 @@
+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 { applyInlineSuppressions } from "@intentius/chant/lint/suppressions";
+import { ALLOW_LOCAL_RECORD_STORE_ENV, checkLocalRecordStore, isCiEnvironment } from "./tf046";
+import { tf024 } from "./tf024";
+import { blocksToEntities, parseTerraformRootDir } from "../../hcl/parse";
+
+const fixtures = join(dirname(fileURLToPath(import.meta.url)), "fixtures", "TF046");
+
+const CI = { CI: "true" };
+
+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("TF046: live root resolves to the local record store in CI", () => {
+  test("fires on a live root with no record_store and no backend", async () => {
+    const diags = checkLocalRecordStore(await ctxFor("implied-local"), CI);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("TF046");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].entity).toBe("estate/terraform");
+    expect(diags[0].message).toContain("no backend block to derive one from");
+    expect(diags[0].message).toContain("declare a record_store");
+    expect(diags[0].message).toContain('backend "s3"');
+  });
+
+  test("stays quiet when an ignored s3 backend with a literal bucket gives a derived store", async () => {
+    // The backend sits in its own backend.tf, as most roots keep it.
+    expect(checkLocalRecordStore(await ctxFor("derived-s3"), CI)).toHaveLength(0);
+  });
+
+  test("agrees with TF024 on the derived store", async () => {
+    const ctx = await ctxFor("derived-s3");
+    const diags = tf024.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("derives the record store");
+  });
+
+  test("fires when the backend's bucket comes only from -backend-config, and says so", async () => {
+    const ctx = await ctxFor("backend-config-only");
+    const diags = checkLocalRecordStore(ctx, CI);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('backend "s3" sets no literal bucket');
+    // TF024 gives the same reason instead of claiming a derived store.
+    const tf024Diags = tf024.check(ctx);
+    expect(tf024Diags[0].message).toContain("sets no literal bucket");
+    expect(tf024Diags[0].message).not.toContain("derives the record store");
+  });
+
+  test("fires on an azurerm backend that leaves out resource_group_name", async () => {
+    const diags = checkLocalRecordStore(await ctxFor("azurerm-no-resource-group"), CI);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("resource_group_name");
+  });
+
+  test('fires on an explicit record_store "local", even beside a derivable backend', async () => {
+    const diags = checkLocalRecordStore(await ctxFor("explicit-local"), CI);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('record_store "local"');
+  });
+
+  test("stays quiet on an explicit bucket record_store beside a local backend", async () => {
+    expect(checkLocalRecordStore(await ctxFor("explicit-s3-beside-local-backend"), CI)).toHaveLength(0);
+  });
+
+  test("keys on an estate.chdf.hcl sidecar as well as a live block", async () => {
+    const diags = checkLocalRecordStore(await ctxFor("sidecar-implied"), CI);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toMatch(/^estate\/live/);
+  });
+
+  test("a sidecar estate opts out with chant-ignore-file in estate.chdf.hcl", async () => {
+    const entities = await blocksToEntities(
+      [{ name: "main.tf", source: "terraform {}\n" }],
+      "app",
+      undefined,
+      { binary: "choudoufu" },
+      { name: "estate.chdf.hcl", source: '# chant-ignore-file: TF046\nestate = "e"\n' },
+    );
+    const ctx = { outputs: new Map(), entities } as unknown as PostSynthContext;
+    const diags = checkLocalRecordStore(ctx, CI);
+    expect(diags).toHaveLength(1);
+    expect(applyInlineSuppressions(diags, ctx.entities).diagnostics).toHaveLength(0);
+  });
+
+  test("says nothing outside CI", async () => {
+    expect(checkLocalRecordStore(await ctxFor("implied-local"), {})).toHaveLength(0);
+    expect(checkLocalRecordStore(await ctxFor("implied-local"), { CI: "false" })).toHaveLength(0);
+  });
+
+  test("an emulator or test lane opts out through the environment", async () => {
+    const env = { ...CI, [ALLOW_LOCAL_RECORD_STORE_ENV]: "1" };
+    expect(checkLocalRecordStore(await ctxFor("explicit-local"), env)).toHaveLength(0);
+    expect(checkLocalRecordStore(await ctxFor("implied-local"), env)).toHaveLength(0);
+  });
+
+  test("one root opts out with chant-ignore-block above the terraform block holding live", async () => {
+    const source =
+      '# chant-ignore-block: TF046\nterraform {\n  live {\n    estate = "e"\n    record_store "local" {}\n  }\n}\n';
+    const entities = await blocksToEntities([{ name: "main.tf", source }], "app", undefined, { binary: "choudoufu" });
+    const ctx = { outputs: new Map(), entities } as unknown as PostSynthContext;
+    const diags = checkLocalRecordStore(ctx, CI);
+    expect(diags).toHaveLength(1);
+    expect(applyInlineSuppressions(diags, ctx.entities).diagnostics).toHaveLength(0);
+  });
+
+  test("stays quiet on a Terragrunt unit whose remote_state writes the backend at run time", async () => {
+    const files = [
+      { name: "main.tf", source: 'terraform {\n  live {\n    estate = "e"\n  }\n}\n' },
+      {
+        name: "terragrunt.hcl",
+        source: 'remote_state {\n  backend = "s3"\n  generate = {\n    path = "backend.tf"\n    if_exists = "overwrite"\n  }\n  config = {\n    bucket = "tfstate"\n  }\n}\n',
+      },
+    ];
+    const entities = await blocksToEntities(files, "unit", undefined, { binary: "choudoufu" });
+    const ctx = { outputs: new Map(), entities } as unknown as PostSynthContext;
+    expect(checkLocalRecordStore(ctx, CI)).toHaveLength(0);
+  });
+
+  test("does not fire on a stock root", async () => {
+    expect(checkLocalRecordStore(await ctxFor("implied-local", "terraform"), CI)).toHaveLength(0);
+  });
+
+  test("reads CI from the variables each forge sets", () => {
+    expect(isCiEnvironment({ CI: "1" })).toBe(true);
+    expect(isCiEnvironment({ GITHUB_ACTIONS: "true" })).toBe(true);
+    expect(isCiEnvironment({ GITLAB_CI: "true" })).toBe(true);
+    expect(isCiEnvironment({ FORGEJO_ACTIONS: "true" })).toBe(true);
+    expect(isCiEnvironment({ TF_BUILD: "True" })).toBe(true);
+    expect(isCiEnvironment({ CI: "0" })).toBe(false);
+    expect(isCiEnvironment({})).toBe(false);
+  });
+});

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/live-plan-reasons.ts

@@ -0,0 +1,54 @@
+/**
+ * choudoufu's live-plan omission codes, in chant's vocabulary.
+ *
+ * Its own module so the observation reader (`./describe-resources.ts`) and
+ * the drift adapters (`./drift-record.ts`) read one table, and the drift
+ * adapters bundle without the reader's process and file-system imports.
+ */
+
+import type { UnobservedReason } from "@intentius/chant/observation";
+
+/**
+ * choudoufu's omission reason codes, mapped onto chant's total vocabulary
+ * (`internal/live/projection/result.go`). `"absent"` is not an
+ * {@link UnobservedReason}: it is the tri-state's OBSERVED-ABSENT, the one
+ * omission that is a claim of knowledge rather than of ignorance.
+ *
+ * A code this table does not know maps to `read-failed`, which is the safe
+ * direction: no NOT-OBSERVED verdict ever becomes a create or a delete.
+ */
+export const LIVE_PLAN_OMISSION_REASONS: Readonly<Record<string, UnobservedReason | "absent">> = {
+  // The provider was asked and reported, normally, that nothing is there.
+  ABSENT: "absent",
+  // The provider errored, or could not be reached in a usable order.
+  FAILED: "read-failed",
+  PARENT_UNAVAILABLE: "read-failed",
+  CYCLE: "read-failed",
+  INCOMPLETE_BLOCK: "read-failed",
+  LISTED_NOT_IMPORTABLE: "read-failed",
+  // Something exists at the identity and does not carry this estate's marker.
+  // Normally answered by the `unowned[]` section before this table is read;
+  // this entry is what happens if a document ever carries the omission alone.
+  UNOWNED: "read-failed",
+  // The mode cannot name, list or tag this instance at all: a server-assigned
+  // identity with no marker to find it by, a resource with no cloud object to
+  // read, or an address another declared instance has taken over.
+  NEEDS_DISCOVERY: "unsupported-kind",
+  UNREADABLE: "unsupported-kind",
+  SUPERSEDED: "unsupported-kind",
+  // The run's own tag index saw an object at the identity and the import
+  // read could not confirm it (choudoufu #1043). The read failed; the
+  // object is not proposed for creation.
+  VERIFIED_NOT_IMPORTABLE: "read-failed",
+  // -target or -exclude left the block out of the plan graph (choudoufu
+  // #1176): nothing was read because the caller asked for it not to be.
+  OUT_OF_SCOPE: "filtered",
+};
+
+/** Does this text name a credentials or authorization failure rather than any other error? */
+export function readsAsCredentials(text: string): boolean {
+  return /\b(no valid credential|credentials?|not authorized|unauthorized|accessdenied|access denied|expiredtoken|invalidclienttokenid|signature)\b/i.test(
+    text,
+  );
+}
+

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