@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/src/hcl/files.ts

@@ -0,0 +1,234 @@
+/**
+ * Which files of a directory are a root's configuration, and how a JSON-syntax
+ * one reads (chant#4457). Every lister in the lexicon asks here, so the parser,
+ * change detection, the backend readers, the report and the rollout pin all
+ * see the same file set for one root.
+ *
+ * The set follows the root's binary. Terraform reads `.tf` and `.tf.json`.
+ * OpenTofu (and choudoufu, which is OpenTofu) also reads `.tofu` and
+ * `.tofu.json`, and when `x.tofu` and `x.tf` both exist it reads `x.tofu`
+ * only (likewise `x.tofu.json` over `x.tf.json`). A binary that is not given
+ * is `terraform`, the config's default.
+ *
+ * `parse.ts` re-exports all of this; the module is separate so the readers
+ * that never parse HCL (`state/backend.ts`, `changed-roots.ts`) do not load
+ * the parser's dependencies.
+ */
+
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** The configuration file suffixes Terraform reads. */
+export const TERRAFORM_SUFFIXES: readonly string[] = [".tf", ".tf.json"];
+/** The ones OpenTofu reads as well. */
+export const TOFU_SUFFIXES: readonly string[] = [".tofu", ".tofu.json"];
+
+/** Whether a root run by `binary` reads `.tofu` files: `tofu` and `choudoufu` do (by name or path), `terraform` and an unset binary do not. */
+export function readsTofuFiles(binary?: string): boolean {
+  const base = (binary ?? "terraform").split(/[\\/]/).pop() ?? "";
+  return base.startsWith("tofu") || base.startsWith("choudoufu");
+}
+
+/** Whether `name` is a configuration file in Terraform's JSON syntax (`.tf.json`, `.tofu.json`). */
+export function isJsonConfigFile(name: string): boolean {
+  return name.endsWith(".tf.json") || name.endsWith(".tofu.json");
+}
+
+/** Whether `name` is a `.tofu` or `.tofu.json` file. */
+export function isTofuConfigFile(name: string): boolean {
+  return TOFU_SUFFIXES.some((s) => name.endsWith(s));
+}
+
+/** Whether `name` is a configuration file a root run by `binary` reads, before the `.tofu`-over-`.tf` rule. */
+export function isConfigFileFor(name: string, binary?: string): boolean {
+  if (TERRAFORM_SUFFIXES.some((s) => name.endsWith(s))) return true;
+  return readsTofuFiles(binary) && isTofuConfigFile(name);
+}
+
+/**
+ * The configuration files among `names` a root run by `binary` reads, in
+ * filename order. For a tofu or choudoufu root, `x.tf` is dropped when
+ * `x.tofu` is present and `x.tf.json` when `x.tofu.json` is, which is
+ * OpenTofu's own rule. Names may carry a directory; the rule compares names
+ * in the same directory.
+ */
+export function selectConfigFiles(names: Iterable<string>, binary?: string): string[] {
+  const kept = [...names].filter((n) => isConfigFileFor(n, binary));
+  const present = new Set(kept);
+  return kept
+    .filter((n) => {
+      if (n.endsWith(".tf")) return !present.has(`${n.slice(0, -".tf".length)}.tofu`);
+      if (n.endsWith(".tf.json")) return !present.has(`${n.slice(0, -".tf.json".length)}.tofu.json`);
+      return true;
+    })
+    .sort();
+}
+
+/**
+ * The configuration files directly under `dir` a root run by `binary` reads,
+ * by name, in filename order. Non-recursive, matching Terraform's module
+ * scoping; directories named like a file are left out. Throws when `dir`
+ * cannot be read.
+ */
+export function listConfigFiles(dir: string, binary?: string): string[] {
+  const files = readdirSync(dir).filter((n) => {
+    if (!isConfigFileFor(n, binary)) return false;
+    try {
+      return statSync(join(dir, n)).isFile();
+    } catch {
+      return false;
+    }
+  });
+  return selectConfigFiles(files, binary);
+}
+
+/** {@link listConfigFiles}, empty when `dir` cannot be read. */
+export function listConfigFilesSafe(dir: string, binary?: string): string[] {
+  try {
+    return listConfigFiles(dir, binary);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The nested blocks a JSON-syntax body can carry that hcl2json would give as
+ * arrays, by block type: each entry is the nested block's label count and its
+ * own nested blocks. Anything not named here is an attribute and is kept as
+ * written, since JSON syntax cannot tell a nested block from an object
+ * attribute without the provider's schema.
+ */
+interface BlockShape {
+  labels: number;
+  nested?: Record<string, BlockShape>;
+  /**
+   * Attributes JSON syntax writes as a bare expression in a string (a type,
+   * a reference), where HCL writes the expression itself and hcl2json gives
+   * it as `"${...}"`. Their strings are wrapped the same way.
+   */
+  exprs?: readonly string[];
+}
+
+const LIFECYCLE: BlockShape = { labels: 0, exprs: ["ignore_changes", "replace_triggered_by"] };
+const RESOURCE_NESTED: Record<string, BlockShape> = {
+  lifecycle: LIFECYCLE,
+  provisioner: { labels: 1, nested: { connection: { labels: 0 } } },
+  connection: { labels: 0 },
+};
+const REFERS = ["provider", "depends_on"];
+
+const TOP_LEVEL: Record<string, BlockShape> = {
+  terraform: {
+    labels: 0,
+    nested: {
+      backend: { labels: 1 },
+      cloud: { labels: 0, nested: { workspaces: { labels: 0 } } },
+      required_providers: { labels: 0 },
+      provider_meta: { labels: 1 },
+      live: { labels: 0 },
+    },
+  },
+  locals: { labels: 0 },
+  provider: { labels: 1 },
+  module: { labels: 1, exprs: ["depends_on", "providers"] },
+  variable: { labels: 1, nested: { validation: { labels: 0 } }, exprs: ["type"] },
+  output: { labels: 1, nested: { precondition: { labels: 0 } }, exprs: ["depends_on"] },
+  resource: { labels: 2, nested: RESOURCE_NESTED, exprs: REFERS },
+  data: { labels: 2, nested: { lifecycle: LIFECYCLE }, exprs: REFERS },
+  moved: { labels: 0, exprs: ["from", "to"] },
+  import: { labels: 0, exprs: ["to", "provider"] },
+  removed: { labels: 0, nested: { lifecycle: LIFECYCLE, provisioner: RESOURCE_NESTED.provisioner! }, exprs: ["from"] },
+  check: { labels: 1, nested: { data: { labels: 2 }, assert: { labels: 0 } } },
+};
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** A bare expression string as hcl2json writes the expression: `aws.west` becomes `${aws.west}`; a template is kept. */
+function asExpression(v: unknown): unknown {
+  if (typeof v === "string") return v.includes("${") ? v : `\${${v}}`;
+  if (Array.isArray(v)) return v.map(asExpression);
+  if (isObject(v)) return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, asExpression(x)]));
+  return v;
+}
+
+/** A JSON body with its `"//"` comment keys dropped (Terraform ignores them), its known nested blocks wrapped and its expression attributes written as hcl2json writes them. */
+function normaliseBody(body: unknown, shape: BlockShape): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!isObject(body)) return out;
+  for (const [k, v] of Object.entries(body)) {
+    if (k === "//") continue;
+    const inner = shape.nested?.[k];
+    out[k] = inner ? wrapBlock(v, inner) : shape.exprs?.includes(k) ? asExpression(v) : v;
+  }
+  return out;
+}
+
+/**
+ * A block in JSON syntax as hcl2json gives the same block in HCL: one object
+ * level per label, then an array of bodies. JSON syntax writes a single body
+ * as an object or several as an array, and allows an array of objects at a
+ * label level to be merged, so both are read.
+ */
+function wrapBlock(value: unknown, shape: BlockShape, labels = shape.labels): unknown {
+  if (labels === 0) return (Array.isArray(value) ? value : [value]).filter(isObject).map((b) => normaliseBody(b, shape));
+  const out: Record<string, unknown> = {};
+  for (const part of Array.isArray(value) ? value : [value]) {
+    if (!isObject(part)) continue;
+    for (const [label, inner] of Object.entries(part)) {
+      if (label === "//") continue;
+      const wrapped = wrapBlock(inner, shape, labels - 1);
+      const had = out[label];
+      if (Array.isArray(had) && Array.isArray(wrapped)) out[label] = [...had, ...wrapped];
+      else if (isObject(had) && isObject(wrapped)) out[label] = mergeLabelled(had, wrapped);
+      else out[label] = wrapped;
+    }
+  }
+  return out;
+}
+
+function mergeLabelled(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    const had = out[k];
+    if (Array.isArray(had) && Array.isArray(v)) out[k] = [...had, ...v];
+    else if (isObject(had) && isObject(v)) out[k] = mergeLabelled(had, v);
+    else out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * A `.tf.json` or `.tofu.json` document in the tree shape hcl2json gives an
+ * HCL file, so `blocksToEntities` reads both the same way. Top-level keys it
+ * does not know are kept as written. Throws on malformed JSON, as hcl2json
+ * throws on malformed HCL.
+ */
+export function jsonConfigTree(source: string): Record<string, unknown> {
+  const doc: unknown = JSON.parse(source);
+  if (!isObject(doc)) throw new Error("a JSON configuration file must hold an object");
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(doc)) {
+    if (k === "//") continue;
+    const shape = TOP_LEVEL[k];
+    out[k] = shape ? wrapBlock(v, shape) : v;
+  }
+  return out;
+}
+
+/**
+ * The bodies of the `live` blocks nested in the `terraform` blocks of a
+ * `.tf.json` or `.tofu.json` document, in the order written (chant#4504).
+ * The fast live readers (`report.ts`'s `estateOfDir`, `op/activities/live-detect.ts`)
+ * read HCL by text and a JSON file through this. Malformed JSON reads as no
+ * `live` block, as those readers treat any file they cannot read.
+ */
+export function jsonLiveBlocks(source: string): Record<string, unknown>[] {
+  let tree: Record<string, unknown>;
+  try {
+    tree = jsonConfigTree(source);
+  } catch {
+    return [];
+  }
+  const terraform = Array.isArray(tree.terraform) ? tree.terraform : [];
+  return terraform.flatMap((t) => (isObject(t) && Array.isArray(t.live) ? t.live.filter(isObject) : []));
+}

