@intentius/chant-lexicon-terraform 0.101.0 → 0.104.0

package/src/components/pr-loop.tofu.test.ts

@@ -0,0 +1,244 @@
+/**
+ * The pull-request loop (#3183) over five real Terraform roots, through the
+ * commands the generated CI runs: `chant components pr-plan` on the pull
+ * request and `chant components pr-apply` on the merge, each talking to a
+ * fake GitHub.
+ *
+ * The issue's "done when": a pull request touching one of five roots plans
+ * only that root and its dependents, applies on merge with the approved
+ * digest, and refuses with a clear message if the plan changed after review.
+ *
+ * The roots use `terraform_data`, which is built into `tofu` and `terraform`,
+ * with local state, so nothing downloads a provider or reaches a cloud. The
+ * estate is net -> a, b and a -> app, with dns on its own; a and b read net's
+ * output and app reads a's, through `stackOutput()`. Skipped when neither
+ * binary is on the PATH.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
+import type { ParsedArgs } from "@intentius/chant/cli/registry";
+import type { PrReport } from "@intentius/chant/pr-loop";
+import { terraformPlugin } from "../plugin";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+
+function which(bin: string): boolean {
+  try {
+    execFileSync(bin, ["version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+const BINARY = which("tofu") ? "tofu" : which("terraform") ? "terraform" : undefined;
+
+const ROOTS: Record<string, string> = {
+  net: 'resource "terraform_data" "vpc" {\n  input = "10.0.0.0/16"\n}\n\noutput "cidr" {\n  value = terraform_data.vpc.output\n}\n',
+  a: 'variable "cidr" {\n  type = string\n}\n\nresource "terraform_data" "subnet" {\n  input = "${var.cidr}/a-v1"\n}\n\noutput "id" {\n  value = terraform_data.subnet.output\n}\n',
+  b: 'variable "cidr" {\n  type = string\n}\n\nresource "terraform_data" "subnet" {\n  input = "${var.cidr}/b-v1"\n}\n',
+  app: 'variable "subnet" {\n  type = string\n}\n\nresource "terraform_data" "app" {\n  input = "app on ${var.subnet}"\n}\n',
+  dns: 'resource "terraform_data" "zone" {\n  input = "example.test"\n}\n',
+};
+
+const COMPONENTS = `import { phase, stackOutput, type Component } from "@intentius/chant/components";
+
+const apply = (root: string, vars?: Record<string, unknown>) =>
+  [phase("Apply", [{ kind: "terraform-apply", root, ...(vars ? { vars } : {}) }])];
+
+export const net: Component = { name: "net", dependsOn: [], deploy: apply("net") };
+export const a: Component = { name: "a", dependsOn: ["net"], deploy: apply("a", { cidr: stackOutput("net", "cidr") }) };
+export const b: Component = { name: "b", dependsOn: ["net"], deploy: apply("b", { cidr: stackOutput("net", "cidr") }) };
+export const app: Component = { name: "app", dependsOn: ["a"], deploy: apply("app", { subnet: stackOutput("a", "id") }) };
+export const dns: Component = { name: "dns", dependsOn: [], deploy: apply("dns") };
+`;
+
+/** GitHub as far as the loop uses it: comments, statuses, reviews and the merged pull request of a commit. */
+class FakeGithub {
+  comments: Array<{ id: number; pr: number; body: string }> = [];
+  statuses: Array<{ sha: string; state: string; context: string; description: string }> = [];
+  reviews: Record<number, Array<{ user: { login: string }; state: string }>> = {};
+  mergedBy: Record<string, number> = {};
+  private nextId = 1;
+
+  fetch = async (url: string, init: { method: string; body?: string }) => {
+    const path = new URL(url).pathname.replace(/^\/repos\/acme\/infra/, "");
+    const body = init.body ? JSON.parse(init.body) : undefined;
+    const ok = (value: unknown) => ({ ok: true, status: 200, text: async () => JSON.stringify(value) });
+    let m: RegExpMatchArray | null;
+    if ((m = path.match(/^\/issues\/(\d+)\/comments$/))) {
+      const pr = Number(m[1]);
+      if (init.method === "GET") return ok(this.comments.filter((c) => c.pr === pr));
+      const c = { id: this.nextId++, pr, body: body.body };
+      this.comments.push(c);
+      return ok(c);
+    }
+    if ((m = path.match(/^\/issues\/comments\/(\d+)$/))) {
+      const c = this.comments.find((x) => x.id === Number(m![1]))!;
+      c.body = body.body;
+      return ok(c);
+    }
+    if ((m = path.match(/^\/statuses\/([0-9a-f]+)$/))) {
+      this.statuses.push({ sha: m[1], ...body });
+      return ok({});
+    }
+    if ((m = path.match(/^\/pulls\/(\d+)\/reviews$/))) return ok(this.reviews[Number(m[1])] ?? []);
+    if ((m = path.match(/^\/commits\/([0-9a-f]+)\/pulls$/))) {
+      const pr = this.mergedBy[m[1]];
+      return ok(pr ? [{ number: pr, merged_at: "2026-10-03T00:00:00Z", merge_commit_sha: m[1] }] : []);
+    }
+    return { ok: false, status: 404, text: async () => "" };
+  };
+}
+
+const args = (overrides: Partial<ParsedArgs>): ParsedArgs => ({
+  command: "components",
+  path: ".",
+  format: "",
+  fix: false,
+  watch: false,
+  verbose: false,
+  help: false,
+  live: false,
+  env: "local",
+  noReleaseRecord: true,
+  ...overrides,
+});
+
+describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform"} roots`, () => {
+  let dir: string;
+  let cwd: string;
+  const github = new FakeGithub();
+  const env = { ...process.env };
+  const git = (...a: string[]) => execFileSync("git", a, { cwd: dir, encoding: "utf8" }).trim();
+  const write = (path: string, text: string) => {
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    writeFileSync(join(dir, path), text);
+  };
+  const report = (stage: "plan" | "apply"): PrReport => JSON.parse(readFileSync(join(dir, ".chant", "pr", `pr-${stage}.json`), "utf8"));
+  const state = (root: string) => readFileSync(join(dir, "roots", root, "terraform.tfstate"), "utf8");
+  const ctx = (overrides: Partial<ParsedArgs>) => ({ args: args(overrides), plugins: [terraformPlugin], serializers: [terraformPlugin.serializer] });
+  let handlers: typeof import("@intentius/chant/cli/handlers/pr");
+  let recordGateApproval: typeof import("@intentius/chant/cli/handlers/operator").recordGateApproval;
+
+  beforeAll(async () => {
+    dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-pr-loop-")));
+    symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"));
+    for (const [name, text] of Object.entries(ROOTS)) write(`roots/${name}/main.tf`, text);
+    write(
+      "chant.config.json",
+      JSON.stringify({ lexicons: ["terraform"], terraform: { binary: BINARY, roots: Object.fromEntries(Object.keys(ROOTS).map((r) => [r, { dir: `roots/${r}` }])) } }, null, 2),
+    );
+    write("estate.component.ts", COMPONENTS);
+    write(".gitignore", "node_modules\n.terraform\n.terraform.lock.hcl\n*.tfstate*\nchant.tfplan\n.chant\n");
+    git("init", "-q", "-b", "main");
+    git("config", "user.email", "ci@example.test");
+    git("config", "user.name", "ci");
+    git("add", "-A");
+    git("commit", "-qm", "five roots");
+
+    cwd = process.cwd();
+    process.chdir(dir);
+    Object.assign(process.env, {
+      GITHUB_REPOSITORY: "acme/infra",
+      GITHUB_TOKEN: "t0k",
+      GITHUB_API_URL: "https://api.github.com",
+      GITHUB_SERVER_URL: "https://github.com",
+      GITHUB_RUN_ID: "1",
+    });
+    vi.stubGlobal("fetch", github.fetch);
+    handlers = await import("@intentius/chant/cli/handlers/pr");
+    ({ recordGateApproval } = await import("@intentius/chant/cli/handlers/operator"));
+
+    // Every root applied once, so each has state and outputs to read.
+    const { runComponentsFanOut } = await import("@intentius/chant/cli/handlers/fan-out");
+    write("all.json", JSON.stringify({ changed: ["net", "dns"] }));
+    expect(await runComponentsFanOut(ctx({ fromAffected: "all.json" }) as never)).toBe(0);
+  }, 240_000);
+
+  afterAll(() => {
+    vi.unstubAllGlobals();
+    if (cwd) process.chdir(cwd);
+    for (const key of Object.keys(process.env)) if (!(key in env)) delete process.env[key];
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  /** A pull request that rewrites root a's subnet to `version`, merged by `merge`. */
+  async function openPullRequest(pr: number, version: string): Promise<PrReport> {
+    git("checkout", "-qb", `pr-${pr}`);
+    write("roots/a/main.tf", ROOTS.a.replace("a-v1", version));
+    git("commit", "-qam", `a ${version}`);
+    expect(await handlers.runComponentsPrPlan(ctx({ base: "main", pr, forge: "github" }) as never)).toBe(0);
+    return report("plan");
+  }
+
+  async function merge(pr: number): Promise<number> {
+    git("checkout", "-q", "main");
+    const before = git("rev-parse", "HEAD");
+    git("merge", "-q", "--no-ff", `pr-${pr}`, "-m", `Merge pull request #${pr}`);
+    github.mergedBy[git("rev-parse", "HEAD")] = pr;
+    return handlers.runComponentsPrApply(ctx({ base: before, forge: "github", requireReview: true }) as never);
+  }
+
+  test("a change to one root plans that root and its dependent, and nothing else", async () => {
+    const plan = await openPullRequest(1, "a-v2");
+
+    expect(plan.status).toBe("planned");
+    expect(plan.selection).toMatchObject({ changed: ["a"], dependents: ["app"], waves: [["a"], ["app"]] });
+    expect(plan.members.map((m) => [m.member, m.counts.update])).toEqual([
+      ["a", 1],
+      ["app", 0],
+    ]);
+    expect(plan.changeSet.digest).toBe(plan.digest);
+    expect(plan.approval).toEqual({ status: "pending" });
+
+    const note = github.comments.find((c) => c.pr === 1)!;
+    expect(note.body.startsWith("<!-- chant-pr:local -->")).toBe(true);
+    expect(note.body).toContain(`chant approve pr-1 pr-apply --plan ${plan.digest} --approver github:<your-login> --sign`);
+    expect(github.statuses.at(-1)).toMatchObject({ context: "chant/plan", state: "success", sha: plan.head });
+  }, 240_000);
+
+  test("on merge it applies the plan the reviewer approved", async () => {
+    const plan = report("plan");
+    github.reviews[1] = [{ user: { login: "alice" }, state: "APPROVED" }];
+    expect((await recordGateApproval("pr-1", "pr-apply", { actor: "github:alice", plan: plan.digest })).ok).toBe(true);
+
+    expect(await merge(1)).toBe(0);
+    const applied = report("apply");
+    expect(applied.digest).toBe(plan.digest);
+    expect(applied.status).toBe("applied");
+    expect(applied.approval).toEqual({ status: "approved", approvedBy: ["github:alice"] });
+    expect(applied.members.map((m) => [m.member, m.status, m.inputsMoved])).toEqual([
+      ["a", "applied", undefined],
+      ["app", "applied", ["a"]],
+    ]);
+    expect(state("a")).toContain("10.0.0.0/16/a-v2");
+    // The same note, now with the apply's outcome.
+    expect(github.comments.filter((c) => c.pr === 1)).toHaveLength(1);
+    expect(github.comments.find((c) => c.pr === 1)!.body).toContain("### chant apply for `local`");
+    expect(github.statuses.at(-1)).toMatchObject({ context: "chant/apply", state: "success", sha: applied.head });
+  }, 240_000);
+
+  test("a plan that changed after review is refused, naming both digests, and nothing applies", async () => {
+    const reviewed = await openPullRequest(2, "a-v3");
+    github.reviews[2] = [{ user: { login: "alice" }, state: "APPROVED" }];
+    expect((await recordGateApproval("pr-2", "pr-apply", { actor: "github:alice", plan: reviewed.digest })).ok).toBe(true);
+    // Pushed after the review.
+    write("roots/a/main.tf", ROOTS.a.replace("a-v1", "a-v4"));
+    git("commit", "-qam", "a v4");
+
+    expect(await merge(2)).toBe(3);
+    const refused = report("apply");
+    expect(refused.status).toBe("refused");
+    expect(refused.refusal).toBe("plan-changed");
+    expect(refused.approval).toEqual({ status: "changed", approved: reviewed.digest });
+    expect(refused.message).toContain(`approved: ${reviewed.digest}; planned now: ${refused.digest}`);
+    expect(refused.message).toContain("nothing was applied");
+    expect(state("a")).toContain("a-v2");
+    expect(state("a")).not.toContain("a-v4");
+    expect(github.statuses.at(-1)).toMatchObject({ context: "chant/apply", state: "failure", description: "refused: the plan changed after review" });
+  }, 240_000);
+});

