@intentius/chant-lexicon-terraform 0.57.0 → 0.59.0

package/src/lint/post-synth/fixtures/load.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared post-synth fixture loader.
+ *
+ * KICS lays its own query fixtures out as `positive.tf`/`negative.tf` pairs
+ * beside the query that tests them (survey, #2107): every query is
+ * externally auditable because a rule and its evidence live in the same
+ * directory. This lexicon adopts that layout: `fixtures/<id>/positive.tf`
+ * triggers the check, `fixtures/<id>/negative.tf` does not, and a rule with
+ * more than one triggering condition adds `positive-<case>.tf` beside them.
+ *
+ * KICS itself scans a whole fixture directory in one pass and tells its
+ * fixtures apart by the file each finding came from. That doesn't transfer
+ * here: TF001 (and most post-synth checks with per-root state, not
+ * per-resource) fire once per *root*, deduplicated by root name, so parsing
+ * `positive.tf` and `negative.tf` together as one root would let whichever
+ * file's terraform block is read first decide the outcome for both, silently
+ * discarding the other. `loadFixture` therefore reads exactly the one named
+ * file and parses it alone, through the same `blocksToEntities` pass
+ * `parseTerraformRootDir` wraps for a real root directory, so sibling
+ * fixtures never mix into one build.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { blocksToEntities } from "../../../hcl/parse";
+import type { CallModuleType } from "../../../hcl/descend";
+import { renderTerraformRoots } from "../../../hcl/roots";
+
+const FIXTURES_DIR = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Parse `fixtures/<checkId>/<name>.tf` into a {@link PostSynthContext} whose
+ * `entities` are exactly what a real root module of that one file would
+ * produce. `root` (the entity key prefix and the `TerraformEntity.props.root`
+ * value) defaults to `checkId`; pass a distinct value to load two fixtures
+ * into one context under different root names.
+ *
+ * Three lines per fixture in a test:
+ * ```ts
+ * const diags = tf001.check(await loadFixture("TF001", "positive"));
+ * expect(diags).toHaveLength(1);
+ * ```
+ */
+export async function loadFixture(
+  checkId: string,
+  name: string,
+  root: string = checkId,
+): Promise<PostSynthContext> {
+  const file = `${name}.tf`;
+  const source = readFileSync(join(FIXTURES_DIR, checkId, file), "utf-8");
+  const entities = await blocksToEntities([{ name: file, source }], root);
+  return {
+    outputs: new Map(),
+    entities,
+    buildResult: {
+      outputs: new Map(),
+      entities,
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+/**
+ * Parse a whole fixture DIRECTORY, `fixtures/<checkId>/<name>/`, the way
+ * `buildRoots()` parses a configured root: its own `.tf` files, then every
+ * local `module` call followed into its directory (chant #2112). A rule about
+ * child modules (TF014, TF015) or about a whole scope's references (TF020)
+ * cannot be shown a single file and still be tested honestly, so its fixture
+ * is a tree:
+ *
+ * ```
+ * fixtures/TF014/positive/main.tf                     # module "cdn" { source = "./modules/cdn" }
+ * fixtures/TF014/positive/modules/cdn/main.tf         # the provider block the rule reports
+ * ```
+ *
+ * The fixture directory is also the project root for the descent, so a
+ * fixture can exercise the outside-the-project refusal with a `../` source
+ * without reaching into the repository around it. `warnings` from the render
+ * lands on `buildResult.warnings`, where the descent's own refusals are
+ * readable by a test.
+ */
+export async function loadTreeFixture(
+  checkId: string,
+  name: string,
+  root: string = checkId,
+  callModuleType?: CallModuleType,
+): Promise<PostSynthContext> {
+  const dir = join(FIXTURES_DIR, checkId, name);
+  const { entities, warnings } = await renderTerraformRoots({
+    projectRoot: dir,
+    roots: { [root]: { dir } },
+    ...(callModuleType ? { callModuleType } : {}),
+  });
+  return {
+    outputs: new Map(),
+    entities,
+    buildResult: {
+      outputs: new Map(),
+      entities,
+      warnings,
+      errors: [],
+      sourceFileCount: entities.size,
+    },
+  };
+}

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

@@ -1,7 +1,59 @@
 // Code generated by chant generate. DO NOT EDIT.
 import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
 import { tf001 } from "./tf001";
+import { tf002 } from "./tf002";
+import { tf003 } from "./tf003";
+import { tf004 } from "./tf004";
+import { tf005 } from "./tf005";
+import { tf006 } from "./tf006";
+import { tf007 } from "./tf007";
+import { tf008 } from "./tf008";
+import { tf009 } from "./tf009";
+import { tf010 } from "./tf010";
+import { tf011 } from "./tf011";
+import { tf012 } from "./tf012";
+import { tf013 } from "./tf013";
+import { tf014 } from "./tf014";
+import { tf015 } from "./tf015";
+import { tf016 } from "./tf016";
+import { tf017 } from "./tf017";
+import { tf018 } from "./tf018";
+import { tf019 } from "./tf019";
+import { tf020 } from "./tf020";
+import { tf021 } from "./tf021";
+import { tf022 } from "./tf022";
+import { tf024 } from "./tf024";
+import { tf025 } from "./tf025";
+import { tf026 } from "./tf026";
+import { tf027 } from "./tf027";
+import { tf028 } from "./tf028";
 
 export const postSynthChecks: PostSynthCheck[] = [
   tf001,
+  tf002,
+  tf003,
+  tf004,
+  tf005,
+  tf006,
+  tf007,
+  tf008,
+  tf009,
+  tf010,
+  tf011,
+  tf012,
+  tf013,
+  tf014,
+  tf015,
+  tf016,
+  tf017,
+  tf018,
+  tf019,
+  tf020,
+  tf021,
+  tf022,
+  tf024,
+  tf025,
+  tf026,
+  tf027,
+  tf028,
 ];

package/src/lint/post-synth/live-refusals-config-format.test.ts

@@ -0,0 +1,143 @@
+/**
+ * The two live-root refusals against both config file formats (#2216).
+ *
+ * `TerraformApplyOp` and `TerraformWatchOp` each resolve a root's mode
+ * synchronously when they are built, and `resolveRootModeSync` reads a
+ * `chant.config.json` and nothing else: a `chant.config.ts` is project-
+ * authored code it will not evaluate. Every project in this repository is on
+ * a `chant.config.ts`, so a refusal that lives only in a composite has never
+ * fired for anyone. TF027 and TF028 read the mode the build stamps onto the
+ * parsed HCL instead, which is the same either way, and these tests
+ * materialise one project in each format to prove it.
+ *
+ * The build path here is the plugin's own `buildRoots` hook (what `chant
+ * build` calls to turn `terraform.roots` into entities) followed by the
+ * checks the plugin contributes, so the entities under test are the ones a
+ * real build produces rather than a hand-assembled map.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { terraformPlugin } from "../../plugin";
+import { TerraformApplyOp } from "../../composites/terraform-apply-op";
+import { TerraformWatchOp } from "../../composites/terraform-watch-op";
+
+const UNTAGGED_DELETE_ROOT = `terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "prod-estate"
+
+    policy {
+      undeclared_untagged = "delete"
+    }
+  }
+}
+
+resource "null_resource" "first" {}
+`;
+
+const LIVE_ROOT = `terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "prod-estate"
+  }
+}
+
+resource "null_resource" "first" {}
+`;
+
+const CONFIG = {
+  lexicons: ["terraform"],
+  terraform: { binary: "choudoufu", roots: { estate: { dir: "./estate" } } },
+};
+
+const dirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+/** A project whose one root is `mainTf`, its config written in `format`. */
+function project(format: "ts" | "json", mainTf: string): string {
+  const dir = mkdtempSync(join(tmpdir(), `chant-tf-2216-${format}-`));
+  dirs.push(dir);
+  mkdirSync(join(dir, "estate"), { recursive: true });
+  writeFileSync(join(dir, "estate", "main.tf"), mainTf);
+  writeFileSync(
+    join(dir, `chant.config.${format}`),
+    format === "json"
+      ? JSON.stringify(CONFIG, null, 2)
+      : `import type { ChantConfig } from "@intentius/chant/config";\n\nexport default ${JSON.stringify(CONFIG, null, 2)} satisfies ChantConfig;\n`,
+  );
+  return dir;
+}
+
+/** `chant build`'s own path: the plugin's `buildRoots`, then the checks it contributes. */
+async function checkProject(dir: string, ops: Map<string, Declarable> = new Map()): Promise<PostSynthDiagnostic[]> {
+  const { entities } = await terraformPlugin.buildRoots!({ projectRoot: dir, config: CONFIG, entities: new Map() });
+  for (const [name, op] of ops) entities.set(name, op);
+  const ctx = { outputs: new Map(), entities } as unknown as PostSynthContext;
+  return (terraformPlugin.postSynthChecks?.() ?? []).flatMap((check) => check.check(ctx));
+}
+
+describe('TF027 fires on undeclared_untagged = "delete" whatever the config format (#2216)', () => {
+  for (const format of ["ts", "json"] as const) {
+    test(`chant.config.${format}: the build reports the root and the setting`, async () => {
+      const diags = await checkProject(project(format, UNTAGGED_DELETE_ROOT));
+      const tf027 = diags.filter((d) => d.checkId === "TF027");
+      expect(tf027).toHaveLength(1);
+      expect(tf027[0].severity).toBe("error");
+      expect(tf027[0].message).toContain('Root module "estate"');
+      expect(tf027[0].message).toContain('undeclared_untagged = "delete"');
+    });
+  }
+
+  test("the same project with no such policy setting is clean", async () => {
+    const diags = await checkProject(project("ts", LIVE_ROOT));
+    expect(diags.filter((d) => d.checkId === "TF027")).toEqual([]);
+  });
+
+  test("the composite's own refusal fires only on the format it can read, which is why the check exists", () => {
+    const json = project("json", UNTAGGED_DELETE_ROOT);
+    expect(() => TerraformApplyOp({ name: "estate-apply", root: "estate", cwd: json })).toThrow(
+      /undeclared_untagged = "delete"/,
+    );
+
+    const ts = project("ts", UNTAGGED_DELETE_ROOT);
+    expect(() => TerraformApplyOp({ name: "estate-apply", root: "estate", cwd: ts })).not.toThrow();
+  });
+});
+
+describe("TF028 reports a stock-mode watch Op on a live root whatever the config format (#2216)", () => {
+  test("chant.config.ts: the composite builds, and the build reports the Op", async () => {
+    const dir = project("ts", LIVE_ROOT);
+    const { op } = TerraformWatchOp({ name: "estate-watch", root: "estate", cwd: dir });
+    const diags = await checkProject(dir, new Map([["estate-watch", op as unknown as Declarable]]));
+    const tf028 = diags.filter((d) => d.checkId === "TF028");
+    expect(tf028).toHaveLength(1);
+    expect(tf028[0].message).toContain('Op "estate-watch"');
+    expect(tf028[0].message).toContain('root module "estate"');
+  });
+
+  test("chant.config.json: the composite refuses before there is an Op to check", () => {
+    const dir = project("json", LIVE_ROOT);
+    expect(() => TerraformWatchOp({ name: "estate-watch", root: "estate", cwd: dir })).toThrow(
+      /runs choudoufu with a declared estate/,
+    );
+  });
+
+  test("live: true on the same root is clean in both formats", async () => {
+    for (const format of ["ts", "json"] as const) {
+      const dir = project(format, LIVE_ROOT);
+      const { op } = TerraformWatchOp({ name: "estate-watch", root: "estate", live: true, cwd: dir });
+      const diags = await checkProject(dir, new Map([["estate-watch", op as unknown as Declarable]]));
+      expect(diags.filter((d) => d.checkId === "TF028")).toEqual([]);
+    }
+  });
+});

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

@@ -0,0 +1,153 @@
+/**
+ * The four rules module descent made possible (chant #2112): TF014 and TF015,
+ * which are about what a child module may contain, and TF020 and TF021, which
+ * need a whole scope's references or a resource's whole body.
+ *
+ * TF014, TF015 and the scoped half of TF020 read tree fixtures
+ * (`fixtures/<id>/<case>/`, parsed through `renderTerraformRoots` by
+ * `loadTreeFixture`), because a rule about a child module cannot be shown one
+ * file and still be tested honestly. TF020's own conditions and TF021 read
+ * single-file fixtures the way every rule before them does.
+ */
+
+import { describe, expect, it } from "vitest";
+import { loadFixture, loadTreeFixture } from "./fixtures/load";
+import { tf001 } from "./tf001";
+import { tf014 } from "./tf014";
+import { tf015 } from "./tf015";
+import { tf020 } from "./tf020";
+import { tf021 } from "./tf021";
+import { withCallersChain } from "./scope";
+
+describe("TF014: a child module configures a provider", () => {
+  it("reports a provider block that sets anything beyond alias", async () => {
+    const diags = tf014.check(await loadTreeFixture("TF014", "positive", "app"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("app/module.cdn/provider.aws");
+    expect(diags[0].message).toContain("profile, region");
+    expect(diags[0].message).toContain("providers = { ... }");
+  });
+
+  it("leaves an alias-only block, and the root's own provider, alone", async () => {
+    const diags = tf014.check(await loadTreeFixture("TF014", "negative", "app"));
+    expect(diags).toEqual([]);
+  });
+
+  it("never fires on a root module's provider block", async () => {
+    // The positive fixture's ROOT configures a region too; only the child's
+    // block is reported.
+    const ctx = await loadTreeFixture("TF014", "positive", "app");
+    expect(ctx.entities.has("app/provider.aws")).toBe(true);
+    expect(tf014.check(ctx).map((d) => d.entity)).toEqual(["app/module.cdn/provider.aws"]);
+  });
+});
+
+describe("TF015: a child module declares a backend or cloud block", () => {
+  it("reports the backend block in the child", async () => {
+    const diags = tf015.check(await loadTreeFixture("TF015", "positive", "app"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("app/module.cdn/terraform");
+    expect(diags[0].message).toContain("declares a backend block");
+    expect(diags[0].message).toContain("Only a root module may");
+  });
+
+  it("leaves a child's required_version and required_providers alone", async () => {
+    expect(tf015.check(await loadTreeFixture("TF015", "negative", "app"))).toEqual([]);
+  });
+
+  it("is TF001's mirror: the root keeps its backend and neither rule fires twice", async () => {
+    const ctx = await loadTreeFixture("TF015", "positive", "app");
+    expect(tf001.check(ctx)).toEqual([]);
+    expect(tf015.check(ctx)).toHaveLength(1);
+  });
+});
+
+describe("TF001 still fires only on roots (#2112)", () => {
+  it("does not report a child module that has no backend", async () => {
+    // The root of the TF014 fixture declares one; the child declares none.
+    const ctx = await loadTreeFixture("TF014", "positive", "app");
+    expect(ctx.entities.has("app/module.cdn/aws_s3_bucket.assets")).toBe(true);
+    expect(tf001.check(ctx)).toEqual([]);
+  });
+
+  it("still reports a root that has none, descent or no descent", async () => {
+    const ctx = await loadTreeFixture("TF020", "scoped", "app");
+    expect(tf001.check(ctx)).toEqual([]); // this root has a remote backend block
+
+    const bare = await loadFixture("TF001", "positive", "app");
+    expect(tf001.check(bare)).toHaveLength(1);
+  });
+});
+
+describe("TF020: a declaration nothing in its scope references", () => {
+  it("reports an unused variable, local, data source and aliased provider", async () => {
+    const diags = tf020.check(await loadFixture("TF020", "positive"));
+    expect(diags.map((d) => d.entity).sort()).toEqual([
+      "TF020/data.aws_ami.ubuntu",
+      "TF020/locals",
+      "TF020/provider.aws",
+      "TF020/var.retention_days",
+    ]);
+    expect(diags.find((d) => d.entity === "TF020/locals")?.message).toContain('"local.common_tags"');
+    expect(diags.find((d) => d.entity === "TF020/data.aws_ami.ubuntu")?.message).toContain("every plan");
+  });
+
+  it("does not count a variable read only by its own validation block as used", async () => {
+    const diags = tf020.check(await loadFixture("TF020", "positive"));
+    expect(diags.some((d) => d.message.includes('"var.retention_days"'))).toBe(true);
+  });
+
+  it("reports nothing when every declaration is referenced", async () => {
+    expect(tf020.check(await loadFixture("TF020", "negative"))).toEqual([]);
+  });
+
+  it("judges each module scope on its own", async () => {
+    const diags = tf020.check(await loadTreeFixture("TF020", "scoped", "app"));
+    // The root's `var.region` is referenced by the module call; the child's
+    // `var.unused_in_child` is referenced by nothing in the child.
+    expect(diags.map((d) => d.entity)).toEqual(["app/module.cdn/var.unused_in_child"]);
+  });
+});
+
+describe("TF021: count where for_each is safer", () => {
+  it("reports a numeric count building an identity from count.index", async () => {
+    const diags = tf021.check(await loadFixture("TF021", "positive"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("`count = 3`");
+    expect(diags[0].message).toContain("tags.Name");
+    expect(diags[0].message).toContain("for_each");
+  });
+
+  it("reports a length() count the same way", async () => {
+    const diags = tf021.check(await loadFixture("TF021", "positive-length"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("length(var.subnets)");
+    expect(diags[0].message).toContain("bucket");
+  });
+
+  it("leaves a conditional count, a positional-only count.index and for_each alone", async () => {
+    expect(tf021.check(await loadFixture("TF021", "negative"))).toEqual([]);
+  });
+});
+
+describe("the Callers chain on a finding inside a child module", () => {
+  it("names the root and every call site, with the file and line of each", async () => {
+    const ctx = await loadTreeFixture("TF014", "positive", "app");
+    const [wrapped] = withCallersChain([tf014]);
+    const [diag] = wrapped.check(ctx);
+    expect(diag.message).toContain("Callers: app -> module.cdn (main.tf:13).");
+  });
+
+  it("chains one hop per level", async () => {
+    const ctx = await loadTreeFixture("TF015", "positive", "app");
+    const [wrapped] = withCallersChain([tf015]);
+    const [diag] = wrapped.check(ctx);
+    expect(diag.message).toContain("Callers: app -> module.cdn (main.tf:11).");
+  });
+
+  it("says nothing on a finding in the root module", async () => {
+    const [wrapped] = withCallersChain([tf001]);
+    const [diag] = wrapped.check(await loadFixture("TF001", "positive", "app"));
+    expect(diag.message).not.toContain("Callers:");
+  });
+});

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

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "vitest";
+import { classifyModuleSource, isDefaultBranch, isPinnedRef } from "./module-source";
+
+describe("classifyModuleSource", () => {
+  test("local paths", () => {
+    expect(classifyModuleSource("./modules/local").kind).toBe("local");
+    expect(classifyModuleSource("../modules/local").kind).toBe("local");
+  });
+
+  test("registry addresses, three and four parts", () => {
+    expect(classifyModuleSource("terraform-aws-modules/vpc/aws").kind).toBe("registry");
+    expect(classifyModuleSource("app.terraform.io/example-corp/k8s-cluster/azurerm").kind).toBe("registry");
+  });
+
+  test("a github.com or bitbucket.org host is never a registry address, even with four parts", () => {
+    expect(classifyModuleSource("github.com/hashicorp/example/extra").kind).not.toBe("registry");
+    expect(classifyModuleSource("bitbucket.org/hashicorp/example/extra").kind).not.toBe("registry");
+  });
+
+  test("git sources: explicit force prefix, github/bitbucket shorthand, scp-style, .git suffix", () => {
+    expect(classifyModuleSource("git::https://example.com/vpc.git").kind).toBe("git");
+    expect(classifyModuleSource("hg::http://example.com/vpc").kind).toBe("git");
+    expect(classifyModuleSource("github.com/hashicorp/example").kind).toBe("git");
+    expect(classifyModuleSource("bitbucket.org/foo/bar").kind).toBe("git");
+    expect(classifyModuleSource("git@github.com:org/repo.git").kind).toBe("git");
+    expect(classifyModuleSource("https://example.com/vpc.git").kind).toBe("git");
+    expect(classifyModuleSource("https://example.com/vpc.git?ref=main").kind).toBe("git");
+  });
+
+  test("extracts ref, falling back to rev", () => {
+    expect(classifyModuleSource("git::https://example.com/vpc.git?ref=v1.2.0").ref).toBe("v1.2.0");
+    expect(classifyModuleSource("git::https://example.com/vpc.git?rev=v1.2.0").ref).toBe("v1.2.0");
+    expect(classifyModuleSource("git::https://example.com/vpc.git?ref=v1.2.0&rev=other").ref).toBe("v1.2.0");
+    expect(classifyModuleSource("git::https://example.com/vpc.git").ref).toBeUndefined();
+  });
+
+  test("a source that parses as neither local, registry nor git is other", () => {
+    expect(classifyModuleSource("s3::https://bucket.s3.amazonaws.com/vpc.zip").kind).toBe("other");
+    expect(classifyModuleSource("not a valid source at all").kind).toBe("other");
+  });
+});
+
+describe("isPinnedRef", () => {
+  test("accepts semver-shaped tags, with or without a leading v", () => {
+    expect(isPinnedRef("v1.2.0")).toBe(true);
+    expect(isPinnedRef("1.2.0")).toBe(true);
+    expect(isPinnedRef("v1.2.0-rc.1")).toBe(true);
+  });
+
+  test("accepts a full 40-hex commit SHA", () => {
+    expect(isPinnedRef("abcdef1234567890abcdef1234567890abcdef12")).toBe(true);
+  });
+
+  test("rejects a short SHA", () => {
+    expect(isPinnedRef("abcdef1")).toBe(false);
+  });
+
+  test("rejects checkov's CKV_TF_2-passing but non-semver v1.2-dev (chant is stricter)", () => {
+    expect(isPinnedRef("v1.2-dev")).toBe(false);
+  });
+
+  test("rejects an arbitrary branch-shaped name", () => {
+    expect(isPinnedRef("some-feature")).toBe(false);
+  });
+});
+
+describe("isDefaultBranch", () => {
+  test("recognizes the four known mutable branch names", () => {
+    for (const b of ["main", "master", "develop", "trunk"]) expect(isDefaultBranch(b)).toBe(true);
+  });
+
+  test("does not flag an arbitrary branch name as a default branch", () => {
+    expect(isDefaultBranch("some-feature")).toBe(false);
+  });
+});

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

@@ -0,0 +1,121 @@
+/**
+ * Classify a `module` block's `source` string, shared by TF004 (registry
+ * module without a version) and TF005 (git/hg module unpinned or pinned to
+ * a branch). Neither rule evaluates HCL: both read `source` as the literal
+ * string hcl2json hands back, so a source built from a variable or a
+ * function call is never classified (`"other"`), matching tflint's own
+ * `SourceKnown` guard on `module.Source`.
+ *
+ * `registry` mirrors `hashicorp/terraform-registry-address`'s
+ * `ParseModuleSource` (MPL-2.0,
+ * https://github.com/hashicorp/terraform-registry-address/blob/main/module.go):
+ * three slash-separated parts (`namespace/name/target-system`), or four with
+ * a leading hostname that contains a dot and is not `github.com` or
+ * `bitbucket.org` (those are reserved for direct VCS installs, never a
+ * registry). `git` covers the sources tflint's `terraform_module_pinned_source`
+ * treats as git/hg: an explicit `git::`/`hg::` force prefix, the `github.com`
+ * and `bitbucket.org` shorthands its `GitHubDetector`/`BitBucketDetector`
+ * 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).
+ */
+
+export type ModuleSourceKind = "local" | "registry" | "git" | "other";
+
+export interface ModuleSourceClassification {
+  kind: ModuleSourceKind;
+  /** The `?ref=`/`&ref=` value (falling back to `rev`), when `kind` is `"git"`. */
+  ref?: string;
+}
+
+const REGISTRY_NAME = /^[0-9A-Za-z](?:[0-9A-Za-z_-]{0,62}[0-9A-Za-z])?$/;
+const REGISTRY_TARGET_SYSTEM = /^[0-9a-z]{1,64}$/;
+const RESERVED_VCS_HOSTS = new Set(["github.com", "bitbucket.org"]);
+
+/** Split a raw query string (no leading `?`) into its key/value pairs, last write wins. */
+function parseQuery(query: string): Map<string, string> {
+  const params = new Map<string, string>();
+  for (const pair of query.split("&")) {
+    if (pair === "") continue;
+    const eq = pair.indexOf("=");
+    const key = eq === -1 ? pair : pair.slice(0, eq);
+    const value = eq === -1 ? "" : decodeURIComponent(pair.slice(eq + 1));
+    params.set(decodeURIComponent(key), value);
+  }
+  return params;
+}
+
+/** Strip a `//<subdir>` package-subdirectory suffix, ignoring one embedded in the scheme (`https://`). */
+function stripSubdir(base: string): string {
+  const schemeEnd = base.indexOf("://");
+  const searchFrom = schemeEnd === -1 ? 0 : schemeEnd + 3;
+  const idx = base.indexOf("//", searchFrom);
+  return idx === -1 ? base : base.slice(0, idx);
+}
+
+function isRegistryAddress(rest: string): boolean {
+  const parts = stripSubdir(rest).split("/");
+  let namespace: string, name: string, targetSystem: string;
+  if (parts.length === 3) {
+    [namespace, name, targetSystem] = parts;
+  } else if (parts.length === 4) {
+    const host = parts[0];
+    if (!host.includes(".") || RESERVED_VCS_HOSTS.has(host.toLowerCase())) return false;
+    [, namespace, name, targetSystem] = parts;
+  } else {
+    return false;
+  }
+  return REGISTRY_NAME.test(namespace) && REGISTRY_NAME.test(name) && REGISTRY_TARGET_SYSTEM.test(targetSystem);
+}
+
+/** Is `rest` (source with any `git::`/`hg::` force prefix already stripped) a git/hg-shaped source? */
+function isGitShaped(rest: string): boolean {
+  if (/^[\w.-]+@[^:/]+:/.test(rest)) return true; // scp-style, e.g. git@github.com:org/repo.git
+  const withoutScheme = rest.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+  if (/^(github\.com|bitbucket\.org)\//i.test(withoutScheme)) return true;
+  if (/\.git($|[/?])/i.test(withoutScheme)) return true;
+  return false;
+}
+
+export function classifyModuleSource(source: string): ModuleSourceClassification {
+  const trimmed = source.trim();
+  if (trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith(".\\") || trimmed.startsWith("..\\")) {
+    return { kind: "local" };
+  }
+
+  const queryIdx = trimmed.indexOf("?");
+  const base = queryIdx === -1 ? trimmed : trimmed.slice(0, queryIdx);
+  const query = queryIdx === -1 ? "" : trimmed.slice(queryIdx + 1);
+
+  const forced = /^(git|hg)::/i.exec(base);
+  const rest = forced ? base.slice(forced[0].length) : base;
+
+  if (forced || isGitShaped(rest)) {
+    const params = parseQuery(query);
+    const ref = params.get("ref") || params.get("rev") || undefined;
+    return { kind: "git", ref };
+  }
+
+  if (isRegistryAddress(rest)) return { kind: "registry" };
+
+  return { kind: "other" };
+}
+
+const TAG_LIKE = /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const FULL_SHA = /^[0-9a-f]{40}$/i;
+const DEFAULT_BRANCHES = new Set(["main", "master", "develop", "trunk"]);
+
+/**
+ * Is `ref` pinned tightly enough for TF005: a semver-shaped tag or a full
+ * 40-hex commit SHA. Stricter than checkov's `CKV_TF_1`/`CKV_TF_2`, which
+ * accept any `?ref=` containing `\d\.\d` (so `v1.2-dev` passes there); the
+ * page documents the difference.
+ */
+export function isPinnedRef(ref: string): boolean {
+  return TAG_LIKE.test(ref) || FULL_SHA.test(ref);
+}
+
+/** Is `ref` one of the well-known mutable branch names tflint's `flexible` style rejects, plus `trunk`. */
+export function isDefaultBranch(ref: string): boolean {
+  return DEFAULT_BRANCHES.has(ref);
+}