@intentius/chant-lexicon-terraform 0.102.0 → 0.104.0

package/src/components/pr-loop.tofu.test.ts

@@ -0,0 +1,244 @@
+/**
+ * The pull-request loop (#3183) over five real Terraform roots, through the
+ * commands the generated CI runs: `chant components pr-plan` on the pull
+ * request and `chant components pr-apply` on the merge, each talking to a
+ * fake GitHub.
+ *
+ * The issue's "done when": a pull request touching one of five roots plans
+ * only that root and its dependents, applies on merge with the approved
+ * digest, and refuses with a clear message if the plan changed after review.
+ *
+ * The roots use `terraform_data`, which is built into `tofu` and `terraform`,
+ * with local state, so nothing downloads a provider or reaches a cloud. The
+ * estate is net -> a, b and a -> app, with dns on its own; a and b read net's
+ * output and app reads a's, through `stackOutput()`. Skipped when neither
+ * binary is on the PATH.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
+import type { ParsedArgs } from "@intentius/chant/cli/registry";
+import type { PrReport } from "@intentius/chant/pr-loop";
+import { terraformPlugin } from "../plugin";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+
+function which(bin: string): boolean {
+  try {
+    execFileSync(bin, ["version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+const BINARY = which("tofu") ? "tofu" : which("terraform") ? "terraform" : undefined;
+
+const ROOTS: Record<string, string> = {
+  net: 'resource "terraform_data" "vpc" {\n  input = "10.0.0.0/16"\n}\n\noutput "cidr" {\n  value = terraform_data.vpc.output\n}\n',
+  a: 'variable "cidr" {\n  type = string\n}\n\nresource "terraform_data" "subnet" {\n  input = "${var.cidr}/a-v1"\n}\n\noutput "id" {\n  value = terraform_data.subnet.output\n}\n',
+  b: 'variable "cidr" {\n  type = string\n}\n\nresource "terraform_data" "subnet" {\n  input = "${var.cidr}/b-v1"\n}\n',
+  app: 'variable "subnet" {\n  type = string\n}\n\nresource "terraform_data" "app" {\n  input = "app on ${var.subnet}"\n}\n',
+  dns: 'resource "terraform_data" "zone" {\n  input = "example.test"\n}\n',
+};
+
+const COMPONENTS = `import { phase, stackOutput, type Component } from "@intentius/chant/components";
+
+const apply = (root: string, vars?: Record<string, unknown>) =>
+  [phase("Apply", [{ kind: "terraform-apply", root, ...(vars ? { vars } : {}) }])];
+
+export const net: Component = { name: "net", dependsOn: [], deploy: apply("net") };
+export const a: Component = { name: "a", dependsOn: ["net"], deploy: apply("a", { cidr: stackOutput("net", "cidr") }) };
+export const b: Component = { name: "b", dependsOn: ["net"], deploy: apply("b", { cidr: stackOutput("net", "cidr") }) };
+export const app: Component = { name: "app", dependsOn: ["a"], deploy: apply("app", { subnet: stackOutput("a", "id") }) };
+export const dns: Component = { name: "dns", dependsOn: [], deploy: apply("dns") };
+`;
+
+/** GitHub as far as the loop uses it: comments, statuses, reviews and the merged pull request of a commit. */
+class FakeGithub {
+  comments: Array<{ id: number; pr: number; body: string }> = [];
+  statuses: Array<{ sha: string; state: string; context: string; description: string }> = [];
+  reviews: Record<number, Array<{ user: { login: string }; state: string }>> = {};
+  mergedBy: Record<string, number> = {};
+  private nextId = 1;
+
+  fetch = async (url: string, init: { method: string; body?: string }) => {
+    const path = new URL(url).pathname.replace(/^\/repos\/acme\/infra/, "");
+    const body = init.body ? JSON.parse(init.body) : undefined;
+    const ok = (value: unknown) => ({ ok: true, status: 200, text: async () => JSON.stringify(value) });
+    let m: RegExpMatchArray | null;
+    if ((m = path.match(/^\/issues\/(\d+)\/comments$/))) {
+      const pr = Number(m[1]);
+      if (init.method === "GET") return ok(this.comments.filter((c) => c.pr === pr));
+      const c = { id: this.nextId++, pr, body: body.body };
+      this.comments.push(c);
+      return ok(c);
+    }
+    if ((m = path.match(/^\/issues\/comments\/(\d+)$/))) {
+      const c = this.comments.find((x) => x.id === Number(m![1]))!;
+      c.body = body.body;
+      return ok(c);
+    }
+    if ((m = path.match(/^\/statuses\/([0-9a-f]+)$/))) {
+      this.statuses.push({ sha: m[1], ...body });
+      return ok({});
+    }
+    if ((m = path.match(/^\/pulls\/(\d+)\/reviews$/))) return ok(this.reviews[Number(m[1])] ?? []);
+    if ((m = path.match(/^\/commits\/([0-9a-f]+)\/pulls$/))) {
+      const pr = this.mergedBy[m[1]];
+      return ok(pr ? [{ number: pr, merged_at: "2026-10-03T00:00:00Z", merge_commit_sha: m[1] }] : []);
+    }
+    return { ok: false, status: 404, text: async () => "" };
+  };
+}
+
+const args = (overrides: Partial<ParsedArgs>): ParsedArgs => ({
+  command: "components",
+  path: ".",
+  format: "",
+  fix: false,
+  watch: false,
+  verbose: false,
+  help: false,
+  live: false,
+  env: "local",
+  noReleaseRecord: true,
+  ...overrides,
+});
+
+describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform"} roots`, () => {
+  let dir: string;
+  let cwd: string;
+  const github = new FakeGithub();
+  const env = { ...process.env };
+  const git = (...a: string[]) => execFileSync("git", a, { cwd: dir, encoding: "utf8" }).trim();
+  const write = (path: string, text: string) => {
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    writeFileSync(join(dir, path), text);
+  };
+  const report = (stage: "plan" | "apply"): PrReport => JSON.parse(readFileSync(join(dir, ".chant", "pr", `pr-${stage}.json`), "utf8"));
+  const state = (root: string) => readFileSync(join(dir, "roots", root, "terraform.tfstate"), "utf8");
+  const ctx = (overrides: Partial<ParsedArgs>) => ({ args: args(overrides), plugins: [terraformPlugin], serializers: [terraformPlugin.serializer] });
+  let handlers: typeof import("@intentius/chant/cli/handlers/pr");
+  let recordGateApproval: typeof import("@intentius/chant/cli/handlers/operator").recordGateApproval;
+
+  beforeAll(async () => {
+    dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-pr-loop-")));
+    symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"));
+    for (const [name, text] of Object.entries(ROOTS)) write(`roots/${name}/main.tf`, text);
+    write(
+      "chant.config.json",
+      JSON.stringify({ lexicons: ["terraform"], terraform: { binary: BINARY, roots: Object.fromEntries(Object.keys(ROOTS).map((r) => [r, { dir: `roots/${r}` }])) } }, null, 2),
+    );
+    write("estate.component.ts", COMPONENTS);
+    write(".gitignore", "node_modules\n.terraform\n.terraform.lock.hcl\n*.tfstate*\nchant.tfplan\n.chant\n");
+    git("init", "-q", "-b", "main");
+    git("config", "user.email", "ci@example.test");
+    git("config", "user.name", "ci");
+    git("add", "-A");
+    git("commit", "-qm", "five roots");
+
+    cwd = process.cwd();
+    process.chdir(dir);
+    Object.assign(process.env, {
+      GITHUB_REPOSITORY: "acme/infra",
+      GITHUB_TOKEN: "t0k",
+      GITHUB_API_URL: "https://api.github.com",
+      GITHUB_SERVER_URL: "https://github.com",
+      GITHUB_RUN_ID: "1",
+    });
+    vi.stubGlobal("fetch", github.fetch);
+    handlers = await import("@intentius/chant/cli/handlers/pr");
+    ({ recordGateApproval } = await import("@intentius/chant/cli/handlers/operator"));
+
+    // Every root applied once, so each has state and outputs to read.
+    const { runComponentsFanOut } = await import("@intentius/chant/cli/handlers/fan-out");
+    write("all.json", JSON.stringify({ changed: ["net", "dns"] }));
+    expect(await runComponentsFanOut(ctx({ fromAffected: "all.json" }) as never)).toBe(0);
+  }, 240_000);
+
+  afterAll(() => {
+    vi.unstubAllGlobals();
+    if (cwd) process.chdir(cwd);
+    for (const key of Object.keys(process.env)) if (!(key in env)) delete process.env[key];
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  /** A pull request that rewrites root a's subnet to `version`, merged by `merge`. */
+  async function openPullRequest(pr: number, version: string): Promise<PrReport> {
+    git("checkout", "-qb", `pr-${pr}`);
+    write("roots/a/main.tf", ROOTS.a.replace("a-v1", version));
+    git("commit", "-qam", `a ${version}`);
+    expect(await handlers.runComponentsPrPlan(ctx({ base: "main", pr, forge: "github" }) as never)).toBe(0);
+    return report("plan");
+  }
+
+  async function merge(pr: number): Promise<number> {
+    git("checkout", "-q", "main");
+    const before = git("rev-parse", "HEAD");
+    git("merge", "-q", "--no-ff", `pr-${pr}`, "-m", `Merge pull request #${pr}`);
+    github.mergedBy[git("rev-parse", "HEAD")] = pr;
+    return handlers.runComponentsPrApply(ctx({ base: before, forge: "github", requireReview: true }) as never);
+  }
+
+  test("a change to one root plans that root and its dependent, and nothing else", async () => {
+    const plan = await openPullRequest(1, "a-v2");
+
+    expect(plan.status).toBe("planned");
+    expect(plan.selection).toMatchObject({ changed: ["a"], dependents: ["app"], waves: [["a"], ["app"]] });
+    expect(plan.members.map((m) => [m.member, m.counts.update])).toEqual([
+      ["a", 1],
+      ["app", 0],
+    ]);
+    expect(plan.changeSet.digest).toBe(plan.digest);
+    expect(plan.approval).toEqual({ status: "pending" });
+
+    const note = github.comments.find((c) => c.pr === 1)!;
+    expect(note.body.startsWith("<!-- chant-pr:local -->")).toBe(true);
+    expect(note.body).toContain(`chant approve pr-1 pr-apply --plan ${plan.digest} --approver github:<your-login> --sign`);
+    expect(github.statuses.at(-1)).toMatchObject({ context: "chant/plan", state: "success", sha: plan.head });
+  }, 240_000);
+
+  test("on merge it applies the plan the reviewer approved", async () => {
+    const plan = report("plan");
+    github.reviews[1] = [{ user: { login: "alice" }, state: "APPROVED" }];
+    expect((await recordGateApproval("pr-1", "pr-apply", { actor: "github:alice", plan: plan.digest })).ok).toBe(true);
+
+    expect(await merge(1)).toBe(0);
+    const applied = report("apply");
+    expect(applied.digest).toBe(plan.digest);
+    expect(applied.status).toBe("applied");
+    expect(applied.approval).toEqual({ status: "approved", approvedBy: ["github:alice"] });
+    expect(applied.members.map((m) => [m.member, m.status, m.inputsMoved])).toEqual([
+      ["a", "applied", undefined],
+      ["app", "applied", ["a"]],
+    ]);
+    expect(state("a")).toContain("10.0.0.0/16/a-v2");
+    // The same note, now with the apply's outcome.
+    expect(github.comments.filter((c) => c.pr === 1)).toHaveLength(1);
+    expect(github.comments.find((c) => c.pr === 1)!.body).toContain("### chant apply for `local`");
+    expect(github.statuses.at(-1)).toMatchObject({ context: "chant/apply", state: "success", sha: applied.head });
+  }, 240_000);
+
+  test("a plan that changed after review is refused, naming both digests, and nothing applies", async () => {
+    const reviewed = await openPullRequest(2, "a-v3");
+    github.reviews[2] = [{ user: { login: "alice" }, state: "APPROVED" }];
+    expect((await recordGateApproval("pr-2", "pr-apply", { actor: "github:alice", plan: reviewed.digest })).ok).toBe(true);
+    // Pushed after the review.
+    write("roots/a/main.tf", ROOTS.a.replace("a-v1", "a-v4"));
+    git("commit", "-qam", "a v4");
+
+    expect(await merge(2)).toBe(3);
+    const refused = report("apply");
+    expect(refused.status).toBe("refused");
+    expect(refused.refusal).toBe("plan-changed");
+    expect(refused.approval).toEqual({ status: "changed", approved: reviewed.digest });
+    expect(refused.message).toContain(`approved: ${reviewed.digest}; planned now: ${refused.digest}`);
+    expect(refused.message).toContain("nothing was applied");
+    expect(state("a")).toContain("a-v2");
+    expect(state("a")).not.toContain("a-v4");
+    expect(github.statuses.at(-1)).toMatchObject({ context: "chant/apply", state: "failure", description: "refused: the plan changed after review" });
+  }, 240_000);
+});