package/src/composites/terraform-pin-rollout-op.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "vitest";
+import { validateActivitySteps, type ActivityStep, type OpConfig } from "@intentius/chant/op";
+import { TerraformPinRolloutOp } from "./terraform-pin-rollout-op";
+import { terraformPinRolloutContract } from "../op/activity-contracts";
+import { parsePinRolloutArgs, pinRolloutExitCode, terraformCommands } from "../commands";
+
+function props(config: Parameters<typeof TerraformPinRolloutOp>[0]): OpConfig {
+  return (TerraformPinRolloutOp(config).op as unknown as { props: OpConfig }).props;
+}
+
+const BASE = { name: "vpc-1-4", module: "oci://registry.example.com/modules/vpc", from: "1.3.0", to: "1.4.0" };
+
+describe("TerraformPinRolloutOp (#3189)", () => {
+  test("one Rollout phase, one step, the rollout's status as the run outcome", () => {
+    const op = props({ ...BASE, canaries: ["live/dev/vpc"], mode: "pull-request", schedule: "*/30 * * * *" });
+    expect(op.phases.map((p) => p.name)).toEqual(["Rollout"]);
+    const step = op.phases[0]!.steps[0] as ActivityStep;
+    expect(step.fn).toBe("terraformPinRollout");
+    expect(step.args).toEqual({ module: BASE.module, from: "1.3.0", to: "1.4.0", canaries: ["live/dev/vpc"], mode: "pull-request" });
+    expect(step.outcomeAttribute).toEqual({ name: "Rollout", from: "status" });
+    expect(op.schedule).toEqual({ cron: "*/30 * * * *", overlap: "skip" });
+  });
+
+  test("its step validates against the activity's contract", () => {
+    const op = props({ ...BASE, roots: [{ root: "a" }, { root: "b", dependsOn: ["a"] }] });
+    const contracts = new Map([["terraformPinRollout", terraformPinRolloutContract]]);
+    expect(validateActivitySteps(op, contracts)).toEqual([]);
+  });
+});
+
+describe("chant terraform pin-rollout", () => {
+  test("is mounted as the terraform group's pin-rollout verb", () => {
+    expect(terraformCommands.name).toBe("terraform");
+    expect(terraformCommands.commands.map((c) => c.name)).toEqual(["pin-rollout"]);
+  });
+
+  test("parses roots, dependencies, a generated root and canaries into the activity's args", () => {
+    const { args, json } = parsePinRolloutArgs([
+      "--module=oci://r/m/vpc",
+      "--from", "1.3.0",
+      "--to", "1.4.0",
+      "--root", "a",
+      "--depends-on", "b=a",
+      "--ts-source", "c=c/vpc.ts",
+      "--canary", "a",
+      "--pull-request",
+      "--json",
+    ]);
+    expect(json).toBe(true);
+    expect(args).toEqual({
+      module: "oci://r/m/vpc",
+      from: "1.3.0",
+      to: "1.4.0",
+      mode: "pull-request",
+      roots: [{ root: "a" }, { root: "b", dependsOn: ["a"] }, { root: "c", tsSource: "c/vpc.ts" }],
+      canaries: ["a"],
+    });
+  });
+
+  test("report is the default mode, and the required flags are required", () => {
+    expect(parsePinRolloutArgs(["--module", "m", "--from", "1", "--to", "2"]).args.mode).toBe("report");
+    expect(() => parsePinRolloutArgs(["--module", "m", "--from", "1"])).toThrow(/--to is required/);
+    expect(() => parsePinRolloutArgs(["--module", "m", "--from", "1", "--to", "2", "--bogus"])).toThrow(/Unknown flag: --bogus/);
+  });
+
+  test("waiting exits 3, stopped exits 1, the rest 0", () => {
+    expect(["complete", "opened", "would-open", "waiting", "stopped"].map(pinRolloutExitCode)).toEqual([0, 0, 0, 3, 1]);
+  });
+});

