@intentius/chant-lexicon-terraform 0.57.0 → 0.59.0

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

@@ -1,16 +1,39 @@
 /**
  * TF001: a root module keeps its state on local disk.
  *
- * A `terraform` block with no `backend "<type>"` and no `cloud {}` falls back
- * to the local backend, which puts `terraform.tfstate` in the working
- * directory. That file holds every attribute of every managed resource,
- * secrets included, and it is not shared, not locked, and not versioned. The
- * first apply from a second machine or a CI runner starts from an empty state
- * and proposes to create the estate again.
+ * Two ways a root gets there, and this reports both (#2218). A `terraform`
+ * block with no `backend "<type>"` and no `cloud {}` falls back to the local
+ * backend implicitly. A `backend "local"` block asks for the same backend by
+ * name. Either way `terraform.tfstate` lands in the working directory, and
+ * that file holds every attribute of every managed resource, secrets
+ * included, and it is not shared, not locked, and not versioned. The first
+ * apply from a second machine or a CI runner starts from an empty state and
+ * proposes to create the estate again.
+ *
+ * So the rule reads the backend block's TYPE LABEL rather than its presence:
+ * the id means "no remote backend", which is what its name, its message and
+ * its page have always argued. `cloud {}` counts as remote (it is Terraform
+ * Cloud / HCP state, held off the machine and locked). Every other backend
+ * type is taken as remote without a list to maintain, since `local` is the
+ * only backend Terraform ships that writes to the working directory.
+ *
+ * A root that keeps local state on purpose says so with a
+ * `# chant-ignore-block: TF001` on the line above its `terraform` block
+ * (chant #2111), which is what the three shipped examples do.
  *
  * One diagnostic per root, fired from the root's `terraform` block. A root
  * with no `terraform` block at all is not flagged: it declares no version
  * constraints either, and the missing block is a different finding.
+ *
+ * Scope: root modules only (#2112). A child module must NOT declare a
+ * backend, which is the mirror image and TF015's finding, so a descended
+ * module's `terraform` block is skipped here rather than read as if it were
+ * the root's.
+ *
+ * Does not fire on a live root (#2103): a `backend` block is exactly what
+ * choudoufu refuses there (TF024's territory), and the fallback to local
+ * state this check warns about does not apply, since a live root keeps no
+ * state file at all, local or remote.
  */
 
 import type {
@@ -20,13 +43,53 @@ import type {
 } from "@intentius/chant/lint/post-synth";
 import { isResourceDeclarable } from "@intentius/chant/declarable";
 import { TERRAFORM_TYPE, type BlockBody } from "../../hcl/parse";
+import { attr } from "../../hcl/value";
+import { isRootScoped } from "./scope";
 
-/** `backend`/`cloud` are blocks, so hcl2json encodes them as a value under the key. */
-function hasBlock(body: BlockBody, key: string): boolean {
-  const value = body[key];
-  if (value === undefined || value === null) return false;
-  if (Array.isArray(value)) return value.length > 0;
-  return typeof value === "object" ? Object.keys(value as object).length > 0 : true;
+/**
+ * `backend`/`cloud` are blocks, so hcl2json encodes them as a value under the
+ * key, structurally the same "literal value under this key" shape `attr()`
+ * (`../../hcl/value.ts`, chant #2113) reads for an ordinary attribute, so
+ * this reads through it rather than re-deriving presence by hand.
+ */
+export function hasBlock(body: BlockBody, key: string): boolean {
+  const a = attr(body, key);
+  if (a.kind === "absent") return false;
+  if (Array.isArray(a.value)) return a.value.length > 0;
+  return typeof a.value === "object" && a.value !== null ? Object.keys(a.value).length > 0 : true;
+}
+
+/** The one backend type that writes state to the working directory. */
+export const LOCAL_BACKEND = "local";
+
+/**
+ * The type labels of the `backend` blocks in a `terraform` block body.
+ *
+ * `backend` takes one label, so hcl2json nests it one level deeper than an
+ * unlabelled block: `backend "s3" { bucket = "b" }` is
+ * `{ backend: { s3: [{ bucket: "b" }] } }`, where `cloud { ... }` is just
+ * `{ cloud: [{ ... }] }`. The keys of that inner object are the labels, which
+ * is the only place the type survives the parse. A malformed body that puts
+ * an array or a scalar under `backend` yields no labels, and the caller then
+ * treats the root as having no remote backend, the same verdict a missing
+ * block gets.
+ */
+export function backendTypes(body: BlockBody): string[] {
+  const a = attr(body, "backend");
+  if (a.kind === "absent") return [];
+  const value = a.value;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return [];
+  return Object.keys(value);
+}
+
+/**
+ * Whether the body configures state somewhere other than the working
+ * directory: any `backend` block whose type is not `local`, or a `cloud`
+ * block.
+ */
+export function hasRemoteBackend(body: BlockBody): boolean {
+  if (hasBlock(body, "cloud")) return true;
+  return backendTypes(body).some((type) => type !== LOCAL_BACKEND);
 }
 
 export const tf001: PostSynthCheck = {
@@ -40,24 +103,41 @@ export const tf001: PostSynthCheck = {
 
     for (const [name, entity] of ctx.entities) {
       if (entity.entityType !== TERRAFORM_TYPE) continue;
-      if (!isResourceDeclarable(entity)) continue;
-      const props = entity.props as { root?: unknown; body?: unknown };
+      if (!isResourceDeclarable(entity) || !isRootScoped(entity)) continue;
+      const props = entity.props as { root?: unknown; body?: unknown; mode?: unknown };
+      if (props.mode === "live") continue;
       const root = typeof props.root === "string" ? props.root : "";
       if (flagged.has(root)) continue;
 
       const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
-      if (hasBlock(body, "backend") || hasBlock(body, "cloud")) continue;
+      if (hasRemoteBackend(body)) continue;
+
+      // What the root actually declares, so the message names it rather than
+      // saying "no remote backend" over a block the reader can see.
+      const found = backendTypes(body).includes(LOCAL_BACKEND)
+        ? 'the backend it declares is `backend "local"`'
+        : "there is no backend block at all";
 
       flagged.add(root);
       diagnostics.push({
         checkId: "TF001",
         severity: "warning",
         message:
-          `Root module "${root}" declares no remote backend. State falls back to a local ` +
-          "terraform.tfstate, which is unshared, unlocked and holds every resource attribute in " +
-          'plaintext. Add a `backend "<type>"` or a `cloud {}` block to the terraform block.',
+          `Root module "${root}" declares no remote backend: ${found}. State is a ` +
+          "terraform.tfstate in the working directory, which is unshared, unlocked and holds every " +
+          'resource attribute in plaintext. Declare a `backend "<type>"` naming a remote type (`s3`, ' +
+          "`gcs`, `azurerm`, `http`) or a `cloud {}` block, or keep the local state on purpose with a " +
+          "`# chant-ignore-block: TF001` above the terraform block.",
         entity: name,
         lexicon: "terraform",
+        // The missing-resource shape (chant #2113): there is no remote
+        // `backend`/`cloud` block to point at, only the root that lacks one.
+        // `entity` above still names the `terraform` block this fired from (by
+        // convenience, not because that block is what's wrong), so `missing`
+        // is what a suppression should key on instead. `kind` stays `backend`
+        // in both cases: what is absent is a remote backend, whether or not a
+        // `backend "local"` block is sitting where one should be.
+        missing: { kind: "backend", scope: root },
       });
     }
 

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

@@ -0,0 +1,93 @@
+import { describe, expect, test } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { tf002 } from "./tf002";
+import { loadFixture } from "./fixtures/load";
+import { TERRAFORM_TYPE, PROVIDER_TYPE, RESOURCE_TYPE, terraformEntity } from "../../hcl/parse";
+
+function makeCtx(entities: Record<string, ReturnType<typeof terraformEntity>>): PostSynthContext {
+  return {
+    outputs: new Map(),
+    entities: new Map(Object.entries(entities)),
+  } as unknown as PostSynthContext;
+}
+
+describe("TF002: provider implied by the root has no required_providers entry", () => {
+  test("check metadata", () => {
+    expect(tf002.id).toBe("TF002");
+    expect(tf002.description).toContain("required_providers");
+  });
+
+  test("flags a provider implied by a resource type prefix with no entry at all", async () => {
+    const diags = tf002.check(await loadFixture("TF002", "positive"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("TF002");
+    expect(diags[0].message).toContain("google");
+    expect(diags[0].lexicon).toBe("terraform");
+  });
+
+  test("flags the legacy shorthand form as lacking source", async () => {
+    const diags = tf002.check(await loadFixture("TF002", "positive-legacy"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("aws");
+    expect(diags[0].message).toContain("source");
+  });
+
+  test("flags an entry missing version", async () => {
+    const diags = tf002.check(await loadFixture("TF002", "positive-no-version"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("version");
+  });
+
+  test("passes a fully constrained provider", async () => {
+    const diags = tf002.check(await loadFixture("TF002", "negative"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("fires once per provider, not once per resource", () => {
+    const diags = tf002.check(
+      makeCtx({
+        "app/terraform": terraformEntity(TERRAFORM_TYPE, "terraform", { required_version: ">= 1.5.0" }, "main.tf", "app"),
+        "app/aws_instance.a": terraformEntity(RESOURCE_TYPE, "aws_instance.a", {}, "main.tf", "app"),
+        "app/aws_instance.b": terraformEntity(RESOURCE_TYPE, "aws_instance.b", {}, "main.tf", "app"),
+      }),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  test("skips the builtin terraform provider (terraform_remote_state)", () => {
+    const diags = tf002.check(
+      makeCtx({
+        "app/terraform": terraformEntity(TERRAFORM_TYPE, "terraform", { required_version: ">= 1.5.0" }, "main.tf", "app"),
+        "app/data.terraform_remote_state.other": terraformEntity(
+          "Terraform::Data",
+          "data.terraform_remote_state.other",
+          {},
+          "main.tf",
+          "app",
+        ),
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  test("anchors on the explicit provider block over the resource that also implies it", () => {
+    const diags = tf002.check(
+      makeCtx({
+        "app/terraform": terraformEntity(TERRAFORM_TYPE, "terraform", { required_version: ">= 1.5.0" }, "main.tf", "app"),
+        "app/aws_instance.web": terraformEntity(RESOURCE_TYPE, "aws_instance.web", {}, "main.tf", "app"),
+        "app/provider.aws": terraformEntity(PROVIDER_TYPE, "provider.aws", {}, "main.tf", "app"),
+      }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("app/provider.aws");
+  });
+
+  test("ignores a root with no terraform block at all", () => {
+    const diags = tf002.check(
+      makeCtx({
+        "app/aws_instance.web": terraformEntity(RESOURCE_TYPE, "aws_instance.web", {}, "main.tf", "app"),
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,151 @@
+/**
+ * TF002: a provider a root implies has no `required_providers` entry, or an
+ * incomplete one.
+ *
+ * A provider is implied two ways: an explicit `provider "<name>" {}` block,
+ * or a resource/data type prefix (`aws_instance` implies `aws`, up to the
+ * first underscore, the same heuristic tflint's `terraform_required_providers`
+ * reads via `GetProviderRefs()`). The `terraform` builtin (the provider
+ * behind `terraform_remote_state`) is never implied: it has no registry
+ * entry to require. Every implied provider needs a `required_providers`
+ * entry that is an object carrying both `source` and `version`, since the old
+ * shorthand form (`aws = "~> 4.0"`, a bare string) has neither and fires the
+ * same as a missing entry.
+ *
+ * Fires once per incomplete or missing provider, not once per resource: two
+ * resources implying the same unconstrained provider produce one diagnostic.
+ * Anchored on whichever entity first implied the provider, preferring an
+ * explicit `provider` block over a resource/data type, so the diagnostic
+ * points at the most specific place a fix belongs.
+ *
+ * A root with no `terraform` block at all is out of scope, same as TF001:
+ * the missing block is that rule's finding, not this one's.
+ *
+ * Scope: root modules only (#2112). A child module's own `required_providers`
+ * are the child's business, and its resources are constrained by the root's
+ * block at plan time, so folding a descended module's blocks into this pass
+ * would both credit the root with requirements it never declared and judge it
+ * on providers it never named.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { isRootScoped } from "./scope";
+import {
+  DATA_TYPE,
+  PROVIDER_TYPE,
+  RESOURCE_TYPE,
+  TERRAFORM_TYPE,
+  type BlockBody,
+} from "../../hcl/parse";
+
+/** The `terraform` provider backs `terraform_remote_state`; it ships with the binary, not the registry. */
+const BUILTIN_PROVIDERS = new Set(["terraform"]);
+
+function providerNameFromType(type: string): string {
+  return type.split("_")[0];
+}
+
+/** One implied provider name to the entity key that first implied it in file order. */
+function impliedProviders(entities: PostSynthContext["entities"], root: string): Map<string, string> {
+  const implied = new Map<string, string>();
+  const fromProviderBlock = new Set<string>();
+
+  for (const [key, entity] of entities) {
+    if (!isResourceDeclarable(entity) || !isRootScoped(entity)) continue;
+    const props = entity.props as { root?: unknown; address?: unknown };
+    if (props.root !== root) continue;
+    const address = typeof props.address === "string" ? props.address : "";
+
+    if (entity.entityType === PROVIDER_TYPE) {
+      const name = address.slice("provider.".length);
+      if (BUILTIN_PROVIDERS.has(name)) continue;
+      implied.set(name, key);
+      fromProviderBlock.add(name);
+    } else if (entity.entityType === RESOURCE_TYPE) {
+      const type = address.split(".")[0] ?? "";
+      const name = providerNameFromType(type);
+      if (BUILTIN_PROVIDERS.has(name) || fromProviderBlock.has(name)) continue;
+      if (!implied.has(name)) implied.set(name, key);
+    } else if (entity.entityType === DATA_TYPE) {
+      const type = address.split(".")[1] ?? "";
+      const name = providerNameFromType(type);
+      if (BUILTIN_PROVIDERS.has(name) || fromProviderBlock.has(name)) continue;
+      if (!implied.has(name)) implied.set(name, key);
+    }
+  }
+
+  return implied;
+}
+
+/** `required_providers` is a nested block: hcl2json encodes it as a one-element array of `{name: entry}`. */
+function requiredProvidersMap(body: BlockBody): Record<string, unknown> {
+  const merged: Record<string, unknown> = {};
+  const blocks = body.required_providers;
+  if (!Array.isArray(blocks)) return merged;
+  for (const block of blocks) {
+    if (typeof block === "object" && block !== null) Object.assign(merged, block);
+  }
+  return merged;
+}
+
+/** Why a `required_providers` entry is incomplete, or `undefined` if it's fine. */
+function entryProblem(entry: unknown): string | undefined {
+  if (entry === undefined) return "no `required_providers` entry";
+  if (typeof entry === "string") return "the legacy shorthand form (a bare version string), which carries no `source`";
+  if (typeof entry !== "object" || entry === null) return "an entry that is not a valid object";
+  const obj = entry as Record<string, unknown>;
+  const missing: string[] = [];
+  if (typeof obj.source !== "string" || obj.source === "") missing.push("`source`");
+  if (typeof obj.version !== "string" || obj.version === "") missing.push("`version`");
+  return missing.length > 0 ? `an entry missing ${missing.join(" and ")}` : undefined;
+}
+
+export const tf002: PostSynthCheck = {
+  id: "TF002",
+  description: "A provider the root implies has no required_providers entry, or an incomplete one",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const roots = new Set<string>();
+    const requiredByRoot = new Map<string, Record<string, unknown>>();
+
+    for (const entity of ctx.entities.values()) {
+      if (entity.entityType !== TERRAFORM_TYPE || !isResourceDeclarable(entity)) continue;
+      if (!isRootScoped(entity)) continue;
+      const props = entity.props as { root?: unknown; body?: unknown };
+      const root = typeof props.root === "string" ? props.root : "";
+      roots.add(root);
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+      const merged = requiredByRoot.get(root) ?? {};
+      Object.assign(merged, requiredProvidersMap(body));
+      requiredByRoot.set(root, merged);
+    }
+
+    for (const root of [...roots].sort()) {
+      const required = requiredByRoot.get(root) ?? {};
+      const implied = impliedProviders(ctx.entities, root);
+
+      for (const name of [...implied.keys()].sort()) {
+        const problem = entryProblem(required[name]);
+        if (!problem) continue;
+        diagnostics.push({
+          checkId: "TF002",
+          severity: "warning",
+          message:
+            `Provider "${name}" is used in root module "${root}" but has ${problem} in ` +
+            "`required_providers`. Add `source` and `version` for it in the terraform block's " +
+            "`required_providers`, so a future provider release can't silently change behavior.",
+          entity: implied.get(name),
+          lexicon: "terraform",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { tf003 } from "./tf003";
+import { loadFixture } from "./fixtures/load";
+import { TERRAFORM_TYPE, terraformEntity } from "../../hcl/parse";
+
+function makeCtx(entities: Record<string, ReturnType<typeof terraformEntity>>): PostSynthContext {
+  return {
+    outputs: new Map(),
+    entities: new Map(Object.entries(entities)),
+  } as unknown as PostSynthContext;
+}
+
+function terraformBlock(root: string, body: Record<string, unknown>): ReturnType<typeof terraformEntity> {
+  return terraformEntity(TERRAFORM_TYPE, "terraform", body, "main.tf", root);
+}
+
+describe("TF003: root module's terraform block has no required_version", () => {
+  test("check metadata", () => {
+    expect(tf003.id).toBe("TF003");
+    expect(tf003.description).toContain("required_version");
+  });
+
+  test("flags a terraform block missing required_version", async () => {
+    const diags = tf003.check(await loadFixture("TF003", "positive"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("TF003");
+    expect(diags[0].entity).toBe("TF003/terraform");
+    expect(diags[0].lexicon).toBe("terraform");
+  });
+
+  test("passes a terraform block with required_version", async () => {
+    const diags = tf003.check(await loadFixture("TF003", "negative"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("fires once per root even split across two terraform blocks", () => {
+    const diags = tf003.check(
+      makeCtx({
+        "app/terraform": terraformBlock("app", {}),
+        "app/terraform~2": terraformBlock("app", { required_providers: [{}] }),
+      }),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  test("passes when required_version is declared on a later block for the same root", () => {
+    const diags = tf003.check(
+      makeCtx({
+        "app/terraform": terraformBlock("app", {}),
+        "app/terraform~2": terraformBlock("app", { required_version: ">= 1.5.0" }),
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  test("reports each root separately", () => {
+    const diags = tf003.check(
+      makeCtx({
+        "legacy/terraform": terraformBlock("legacy", {}),
+        "app/terraform": terraformBlock("app", { required_version: ">= 1.5.0" }),
+      }),
+    );
+    expect(diags.map((d) => d.entity)).toEqual(["legacy/terraform"]);
+  });
+
+  test("ignores a root with no terraform block at all", () => {
+    const diags = tf003.check(
+      makeCtx({
+        "app/null_resource.first": terraformEntity("Terraform::Resource", "null_resource.first", {}, "main.tf", "app"),
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,71 @@
+/**
+ * TF003: a root's `terraform` block has no `required_version`.
+ *
+ * Sits on the same `terraform` block TF001 already walks. Without
+ * `required_version`, a root can be applied by whatever Terraform binary
+ * happens to be on the runner's `PATH`, and a binary upgrade that changes
+ * behavior (a provider protocol bump, a changed default) surfaces as a
+ * surprise plan diff instead of a version-check failure before anything runs.
+ *
+ * One diagnostic per root, fired once even if the root spreads its
+ * `terraform` block across several files (a legacy-config split into
+ * `terraform.tf` and `versions.tf`, say). A root with no `terraform` block
+ * at all is out of scope, same as TF001 and TF002: the missing block is
+ * their finding, not this one's.
+ *
+ * Scope: root modules only (#2112). A child module may legitimately leave
+ * `required_version` to the root that calls it, so a descended module's
+ * `terraform` block is skipped here.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { isRootScoped } from "./scope";
+import { TERRAFORM_TYPE, type BlockBody } from "../../hcl/parse";
+
+function hasRequiredVersion(body: BlockBody): boolean {
+  return typeof body.required_version === "string" && body.required_version.trim() !== "";
+}
+
+export const tf003: PostSynthCheck = {
+  id: "TF003",
+  description: "Root module's terraform block has no required_version",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    /** Root name to the entity key of its first `terraform` block, and whether any block for it declares `required_version`. */
+    const seen = new Map<string, { anchor: string; hasVersion: boolean }>();
+
+    for (const [key, entity] of ctx.entities) {
+      if (entity.entityType !== TERRAFORM_TYPE || !isResourceDeclarable(entity)) continue;
+      if (!isRootScoped(entity)) continue;
+      const props = entity.props as { root?: unknown; body?: unknown };
+      const root = typeof props.root === "string" ? props.root : "";
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+
+      const existing = seen.get(root);
+      const hasVersion = (existing?.hasVersion ?? false) || hasRequiredVersion(body);
+      seen.set(root, { anchor: existing?.anchor ?? key, hasVersion });
+    }
+
+    for (const [root, { anchor, hasVersion }] of [...seen].sort(([a], [b]) => a.localeCompare(b))) {
+      if (hasVersion) continue;
+      diagnostics.push({
+        checkId: "TF003",
+        severity: "warning",
+        message:
+          `Root module "${root}"'s terraform block has no \`required_version\`. Without it, ` +
+          "an upgraded Terraform binary can change behavior with no version-check failure to " +
+          "flag it first. Add `required_version = \">= <lowest supported version>\"`.",
+        entity: anchor,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "vitest";
+import { tf004 } from "./tf004";
+import { tf005 } from "./tf005";
+import { loadFixture } from "./fixtures/load";
+
+describe("TF004: registry-sourced module block has no version", () => {
+  test("check metadata", () => {
+    expect(tf004.id).toBe("TF004");
+    expect(tf004.description.toLowerCase()).toContain("registry");
+  });
+
+  test("flags a registry module with no version", async () => {
+    const diags = tf004.check(await loadFixture("TF004", "positive"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("TF004");
+    expect(diags[0].message).toContain("terraform-aws-modules/vpc/aws");
+    expect(diags[0].entity).toBe("TF004/module.vpc");
+    expect(diags[0].lexicon).toBe("terraform");
+  });
+
+  test("passes a registry module with a version", async () => {
+    const diags = tf004.check(await loadFixture("TF004", "negative"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("never fires on a local source", async () => {
+    const diags = tf004.check(await loadFixture("TF004", "negative-local"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("never fires on a git source", async () => {
+    const diags = tf004.check(await loadFixture("TF004", "negative-git"));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("is exclusive of TF005 on a git-sourced module block", async () => {
+    const ctx = await loadFixture("TF004", "negative-git");
+    expect(tf004.check(ctx)).toHaveLength(0);
+    expect(tf005.check(ctx)).toHaveLength(0); // pinned to a tag, so neither fires
+  });
+
+  test("is exclusive of TF005 on a registry-sourced module block", async () => {
+    const ctx = await loadFixture("TF004", "positive");
+    expect(tf004.check(ctx)).toHaveLength(1);
+    expect(tf005.check(ctx)).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,63 @@
+/**
+ * TF004: a registry-sourced `module` block has no `version`.
+ *
+ * "Registry-sourced" means `source` parses as a Terraform module registry
+ * address (`classifyModuleSource`, `./module-source.ts`): a bare
+ * `namespace/name/target-system`, or a hostname-prefixed
+ * `host/namespace/name/target-system`. Without `version`, `terraform init`
+ * always resolves to the newest release that satisfies no constraint at
+ * all, so an upstream module release can change what a root provisions with
+ * no local edit and no diff to review first.
+ *
+ * A local (`./`, `../`) or git/hg source is never flagged here: git/hg is
+ * TF005's territory, and a local source cannot carry a registry version at
+ * all. One diagnostic per module block.
+ *
+ * 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 { MODULE_TYPE, type BlockBody } from "../../hcl/parse";
+import { classifyModuleSource } from "./module-source";
+
+export const tf004: PostSynthCheck = {
+  id: "TF004",
+  description: "Registry-sourced module block has no version",
+
+  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 { root?: unknown; address?: unknown; body?: unknown };
+      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) continue;
+      if (classifyModuleSource(source).kind !== "registry") continue;
+
+      const version = body.version;
+      if (typeof version === "string" && version.trim() !== "") continue;
+
+      const address = typeof props.address === "string" ? props.address : key;
+      diagnostics.push({
+        checkId: "TF004",
+        severity: "warning",
+        message:
+          `Module "${address}" sources "${source}" from a registry with no \`version\`. ` +
+          "`terraform init` resolves to the newest release with no constraint to hold it back. " +
+          "Add a `version` constraint (e.g. `~> 5.0`).",
+        entity: key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};