package/src/composites/terraform-pin-rollout-op.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "vitest";
+import { validateActivitySteps, type ActivityStep, type OpConfig } from "@intentius/chant/op";
+import { TerraformPinRolloutOp } from "./terraform-pin-rollout-op";
+import { terraformPinRolloutContract } from "../op/activity-contracts";
+import { parsePinRolloutArgs, pinRolloutExitCode, terraformCommands } from "../commands";
+
+function props(config: Parameters<typeof TerraformPinRolloutOp>[0]): OpConfig {
+  return (TerraformPinRolloutOp(config).op as unknown as { props: OpConfig }).props;
+}
+
+const BASE = { name: "vpc-1-4", module: "oci://registry.example.com/modules/vpc", from: "1.3.0", to: "1.4.0" };
+
+describe("TerraformPinRolloutOp (#3189)", () => {
+  test("one Rollout phase, one step, the rollout's status as the run outcome", () => {
+    const op = props({ ...BASE, canaries: ["live/dev/vpc"], mode: "pull-request", schedule: "*/30 * * * *" });
+    expect(op.phases.map((p) => p.name)).toEqual(["Rollout"]);
+    const step = op.phases[0]!.steps[0] as ActivityStep;
+    expect(step.fn).toBe("terraformPinRollout");
+    expect(step.args).toEqual({ module: BASE.module, from: "1.3.0", to: "1.4.0", canaries: ["live/dev/vpc"], mode: "pull-request" });
+    expect(step.outcomeAttribute).toEqual({ name: "Rollout", from: "status" });
+    expect(op.schedule).toEqual({ cron: "*/30 * * * *", overlap: "skip" });
+  });
+
+  test("its step validates against the activity's contract", () => {
+    const op = props({ ...BASE, roots: [{ root: "a" }, { root: "b", dependsOn: ["a"] }] });
+    const contracts = new Map([["terraformPinRollout", terraformPinRolloutContract]]);
+    expect(validateActivitySteps(op, contracts)).toEqual([]);
+  });
+});
+
+describe("chant terraform pin-rollout", () => {
+  test("is mounted as the terraform group's pin-rollout verb", () => {
+    expect(terraformCommands.name).toBe("terraform");
+    expect(terraformCommands.commands.map((c) => c.name)).toEqual(["pin-rollout"]);
+  });
+
+  test("parses roots, dependencies, a generated root and canaries into the activity's args", () => {
+    const { args, json } = parsePinRolloutArgs([
+      "--module=oci://r/m/vpc",
+      "--from", "1.3.0",
+      "--to", "1.4.0",
+      "--root", "a",
+      "--depends-on", "b=a",
+      "--ts-source", "c=c/vpc.ts",
+      "--canary", "a",
+      "--pull-request",
+      "--json",
+    ]);
+    expect(json).toBe(true);
+    expect(args).toEqual({
+      module: "oci://r/m/vpc",
+      from: "1.3.0",
+      to: "1.4.0",
+      mode: "pull-request",
+      roots: [{ root: "a" }, { root: "b", dependsOn: ["a"] }, { root: "c", tsSource: "c/vpc.ts" }],
+      canaries: ["a"],
+    });
+  });
+
+  test("report is the default mode, and the required flags are required", () => {
+    expect(parsePinRolloutArgs(["--module", "m", "--from", "1", "--to", "2"]).args.mode).toBe("report");
+    expect(() => parsePinRolloutArgs(["--module", "m", "--from", "1"])).toThrow(/--to is required/);
+    expect(() => parsePinRolloutArgs(["--module", "m", "--from", "1", "--to", "2", "--bogus"])).toThrow(/Unknown flag: --bogus/);
+  });
+
+  test("waiting exits 3, stopped exits 1, the rest 0", () => {
+    expect(["complete", "opened", "would-open", "waiting", "stopped"].map(pinRolloutExitCode)).toEqual([0, 0, 0, 3, 1]);
+  });
+});