package/src/composites/terraform-pin-rollout-op.ts

@@ -0,0 +1,60 @@
+/**
+ * TerraformPinRolloutOp composite (#3189): roll a module version out as
+ * pin-bump pull requests, one wave at a time.
+ *
+ * One phase, one `terraformPinRollout` step. Each run reads the rollout's
+ * state from the forge and opens at most the next wave's PR, so the Op is
+ * meant to run again: on a `schedule`, or from the pipeline that applies a
+ * merged wave. Wave N+1 opens only on a run after wave N's PR merged and each
+ * of its roots reported its apply check as passed on the merge commit. Until
+ * then a run reports where the rollout stands and opens nothing. A failed
+ * root fails the run, naming it.
+ *
+ * The run's `Rollout` outcome is the rollout's status: `opened`, `waiting`,
+ * `complete`, or `would-open` in report mode.
+ *
+ * @example
+ * ```typescript
+ * import { TerraformPinRolloutOp } from "@intentius/chant-lexicon-terraform";
+ *
+ * export const { op } = TerraformPinRolloutOp({
+ *   name: "vpc-1-4",
+ *   module: "oci://registry.example.com/modules/vpc",
+ *   from: "1.3.0",
+ *   to: "1.4.0",
+ *   canaries: ["live/dev/vpc"],
+ *   mode: "pull-request",
+ *   schedule: "*\/30 * * * *",
+ * });
+ * ```
+ */
+
+import { Op, phase, OpResource } from "@intentius/chant/op";
+import { terraformPinRollout } from "../op/builders";
+import type { TerraformPinRolloutArgs } from "../op/activities/pin-rollout";
+
+export interface TerraformPinRolloutOpConfig extends TerraformPinRolloutArgs {
+  /** Op name (kebab-case). */
+  name: string;
+  /** Cron expression, so the rollout re-reads the forge and moves on without anyone running it. */
+  schedule?: string;
+}
+
+export interface TerraformPinRolloutOpResources {
+  /** Op resource. One Rollout phase. */
+  op: InstanceType<typeof OpResource>;
+}
+
+export function TerraformPinRolloutOp(config: TerraformPinRolloutOpConfig): TerraformPinRolloutOpResources {
+  const { name, schedule, ...args } = config;
+  const step = terraformPinRollout(args);
+  step.outcomeAttribute = { name: "Rollout", from: "status" };
+  const op = Op({
+    name,
+    overview: `Roll ${config.module} ${config.from} -> ${config.to} out as one pin-bump pull request per wave`,
+    labels: { Surface: "terraform-pin-rollout" },
+    ...(schedule ? { schedule: { cron: schedule, overlap: "skip" as const } } : {}),
+    phases: [phase("Rollout", [step])],
+  });
+  return { op };
+}

