@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/src/module-catalog/types.ts

@@ -0,0 +1,88 @@
+/**
+ * The shape of choudoufu's `live/module-compat.json` (choudoufu#2292,
+ * `tools/modcompat/modcompat.go`), as far as the known-module catalog reads
+ * it. Only the static tier is typed here; see `./refresh-cli.ts`.
+ */
+
+/** One refusal on a static row: a choudoufu refusal ID and where it is documented. */
+export interface StaticRefusal {
+  id: string;
+  layer: string;
+  sites: number;
+  docs_ref: string;
+  docs_url: string;
+}
+
+/** One terraform-aws-modules example measured offline in the onboarded form. */
+export interface StaticRow {
+  tier: "static";
+  /** Registry address, `terraform-aws-modules/vpc/aws`. */
+  module: string;
+  /** The module repository's tag, `v6.6.1`. */
+  version: string;
+  /** The example directory inside the module repository. */
+  example: string;
+  date: string;
+  commit: string;
+  aws_provider: string;
+  verdict: "clear" | "refused" | "unmeasured";
+  /** Eligible data-source reads. These never refuse and are not refusals. */
+  reads: number;
+  refusals: StaticRefusal[];
+  reason?: string;
+  partial_schemas?: string[];
+}
+
+export interface StaticSource {
+  module: string;
+  repo: string;
+  version: string;
+  commit: string;
+  glob: string;
+  examples: number;
+}
+
+/** How the static tier was measured. */
+export interface StaticMeasurement {
+  date: string;
+  commit: string;
+  instrument: string;
+  form: string;
+  schemas: boolean;
+  second_pass: boolean;
+  aws_provider: string;
+  sources: StaticSource[];
+}
+
+/** The parts of the file the catalog reads. */
+export interface ModuleCompatFile {
+  schema: number;
+  static_measurement: StaticMeasurement;
+  static: StaticRow[];
+}
+
+const VERDICTS = new Set(["clear", "refused", "unmeasured"]);
+
+/**
+ * Check a parsed `live/module-compat.json` against the shape above and return
+ * it. Throws on a schema other than 1, a row outside the static tier, or a
+ * row whose verdict disagrees with its refusals, so a refresh never vendors a
+ * table the catalog would misread.
+ */
+export function parseModuleCompat(raw: unknown): ModuleCompatFile {
+  const file = raw as Partial<ModuleCompatFile>;
+  if (file?.schema !== 1) throw new Error(`module-compat.json: schema ${String(file?.schema)}, expected 1`);
+  if (!file.static_measurement || !Array.isArray(file.static)) {
+    throw new Error("module-compat.json: missing static_measurement or static");
+  }
+  for (const row of file.static) {
+    const where = `${row.module} ${row.version} ${row.example}`;
+    if (row.tier !== "static") throw new Error(`module-compat.json: ${where} is in the static array with tier ${row.tier}`);
+    if (!VERDICTS.has(row.verdict)) throw new Error(`module-compat.json: ${where} has verdict ${row.verdict}`);
+    if (!Array.isArray(row.refusals)) throw new Error(`module-compat.json: ${where} has no refusals list`);
+    if ((row.verdict === "refused") !== (row.refusals.length > 0)) {
+      throw new Error(`module-compat.json: ${where} is ${row.verdict} with ${row.refusals.length} refusals`);
+    }
+  }
+  return { schema: file.schema, static_measurement: file.static_measurement, static: file.static };
+}

package/src/op/activities/terraform.ts

@@ -53,6 +53,8 @@ import type { ChangeSetPart } from "@intentius/chant/change-set";
 import type { TerraformConfig, TerraformRootConfig } from "../../config";
 import { detectLiveEstate } from "./live-detect";
 import { backendConfigValues } from "../../backend-config";