package/src/composites/terraform-pin-rollout-op.ts

@@ -0,0 +1,60 @@
+/**
+ * TerraformPinRolloutOp composite (#3189): roll a module version out as
+ * pin-bump pull requests, one wave at a time.
+ *
+ * One phase, one `terraformPinRollout` step. Each run reads the rollout's
+ * state from the forge and opens at most the next wave's PR, so the Op is
+ * meant to run again: on a `schedule`, or from the pipeline that applies a
+ * merged wave. Wave N+1 opens only on a run after wave N's PR merged and each
+ * of its roots reported its apply check as passed on the merge commit. Until
+ * then a run reports where the rollout stands and opens nothing. A failed
+ * root fails the run, naming it.
+ *
+ * The run's `Rollout` outcome is the rollout's status: `opened`, `waiting`,
+ * `complete`, or `would-open` in report mode.
+ *
+ * @example
+ * ```typescript
+ * import { TerraformPinRolloutOp } from "@intentius/chant-lexicon-terraform";
+ *
+ * export const { op } = TerraformPinRolloutOp({
+ *   name: "vpc-1-4",
+ *   module: "oci://registry.example.com/modules/vpc",
+ *   from: "1.3.0",
+ *   to: "1.4.0",
+ *   canaries: ["live/dev/vpc"],
+ *   mode: "pull-request",
+ *   schedule: "*\/30 * * * *",
+ * });
+ * ```
+ */
+
+import { Op, phase, OpResource } from "@intentius/chant/op";
+import { terraformPinRollout } from "../op/builders";
+import type { TerraformPinRolloutArgs } from "../op/activities/pin-rollout";
+
+export interface TerraformPinRolloutOpConfig extends TerraformPinRolloutArgs {
+  /** Op name (kebab-case). */
+  name: string;
+  /** Cron expression, so the rollout re-reads the forge and moves on without anyone running it. */
+  schedule?: string;
+}
+
+export interface TerraformPinRolloutOpResources {
+  /** Op resource. One Rollout phase. */
+  op: InstanceType<typeof OpResource>;
+}
+
+export function TerraformPinRolloutOp(config: TerraformPinRolloutOpConfig): TerraformPinRolloutOpResources {
+  const { name, schedule, ...args } = config;
+  const step = terraformPinRollout(args);
+  step.outcomeAttribute = { name: "Rollout", from: "status" };
+  const op = Op({
+    name,
+    overview: `Roll ${config.module} ${config.from} -> ${config.to} out as one pin-bump pull request per wave`,
+    labels: { Surface: "terraform-pin-rollout" },
+    ...(schedule ? { schedule: { cron: schedule, overlap: "skip" as const } } : {}),
+    phases: [phase("Rollout", [step])],
+  });
+  return { op };
+}

