@intentius/chant-lexicon-terraform 0.101.0 → 0.104.0

package/dist/rules/tf037.ts

@@ -0,0 +1,101 @@
+/**
+ * TF037: an ECR repository lets an image tag be repointed (chant #2288, epic
+ * #2284).
+ *
+ * The Terraform counterpart of the aws lexicon's WAW054, written natively.
+ *
+ * Absence is insecure for this resource, and the rule reports it.
+ * `aws_ecr_repository.image_tag_mutability` (provider
+ * `internal/service/ecr/repository.go`, v6.67.0) is optional with
+ * `Default: MUTABLE`, so a repository that does not set it lets anyone with
+ * push access move a tag (`prod`, `v1.4.2`) to different image content after
+ * it was deployed, scanned or signed.
+ *
+ * Provider v6 accepts four values (AWS added the two `_WITH_EXCLUSION` modes
+ * in 2025), and the rule reads them as follows:
+ *
+ * - `IMMUTABLE`: secure.
+ * - `IMMUTABLE_WITH_EXCLUSION`: secure. Tags matching an
+ *   `image_tag_mutability_exclusion_filter` stay mutable, a written-down
+ *   exception such as `latest`. A filter that is nothing but `*` excludes
+ *   every tag, so it is a finding; a filter from an expression is not
+ *   determined.
+ * - `MUTABLE`, absent, and `MUTABLE_WITH_EXCLUSION` (every tag mutable except
+ *   those the filters name): a finding.
+ * - an expression: not determined.
+ *
+ * Scope: root and child modules alike (#2112).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import type { TerraformBlock } from "./blocks";
+import { finding, nestedBodies, notDetermined, readString, resourcesOfType } from "./flat-attributes";
+
+const ID = "TF037";
+
+const FIX =
+  'Set `image_tag_mutability = "IMMUTABLE"` and push a new tag for each build, or `"IMMUTABLE_WITH_EXCLUSION"` with ' +
+  "an `image_tag_mutability_exclusion_filter` for the few moving tags (`latest`) that must stay mutable.";
+
+const TAIL = "TF037 does not evaluate expressions, so it cannot tell whether this repository's tags are immutable.";
+
+/** A diagnostic for an `IMMUTABLE_WITH_EXCLUSION` repository, or nothing. */
+function checkExclusions(block: TerraformBlock): PostSynthDiagnostic | undefined {
+  for (const [i, f] of nestedBodies(block.body, "image_tag_mutability_exclusion_filter").entries()) {
+    const filter = readString(f, "filter");
+    if (filter.kind === "unknown") {
+      return notDetermined(ID, block, `exclusion filter ${i + 1}: ${filter.reason}`, TAIL);
+    }
+    if (filter.kind === "known" && /^\*+$/.test(filter.value)) {
+      return finding(
+        ID,
+        "error",
+        block,
+        `is \`IMMUTABLE_WITH_EXCLUSION\`, but exclusion filter ${i + 1} is "${filter.value}", which matches every tag, ` +
+          `so every tag stays mutable. ${FIX}`,
+      );
+    }
+  }
+  if (nestedBodies(block.body, "dynamic").some((d) => d.image_tag_mutability_exclusion_filter !== undefined)) {
+    return notDetermined(ID, block, 'has a `dynamic "image_tag_mutability_exclusion_filter"` block', TAIL);
+  }
+  return undefined;
+}
+
+export const tf037: PostSynthCheck = {
+  id: "TF037",
+  description: "ECR repository allows mutable image tags",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const out: PostSynthDiagnostic[] = [];
+    for (const block of resourcesOfType(ctx, "aws_ecr_repository")) {
+      const mode = readString(block.body, "image_tag_mutability");
+      if (mode.kind === "unknown") {
+        out.push(notDetermined(ID, block, mode.reason, TAIL));
+        continue;
+      }
+      if (mode.kind === "known" && mode.value === "IMMUTABLE") continue;
+      if (mode.kind === "known" && mode.value === "IMMUTABLE_WITH_EXCLUSION") {
+        const d = checkExclusions(block);
+        if (d) out.push(d);
+        continue;
+      }
+      const how =
+        mode.kind === "absent"
+          ? "does not set `image_tag_mutability`, and the provider default is `MUTABLE`"
+          : mode.value === "MUTABLE_WITH_EXCLUSION"
+            ? "is `MUTABLE_WITH_EXCLUSION`, so every tag the exclusion filters do not name stays mutable"
+            : `sets \`image_tag_mutability = "${mode.value}"\``;
+      out.push(
+        finding(
+          ID,
+          "error",
+          block,
+          `${how}: a pushed tag can later be repointed at different image content, so what was deployed, scanned or ` +
+            `signed under that tag is no longer what it names. ${FIX}`,
+        ),
+      );
+    }
+    return out;
+  },
+};

