@intentius/chant-lexicon-terraform 0.57.0 → 0.59.0

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

@@ -0,0 +1,72 @@
+/**
+ * TF014: a `provider` block inside a child module that configures anything.
+ *
+ * Scope: child modules only. A `provider` block in the ROOT module is where
+ * providers are supposed to be configured, and TF008 is what checks its
+ * contents.
+ *
+ * A child module that configures its own provider takes the decision away
+ * from its caller: the caller can no longer point the module at a different
+ * region, account or endpoint, and two calls of the module in one root cannot
+ * differ. Worse, Terraform cannot remove a module whose provider is declared
+ * inside it, because destroying the resources needs a provider configuration
+ * that the removal itself deletes. That is the "Provider configuration not
+ * present" failure that leaves a root unable to plan.
+ *
+ * The one legal form is a provider block that declares only `alias`, which
+ * names a slot the caller fills through `providers = { aws.replica =
+ * aws.west }`. That is a declaration, not a configuration, so a block whose
+ * body has nothing but `alias` is not reported. Everything else is: a
+ * `region`, a `profile`, an `assume_role` block, and `version` too, which has
+ * been deprecated in favour of `required_providers` since Terraform 0.13.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { PROVIDER_TYPE, type BlockBody, type TerraformEntity } from "../../hcl/parse";
+import { isChildScoped } from "./scope";
+
+/** Everything in a provider body that is not the `alias` slot declaration. */
+function configuredKeys(body: BlockBody): string[] {
+  return Object.keys(body).filter((key) => key !== "alias");
+}
+
+export const tf014: PostSynthCheck = {
+  id: "TF014",
+  description: "Child module configures a provider block",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [key, entity] of ctx.entities) {
+      if (entity.entityType !== PROVIDER_TYPE || !isResourceDeclarable(entity)) continue;
+      if (!isChildScoped(entity)) continue;
+
+      const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+      const configured = configuredKeys(body);
+      if (configured.length === 0) continue;
+
+      const address = typeof props.address === "string" ? props.address : key;
+      diagnostics.push({
+        checkId: "TF014",
+        severity: "warning",
+        message:
+          `Child module block "${address}" configures a provider (${configured.sort().join(", ")}). ` +
+          "A module that configures its own provider cannot be pointed at another region or account by " +
+          "its caller, cannot be called twice with different settings, and cannot be removed, since " +
+          "destroying its resources needs the provider configuration the removal deletes. Configure the " +
+          "provider in the root module and pass it in with `providers = { ... }`, leaving at most an " +
+          "`alias`-only block here.",
+        entity: key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,72 @@
+/**
+ * TF015: a `backend` or `cloud` block inside a child module.
+ *
+ * Scope: child modules only. This is TF001's mirror image. TF001 wants a root
+ * module to declare a REMOTE backend, because a root without one keeps its
+ * state on local disk. A child module must declare neither: state belongs to
+ * the root,
+ * one state per root however many modules it calls, and Terraform says so
+ * directly, "A backend block can only appear in the root module" and the
+ * same for `cloud`. Depending on the version, the block is ignored with a
+ * warning or the root refuses to initialize, and either way the block is a
+ * claim about where state lives that the module does not get to make.
+ *
+ * The usual cause is a directory that used to be a root module and became a
+ * child when someone factored it out, with its `terraform` block carried
+ * along. The rest of that block is fine to keep: `required_version` and
+ * `required_providers` are meaningful in a child module and are not reported
+ * here.
+ *
+ * Label-blind on purpose (#2218). TF001 had to start reading the backend
+ * block's type label, since `local` is the state placement it warns about
+ * rather than a cure for it. Nothing of the sort applies here: what a child
+ * module may not do is name a backend at all, `local` included, and
+ * Terraform's own refusal ("A backend block can only appear in the root
+ * module") does not read the label either. `hasBlock` is the right test, and
+ * the `positive` fixture's child declares `backend "local"` for that reason.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { TERRAFORM_TYPE, type BlockBody, type TerraformEntity } from "../../hcl/parse";
+import { hasBlock } from "./tf001";
+import { isChildScoped } from "./scope";
+
+export const tf015: PostSynthCheck = {
+  id: "TF015",
+  description: "Child module declares a backend or cloud block",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [key, entity] of ctx.entities) {
+      if (entity.entityType !== TERRAFORM_TYPE || !isResourceDeclarable(entity)) continue;
+      if (!isChildScoped(entity)) continue;
+
+      const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+      const backend = hasBlock(body, "backend");
+      const cloud = hasBlock(body, "cloud");
+      if (!backend && !cloud) continue;
+
+      const blockKind = backend ? "backend" : "cloud";
+      diagnostics.push({
+        checkId: "TF015",
+        severity: "warning",
+        message:
+          `A child module's terraform block declares a ${blockKind} block. Only a root module may: ` +
+          "state belongs to the root, one state file for every module it calls, so this block is either " +
+          `ignored with a warning or refused at init. Delete the ${blockKind} block and leave the state ` +
+          "configuration to the root module that calls this one.",
+        entity: key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,75 @@
+/**
+ * TF016: an attribute whose whole value is one quoted interpolation,
+ * `x = "${var.y}"`, the pre-0.12 style Terraform deprecated in 2019.
+ *
+ * The quotes buy nothing and cost readability: the expression is already an
+ * expression, and wrapping it in a template makes every value in the file look
+ * like a string whether it is one or not, which hides the actual type of an
+ * argument that takes a list or a bool.
+ *
+ * This is the one rule in the family that reads the block's SOURCE rather than
+ * its parsed body, and it has to. `@cdktf/hcl2json` renders both `x = var.y`
+ * and `x = "${var.y}"` as the string `"${var.y}"`, so a check over the parse
+ * cannot tell the deprecated form from the idiomatic one and would report every
+ * reference in the root. The quotes only survive in the text, so the text is
+ * what is scanned, one pass per file, through the same
+ * `interpolationOnlyLine` the deterministic fix uses, so the finding and the
+ * patch can never disagree.
+ *
+ * Out of reach, and deliberately not guessed at: tflint also reports the
+ * deprecated interpolation inside an object KEY (`"${var.k}" = "value"`).
+ * That is a different line shape and its fix is not a simple unquote, so this
+ * rule leaves it alone rather than emit a diff it cannot justify.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { interpolationOnlyLine } from "@intentius/chant/audit/proof";
+import type { TerraformEntity } from "../../hcl/parse";
+
+export const tf016: PostSynthCheck = {
+  id: "TF016",
+  description: "Attribute value is a quoted interpolation of a single expression",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    /** `<root>/<file>` to that file's source, so a file is scanned once however many blocks it holds. */
+    const sources = new Map<string, string>();
+
+    for (const entity of ctx.entities.values()) {
+      if (entity.lexicon !== "terraform") continue;
+      if (!isResourceDeclarable(entity)) continue;
+      const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+      if (typeof props.source !== "string" || props.source === "") continue;
+      sources.set(`${props.root ?? ""}/${props.file ?? ""}`, props.source);
+    }
+
+    for (const [key, source] of sources) {
+      const lines = source.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const parsed = interpolationOnlyLine(lines[i]);
+        if (!parsed) continue;
+        diagnostics.push({
+          checkId: "TF016",
+          severity: "info",
+          message:
+            `${key}:${i + 1}: \`${parsed.name}\` wraps a single expression in a template ` +
+            `("\${${parsed.expr}}"). Terraform deprecated that spelling in 0.12. Write ` +
+            `\`${parsed.name} = ${parsed.expr}\` instead, so the argument keeps its own type.`,
+          entity: `${key}:${i + 1}`,
+          lexicon: "terraform",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,50 @@
+/**
+ * TF017: a `module` block carries `depends_on`.
+ *
+ * `depends_on` on a module applies to every resource inside it, including the
+ * ones that had no reason to wait, so the whole module serializes behind the
+ * named dependency and a plan that could have run in parallel does not. It
+ * also makes the dependency invisible from inside the module, where the
+ * resource that actually needed the ordering lives.
+ *
+ * Passing an attribute of the dependency into a module input creates the same
+ * edge implicitly, only narrower and self-documenting.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { MODULE_TYPE } from "../../hcl/parse";
+import { blocksOfType } from "./blocks";
+
+export const tf017: PostSynthCheck = {
+  id: "TF017",
+  description: "Module block uses depends_on",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const block of blocksOfType(ctx, MODULE_TYPE)) {
+      if (!("depends_on" in block.body)) continue;
+
+      diagnostics.push({
+        checkId: "TF017",
+        severity: "info",
+        message:
+          `"${block.address}" uses \`depends_on\`, which orders every resource in the module behind ` +
+          "the dependency, not just the one that needs it. Pass an attribute of the dependency into " +
+          "a module input instead, so Terraform derives the edge itself.",
+        entity: block.key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,72 @@
+/**
+ * TF018: an `output` returns a whole resource or data source.
+ *
+ * `value = aws_instance.web` exports every attribute the provider schema
+ * happens to have, which is a much larger promise than the module meant to
+ * make. Consumers reach into whatever they find, the module can no longer
+ * change any of it, and a provider upgrade that adds or renames an attribute
+ * moves the module's public interface without anyone editing it. Sensitive
+ * attributes ride along too.
+ *
+ * A bare `module.x` reference is not reported: a module's outputs are already
+ * a curated surface, which is the property this rule is asking for.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { OUTPUT_TYPE } from "../../hcl/parse";
+import { blockName, blocksOfType } from "./blocks";
+
+/** Reference prefixes that are not a managed resource type. */
+const NOT_A_RESOURCE = new Set(["var", "local", "module", "each", "count", "self", "path", "terraform"]);
+
+/**
+ * Is this value a reference to a whole resource (`type.name`) or a whole data
+ * source (`data.type.name`), with no attribute selected? Anything with a third
+ * segment, an index, or a function call around it has already narrowed the
+ * value down, which is the fix.
+ */
+function wholeBlockReference(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const m = /^\$\{([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)+)\}$/.exec(value);
+  if (!m) return undefined;
+  const parts = m[1].split(".");
+  if (parts[0] === "data") return parts.length === 3 ? m[1] : undefined;
+  if (NOT_A_RESOURCE.has(parts[0])) return undefined;
+  return parts.length === 2 ? m[1] : undefined;
+}
+
+export const tf018: PostSynthCheck = {
+  id: "TF018",
+  description: "Output value is a whole resource or data source",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const block of blocksOfType(ctx, OUTPUT_TYPE)) {
+      const reference = wholeBlockReference(block.body.value);
+      if (!reference) continue;
+
+      diagnostics.push({
+        checkId: "TF018",
+        severity: "info",
+        message:
+          `Output "${blockName(block.address)}" returns the whole of \`${reference}\`, so every ` +
+          "attribute the provider schema has becomes part of this module's public interface, " +
+          "including the ones a provider upgrade adds later. Return the attribute the caller needs " +
+          `(\`${reference}.id\`, \`${reference}.arn\`) instead.`,
+        entity: block.key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,72 @@
+/**
+ * TF019: a meta-argument is explicitly set to its own default, `false`.
+ *
+ * `sensitive` and `ephemeral` on a `variable` or an `output`, `prevent_destroy`
+ * and `create_before_destroy` inside a `lifecycle` block. All four default to
+ * false, so writing it changes nothing and reads as though someone considered
+ * the setting and turned it off, which is exactly the impression a reviewer
+ * should not get from a variable called `password`.
+ *
+ * The first TF rule with a mechanical fix: the remediation is the deletion of
+ * the line, so this ships `fixKind: "deterministic"` and `chant audit` renders
+ * the diff in its quick-wins section. `packages/core/src/audit/proof.ts` owns
+ * the patch, as it does for every other deterministic rule.
+ *
+ * Only a literal `false` counts. `prevent_destroy = var.protect` is a real
+ * decision expressed as a variable, and hcl2json leaves it a `"${var.protect}"`
+ * string rather than a boolean, so it never reaches the comparison.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { DATA_TYPE, OUTPUT_TYPE, RESOURCE_TYPE, VARIABLE_TYPE } from "../../hcl/parse";
+import { blocksOfTypes, nestedBodies, type TerraformBlock } from "./blocks";
+
+/** Meta-arguments that default to false on a `variable` or an `output`. */
+const BLOCK_ARGS = ["sensitive", "ephemeral"] as const;
+/** Meta-arguments that default to false inside a `lifecycle` block. */
+const LIFECYCLE_ARGS = ["prevent_destroy", "create_before_destroy"] as const;
+
+function redundant(block: TerraformBlock, arg: string, where: string): PostSynthDiagnostic {
+  return {
+    checkId: "TF019",
+    severity: "info",
+    message:
+      `"${block.address}" sets \`${arg} = false\`${where}, which is already the default. Declaring a ` +
+      "default reads as a deliberate decision to turn the behaviour off. Delete the line.",
+    entity: `${block.key}.${arg}`,
+    lexicon: "terraform",
+  };
+}
+
+export const tf019: PostSynthCheck = {
+  id: "TF019",
+  description: "Meta-argument explicitly set to its default of false",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const block of blocksOfTypes(ctx, [VARIABLE_TYPE, OUTPUT_TYPE])) {
+      for (const arg of BLOCK_ARGS) {
+        if (block.body[arg] === false) diagnostics.push(redundant(block, arg, ""));
+      }
+    }
+
+    for (const block of blocksOfTypes(ctx, [RESOURCE_TYPE, DATA_TYPE])) {
+      for (const lifecycle of nestedBodies(block.body, "lifecycle")) {
+        for (const arg of LIFECYCLE_ARGS) {
+          if (lifecycle[arg] === false) diagnostics.push(redundant(block, arg, " in its `lifecycle` block"));
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,123 @@
+/**
+ * TF020: a `variable`, a `locals` entry, a `data` source or an aliased
+ * `provider` that nothing in its module scope references.
+ *
+ * Scope: root and child modules, each judged on its own. Terraform's
+ * namespaces are per module, so `var.region` inside `module.cdn` is the child
+ * module's variable and a reference to it in the root proves nothing about
+ * the child's. The reference index (`hcl/references.ts`) is keyed the same
+ * way, one scope per module, and this check never looks outside the scope the
+ * declaration is in.
+ *
+ * An unused declaration is dead weight rather than a defect, which is why
+ * this is report-only. It still earns a finding: a variable nobody reads is
+ * usually the leftover of a refactor, and the next reader has to prove that
+ * before deleting it. A data source is worse than dead weight, since it is
+ * read from the provider's API on every plan whether or not anything uses the
+ * result.
+ *
+ * Two deliberate gaps, both from the index being a string scan rather than an
+ * expression tree (see its module doc), and both the reason the credit to
+ * tflint's `terraform_unused_declarations` is `overlaps`:
+ *
+ * - A name mentioned in a string that is not an expression (a `description`
+ *   that says "overrides var.region") reads as a reference, so the
+ *   declaration is not reported. Quiet, and wrong in the safe direction.
+ * - A value reached only dynamically (`lookup(local.by_env, ...)` where the
+ *   map is built elsewhere) is a real reference the scan does see, since the
+ *   local is still named; but a variable consumed only through
+ *   `TF_VAR_`-style external input is not, and a root's variables are
+ *   frequently exactly that. Report-only keeps that from failing a build.
+ *
+ * A `provider` block with no `alias` is never reported: it is the default
+ * configuration for its type, used by every resource of that type without
+ * naming it. Only an aliased one has to be asked for by name.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import {
+  DATA_TYPE,
+  LOCALS_TYPE,
+  PROVIDER_TYPE,
+  VARIABLE_TYPE,
+  scopeOfKey,
+  type BlockBody,
+  type TerraformEntity,
+} from "../../hcl/parse";
+import { buildReferenceIndex, isReferenced } from "../../hcl/references";
+
+/** What a reader is being told to do about each kind of unused declaration. */
+const ADVICE: Record<string, string> = {
+  variable: "Delete it, or reference it where it was meant to be used.",
+  local: "Delete it, or reference it where it was meant to be used.",
+  data:
+    "Delete it. A data source is read from the provider on every plan, so an unused one costs an API " +
+    "call and a permission for a value nothing consumes.",
+  provider: "Delete it, or pass it to the resources or modules that were meant to use it.",
+};
+
+export const tf020: PostSynthCheck = {
+  id: "TF020",
+  description: "Declaration is never referenced in its module scope",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const index = buildReferenceIndex(ctx.entities);
+
+    const report = (key: string, kind: keyof typeof ADVICE, what: string): void => {
+      diagnostics.push({
+        checkId: "TF020",
+        severity: "warning",
+        message: `${what} is declared and never referenced in its module. ${ADVICE[kind]}`,
+        entity: key,
+        lexicon: "terraform",
+      });
+    };
+
+    for (const [key, entity] of ctx.entities) {
+      if (!isResourceDeclarable(entity)) continue;
+      const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+      const address = typeof props.address === "string" ? props.address : key;
+      const scope = scopeOfKey(key);
+
+      if (entity.entityType === VARIABLE_TYPE) {
+        // Excluding the variable's own key matters here: a `validation` block
+        // reads `var.<self>` in its condition, which would otherwise make
+        // every validated variable look used.
+        if (!isReferenced(index, scope, address, key)) report(key, "variable", `Variable "${address}"`);
+        continue;
+      }
+
+      if (entity.entityType === LOCALS_TYPE) {
+        for (const name of Object.keys(body)) {
+          // No self-exclusion: one `locals` block is many declarations, and a
+          // local reading another local of the same block is a real use.
+          if (!isReferenced(index, scope, `local.${name}`)) report(key, "local", `Local value "local.${name}"`);
+        }
+        continue;
+      }
+
+      if (entity.entityType === DATA_TYPE) {
+        if (!isReferenced(index, scope, address, key)) report(key, "data", `Data source "${address}"`);
+        continue;
+      }
+
+      if (entity.entityType === PROVIDER_TYPE) {
+        const alias = typeof body.alias === "string" ? body.alias : undefined;
+        if (alias === undefined || alias.trim() === "") continue;
+        const type = address.startsWith("provider.") ? address.slice("provider.".length) : address;
+        if (!isReferenced(index, scope, `provider.${type}.${alias}`, key)) {
+          report(key, "provider", `Aliased provider "${type}.${alias}"`);
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,126 @@
+/**
+ * TF021: `count` used where `for_each` is safer, judged narrowly.
+ *
+ * Scope: root and child modules. A resource is a resource wherever it is
+ * declared, and the failure mode below does not depend on the scope.
+ *
+ * `count` addresses its instances by position: `aws_instance.web[0]`,
+ * `[1]`, `[2]`. Delete the middle element of the list the count was derived
+ * from and every instance after it shifts down one, so Terraform plans to
+ * destroy and recreate them all, in order, to move each one's identity onto
+ * the next index. `for_each` addresses by key instead, and removing one
+ * element removes exactly one instance.
+ *
+ * The narrow part is which counts get reported. Two conditions must both
+ * hold:
+ *
+ * 1. The count is plural and derived, not a switch. A numeric literal of two
+ *    or more, or `length(var.x)` / `length(local.x)`. `count = 0`, `count =
+ *    1` and `count = var.enabled ? 1 : 0` are the conditional-resource idiom,
+ *    which `for_each` does not replace, and they are never reported.
+ * 2. The resource uses `count.index` to build something that carries the
+ *    instance's identity: a name, a bucket, a key, a `tags.Name`. That is what
+ *    makes a shift destructive; a `count.index` used only to pick a subnet out
+ *    of a list is reindexed silently and harmlessly.
+ *
+ * Redeploy's `terraform_prefer_for_each` reports every `count` over a
+ * collection, which is a broader rule and a noisier one, so the credit is
+ * `overlaps` rather than `equivalent`. choudoufu's `RuleCountIndex`
+ * (`internal/live/lint/count_index.go`) is the survey's deepest treatment of
+ * the identity-bearing question, and it is credited the same way. Report-only
+ * either way: a `count` with a stable list behind it is fine forever, and
+ * only the person who knows whether that list is stable can say.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { RESOURCE_TYPE, type BlockBody, type TerraformEntity } from "../../hcl/parse";
+import { walkAttributes } from "./blocks";
+
+/** `length(var.x)` or `length(local.x)`, as hcl2json renders the expression. */
+const LENGTH_OF = /^\$\{?\s*length\(\s*(var|local)\.[A-Za-z_][A-Za-z0-9_-]*\s*\)\s*\}?$/;
+
+/**
+ * Attribute names whose value IS the instance's identity to the provider: a
+ * rename destroys and recreates. Matched on the last path segment, so
+ * `tags.Name` and `labels.name` are covered without listing every container.
+ */
+const IDENTITY_ATTRIBUTES = new Set([
+  "name",
+  "bucket",
+  "key",
+  "identifier",
+  "hostname",
+  "domain",
+  "domain_name",
+  "display_name",
+  "resource_name",
+  "alias",
+  "prefix",
+  "path",
+  "topic",
+  "queue_name",
+  "function_name",
+  "db_name",
+  "repository",
+]);
+
+/** The `count` value, when it is one this rule reports on. */
+export function pluralCount(body: BlockBody): string | undefined {
+  const count = body.count;
+  if (typeof count === "number") return count >= 2 ? String(count) : undefined;
+  if (typeof count !== "string") return undefined;
+  if (LENGTH_OF.test(count.trim())) return count.replace(/^\$\{?/, "").replace(/\}$/, "");
+  const literal = /^\$\{?\s*(\d+)\s*\}?$/.exec(count.trim());
+  return literal && Number(literal[1]) >= 2 ? literal[1] : undefined;
+}
+
+/** Identity-bearing attributes of this body whose value is built from `count.index`. */
+export function identityUsesOfCountIndex(body: BlockBody): string[] {
+  const out: string[] = [];
+  for (const attr of walkAttributes(body)) {
+    if (typeof attr.value !== "string" || !attr.value.includes("count.index")) continue;
+    if (!IDENTITY_ATTRIBUTES.has(attr.name.toLowerCase())) continue;
+    out.push(attr.path);
+  }
+  return out;
+}
+
+export const tf021: PostSynthCheck = {
+  id: "TF021",
+  description: "count builds instance identities from count.index where for_each is safer",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [key, entity] of ctx.entities) {
+      if (entity.entityType !== RESOURCE_TYPE || !isResourceDeclarable(entity)) continue;
+      const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+
+      const count = pluralCount(body);
+      if (count === undefined) continue;
+      const uses = identityUsesOfCountIndex(body);
+      if (uses.length === 0) continue;
+
+      const address = typeof props.address === "string" ? props.address : key;
+      diagnostics.push({
+        checkId: "TF021",
+        severity: "warning",
+        message:
+          `Resource "${address}" has \`count = ${count}\` and builds ${uses.sort().join(", ")} from ` +
+          "`count.index`, so each instance's identity is its position in the list. Removing an element " +
+          "shifts every later instance down one index, and Terraform destroys and recreates all of them " +
+          "to match. Use `for_each` over a map or set so each instance is addressed by a stable key.",
+        entity: key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};