package/src/hcl/descend.ts

@@ -49,7 +49,7 @@
 import { existsSync, statSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import type { Declarable } from "@intentius/chant/declarable";
-import type { Hcl2Json } from "@intentius/chant/terraform/parse";
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
 import { isResourceDeclarable } from "@intentius/chant/declarable";
 import { classifyModuleSource } from "../lint/post-synth/module-source";
 import {

package/src/hcl/edges.ts

@@ -14,7 +14,7 @@
  *
  * The `${...}` body is tokenized by hcl2json's own expression AST
  * (`getReferencesInExpression`), never by a regex over the string. That is the
- * same instrument `packages/core/src/terraform/parse.ts` uses for the carve-out
+ * same instrument `packages/core/src/terraform/hcl2json.ts` uses for the carve-out
  * advisor, and for the same reason: a quoted address used as a map key
  * (`var.m["aws_s3_bucket.assets.arn"]`) and an escaped `$${...}` literal are
  * not references, and no regex over the raw string can tell. `./references.ts`
@@ -86,7 +86,7 @@
 
 import { isResourceDeclarable, type Declarable } from "@intentius/chant/declarable";
 import type { EntityReference } from "@intentius/chant/graph-ir";
-import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/parse";
+import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/hcl2json";
 import { refFromAccessor } from "@intentius/chant/terraform/graph";
 import { LOCALS_TYPE, scopeOfKey, type BlockBody, type TerraformEntity } from "./parse";
 

package/src/hcl/parse.test.ts

@@ -67,3 +67,28 @@ describe("blocksToEntities: suppression attachment (chant #2111)", () => {
     expect(second.suppressions).toBeUndefined();
   });
 });