package/dist/rules/tf038.ts

@@ -0,0 +1,71 @@
+/**
+ * TF038: an `oci://` module source names no tag and no digest, or a mutable
+ * tag.
+ *
+ * OpenTofu resolves an OCI module source with no `tag` to the `latest` tag
+ * (https://opentofu.org/docs/language/modules/sources/), so an unpinned source
+ * and `?tag=latest` are the same thing: a push to the registry changes what
+ * the root provisions with no diff to review. A digest, or an exact version
+ * tag, holds it. `classifyModuleSource` (`./module-source.ts`) reads the tag
+ * and digest from either spelling.
+ *
+ * A warning rather than an error: a registry can make a version tag
+ * immutable, and a source that names `?tag=1.4.0` is read as pinned here
+ * whether or not the registry enforces that. A digest is the only pin the
+ * registry cannot move, which the message says. A source that names a digest
+ * is never flagged, whatever tag sits beside it.
+ *
+ * Scope: root and child modules alike (#2112), same as TF004 and TF005.
+ */
+
+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, isMutableOciTag } from "./module-source";
+
+export const tf038: PostSynthCheck = {
+  id: "TF038",
+  description: "OCI module source has no tag or digest, or a mutable tag",
+
+  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 !== "oci" || classified.digest) continue;
+
+      const address = typeof props.address === "string" ? props.address : key;
+      let message: string | undefined;
+      if (!classified.tag) {
+        message =
+          `Module "${address}" sources "${source}" with no tag or digest, so OpenTofu pulls the \`latest\` tag. ` +
+          "Pin it to a digest (`?digest=sha256:...`) or an exact version tag (`?tag=1.4.0`).";
+      } else if (isMutableOciTag(classified.tag)) {
+        message =
+          `Module "${address}" sources "${source}" with the mutable tag "${classified.tag}". ` +
+          "Pin it to a digest (`?digest=sha256:...`) or an exact version tag (`?tag=1.4.0`).";
+      }
+      if (!message) continue;
+
+      diagnostics.push({
+        checkId: "TF038",
+        severity: "warning",
+        message,
+        entity: key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf039.ts

@@ -0,0 +1,64 @@
+/**
+ * TF039: a registry module's `version` is a range, not an exact version.
+ *
+ * TF004 flags a registry module with no `version`; a `version` of `~> 1.4`,
+ * `>= 1.4` or `>= 1.0, < 2.0` passes it, yet an upstream release inside the
+ * range changes what the root provisions with no diff to review. This rule is
+ * for projects that pin modules to one version (`1.4.0` or `= 1.4.0`).
+ *
+ * Off by default: it is a `report-only` catalog entry, so the `recommended`
+ * preset leaves it out and `lint.presets: { terraform: "all" }` (or a
+ * `lint.rules` entry for TF039) turns it on. Ranges are common and often
+ * intended, so a default warning would be noise for most roots. It is a
+ * separate rule from TF004 because a post-synth check receives no options
+ * (`PostSynthCheck.check(ctx)`), while the preset mechanism already carries
+ * exactly this on/off choice per rule id (#3190).
+ *
+ * A module that has no `version` is TF004's finding and is skipped here.
+ *
+ * Scope: root and child modules alike (#2112).
+ */
+
+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";
+
+export const tf039: PostSynthCheck = {
+  id: "TF039",
+  description: "Registry module version is a range, not an exact 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 { 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 || classifyModuleSource(source).kind !== "registry") continue;
+
+      const version = body.version;
+      if (typeof version !== "string" || version.trim() === "") continue;
+      if (isExactVersionConstraint(version)) continue;
+
+      const address = typeof props.address === "string" ? props.address : key;
+      diagnostics.push({
+        checkId: "TF039",
+        severity: "warning",
+        message:
+          `Module "${address}" sources "${source}" with the version range "${version}". ` +
+          "A release inside the range changes what the root provisions with no diff to review. " +
+          'Pin an exact version (`version = "1.4.0"`).',
+        entity: key,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf040.ts

@@ -0,0 +1,76 @@
+/**
+ * TF040: a root that uses providers has no `.terraform.lock.hcl`.
+ *
+ * The lock file records the provider versions and hashes `terraform init`
+ * selected. Without it, each `init` resolves `required_providers` constraints
+ * afresh, so a provider release changes a plan with no diff. None of
+ * TF001 to TF029 looks at it.
+ *
+ * "Committed" is decided by presence: the file sits beside the root's `.tf`
+ * files in the source tree being parsed (`props.lockFile`, stamped by
+ * `parseTerraformRootDir` and by the local audit path). Whether git tracks it
+ * is not asked, so a lock file that is present but gitignored counts as
+ * committed. A parse with no directory to look in (a fetched repository,
+ * inline source) leaves `lockFile` unset and the rule reports nothing: not
+ * determined, not clean.
+ *
+ * A root that implies no provider (no `provider` block and no resource or data
+ * type) gets no lock file from `init`, so it is skipped, as is a live
+ * choudoufu root, which runs no `init`. One diagnostic per root, anchored on
+ * the first block that implies a provider.
+ *
+ * Off by default in both places: the `report-only` tier keeps it out of a
+ * build's `recommended` preset, and `auditOptIn` keeps it out of `chant audit`.
+ * Many estates run `init` in CI and never commit the file.
+ *
+ * Scope: root modules only (#2112); a child module has no lock file of its own.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { LOCK_FILENAME } from "../../hcl/parse";
+import { isRootScoped } from "./scope";
+import { impliedProviders } from "./tf002";
+
+export const tf040: PostSynthCheck = {
+  id: "TF040",
+  description: "Root has no committed .terraform.lock.hcl",
+  // `chant audit` runs every rule, report-only ones included, so without this a
+  // new rule would change every project's audit output. A `lint.rules` entry
+  // for TF040 turns it on in the audit as well as in a build (#3190).
+  auditOptIn: true,
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const missing = new Set<string>();
+
+    for (const entity of ctx.entities.values()) {
+      if (!isResourceDeclarable(entity) || !isRootScoped(entity)) continue;
+      const props = entity.props as { root?: unknown; lockFile?: unknown; mode?: unknown };
+      if (props.lockFile !== false || props.mode === "live" || typeof props.root !== "string") continue;
+      missing.add(props.root);
+    }
+
+    for (const root of [...missing].sort()) {
+      const implied = impliedProviders(ctx.entities, root);
+      if (implied.size === 0) continue;
+      const names = [...implied.keys()].sort();
+      diagnostics.push({
+        checkId: "TF040",
+        severity: "warning",
+        message:
+          `Root module "${root}" uses ${names.length === 1 ? "provider" : "providers"} ${names.map((n) => `"${n}"`).join(", ")} ` +
+          `but has no ${LOCK_FILENAME} beside its .tf files. Run \`terraform init\` and commit the file, ` +
+          "so every init selects the same provider versions.",
+        entity: implied.get(names[0]),
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/tf041.ts

@@ -0,0 +1,56 @@
+/**
+ * TF041: a Terragrunt `dependency` has `mock_outputs` and lets them stand in
+ * for `apply`.
+ *
+ * `mock_outputs` is what a dependency returns when it has no outputs yet.
+ * `mock_outputs_allowed_terraform_commands` limits which commands may use
+ * them. Terragrunt reads a missing list and an empty list the same way, as no
+ * limit (`shouldReturnMockOutputs` in `pkg/config/dependency.go`, v1.1.6:
+ * `nil || len == 0 || slices.Contains(list, command)`). So a dependency with
+ * mocks and no list, or a list that names `apply`, can apply the mock values
+ * to real state when the upstream unit has not been applied, and the apply
+ * reports success. The usual list is `["validate", "plan"]`.
+ *
+ * A list that is an expression (`local.mock_commands`) is not determined and
+ * passes. A dependency with `enabled = false` returns its mocks whatever the
+ * list says; that is a different decision and is not reported here.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { TERRAGRUNT_DEPENDENCY_TYPE } from "../../hcl/parse";
+import { isExpression, terragruntEntities } from "./terragrunt";
+
+export const tf041: PostSynthCheck = {
+  id: "TF041",
+  description: "Terragrunt dependency lets mock_outputs stand in for apply",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const dep of terragruntEntities(ctx.entities, TERRAGRUNT_DEPENDENCY_TYPE)) {
+      if (dep.body.mock_outputs === undefined) continue;
+      const allowed = dep.body.mock_outputs_allowed_terraform_commands;
+      if (isExpression(allowed)) continue;
+
+      let problem: string | undefined;
+      if (allowed === undefined || (Array.isArray(allowed) && allowed.length === 0)) {
+        problem =
+          "sets no `mock_outputs_allowed_terraform_commands`, and Terragrunt reads a missing or empty list as every command";
+      } else if (Array.isArray(allowed) && allowed.includes("apply")) {
+        problem = 'lists "apply" in `mock_outputs_allowed_terraform_commands`';
+      }
+      if (problem === undefined) continue;
+
+      diagnostics.push({
+        checkId: "TF041",
+        severity: "warning",
+        message:
+          `Dependency "${dep.address.replace(/^dependency\./, "")}" in ${dep.file} sets \`mock_outputs\` and ${problem}. ` +
+          "An apply that runs before the upstream unit is applied writes the mock values to real state. " +
+          'Set `mock_outputs_allowed_terraform_commands = ["validate", "plan"]`.',
+        entity: dep.key,
+        lexicon: "terraform",
+      });
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/tf042.ts

@@ -0,0 +1,42 @@
+/**
+ * TF042: a Terragrunt `dependency` sets `skip_outputs = true` and
+ * `mock_outputs`.
+ *
+ * With `skip_outputs = true` Terragrunt never reads the upstream unit's
+ * outputs (`shouldGetOutputs` in `pkg/config/dependency.go`, v1.1.6), so the
+ * only values the dependency can return are the mocks. Every plan and apply
+ * the mocks are allowed for runs on them, however far the upstream unit has
+ * been applied. The pair is sometimes meant, to break a cycle or to avoid
+ * reading state, and then the mock values are the configuration; that is
+ * worth writing as inputs, which a reader of the unit can see.
+ *
+ * Only a literal `skip_outputs = true` is reported. A `skip_outputs` built
+ * from an expression is not determined.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { TERRAGRUNT_DEPENDENCY_TYPE } from "../../hcl/parse";
+import { terragruntEntities } from "./terragrunt";
+
+export const tf042: PostSynthCheck = {
+  id: "TF042",
+  description: "Terragrunt dependency sets skip_outputs together with mock_outputs",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const dep of terragruntEntities(ctx.entities, TERRAGRUNT_DEPENDENCY_TYPE)) {
+      if (dep.body.skip_outputs !== true || dep.body.mock_outputs === undefined) continue;
+      diagnostics.push({
+        checkId: "TF042",
+        severity: "warning",
+        message:
+          `Dependency "${dep.address.replace(/^dependency\./, "")}" in ${dep.file} sets \`skip_outputs = true\` with \`mock_outputs\`. ` +
+          "Terragrunt then never reads the upstream unit's outputs, so every plan and apply runs on the mock values. " +
+          "Drop `skip_outputs`, or pass the values as `inputs` so they are visible as configuration.",
+        entity: dep.key,
+        lexicon: "terraform",
+      });
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/tf043.ts

@@ -0,0 +1,49 @@
+/**
+ * TF043: a Terragrunt unit's `terraform.source` names no version.
+ *
+ * A git source with no `?ref=` follows the default branch, a `tfr://` source
+ * with no `?version=` follows the registry's latest release, and an `oci://`
+ * source with no tag or digest pulls `latest`. A push or a release changes
+ * what the unit provisions with no diff to review. TF005 and TF038 do the same
+ * for `module` blocks; a Terragrunt unit has no `module` block, its source is
+ * the `source` argument of the `terraform` block.
+ *
+ * A local path and a source built from an expression (`${local.base}//x`) are
+ * not determined and pass. A mutable `?ref=main` is not judged
+ * here: the rule asks only whether a version is named.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { TERRAGRUNT_SOURCE_TYPE } from "../../hcl/parse";
+import { classifyTerragruntSource, terragruntEntities } from "./terragrunt";
+
+const FIX: Record<string, string> = {
+  git: "Add `?ref=` with a tag or commit SHA.",
+  tfr: "Add `?version=` with an exact version.",
+  oci: "Add `?digest=sha256:...` or `?tag=` with an exact version tag.",
+};
+
+export const tf043: PostSynthCheck = {
+  id: "TF043",
+  description: "Terragrunt terraform.source names no version (git ref, tfr version or oci tag)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const block of terragruntEntities(ctx.entities, TERRAGRUNT_SOURCE_TYPE)) {
+      const source = block.body.source;
+      if (typeof source !== "string") continue;
+      const classified = classifyTerragruntSource(source);
+      if (classified.pinned !== false) continue;
+      diagnostics.push({
+        checkId: "TF043",
+        severity: "warning",
+        message:
+          `The \`terraform\` block in ${block.file} sources "${source}" with no version, so a push or a release changes the unit with no diff to review. ` +
+          FIX[classified.kind],
+        entity: block.key,
+        lexicon: "terraform",
+      });
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/tf044.ts

@@ -0,0 +1,51 @@
+/**
+ * TF044: a Terragrunt config keeps state in a local backend.
+ *
+ * Read from `remote_state { backend = "local" }` and from a `generate` block
+ * whose `contents` declare `backend "local"`. State on the runner's disk is
+ * gone when the job ends, a second job cannot read what the first applied, and
+ * a git-range run, which checks out each side in a temporary directory, never
+ * sees state at all. A shared backend (S3, GCS, azurerm, a Terraform HTTP
+ * backend) holds it.
+ *
+ * A backend named by an expression is not determined and passes. A local
+ * backend is sometimes right for a throwaway sandbox; suppress the rule there
+ * with `# chant-ignore TF044`.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { TERRAGRUNT_GENERATE_TYPE, TERRAGRUNT_REMOTE_STATE_TYPE } from "../../hcl/parse";
+import { terragruntEntities } from "./terragrunt";
+
+const LOCAL_BACKEND_BLOCK = /\bbackend\s+"local"/;
+
+export const tf044: PostSynthCheck = {
+  id: "TF044",
+  description: "Terragrunt config keeps state in a local backend",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const report = (key: string, file: string, how: string): void => {
+      diagnostics.push({
+        checkId: "TF044",
+        severity: "warning",
+        message:
+          `${how} in ${file} keeps state in a local backend. The state lives on the runner's disk, so a later job cannot read it ` +
+          "and a git-range run, which checks out each side in a temporary directory, never sees it. Use a shared backend such as S3 or GCS.",
+        entity: key,
+        lexicon: "terraform",
+      });
+    };
+
+    for (const block of terragruntEntities(ctx.entities, TERRAGRUNT_REMOTE_STATE_TYPE)) {
+      if (block.body.backend === "local") report(block.key, block.file, "`remote_state` sets `backend = \"local\"`");
+    }
+    for (const block of terragruntEntities(ctx.entities, TERRAGRUNT_GENERATE_TYPE)) {
+      const contents = block.body.contents;
+      if (typeof contents === "string" && LOCAL_BACKEND_BLOCK.test(contents)) {
+        report(block.key, block.file, `\`generate "${block.address.replace(/^generate\./, "")}"\` writes a \`backend "local"\` block`);
+      }
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/tf045.ts

@@ -0,0 +1,47 @@
+/**
+ * TF045: no Terragrunt config sets `terragrunt_version_constraint`.
+ *
+ * The attribute makes Terragrunt refuse to run on a release outside the range.
+ * Without it each machine and each CI image runs whatever Terragrunt it
+ * installed, and a behaviour change between releases reaches a plan with no
+ * diff. It is usually set once, in the root config every unit includes.
+ *
+ * The rule looks at the whole set of configs in the scan and reports once. It
+ * reports only when the set holds a config that includes no other file (the
+ * root config, or a self-contained unit) and none of the configs sets the
+ * attribute. A set made only of units that include a parent it did not read,
+ * such as one unit directory passed alone, is not determined: the parent may
+ * set it. The finding is anchored on `root.hcl` when the set has one.
+ *
+ * Off by default: the `report-only` tier keeps it out of the `recommended`
+ * preset, since many repos pin Terragrunt in the toolchain (`.tool-versions`,
+ * a CI image) rather than in config.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { TERRAGRUNT_CONFIG_TYPE } from "../../hcl/parse";
+import { terragruntEntities } from "./terragrunt";
+
+export const tf045: PostSynthCheck = {
+  id: "TF045",
+  description: "No Terragrunt config sets terragrunt_version_constraint",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const configs = terragruntEntities(ctx.entities, TERRAGRUNT_CONFIG_TYPE);
+    if (configs.some((c) => c.body.terragrunt_version_constraint !== undefined)) return [];
+    const tops = configs.filter((c) => Array.isArray(c.body.includes) && c.body.includes.length === 0);
+    if (tops.length === 0) return [];
+    const anchor = [...tops].sort((a, b) => Number(b.file === "root.hcl") - Number(a.file === "root.hcl") || a.key.localeCompare(b.key))[0];
+    return [
+      {
+        checkId: "TF045",
+        severity: "warning",
+        message:
+          `No Terragrunt config sets \`terragrunt_version_constraint\` (${anchor.file} is the top config read). ` +
+          'Set it once in the root config, for example `terragrunt_version_constraint = ">= 1.1.0"`, so every machine runs a release the repo was tested with.',
+        entity: anchor.key,
+        lexicon: "terraform",
+      },
+    ];
+  },
+};