@intentius/chant-lexicon-terraform 0.102.0 → 0.104.0

package/src/index.ts

@@ -1,6 +1,18 @@
 // Plugin
 export { terraformPlugin } from "./plugin";
 
+// The `terraform-apply` component verb (#3049), contributed to core's
+// capability-plugin seam. Core loads `terraformCapabilityPlugin` when a
+// project's chant.config lists this lexicon, so a component can deploy a root
+// and a fan-out can run many of them in gated waves.
+export {
+  terraformCapabilityPlugin,
+  terraformApplyCapability,
+  TERRAFORM_VERB_FAMILIES,
+  type TerraformApplyStepInput,
+  type TerraformApplyStepOutput,
+} from "./components/capability-plugin";
+
 // Serializer
 export { terraformSerializer } from "./serializer";
 
@@ -55,6 +67,7 @@ export {
   choudoufuLiveLs,
   choudoufuLiveCheck,
   choudoufuAdopt,
+  terraformPinRollout,
 } from "./op/builders";
 
 // The adoption ledger over `live-plan -json`'s document (#2105). Pure, and
@@ -90,6 +103,11 @@ export type {
 export { TerraformAdoptOp } from "./composites/terraform-adopt-op";
 export type { TerraformAdoptOpConfig, TerraformAdoptOpResources } from "./composites/terraform-adopt-op";
 
+// One pin-bump PR per wave (#3189). The pin edit, wave plan and rollout run
+// are in the `@intentius/chant-lexicon-terraform/pin` subpath.
+export { TerraformPinRolloutOp } from "./composites/terraform-pin-rollout-op";
+export type { TerraformPinRolloutOpConfig, TerraformPinRolloutOpResources } from "./composites/terraform-pin-rollout-op";
+
 // Live observation over `terraform show -json` (#2087). The plugin reaches
 // `describeResources` through a dynamic import; the ownership keys are here
 // because `ownershipChannel` declares them eagerly.

package/src/lint/audit-catalog.ts

@@ -469,6 +469,88 @@ export const terraformAuditCatalog: Record<string, RuleMeta> = {
     authority: [AWS_ECR_TAG_IMMUTABILITY],
     yamlBased: false,
   },
+  TF038: {
+    id: "TF038",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "OCI module source has no tag or digest, or a mutable tag",
+    remediation:
+      "Pin the `oci://` source with `?digest=sha256:...` (a digest cannot move) or an exact version tag " +
+      "(`?tag=1.4.0`). A source with no tag pulls `latest`.",
+    yamlBased: false,
+  },
+  TF039: {
+    id: "TF039",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "best-practice",
+    title: "Registry module version is a range, not an exact version",
+    remediation: 'Set an exact `version` (`version = "1.4.0"`) for projects that pin modules. Off by default.',
+    yamlBased: false,
+  },
+  TF040: {
+    id: "TF040",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "best-practice",
+    title: "Root has no committed .terraform.lock.hcl",
+    remediation:
+      "Run `terraform init` in the root and commit the `.terraform.lock.hcl` it writes. Off by default; " +
+      "checked only where the root's directory is known.",
+    yamlBased: false,
+  },
+  TF041: {
+    id: "TF041",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Terragrunt dependency lets mock_outputs stand in for apply",
+    remediation:
+      'Set `mock_outputs_allowed_terraform_commands = ["validate", "plan"]` on every `dependency` that sets `mock_outputs`. ' +
+      "Terragrunt reads a missing or empty list as every command, apply included.",
+    yamlBased: false,
+  },
+  TF042: {
+    id: "TF042",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Terragrunt dependency sets skip_outputs together with mock_outputs",
+    remediation:
+      "Drop `skip_outputs`, or pass the values as `inputs`. With `skip_outputs = true` the upstream outputs are never read, so every run uses the mocks.",
+    yamlBased: false,
+  },
+  TF043: {
+    id: "TF043",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Terragrunt terraform.source names no version (git ref, tfr version or oci tag)",
+    remediation:
+      "Pin the source: `?ref=` for git, `?version=` for `tfr://`, `?digest=` or `?tag=` for `oci://`.",
+    yamlBased: false,
+  },
+  TF044: {
+    id: "TF044",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Terragrunt config keeps state in a local backend",
+    remediation:
+      'Use a shared backend (S3, GCS) in `remote_state`. State written by `backend = "local"` stays on the runner and is lost with it.',
+    yamlBased: false,
+  },
+  TF045: {
+    id: "TF045",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "best-practice",
+    title: "No Terragrunt config sets terragrunt_version_constraint",
+    remediation:
+      'Set `terragrunt_version_constraint = ">= 1.1.0"` in the root config. Off by default; judged only across the configs scanned.',
+    yamlBased: false,
+  },
 };
 
 // Prior art credits, if any, live beside the rules in ./audit-lineage.ts (see