+
+describe("Terragrunt config files (#3417)", () => {
+  const files = [
+    {
+      name: "terragrunt.hcl",
+      source: 'terraform {\n  source = "../m"\n}\ndependency "vpc" {\n  config_path = "../vpc"\n}\nremote_state {\n  backend = "s3"\n}\n',
+    },
+  ];
+
+  test("terragrunt.hcl and root.hcl become Terragrunt entities, never module entities", async () => {
+    const entities = await blocksToEntities(files, "unit");
+    expect([...entities.values()].map((e) => e.entityType).sort()).toEqual([
+      "Terraform::TerragruntConfig",
+      "Terraform::TerragruntDependency",
+      "Terraform::TerragruntRemoteState",
+      "Terraform::TerragruntSource",
+    ]);
+    expect([...entities.keys()]).toContain("unit/dependency.vpc");
+  });
+
+  test("the same text under a .tf name is read as a Terraform terraform block", async () => {
+    const entities = await blocksToEntities([{ name: "main.tf", source: 'terraform {\n  required_version = ">= 1.5"\n}\n' }], "unit");
+    expect([...entities.values()].map((e) => e.entityType)).toEqual(["Terraform::Terraform"]);
+  });
+});

package/src/hcl/parse.ts

@@ -20,7 +20,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/parse";
+import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/hcl2json";
 import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
 import type { EntityReference } from "@intentius/chant/graph-ir";
 import type { SuppressionDirective } from "@intentius/chant/lint/suppressions";