package/src/hcl/instance-forms.test.ts

@@ -0,0 +1,94 @@
+/**
+ * The expansion forms #4489 counts, and the rollup reason on every block the
+ * declared graph still leaves as one node. The fixture is
+ * `src/__fixtures__/instance-forms/app/`, built as `chant graph --format ir`
+ * builds a terraform root's graph.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+import { buildGraphIr, withInstanceNodes, type GraphIR, type IRNode } from "@intentius/chant/graph-ir";
+import { INSTANCE_ROLLUP_CODES } from "@intentius/chant/instance-nodes";
+import type { Declarable } from "@intentius/chant/declarable";
+import { renderTerraformRoots } from "./roots";
+
+const TREE = join(dirname(fileURLToPath(import.meta.url)), "..", "__fixtures__", "instance-forms");
+
+let entities: Map<string, Declarable>;
+let ir: GraphIR;
+
+beforeAll(async () => {
+  const rendered = await renderTerraformRoots({ projectRoot: TREE, roots: { estate: { dir: "./app" } } });
+  entities = rendered.entities;
+  ir = withInstanceNodes(buildGraphIr(entities), entities);
+});
+
+function instancesOf(block: string): string[] {
+  return ir.nodes.filter((n) => n.instanceOf === block).map((n) => n.id).sort();
+}
+
+function node(id: string): IRNode {
+  const n = ir.nodes.find((x) => x.id === id);
+  if (!n) throw new Error(`no node ${id}`);
+  return n;
+}
+
+describe("forms counted since #4489", () => {
+  it("counts `count = local.x` over a literal local", () => {
+    expect(instancesOf("estate/aws_eip.local_count")).toEqual(["estate/aws_eip.local_count[0]", "estate/aws_eip.local_count[1]"]);
+    expect(node("estate/aws_eip.local_count").instanceRollup).toBeUndefined();
+  });
+
+  it("counts `count = length(local.x)`", () => {
+    expect(instancesOf("estate/aws_sqs_queue.local_length")).toHaveLength(3);
+  });
+
+  it("keys `for_each = toset(local.l)` and `for_each = local.m`", () => {
+    expect(instancesOf("estate/aws_s3_bucket.local_set")).toEqual(['estate/aws_s3_bucket.local_set["p"]', 'estate/aws_s3_bucket.local_set["q"]']);
+    expect(instancesOf("estate/aws_lb_listener.local_map")).toEqual(['estate/aws_lb_listener.local_map["http"]', 'estate/aws_lb_listener.local_map["https"]']);
+  });
+
+  it("counts `var.on ? 1 : 0` over a known bool, and a local that reads one", () => {
+    expect(instancesOf("estate/aws_sns_topic.enabled")).toEqual(["estate/aws_sns_topic.enabled[0]"]);
+    expect(instancesOf("estate/aws_sns_topic.disabled")).toEqual([]);
+    expect(node("estate/aws_sns_topic.disabled").instanceRollup).toBeUndefined();
+    expect(instancesOf("estate/aws_sns_topic.local_flag")).toHaveLength(2);
+  });
+});
+
+describe("forms still rolled up, with the node's reason", () => {
+  it.each([
+    ["estate/aws_sns_topic.flag_unknown", "instances-value-unknown", "count", "var.flag ? 1 : 0"],
+    ["estate/aws_sns_topic.local_unknown", "instances-value-unknown", "count", "local.computed"],
+    ["estate/aws_iam_group.each", "instances-each-value", "for_each", "each.value"],
+    ["estate/aws_iam_policy.arith", "instances-form-unread", "count", "local.replicas + 1"],
+    ["estate/aws_eip.too_many", "instances-over-limit", "count", "300"],
+    ["estate/module.svc", "instances-value-unknown", "count", "var.unknown"],
+  ])("%s is one node with %s", (id, code, argument, expression) => {
+    expect(instancesOf(id)).toEqual([]);
+    expect(node(id).instanceRollup).toEqual({ code, argument, expression });
+  });
+
+  it("names merge() and a for expression", () => {
+    expect(node("estate/aws_iam_user.merged").instanceRollup).toMatchObject({ code: "instances-merge", argument: "for_each" });
+    expect(node("estate/aws_iam_user.merged").instanceRollup?.expression).toMatch(/^merge\(/);
+    expect(node("estate/aws_iam_role.for_expr").instanceRollup).toMatchObject({ code: "instances-form-unread", argument: "for_each" });
+  });
+
+  it("names the uncounted module call on a block under it", () => {
+    expect(instancesOf("estate/module.svc/aws_iam_role.runner")).toEqual([]);
+    expect(node("estate/module.svc/aws_iam_role.runner").instanceRollup).toEqual({
+      code: "instances-module-uncounted",
+      argument: "count",
+      expression: "var.unknown",
+      call: "module.svc",
+    });
+  });
+
+  it("uses only the listed codes", () => {
+    for (const n of ir.nodes) {
+      if (n.instanceRollup) expect(INSTANCE_ROLLUP_CODES).toContain(n.instanceRollup.code);
+    }
+  });
+});

package/src/hcl/instances.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Instance nodes counted from variables, and under expanded module calls
+ * (chant #4486).
+ *
+ * The fixture is `src/__fixtures__/instance-vars/app/`, rendered through
+ * `renderTerraformRoots`, then core's `buildGraphIr` and `withInstanceNodes`,
+ * which is how `chant graph --format ir` builds a terraform root's graph.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+import { buildGraphIr, withInstanceNodes, type GraphIR } from "@intentius/chant/graph-ir";
+import { graphNodeFor } from "@intentius/chant/change-set-graph";
+import { terraformInstancePath } from "@intentius/chant/instance-nodes";
+import type { Declarable } from "@intentius/chant/declarable";
+import { renderTerraformRoots } from "./roots";
+
+const TREE = join(dirname(fileURLToPath(import.meta.url)), "..", "__fixtures__", "instance-vars");
+
+let entities: Map<string, Declarable>;
+let ir: GraphIR;
+
+beforeAll(async () => {
+  const rendered = await renderTerraformRoots({ projectRoot: TREE, roots: { estate: { dir: "./app" } } });
+  expect(rendered.warnings).toEqual([]);
+  entities = rendered.entities;
+  ir = withInstanceNodes(buildGraphIr(entities), entities);
+});
+
+/** The instance nodes under one block node, as `[id, instanceKey, instanceScope]`. */
+function instancesOf(block: string): Array<[string, string | null, string | null]> {
+  return ir.nodes
+    .filter((n) => n.instanceOf === block)
+    .map((n) => [n.id, n.instanceKey ?? null, n.instanceScope ?? null] as [string, string | null, string | null])
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+}
+
+describe("count and for_each resolved from variables", () => {
+  it("counts `count = var.n` from terraform.tfvars over the default", () => {
+    expect(instancesOf("estate/aws_eip.pool")).toEqual([
+      ["estate/aws_eip.pool[0]", "[0]", null],
+      ["estate/aws_eip.pool[1]", "[1]", null],
+      ["estate/aws_eip.pool[2]", "[2]", null],
+    ]);
+  });
+
+  it("keys `for_each = var.names` over a set variable's default", () => {
+    expect(instancesOf("estate/aws_s3_bucket.named").map((i) => i[0])).toEqual([
+      'estate/aws_s3_bucket.named["a"]',
+      'estate/aws_s3_bucket.named["b"]',
+    ]);
+  });
+
+  it("counts `count = length(var.zones)`", () => {
+    expect(instancesOf("estate/aws_sqs_queue.zoned").map((i) => i[0])).toEqual([
+      "estate/aws_sqs_queue.zoned[0]",
+      "estate/aws_sqs_queue.zoned[1]",
+    ]);
+  });
+
+  it("leaves a block whose variable has no known value as one node", () => {
+    expect(instancesOf("estate/aws_sns_topic.uncounted")).toEqual([]);
+    expect(ir.nodes.some((n) => n.id === "estate/aws_sns_topic.uncounted")).toBe(true);
+  });
+});
+
+describe("instances under an expanded module call", () => {
+  it("gives the module call its own instance nodes", () => {
+    expect(instancesOf("estate/module.app")).toEqual([
+      ["estate/module.app[0]", "[0]", null],
+      ["estate/module.app[1]", "[1]", null],
+    ]);
+  });
+
+  it("puts the module key on the call segment and the block key at the end", () => {
+    // `size = var.n` passes the root's 3 into the child's `count = var.size`.
+    expect(instancesOf("estate/module.app/aws_instance.web")).toEqual([
+      ["estate/module.app[0]/aws_instance.web[0]", "[0]", "module.app[0]"],
+      ["estate/module.app[0]/aws_instance.web[1]", "[1]", "module.app[0]"],
+      ["estate/module.app[0]/aws_instance.web[2]", "[2]", "module.app[0]"],
+      ["estate/module.app[1]/aws_instance.web[0]", "[0]", "module.app[1]"],
+      ["estate/module.app[1]/aws_instance.web[1]", "[1]", "module.app[1]"],
+      ["estate/module.app[1]/aws_instance.web[2]", "[2]", "module.app[1]"],
+    ]);
+  });
+
+  it("gives a block that is not expanded itself one instance per module instance, with no instanceKey", () => {
+    expect(instancesOf("estate/module.app/aws_iam_role.runner")).toEqual([
+      ["estate/module.app[0]/aws_iam_role.runner", null, "module.app[0]"],
+      ["estate/module.app[1]/aws_iam_role.runner", null, "module.app[1]"],
+    ]);
+    expect(instancesOf("estate/module.edge/aws_route53_record.front")).toEqual([
+      ['estate/module.edge["east"]/aws_route53_record.front', null, 'module.edge["east"]'],
+      ['estate/module.edge["west"]/aws_route53_record.front', null, 'module.edge["west"]'],
+    ]);
+  });
+
+  it("keeps the block node as the rollup, in the same groups", () => {
+    expect(ir.nodes.some((n) => n.id === "estate/module.app/aws_instance.web" && !n.instanceOf)).toBe(true);
+    expect(ir.groups.byStack?.estate).toEqual(
+      expect.arrayContaining(["estate/module.app/aws_instance.web", "estate/module.app[1]/aws_instance.web[2]"]),
+    );
+  });
+
+  it("places a plan address on the same id the graph lists", () => {
+    const graph = { member: null, at: null, ids: ir.nodes.map((n) => n.id) };
+    expect(graphNodeFor({ member: "estate", planner: "terraform", address: "module.app[1].aws_instance.web[2]" }, graph)).toEqual({
+      node: "estate/module.app[1]/aws_instance.web[2]",
+      instanceOf: "estate/module.app/aws_instance.web",
+    });
+    expect(graphNodeFor({ member: "estate", planner: "tofu", address: 'module.edge["east"].aws_route53_record.front' }, graph)).toEqual({
+      node: 'estate/module.edge["east"]/aws_route53_record.front',
+      instanceOf: "estate/module.edge/aws_route53_record.front",
+    });
+    for (const n of ir.nodes.filter((x) => x.instanceOf)) expect(graph.ids).toContain(n.id);
+  });
+});
+
+describe("terraformInstancePath", () => {
+  it("maps an address to its block key and instance key", () => {
+    expect(terraformInstancePath("aws_eip.pool[1]")).toEqual({ block: "aws_eip.pool", instance: "aws_eip.pool[1]", key: "[1]" });
+    expect(terraformInstancePath("aws_eip.pool")).toBeUndefined();
+    expect(terraformInstancePath("module.app[0].aws_eip.pool[1]")).toEqual({
+      block: "module.app/aws_eip.pool",
+      instance: "module.app[0]/aws_eip.pool[1]",
+      key: "[1]",
+      scope: "module.app[0]",
+    });
+    expect(terraformInstancePath('module.a["x.y"].module.b.data.http.site')).toEqual({
+      block: "module.a/module.b/data.http.site",
+      instance: 'module.a["x.y"]/module.b/data.http.site',
+      scope: 'module.a["x.y"].module.b',
+    });
+    expect(terraformInstancePath("module.app[0]")).toEqual({ block: "module.app", instance: "module.app[0]", key: "[0]" });
+  });
+});