@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/applied-state.ts

@@ -0,0 +1,52 @@
+/**
+ * What applied, read from `show -json` of a plan made after the apply: its
+ * `prior_state` is the state the apply left (chant#4445). choudoufu refuses a
+ * bare `show` under a `live` block, since there is no state file to show, so
+ * a post-apply plan is the one place its applied values can be read.
+ *
+ * `chant terraform report` (`./report.ts`) and the composed estate run
+ * (`./compose/estate.ts`) both read through {@link priorStateValues}.
+ */
+
+type Json = Record<string, unknown>;
+
+const isObject = (v: unknown): v is Json => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * The `values` of the state a `show -json` holds: a plan's `prior_state`, or
+ * a state's own `values` when it is a `show -json` of state. Undefined when
+ * it holds neither.
+ */
+export function priorStateValues(show: unknown): Json | undefined {
+  const root = isObject(show) ? show : {};
+  const state = isObject(root.prior_state) ? root.prior_state : root;
+  return isObject(state.values) ? state.values : undefined;
+}
+
+/** One resource of a state: its values and its sensitivity map. */
+export interface StateResourceValues {
+  values: Json;
+  sensitive: Json;
+}
+
+/** Every resource of the state a `show -json` holds, by address. A deposed object is left out. */
+export function stateResources(show: unknown): Map<string, StateResourceValues> {
+  const out = new Map<string, StateResourceValues>();
+  const walk = (mod: unknown): void => {
+    if (!isObject(mod)) return;
+    for (const r of Array.isArray(mod.resources) ? mod.resources : []) {
+      if (!isObject(r) || typeof r.address !== "string" || r.deposed_key !== undefined) continue;
+      out.set(r.address, { values: isObject(r.values) ? r.values : {}, sensitive: isObject(r.sensitive_values) ? r.sensitive_values : {} });
+    }
+    for (const c of Array.isArray(mod.child_modules) ? mod.child_modules : []) walk(c);
+  };
+  walk(priorStateValues(show)?.root_module);
+  return out;
+}
+
+/** The outputs of the state a `show -json` holds, by name, each its value. */
+export function stateOutputs(show: unknown): Record<string, unknown> {
+  const outputs = priorStateValues(show)?.outputs;
+  if (!isObject(outputs)) return {};
+  return Object.fromEntries(Object.entries(outputs).map(([k, v]) => [k, isObject(v) && "value" in v ? v.value : v]));
+}

package/src/backend-config.test.ts