package/src/lint/audit.test.ts

@@ -208,7 +208,9 @@ describe("every fixture root gets the same verdict from chant audit as from chan
       entities,
       buildResult: { outputs: new Map(), entities, warnings, errors: [], sourceFileCount: entities.size },
     } as unknown as PostSynthContext;
-    return verdictOf((terraformPlugin.postSynthChecks?.() ?? []).flatMap((check) => check.check(ctx)));
+    // An `auditOptIn` check (TF040, #3190) is the one place the audit is meant to
+    // differ from the unfiltered build: it needs `lint.rules` there.
+    return verdictOf((terraformPlugin.postSynthChecks?.() ?? []).filter((check) => !check.auditOptIn).flatMap((check) => check.check(ctx)));
   }
 
   async function auditVerdict(dir: string): Promise<string[]> {

package/src/lint/post-synth/fixtures/TF038/positive.tf

@@ -0,0 +1,3 @@
+module "network" {
+  source = "oci://registry.example.com/platform/network"
+}

package/src/lint/post-synth/fixtures/TF039/positive.tf

@@ -0,0 +1,4 @@
+module "vpc" {
+  source  = "terraform-aws-modules/vpc/aws"
+  version = "~> 5.0"
+}

package/src/lint/post-synth/fixtures/TF041/negative/terragrunt.hcl

@@ -0,0 +1,12 @@
+dependency "vpc" {
+  config_path = "../vpc"
+
+  mock_outputs = {
+    vpc_id = "vpc-00000000"
+  }
+  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
+}
+
+dependency "db" {
+  config_path = "../db"
+}

package/src/lint/post-synth/fixtures/TF041/positive/terragrunt.hcl

@@ -0,0 +1,7 @@
+dependency "vpc" {
+  config_path = "../vpc"
+
+  mock_outputs = {
+    vpc_id = "vpc-00000000"
+  }
+}

package/src/lint/post-synth/fixtures/TF041/positive-apply/terragrunt.hcl

@@ -0,0 +1,8 @@
+dependency "vpc" {
+  config_path = "../vpc"
+
+  mock_outputs = {
+    vpc_id = "vpc-00000000"
+  }
+  mock_outputs_allowed_terraform_commands = ["validate", "plan", "apply"]
+}

package/src/lint/post-synth/fixtures/TF042/negative/terragrunt.hcl

@@ -0,0 +1,13 @@
+dependency "vpc" {
+  config_path  = "../vpc"
+  skip_outputs = true
+}
+
+dependency "db" {
+  config_path  = "../db"
+  skip_outputs = false
+
+  mock_outputs = {
+    endpoint = "db.example.com"
+  }
+}

package/src/lint/post-synth/fixtures/TF042/positive/terragrunt.hcl

@@ -0,0 +1,9 @@
+dependency "vpc" {
+  config_path = "../vpc"
+  skip_outputs = true
+
+  mock_outputs = {
+    vpc_id = "vpc-00000000"
+  }
+  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
+}

package/src/lint/post-synth/fixtures/TF043/negative/terragrunt.hcl

@@ -0,0 +1,3 @@
+terraform {
+  source = "git::https://github.com/example/modules.git//vpc?ref=v1.4.0"
+}

package/src/lint/post-synth/fixtures/TF043/negative-other/terragrunt.hcl

@@ -0,0 +1,3 @@
+terraform {
+  source = "${get_repo_root()}/modules/vpc"
+}

package/src/lint/post-synth/fixtures/TF043/positive-git/terragrunt.hcl

@@ -0,0 +1,3 @@
+terraform {
+  source = "git::https://github.com/example/modules.git//vpc"
+}

package/src/lint/post-synth/fixtures/TF043/positive-oci/terragrunt.hcl

@@ -0,0 +1,3 @@
+terraform {
+  source = "oci://registry.example.com/platform/vpc"
+}

package/src/lint/post-synth/fixtures/TF043/positive-tfr/terragrunt.hcl

@@ -0,0 +1,3 @@
+terraform {
+  source = "tfr:///terraform-aws-modules/vpc/aws"
+}

package/src/lint/post-synth/fixtures/TF044/negative/terragrunt.hcl

@@ -0,0 +1,9 @@
+remote_state {
+  backend = "s3"
+
+  config = {
+    bucket = "example-tfstate"
+    key    = "${path_relative_to_include()}/terraform.tfstate"
+    region = "us-east-1"
+  }
+}

package/src/lint/post-synth/fixtures/TF044/positive/terragrunt.hcl

@@ -0,0 +1,7 @@
+remote_state {
+  backend = "local"
+
+  config = {
+    path = "${get_parent_terragrunt_dir()}/.state/${path_relative_to_include()}/terraform.tfstate"
+  }
+}

package/src/lint/post-synth/fixtures/TF044/positive-generate/terragrunt.hcl

@@ -0,0 +1,9 @@
+generate "backend" {
+  path      = "backend.tf"
+  if_exists = "overwrite"
+  contents  = <<-EOT
+    terraform {
+      backend "local" {}
+    }
+  EOT
+}

package/src/lint/post-synth/fixtures/TF045/negative/root.hcl

@@ -0,0 +1 @@
+terragrunt_version_constraint = ">= 1.1.0"

package/src/lint/post-synth/fixtures/TF045/negative/terragrunt.hcl

@@ -0,0 +1,3 @@
+include "root" {
+  path = find_in_parent_folders("root.hcl")
+}

package/src/lint/post-synth/fixtures/TF045/positive/root.hcl

@@ -0,0 +1,9 @@
+remote_state {
+  backend = "s3"
+
+  config = {
+    bucket = "example-tfstate"
+    key    = "${path_relative_to_include()}/terraform.tfstate"
+    region = "us-east-1"
+  }
+}

package/src/lint/post-synth/fixtures/TF045/positive/terragrunt.hcl

@@ -0,0 +1,3 @@
+include "root" {
+  path = find_in_parent_folders("root.hcl")
+}

package/src/lint/post-synth/fixtures/TF045/unit-only/terragrunt.hcl

@@ -0,0 +1,3 @@
+include "root" {
+  path = find_in_parent_folders("root.hcl")
+}

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

@@ -36,6 +36,14 @@ import { tf034 } from "./tf034";
 import { tf035 } from "./tf035";
 import { tf036 } from "./tf036";
 import { tf037 } from "./tf037";
+import { tf038 } from "./tf038";
+import { tf039 } from "./tf039";
+import { tf040 } from "./tf040";
+import { tf041 } from "./tf041";
+import { tf042 } from "./tf042";
+import { tf043 } from "./tf043";
+import { tf044 } from "./tf044";
+import { tf045 } from "./tf045";
 
 export const postSynthChecks: PostSynthCheck[] = [
   tf001,
@@ -74,4 +82,12 @@ export const postSynthChecks: PostSynthCheck[] = [
   tf035,
   tf036,
   tf037,
+  tf038,
+  tf039,
+  tf040,
+  tf041,
+  tf042,
+  tf043,
+  tf044,
+  tf045,
 ];

package/src/lint/post-synth/module-source.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { classifyModuleSource, isDefaultBranch, isPinnedRef } from "./module-source";
+import { classifyModuleSource, isDefaultBranch, isExactVersionConstraint, isMutableOciTag, isPinnedRef } from "./module-source";
 
 describe("classifyModuleSource", () => {
   test("local paths", () => {
@@ -73,3 +73,44 @@ describe("isDefaultBranch", () => {
     expect(isDefaultBranch("some-feature")).toBe(false);
   });
 });
+
+describe("classifyModuleSource: oci sources (#3190)", () => {
+  const cases: Array<[string, string, string | undefined, string | undefined]> = [
+    ["tag query", "oci://example.com/org/mod?tag=v1.4.0", "v1.4.0", undefined],
+    ["digest query", "oci://example.com/org/mod?digest=sha256:abc123", undefined, "sha256:abc123"],
+    ["tag suffix", "oci://example.com/org/mod:1.4.0", "1.4.0", undefined],
+    ["digest suffix", "oci://example.com/org/mod@sha256:abc123", undefined, "sha256:abc123"],
+    ["tag and digest suffix", "oci://example.com/org/mod:1.4.0@sha256:abc123", "1.4.0", "sha256:abc123"],
+    ["tag and digest query", "oci://example.com/org/mod?tag=1.4.0&digest=sha256:abc123", "1.4.0", "sha256:abc123"],
+    ["neither", "oci://example.com/org/mod", undefined, undefined],
+    ["host with a port, no tag", "oci://registry.example.com:5000/org/mod", undefined, undefined],
+    ["host with a port and a tag", "oci://registry.example.com:5000/org/mod:2.0.1", "2.0.1", undefined],
+    ["host with a port and a digest", "oci://registry.example.com:5000/org/mod@sha256:def", undefined, "sha256:def"],
+    ["subdirectory before the query", "oci://example.com/org/mod//modules/vpc?tag=v1.0.0", "v1.0.0", undefined],
+    ["subdirectory, no pin", "oci://example.com/org/mod//modules/vpc", undefined, undefined],
+  ];
+
+  test.each(cases)("%s", (_name, source, tag, digest) => {
+    const c = classifyModuleSource(source);
+    expect(c.kind).toBe("oci");
+    expect(c.tag).toBe(tag);
+    expect(c.digest).toBe(digest);
+  });
+});
+
+describe("isMutableOciTag", () => {
+  test("names that move are mutable, versions are not", () => {
+    expect(isMutableOciTag("latest")).toBe(true);
+    expect(isMutableOciTag("LATEST")).toBe(true);
+    expect(isMutableOciTag("main")).toBe(true);
+    expect(isMutableOciTag("1.4.0")).toBe(false);
+    expect(isMutableOciTag("v1.4.0")).toBe(false);
+  });
+});
+
+describe("isExactVersionConstraint", () => {
+  test.each([["1.4.0", true], ["= 1.4.0", true], ["=1.4.0", true], ["1.4.0-rc1", true], ["~> 1.4", false], [">= 1.4", false], [">= 1.0, < 2.0", false], ["!= 1.4.0", false], ["< 2", false]])(
+    "%s",
+    (v, exact) => expect(isExactVersionConstraint(v as string)).toBe(exact),
+  );
+});

package/src/lint/post-synth/module-source.ts

@@ -18,14 +18,27 @@
  * recognize, scp-style `git@host:path` addresses, and any source ending in
  * `.git`. `local` is `./` or `../` (checkov's `UNKNOWN` case for module
  * pinning: a local path cannot be pinned to anything and is never flagged).
+ * `oci` is an OpenTofu `oci://host/repo` source (#3190). OpenTofu selects a
+ * version with `?tag=` or `?digest=` (https://opentofu.org/docs/language/modules/sources/),
+ * and a source naming neither resolves the `latest` tag. The container-image
+ * shapes `repo:tag` and `repo@sha256:...` are read too, so a source written
+ * the way `docker pull` spells it is not misread as unpinned. A `:` inside the
+ * host (a registry port) is never a tag: only a colon in the last path
+ * segment is. The tag and digest rules were checked against the docs page
+ * above; the suffix forms are not documented there and are not verified
+ * against OpenTofu's parser.
  */
 
-export type ModuleSourceKind = "local" | "registry" | "git" | "other";
+export type ModuleSourceKind = "local" | "registry" | "git" | "oci" | "other";
 
 export interface ModuleSourceClassification {
   kind: ModuleSourceKind;
   /** The `?ref=`/`&ref=` value (falling back to `rev`), when `kind` is `"git"`. */
   ref?: string;
+  /** The tag an `oci://` source names, from `?tag=` or a `:tag` suffix on the repository. */
+  tag?: string;
+  /** The digest an `oci://` source names, from `?digest=` or an `@sha256:...` suffix. */
+  digest?: string;
 }
 
 const REGISTRY_NAME = /^[0-9A-Za-z](?:[0-9A-Za-z_-]{0,62}[0-9A-Za-z])?$/;
@@ -77,6 +90,25 @@ function isGitShaped(rest: string): boolean {
   return false;
 }
 
+function classifyOci(base: string, query: string): ModuleSourceClassification {
+  const params = parseQuery(query);
+  let path = stripSubdir(base).replace(/^oci:\/\//i, "");
+  let tag = params.get("tag") || undefined;
+  let digest = params.get("digest") || undefined;
+
+  const at = path.indexOf("@");
+  if (at !== -1) {
+    digest = digest ?? (path.slice(at + 1) || undefined);
+    path = path.slice(0, at);
+  }
+  const lastSlash = path.lastIndexOf("/");
+  const colon = path.indexOf(":", lastSlash + 1); // a port sits before the first slash
+  if (colon !== -1) {
+    tag = tag ?? (path.slice(colon + 1) || undefined);
+  }
+  return { kind: "oci", ...(tag !== undefined ? { tag } : {}), ...(digest !== undefined ? { digest } : {}) };
+}
+
 export function classifyModuleSource(source: string): ModuleSourceClassification {
   const trimmed = source.trim();
   if (trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith(".\\") || trimmed.startsWith("..\\")) {
@@ -87,6 +119,8 @@ export function classifyModuleSource(source: string): ModuleSourceClassification
   const base = queryIdx === -1 ? trimmed : trimmed.slice(0, queryIdx);
   const query = queryIdx === -1 ? "" : trimmed.slice(queryIdx + 1);
 
+  if (/^oci:\/\//i.test(base)) return classifyOci(base, query);
+
   const forced = /^(git|hg)::/i.exec(base);
   const rest = forced ? base.slice(forced[0].length) : base;
 
@@ -119,3 +153,24 @@ export function isPinnedRef(ref: string): boolean {
 export function isDefaultBranch(ref: string): boolean {
   return DEFAULT_BRANCHES.has(ref);
 }
+
+const MUTABLE_TAGS = new Set(["latest", "main", "master", "develop", "dev", "stable", "edge", "nightly"]);
+
+/**
+ * Is `tag` a name that conventionally moves (`latest`, a branch-like name)
+ * rather than an exact version. Used by TF038. A tag is a mutable pointer in
+ * most registries whatever it looks like, so the rule is a warning and this
+ * only decides what reads as obviously floating.
+ */
+export function isMutableOciTag(tag: string): boolean {
+  return MUTABLE_TAGS.has(tag.toLowerCase());
+}
+
+/**
+ * Is a registry `version` constraint an exact version (`1.4.0`, `= 1.4.0`,
+ * `=1.4.0`) rather than a range (`~> 1.4`, `>= 1.4`, `>= 1.0, < 2.0`). Used
+ * by TF039. A bare version is an exact constraint in Terraform.
+ */
+export function isExactVersionConstraint(version: string): boolean {
+  return /^(?:=\s*)?v?\d+(?:\.\d+){0,2}(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version.trim()) && !version.includes(",");
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Shared reading for the Terragrunt rules TF041 to TF045 (#3417).
+ *
+ * These rules look at `terragrunt.hcl` and `root.hcl`, which the parse reads
+ * into their own entity types (`TERRAGRUNT_*_TYPE` in `../../hcl/parse.ts`)
+ * and never into the module types the other TF rules check. Like the module
+ * source rules, they read the literal values hcl2json hands back: an
+ * attribute built from a function or a `local.` reference arrives as a
+ * `"${...}"` string and is treated as not determined, never as a finding.
+ */
+
+import { isResourceDeclarable, type Declarable } from "@intentius/chant/declarable";
+import type { BlockBody } from "../../hcl/parse";
+import { classifyModuleSource } from "./module-source";
+
+/** Entities of one Terragrunt type, with their keys, in map order. */
+export function terragruntEntities(
+  entities: ReadonlyMap<string, Declarable>,
+  entityType: string,
+): Array<{ key: string; address: string; file: string; body: BlockBody }> {
+  const out: Array<{ key: string; address: string; file: string; body: BlockBody }> = [];
+  for (const [key, entity] of entities) {
+    if (entity.entityType !== entityType || !isResourceDeclarable(entity)) continue;
+    const props = entity.props as { address?: unknown; file?: unknown; body?: unknown };
+    out.push({
+      key,
+      address: typeof props.address === "string" ? props.address : key,
+      file: typeof props.file === "string" ? props.file : "terragrunt.hcl",
+      body: (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody,
+    });
+  }
+  return out;
+}
+
+/** An HCL expression hcl2json left as `"${...}"`: its value is not known without evaluating it. */
+export function isExpression(value: unknown): boolean {
+  return typeof value === "string" && value.includes("${");
+}
+
+export type TerragruntSourceKind = "local" | "git" | "tfr" | "oci" | "other";
+
+export interface TerragruntSourceClassification {
+  kind: TerragruntSourceKind;
+  /** Whether the source names a version: `?ref=` for git, `?version=` for `tfr://`, a tag or digest for `oci://`. Undefined for `local` and `other`. */
+  pinned?: boolean;
+}
+
+/**
+ * Classify a unit's `terraform.source`. Git and `oci://` sources go through
+ * {@link classifyModuleSource}, the reader TF005 and TF038 use. `tfr://` is
+ * Terragrunt's own scheme for registry modules and takes its version from the
+ * `?version=` query argument. A source that holds an interpolation, or that
+ * names an absolute path or an archive URL, is `other` or `local` and is
+ * never reported.
+ */
+export function classifyTerragruntSource(source: string): TerragruntSourceClassification {
+  const trimmed = source.trim();
+  if (trimmed.includes("${")) return { kind: "other" };
+  if (/^tfr:\/\//i.test(trimmed)) {
+    const query = trimmed.includes("?") ? trimmed.slice(trimmed.indexOf("?") + 1) : "";
+    const version = new URLSearchParams(query).get("version");
+    return { kind: "tfr", pinned: version !== null && version.trim() !== "" };
+  }
+  if (trimmed.startsWith("/")) return { kind: "local" };
+  const classified = classifyModuleSource(trimmed);
+  switch (classified.kind) {
+    case "local":
+      return { kind: "local" };
+    case "git":
+      return { kind: "git", pinned: classified.ref !== undefined };
+    case "oci":
+      return { kind: "oci", pinned: classified.tag !== undefined || classified.digest !== undefined };
+    default:
+      return { kind: "other" };
+  }
+}

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

@@ -51,7 +51,7 @@ function providerNameFromType(type: string): string {
 }
 
 /** 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> {
+export function impliedProviders(entities: PostSynthContext["entities"], root: string): Map<string, string> {
   const implied = new Map<string, string>();
   const fromProviderBlock = new Set<string>();
 

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

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { blocksToEntities } from "../../hcl/parse";
+import { loadFixture } from "./fixtures/load";
+import { tf038 } from "./tf038";
+
+async function withSource(source: string): Promise<PostSynthContext> {
+  const hcl = `module "m" {\n  source = ${JSON.stringify(source)}\n}\n`;
+  const entities = await blocksToEntities([{ name: "main.tf", source: hcl }], "app");
+  return { outputs: new Map(), entities } as unknown as PostSynthContext;
+}
+
+describe("TF038: OCI module source with no tag or digest, or a mutable tag", () => {
+  test("flags the documented positive fixture", async () => {
+    expect(tf038.check(await loadFixture("TF038", "positive"))).toHaveLength(1);
+  });
+
+  test("check metadata", () => {
+    expect(tf038.id).toBe("TF038");
+  });
+
+  test.each([
+    ["no tag or digest", "oci://example.com/org/mod"],
+    ["no tag, registry host with a port", "oci://registry.example.com:5000/org/mod"],
+    ["latest as a query tag", "oci://example.com/org/mod?tag=latest"],
+    ["latest as a suffix tag", "oci://example.com/org/mod:latest"],
+    ["no pin, with a subdirectory", "oci://example.com/org/mod//modules/vpc"],
+  ])("flags %s", async (_n, source) => {
+    const diags = tf038.check(await withSource(source));
+    expect(diags).toHaveLength(1);
+    expect(diags[0]).toMatchObject({ checkId: "TF038", severity: "warning", entity: "app/module.m", lexicon: "terraform" });
+    expect(diags[0].message).toContain(source);
+  });
+
+  test.each([
+    ["an exact tag", "oci://example.com/org/mod?tag=1.4.0"],
+    ["an exact suffix tag", "oci://example.com/org/mod:v1.4.0"],
+    ["a digest", "oci://example.com/org/mod?digest=sha256:abc123"],
+    ["a suffix digest", "oci://example.com/org/mod@sha256:abc123"],
+    ["a digest beside latest", "oci://example.com/org/mod:latest@sha256:abc123"],
+    ["a tag on a host with a port", "oci://registry.example.com:5000/org/mod:1.4.0"],
+  ])("passes %s", async (_n, source) => {
+    expect(tf038.check(await withSource(source))).toEqual([]);
+  });
+
+  test("ignores a registry, git and local source", async () => {
+    for (const s of ["terraform-aws-modules/vpc/aws", "git::https://example.com/vpc.git", "./modules/x"]) {
+      expect(tf038.check(await withSource(s))).toEqual([]);
+    }
+  });
+});