@@ -83,6 +83,13 @@ export interface TerraformEntity extends Declarable {
     readonly mode?: TerraformRootMode;
     /** The declared estate name. Present only when `mode` is `"live"`. */
     readonly estate?: string;
+    /**
+     * Whether `.terraform.lock.hcl` sits beside the root's `.tf` files (#3190,
+     * TF040). Stamped on every entity of a root parsed from a directory, and
+     * absent when the parse had no directory to look in (a fetched
+     * repository, inline source), which reads as "not determined".
+     */
+    readonly lockFile?: boolean;
     /** `terraform.roots.<name>.workspace`, recorded so TF025 can flag a non-default one on a live root. */
     readonly workspace?: string;
     /**
@@ -166,6 +173,26 @@ export const LOCALS_TYPE = "Terraform::Locals";
 /** A `live { estate = "..." }` block, or an `estate.chdf.hcl` sidecar's content (#2103). */
 export const LIVE_TYPE = "Terraform::Live";
 
+/**
+ * Terragrunt config entities (#3417). A `terragrunt.hcl` or `root.hcl` is not
+ * a Terraform module, so its blocks are read into these types and never into
+ * `TERRAFORM_TYPE`: TF001's `required_version` check and the rest of the
+ * module rules keep to the `.tf` files.
+ */
+export const TERRAGRUNT_CONFIG_TYPE = "Terraform::TerragruntConfig";
+export const TERRAGRUNT_SOURCE_TYPE = "Terraform::TerragruntSource";
+export const TERRAGRUNT_DEPENDENCY_TYPE = "Terraform::TerragruntDependency";
+export const TERRAGRUNT_REMOTE_STATE_TYPE = "Terraform::TerragruntRemoteState";
+export const TERRAGRUNT_GENERATE_TYPE = "Terraform::TerragruntGenerate";
+
+/** The Terragrunt config files read, by their default names. A `--config` rename is not followed. */
+export const TERRAGRUNT_FILENAMES: readonly string[] = ["root.hcl", "terragrunt.hcl"];
+
+/** Whether `name` (a bare filename) is a Terragrunt config file this lexicon reads. */
+export function isTerragruntFileName(name: string): boolean {
+  return TERRAGRUNT_FILENAMES.includes(name);
+}
+
 /** The sidecar filename choudoufu reads an estate declaration from when no in-block `live { }` is used. */
 export const LIVE_SIDECAR_FILENAME = "estate.chdf.hcl";
 
@@ -260,6 +287,11 @@ export function listTerraformFiles(dir: string): string[] {
     .sort();
 }
 
+/** The Terragrunt config files directly under `dir` (`root.hcl`, `terragrunt.hcl`), in filename order like the audit's bundle. */
+export function listTerragruntFiles(dir: string): string[] {
+  return TERRAGRUNT_FILENAMES.filter((name) => existsSync(join(dir, name)));
+}
+
 /**
  * Read the `estate.chdf.hcl` sidecar beside `dir`'s `.tf` files, if present.
  * Sibling to {@link listTerraformFiles}: the sidecar is plain HCL (a bare
@@ -313,8 +345,13 @@ export interface TerraformRootModeOptions {
    * declaration silently overrides.
    */
   configEstate?: string;
+  /** Stamp `props.lockFile` on every entity (#3190). Set by the two directory-backed parses only. */
+  lockFile?: boolean;
 }
 