+import { lockTimeoutArgs } from "../../lock-timeout";
+import { coneArgs, readPlanCone, type PlanCone } from "../../cone";
 import {
   parseAdoptionCommands,
   readAdoptionLedger,
@@ -195,6 +197,14 @@ export interface TerraformRootArgs {
    * `process.cwd()`, which is the project root under `chant run`.
    */
   cwd?: string;
+  /**
+   * The directory the root's files are read from in place of the entry's
+   * `dir`, relative to the project root (chant#4542). A promote or rollback
+   * under a release sets it to the release's recorded copy of the root; the
+   * entry's workspace, var files, backend config and estate still apply, and
+   * its var files and backend-config files resolve against this directory.
+   */
+  dir?: string;
 }
 
 export interface TerraformInitArgs extends TerraformRootArgs {
@@ -231,6 +241,19 @@ export interface TerraformPlanArgs extends TerraformRootArgs {
    * the text, such as the `terraform-apply` capability. Default: `true`.
    */
   text?: boolean;
+  /**
+   * How long the plan waits for another run's state lock (#4545), passed as
+   * `-lock-timeout` unless `TF_CLI_ARGS` or `TF_CLI_ARGS_plan` names one.
+   * Default: no flag, terraform's own (no wait).
+   */
+  lockTimeout?: string;
+  /**
+   * choudoufu only (#4545): plan the cone of the change since this revision
+   * (`-cone=<base>`) on a root under a `live` block that is not an estate
+   * file. Any other root, binary, or a plan with `targets` or `destroy`,
+   * plans in full. {@link TerraformPlanResult.cone} says which it was.
+   */
+  cone?: string;
 }
 
 export interface TerraformApplyArgs extends TerraformRootArgs {
@@ -251,6 +274,8 @@ export interface TerraformApplyArgs extends TerraformRootArgs {
    * separate to pass.
    */
   planFile?: string;
+  /** How long the apply waits for another run's state lock (#4545), as {@link TerraformPlanArgs.lockTimeout}. */
+  lockTimeout?: string;
 }
 
 export interface TerraformShowArgs extends TerraformRootArgs {
@@ -367,6 +392,8 @@ export interface TerraformPlanResult extends PlanChangeCounts {
    * `composeChangeSet` and bind the run's gate to the document's digest.
    */
   changeSet: ChangeSetPart;
+  /** Set when the plan was asked for a cone (#4545): the cone it planned, or why it planned the whole estate. */
+  cone?: PlanCone;
 }
 
 /**
@@ -617,9 +644,12 @@ export function terraformPlanCommand(opts: {
   vars?: Record<string, unknown>;
   destroy?: boolean;
   targets?: string[];
+  /** Extra flags after the fixed ones (#4545): `-lock-timeout`, `-cone`. */
+  extra?: readonly string[];
 }): string {
   const parts = [opts.binary, "plan", "-input=false", "-detailed-exitcode"];
   if (opts.destroy) parts.push("-destroy");
+  for (const flag of opts.extra ?? []) parts.push(quoteArg(flag));
   for (const target of [...new Set(opts.targets ?? [])].sort()) parts.push(`-target=${quoteArg(target)}`);
   for (const varFile of opts.varFiles ?? []) parts.push(`-var-file=${quoteArg(varFile)}`);
   for (const [name, value] of Object.entries(opts.vars ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
@@ -636,8 +666,9 @@ export function terraformPlanCommand(opts: {
  * block, and a matched one applies without re-prompting, exactly as stock's
  * own `apply <planfile>` does, so no `-auto-approve` is needed or passed.
  */
-export function terraformApplyCommand(opts: { binary: string; planFile: string }): string {
-  return `${opts.binary} apply -input=false ${quoteArg(opts.planFile)}`;
+export function terraformApplyCommand(opts: { binary: string; planFile: string; extra?: readonly string[] }): string {
+  const extra = (opts.extra ?? []).map((f) => ` ${quoteArg(f)}`).join("");
+  return `${opts.binary} apply -input=false${extra} ${quoteArg(opts.planFile)}`;
 }
 
 /**
@@ -937,7 +968,7 @@ async function resolveRoot(args: TerraformRootArgs, signal?: AbortSignal): Promi
     );
   }
   const binary = terraformBinary(namespace);
-  const dir = resolve(projectRoot, root.dir);
+  const dir = resolve(projectRoot, args.dir ?? root.dir);
   await ensureChoudoufuVersion(binary, signal);
   const estate = binary === "choudoufu" ? detectLiveEstate(dir) : undefined;
   // `estate` stays what it has always been: the estate the root's own HCL
@@ -1075,9 +1106,13 @@ export async function terraformPlan(
   args: TerraformPlanArgs,
   signal?: AbortSignal,
 ): Promise<TerraformPlanResult> {
-  const { binary, root, dir } = await resolveRoot(args, signal);
+  const { binary, root, dir, live } = await resolveRoot(args, signal);
   const planFile = args.planFile ?? DEFAULT_PLAN_FILE;
   const env = terraformEnvironment(root);
+  const lock = args.lockTimeout !== undefined ? lockTimeoutArgs("plan", args.lockTimeout) : [];
+  // #4545: a cone only on a live root that is not an estate file; -target and -destroy plan in full.
+  const fixed = [...(args.destroy ? ["-destroy"] : []), ...((args.targets ?? []).length > 0 ? ["-target"] : [])];
+  const cone = args.cone !== undefined ? coneArgs(binary, args.cone, fixed, live && !existsSync(join(dir, "estate.chdf.hcl"))) : [];
   const cmd = terraformPlanCommand({
     binary,
     planFile,
@@ -1085,12 +1120,15 @@ export async function terraformPlan(
     ...(args.vars ? { vars: args.vars } : {}),
     ...(args.destroy ? { destroy: true } : {}),
     ...(args.targets && args.targets.length > 0 ? { targets: args.targets } : {}),
+    ...(cone.length + lock.length > 0 ? { extra: [...cone, ...lock] } : {}),
   });
 
   let changed: boolean;
+  let output = "";
   try {
     const { stdout, stderr } = await run(cmd, dir, env, signal);
     report(stdout, stderr);
+    output = `${stdout}\n${stderr}`;
     changed = false;
   } catch (err) {
     // An abort or a spawn failure carries no numeric exit code. That is not
@@ -1104,6 +1142,7 @@ export async function terraformPlan(
       );
     }
     report(failure.stdout ?? "", failure.stderr ?? "");
+    output = `${failure.stdout ?? ""}\n${failure.stderr ?? ""}`;
     changed = true;
   }
 
@@ -1125,6 +1164,7 @@ export async function terraformPlan(
       ...((root.estate ?? root.workspace) ? { scope: root.estate ?? root.workspace } : {}),
     }),
     ...countPlanChanges(json),
+    ...(cone.length > 0 ? { cone: readPlanCone(output, join(dir, planFile), args.cone!) } : {}),
   };
 }
 
@@ -1176,7 +1216,8 @@ export async function terraformApply(
   }
 
   const planFile = args.planFile!;
-  const cmd = terraformApplyCommand({ binary, planFile });
+  const lock = args.lockTimeout !== undefined ? lockTimeoutArgs("apply", args.lockTimeout) : [];
+  const cmd = terraformApplyCommand({ binary, planFile, ...(lock.length > 0 ? { extra: lock } : {}) });
 
   try {
     const { stdout, stderr } = await run(cmd, dir, terraformEnvironment(root), signal);

package/src/op-wave-step.test.ts

@@ -0,0 +1,109 @@
+/**
+ * The terraform side of op waves through capabilities (#4545): lock
+ * timeouts, choudoufu cone plans, reads from another root's state and the
+ * cost hold preset, moved here from terragucci's wave callbacks.
+ */
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { DEFAULT_LOCK_TIMEOUT, isLockTimeout, lockTimeoutArgs } from "./lock-timeout";
+import { coneArgs, conePlanDigest, coneRecordPath, coneText, readPlanCone } from "./cone";
+import { atmosStateReads, fillStateReads, readOutputValue, stateReadsProblems, waitingReadsReason } from "./state-reads";
+import { INFRACOST_ARGV, terraformCostHold } from "./cost-hold";
+import { terraformApplyCommand, terraformPlanCommand } from "./op/activities/terraform";
+
+describe("lock timeout (#4545)", () => {
+  test("adds -lock-timeout unless the job sets one", () => {
+    expect(lockTimeoutArgs("plan", DEFAULT_LOCK_TIMEOUT, {})).toEqual(["-lock-timeout=5m"]);
+    expect(lockTimeoutArgs("apply", "30s", { TF_CLI_ARGS: "-no-color" })).toEqual(["-lock-timeout=30s"]);
+    expect(lockTimeoutArgs("plan", "5m", { TF_CLI_ARGS_plan: "-lock-timeout=1m" })).toEqual([]);
+    expect(lockTimeoutArgs("apply", "5m", { TF_CLI_ARGS: "--lock-timeout 2m" })).toEqual([]);
+    expect(lockTimeoutArgs("plan", false, {})).toEqual([]);
+    expect(() => lockTimeoutArgs("plan", "five", {})).toThrow(/not a duration/);
+    expect(isLockTimeout("1h30m")).toBe(true);
+  });
+
+  test("the plan and apply commands carry the extra flags", () => {
+    expect(terraformPlanCommand({ binary: "tofu", planFile: "chant.tfplan", extra: ["-cone=origin/main", "-lock-timeout=5m"] })).toBe(
+      "tofu plan -input=false -detailed-exitcode -cone=origin/main -lock-timeout=5m -out=chant.tfplan",
+    );
+    expect(terraformApplyCommand({ binary: "tofu", planFile: "chant.tfplan", extra: ["-lock-timeout=5m"] })).toBe("tofu apply -input=false -lock-timeout=5m chant.tfplan");
+    expect(terraformApplyCommand({ binary: "tofu", planFile: "chant.tfplan" })).toBe("tofu apply -input=false chant.tfplan");
+  });
+});
+
+describe("cone plans (#4545)", () => {
+  test("only choudoufu on a live root, and never beside -target or -destroy", () => {
+    expect(coneArgs("choudoufu", "origin/main", [], true)).toEqual(["-cone=origin/main"]);
+    expect(coneArgs("/usr/local/bin/choudoufu", "origin/main", [], true)).toEqual(["-cone=origin/main"]);
+    expect(coneArgs("tofu", "origin/main", [], true)).toEqual([]);
+    expect(coneArgs("choudoufu", "origin/main", [], false)).toEqual([]);
+    expect(coneArgs("choudoufu", "origin/main", ["-target"], true)).toEqual([]);
+    expect(coneArgs("choudoufu", undefined, [], true)).toEqual([]);
+  });
+
+  test("reads the record beside the plan, or the guard's fallback", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cone-"));
+    const plan = join(dir, "chant.tfplan");
+    writeFileSync(coneRecordPath(plan), JSON.stringify({ base: "origin/main", base_sha: "abc", targets: ["b.x", "a.y"] }));
+    const cone = readPlanCone("Warning: Cone plan\n\nThis plan covers the cone: 2 of the estate's 40 blocks\n\nPlan: 1 to add", plan, "origin/main");
+    expect(cone).toEqual({ base: "origin/main", blocks: 2, of: 40, record: { base: "origin/main", base_sha: "abc", targets: ["a.y", "b.x"] } });
+    expect(coneText(cone)).toBe("the cone of the change since origin/main, 2 of the estate's 40 blocks");
+    const fell = readPlanCone("Warning: Cone plan fell back to a full plan\n\nThis plan covers the whole estate (guard lockfile): the lock file changed.\n", plan, "origin/main");
+    expect(fell).toEqual({ base: "origin/main", fallback: { kind: "lockfile", reason: "the lock file changed" } });
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("the cone's targets join the digest; a full plan keeps its own", () => {
+    const d = `sha256:${"1".repeat(64)}`;
+    expect(conePlanDigest(d, undefined)).toBe(d);
+    expect(conePlanDigest(d, { base: "origin/main", fallback: { kind: "x", reason: "y" } })).toBe(d);
+    const a = conePlanDigest(d, { base: "origin/main", record: { base: "origin/main", base_sha: "", targets: ["a"] } });
+    const b = conePlanDigest(d, { base: "origin/main", record: { base: "origin/main", base_sha: "", targets: ["b"] } });
+    expect(a).not.toBe(d);
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("reads from another root's state (#4545)", () => {
+  test("fills each read once per upstream, and waits on a missing output", async () => {
+    let reads = 0;
+    const filled = await fillStateReads(
+      [
+        { var: "vpc_id", root: "network", output: ["vpc", "id"] },
+        { var: "subnets", root: "network", output: ["subnets"] },
+        { var: "db", root: "data", output: ["endpoint"] },
+      ],
+      async (root) => {
+        reads++;
+        return root === "network" ? { vpc: { id: "vpc-1" }, subnets: ["a", "b"] } : {};
+      },
+    );
+    expect(reads).toBe(2);
+    expect(filled.vars).toEqual({ vpc_id: "vpc-1", subnets: ["a", "b"] });
+    expect(filled.waiting.map((w) => w.why)).toEqual(["has no state yet"]);
+    expect(waitingReadsReason(filled.waiting)).toBe("not planned: it reads db from data, which has no state yet; apply data first");
+  });
+
+  test("a state that cannot be read is an error, not a wait", async () => {
+    const filled = await fillStateReads([{ var: "x", root: "up", output: ["x"] }], async () => {
+      throw new Error("init failed");
+    });
+    expect(filled.errors).toEqual(["it reads x from up, whose state could not be read: init failed"]);
+  });
+
+  test("checks the reads, reads a nested output, and maps Atmos edges", () => {
+    expect(stateReadsProblems([{ var: "a", root: "r", output: ["o"] }, { var: "a", root: "", output: [] }])).toHaveLength(3);
+    expect(readOutputValue({ o: { k: 1 } }, ["o", "k"])).toEqual({ value: 1 });
+    expect(readOutputValue({ o: { k: 1 } }, ["o", "j"])).toBeUndefined();
+    expect(atmosStateReads({ reads: [{ var: "v", upstream: "dev/vpc", output: ["id"], function: "!terraform.state vpc id" }] }, (u) => u.replace("/", "-"))).toEqual([{ var: "v", root: "dev-vpc", output: ["id"] }]);
+  });
+});
+
+describe("cost hold preset (#4545)", () => {
+  test("prices each root's plan document with infracost", () => {
+    expect(terraformCostHold({ approveAbove: 100 })).toEqual({ command: [...INFRACOST_ARGV], approveAbove: 100, format: "infracost" });
+    expect(() => terraformCostHold({ approveAbove: 1, command: ["infracost"] })).toThrow(/\{planJson\}/);
+  });
+});

package/src/pin/__fixtures__/consumers/live/dev/main.tf

@@ -0,0 +1,4 @@
+module "vpc" {
+  source  = "REGISTRY.acme.dev/acme/vpc/aws"
+  version = "v2.0.0"
+}

package/src/pin/__fixtures__/consumers/live/prod/main.tf

@@ -0,0 +1,21 @@
+module "vpc" {
+  source  = "registry.acme.dev/acme/vpc/aws"
+  version = "1.0.0"
+}
+
+module "eks" {
+  source  = "acme/eks/aws"
+  version = "~> 2.0"
+}
+
+module "net" {
+  source = "git::https://git.acme.dev/acme/net.git?ref=v1.2.0"
+}
+
+module "cache" {
+  source = "oci://registry.acme.dev/modules/cache?tag=3.1.0"
+}
+
+module "local" {
+  source = "./modules/local"
+}

package/src/pin/__fixtures__/consumers/units/vpc/terragrunt.hcl

@@ -0,0 +1,7 @@
+terraform {
+  source = "tfr://registry.acme.dev/acme/vpc/aws?version=1.1.0"
+}
+
+inputs = {
+  cidr = "10.0.0.0/16"
+}

package/src/pin/consumers.test.ts

@@ -0,0 +1,57 @@
+/**
+ * The consumer scan (chant#4599): registry, git ref and OCI tag pins, a
+ * constraint left unpinned, a Terragrunt unit's `terraform { source }`, and
+ * local calls left out, all read from source files.
+ */
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { isLocalSource, moduleConsumers, normalizeModuleSource } from "./consumers";
+
+const REPO = join(import.meta.dirname, "__fixtures__", "consumers");
+
+describe("moduleConsumers", () => {
+  test("lists every published module call in the roots, sorted", async () => {
+    const calls = await moduleConsumers(REPO, ["live/prod", "live/dev", "units/vpc"]);
+    expect(calls.map((c) => [c.root, c.address, c.module, c.pin])).toEqual([
+      ["live/dev", "module.vpc", "registry.acme.dev/acme/vpc/aws", "v2.0.0"],
+      ["live/prod", "module.cache", "oci://registry.acme.dev/modules/cache", "3.1.0"],
+      ["live/prod", "module.eks", "registry.terraform.io/acme/eks/aws", null],
+      ["live/prod", "module.net", "git::https://git.acme.dev/acme/net.git", "v1.2.0"],
+      ["live/prod", "module.vpc", "registry.acme.dev/acme/vpc/aws", "1.0.0"],
+      ["units/vpc", "terragrunt.terraform", "registry.acme.dev/acme/vpc/aws", "1.1.0"],
+    ]);
+  });
+
+  test("keeps where each pin sits and why a call has none", async () => {
+    const calls = await moduleConsumers(REPO, ["live/prod", "units/vpc"]);
+    const by = (a: string, root = "live/prod") => calls.find((c) => c.address === a && c.root === root)!;
+    expect(by("module.vpc")).toMatchObject({ kind: "terraform", file: "live/prod/main.tf", at: "version", source: "registry.acme.dev/acme/vpc/aws" });
+    expect(by("module.net")).toMatchObject({ at: "source", param: "ref" });
+    expect(by("module.cache")).toMatchObject({ at: "source", param: "tag" });
+    expect(by("module.eks").unpinned).toContain("constraint");
+    expect(by("terragrunt.terraform", "units/vpc")).toMatchObject({ kind: "terragrunt", file: "units/vpc/terragrunt.hcl", at: "source", param: "version" });
+  });
+
+  test("leaves local calls out", async () => {
+    const calls = await moduleConsumers(REPO, ["live/prod"]);
+    expect(calls.find((c) => c.address === "module.local")).toBeUndefined();
+    expect(isLocalSource("./modules/local")).toBe(true);
+    expect(isLocalSource("../shared")).toBe(true);
+    expect(isLocalSource("acme/vpc/aws")).toBe(false);
+  });
+});
+
+describe("normalizeModuleSource", () => {
+  test.each([
+    ["acme/vpc/aws", "registry.terraform.io/acme/vpc/aws"],
+    ["acme/vpc/aws//modules/x", "registry.terraform.io/acme/vpc/aws//modules/x"],
+    ["Registry.Acme.dev/acme/vpc/aws", "registry.acme.dev/acme/vpc/aws"],
+    ["tfr:///terraform-aws-modules/vpc/aws", "registry.terraform.io/terraform-aws-modules/vpc/aws"],
+    ["tfr://registry.acme.dev/acme/vpc/aws", "registry.acme.dev/acme/vpc/aws"],
+    ["github.com/acme/vpc", "github.com/acme/vpc"],
+    ["git::https://git.acme.dev/acme/net.git", "git::https://git.acme.dev/acme/net.git"],
+    ["oci://registry.acme.dev/modules/cache", "oci://registry.acme.dev/modules/cache"],
+  ])("%s is %s", (from, to) => {
+    expect(normalizeModuleSource(from)).toBe(to);
+  });
+});

package/src/pin/consumers.ts

@@ -0,0 +1,95 @@
+/**
+ * Where a repo calls its modules (chant#4599, terragucci#1289 bundle B): one
+ * entry per module call in the roots given, Terragrunt units included, read
+ * from the source files with chant's HCL parse and never from a plan, so the
+ * scan runs in a check job before anything is planned.
+ *
+ * Each call carries its root, file and block path, the source as written,
+ * the module it names with the pin taken out and normalised
+ * ({@link normalizeModuleSource}), and the pin `readModulePin` (./source.ts)
+ * reads. A local call (`./`, `../`) names no published module and is left
+ * out. The release catalog lists these as a version's consumers, and
+ * `deprecatedPins` (../registry/deprecated.ts) checks them against it.
+ *
+ * The `terragucci_module_pin` metric keeps reading the plan; this is the
+ * source-side view of the same calls. The normal form is chant#3924's
+ * (../registry/source-forms.ts), shared with `usedSources` (../sources.ts).
+ */
+import { join, relative } from "node:path";
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import { MODULE_TYPE, TERRAGRUNT_SOURCE_TYPE, parseTerraformRootDir, type TerraformEntity } from "../hcl/parse";
+import { normalizeModuleSource, PUBLIC_REGISTRY_HOST } from "../registry/source-forms";
+import { readModulePin, type ModuleCallPin } from "./source";
+
+export { normalizeModuleSource, PUBLIC_REGISTRY_HOST };
+
+/** One module call in a consuming repo. */
+export interface ModuleConsumer {
+  /** The root (or Terragrunt unit) directory, from the repo's top, `/`-separated. */
+  root: string;
+  /** The file holding the call, from the repo's top. */
+  file: string;
+  /** The block: `module.<name>`, or `terragrunt.terraform` for a unit's source. */
+  address: string;
+  /** `terraform` for a module block, `terragrunt` for a unit's `terraform { source }`. */
+  kind: "terraform" | "terragrunt";
+  /** The `source` as written. */
+  source: string;
+  /** The module the call names: the source with the pin taken out, normalised. */
+  module: string;
+  /** The pinned version, tag, digest or ref, or null when the call pins none. */
+  pin: string | null;
+  /** Where the pin is, as `readModulePin` reads it. */
+  at: ModuleCallPin["at"];
+  param?: ModuleCallPin["param"];
+  /** Why there is no pin, when `pin` is null. */
+  unpinned?: string;
+}
+
+/** A source names a local directory, not a published module. */
+export function isLocalSource(source: string): boolean {
+  return source.startsWith("./") || source.startsWith("../");
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+/**
+ * Every module call in `roots` (directories from `repo`), sorted by root,
+ * file and address. A root whose files cannot be parsed throws, naming the
+ * root, so a check job fails loudly instead of listing fewer consumers.
+ */
+export async function moduleConsumers(repo: string, roots: readonly string[], parser?: Hcl2Json): Promise<ModuleConsumer[]> {
+  const out: ModuleConsumer[] = [];
+  for (const root of [...new Set(roots)].sort()) {
+    const dir = join(repo, root);
+    const rel = relative(repo, dir).split("\\").join("/") || ".";
+    let entities: TerraformEntity[];
+    try {
+      entities = [...(await parseTerraformRootDir(dir, "consumers", parser)).values()] as TerraformEntity[];
+    } catch (e) {
+      throw new Error(`${rel}: ${(e as Error).message}`);
+    }
+    for (const e of entities) {
+      if (e.entityType !== MODULE_TYPE && e.entityType !== TERRAGRUNT_SOURCE_TYPE) continue;
+      const source = str(e.props.body.source);
+      if (source === undefined || isLocalSource(source)) continue;
+      const version = e.entityType === MODULE_TYPE ? str(e.props.body.version) : undefined;
+      const pin = readModulePin(source, version);
+      out.push({
+        root: rel,
+        file: rel === "." ? e.props.file : `${rel}/${e.props.file}`,
+        address: e.props.address,
+        kind: e.entityType === MODULE_TYPE ? "terraform" : "terragrunt",
+        source,
+        module: normalizeModuleSource(pin.module),
+        pin: pin.pin,
+        at: pin.at,
+        ...(pin.param ? { param: pin.param } : {}),
+        ...(pin.unpinned ? { unpinned: pin.unpinned } : {}),
+      });
+    }
+  }
+  return out.sort((a, b) => a.root.localeCompare(b.root) || a.file.localeCompare(b.file) || a.address.localeCompare(b.address));
+}

package/src/plugin.ts

@@ -1,4 +1,5 @@
 import type { AuditEntitiesInput, LexiconPlugin } from "@intentius/chant/lexicon";
+import { terraformCiSetup } from "./ci-setup";
 import { terraformBehaviourKinds } from "./behaviour/kinds";
 import type { CompletionContext, HoverContext } from "@intentius/chant/lsp/types";
 import type { Declarable } from "@intentius/chant/declarable";
@@ -84,6 +85,11 @@ export const terraformPlugin: LexiconPlugin = {
   serializer: terraformSerializer,
   configSchema: terraformConfigSchema,
 
+  // #4550: the engine install lines for the pull request pipeline's default image.
+  ciSetup(ctx: { dir: string }): string[] {
+    return terraformCiSetup(ctx);
+  },
+
   // ── Required lifecycle methods ────────────────────────────────
 
   async generate(options?: { verbose?: boolean }): Promise<void> {

package/src/registry/__fixtures__/docs/documented/.terraform-docs.yml

@@ -0,0 +1,3 @@
+formatter: markdown table
+output:
+  mode: inject

package/src/registry/__fixtures__/docs/documented/README.md

@@ -0,0 +1 @@
+# documented

package/src/registry/__fixtures__/docs/documented/main.tf

@@ -0,0 +1,8 @@
+variable "name" {
+  type        = string
+  description = "The bucket's name."
+}
+
+output "bucket" {
+  value = var.name
+}

package/src/registry/__fixtures__/docs/json/main.tf.json

@@ -0,0 +1,14 @@
+{
+  "terraform": {
+    "required_providers": {
+      "google": { "source": "hashicorp/google", "version": "~> 6.0" }
+    }
+  },
+  "variable": {
+    "project": { "type": "string", "description": "The project id." },
+    "region": { "type": "string", "default": "us-central1" }
+  },
+  "output": {
+    "name": { "value": "${var.project}", "description": "The project id, echoed." }
+  }
+}

package/src/registry/__fixtures__/docs/vpc/README.md

@@ -0,0 +1,3 @@
+# vpc
+
+A VPC with flow logs.

package/src/registry/__fixtures__/docs/vpc/examples/complete/main.tf

@@ -0,0 +1,5 @@
+module "vpc" {
+  source = "../.."
+  cidr   = "10.1.0.0/16"
+  tags   = { team = "net" }
+}

package/src/registry/__fixtures__/docs/vpc/examples/simple/README.md

@@ -0,0 +1 @@
+# Simple

package/src/registry/__fixtures__/docs/vpc/examples/simple/main.tf

@@ -0,0 +1,4 @@
+module "vpc" {
+  source = "../.."
+  cidr   = "10.0.0.0/16"
+}

package/src/registry/__fixtures__/docs/vpc/main.tf

@@ -0,0 +1,14 @@
+terraform {
+  required_version = ">= 1.5"
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5.0"
+    }
+  }
+}
+
+resource "aws_vpc" "this" {
+  cidr_block = var.cidr
+  tags       = var.tags
+}

package/src/registry/__fixtures__/docs/vpc/outputs.tf

@@ -0,0 +1,9 @@
+output "vpc_id" {
+  value       = aws_vpc.this.id
+  description = "The VPC's id."
+}
+
+output "arn" {
+  value     = aws_vpc.this.arn
+  sensitive = true
+}

package/src/registry/__fixtures__/docs/vpc/variables.tf

@@ -0,0 +1,16 @@
+variable "cidr" {
+  type        = string
+  description = "The VPC's IPv4 CIDR block."
+}
+
+variable "tags" {
+  type        = map(string)
+  default     = {}
+  description = "Tags for every resource."
+}
+
+variable "flow_log_key" {
+  type      = string
+  default   = "not-a-real-key"
+  sensitive = true
+}