@intentius/chant-lexicon-terraform 0.57.0 → 0.59.0

package/dist/rules/plan-before-apply.ts

@@ -27,6 +27,17 @@ import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lin
  * silent — the same deliberately shallow "bail rather than guess" posture
  * `validateStepOutputRefs` takes, since the runtime brand on a real
  * `StepOutputRef` is invisible to a source-level AST match.
+ *
+ * Fires on every `terraformApply` call, live root or stock. #2106 exempted
+ * live roots for one release, because choudoufu refused `-out` and
+ * `apply <planfile>` and the activity ran a bare `apply -auto-approve` with no
+ * plan file to pair. choudoufu v0.13.0 admits both under a `live` block
+ * ([choudoufu #878](https://github.com/INTENTIUS/choudoufu/issues/878)), and
+ * there the pairing matters more than on a stock root, not less: the apply
+ * re-plans the live system and compares its fresh plan against the file it was
+ * handed, so a plan file spelled out as a literal is an approval for a run
+ * nobody can trace back to a plan step. The exemption is gone with the
+ * condition that produced it, and this rule reads no project config at all.
  */
 export const planBeforeApplyRule: LintRule = {
   id: "TF101",

package/dist/rules/scope.ts

@@ -0,0 +1,107 @@
+/**
+ * Root scope or child scope, and the `Callers:` chain that says which call
+ * reached a finding (chant #2112).
+ *
+ * Since the parse descends into local modules, `ctx.entities` holds two kinds
+ * of block: the root module's own, keyed `<root>/<address>`, and a child
+ * module's, keyed `<root>/module.<name>/<address>` with the call chain on
+ * `props.callers`. Every check has to say which it applies to, and the three
+ * shapes that answer live here:
+ *
+ * - {@link isRootScoped} for a check about how a ROOT is assembled (TF001's
+ *   backend, TF002's `required_providers`): a child module has no backend and
+ *   no provider requirements of its own to judge, and reading one as if it
+ *   were the root's is how a root with a perfectly good backend gets flagged
+ *   because a module beneath it has none.
+ * - {@link isChildScoped} for the mirror, the two rules that are ONLY about
+ *   child modules (TF014, TF015).
+ * - {@link callersNote} for the sentence appended to a finding inside a
+ *   child, naming each call site with the file and line it sits on. tflint
+ *   prints the same thing as a `Callers:` block under the diagnostic
+ *   (https://github.com/terraform-linters/tflint/blob/master/docs/user-guide/calling-modules.md);
+ *   a `PostSynthDiagnostic` carries no ranges, so the chain goes in the
+ *   message, where a reader of any output format sees it.
+ *
+ * A check with no opinion (most of them: an unset `type` on a variable is the
+ * same finding wherever the variable lives) needs nothing from this module and
+ * runs over both scopes, which is what tflint does with its own language rules
+ * under `--call-module-type=local`.
+ */
+
+import type { PostSynthCheck, PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable, type Declarable } from "@intentius/chant/declarable";
+import { callersOfKey, type TerraformEntity } from "../../hcl/parse";
+
+/** The `module.<name>` chain on an entity, outermost first. Empty for a root block. */
+export function callersOf(entity: Declarable): readonly string[] {
+  if (!isResourceDeclarable(entity)) return [];
+  const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+  return Array.isArray(props.callers) ? props.callers : [];
+}
+
+/** Was this block declared in the root module itself? */
+export function isRootScoped(entity: Declarable): boolean {
+  return callersOf(entity).length === 0;
+}
+
+/** Was this block declared in a child module the root calls? */
+export function isChildScoped(entity: Declarable): boolean {
+  return callersOf(entity).length > 0;
+}
+
+/**
+ * The `Callers:` sentence for a finding on `key`, or `""` when the finding is
+ * in the root module.
+ *
+ * The call sites are the key's own prefixes: a finding on
+ * `app/module.cdn/module.bucket/aws_s3_bucket.assets` was reached through
+ * `app/module.cdn` and then `app/module.cdn/module.bucket`, both of them
+ * `module` block entities in `ctx.entities`, so the file and line each was
+ * parsed from are already recorded. A prefix with no entity (a hand-built
+ * context in a test) renders as the bare call name.
+ */
+export function callersNote(ctx: PostSynthContext, key: string): string {
+  const callers = callersOfKey(key);
+  if (callers.length === 0) return "";
+
+  const root = key.slice(0, key.indexOf("/"));
+  const hops = callers.map((caller, i) => {
+    const callSite = [root, ...callers.slice(0, i + 1)].join("/");
+    const entity = ctx.entities.get(callSite);
+    if (!entity || !isResourceDeclarable(entity)) return caller;
+    const props = (entity as TerraformEntity).props as Partial<TerraformEntity["props"]>;
+    const file = typeof props.file === "string" ? props.file : "";
+    if (file === "") return caller;
+    return typeof props.line === "number" ? `${caller} (${file}:${props.line})` : `${caller} (${file})`;
+  });
+
+  return ` Callers: ${[root, ...hops].join(" -> ")}.`;
+}
+
+/**
+ * Wrap every check so a finding inside a child module carries its
+ * {@link callersNote}, whichever rule produced it.
+ *
+ * Done once, here, rather than in each rule's message: a reader of a finding
+ * on `module.cdn`'s bucket needs to know which call reached that code no
+ * matter which of the twenty-odd checks reported it, and a rule that forgot
+ * to append the chain would be a silent gap. The wrapper is what
+ * `terraformPlugin.postSynthChecks()` returns; a rule's own `check()` is
+ * unchanged, which is what its unit tests call.
+ *
+ * A message that already names the chain is left alone, so a rule with
+ * something more specific to say about its callers can say it.
+ */
+export function withCallersChain(checks: readonly PostSynthCheck[]): PostSynthCheck[] {
+  return checks.map((check) => ({
+    ...check,
+    check(ctx: PostSynthContext) {
+      return check.check(ctx).map((diagnostic) => {
+        if (typeof diagnostic.entity !== "string") return diagnostic;
+        if (diagnostic.message.includes("Callers:")) return diagnostic;
+        const note = callersNote(ctx, diagnostic.entity);
+        return note === "" ? diagnostic : { ...diagnostic, message: diagnostic.message + note };
+      });
+    },
+  }));
+}

package/dist/rules/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/dist/rules/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/dist/rules/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/dist/rules/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;
+  },
+};

package/dist/rules/tf005.ts

@@ -0,0 +1,76 @@
+/**
+ * TF005: a git or hg `module` source with no `?ref=`, or a `?ref=` that
+ * isn't tight enough to call pinned.
+ *
+ * "Git or hg" is `classifyModuleSource`'s `"git"` kind (`./module-source.ts`):
+ * an explicit `git::`/`hg::` prefix, the bare `github.com`/`bitbucket.org`
+ * shorthands, an scp-style `git@host:path`, or anything ending in `.git`.
+ * A ref counts as pinned only if it is a semver-shaped tag or a full 40-hex
+ * commit SHA (`isPinnedRef`), stricter than checkov's `CKV_TF_1`/`CKV_TF_2`,
+ * which accept any `?ref=` containing `\d\.\d` (so `v1.2-dev` passes there;
+ * it does not here, and the rule's page section says so). A ref matching a
+ * well-known mutable branch name (`main`, `master`, `develop`, `trunk`) gets
+ * its own, more specific message, since that's the exact case tflint's
+ * `flexible` style (the style this rule ships; see the page section for what
+ * `semver` style would add) already reports on.
+ *
+ * A local (`./`, `../`) source is never flagged: it can't be pinned to a
+ * ref at all, and checkov's own module-pinning checks return `UNKNOWN`
+ * (not a failure) for the same reason. A registry source is TF004's
+ * territory, not this rule's; the two never fire on the same 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, isDefaultBranch, isPinnedRef } from "./module-source";
+
+export const tf005: PostSynthCheck = {
+  id: "TF005",
+  description: "Git/hg module source is unpinned, or pinned to a mutable ref",
+
+  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 };
+      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;
+
+      const classified = classifyModuleSource(source);
+      if (classified.kind !== "git") continue;
+
+      const address = typeof props.address === "string" ? props.address : key;
+      let message: string | undefined;
+
+      if (!classified.ref) {
+        message = `Module "${address}" sources "${source}" from git/hg with no \`?ref=\`. Add one pinned to a tag or a full commit SHA.`;
+      } else if (isDefaultBranch(classified.ref)) {
+        message = `Module "${address}" sources "${source}" pinned to "${classified.ref}", a mutable branch. Pin to a tag or a full commit SHA instead.`;
+      } else if (!isPinnedRef(classified.ref)) {
+        message = `Module "${address}" sources "${source}" pinned to "${classified.ref}", which is neither a tag nor a full commit SHA and can move. Pin to a tag or a full commit SHA instead.`;
+      }
+
+      if (!message) continue;
+      diagnostics.push({
+        checkId: "TF005",
+        severity: "warning",
+        message,
+        entity: key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};