+/** The lock file `terraform init` writes beside a root's `.tf` files. */
+export const LOCK_FILENAME = ".terraform.lock.hcl";
+
 /**
  * Parse a set of files into entities keyed `<root>/<address>`. Two blocks that
  * genuinely share an address (two `locals` blocks, or the same address in two
@@ -351,8 +388,15 @@ export async function blocksToEntities(
   const entities = new Map<string, Declarable>();
   const prefix = callers.length > 0 ? `${root}/${callers.join("/")}` : root;
 
-  const add = (entityType: string, address: string, body: unknown, file: TerraformFile, scan: FileScan): void => {
-    const { line, suppressions } = directivesFor(scan, address);
+  const add = (
+    entityType: string,
+    address: string,
+    body: unknown,
+    file: TerraformFile,
+    scan: FileScan,
+    scanAddress: string = address,
+  ): void => {
+    const { line, suppressions } = directivesFor(scan, scanAddress);
     const entity = terraformEntity(
       entityType,
       address,
@@ -418,6 +462,10 @@ export async function blocksToEntities(
   for (const file of files) {
     const tree = (await parser.parse(file.name, file.source)) as Record<string, unknown>;
     const scan = scanSuppressions(file.name, file.source);
+    if (isTerragruntFileName(file.name)) {
+      terragruntBlocks(tree, file, scan, add);
+      continue;
+    }
     unlabelled(tree, "terraform", TERRAFORM_TYPE, file, scan);
     for (const liveBody of liveBlocksIn(tree)) add(LIVE_TYPE, "live", liveBody, file, scan);
     unlabelled(tree, "locals", LOCALS_TYPE, file, scan);
@@ -450,7 +498,12 @@ export async function blocksToEntities(
     const te = entity as TerraformEntity;
     const stamped: TerraformEntity = {
       ...te,
-      props: { ...te.props, mode, ...(mode === "live" ? { estate } : {}) },
+      props: {
+        ...te.props,
+        mode,
+        ...(mode === "live" ? { estate } : {}),
+        ...(modeOptions?.lockFile !== undefined ? { lockFile: modeOptions.lockFile } : {}),
+      },
     };
     entities.set(key, stamped);
   }
@@ -458,6 +511,34 @@ export async function blocksToEntities(
   return entities;
 }
 
+/**
+ * One Terragrunt config file's blocks, as entities (#3417): the file's own
+ * settings (`terragrunt_version_constraint` and the `include` labels), the
+ * `terraform` block that names the unit's source, `remote_state`, each
+ * `dependency` and each `generate`. Everything else in the file (`inputs`,
+ * `locals`, `iam_role`) is left unread.
+ */
+function terragruntBlocks(
+  tree: Record<string, unknown>,
+  file: TerraformFile,
+  scan: FileScan,
+  add: (entityType: string, address: string, body: unknown, file: TerraformFile, scan: FileScan, scanAddress?: string) => void,
+): void {
+  const config: BlockBody = { includes: Object.keys(asRecord(tree["include"])) };
+  if (typeof tree["terragrunt_version_constraint"] === "string") {
+    config["terragrunt_version_constraint"] = tree["terragrunt_version_constraint"];
+  }
+  add(TERRAGRUNT_CONFIG_TYPE, "terragrunt", config, file, scan, "");
+  for (const body of asArray(tree["terraform"])) add(TERRAGRUNT_SOURCE_TYPE, "terragrunt.terraform", body, file, scan, "terraform");
+  for (const body of asArray(tree["remote_state"])) add(TERRAGRUNT_REMOTE_STATE_TYPE, "remote_state", body, file, scan);
+  for (const [name, bodies] of Object.entries(asRecord(tree["dependency"]))) {
+    for (const body of asArray(bodies)) add(TERRAGRUNT_DEPENDENCY_TYPE, `dependency.${name}`, body, file, scan);
+  }
+  for (const [name, bodies] of Object.entries(asRecord(tree["generate"]))) {
+    for (const body of asArray(bodies)) add(TERRAGRUNT_GENERATE_TYPE, `generate.${name}`, body, file, scan);
+  }
+}
+
 /**
  * Parse a root module directory. Reads every `.tf` directly under `dir`, plus
  * the `estate.chdf.hcl` sidecar beside them when present. Throws whatever the
@@ -471,7 +552,9 @@ export async function parseTerraformRootDir(
   modeOptions?: TerraformRootModeOptions,
   callers: readonly string[] = [],
 ): Promise<Map<string, Declarable>> {
-  const files = listTerraformFiles(dir).map((name) => ({
+  // A child module is a Terraform module, never a Terragrunt unit (#3417).
+  const names = [...listTerraformFiles(dir), ...(callers.length === 0 ? listTerragruntFiles(dir) : [])];
+  const files = names.map((name) => ({
     name,
     source: readFileSync(join(dir, name), "utf-8"),
   }));
@@ -479,7 +562,9 @@ export async function parseTerraformRootDir(
   // estate a ROOT runs against, and choudoufu reads it from the root's own
   // directory only. See `./descend.ts`.
   const sidecar = callers.length === 0 ? readLiveSidecarFile(dir) : undefined;
-  return blocksToEntities(files, root, hcl2json, modeOptions, sidecar, callers);
+  // Only the root's own directory carries a lock file that matters (#3190).
+  const opts = callers.length === 0 ? { ...modeOptions, lockFile: existsSync(join(dir, LOCK_FILENAME)) } : modeOptions;
+  return blocksToEntities(files, root, hcl2json, opts, sidecar, callers);
 }
 
 /**

package/src/hcl/roots.ts

@@ -29,7 +29,7 @@
 import { existsSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import { isResourceDeclarable, type Declarable } from "@intentius/chant/declarable";
-import type { Hcl2Json } from "@intentius/chant/terraform/parse";
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
 import type { TerraformRootConfig } from "../config";
 import { LIVE_TYPE, parseTerraformRootDir } from "./parse";
 import { descendModules, resolveCallModuleType, type CallModuleType } from "./descend";

package/src/hcl/suppressions.ts

@@ -27,9 +27,9 @@
 import type { SuppressionDirective, SuppressionIds } from "@intentius/chant/lint/suppressions";
 
 /** A block header keyword with zero labels (`terraform {`, `locals {`). */
-const BARE_RE = /^\s*(terraform|locals)\s*\{/;
+const BARE_RE = /^\s*(terraform|locals|remote_state)\s*\{/;
 /** One label (`provider "aws" {`, `module "vpc" {`, `variable "x" {`, `output "x" {`). */
-const ONE_LABEL_RE = /^\s*(provider|module|variable|output)\s+"([^"]*)"\s*\{/;
+const ONE_LABEL_RE = /^\s*(provider|module|variable|output|dependency|generate)\s+"([^"]*)"\s*\{/;
 /** Two labels (`resource "aws_s3_bucket" "assets" {`, `data "aws_ami" "x" {`). */
 const TWO_LABEL_RE = /^\s*(resource|data)\s+"([^"]*)"\s+"([^"]*)"\s*\{/;
 
@@ -43,6 +43,12 @@ function addressFor(keyword: string, labels: string[]): string {
       return "terraform";
     case "locals":
       return "locals";
+    case "remote_state":
+      return "remote_state";
+    case "dependency":
+      return `dependency.${labels[0]}`;
+    case "generate":
+      return `generate.${labels[0]}`;
     case "provider":
       return `provider.${labels[0]}`;
     case "module":