@intentius/chant-lexicon-terraform 0.124.31 → 0.124.32

package/dist/generated/index.js

@@ -0,0 +1 @@
+export {};

package/dist/hcl/descend.js

@@ -0,0 +1,208 @@
+/**
+ * Descend into local child modules (chant #2112).
+ *
+ * `parseTerraformRootDir` reads one directory, non-recursively, which is
+ * Terraform's own root-module scoping and the right unit for a root-scoped
+ * check like TF001. Four rules need more than that: TF014 and TF015 are about
+ * what a CHILD module may contain, and TF020 needs every reference in a scope
+ * before it can call a declaration unused. This module supplies the missing
+ * half: a `module` block whose `source` is a local path names a directory,
+ * and that directory parses with the same `blocksToEntities` into entities
+ * keyed `<root>/module.<name>/<address>` carrying `props.callers`.
+ *
+ * ## What is followed, and what is not
+ *
+ * tflint's `--call-module-type` (three states, defaulting to `local`,
+ * https://github.com/terraform-linters/tflint/blob/master/docs/user-guide/calling-modules.md)
+ * is the model:
+ *
+ * - `local` (the default): only `./` and `../` sources are read. A registry
+ *   or git source is NOT fetched, so its contents are never linted and every
+ *   finding about it is reported against the call site instead, which is
+ *   where TF004 and TF005 already report. The skipped call sites are named in
+ *   a warning rather than passed over in silence.
+ * - `none`: no descent at all. A root then parses exactly as it did before
+ *   this module existed.
+ * - `all`: reserved. tflint means "fetch registry and git modules too", which
+ *   needs a `terraform init`/`terraform get` first so the modules are on disk
+ *   under `.terraform`. chant fetches nothing, so this is refused with a
+ *   message rather than quietly behaving like `local`.
+ *
+ * Two more refusals, both about staying inside the repository being read:
+ *
+ * - A source that resolves outside the project root is refused. `../` is a
+ *   legal Terraform source and a repository may legitimately share modules
+ *   between sibling roots, but reading above the project root means linting
+ *   files the project does not own, so the boundary is the project root and
+ *   crossing it is a warning, not a parse.
+ * - A source already on the current call chain is a cycle (`a` calls `b`
+ *   calls `a`) and stops there. The visited set is per chain, on RESOLVED
+ *   paths, so one module called from two different places is still read once
+ *   per call site, each under its own `module.<name>` key, the way
+ *   `terraform show -json` reports two `child_modules[]` entries for it.
+ *
+ * Everything here is best effort, like `./roots.ts`: an unreadable or
+ * unparseable child module is a warning and no entities, never a throw, since
+ * half a root parsed is more useful than none of it.
+ */
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { classifyModuleSource } from "../lint/post-synth/module-source.js";
+import { MODULE_TYPE, parseTerraformRootDir, } from "./parse.js";
+/**
+ * Resolve the configured `callModuleType` into one this lexicon implements.
+ * `"all"` is refused with a message naming what it would need; everything
+ * else passes through, and an absent value is `"local"`, tflint's default.
+ */
+export function resolveCallModuleType(value) {
+    if (value === "none")
+        return { effective: "none" };
+    if (value === "all") {
+        return {
+            effective: "none",
+            warning: 'terraform.callModuleType: "all" is not supported. It means "descend into registry and git ' +
+                "modules too\", which requires fetching them (`terraform init`/`terraform get`) first, and chant " +
+                'fetches nothing. Use "local" (the default, relative-path sources only) or "none". No module was descended into.',
+        };
+    }
+    return { effective: "local" };
+}
+const DEFAULT_MAX_DEPTH = 8;
+/** Is `path` inside `boundary` (or the boundary itself)? */
+function isInside(boundary, path) {
+    const rel = relative(boundary, path);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/** The `module` blocks of one scope, in `ctx.entities` order, with their sources read. */
+function moduleCallsOf(entities) {
+    const calls = [];
+    for (const entity of entities.values()) {
+        if (entity.entityType !== MODULE_TYPE || !isResourceDeclarable(entity))
+            continue;
+        const props = entity.props;
+        const body = (typeof props.body === "object" && props.body !== null ? props.body : {});
+        calls.push({
+            address: typeof props.address === "string" ? props.address : "module.?",
+            source: typeof body.source === "string" ? body.source : undefined,
+        });
+    }
+    return calls;
+}
+/**
+ * The mode and estate the scope's own entities carry.
+ *
+ * A child module directory holds no `live` block and no `estate.chdf.hcl`
+ * sidecar (choudoufu reads the estate declaration from the root's directory,
+ * and only there), so parsing it alone always lands on `mode: "state"`. The
+ * root's verdict is the root's, one root one mode, so it is copied down onto
+ * every descended entity rather than re-derived from files that cannot carry
+ * it.
+ */
+function scopeMode(entities) {
+    for (const entity of entities.values()) {
+        if (!isResourceDeclarable(entity))
+            continue;
+        const props = entity.props;
+        if (typeof props.mode !== "string")
+            continue;
+        return { mode: props.mode, ...(typeof props.estate === "string" ? { estate: props.estate } : {}) };
+    }
+    return {};
+}
+/** Rebuild `entity` with the parent scope's mode and estate on its props. */
+function withMode(entity, mode) {
+    if (mode.mode === undefined || !isResourceDeclarable(entity))
+        return entity;
+    const te = entity;
+    return {
+        ...te,
+        props: { ...te.props, mode: mode.mode, ...(mode.estate !== undefined ? { estate: mode.estate } : {}) },
+    };
+}
+/**
+ * Parse every local child module reachable from `scope`, recursively.
+ *
+ * `scope` is one already-parsed module scope: the root's own entities on the
+ * first call, a child's on a recursive one. Returned entities are the
+ * children's only, never the scope's own, so a caller merges them into the
+ * map it already has.
+ */
+export async function descendModules(scope, opts) {
+    const entities = new Map();
+    const warnings = [];
+    const mode = opts.callModuleType ?? "local";
+    if (mode === "none")
+        return { entities, warnings };
+    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const where = `terraform.roots.${opts.root}`;
+    // The project root is the boundary, except for a root module configured
+    // with a `dir` outside the project entirely (an absolute path to an estate
+    // kept elsewhere): there the root's own directory is the boundary, since
+    // the project root would refuse every module the root has. A declared
+    // `moduleRoot` (#2874) replaces both.
+    const boundary = opts.moduleRoot !== undefined
+        ? resolve(opts.moduleRoot)
+        : isInside(opts.projectRoot, opts.dir)
+            ? resolve(opts.projectRoot)
+            : resolve(opts.dir);
+    /** One scope's calls, with the chain that reached it and the paths already on that chain. */
+    const walk = async (scopeEntities, dir, callers, onChain) => {
+        const notFollowed = [];
+        for (const call of moduleCallsOf(scopeEntities)) {
+            if (call.source === undefined)
+                continue;
+            const classified = classifyModuleSource(call.source);
+            if (classified.kind !== "local") {
+                notFollowed.push(`${call.address} (${call.source})`);
+                continue;
+            }
+            const target = resolve(dir, call.source);
+            if (!isInside(boundary, target)) {
+                warnings.push(`${where}: ${call.address} sources ${JSON.stringify(call.source)}, which resolves outside the project ` +
+                    `root (${target}). chant does not read modules from outside the project it was pointed at, so that ` +
+                    "module is not parsed and any finding in it is not reported.");
+                continue;
+            }
+            if (onChain.includes(target)) {
+                warnings.push(`${where}: ${call.address} sources ${JSON.stringify(call.source)}, which is already on this call chain ` +
+                    `(${[...callers, call.address].join(" -> ")}). That is a cycle, so the descent stops here.`);
+                continue;
+            }
+            if (!existsSync(target) || !statSync(target).isDirectory()) {
+                warnings.push(`${where}: ${call.address} sources ${JSON.stringify(call.source)}, but no directory exists at ${target}, ` +
+                    "so the module is not parsed.");
+                continue;
+            }
+            if (callers.length >= maxDepth) {
+                warnings.push(`${where}: ${call.address} is more than ${maxDepth} module calls deep (${callers.join(" -> ")}), ` +
+                    "so the descent stops here.");
+                continue;
+            }
+            const chain = [...callers, call.address];
+            let child;
+            try {
+                child = await parseTerraformRootDir(target, opts.root, opts.hcl2json, opts.modeOptions, chain);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                warnings.push(`${where}: could not parse ${call.address} at ${target}, ${message}`);
+                continue;
+            }
+            const mode = scopeMode(scopeEntities);
+            for (const [key, entity] of child) {
+                const stamped = withMode(entity, mode);
+                child.set(key, stamped);
+                entities.set(key, stamped);
+            }
+            await walk(child, target, chain, [...onChain, target]);
+        }
+        if (notFollowed.length > 0) {
+            warnings.push(`${where}: not descending into ${notFollowed.join(", ")}. The source is a registry or git module and chant ` +
+                "fetches nothing, so the module's own contents are unchecked and every finding about it is reported " +
+                "against the module block at the call site.");
+        }
+    };
+    await walk(scope, opts.dir, [], [resolve(opts.dir)]);
+    return { entities, warnings };
+}

package/dist/hcl/edges.js

@@ -0,0 +1,287 @@
+/**
+ * Resolve each block's references into graph edges (chant #2265).
+ *
+ * `chant graph --format ir` used to emit a complete, module-descended,
+ * fully-attributed node set for a Terraform estate and zero edges. Core's
+ * `collectEdges` walks a node's config bag for `AttrRef` objects and `Ref`
+ * intrinsics; a block body out of hcl2json holds `"${aws_vpc.main.id}"`, a
+ * string, so the walk found nothing and said so. This module supplies what
+ * that walk cannot see: the references, already resolved to the entity keys
+ * `blocksToEntities` minted, published on each entity as core's lexicon-neutral
+ * `EntityReference` (see `@intentius/chant/graph-ir`).
+ *
+ * ## Where the reference forms come from
+ *
+ * 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/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`
+ * IS such a regex scan and stays one: it answers "is this declaration used
+ * anywhere", deliberately generously, for a report-only rule. An edge a
+ * renderer draws is a stricter claim and gets the stricter instrument.
+ *
+ * Each accessor the AST returns is classified by core's own `refFromAccessor`
+ * for the three forms it already knows (`<type>.<name>`, `module.<name>`,
+ * `data.<type>.<name>`), and here for the two it deliberately excludes as
+ * non-resources, `var.<name>` and `local.<name>`.
+ *
+ * ## Four decisions a renderer will draw
+ *
+ * **Which forms become edges.** All five: `resource`, `data`, `module`, `var`
+ * and `local`. The first three are uncontroversial. The last two are edges
+ * because this lexicon emits a NODE for every `variable` and every `locals`
+ * block, and on a real estate those are the majority of them (108 variables
+ * and 10 locals out of 247 nodes, on the estate the issue was filed against).
+ * Dropping their edges would leave nearly half the graph as unconnected cards,
+ * which is the same picture the zero-edge bug drew. "Which resources consume
+ * `var.region`" is also a question a reader of a root module actually asks,
+ * and `terraform graph` itself answers it.
+ *
+ * A `local.<name>` resolves to the `locals` BLOCK that declares that name,
+ * found by looking `name` up in each block's body, so two `locals` blocks in
+ * one scope resolve independently rather than both matching.
+ *
+ * `provider = aws.west` is NOT an edge. The reference names a `provider`
+ * block by type AND alias, and this lexicon's entity key for one is
+ * `provider.<type>` with the alias inside the body, so two aliased providers
+ * of one type key as `provider.aws` and `provider.aws~2` and the reference
+ * cannot be resolved to either without guessing. `./references.ts` still
+ * records it for TF020, where "is it used at all" is answerable without
+ * knowing which block.
+ *
+ * **`depends_on` is an edge.** It arrives from hcl2json as
+ * `["${aws_vpc.main}"]` under the key `depends_on`, so it resolves through the
+ * same path as any other reference and lands as `viaAttr: "depends_on"` with
+ * no `toAttr`, which is exactly what it is: an ordering edge with no attribute
+ * flowing along it.
+ *
+ * **`count` / `for_each` are block-to-block.** chant's entity is the block, so
+ * `count = 3` is one node and one edge, not three. The expansion itself is
+ * recorded on the entity (`props.expansion`, `./parse.ts`) rather than left to
+ * be inferred from a node count that never grows. A `count = length(var.x)`
+ * also yields a real edge to `var.x` through `viaAttr: "count"`, since the
+ * meta-argument is an expression like any other.
+ *
+ * **Attribute naming.** `viaAttr` is the consumer-side TOP-LEVEL attribute the
+ * reference sits under and `toAttr` the producer-side attribute it read, which
+ * is the same pair carve's `TfEdge` carries as `via` and `attrs` and the pair
+ * behold already renders. One edge per (consumer, producer, `viaAttr`), and
+ * `toAttr` is set only when that edge read exactly one producer attribute:
+ * `subnet_id = aws_subnet.a.id` gives `id`, while
+ * `tags = merge(aws_vpc.main.tags, { id = aws_vpc.main.id })` names two and
+ * gets none rather than an arbitrary one.
+ *
+ * ## Scope, and what is deliberately not resolved
+ *
+ * Resolution is bounded to the referring block's own module scope
+ * (`scopeOfKey`), which is Terraform's own namespace: a `var.region` inside
+ * `module.cdn` is the child module's variable and never the root's. That also
+ * means no edge ever crosses roots, which is correct and intended (#2265):
+ * separate roots read each other by NAME through a data source, never by
+ * reference, and a value-match pass over those is a consumer's job, not this
+ * one's.
+ */
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { loadHcl2json } from "@intentius/chant/terraform/hcl2json";
+import { refFromAccessor } from "@intentius/chant/terraform/graph";
+import { LOCALS_TYPE, scopeOfKey } from "./parse.js";
+/** An identifier as Terraform's grammar allows it. Same as `./references.ts`. */
+const NAME = "[A-Za-z_][A-Za-z0-9_-]*";
+/** `var.<name>` / `local.<name>` at the head of a traversal accessor. */
+const SCALAR_HEAD_RE = new RegExp(`^(var|local)\\.(${NAME})(?:\\.|$)`);
+/**
+ * Classify one AST traversal accessor. `var`/`local` are handled here because
+ * core's `refFromAccessor` excludes them by design (they are not carvable
+ * resources); everything else defers to it, quoted map keys and numeric
+ * indexes included.
+ */
+export function referenceFromAccessor(accessor) {
+    const scalar = SCALAR_HEAD_RE.exec(accessor);
+    if (scalar)
+        return { address: `${scalar[1]}.${scalar[2]}` };
+    return refFromAccessor(accessor) ?? undefined;
+}
+/** Every `${...}` string in a body, paired with the top-level attribute it sits under. */
+function expressionsInBody(body) {
+    const out = [];
+    const visit = (value, via, depth) => {
+        if (depth > 8)
+            return;
+        if (typeof value === "string") {
+            if (value.includes("${"))
+                out.push({ via, expression: value });
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, via, depth + 1);
+            return;
+        }
+        if (typeof value === "object" && value !== null) {
+            for (const [key, inner] of Object.entries(value)) {
+                visit(inner, depth === 0 ? key : via, depth + 1);
+            }
+        }
+    };
+    visit(body, "", 0);
+    return out;
+}
+/** The `${...}` strings of every entity in the map, deduplicated. */
+function allExpressions(entities) {
+    const seen = new Set();
+    for (const entity of entities.values()) {
+        if (!isResourceDeclarable(entity))
+            continue;
+        const body = bodyOf(entity);
+        for (const { expression } of expressionsInBody(body))
+            seen.add(expression);
+    }
+    return [...seen];
+}
+function bodyOf(entity) {
+    const props = entity.props;
+    return (typeof props.body === "object" && props.body !== null ? props.body : {});
+}
+/**
+ * Resolve every expression once through the AST. An expression the parser
+ * refuses in isolation resolves to no references: fewer edges, never a phantom
+ * one, which is the same trade `resolveExpressionRefs` makes in core.
+ */
+async function resolveAccessors(parser, expressions) {
+    const out = new Map();
+    for (const expression of expressions) {
+        try {
+            const found = await parser.getReferencesInExpression("expression.tf", expression);
+            out.set(expression, found.map((r) => r.value));
+        }
+        catch {
+            out.set(expression, []);
+        }
+    }
+    return out;
+}
+function buildScopeIndex(entities) {
+    const scopes = new Map();
+    for (const [key, entity] of entities) {
+        if (!isResourceDeclarable(entity))
+            continue;
+        const te = entity;
+        const address = te.props.address;
+        if (typeof address !== "string")
+            continue;
+        const scope = scopeOfKey(key);
+        let index = scopes.get(scope);
+        if (!index) {
+            index = { byAddress: new Map(), byLocal: new Map() };
+            scopes.set(scope, index);
+        }
+        // First key wins: two blocks that genuinely share an address are keyed
+        // `~2`, `~3` (`./parse.ts`), and a reference cannot say which it meant.
+        if (!index.byAddress.has(address))
+            index.byAddress.set(address, key);
+        if (te.entityType === LOCALS_TYPE) {
+            for (const name of Object.keys(bodyOf(te))) {
+                if (!index.byLocal.has(name))
+                    index.byLocal.set(name, key);
+            }
+        }
+    }
+    return scopes;
+}
+/** The entity key an address names within one scope, or undefined. */
+function resolveAddress(address, index) {
+    if (address.startsWith("local."))
+        return index.byLocal.get(address.slice("local.".length));
+    return index.byAddress.get(address);
+}
+/** Every reference in one body, as raw addresses paired with the attribute they sit under. */
+function rawReferences(body, accessors) {
+    const out = [];
+    for (const { via, expression } of expressionsInBody(body)) {
+        for (const accessor of accessors.get(expression) ?? []) {
+            const ref = referenceFromAccessor(accessor);
+            if (ref)
+                out.push({ address: ref.address, ...(ref.attr ? { attr: ref.attr } : {}), via });
+        }
+    }
+    return out;
+}
+/**
+ * The references one block declares, resolved to entity keys and collapsed to
+ * one entry per (producer, `viaAttr`). Sorted, so the IR a build emits is
+ * byte-stable across runs.
+ */
+export function referencesOfEntity(key, entity, scopes, accessors) {
+    const index = scopes.get(scopeOfKey(key));
+    if (!index)
+        return [];
+    const grouped = new Map();
+    for (const raw of rawReferences(bodyOf(entity), accessors)) {
+        const to = resolveAddress(raw.address, index);
+        if (!to || to === key)
+            continue;
+        const groupKey = `${to}${raw.via}`;
+        let group = grouped.get(groupKey);
+        if (!group) {
+            group = { to, viaAttr: raw.via, attrs: new Set() };
+            grouped.set(groupKey, group);
+        }
+        if (raw.attr)
+            group.attrs.add(raw.attr);
+    }
+    const out = [];
+    for (const { to, viaAttr, attrs } of grouped.values()) {
+        out.push({
+            to,
+            ...(viaAttr ? { viaAttr } : {}),
+            // Exactly one, or none: an edge carrying an arbitrary pick out of two
+            // would be a label a reader cannot trust.
+            ...(attrs.size === 1 ? { toAttr: [...attrs][0] } : {}),
+        });
+    }
+    return out.sort((a, b) => cmp(a.to, b.to) || cmp(a.viaAttr ?? "", b.viaAttr ?? ""));
+}
+/** Code-point ordering, so output does not depend on the machine's locale. */
+function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Stamp `references` onto every terraform entity in `entities`, in place.
+ *
+ * Takes the whole build's entity map rather than one root's, because one
+ * shared expression cache across every root is what keeps this to one wasm
+ * call per DISTINCT expression instead of one per occurrence. Resolution is
+ * still per module scope, so pooling the parse pools no references.
+ *
+ * Best effort, like everything else on this path: a parser that cannot be
+ * loaded, or one that does not expose the expression AST, leaves every entity
+ * unreferenced rather than failing a build over a diagram.
+ */
+export async function resolveEntityReferences(entities, hcl2json) {
+    const expressions = allExpressions(entities);
+    if (expressions.length === 0)
+        return;
+    let parser;
+    try {
+        parser = hcl2json ?? (await loadHcl2json());
+    }
+    catch {
+        return;
+    }
+    if (typeof parser.getReferencesInExpression !== "function")
+        return;
+    const accessors = await resolveAccessors(parser, expressions);
+    const scopes = buildScopeIndex(entities);
+    for (const [key, entity] of entities) {
+        if (!isResourceDeclarable(entity))
+            continue;
+        const te = entity;
+        const references = referencesOfEntity(key, te, scopes, accessors);
+        if (references.length === 0)
+            continue;
+        const stamped = { ...te, references };
+        entities.set(key, stamped);
+    }
+}