@intentius/chant-lexicon-terraform 0.124.31 → 0.124.32

package/dist/terragrunt/run.js

@@ -0,0 +1,264 @@
+/**
+ * The Terragrunt runner (#3414): discovery and one wave, run against a real
+ * `terragrunt`. The pure halves are `./units.ts` and `./wave.ts`.
+ *
+ * Every call takes an injectable `exec`, so tests stub the process and the
+ * acceptance test runs the real binary.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { plannerForBinary } from "../change-set.js";
+import { parseTerragruntFind, terragruntFindArgs, terragruntVersionProblem, } from "./units.js";
+import { describeMockRefusal, failMockedParts, markProvisional, parseRenderedDependencies, parseTerragruntOutputs, PROVISIONAL_MARKER, terragruntMockReads, terragruntMockWarnings, terragruntOutputArgs, terragruntOutputUpstreams, terragruntRenderArgs, } from "./mocks.js";
+import { parseTerragruntReport, terragruntEnv, terragruntUnitResults, terragruntWaveArgs, terragruntWaveParts, } from "./wave.js";
+export const defaultTerragruntExec = (file, args, options) => new Promise((done) => {
+    execFile(file, [...args], { cwd: options.cwd, env: { ...process.env, ...options.env }, maxBuffer: 256 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const code = err ? (typeof err.code === "number" ? (err.code) : null) : 0;
+        done({ code, stdout: String(stdout), stderr: err && code === null ? `${String(stderr)}${err.message}` : String(stderr) });
+    });
+});
+/** Thrown when `terragrunt` is missing, too old or fails. */
+export class TerragruntError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TerragruntError";
+    }
+}
+/** Refuse a Terragrunt older than 1.1. Returns the version line. */
+export async function checkTerragruntVersion(options) {
+    const exec = options.exec ?? defaultTerragruntExec;
+    const tg = options.terragrunt ?? "terragrunt";
+    const r = await exec(tg, ["--version"], { cwd: options.dir, env: {} });
+    if (r.code !== 0)
+        throw new TerragruntError(`\`${tg} --version\` failed (exit ${r.code}): ${(r.stderr || r.stdout).trim()}`);
+    const problem = terragruntVersionProblem(r.stdout);
+    if (problem)
+        throw new TerragruntError(problem);
+    return r.stdout.trim();
+}
+/**
+ * The project's units, from `terragrunt find`, with catalog templates and the
+ * module cache left out and `.terragrunt-filters` honoured.
+ */
+export async function discoverTerragruntUnits(options) {
+    const exec = options.exec ?? defaultTerragruntExec;
+    const tg = options.terragrunt ?? "terragrunt";
+    const args = terragruntFindArgs(options);
+    const r = await exec(tg, args, { cwd: options.dir, env: terragruntEnv(options.binary) });
+    if (r.code !== 0)
+        throw new TerragruntError(`\`${tg} ${args.join(" ")}\` failed (exit ${r.code}): ${r.stderr.trim()}`);
+    let units;
+    try {
+        units = parseTerragruntFind(r.stdout);
+    }
+    catch (err) {
+        throw new TerragruntError(`could not read \`terragrunt find\` output: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { units, warnings: options.binary ? terraformBinaryWarnings(options.dir, units, options.binary) : [] };
+}
+const TERRAFORM_BINARY = /^\s*terraform_binary\s*=\s*(.+?)\s*$/m;
+/**
+ * A warning per unit whose `terragrunt.hcl`, or a file it includes, sets
+ * `terraform_binary` to something other than `binary`. `TG_TF_PATH` wins over
+ * it (observed on 1.1.6), so the unit runs `binary`, not what it names.
+ */
+export function terraformBinaryWarnings(dir, units, binary) {
+    const out = [];
+    for (const u of units) {
+        const files = [join(u.path, "terragrunt.hcl"), ...Object.values(u.include ?? {})];
+        for (const f of files) {
+            let text;
+            try {
+                text = readFileSync(resolve(dir, f), "utf8");
+            }
+            catch {
+                continue;
+            }
+            const m = TERRAFORM_BINARY.exec(text);
+            if (!m)
+                continue;
+            const literal = /^"([^"$]*)"$/.exec(m[1]);
+            if (literal && literal[1] === binary)
+                break;
+            out.push(`${u.path}: ${f} sets terraform_binary = ${m[1]}, but the project's binary is ${binary}; ` +
+                `TG_TF_PATH=${binary} overrides it, so the unit runs ${binary}`);
+            break;
+        }
+    }
+    return out;
+}
+/** The planner a wave's plans come from: the project's binary, else Terragrunt's default of tofu. */
+export function terragruntPlanner(binary) {
+    return plannerForBinary(binary ?? "tofu");
+}
+/**
+ * Thrown when a wave's plans would read `mock_outputs` (#3416). Nothing in
+ * the wave was planned, so there is nothing to gate. `reads` names each unit,
+ * dependency and upstream.
+ */
+export class TerragruntMockRefusal extends TerragruntError {
+    constructor(reads) {
+        super(describeMockRefusal(reads));
+        this.reads = reads;
+        this.name = "TerragruntMockRefusal";
+    }
+}
+/** Run `fn` over `items`, at most `limit` at a time, keeping their order. */
+async function pool(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+    return out;
+}
+/** `dir` and its real path, for reading the absolute paths Terragrunt prints. */
+function dirsOf(dir) {
+    const abs = resolve(dir);
+    try {
+        const real = realpathSync(abs);
+        return real === abs ? [abs] : [abs, real];
+    }
+    catch {
+        return [abs];
+    }
+}
+/**
+ * Which dependencies of the wave's units would read `mock_outputs` at plan,
+ * asked of Terragrunt: `render --json` in each unit for its evaluated
+ * `dependency` blocks, then `output -json` in each upstream they read. Empty
+ * when the wave would plan on real outputs only. Throws when Terragrunt
+ * cannot render a unit or read an upstream's outputs, since then nobody
+ * knows what the plan would read. A unit with no `terragrunt.hcl` in `dir`
+ * (removed by the change, so planned as a destroy) is not rendered.
+ */
+export async function checkTerragruntWaveMocks(input) {
+    const exec = input.exec ?? defaultTerragruntExec;
+    const tg = input.terragrunt ?? "terragrunt";
+    const env = terragruntEnv(input.binary);
+    const limit = input.parallelism ?? 8;
+    const dirs = dirsOf(input.dir);
+    // A unit this change removed has no terragrunt.hcl here: Terragrunt plans its destroy from the old checkout.
+    // It is not rendered; the plan log check still covers it.
+    const units = [...new Set(input.units)].sort().filter((u) => existsSync(join(resolve(input.dir), u, "terragrunt.hcl")));
+    const rendered = await pool(units, limit, async (unit) => {
+        const args = terragruntRenderArgs(unit);
+        const r = await exec(tg, args, { cwd: input.dir, env });
+        if (r.code !== 0)
+            throw new TerragruntError(`\`${tg} ${args.join(" ")}\` failed (exit ${r.code}), so the wave's dependencies are unknown: ${r.stderr.trim()}`);
+        try {
+            return [unit, parseRenderedDependencies(unit, r.stdout, dirs)];
+        }
+        catch (err) {
+            throw new TerragruntError(`could not read \`terragrunt render --json\` for ${unit}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    const dependencies = new Map(rendered);
+    const upstreams = terragruntOutputUpstreams(dependencies);
+    const outputs = await pool(upstreams, limit, async (upstream) => {
+        const args = terragruntOutputArgs(upstream);
+        const r = await exec(tg, args, { cwd: input.dir, env });
+        const parsed = r.code === 0 ? parseTerragruntOutputs(r.stdout) : undefined;
+        if (!parsed) {
+            throw new TerragruntError(`could not read the outputs of ${upstream}, which the wave reads (\`${tg} ${args.join(" ")}\` exit ${r.code}): ${(r.stderr || r.stdout).trim().slice(-2000)}`);
+        }
+        return [upstream, parsed];
+    });
+    return terragruntMockReads({ dependencies, outputs: new Map(outputs) });
+}
+/**
+ * Plan one wave with one `terragrunt run --all`, and read each unit's plan
+ * JSON and run-report row.
+ *
+ * Unless the plan is provisional, the wave is first checked for mock reads
+ * ({@link checkTerragruntWaveMocks}) and refused with a
+ * {@link TerragruntMockRefusal} when any dependency would read
+ * `mock_outputs`; nothing is planned then. A unit the plan log still shows
+ * reading a mock (its upstream's state went away in between) becomes a
+ * failed member.
+ */
+export async function planTerragruntWave(input) {
+    const exec = input.exec ?? defaultTerragruntExec;
+    const tg = input.terragrunt ?? "terragrunt";
+    const work = resolve(input.dir, input.workDir);
+    const outDir = join(work, "plans");
+    const jsonOutDir = join(work, "json");
+    const reportFile = join(work, "plan-report.json");
+    const marker = join(work, PROVISIONAL_MARKER);
+    // A plan or report left by an earlier attempt must not stand in for a unit that did not plan this time.
+    for (const stale of [outDir, jsonOutDir, reportFile, marker])
+        rmSync(stale, { recursive: true, force: true });
+    if (!input.provisional) {
+        const reads = await checkTerragruntWaveMocks({ ...input, exec });
+        if (reads.length > 0)
+            throw new TerragruntMockRefusal(reads);
+    }
+    mkdirSync(work, { recursive: true });
+    // Written before planning, so a plan cut short still never applies.
+    if (input.provisional)
+        writeFileSync(marker, "planned before its upstream applied; never applied\n");
+    const args = terragruntWaveArgs({
+        units: input.units,
+        command: "plan",
+        outDir,
+        jsonOutDir,
+        reportFile,
+        ...(input.destroy ? { destroy: true } : {}),
+        ...(input.parallelism !== undefined ? { parallelism: input.parallelism } : {}),
+    });
+    const r = await exec(tg, args, { cwd: input.dir, env: terragruntEnv(input.binary) });
+    const report = existsSync(reportFile) ? parseTerragruntReport(readFileSync(reportFile, "utf8")) : new Map();
+    const planFor = (unit) => {
+        const f = join(jsonOutDir, unit, "tfplan.json");
+        return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : undefined;
+    };
+    const parts = terragruntWaveParts({ units: input.units, report, planFor, planner: terragruntPlanner(input.binary) });
+    const inWave = new Set(input.units);
+    const mocked = terragruntMockWarnings(`${r.stderr}\n${r.stdout}`, dirsOf(input.dir)).filter((m) => inWave.has(m.unit));
+    return {
+        parts: input.provisional ? markProvisional(parts) : failMockedParts(parts, mocked),
+        provisional: input.provisional === true,
+        results: terragruntUnitResults(input.units, report),
+        code: r.code,
+        log: r.stderr,
+    };
+}
+/**
+ * Apply one planned wave from its saved plans, with the same filters. Refuses
+ * before running anything when a unit of the wave has no saved plan, since
+ * Terragrunt would plan it afresh and apply a plan nobody saw, and when the
+ * plans are provisional.
+ */
+export async function applyTerragruntWave(input) {
+    const exec = input.exec ?? defaultTerragruntExec;
+    const tg = input.terragrunt ?? "terragrunt";
+    const work = resolve(input.dir, input.workDir);
+    const outDir = join(work, "plans");
+    if (input.provisional || existsSync(join(work, PROVISIONAL_MARKER))) {
+        throw new TerragruntError(`the plans under ${work} are provisional: planned before their upstream applied, possibly on mock_outputs. ` +
+            `They are never applied; plan the wave again once its upstream applied`);
+    }
+    const missing = [...new Set(input.units)].sort().filter((u) => !existsSync(join(outDir, u, "tfplan.tfplan")));
+    if (missing.length > 0) {
+        throw new TerragruntError(`no saved plan for ${missing.join(", ")} under ${outDir}; plan the wave before applying it, so apply runs the plan that was reviewed`);
+    }
+    const reportFile = join(work, "apply-report.json");
+    rmSync(reportFile, { force: true });
+    mkdirSync(dirname(reportFile), { recursive: true });
+    const args = terragruntWaveArgs({
+        units: input.units,
+        command: "apply",
+        outDir,
+        reportFile,
+        ...(input.destroy ? { destroy: true } : {}),
+        ...(input.parallelism !== undefined ? { parallelism: input.parallelism } : {}),
+    });
+    const r = await exec(tg, args, { cwd: input.dir, env: terragruntEnv(input.binary) });
+    const report = existsSync(reportFile) ? parseTerragruntReport(readFileSync(reportFile, "utf8")) : new Map();
+    return { results: terragruntUnitResults(input.units, report), code: r.code, log: r.stderr };
+}

package/dist/terragrunt/units.js

@@ -0,0 +1,195 @@
+/**
+ * Terragrunt units as roots (#3414): what a unit is, how discovery finds the
+ * units, and how the unit graph orders them into waves.
+ *
+ * A Terragrunt unit is a root: its own state, plan file and plan digest. The
+ * units and their edges come from `terragrunt find --json --dag
+ * --dependencies`, run by Terragrunt itself, so chant never evaluates
+ * Terragrunt's HCL to learn the graph. Directories that group units (implicit
+ * stacks) are labels: a unit's stack is its parent directory.
+ *
+ * This module runs nothing and imports only chant's `gated-waves` subpath, so
+ * terragucci can bundle it without TypeScript (#3421). `./run.ts` spawns.
+ */
+import { layerWaves } from "@intentius/chant/gated-waves";
+/** The oldest Terragrunt this runner drives: `run --all`, `find --dag` and `--filter` as 1.1 ships them. */
+export const TERRAGRUNT_MIN_VERSION = "1.1.0";
+/**
+ * Filters every discovery adds: catalog unit templates, which parse only
+ * inside a stack, and Terragrunt's module cache. A project's own `exclude`
+ * globs are added after these.
+ */
+export const TERRAGRUNT_DISCOVERY_EXCLUDES = ["catalog/**", "**/.terragrunt-cache/**"];
+/** Read `terragrunt --version` output (`terragrunt version v1.1.6`). Undefined when no version is in it. */
+export function parseTerragruntVersion(output) {
+    const m = /v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(output);
+    if (!m)
+        return undefined;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), ...(m[4] ? { pre: m[4] } : {}), raw: m[0] };
+}
+/**
+ * Why this Terragrunt cannot run units, or undefined when it can. A release
+ * candidate of 1.1.0 or later counts as that release line.
+ */
+export function terragruntVersionProblem(output) {
+    const v = parseTerragruntVersion(output);
+    if (!v)
+        return `could not read a version from \`terragrunt --version\` (got ${JSON.stringify(output.trim().slice(0, 80))})`;
+    const [minMajor, minMinor] = TERRAGRUNT_MIN_VERSION.split(".").map(Number);
+    if (v.major > minMajor || (v.major === minMajor && v.minor >= minMinor))
+        return undefined;
+    return `Terragrunt ${v.raw} is older than ${TERRAGRUNT_MIN_VERSION}, the oldest release chant runs units with (run --all, find --dag and --filter as 1.1 ships them)`;
+}
+/** A path filter that selects exactly one unit. Braced so a path with glob characters stays a path. */
+export function unitPathFilter(path) {
+    return `{./${path}}`;
+}
+/** A filter that drops everything under `glob`, relative to where discovery runs. */
+export function excludeFilter(glob) {
+    return `!./${glob.replace(/^\.\//, "")}`;
+}
+/**
+ * Arguments to `terragrunt` for discovery. `.terragrunt-filters` is read, as
+ * Terragrunt reads it by default; the excludes narrow what it selects.
+ */
+export function terragruntFindArgs(options = {}) {
+    const excludes = [...TERRAGRUNT_DISCOVERY_EXCLUDES, ...(options.exclude ?? [])];
+    return [
+        "find",
+        "--json",
+        "--dag",
+        "--dependencies",
+        "--include",
+        "--reading",
+        "--no-color",
+        ...excludes.flatMap((g) => ["--filter", excludeFilter(g)]),
+    ];
+}
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : []);
+const clean = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+/**
+ * The units in `find --json` output, in the order Terragrunt printed them
+ * (its DAG order under `--dag`). Stacks and anything else that is not a unit
+ * are left out. Throws when the output is not a JSON array.
+ */
+export function parseTerragruntFind(output) {
+    const doc = typeof output === "string" ? JSON.parse(output.trim() === "" ? "[]" : output) : output;
+    if (!Array.isArray(doc))
+        throw new Error("terragrunt find --json did not print an array");
+    const units = [];
+    for (const raw of doc) {
+        if (!isObject(raw) || raw.type !== "unit" || typeof raw.path !== "string")
+            continue;
+        const include = isObject(raw.include)
+            ? Object.fromEntries(Object.entries(raw.include).filter((e) => typeof e[1] === "string").map(([k, v]) => [k, clean(v)]))
+            : undefined;
+        const reading = Array.isArray(raw.reading) ? strings(raw.reading).map(clean) : undefined;
+        units.push({
+            path: clean(raw.path),
+            dependencies: [...new Set(strings(raw.dependencies).map(clean))].sort(),
+            ...(include && Object.keys(include).length > 0 ? { include } : {}),
+            ...(reading ? { reading } : {}),
+        });
+    }
+    return units;
+}
+/** A unit's implicit stack: its parent directory, or `.` for a unit at the top. */
+export function stackOfUnit(path) {
+    const i = path.lastIndexOf("/");
+    return i <= 0 ? "." : path.slice(0, i);
+}
+/** Whether `path` matches `glob` (`*` within a segment, `**` across segments, `?` one character). */
+export function matchesUnitGlob(path, glob) {
+    const g = clean(glob);
+    let re = "";
+    for (let i = 0; i < g.length; i++) {
+        const c = g[i];
+        if (c === "*" && g[i + 1] === "*") {
+            // `a/**/b` and `a/**` also match zero directories.
+            if (g[i + 2] === "/") {
+                re += "(?:.*/)?";
+                i += 2;
+            }
+            else {
+                re += ".*";
+                i += 1;
+            }
+        }
+        else if (c === "*")
+            re += "[^/]*";
+        else if (c === "?")
+            re += "[^/]";
+        else
+            re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${re}$`).test(path);
+}
+/** The units, as the nodes gated waves (#3049) and a fan-out (#2417) layer. */
+export function terragruntWaveNodes(units) {
+    return units.map((u) => ({ name: u.path, dependsOn: u.dependencies }));
+}
+/** Thrown when units cannot be cut into waves. The message names the units. */
+export class TerragruntWaveError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TerragruntWaveError";
+    }
+}
+/**
+ * Cut units into waves by Terragrunt's unit graph: each unit after every unit
+ * it depends on. A dependency outside `units` holds nothing back; it is not
+ * part of this change. Each wave is sorted by path.
+ *
+ * Canaries go first, layered among themselves, so a canary that reads
+ * another canary still waits for it to apply. A canary that depends on a unit
+ * of the set that is not a canary is refused: it would apply before what it
+ * reads.
+ */
+export function terragruntWaves(units, options = {}) {
+    const canaries = new Set((options.canary ?? []).flatMap((g) => units.filter((u) => matchesUnitGlob(u.path, g)).map((u) => u.path)));
+    const names = new Set(units.map((u) => u.path));
+    for (const u of units) {
+        if (!canaries.has(u.path))
+            continue;
+        const outside = u.dependencies.filter((d) => names.has(d) && !canaries.has(d));
+        if (outside.length > 0) {
+            throw new TerragruntWaveError(`canary ${u.path} depends on ${outside.join(", ")}, which is not a canary, so the canary wave would apply it first`);
+        }
+    }
+    const nodes = terragruntWaveNodes(units);
+    const layer = (subset) => {
+        try {
+            return layerWaves(subset);
+        }
+        catch (err) {
+            throw new TerragruntWaveError(err instanceof Error ? err.message : String(err));
+        }
+    };
+    return [...layer(nodes.filter((n) => canaries.has(n.name))), ...layer(nodes.filter((n) => !canaries.has(n.name)))];
+}
+/**
+ * Every unit that depends on one of `changed`, directly or through other
+ * units, not counting `changed` itself. Sorted by path.
+ *
+ * `find` reports `dependency` and ordering-only `dependencies` edges as one
+ * list, so this follows both. A caller that follows `dependency` edges only
+ * passes `edges` built from the units' own blocks.
+ */
+export function terragruntDependents(units, changed, edges = (u) => u.dependencies) {
+    const seeds = new Set(changed.map(clean));
+    const reached = new Set(seeds);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const u of units) {
+            if (reached.has(u.path))
+                continue;
+            if (edges(u).some((d) => reached.has(d))) {
+                reached.add(u.path);
+                grew = true;
+            }
+        }
+    }
+    return [...reached].filter((p) => !seeds.has(p)).sort();
+}

package/dist/terragrunt/wave.js

@@ -0,0 +1,125 @@
+/**
+ * One wave of Terragrunt units as one `terragrunt run --all` (#3414): the
+ * arguments, the environment, the run report and the change-set parts.
+ *
+ * A wave names its units with explicit path filters, so it plans and applies
+ * exactly those units. `.terragrunt-filters` is not read by a wave run:
+ * Terragrunt unions its filters with the ones given on the command line
+ * (observed on 1.1.6), so a filters file selecting `live/prod/**` would pull
+ * every prod unit into every wave. Discovery reads it; the wave's paths came
+ * from discovery.
+ *
+ * Plan writes `<outDir>/<unit>/tfplan.tfplan` and
+ * `<jsonOutDir>/<unit>/tfplan.json`; apply reads the saved plans from the
+ * same `outDir` with the same filters.
+ *
+ * Pure: nothing here spawns or reads files, so terragucci can bundle it. It
+ * imports `../change-set` and chant's `change-set` types only.
+ */
+import { terraformChangeSetPart } from "../change-set.js";
+import { stackOfUnit, unitPathFilter } from "./units.js";
+/** Arguments to `terragrunt` for one wave. Throws on an empty wave: with no filter, `run --all` runs every unit. */
+export function terragruntWaveArgs(input) {
+    if (input.units.length === 0)
+        throw new Error("a Terragrunt wave needs at least one unit; with no path filter run --all would run every unit");
+    if (input.parallelism !== undefined && (!Number.isInteger(input.parallelism) || input.parallelism < 1)) {
+        throw new Error(`parallelism must be a whole number of 1 or more, got ${input.parallelism}`);
+    }
+    const units = [...new Set(input.units)].sort();
+    const args = [
+        "run",
+        "--all",
+        "--non-interactive",
+        "--no-color",
+        "--no-filters-file",
+        ...units.flatMap((u) => ["--filter", unitPathFilter(u)]),
+        ...(input.destroy ? ["--filter-allow-destroy"] : []),
+        "--out-dir",
+        input.outDir,
+        ...(input.command === "plan" && input.jsonOutDir ? ["--json-out-dir", input.jsonOutDir] : []),
+        "--report-file",
+        input.reportFile,
+        "--report-format",
+        "json",
+        ...(input.parallelism !== undefined ? ["--parallelism", String(input.parallelism)] : []),
+        "--",
+        input.command,
+        ...(input.command === "plan" && input.destroy ? ["-destroy"] : []),
+        ...(input.extra ?? []),
+    ];
+    return args;
+}
+/**
+ * The environment a wave adds: `TG_TF_PATH` when the project names a binary,
+ * nothing otherwise, so Terragrunt's own choice (tofu, then terraform, or a
+ * unit's `terraform_binary`) stands.
+ */
+export function terragruntEnv(binary) {
+    return binary ? { TG_TF_PATH: binary } : {};
+}
+/** The rows of a run report, keyed by unit path. Malformed rows are dropped. */
+export function parseTerragruntReport(text) {
+    const doc = typeof text === "string" ? JSON.parse(text.trim() === "" ? "[]" : text) : text;
+    const rows = Array.isArray(doc) ? doc : [];
+    const out = new Map();
+    for (const raw of rows) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        const r = raw;
+        if (typeof r.Name !== "string" || typeof r.Result !== "string")
+            continue;
+        const name = r.Name.replace(/\\/g, "/").replace(/^\.\//, "");
+        out.set(name, {
+            name,
+            result: r.Result,
+            ...(typeof r.Reason === "string" && r.Reason ? { reason: r.Reason } : {}),
+            ...(typeof r.Cause === "string" && r.Cause ? { cause: r.Cause.trim() } : {}),
+            ...(typeof r.Cmd === "string" ? { cmd: r.Cmd } : {}),
+            ...(typeof r.Started === "string" ? { started: r.Started } : {}),
+            ...(typeof r.Ended === "string" ? { ended: r.Ended } : {}),
+        });
+    }
+    return out;
+}
+/** Each of the wave's units against the run report. A unit the report leaves out failed: nothing says it ran. */
+export function terragruntUnitResults(units, report) {
+    return [...new Set(units)].sort().map((unit) => {
+        const row = report.get(unit);
+        if (!row)
+            return { unit, status: "failed", result: "not run", error: "not in Terragrunt's run report, so it did not run" };
+        if (row.result === "succeeded")
+            return { unit, status: "succeeded", result: row.result };
+        const why = [row.reason, row.cause].filter(Boolean).join(": ");
+        return { unit, status: "failed", result: row.result, error: `${row.result}${why ? ` (${why})` : ""}` };
+    });
+}
+/**
+ * The change-set parts of a planned wave: one member per unit, named by the
+ * unit's path. A unit the run report marks succeeded, with a plan JSON, goes
+ * through {@link terraformChangeSetPart}; any other is a failed member
+ * carrying the report's result, so a unit that never planned cannot read as
+ * planned with nothing to do.
+ */
+export function terragruntWaveParts(input) {
+    const scopeFor = input.scopeFor ?? stackOfUnit;
+    return terragruntUnitResults(input.units, input.report).map((r) => {
+        const scope = scopeFor(r.unit);
+        const plan = r.status === "succeeded" ? input.planFor(r.unit) : undefined;
+        if (r.status === "succeeded" && plan !== undefined) {
+            return terraformChangeSetPart({ member: r.unit, plan, planner: input.planner, ...(scope ? { scope } : {}) });
+        }
+        return {
+            member: {
+                member: r.unit,
+                lexicon: "terraform",
+                planner: input.planner,
+                ...(scope ? { scope } : {}),
+                status: "failed",
+                error: r.error ?? "Terragrunt reported the unit succeeded but wrote no plan JSON for it",
+                planDigest: null,
+                holes: [],
+            },
+            entries: [],
+        };
+    });
+}

package/dist/validate-cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+import { validate } from "./validate.js";
+// `validate` takes an optional { basePath }; defaults to the lexicon root.
+await validate();

package/dist/validate.js

@@ -0,0 +1,31 @@
+/**
+ * Validate generated lexicon-terraform artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with terraform-specific configuration.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts } from "@intentius/chant/codegen/validate";
+/**
+ * Empty, and correct empty (#2220). `requiredNames` names generated resource
+ * classes that must survive a regenerate, and this lexicon generates none:
+ * `codegen/generate.ts` writes `lexicon-terraform.json` as `{}` on purpose,
+ * because Terraform's resource surface lives in provider registries rather
+ * than in one upstream schema, and an estate's `.tf` files are read as they
+ * are. There is no name to require, so the list stays empty and the
+ * remaining checks (the artifacts exist, the registry parses, the surface
+ * snapshot) are what validate actually proves here.
+ */
+const REQUIRED_NAMES = [];
+/**
+ * Validate the generated lexicon-terraform artifacts.
+ */
+export async function validate(opts) {
+    const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+    return validateLexiconArtifacts({
+        lexiconJsonFilename: "lexicon-terraform.json",
+        requiredNames: REQUIRED_NAMES,
+        basePath,
+    });
+}