@intentius/chant-lexicon-terraform 0.124.31 → 0.124.32

package/dist/hcl/parse.js

@@ -0,0 +1,372 @@
+/**
+ * The one shared HCL parse for the terraform lexicon.
+ *
+ * Two entry points, one entity shape. `parseTerraformRootDir` reads the `.tf`
+ * files of a directory (non-recursive, matching Terraform's own module
+ * scoping) and is what `buildRoots()` calls. `parseTerraformRootContent` takes
+ * the joined-file string `chant audit` hands a lexicon for a discovered root
+ * module: every `.tf` in filename order behind a `# file: <name>` line comment.
+ * Both funnel through `blocksToEntities`, so an entity the audit path sees is
+ * the entity the build path sees.
+ *
+ * Core owns the parser glue: `loadHcl2json()` lazy-loads `@cdktn/hcl2json`
+ * (a ~1.8 MB wasm blob) and raises a one-line install hint when it is absent.
+ * `parseTerraformDir()` next to it is NOT reused: it returns carve's `TfGraph`,
+ * a scoring-and-excision shape with no room for the per-block bodies a
+ * serializer and the post-synth checks read. The import path is the wildcard
+ * core's exports map already carries (`"./*"` to `./src/*.ts`), so nothing
+ * changed in `packages/core/package.json` for this.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadHcl2json } from "@intentius/chant/terraform/hcl2json";
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+import { scanSuppressions, directivesFor } from "./suppressions.js";
+/** `entityType` per block kind. */
+export const TERRAFORM_TYPE = "Terraform::Terraform";
+export const PROVIDER_TYPE = "Terraform::Provider";
+export const RESOURCE_TYPE = "Terraform::Resource";
+export const DATA_TYPE = "Terraform::Data";
+export const MODULE_TYPE = "Terraform::Module";
+export const VARIABLE_TYPE = "Terraform::Variable";
+export const OUTPUT_TYPE = "Terraform::Output";
+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 = ["root.hcl", "terragrunt.hcl"];
+/** Whether `name` (a bare filename) is a Terragrunt config file this lexicon reads. */
+export function isTerragruntFileName(name) {
+    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";
+/** The expansion meta-argument a block body carries, if any. `count` wins if both are present (Terraform rejects that combination anyway). */
+function expansionOf(body) {
+    if ("count" in body)
+        return "count";
+    if ("for_each" in body)
+        return "for_each";
+    return undefined;
+}
+/**
+ * Build one entity. Written out rather than run through `createResource`
+ * from `@intentius/chant/runtime`: that factory is for generated resource
+ * classes and hides `props` behind a non-enumerable descriptor plus an
+ * `attrMap` of `AttrRef`s this lexicon has nothing to put in. The literal
+ * carries the same marker, so `isDeclarable()` and `isResourceDeclarable()`
+ * both hold.
+ */
+export function terraformEntity(entityType, address, body, file, root, extra, source = "", line, suppressions) {
+    const expansion = expansionOf(body);
+    return {
+        [DECLARABLE_MARKER]: true,
+        lexicon: "terraform",
+        entityType,
+        kind: "resource",
+        stack: root,
+        props: {
+            address,
+            body,
+            file,
+            root,
+            source,
+            line,
+            ...(expansion ? { expansion } : {}),
+            ...(extra?.mode !== undefined ? { mode: extra.mode } : {}),
+            ...(extra?.estate !== undefined ? { estate: extra.estate } : {}),
+            ...(extra?.workspace !== undefined ? { workspace: extra.workspace } : {}),
+            ...(extra?.delete !== undefined ? { delete: extra.delete } : {}),
+            ...(extra?.configEstate !== undefined ? { configEstate: extra.configEstate } : {}),
+            ...(extra?.callers !== undefined && extra.callers.length > 0 ? { callers: extra.callers } : {}),
+        },
+        suppressions,
+    };
+}
+/** The `# file: <name>` boundary `chant audit` writes between joined `.tf` files. */
+const FILE_MARKER = /^# file: (.+)$/;
+/**
+ * Split the joined form back into files. A string with no marker at all is one
+ * anonymous file, so a caller that hands over a single `.tf` still parses.
+ */
+export function splitBundleContent(content, fallbackName = "main.tf") {
+    const files = [];
+    let current;
+    for (const line of content.split("\n")) {
+        const marker = FILE_MARKER.exec(line);
+        if (marker) {
+            current = { name: marker[1].trim(), source: "" };
+            files.push(current);
+            continue;
+        }
+        if (!current) {
+            current = { name: fallbackName, source: "" };
+            files.push(current);
+        }
+        current.source += current.source === "" ? line : `\n${line}`;
+    }
+    return files.filter((f) => f.source.trim() !== "");
+}
+/** Every `.tf` directly under `dir`, in filename order. Non-recursive. */
+export function listTerraformFiles(dir) {
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".tf"))
+        .sort();
+}
+/** The Terragrunt config files directly under `dir` (`root.hcl`, `terragrunt.hcl`), in filename order like the audit's bundle. */
+export function listTerragruntFiles(dir) {
+    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
+ * `estate = "..."` attribute, no wrapper block) and is never a `.tf` file, so
+ * it falls outside that glob and needs its own read.
+ */
+export function readLiveSidecarFile(dir) {
+    const path = join(dir, LIVE_SIDECAR_FILENAME);
+    if (!existsSync(path))
+        return undefined;
+    return { name: LIVE_SIDECAR_FILENAME, source: readFileSync(path, "utf-8") };
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+/** Every `live { ... }` block nested inside every `terraform { ... }` block of `tree`. */
+function liveBlocksIn(tree) {
+    const out = [];
+    for (const tfBody of asArray(tree["terraform"])) {
+        const body = asRecord(tfBody);
+        for (const liveBody of asArray(body["live"]))
+            out.push(asRecord(liveBody));
+    }
+    return out;
+}
+/** 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
+ * files of one root) are numbered `~2`, `~3` rather than overwriting.
+ *
+ * Recognises both ways an estate is declared: a `live { }` block nested in a
+ * `terraform { }` block of any file here, and, when `sidecar` is given, the
+ * `estate.chdf.hcl` sidecar's bare `estate = "..."` attribute. Either becomes
+ * a {@link LIVE_TYPE} entity, and the root is live (`mode: "live"`) exactly
+ * when `modeOptions.binary` is `"choudoufu"` and one of the two named an
+ * estate; that verdict, and the estate name when live, is then stamped onto
+ * every entity this call returns, sidecar and in-block declaration alike so
+ * a post-synth check or `describeResources()` reads it without re-parsing.
+ * When both forms are present the sidecar wins, matching choudoufu's own
+ * "the sidecar is the leading one" (choudoufu refuses the combination
+ * outright; this lexicon does not police that here, see TF024/TF025 for
+ * what it does police on a live root).
+ *
+ * `callers` is the module-call chain these files were reached through
+ * (chant #2112), empty for a root module. When it is non-empty the keys
+ * become `<root>/module.<name>/<address>` (one segment per caller) and every
+ * entity carries the chain on `props.callers`. `./descend.ts` is what fills
+ * it in; nothing else should pass it.
+ */
+export async function blocksToEntities(files, root, hcl2json, modeOptions, sidecar, callers = []) {
+    const parser = hcl2json ?? (await loadHcl2json());
+    const entities = new Map();
+    const prefix = callers.length > 0 ? `${root}/${callers.join("/")}` : root;
+    const add = (entityType, address, body, file, scan, scanAddress = address) => {
+        const { line, suppressions } = directivesFor(scan, scanAddress);
+        const entity = terraformEntity(entityType, address, (typeof body === "object" && body !== null ? body : {}), file.name, root, {
+            ...(modeOptions?.workspace !== undefined ? { workspace: modeOptions.workspace } : {}),
+            ...(modeOptions?.delete !== undefined ? { delete: modeOptions.delete } : {}),
+            ...(modeOptions?.configEstate !== undefined ? { configEstate: modeOptions.configEstate } : {}),
+            ...(callers.length > 0 ? { callers } : {}),
+        }, file.source, line, suppressions);
+        let key = `${prefix}/${address}`;
+        for (let n = 2; entities.has(key); n++)
+            key = `${prefix}/${address}~${n}`;
+        entities.set(key, entity);
+    };
+    /** `terraform` and `locals` carry no labels: the tree holds a bare body array. */
+    const unlabelled = (tree, section, entityType, file, scan) => {
+        for (const body of asArray(tree[section]))
+            add(entityType, section, body, file, scan);
+    };
+    /** `provider`, `module`, `variable`, `output`: one label, so `Record<name, body[]>`. */
+    const oneLabel = (tree, section, entityType, address, file, scan) => {
+        for (const [name, bodies] of Object.entries(asRecord(tree[section]))) {
+            for (const body of asArray(bodies))
+                add(entityType, address(name), body, file, scan);
+        }
+    };
+    /** `resource`, `data`: two labels, so `Record<type, Record<name, body[]>>`. */
+    const twoLabels = (tree, section, entityType, address, file, scan) => {
+        for (const [type, named] of Object.entries(asRecord(tree[section]))) {
+            for (const [name, bodies] of Object.entries(asRecord(named))) {
+                for (const body of asArray(bodies))
+                    add(entityType, address(type, name), body, file, scan);
+            }
+        }
+    };
+    for (const file of files) {
+        const tree = (await parser.parse(file.name, file.source));
+        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);
+        oneLabel(tree, "provider", PROVIDER_TYPE, (n) => `provider.${n}`, file, scan);
+        oneLabel(tree, "module", MODULE_TYPE, (n) => `module.${n}`, file, scan);
+        oneLabel(tree, "variable", VARIABLE_TYPE, (n) => `var.${n}`, file, scan);
+        oneLabel(tree, "output", OUTPUT_TYPE, (n) => `output.${n}`, file, scan);
+        twoLabels(tree, "resource", RESOURCE_TYPE, (t, n) => `${t}.${n}`, file, scan);
+        twoLabels(tree, "data", DATA_TYPE, (t, n) => `data.${t}.${n}`, file, scan);
+    }
+    if (sidecar) {
+        const tree = (await parser.parse(sidecar.name, sidecar.source));
+        if (typeof tree["estate"] === "string")
+            add(LIVE_TYPE, "live", tree, sidecar, scanSuppressions(sidecar.name, sidecar.source));
+    }
+    // Which of the (at most two) Live entities names the estate, preferring the
+    // sidecar over an in-block declaration when both are present.
+    let estate;
+    for (const entity of entities.values()) {
+        if (entity.entityType !== LIVE_TYPE)
+            continue;
+        const props = entity.props;
+        const name = typeof props.body["estate"] === "string" ? props.body["estate"] : undefined;
+        if (name === undefined)
+            continue;
+        if (estate === undefined || props.file === LIVE_SIDECAR_FILENAME)
+            estate = name;
+    }
+    const mode = modeOptions?.binary === "choudoufu" && estate !== undefined ? "live" : "state";
+    for (const [key, entity] of entities) {
+        const te = entity;
+        const stamped = {
+            ...te,
+            props: {
+                ...te.props,
+                mode,
+                ...(mode === "live" ? { estate } : {}),
+                ...(modeOptions?.lockFile !== undefined ? { lockFile: modeOptions.lockFile } : {}),
+            },
+        };
+        entities.set(key, stamped);
+    }
+    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, file, scan, add) {
+    const config = { 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
+ * parser throws for malformed HCL; `buildRoots()` is where that becomes a
+ * warning.
+ */
+export async function parseTerraformRootDir(dir, root, hcl2json, modeOptions, callers = []) {
+    // 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"),
+    }));
+    // A child module gets no sidecar read: `estate.chdf.hcl` declares the
+    // 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;
+    // 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);
+}
+/**
+ * Parse the joined-file string form `chant audit` produces for a discovered
+ * root module (`AuditInput.content`). `auditEntities()` is what calls it; that
+ * hook's single-argument contract carries no project config, so `modeOptions`
+ * is left undefined there and every entity gets `mode: "state"`; the audit
+ * path does not detect live mode (#2103). `modeOptions` exists here mainly for
+ * tests exercising the mode-stamping behaviour directly against inline HCL,
+ * the same way `parseTerraformRootDir`'s callers exercise it against files.
+ */
+export async function parseTerraformRootContent(content, root, hcl2json, modeOptions) {
+    return blocksToEntities(splitBundleContent(content), root, hcl2json, modeOptions);
+}
+/** The root name an audit of the audited directory itself parses under. */
+export const AUDIT_ROOT_NAME = "audit-root";
+/**
+ * The root name one `chant audit` input parses under (#2217).
+ *
+ * A build names its roots from `terraform.roots`; an audit has no such
+ * config, so the name comes from the input's own path, which is the one thing
+ * that tells two discovered roots apart. `envs/prod` becomes `envs.prod`,
+ * because an entity key is `<root>/<address>` with the module chain between
+ * them and a `/` inside the root name would read as a module scope. The
+ * audited directory itself keeps the name {@link AUDIT_ROOT_NAME}, so a
+ * single-root audit reads the way it did before an input path was available.
+ */
+export function auditRootName(path) {
+    const trimmed = (path ?? "").replace(/^\.\//, "").replace(/\/+$/, "");
+    if (trimmed === "" || trimmed === ".")
+        return AUDIT_ROOT_NAME;
+    return trimmed.replace(/\//g, ".");
+}
+/**
+ * The module scope an entity key names: the part before the address.
+ *
+ * `"app/aws_s3_bucket.assets"` is scope `"app"` (the root module);
+ * `"app/module.cdn/aws_s3_bucket.assets"` is scope `"app/module.cdn"`. Keys
+ * are built here (see {@link blocksToEntities}), so the split lives here too:
+ * the reference index (`./references.ts`) and the module-scoped checks read
+ * scopes through it rather than re-deriving the key shape.
+ */
+export function scopeOfKey(key) {
+    const slash = key.lastIndexOf("/");
+    return slash === -1 ? "" : key.slice(0, slash);
+}
+/** The `module.<name>` chain in an entity key, outermost first. Empty for a root-module block. */
+export function callersOfKey(key) {
+    const parts = key.split("/");
+    return parts.length <= 2 ? [] : parts.slice(1, -1);
+}

package/dist/hcl/references.js

@@ -0,0 +1,156 @@
+/**
+ * Which declarations does a module scope actually reference (chant #2112)?
+ *
+ * One pass over every entity's body, collecting the reference forms Terraform
+ * writes as expressions: `var.<name>`, `local.<name>`, `data.<type>.<name>`,
+ * `module.<name>`, and the `provider = <type>.<alias>` / `providers = { <type>
+ * = <type>.<alias> }` meta-arguments. The result is keyed per module scope
+ * (`./parse.ts`'s `scopeOfKey`), because Terraform's own namespaces are: a
+ * `var.region` inside `module.cdn` is the child module's variable, never the
+ * root's, and a rule that pooled the two would call a genuinely unused root
+ * variable used.
+ *
+ * ## It is a string scan, and the rules built on it say so
+ *
+ * hcl2json gives back an expression as a STRING, with the `${...}` wrapper
+ * preserved: `count = length(var.subnets)` arrives as `"${length(var.subnets)}"`
+ * and `bucket = var.name` as `"${var.name}"`. There is no expression tree to
+ * walk, so this scans the strings with regexes. That reads a reference inside
+ * a comment-free body correctly and is deliberately generous at the edges: a
+ * name that appears inside a quoted literal (`description = "set var.region"`)
+ * counts as a reference, and a reference built dynamically
+ * (`lookup(local.by_env, terraform.workspace)` reaching a value nothing names
+ * directly) does not. Both directions are why TF020 is report-only and credits
+ * tflint's `terraform_unused_declarations` as `overlaps` rather than
+ * `equivalent`: it is the same question answered with a coarser instrument.
+ *
+ * The index records WHICH entity each reference came from, so a check can ask
+ * "is anything other than the declaration itself referring to this?". A
+ * `variable "port"` whose own `validation` block reads `var.port` is the case
+ * that needs it: without the exclusion every validated variable would look
+ * used.
+ */
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { scopeOfKey } from "./parse.js";
+/** An identifier as Terraform's grammar allows it: letters, digits, `_`, `-`. */
+const NAME = "[A-Za-z_][A-Za-z0-9_-]*";
+const VAR_RE = new RegExp(`\\bvar\\.(${NAME})`, "g");
+const LOCAL_RE = new RegExp(`\\blocal\\.(${NAME})`, "g");
+const DATA_RE = new RegExp(`\\bdata\\.(${NAME})\\.(${NAME})`, "g");
+const MODULE_RE = new RegExp(`\\bmodule\\.(${NAME})`, "g");
+/** A provider reference once any `${...}` wrapper is off: `aws.west`. */
+const PROVIDER_REF_RE = new RegExp(`^(${NAME})\\.(${NAME})$`);
+/** hcl2json's wrapper around a bare expression, which a `provider` value always is. */
+const INTERPOLATION_RE = /^\$\{(.*)\}$/s;
+/**
+ * Every reference token in one string, in the vocabulary the index keys by:
+ * `var.region`, `local.tags`, `data.aws_ami.ubuntu`, `module.cdn`.
+ *
+ * `data.` is matched before `local.`/`var.` can see it, and a `module.cdn.url`
+ * yields `module.cdn`, since the call is what a reference makes used.
+ */
+export function collectReferences(text) {
+    const found = new Set();
+    for (const m of text.matchAll(DATA_RE))
+        found.add(`data.${m[1]}.${m[2]}`);
+    for (const m of text.matchAll(VAR_RE))
+        found.add(`var.${m[1]}`);
+    for (const m of text.matchAll(LOCAL_RE))
+        found.add(`local.${m[1]}`);
+    for (const m of text.matchAll(MODULE_RE))
+        found.add(`module.${m[1]}`);
+    return [...found];
+}
+/**
+ * The `provider`/`providers` meta-argument's own reference form, which is not
+ * an interpolation and has no prefix of its own: `provider = aws.west` names
+ * the `provider "aws" { alias = "west" }` block. Returned in the index's
+ * vocabulary, `provider.aws.west`, so it cannot collide with a resource
+ * address that happens to look the same.
+ */
+export function providerReference(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    const inner = INTERPOLATION_RE.exec(trimmed);
+    const m = PROVIDER_REF_RE.exec((inner ? inner[1] : trimmed).trim());
+    return m ? `provider.${m[1]}.${m[2]}` : undefined;
+}
+/** Every reference in one block body, provider meta-arguments included. */
+export function referencesInBody(body) {
+    const found = new Set();
+    const visit = (value, key, depth) => {
+        if (depth > 6)
+            return;
+        if (typeof value === "string") {
+            for (const ref of collectReferences(value))
+                found.add(ref);
+            if (key === "provider") {
+                const provider = providerReference(value);
+                if (provider)
+                    found.add(provider);
+            }
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, key, depth + 1);
+            return;
+        }
+        if (typeof value === "object" && value !== null) {
+            for (const [k, v] of Object.entries(value)) {
+                // `providers = { aws = aws.west }` maps a child module's provider name
+                // to the caller's block, so every VALUE under `providers` is a
+                // provider reference, whatever its key.
+                visit(v, key === "providers" ? "provider" : k, depth + 1);
+            }
+        }
+    };
+    visit(body, "", 0);
+    return [...found];
+}
+/**
+ * Build the index over a whole build's entities. Scopes come from the entity
+ * keys, so a root and each of its descended child modules are separate, and
+ * two roots never pool.
+ */
+export function buildReferenceIndex(entities) {
+    const scopes = new Map();
+    for (const [key, entity] of entities) {
+        if (!isResourceDeclarable(entity))
+            continue;
+        const props = entity.props;
+        const body = (typeof props.body === "object" && props.body !== null ? props.body : {});
+        const scope = scopeOfKey(key);
+        let refs = scopes.get(scope);
+        if (!refs) {
+            refs = new Map();
+            scopes.set(scope, refs);
+        }
+        for (const ref of referencesInBody(body)) {
+            const from = refs.get(ref);
+            if (from)
+                from.add(key);
+            else
+                refs.set(ref, new Set([key]));
+        }
+    }
+    return { scopes };
+}
+/** The entity keys in `scope` whose body references `token`. */
+export function referencesTo(index, scope, token) {
+    return index.scopes.get(scope)?.get(token) ?? new Set();
+}
+/**
+ * Is `token` referenced anywhere in `scope` other than by `declaredBy` itself?
+ * The exclusion is what keeps a variable read only by its own `validation`
+ * block, or a local read only by its own `locals` block, from looking used.
+ */
+export function isReferenced(index, scope, token, declaredBy) {
+    const from = referencesTo(index, scope, token);
+    for (const key of from) {
+        if (key !== declaredBy)
+            return true;
+    }
+    return false;
+}

package/dist/hcl/roots.js

@@ -0,0 +1,98 @@
+/**
+ * Terraform build roots.
+ *
+ * An estate that keeps its `.tf` tree has no typed chant source for it. What
+ * it can declare is the directory: each entry in `terraform.roots` names a
+ * root module that parses at build time into entities, so the blocks are
+ * serialized into the build output and seen by the post-synth checks. Same
+ * shape `lexicons/k8s/src/kustomize/root.ts` uses for kustomize overlays: the
+ * render lives here, the plugin's `buildRoots()` member stays thin.
+ *
+ * Unlike the kustomize renderer, a missing directory or a `.tf` the parser
+ * refuses is a warning and zero entities for that root, never a throw. Reading
+ * someone else's estate is the whole job here, and half of it parsing is more
+ * useful than none of it, especially when the audit path (#2085) walks
+ * repositories it did not write.
+ *
+ * A root's own directory is not the end of the parse: a `module` block with a
+ * local source is followed into its directory and parsed as a child scope of
+ * the root (#2112). `./descend.ts` owns that walk and every refusal in it; the
+ * refusals surface here as this render's warnings.
+ *
+ * One pass runs after every root has parsed: `./edges.ts` resolves each
+ * block's `${...}` references into the entity keys they name, so the graph IR
+ * has edges to draw (#2265). It runs here rather than inside the per-file
+ * parse because an edge's target may be a block in a file, or a child module,
+ * that has not been read yet.
+ */
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { LIVE_TYPE, parseTerraformRootDir } from "./parse.js";
+import { descendModules, resolveCallModuleType } from "./descend.js";
+import { resolveEntityReferences } from "./edges.js";
+/**
+ * Parse each configured root into entities keyed `<root>/<address>`, plus its
+ * local child modules, keyed `<root>/module.<name>/<address>` (#2112). Roots
+ * are visited in declaration order, and one root's failure never stops the
+ * next.
+ */
+export async function renderTerraformRoots(opts) {
+    const entities = new Map();
+    const warnings = [];
+    // One verdict for the whole render: the mode is a project-level setting, so
+    // a refused `"all"` is said once rather than once per root (#2112).
+    const callModuleType = resolveCallModuleType(opts.callModuleType);
+    if (callModuleType.warning)
+        warnings.push(callModuleType.warning);
+    for (const [name, root] of Object.entries(opts.roots)) {
+        const dir = isAbsolute(root.dir) ? root.dir : resolve(opts.projectRoot, root.dir);
+        if (!existsSync(dir)) {
+            warnings.push(`terraform.roots.${name}: directory not found at ${dir}, no entities contributed`);
+            continue;
+        }
+        try {
+            const modeOptions = { binary: opts.binary, workspace: root.workspace, delete: root.delete, configEstate: root.estate };
+            const parsed = await parseTerraformRootDir(dir, name, opts.hcl2json, modeOptions);
+            for (const [key, entity] of parsed)
+                entities.set(key, entity);
+            // Local child modules, keyed `<root>/module.<name>/<address>` (#2112).
+            // Their refusals are warnings on the root that called them, since the
+            // call site is where a reader can act on one.
+            const descended = await descendModules(parsed, {
+                dir,
+                root: name,
+                projectRoot: opts.projectRoot,
+                ...(opts.moduleRoot !== undefined ? { moduleRoot: isAbsolute(opts.moduleRoot) ? opts.moduleRoot : resolve(opts.projectRoot, opts.moduleRoot) } : {}),
+                callModuleType: callModuleType.effective,
+                hcl2json: opts.hcl2json,
+                modeOptions,
+            });
+            for (const [key, entity] of descended.entities)
+                entities.set(key, entity);
+            warnings.push(...descended.warnings);
+            // A `live` block or `estate.chdf.hcl` sidecar only takes effect under
+            // choudoufu; under any other binary it parses fine but is inert, which
+            // is worth a warning rather than silence (#2103).
+            for (const entity of parsed.values()) {
+                if (entity.entityType !== LIVE_TYPE || !isResourceDeclarable(entity))
+                    continue;
+                if (entity.props.mode === "state") {
+                    warnings.push(`terraform.roots.${name}: declares a live estate (a \`live\` block or ${JSON.stringify("estate.chdf.hcl")} sidecar), but terraform.binary is ${JSON.stringify(opts.binary ?? "terraform")}, not "choudoufu", so the live declaration is inert.`);
+                }
+                break;
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            warnings.push(`terraform.roots.${name}: could not parse ${dir}, ${message}`);
+        }
+    }
+    // Every root and every descended child module is parsed by now, which is
+    // what reference resolution needs: an edge points at an entity key, and the
+    // keys only all exist once the last descent has run (#2265). One pass over
+    // the whole map, one expression cache, resolution still bounded to each
+    // block's own module scope.
+    await resolveEntityReferences(entities, opts.hcl2json);
+    return { entities, warnings };
+}