package/src/hcl/descend.ts

@@ -49,7 +49,7 @@
 import { existsSync, statSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import type { Declarable } from "@intentius/chant/declarable";
-import type { Hcl2Json } from "@intentius/chant/terraform/parse";
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
 import { isResourceDeclarable } from "@intentius/chant/declarable";
 import { classifyModuleSource } from "../lint/post-synth/module-source";
 import {

package/src/hcl/edges.ts

@@ -14,7 +14,7 @@
  *
  * 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
+ * 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`
@@ -86,7 +86,7 @@
 
 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 { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/hcl2json";
 import { refFromAccessor } from "@intentius/chant/terraform/graph";
 import { LOCALS_TYPE, scopeOfKey, type BlockBody, type TerraformEntity } from "./parse";
 

package/src/hcl/jsonencode.test.ts

@@ -0,0 +1,226 @@
+import { describe, expect, test } from "vitest";
+import { hasUnknownKeys, isUnknown, readJsonencode, UNKNOWN, UNKNOWN_KEYS } from "./jsonencode";
+
+/** What hcl2json hands back for `attr = jsonencode(<arg>)`: the source text, wrapped as one interpolation. */
+const call = (arg: string): string => `\${jsonencode(${arg})}`;
+
+describe("readJsonencode: a literal jsonencode argument read as structure (chant #2286)", () => {
+  test("an IAM policy in HCL object syntax, as hcl2json renders it", () => {
+    const raw =
+      '${jsonencode({\n    Version = "2012-10-17"\n    Statement = [\n      {\n        Action   = ["s3:*", "ec2:Describe*"]\n' +
+      '        "Effect" : "Allow"\n        Resource = "*"\n      },\n    ]\n  })}';
+    expect(readJsonencode(raw)).toEqual({
+      kind: "literal",
+      value: {
+        Version: "2012-10-17",
+        Statement: [{ Action: ["s3:*", "ec2:Describe*"], Effect: "Allow", Resource: "*" }],
+      },
+    });
+  });
+
+  test("a container definitions tuple with commas, numbers, booleans and null", () => {
+    const raw = call('[{ name = "app", cpu = 256, essential = true, memory = null, portMappings = [{ containerPort = 80 }] }]');
+    expect(readJsonencode(raw)).toEqual({
+      kind: "literal",
+      value: [{ name: "app", cpu: 256, essential: true, memory: null, portMappings: [{ containerPort: 80 }] }],
+    });
+  });
+
+  test("scalars, negative and exponent numbers, and string escapes", () => {
+    expect(readJsonencode(call('"x"'))).toEqual({ kind: "literal", value: "x" });
+    expect(readJsonencode(call("-1.5e2"))).toEqual({ kind: "literal", value: -150 });
+    expect(readJsonencode(call('"a\\"b\\\\c\\n\\u00e9"'))).toEqual({ kind: "literal", value: 'a"b\\c\né' });
+    expect(readJsonencode(call('"$${literal} %%{also}"'))).toEqual({ kind: "literal", value: "${literal} %{also}" });
+  });
+
+  test("comments inside the argument are whitespace", () => {
+    const raw = call('{\n  # why\n  a = 1 // trailing\n  /* block */ b = "x"\n}');
+    expect(readJsonencode(raw)).toEqual({ kind: "literal", value: { a: 1, b: "x" } });
+  });
+
+  test("spacing around the call itself", () => {
+    expect(readJsonencode('${ jsonencode ( { a = 1 } ) }')).toEqual({ kind: "literal", value: { a: 1 } });
+  });
+
+  test.each([
+    ["a reference as a value", '{ Resource = var.arn }', /reference/],
+    ["a reference as the whole argument", "local.policy", /reference/],
+    ["a function call", '{ Resource = concat(["a"], var.b) }', /function call/],
+    ["a for-expression in a tuple", "[for a in var.actions : a]", /for-expression/],
+    ["a for-expression in an object", "{ for k, v in var.m : k => v }", /for-expression/],
+    ["a conditional", '{ Action = var.admin ? "*" : "s3:GetObject" }', /reference/],
+    ["a conditional on a literal", '{ Action = true ? "*" : "x" }', /conditional/],
+    ["an interpolated string", '{ Resource = "arn:aws:s3:::${var.bucket}/*" }', /interpolation/],
+    ["a template directive", '{ Resource = "%{ if true }x%{ endif }" }', /directive/],
+    ["an operator", "{ n = 1 + 2 }", /operator/],
+    ["a computed key", '{ (var.k) = "v" }', /computed object key/],
+    ["a heredoc", "<<EOT\n{}\nEOT\n", /heredoc/],
+    ["an index on a literal", '{ a = ["x"][0] }', /index/],
+  ])("not-determined: %s", (_name, arg, reason) => {
+    const read = readJsonencode(call(arg));
+    expect(read.kind).toBe("not-determined");
+    if (read.kind === "not-determined") expect(read.reason).toMatch(reason);
+  });
+
+  test("not-determined: two calls in one template, never literal", () => {
+    expect(readJsonencode('${jsonencode({a = 1})}-${jsonencode({b = 2})}').kind).toBe("not-determined");
+  });
+
+  test.each([
+    ["a plain string", '{"Statement":[]}'],
+    ["a reference", "${data.aws_iam_policy_document.x.json}"],
+    ["a file() call", '${file("policy.json")}'],
+    ["a templatefile() call", '${templatefile("p.tpl", { a = 1 })}'],
+    ["a template around a jsonencode call", 'x-${jsonencode({a = 1})}'],
+    ["a number", 3],
+    ["absent", undefined],
+    ["a structured value", { Statement: [] }],
+  ])("not-jsonencode: %s", (_name, raw) => {
+    expect(readJsonencode(raw)).toEqual({ kind: "not-jsonencode" });
+  });
+});
+
+describe("readJsonencode with unknownLeaves: expressions become opaque leaves", () => {
+  const leaves = (raw: string) => readJsonencode(raw, { unknownLeaves: true });
+
+  test("a literal Action survives beside a reference Resource", () => {
+    const read = leaves(call('{\n  Statement = [{\n    Action   = "*"\n    Resource = aws_s3_bucket.x.arn\n    Effect   = "Allow"\n  }]\n}'));
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const stmt = (read.value as { Statement: Record<string, unknown>[] }).Statement[0];
+    expect(stmt.Action).toBe("*");
+    expect(stmt.Effect).toBe("Allow");
+    expect(isUnknown(stmt.Resource)).toBe(true);
+    expect((stmt.Resource as { reason: string }).reason).toMatch(/reference/);
+    expect((stmt.Resource as Record<symbol, unknown>)[UNKNOWN]).toBe(true);
+    expect((stmt.Resource as { source: string }).source).toBe("aws_s3_bucket.x.arn");
+  });
+
+  test("container definitions keep their literal environment beside image = var.image", () => {
+    const read = leaves(
+      call('[{\n  name  = "app"\n  image = "${var.repo}:${var.tag}"\n  cpu   = var.cpu * 2\n  environment = [{ name = "DB_PASSWORD", value = "hunter2" }]\n}]'),
+    );
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const def = (read.value as Record<string, unknown>[])[0];
+    expect(def.name).toBe("app");
+    expect(isUnknown(def.image)).toBe(true);
+    expect((def.image as { source: string }).source).toBe('"${var.repo}:${var.tag}"');
+    expect(isUnknown(def.cpu)).toBe(true);
+    expect(def.environment).toEqual([{ name: "DB_PASSWORD", value: "hunter2" }]);
+  });
+
+  test.each([
+    ["a function call spanning lines", 'merge(\n  { a = "x" },\n  var.extra,\n)'],
+    ["a conditional with nested literals", 'var.admin ? { a = "*" } : {}'],
+    ["a heredoc", "<<EOT\n{\"a\": 1}\nEOT"],
+    ["an indexed tuple", '["x"][0]'],
+    ["a splat", "aws_s3_bucket.b[*].arn"],
+    ["a string with nested quotes in its interpolation", '"${lookup(var.m, "k", "}")}"'],
+  ])("skips %s and reads the next field", (_name, expr) => {
+    const read = leaves(call(`{\n  a = ${expr}\n  b = "after"\n}`));
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const v = read.value as Record<string, unknown>;
+    expect(isUnknown(v.a)).toBe(true);
+    expect(v.b).toBe("after");
+  });
+
+  test("tuple items are skipped one at a time", () => {
+    const read = leaves(call('["s3:GetObject", var.extra, "*"]'));
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const v = read.value as unknown[];
+    expect(v[0]).toBe("s3:GetObject");
+    expect(isUnknown(v[1])).toBe(true);
+    expect(v[2]).toBe("*");
+  });
+
+  test.each([
+    ["a tuple for-expression as the whole argument", "[for s in var.s : s]", /for-expression/],
+    ["an object for-expression as the whole argument", "{ for k, v in var.m : k => v }", /for-expression/],
+    ["an expression as the whole argument", "local.policy", /reference/],
+    ["a splat as the whole argument", "var.x[*]", /reference/],
+  ])("still not-determined: %s", (_name, arg, reason) => {
+    const read = leaves(call(arg));
+    expect(read.kind).toBe("not-determined");
+    if (read.kind === "not-determined") expect(read.reason).toMatch(reason);
+  });
+
+  test("the default mode is unchanged: one expression makes the whole read not-determined", () => {
+    expect(readJsonencode(call('{ Action = "*", Resource = var.arn }')).kind).toBe("not-determined");
+  });
+});
+
+describe("readJsonencode with unknownLeaves: members with an expression key", () => {
+  test("a traefik label keyed by an interpolation is dropped and recorded (govuk-forms/forms-admin shape)", () => {
+    const raw = call(
+      '[{\n  name = "forms-admin"\n  dockerLabels = {\n    "traefik.enable" : "true"\n' +
+        '    "traefik.http.routers.forms-admin-pr-${var.pull_request_number}.rule" : "Host(`pr-${var.pull_request_number}.example`)"\n' +
+        '    "traefik.port" : "3000"\n  }\n}]',
+    );
+    const read = readJsonencode(raw, { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const labels = (read.value as Record<string, unknown>[])[0].dockerLabels as Record<string | symbol, unknown>;
+    expect(Object.keys(labels)).toEqual(["traefik.enable", "traefik.port"]);
+    expect(hasUnknownKeys(labels)).toBe(true);
+    expect(labels[UNKNOWN_KEYS]).toEqual([expect.stringMatching(/object key holding .*interpolation/)]);
+    expect(hasUnknownKeys((read.value as Record<string, unknown>[])[0])).toBe(false);
+  });
+
+  test("a parenthesised computed key is dropped with its multi-line value", () => {
+    const read = readJsonencode(call('{\n  (var.k) = {\n    x = 1\n  }\n  b = "after"\n}'), { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    expect(Object.keys(read.value as object)).toEqual(["b"]);
+    expect((read.value as Record<symbol, unknown>)[UNKNOWN_KEYS]).toEqual(["a computed object key"]);
+  });
+
+  test.each([
+    ["a computed key", '{ (var.k) = "v" }', /computed object key/],
+    ["an interpolated key", '{ "${var.k}" = "v" }', /object key/],
+  ])("default mode: %s makes the whole read not-determined", (_name, arg, reason) => {
+    const read = readJsonencode(call(arg));
+    expect(read.kind).toBe("not-determined");
+    if (read.kind === "not-determined") expect(read.reason).toMatch(reason);
+  });
+});
+
+describe("readJsonencode with unknownLeaves: a for-expression below the argument is a leaf", () => {
+  test("a tuple for-expression as a member value (sonodar/dify-aws-terraform shape)", () => {
+    const raw = call(
+      '[{\n  name = "api"\n  environment = [for name, value in {\n    MODE = "api"\n    LOG_LEVEL = "INFO"\n  } : { name = name, value = tostring(value) }]\n  essential = true\n}]',
+    );
+    const read = readJsonencode(raw, { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const def = (read.value as Record<string, unknown>[])[0];
+    expect(def.name).toBe("api");
+    expect(isUnknown(def.environment)).toBe(true);
+    expect((def.environment as { reason: string }).reason).toMatch(/for-expression/);
+    expect(def.essential).toBe(true);
+  });
+
+  test("an object for-expression as a member value", () => {
+    const read = readJsonencode(call('{\n  labels = { for k, v in var.m : k => v }\n  b = 1\n}'), { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    const v = read.value as Record<string, unknown>;
+    expect(isUnknown(v.labels)).toBe(true);
+    expect(v.b).toBe(1);
+  });
+
+  test("a for-expression producing a policy's Statement list is one unknown leaf", () => {
+    const read = readJsonencode(call('{\n  Version = "2012-10-17"\n  Statement = [for s in var.statements : s]\n}'), { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind !== "literal") return;
+    expect(isUnknown((read.value as Record<string, unknown>).Statement)).toBe(true);
+  });
+
+  test("a for-expression as a tuple item", () => {
+    const read = readJsonencode(call('["a", [for x in var.y : x]]'), { unknownLeaves: true });
+    expect(read.kind).toBe("literal");
+    if (read.kind === "literal") expect(isUnknown((read.value as unknown[])[1])).toBe(true);
+  });
+});