@@ -0,0 +1,105 @@
+/**
+ * A root can name backend-config files (chant#4459): the config key, the
+ * flags init gets, where a relative path resolves, and the keys the
+ * composition reads from a file before init.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { terraformRootSchema } from "./config";
+import { ROOT_ENTRY_KEYS } from "./lsp/option-keys";
+import { backendConfigArgs, backendConfigFileKeys, backendConfigFilePath, readBackendConfigFile } from "./backend-config";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { compositionFor } from "./compose";
+import { rootState } from "./compose/hcl";
+import { declaredBackend, lockRefusal, readBackend } from "./state/backend";
+
+const made: string[] = [];
+afterAll(() => {
+  for (const d of made) rmSync(d, { recursive: true, force: true });
+});
+
+function tree(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-4459-"));
+  made.push(dir);
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    writeFileSync(join(dir, path), text);
+  }
+  return dir;
+}
+
+const S3_NO_LOCK = 'terraform {\n  backend "s3" {\n    bucket = "b"\n  }\n}\n';
+
+describe("terraform.roots.<name>.backendConfigFiles", () => {
+  test("the config schema takes a list of paths beside backendConfig, and refuses anything else", () => {
+    expect(terraformRootSchema.safeParse({ dir: ".", backendConfigFiles: ["backend.hcl"], backendConfig: { key: "k" } }).success).toBe(true);
+    expect(terraformRootSchema.safeParse({ dir: ".", backendConfigFiles: "backend.hcl" }).success).toBe(false);
+    expect(terraformRootSchema.safeParse({ dir: ".", backendConfigFiles: [1] }).success).toBe(false);
+  });
+
+  test("the LSP offers the key on a root entry", () => {
+    expect(ROOT_ENTRY_KEYS.map((k) => k.key)).toContain("backendConfigFiles");
+  });
+
+  test("init's flags: files in order, then the pairs", () => {
+    expect(backendConfigArgs({ backendConfigFiles: ["a.hcl", "b.hcl"], backendConfig: { key: "k" } })).toEqual(["-backend-config=a.hcl", "-backend-config=b.hcl", "-backend-config=key=k"]);
+    expect(backendConfigArgs({})).toEqual([]);
+  });
+});
+
+describe("a backend-config file's keys", () => {
+  test("a relative path resolves against the root's directory, as varFiles does; an absolute one stays", () => {
+    expect(backendConfigFilePath("/repo/roots/app", "backend.hcl")).toBe("/repo/roots/app/backend.hcl");
+    expect(backendConfigFilePath("/repo/roots/app", "../shared/backend.hcl")).toBe("/repo/roots/shared/backend.hcl");
+    expect(backendConfigFilePath("/repo/roots/app", "/etc/backend.hcl")).toBe("/etc/backend.hcl");
+  });
+
+  test("a file's key = value lines, typed, comments and interpolations left out", () => {
+    const dir = tree({ "backend.hcl": '# shared\nbucket = "acme-state" // the bucket\nuse_lockfile = true\nmax_retries = 5\nkey = "${var.no}"\n' });
+    expect(readBackendConfigFile(join(dir, "backend.hcl"))).toEqual({ bucket: "acme-state", use_lockfile: true, max_retries: 5 });
+  });
+
+  test("later files over earlier ones, read from the root's directory, and a missing file named", () => {
+    const dir = tree({ "roots/app/one.hcl": 'bucket = "one"\nkey = "k"\n', "roots/shared/two.hcl": 'bucket = "two"\n' });
+    expect(backendConfigFileKeys(join(dir, "roots/app"), ["one.hcl", "../shared/two.hcl", "gone.hcl"])).toEqual({ config: { bucket: "two", key: "k" }, unread: ["gone.hcl"] });
+  });
+});
+
+describe("the composition reads the file's keys before init (ruled: yes)", () => {
+  test("an s3 root whose use_lockfile = true is only in the file is lockable", () => {
+    const dir = tree({ "main.tf": S3_NO_LOCK, "backend.hcl": 'key = "app.tfstate"\nuse_lockfile = true\n' });
+    expect(lockRefusal(readBackend(dir, { recorded: null }))).toMatchObject({ refused: "no-lockfile" });
+    expect(lockRefusal(readBackend(dir, { recorded: null, backendConfigFiles: ["backend.hcl"] }))).toBeUndefined();
+  });
+
+  test("a pair overrides the file, and the file overrides the code", () => {
+    const dir = tree({ "main.tf": 'terraform {\n  backend "s3" {\n    bucket = "code"\n    key = "code"\n  }\n}\n', "backend.hcl": 'bucket = "file"\nkey = "file"\n' });
+    expect(declaredBackend(dir, { backendConfigFiles: ["backend.hcl"], backendConfig: { key: "pair" } })).toEqual({ type: "s3", config: { bucket: "file", key: "pair" } });
+  });
+
+  test("a -backend-config file in TF_CLI_ARGS_init is read too", () => {
+    const dir = tree({ "main.tf": S3_NO_LOCK, "ci.hcl": "use_lockfile = true\n" });
+    expect(lockRefusal(readBackend(dir, { recorded: null, env: { TF_CLI_ARGS_init: "-backend-config=ci.hcl" } }))).toBeUndefined();
+  });
+
+  test("rootState finds the state's address from a key only the file gives", () => {
+    const dir = tree({ "main.tf": S3_NO_LOCK });
+    expect(rootState(dir, "app", { env: {}, recorded: null, backendConfig: { key: "from-file.tfstate" } }).own).toMatchObject({ key: "from-file.tfstate" });
+  });
+
+  test("a composition lines a read up with a member whose state key is only in its file", () => {
+    const tf = (name: string): DriverComponent => ({ name, dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: name }] }] });
+    const reader = 'data "terraform_remote_state" "a" {\n  backend = "s3"\n  config = {\n    bucket = "b"\n    key    = "a.tfstate"\n  }\n}\n\nresource "terraform_data" "x" {\n  input = data.terraform_remote_state.a.outputs.id\n}\n';
+    const lockedS3 = (key?: string): string => `terraform {\n  backend "s3" {\n    bucket = "b"\n${key ? `    key = "${key}"\n` : ""}    use_lockfile = true\n  }\n}\n`;
+    const dir = tree({ "roots/a/main.tf": lockedS3(), "roots/a/backend.hcl": 'key = "a.tfstate"\n', "roots/b/main.tf": lockedS3("b.tfstate") + reader });
+    const c = compositionFor({
+      projectRoot: dir,
+      env: {},
+      components: [tf("a"), tf("b")],
+      terraform: { roots: { a: { dir: "roots/a", backendConfigFiles: ["backend.hcl"] }, b: { dir: "roots/b" } }, compose: { enabled: true } },
+    });
+    expect(c.reads.get("b")).toEqual([{ via: "remote-state", upstream: "a", name: "a" }]);
+  });
+});

package/src/backend-config.ts

@@ -0,0 +1,133 @@
+/**
+ * A root's `-backend-config` (chant#4459): the files it names in
+ * `terraform.roots.<name>.backendConfigFiles` and the pairs in
+ * `backendConfig`, as the flags every init the lexicon runs passes, and the
+ * keys a file holds, as the readers that find a root's state before init see
+ * them.
+ *
+ * Files go first and pairs after, because init applies later flags over
+ * earlier ones and a pair is the more specific of the two. A file's path is
+ * passed as written: init runs in the root's directory, so a relative path
+ * resolves against it, as `varFiles` does. A reader of the file resolves it
+ * the same way.
+ *
+ * Plain node: `op/activities/terraform.ts` imports this, and it stays out of
+ * the HCL parser's dependency graph.
+ */
+
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+/** The two keys of a root that say what init's `-backend-config` flags are. */
+export interface BackendConfigFlags {
+  backendConfigFiles?: readonly string[];
+  backendConfig?: Readonly<Record<string, string>>;
+}
+
+/** The `-backend-config` values in the order init takes them: each file's path, then each `key=value` pair. Unquoted, one per flag. */
+export function backendConfigValues(root: BackendConfigFlags): string[] {
+  return [...(root.backendConfigFiles ?? []), ...Object.entries(root.backendConfig ?? {}).map(([k, v]) => `${k}=${v}`)];
+}
+
+/** {@link backendConfigValues} as argv: `-backend-config=<value>` each. */
+export function backendConfigArgs(root: BackendConfigFlags): string[] {
+  return backendConfigValues(root).map((v) => `-backend-config=${v}`);
+}
+
+/** A backend-config file's path as init in `dir` reads it: an absolute path as it is, a relative one against `dir`. */
+export function backendConfigFilePath(dir: string, file: string): string {
+  return isAbsolute(file) ? file : resolve(dir, file);
+}
+
+/**
+ * The text of `body` with everything nested deeper than `level` braces
+ * blanked, newlines kept, so only the attributes at that level are left to
+ * read. Strings are read through, so a brace in one does not count.
+ */
+export function blankBelow(body: string, level: number): string {
+  const out = body.split("");
+  let depth = 0;
+  let inString = false;
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i]!;
+    if (depth > level && c !== "\n") out[i] = " ";
+    if (inString) {
+      if (c === "\\") {
+        if (depth > level && body[i + 1] !== undefined && body[i + 1] !== "\n") out[i + 1] = " ";
+        i++;
+      } else if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') inString = true;
+    else if (c === "{") depth++;
+    else if (c === "}") depth--;
+  }
+  return out.join("");
+}
+
+/**
+ * The literal attributes of HCL text at brace depth `level` (0 for a file of
+ * bare attributes, 1 for the body of a block given with its header): plain
+ * strings, booleans and numbers, typed as init records them. A string with an
+ * interpolation, and anything that is not one line of `name = literal`, is
+ * left out. Comments are left to the caller to blank.
+ */
+export function literalAttributes(text: string, level: number): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const m of blankBelow(text, level).matchAll(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*("(?:[^"\\]|\\.)*"|true|false|-?\d+(?:\.\d+)?)\s*$/gm)) {
+    const raw = m[2]!;
+    if (raw.startsWith('"')) {
+      const s = raw.slice(1, -1);
+      if (/\$\{|%\{/.test(s)) continue;
+      out[m[1]!] = s.replace(/\\(.)/g, "$1");
+    } else out[m[1]!] = raw === "true" ? true : raw === "false" ? false : Number(raw);
+  }
+  return out;
+}
+
+/** HCL text with its `#`, `//` and `/* *\/` comments blanked, strings read through. */
+function withoutComments(text: string): string {
+  const out = text.split("");
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (inString) {
+      if (c === "\\") i++;
+      else if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') inString = true;
+    else if (c === "#" || (c === "/" && text[i + 1] === "/")) {
+      for (; i < text.length && text[i] !== "\n"; i++) out[i] = " ";
+    } else if (c === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      const stop = end < 0 ? text.length : end + 2;
+      for (; i < stop; i++) if (text[i] !== "\n") out[i] = " ";
+      i--;
+    }
+  }
+  return out.join("");
+}
+
+/** The keys one backend-config file sets: its top-level `key = "value"` lines. Throws when the file cannot be read. */
+export function readBackendConfigFile(path: string): Record<string, unknown> {
+  return literalAttributes(withoutComments(readFileSync(path, "utf-8")), 0);
+}
+
+/**
+ * The keys a root's backend-config files set, later files over earlier ones,
+ * each path resolved against `dir`; and the files that could not be read,
+ * which init itself will refuse.
+ */
+export function backendConfigFileKeys(dir: string, files: readonly string[] = []): { config: Record<string, unknown>; unread: string[] } {
+  const config: Record<string, unknown> = {};
+  const unread: string[] = [];
+  for (const f of files) {
+    try {
+      Object.assign(config, readBackendConfigFile(backendConfigFilePath(dir, f)));
+    } catch {
+      unread.push(f);
+    }
+  }
+  return { config, unread };
+}

