@intentius/chant-lexicon-terraform 0.60.0 → 0.61.0

package/src/hcl/edges.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Reference resolution and the graph IR it feeds (chant #2265, #2266).
+ *
+ * Everything here goes through `renderTerraformRoots` and then core's own
+ * `buildGraphIr`, which is the exact pair `chant graph --format ir` runs, so
+ * what is asserted is what a renderer receives. The fixture is
+ * `src/__fixtures__/graph-roots/`: two roots, a local child module, and one
+ * instance of every decision these issues asked to have pinned.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+import { buildGraphIr, entityReferences, entityStack, type IREdge } from "@intentius/chant/graph-ir";
+import type { Declarable } from "@intentius/chant/declarable";
+import { renderTerraformRoots } from "./roots";
+import { referenceFromAccessor } from "./edges";
+import type { TerraformEntity } from "./parse";
+
+const TREE = join(dirname(fileURLToPath(import.meta.url)), "..", "__fixtures__", "graph-roots");
+
+let entities: Map<string, Declarable>;
+let edges: IREdge[];
+let groups: ReturnType<typeof buildGraphIr>["groups"];
+
+beforeAll(async () => {
+  const rendered = await renderTerraformRoots({
+    projectRoot: TREE,
+    roots: { app: { dir: "./app" }, network: { dir: "./network" } },
+  });
+  expect(rendered.warnings).toEqual([]);
+  entities = rendered.entities;
+  const ir = buildGraphIr(entities);
+  edges = ir.edges;
+  groups = ir.groups;
+});
+
+/** The edge between two nodes through one consumer attribute, if there is one. */
+function edge(from: string, to: string, viaAttr: string): IREdge | undefined {
+  return edges.find((e) => e.from === from && e.to === to && e.viaAttr === viaAttr);
+}
+
+describe("referenceFromAccessor", () => {
+  it("classifies every form that becomes an edge", () => {
+    expect(referenceFromAccessor("aws_vpc.main.id")).toEqual({ address: "aws_vpc.main", attr: "id" });
+    expect(referenceFromAccessor("module.cdn.url")).toEqual({ address: "module.cdn", attr: "url" });
+    expect(referenceFromAccessor("data.aws_ami.ubuntu.id")).toEqual({
+      address: "data.aws_ami.ubuntu",
+      attr: "id",
+    });
+    expect(referenceFromAccessor("var.region")).toEqual({ address: "var.region" });
+    expect(referenceFromAccessor("local.tags")).toEqual({ address: "local.tags" });
+  });
+
+  it("reads no reference out of the meta-arguments that are not one", () => {
+    // `count.index`, `each.value`, `path.module`, `terraform.workspace` and
+    // `self.x` all look like `<head>.<name>` and none of them names a block.
+    expect(referenceFromAccessor("count.index")).toBeUndefined();
+    expect(referenceFromAccessor("each.value")).toBeUndefined();
+    expect(referenceFromAccessor("path.module")).toBeUndefined();
+    expect(referenceFromAccessor("terraform.workspace")).toBeUndefined();
+    expect(referenceFromAccessor("self.private_ip")).toBeUndefined();
+  });
+});
+
+describe("edges out of a parsed estate (#2265)", () => {
+  it("emits the whole edge set, and only it", () => {
+    expect(
+      edges.map((e) => [e.from, e.to, e.viaAttr ?? "", e.toAttr ?? ""].join(" ")),
+    ).toEqual([
+      "app/aws_instance.web app/aws_s3_bucket.assets depends_on ",
+      "app/aws_instance.web app/data.aws_iam_policy.boundary tags arn",
+      "app/aws_instance.web app/module.cdn depends_on ",
+      "app/aws_instance.web app/var.subnets count ",
+      "app/aws_instance.web app/var.subnets subnet_id ",
+      "app/module.cdn/aws_cloudfront_distribution.cdn app/module.cdn/var.bucket origin_id ",
+      "app/module.cdn app/aws_s3_bucket.assets bucket id",
+      "app/output.cdn_url app/module.cdn value url",
+      "app/provider.aws app/var.region region ",
+      "network/aws_vpc.main network/locals tags ",
+      "network/aws_vpc.main network/var.cidr cidr_block ",
+      "network/output.vpc_id network/aws_vpc.main value id",
+    ]);
+  });
+
+  it("makes a `module` reference an edge to the call block, in both directions of use", () => {
+    // The call reads a resource; an output reads the call.
+    expect(edge("app/module.cdn", "app/aws_s3_bucket.assets", "bucket")).toEqual({
+      from: "app/module.cdn",
+      to: "app/aws_s3_bucket.assets",
+      kind: "ref",
+      viaAttr: "bucket",
+      toAttr: "id",
+    });
+    expect(edge("app/output.cdn_url", "app/module.cdn", "value")?.toAttr).toBe("url");
+  });
+
+  it("makes `depends_on` an edge with no producer attribute", () => {
+    const ordering = edges.filter((e) => e.viaAttr === "depends_on");
+    expect(ordering.map((e) => e.to).sort()).toEqual(["app/aws_s3_bucket.assets", "app/module.cdn"]);
+    for (const e of ordering) expect(e.toAttr).toBeUndefined();
+  });
+
+  it("keeps a `count` block one node, and its edges block-to-block", () => {
+    const web = entities.get("app/aws_instance.web") as TerraformEntity;
+    // `count = length(var.subnets)` over a list: the declaration is one block,
+    // so it is one node whatever the count evaluates to, and the expansion is
+    // recorded rather than left to be inferred from a node count.
+    expect(web.props.expansion).toBe("count");
+    expect([...entities.keys()].filter((k) => k.startsWith("app/aws_instance.web"))).toEqual([
+      "app/aws_instance.web",
+    ]);
+    // The meta-argument is an expression like any other, so it carries an edge.
+    expect(edge("app/aws_instance.web", "app/var.subnets", "count")).toBeDefined();
+    // ...and reading `var.subnets[count.index]` elsewhere in the block is a
+    // second edge through a second attribute, not a second instance.
+    expect(edge("app/aws_instance.web", "app/var.subnets", "subnet_id")).toBeDefined();
+  });
+
+  it("makes `var` and `local` edges, and resolves a local to the block that declares it", () => {
+    expect(edge("network/aws_vpc.main", "network/var.cidr", "cidr_block")).toBeDefined();
+    expect(edge("network/aws_vpc.main", "network/locals", "tags")).toBeDefined();
+  });
+
+  it("names the consumer attribute on every edge and the producer attribute only when one was read", () => {
+    for (const e of edges) expect(e.viaAttr).toBeTruthy();
+    // `data.aws_iam_policy.boundary.arn` named exactly one producer attribute.
+    expect(edge("app/aws_instance.web", "app/data.aws_iam_policy.boundary", "tags")?.toAttr).toBe("arn");
+    // `[aws_s3_bucket.assets]` named none.
+    expect(edge("app/aws_instance.web", "app/aws_s3_bucket.assets", "depends_on")?.toAttr).toBeUndefined();
+  });
+
+  it("resolves a child module's references inside the child's own scope", () => {
+    // `var.bucket` in `module.cdn` is the CHILD's variable. The root declares
+    // no `var.bucket` at all, so a scope-blind resolution would have produced
+    // no edge here rather than the wrong one; the assertion that matters is
+    // that the edge lands on the child's key.
+    expect(
+      edge(
+        "app/module.cdn/aws_cloudfront_distribution.cdn",
+        "app/module.cdn/var.bucket",
+        "origin_id",
+      ),
+    ).toBeDefined();
+  });
+
+  it("draws no edge for a `provider` meta-argument", () => {
+    // `provider = aws.replica` names a block by type AND alias, which this
+    // lexicon's `provider.<type>` key cannot be resolved to without guessing.
+    expect(edges.some((e) => e.viaAttr === "provider")).toBe(false);
+  });
+
+  it("draws no edge between two roots", () => {
+    const rootOf = (id: string): string => id.split("/")[0];
+    for (const e of edges) expect(rootOf(e.from)).toBe(rootOf(e.to));
+  });
+
+  it("publishes the references on the entity, in core's lexicon-neutral shape", () => {
+    // The channel core reads (#2265): an entity key, plus the two attribute
+    // names `IREdge` carries. Nothing terraform-shaped crosses the boundary.
+    expect(entityReferences(entities.get("app/output.cdn_url")!)).toEqual([
+      { to: "app/module.cdn", viaAttr: "value", toAttr: "url" },
+    ]);
+    // An entity that references nothing carries no channel at all.
+    expect(entityReferences(entities.get("app/var.region")!)).toEqual([]);
+  });
+
+  it("drops a reference to something outside the graph rather than dangling it", () => {
+    // Only ids that are nodes become edges, so an entity key that never made
+    // it into the IR cannot leave a half-edge behind.
+    const ids = new Set([...entities.keys()]);
+    for (const e of edges) {
+      expect(ids.has(e.from)).toBe(true);
+      expect(ids.has(e.to)).toBe(true);
+    }
+  });
+});
+
+describe("grouping by root (#2266)", () => {
+  it("keys byStack by root name, one entry per declared root", () => {
+    expect(Object.keys(groups.byStack ?? {})).toEqual(["app", "network"]);
+    expect(groups.byStack?.["network"]).toEqual([
+      "network/aws_vpc.main",
+      "network/locals",
+      "network/output.vpc_id",
+      "network/var.cidr",
+    ]);
+  });
+
+  it("keeps byLexicon saying terraform", () => {
+    expect(Object.keys(groups.byLexicon ?? {})).toEqual(["terraform"]);
+    expect(groups.byLexicon?.["terraform"].length).toBe(
+      (groups.byStack?.["app"].length ?? 0) + (groups.byStack?.["network"].length ?? 0),
+    );
+  });
+
+  it("puts every node in exactly one root's bucket, the one its id is prefixed with", () => {
+    for (const [root, ids] of Object.entries(groups.byStack ?? {})) {
+      for (const id of ids) expect(id.startsWith(`${root}/`)).toBe(true);
+    }
+  });
+
+  it("says which unit an entity belongs to on the entity, not by convention on its id", () => {
+    expect(entityStack(entities.get("app/module.cdn/var.bucket")!)).toBe("app");
+    expect(entityStack(entities.get("network/aws_vpc.main")!)).toBe("network");
+  });
+});

package/src/hcl/edges.ts

@@ -0,0 +1,316 @@
+/**
+ * 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/parse.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, type Declarable } from "@intentius/chant/declarable";
+import type { EntityReference } from "@intentius/chant/graph-ir";
+import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/parse";
+import { refFromAccessor } from "@intentius/chant/terraform/graph";
+import { LOCALS_TYPE, scopeOfKey, type BlockBody, type TerraformEntity } from "./parse";
+
+/** 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})(?:\\.|$)`);
+
+/** One reference read out of a body, before it is resolved to an entity key. */
+interface RawReference {
+  /** The address in this lexicon's own vocabulary: `aws_vpc.main`, `var.region`, `local.tags`. */
+  address: string;
+  /** Producer-side attribute, when the accessor named one. */
+  attr?: string;
+  /** Consumer-side top-level attribute the reference sits under. */
+  via: string;
+}
+
+/**
+ * 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: string): { address: string; attr?: string } | undefined {
+  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: BlockBody): Array<{ via: string; expression: string }> {
+  const out: Array<{ via: string; expression: string }> = [];
+  const visit = (value: unknown, via: string, depth: number): void => {
+    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 as Record<string, unknown>)) {
+        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: ReadonlyMap<string, Declarable>): string[] {
+  const seen = new Set<string>();
+  for (const entity of entities.values()) {
+    if (!isResourceDeclarable(entity)) continue;
+    const body = bodyOf(entity as TerraformEntity);
+    for (const { expression } of expressionsInBody(body)) seen.add(expression);
+  }
+  return [...seen];
+}
+
+function bodyOf(entity: TerraformEntity): BlockBody {
+  const props = entity.props as Partial<TerraformEntity["props"]>;
+  return (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+}
+
+/**
+ * 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: Hcl2Json,
+  expressions: readonly string[],
+): Promise<Map<string, string[]>> {
+  const out = new Map<string, string[]>();
+  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;
+}
+
+/** Address to entity key, and local name to the `locals` block declaring it, per module scope. */
+export interface ScopeIndex {
+  byAddress: Map<string, string>;
+  byLocal: Map<string, string>;
+}
+
+function buildScopeIndex(entities: ReadonlyMap<string, Declarable>): Map<string, ScopeIndex> {
+  const scopes = new Map<string, ScopeIndex>();
+  for (const [key, entity] of entities) {
+    if (!isResourceDeclarable(entity)) continue;
+    const te = entity as TerraformEntity;
+    const address = (te.props as Partial<TerraformEntity["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: string, index: ScopeIndex): string | undefined {
+  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: BlockBody, accessors: ReadonlyMap<string, readonly string[]>): RawReference[] {
+  const out: RawReference[] = [];
+  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: string,
+  entity: TerraformEntity,
+  scopes: ReadonlyMap<string, ScopeIndex>,
+  accessors: ReadonlyMap<string, readonly string[]>,
+): EntityReference[] {
+  const index = scopes.get(scopeOfKey(key));
+  if (!index) return [];
+
+  const grouped = new Map<string, { to: string; viaAttr: string; attrs: Set<string> }>();
+  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: EntityReference[] = [];
+  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: string, b: string): number {
+  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: Map<string, Declarable>,
+  hcl2json?: Hcl2Json,
+): Promise<void> {
+  const expressions = allExpressions(entities);
+  if (expressions.length === 0) return;
+
+  let parser: Hcl2Json;
+  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 as TerraformEntity;
+    const references = referencesOfEntity(key, te, scopes, accessors);
+    if (references.length === 0) continue;
+    const stamped: TerraformEntity = { ...te, references };
+    entities.set(key, stamped);
+  }
+}

package/src/hcl/parse.ts

@@ -22,6 +22,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/parse";
 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";
 import type { TerraformDeleteMode } from "../config";
 import { scanSuppressions, directivesFor, type FileScan } from "./suppressions";
@@ -29,6 +30,18 @@ import { scanSuppressions, directivesFor, type FileScan } from "./suppressions";
 /** A parsed HCL block body, as `@cdktf/hcl2json` encodes it. */
 export type BlockBody = Record<string, unknown>;
 
+/**
+ * The meta-argument that expands a block into instances, when it carries one
+ * (chant #2265). Recorded because chant's entity is the BLOCK, one node
+ * whatever `count` evaluates to, so an edge out of an expanded block is
+ * block-to-block and says nothing about how many instances reference how many
+ * others. That is the honest shape for a read of the declaration alone, since
+ * the instance count is a plan-time answer and often a state-time one, but it
+ * is a shape a reader should be told rather than left to infer from a node
+ * count that never grows.
+ */
+export type TerraformExpansion = "count" | "for_each";
+
 /** Whether a root runs under choudoufu with a declared estate (#2103). */
 export type TerraformRootMode = "live" | "state";
 
@@ -99,7 +112,37 @@ export interface TerraformEntity extends Declarable {
      * quotes still exist. Empty when a caller built the entity by hand.
      */
     readonly source: string;
+    /**
+     * `count` or `for_each` when the block carries one (chant #2265). See
+     * {@link TerraformExpansion} for why one node still stands for the whole
+     * expansion.
+     */
+    readonly expansion?: TerraformExpansion;
   };
+  /**
+   * The deployable unit this entity belongs to: the root name, which is what
+   * one `terraform apply` runs against (chant #2266).
+   *
+   * Duplicates `props.root`, deliberately. `props` is what this lexicon's own
+   * checks and serializer read; `stack` is the lexicon-neutral field core's
+   * `buildGraphIr` reads to key `groups.byStack`, so a five-root project draws
+   * as five boundary boxes instead of one bucket named `terraform`. Core has
+   * no business reaching into a lexicon's `props` to find out, and this
+   * lexicon has no business knowing how the grouping is built, so the fact is
+   * said once in each vocabulary. A child module's blocks carry the calling
+   * ROOT's name, not the module's: the module is not separately applied.
+   */
+  readonly stack: string;
+  /**
+   * Every reference in this block, resolved to the entity keys it points at
+   * (chant #2265), in core's lexicon-neutral {@link EntityReference} shape.
+   *
+   * Absent until `./edges.ts` resolves it, which needs the whole root's entity
+   * set and so cannot happen inside the per-file parse below. An entity that
+   * never went through that pass carries none, which reads as "no references
+   * were resolved", never as "this block references nothing".
+   */
+  readonly references?: readonly EntityReference[];
   /**
    * `# chant-ignore`/`chant-ignore-file`/`chant-ignore-block` directives that
    * apply to this entity (chant #2111): the ones anchored to its own block,
@@ -126,6 +169,13 @@ export const LIVE_TYPE = "Terraform::Live";
 /** 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: BlockBody): TerraformExpansion | undefined {
+  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
@@ -145,11 +195,13 @@ export function terraformEntity(
   line?: number,
   suppressions?: readonly SuppressionDirective[],
 ): TerraformEntity {
+  const expansion = expansionOf(body);
   return {
     [DECLARABLE_MARKER]: true,
     lexicon: "terraform",
     entityType,
     kind: "resource",
+    stack: root,
     props: {
       address,
       body,
@@ -157,6 +209,7 @@ export function terraformEntity(
       root,
       source,
       line,
+      ...(expansion ? { expansion } : {}),
       ...(extra?.mode !== undefined ? { mode: extra.mode } : {}),
       ...(extra?.estate !== undefined ? { estate: extra.estate } : {}),
       ...(extra?.workspace !== undefined ? { workspace: extra.workspace } : {}),

package/src/hcl/roots.ts

@@ -18,6 +18,12 @@
  * 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";
@@ -27,6 +33,7 @@ import type { Hcl2Json } from "@intentius/chant/terraform/parse";
 import type { TerraformRootConfig } from "../config";
 import { LIVE_TYPE, parseTerraformRootDir } from "./parse";
 import { descendModules, resolveCallModuleType, type CallModuleType } from "./descend";
+import { resolveEntityReferences } from "./edges";
 
 export interface TerraformRootsResult {
   entities: Map<string, Declarable>;
@@ -117,5 +124,12 @@ export async function renderTerraformRoots(
     }
   }
 
+  // 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 };
 }

package/src/index.ts

@@ -66,6 +66,7 @@ export {
   renderAdoptionLedger,
   type AdoptionCandidate,
   type AdoptionLedger,
+  type AdoptionMatch,
 } from "./op/adoption";
 
 // The Init/Plan/Gate/Apply composite (#2086).