package/src/behaviour/kinds.ts

@@ -138,6 +138,10 @@ const BLOCKS: Readonly<Record<string, string>> = {
   "Terraform::Module": "a call to a child module; the blocks the call expands to are entities of their own and carry the figures",
   "Terraform::Data": "a read of something that exists outside this root; whatever it reads is priced where it is declared",
   "Terraform::Live": "choudoufu's estate declaration, which names the ownership marker every resource of the root carries and holds nothing itself",
+  "Terraform::Moved": "an instruction to rename an address in state; the resource it names carries the figures",
+  "Terraform::Import": "an instruction to adopt an existing object into state; the resource it names carries the figures",
+  "Terraform::Removed": "an instruction to drop an address from state; nothing is created by it",
+  "Terraform::Check": "an assertion terraform evaluates after a plan or apply, which holds nothing in any account",
 };
 
 /**

package/src/behaviour/predict.ts

@@ -163,10 +163,13 @@ export const readTerraformDeclaration: TerraformDeclarationReader = async (cwd)
   const { config, configPath } = await loadChantConfigUpward(start);
   const namespace = (config as { terraform?: TerraformConfig }).terraform;
   const entities = new Map<string, TerraformBehaviourEntity>();
-  if (!namespace?.roots || Object.keys(namespace.roots).length === 0) return entities;
+  // A `signalOnly` root (#4484) builds nothing, as in `buildRoots`.
+  if (!namespace) return entities;
+  const roots = Object.fromEntries(Object.entries(namespace.roots ?? {}).filter(([, r]) => r.signalOnly !== true));
+  if (Object.keys(roots).length === 0) return entities;
   const rendered = await renderTerraformRoots({
     projectRoot: configPath ? dirname(configPath) : start,
-    roots: namespace.roots,
+    roots,
     binary: namespace.binary,
     callModuleType: namespace.callModuleType,
     moduleRoot: namespace.moduleRoot,

package/src/behaviour/reference-catalog.plugin.test.ts

@@ -0,0 +1,65 @@
+/**
+ * #4535: terraform's catalog is on the plugin, and what it reads there.
+ *
+ * A reader that asks each lexicon of a graph for its catalog (behold#1030)
+ * now finds terraform's. On a `chant graph` node (`Terraform::Resource`, no
+ * arguments in its attrs) no rule applies, so a declared terraform graph
+ * keeps exactly the edges its HCL references give it: on example-three-cloud's
+ * azure member that is also what behold's matcher added (nothing). On a node
+ * whose kind is the provider type and whose attrs are the block's arguments,
+ * each rule draws its edge.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { IRNode } from "@intentius/chant/graph-ir";
+import { reconstructIndexedEdges, refRuleId } from "@intentius/chant/graph-refs";
+import { TERRAFORM_REFERENCE_CATALOG } from "./reference-catalog";
+import { terraformPlugin } from "../plugin";
+
+const LEXICON = "terraform";
+
+function atPath(path: string, value: string): Record<string, unknown> {
+  const parts = path.split(".");
+  const build = (i: number): unknown => {
+    if (i === parts.length) return value;
+    const part = parts[i];
+    const isArr = part.endsWith("[]");
+    const inner = build(i + 1);
+    return { [isArr ? part.slice(0, -2) : part]: isArr ? [inner] : inner };
+  };
+  return build(0) as Record<string, unknown>;
+}
+
+describe("terraform reference catalog on the plugin", () => {
+  it("is the plugin's referenceCatalog", () => {
+    expect(terraformPlugin.referenceCatalog).toBe(TERRAFORM_REFERENCE_CATALOG);
+  });
+
+  describe("each targeted rule draws its edge on provider-typed nodes", () => {
+    for (const [i, rule] of TERRAFORM_REFERENCE_CATALOG.refs.entries()) {
+      if (!rule.targetKind) continue;
+      it(`${rule.from} ${rule.path} -> ${rule.targetKind}`, () => {
+        const value = `id-${i}`;
+        const nodes: IRNode[] = [
+          { id: `holder-${i}`, kind: rule.from, lexicon: LEXICON, attrs: atPath(rule.path, value) },
+          { id: `target-${i}`, kind: rule.targetKind!, lexicon: LEXICON, attrs: {}, physicalId: value },
+        ];
+        const out = reconstructIndexedEdges(nodes, [{ lexicon: LEXICON, catalog: TERRAFORM_REFERENCE_CATALOG }], () => ({ account: "declared" }));
+        expect(out.edges.find((e) => e.from === `holder-${i}` && e.to === `target-${i}`)?.rule).toBe(refRuleId(LEXICON, rule.from, rule.path));
+      });
+    }
+  });
+
+  describe("example-three-cloud's azure member (parity with behold's matcher)", () => {
+    const graph = JSON.parse(readFileSync(join(import.meta.dirname, "..", "__fixtures__", "three-cloud-azure.graph.json"), "utf-8")) as { nodes: IRNode[] };
+    const out = reconstructIndexedEdges(graph.nodes, [{ lexicon: LEXICON, catalog: TERRAFORM_REFERENCE_CATALOG }], () => ({ account: "declared" }));
+
+    it("adds no edge to a declared block graph, as the matcher added none", () => {
+      expect(graph.nodes.some((n) => n.kind === "Terraform::Resource")).toBe(true);
+      expect(out.edges).toEqual([]);
+      expect(out.ambiguous).toEqual([]);
+      expect(out.dangling).toEqual([]);
+    });
+  });
+});

package/src/behaviour/reference-catalog.ts

@@ -16,11 +16,22 @@
  * Every terraform `resource` block is `Terraform::Resource` to chant. A rule
  * keyed on that would apply to a VPC and an instance alike, so the nodes
  * `./request.ts` builds for the resolver carry the **provider type** as their
- * `kind` — `aws_subnet` — and the rules here are keyed the same way. That is
- * also why this catalog is not declared on the plugin as `referenceCatalog`:
- * `chant graph --live` builds its nodes with `kind: "Terraform::Resource"`
- * and attributes that carry no arguments at all, so declaring it there would
- * be a catalog that matched nothing and looked like coverage.
+ * `kind` — `aws_subnet` — and the rules here are keyed the same way.
+ *
+ * ## On the plugin (#4535)
+ *
+ * The plugin declares it as `referenceCatalog` since #4535, so a reader that
+ * asks every lexicon of a graph for its catalog (behold#1030's gate, before
+ * behold#1005 retires behold's name matcher) finds terraform's. What it
+ * matches depends on the nodes. A declared or live `chant graph` node is
+ * `Terraform::Resource`, with its provider type in `attrs.type` and no
+ * arguments in `attrs`, so no rule here reads it: those graphs keep the edges
+ * the HCL references and the state dependencies give them, and gain none. A
+ * node whose `kind` is the provider type and whose `attrs` are the block's
+ * arguments (`./request.ts`'s, an engine's instance roster) is what the rules
+ * are for. `chant graph --live` merges a catalog's edges with the
+ * observation's own since #4535; before, any catalog replaced them, which is
+ * what kept this one off the plugin.
  *
  * ## Two relations, and why the split matters to an engine
  *

package/src/behaviour/request.ts

@@ -329,8 +329,9 @@ function liveVerdictOf(address: string, plan: LivePlanIndex): LiveVerdict {
       kind: "unobserved",
       instances,
       // `no-credentials` is an observation reason and not a prediction one;
-      // the credential wording stays in the detail.
-      reason: unobserved.reason === "no-credentials" ? "read-failed" : unobserved.reason,
+      // the credential wording stays in the detail. `not-reached` is a
+      // stream's reason (#4451) and a live-plan omission never gives it.
+      reason: unobserved.reason === "no-credentials" || unobserved.reason === "not-reached" ? "read-failed" : unobserved.reason,
       detail: unobserved.detail,
     };
   }

package/src/change-set-instances.test.ts

@@ -0,0 +1,98 @@
+/**
+ * A `count = 3` resource's stored change set carries three node ids (#4454).
+ *
+ * The graph is read in process the way `chant graph --format ir` builds it
+ * for a terraform root: the root's entities, `buildGraphIr`, then
+ * `withInstanceNodes`. The plan is a `show -json` shape with one
+ * `resource_changes` row per instance, as terraform prints a `count` block.
+ */
+
+import { describe, expect, test } from "vitest";
+import { composeChangeSet, verifyChangeSetDigest } from "@intentius/chant/change-set";
+import { graphNodeFor, mapChangeSetToGraph } from "@intentius/chant/change-set-graph";
+import { buildGraphIr, withInstanceNodes } from "@intentius/chant/graph-ir";
+import { terraformChangeSetPart } from "./change-set";
+import { literalInstanceKeys, parseTerraformRootContent } from "./hcl/parse";
+
+const SOURCE = `resource "aws_eip" "pool" {
+  count  = 3
+  domain = "vpc"
+}
+
+resource "aws_s3_bucket" "logs" {
+  bucket = "logs"
+}
+`;
+
+const create = (address: string, index?: number) => ({
+  address,
+  mode: "managed",
+  type: address.split(".")[0],
+  name: address.split(".")[1]!.replace(/\[.*$/, ""),
+  ...(index !== undefined ? { index } : {}),
+  change: { actions: ["create"], before: null, after: { domain: "vpc" }, after_unknown: { id: true } },
+});
+
+const PLAN = {
+  format_version: "1.2",
+  resource_changes: [create("aws_eip.pool[0]", 0), create("aws_eip.pool[1]", 1), create("aws_eip.pool[2]", 2), create("aws_s3_bucket.logs")],
+};
+
+describe("instance nodes for a count block", () => {
+  test("a literal count gives the block three instance keys", () => {
+    expect(literalInstanceKeys({ count: 3 })).toEqual(["[0]", "[1]", "[2]"]);
+    expect(literalInstanceKeys({ count: "${var.n}" })).toBeUndefined();
+    expect(literalInstanceKeys({ for_each: { b: 1, a: 2 } })).toEqual(['["a"]', '["b"]']);
+    expect(literalInstanceKeys({ for_each: '${toset(["x", "y"])}' })).toEqual(['["x"]', '["y"]']);
+  });
+
+  test("the graph has the block node and one instance node per index, each naming the block", async () => {
+    const entities = await parseTerraformRootContent(SOURCE, "estate");
+    const ir = withInstanceNodes(buildGraphIr(entities), entities);
+    const pool = ir.nodes.filter((n) => n.id.startsWith("estate/aws_eip.pool"));
+    expect(pool.map((n) => [n.id, n.instanceOf ?? null, n.instanceKey ?? null])).toEqual([
+      ["estate/aws_eip.pool", null, null],
+      ["estate/aws_eip.pool[0]", "estate/aws_eip.pool", "[0]"],
+      ["estate/aws_eip.pool[1]", "estate/aws_eip.pool", "[1]"],
+      ["estate/aws_eip.pool[2]", "estate/aws_eip.pool", "[2]"],
+    ]);
+    expect(ir.groups.byStack?.estate).toEqual(expect.arrayContaining(["estate/aws_eip.pool[0]", "estate/aws_eip.pool[2]"]));
+  });
+
+  test("the stored change set carries three node ids for the three instances", async () => {
+    const entities = await parseTerraformRootContent(SOURCE, "estate");
+    const ir = withInstanceNodes(buildGraphIr(entities), entities);
+    const doc = composeChangeSet([terraformChangeSetPart({ member: "estate", plan: PLAN })]);
+    const mapped = mapChangeSetToGraph(doc, { member: "infra", at: null, ids: ir.nodes.map((n) => n.id) });
+
+    const pool = mapped.entries.filter((e) => e.type === "aws_eip");
+    expect(pool.map((e) => [e.address, e.node, e.instanceOf])).toEqual([
+      ["aws_eip.pool[0]", "infra/estate/aws_eip.pool[0]", "infra/estate/aws_eip.pool"],
+      ["aws_eip.pool[1]", "infra/estate/aws_eip.pool[1]", "infra/estate/aws_eip.pool"],
+      ["aws_eip.pool[2]", "infra/estate/aws_eip.pool[2]", "infra/estate/aws_eip.pool"],
+    ]);
+    expect(new Set(pool.map((e) => e.node)).size).toBe(3);
+    const logs = mapped.entries.find((e) => e.address === "aws_s3_bucket.logs")!;
+    expect(logs.node).toBe("infra/estate/aws_s3_bucket.logs");
+    expect(logs.instanceOf).toBeUndefined();
+    // Node ids are not hashed.
+    expect(mapped.digest).toBe(doc.digest);
+    expect(verifyChangeSetDigest(mapped)).toBe(true);
+  });
+
+  test("an instance the graph cannot count still gets its instance id, and a drift row the same", async () => {
+    const entities = await parseTerraformRootContent(SOURCE.replace("count  = 3", "count  = var.n"), "estate");
+    const ir = withInstanceNodes(buildGraphIr(entities), entities);
+    expect(ir.nodes.some((n) => n.instanceOf)).toBe(false);
+    const graph = { member: null, at: null, ids: ir.nodes.map((n) => n.id) };
+    expect(graphNodeFor({ member: "estate", planner: "terraform", address: "aws_eip.pool[1]" }, graph)).toMatchObject({
+      node: "estate/aws_eip.pool[1]",
+      instanceOf: "estate/aws_eip.pool",
+    });
+    // Under an expanded module call the module key sits on the call's segment (#4486).
+    expect(graphNodeFor({ member: "estate", planner: "terraform", address: "module.app[0].aws_eip.pool[1]" }, { ...graph, ids: ["estate/module.app/aws_eip.pool"] })).toEqual({
+      node: "estate/module.app[0]/aws_eip.pool[1]",
+      instanceOf: "estate/module.app/aws_eip.pool",
+    });
+  });
+});

package/src/changed-roots.ts

@@ -9,16 +9,19 @@
  * in a local module it calls (followed through modules that call modules),
  * or is one of its var files.
  *
- * The module calls are read with a regex over the root's `.tf` and `.tofu`
+ * The module calls are read with a regex over the root's HCL configuration
  * files, the way `./op/activities/live-detect.ts` reads a live block, so
- * this stays out of the HCL parser's dependency graph. Only a `source` that
+ * this stays out of the HCL parser's dependency graph. Which files those are
+ * follows the root's binary through the lexicon's one lister (chant#4457):
+ * `.tf`, plus `.tofu` for a tofu or choudoufu root. Only a `source` that
  * starts with `./` or `../` is followed; a registry or git source is a
  * version pin in the root's own files, which a change to it already touches.
  */
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, posix, relative, resolve, sep } from "node:path";
 import type { TerraformRootConfig } from "./config";
+import { isJsonConfigFile, listConfigFilesSafe } from "./hcl/files";
 
 /** `source = "./..."` or `"../..."` inside a module block. Other sources are not on disk here. */
 const LOCAL_SOURCE = /\bsource\s*=\s*"(\.{1,2}\/[^"]*)"/g;
@@ -31,17 +34,11 @@ function projectRelative(projectRoot: string, dir: string): string {
   return rel === "" ? "." : posix.normalize(rel).replace(/\/+$/, "");
 }
 
-/** Local module directories `dir` calls, read from its HCL files. */
-function localModuleDirs(dir: string): string[] {
-  let names: string[];
-  try {
-    names = readdirSync(dir);
-  } catch {
-    return [];
-  }
+/** Local module directories `dir` calls, read from the HCL configuration files `binary` reads. */
+function localModuleDirs(dir: string, binary?: string): string[] {
   const out: string[] = [];
-  for (const name of names) {
-    if (!name.endsWith(".tf") && !name.endsWith(".tofu")) continue;
+  for (const name of listConfigFilesSafe(dir, binary)) {
+    if (isJsonConfigFile(name)) continue;
     let text: string;
     try {
       text = readFileSync(join(dir, name), "utf8");
@@ -61,7 +58,7 @@ function localModuleDirs(dir: string): string[] {
  * Every path, relative to `projectRoot`, whose change touches `root`: its
  * directory, each local module it reaches, and its var files.
  */
-export function rootWatchPaths(projectRoot: string, root: Pick<TerraformRootConfig, "dir" | "varFiles">): string[] {
+export function rootWatchPaths(projectRoot: string, root: Pick<TerraformRootConfig, "dir" | "varFiles">, binary?: string): string[] {
   const rootDir = resolve(projectRoot, root.dir);
   const seen = new Set<string>();
   const queue = [rootDir];
@@ -69,7 +66,7 @@ export function rootWatchPaths(projectRoot: string, root: Pick<TerraformRootConf
     const dir = queue.shift()!;
     if (seen.has(dir)) continue;
     seen.add(dir);
-    queue.push(...localModuleDirs(dir));
+    queue.push(...localModuleDirs(dir, binary));
   }
   const paths = [...seen].map((d) => projectRelative(projectRoot, d));
   for (const file of root.varFiles ?? []) paths.push(projectRelative(projectRoot, resolve(rootDir, file)));
@@ -91,11 +88,12 @@ export function changedRoots(
   projectRoot: string,
   roots: Record<string, Pick<TerraformRootConfig, "dir" | "varFiles">>,
   changedFiles: readonly string[],
+  binary?: string,
 ): string[] {
   const files = changedFiles.map((f) => posix.normalize(f));
   const touched: string[] = [];
   for (const [name, root] of Object.entries(roots)) {
-    const watch = rootWatchPaths(projectRoot, root);
+    const watch = rootWatchPaths(projectRoot, root, binary);
     if (files.some((f) => watch.some((p) => covers(p, f)))) touched.push(name);
   }
   return touched.sort();

package/src/ci-setup.ts

@@ -0,0 +1,42 @@
+/**
+ * The engine install lines a Terraform project's pull request pipeline runs
+ * in chant's default image (#4550, `LexiconPlugin.ciSetup`): OpenTofu, and
+ * choudoufu when a root runs it. Each line skips the install when the binary
+ * is already on PATH.
+ *
+ * Whether a root runs choudoufu is read from the text of the project's
+ * `chant.config.ts` (`binary: "choudoufu"`), never by running it, as lexicon
+ * detection reads source.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PR_LOOP_SETUP } from "@intentius/chant/components/pr-pipeline";
+
+/** The choudoufu release the default lines install. A product's images pin their own. */
+export const CHOUDOUFU_CI_VERSION = "0.31.0";
+
+/** choudoufu into /usr/local/bin from its release archive. */
+export function choudoufuInstallLine(version = CHOUDOUFU_CI_VERSION): string {
+  const arch = `$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')`;
+  const url = `https://github.com/INTENTIUS/choudoufu/releases/download/v${version}/choudoufu_v${version}_linux_${arch}.tar.gz`;
+  return `command -v choudoufu >/dev/null 2>&1 || (mkdir -p /tmp/choudoufu && curl -fsSL "${url}" | tar -xz -C /tmp/choudoufu && install "$(find /tmp/choudoufu -type f -name choudoufu | head -n 1)" /usr/local/bin/choudoufu)`;
+}
+
+/** Whether the project's config names choudoufu as a root's binary. */
+export function usesChoudoufu(dir: string): boolean {
+  for (const name of ["chant.config.ts", "chant.config.mts", "chant.config.js"]) {
+    const file = join(dir, name);
+    if (!existsSync(file)) continue;
+    try {
+      if (/binary\s*:\s*["']choudoufu["']/.test(readFileSync(file, "utf-8"))) return true;
+    } catch {
+      // unreadable: no choudoufu line
+    }
+  }
+  return false;
+}
+
+/** The lines for the project at `dir`. */
+export function terraformCiSetup(ctx: { dir: string }): string[] {
+  return [...PR_LOOP_SETUP, ...(usesChoudoufu(ctx.dir) ? [choudoufuInstallLine()] : [])];
+}