@intentius/chant-lexicon-terraform 0.102.0 → 0.104.1

package/src/changed-roots.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Which `terraform.roots` a change touches (#3183): a file in the root's
+ * directory, in a local module it calls (and modules those call), or one of
+ * its var files.
+ */
+
+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 { changedRoots, rootWatchPaths } from "./changed-roots";
+
+const project = mkdtempSync(join(tmpdir(), "chant-changed-roots-"));
+afterAll(() => rmSync(project, { recursive: true, force: true }));
+
+function write(path: string, text: string): void {
+  mkdirSync(dirname(join(project, path)), { recursive: true });
+  writeFileSync(join(project, path), text);
+}
+
+write("roots/net/main.tf", 'module "vpc" {\n  source = "../../modules/vpc"\n}\n');
+write("roots/app/main.tf", 'module "svc" {\n  source = "../../modules/svc//inner"\n}\nmodule "reg" {\n  source = "terraform-aws-modules/vpc/aws"\n}\n');
+write("roots/dns/main.tofu", 'resource "terraform_data" "z" {}\n');
+write("modules/vpc/main.tf", 'module "subnets" {\n  source = "./subnets"\n}\n');
+write("modules/vpc/subnets/main.tf", "");
+write("modules/svc/inner/main.tf", "");
+write("envs/prod.tfvars", "");
+
+const ROOTS = {
+  net: { dir: "roots/net" },
+  app: { dir: "./roots/app", varFiles: ["../../envs/prod.tfvars"] },
+  dns: { dir: "roots/dns" },
+};
+
+describe("rootWatchPaths", () => {
+  test("a root watches its directory, each local module it reaches and its var files", () => {
+    expect(rootWatchPaths(project, ROOTS.net)).toEqual(["modules/vpc", "modules/vpc/subnets", "roots/net"]);
+    expect(rootWatchPaths(project, ROOTS.app)).toEqual(["envs/prod.tfvars", "modules/svc/inner", "roots/app"]);
+  });
+});
+
+describe("changedRoots", () => {
+  test("a file in a root's directory touches that root alone", () => {
+    expect(changedRoots(project, ROOTS, ["roots/dns/main.tofu"])).toEqual(["dns"]);
+  });
+
+  test("a file in a module two calls deep touches the root that calls it", () => {
+    expect(changedRoots(project, ROOTS, ["modules/vpc/subnets/main.tf"])).toEqual(["net"]);
+  });
+
+  test("a var file touches the root that reads it", () => {
+    expect(changedRoots(project, ROOTS, ["envs/prod.tfvars"])).toEqual(["app"]);
+  });
+
+  test("a registry source is not followed, and a file nothing reads touches nothing", () => {
+    expect(changedRoots(project, ROOTS, ["README.md", "roots/netsplit/main.tf"])).toEqual([]);
+  });
+});

package/src/changed-roots.ts

@@ -0,0 +1,102 @@
+/**
+ * Which `terraform.roots` a change touched (#3183), from the changed files
+ * alone.
+ *
+ * A root is hand-written HCL, not chant source, so `chant lifecycle affected`
+ * never sees it move: its artifact diff covers what chant builds. A pull
+ * request's plan needs the roots a change reaches, and this answers that
+ * from paths: a root is touched when a changed file sits in its directory,
+ * 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`
+ * 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
+ * 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 { join, posix, relative, resolve, sep } from "node:path";
+import type { TerraformRootConfig } from "./config";
+
+/** `source = "./..."` or `"../..."` inside a module block. Other sources are not on disk here. */
+const LOCAL_SOURCE = /\bsource\s*=\s*"(\.{1,2}\/[^"]*)"/g;
+
+const toPosix = (p: string): string => p.split(sep).join("/");
+
+/** `dir` relative to `projectRoot`, `/`-separated, without a trailing slash; `.` for the root itself. */
+function projectRelative(projectRoot: string, dir: string): string {
+  const rel = toPosix(relative(projectRoot, dir));
+  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 [];
+  }
+  const out: string[] = [];
+  for (const name of names) {
+    if (!name.endsWith(".tf") && !name.endsWith(".tofu")) continue;
+    let text: string;
+    try {
+      text = readFileSync(join(dir, name), "utf8");
+    } catch {
+      continue;
+    }
+    for (const m of text.matchAll(LOCAL_SOURCE)) {
+      // A `//subdir` suffix names a directory inside the source.
+      const target = resolve(dir, m[1].replace("//", "/"));
+      if (existsSync(target) && statSync(target).isDirectory()) out.push(target);
+    }
+  }
+  return out;
+}
+
+/**
+ * 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[] {
+  const rootDir = resolve(projectRoot, root.dir);
+  const seen = new Set<string>();
+  const queue = [rootDir];
+  while (queue.length > 0) {
+    const dir = queue.shift()!;
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    queue.push(...localModuleDirs(dir));
+  }
+  const paths = [...seen].map((d) => projectRelative(projectRoot, d));
+  for (const file of root.varFiles ?? []) paths.push(projectRelative(projectRoot, resolve(rootDir, file)));
+  return [...new Set(paths)].sort();
+}
+
+/** Whether `file` is `path` or sits under it. Both relative to the project, `/`-separated. */
+function covers(path: string, file: string): boolean {
+  if (path === ".") return !file.startsWith("../");
+  return file === path || file.startsWith(`${path}/`);
+}
+
+/**
+ * The names of the roots in `roots` that a change to `changedFiles` touches,
+ * sorted. `changedFiles` are relative to `projectRoot` with `/` separators,
+ * as `git diff --name-only --relative` prints them.
+ */
+export function changedRoots(
+  projectRoot: string,
+  roots: Record<string, Pick<TerraformRootConfig, "dir" | "varFiles">>,
+  changedFiles: readonly 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);
+    if (files.some((f) => watch.some((p) => covers(p, f)))) touched.push(name);
+  }
+  return touched.sort();
+}

package/src/commands.ts

@@ -0,0 +1,112 @@
+/**
+ * `chant terraform pin-rollout`: one run of a pin-bump rollout (#3189), from
+ * the command line. The `TerraformPinRolloutOp` composite runs the same code
+ * as an Op step.
+ *
+ *     chant terraform pin-rollout --module <source> --from <pin> --to <pin>
+ *       [--root <dir>]... [--depends-on <dir>=<dir>]... [--ts-source <dir>=<file>]...
+ *       [--canary <dir>]... [--waves-from <live-waves.json> [--waves-prefix <dir>]]
+ *       [--pull-request] [--base <branch>] [--remote <name>] [--applied-check <name>] [--json]
+ *
+ * Without `--pull-request` it reports the next wave and opens nothing. Exit
+ * 0 when the rollout is complete or a wave's PR was opened (or would be), 3
+ * when it is waiting on a merge or an apply (a gate is a fact, #2119), and 1
+ * when it stopped on a failed root or a closed PR.
+ */
+
+import type { CommandGroup, CommandGroupContext } from "@intentius/chant/cli/command-group";
+import { splitJoinedFlags, unknownFlagError } from "@intentius/chant/cli/command-group";
+import type { TerraformPinRolloutArgs } from "./op/activities/pin-rollout";
+import type { PinRoot } from "./pin";
+
+const USAGE =
+  "usage: chant terraform pin-rollout --module <source> --from <pin> --to <pin> [--root <dir>]... [--depends-on <dir>=<dir>]... " +
+  "[--ts-source <dir>=<file>]... [--canary <dir>]... [--waves-from <file> [--waves-prefix <dir>]] [--pull-request] " +
+  "[--base <branch>] [--remote <name>] [--applied-check <name>] [--json]";
+
+const VALUE_FLAGS = new Set(["--module", "--from", "--to", "--root", "--depends-on", "--ts-source", "--canary", "--waves-from", "--waves-prefix", "--base", "--remote", "--applied-check"]);
+const BOOLEAN_FLAGS = new Set(["--pull-request", "--json"]);
+
+/** Parse the verb's flags into the activity's args. Throws on an unknown flag or a missing value. */
+export function parsePinRolloutArgs(rawArgs: string[]): { args: TerraformPinRolloutArgs; json: boolean } {
+  const tokens = splitJoinedFlags(rawArgs, BOOLEAN_FLAGS);
+  const values = new Map<string, string[]>();
+  const flags = new Set<string>();
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i]!;
+    if (BOOLEAN_FLAGS.has(t)) {
+      flags.add(t);
+      continue;
+    }
+    if (!VALUE_FLAGS.has(t)) throw t.startsWith("-") ? unknownFlagError(t, USAGE) : new Error(`unexpected argument "${t}"\n${USAGE}`);
+    const v = tokens[++i];
+    if (v === undefined || v.startsWith("--")) throw new Error(`${t} needs a value\n${USAGE}`);
+    values.set(t, [...(values.get(t) ?? []), v]);
+  }
+  const one = (flag: string): string | undefined => values.get(flag)?.at(-1);
+  const pairs = (flag: string): Array<[string, string]> =>
+    (values.get(flag) ?? []).map((v) => {
+      const eq = v.indexOf("=");
+      if (eq <= 0 || eq === v.length - 1) throw new Error(`${flag} takes <dir>=<value>, got "${v}"`);
+      return [v.slice(0, eq), v.slice(eq + 1)];
+    });
+  for (const required of ["--module", "--from", "--to"]) if (!one(required)) throw new Error(`${required} is required\n${USAGE}`);
+
+  const dependsOn = pairs("--depends-on");
+  const tsSource = new Map(pairs("--ts-source"));
+  const named = [...new Set([...(values.get("--root") ?? []), ...dependsOn.map(([r]) => r), ...tsSource.keys()])];
+  const roots: PinRoot[] | undefined =
+    named.length > 0
+      ? named.map((root) => {
+          const deps = dependsOn.filter(([r]) => r === root).map(([, d]) => d);
+          return { root, ...(deps.length > 0 ? { dependsOn: deps } : {}), ...(tsSource.has(root) ? { tsSource: tsSource.get(root)! } : {}) };
+        })
+      : undefined;
+
+  const args: TerraformPinRolloutArgs = {
+    module: one("--module")!,
+    from: one("--from")!,
+    to: one("--to")!,
+    mode: flags.has("--pull-request") ? "pull-request" : "report",
+    ...(roots ? { roots } : {}),
+    ...(values.has("--canary") ? { canaries: values.get("--canary")! } : {}),
+    ...(one("--waves-from") ? { wavesFrom: one("--waves-from")! } : {}),
+    ...(one("--waves-prefix") ? { wavesPrefix: one("--waves-prefix")! } : {}),
+    ...(one("--base") ? { base: one("--base")! } : {}),
+    ...(one("--remote") ? { remote: one("--remote")! } : {}),
+    ...(one("--applied-check") ? { appliedCheck: one("--applied-check")! } : {}),
+  };
+  return { args, json: flags.has("--json") };
+}
+
+/** Exit status for a rollout's status. */
+export function pinRolloutExitCode(status: string): number {
+  if (status === "waiting") return 3;
+  if (status === "stopped") return 1;
+  return 0;
+}
+
+async function runPinRolloutVerb(ctx: CommandGroupContext): Promise<number> {
+  let parsed: ReturnType<typeof parsePinRolloutArgs>;
+  try {
+    parsed = parsePinRolloutArgs(ctx.rawArgs);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+  const { readPinRollout } = await import("./op/activities/pin-rollout");
+  try {
+    const result = await readPinRollout(parsed.args);
+    console.log(parsed.json ? JSON.stringify(result, null, 2) : result.summary);
+    return pinRolloutExitCode(result.status);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}
+
+export const terraformCommands: CommandGroup = {
+  name: "terraform",
+  description: "Terraform and OpenTofu roots: roll a module version out as one pin-bump PR per wave",
+  commands: [{ name: "pin-rollout", description: "Read a pin-bump rollout's state and open the next wave's PR when it is due", handler: runPinRolloutVerb }],
+};

package/src/components/capability-plugin.test.ts

@@ -0,0 +1,91 @@
+/**
+ * `terraform-apply` (#3049): plan answers with the root and its #2300 digest,
+ * and run applies the plan a wave approved rather than planning again.
+ */
+
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+const calls: string[] = [];
+let applyResult: Record<string, unknown> = { applied: true };
+let changeSet: Record<string, unknown> | undefined;
+
+vi.mock("../op/activities/terraform", () => ({
+  terraformInit: vi.fn(async (args: { root: string }) => {
+    calls.push(`init ${args.root}`);
+    return { dir: `/x/${args.root}` };
+  }),
+  terraformPlan: vi.fn(async (args: { root: string; vars?: Record<string, unknown> }) => {
+    calls.push(`plan ${args.root} ${JSON.stringify(args.vars ?? {})}`);
+    return { planFile: "chant.tfplan", planDigest: `jcs1-sha256:${args.root}`, ...(changeSet ? { changeSet } : {}) };
+  }),
+  terraformApply: vi.fn(async (args: { root: string; planFile: string }) => {
+    calls.push(`apply ${args.root} ${args.planFile}`);
+    return { planFile: args.planFile, dir: `/x/${args.root}`, ...applyResult };
+  }),
+  terraformOutputs: vi.fn(async (args: { root: string }) => {
+    calls.push(`output ${args.root}`);
+    return { id: `${args.root}-id` };
+  }),
+}));
+
+const { terraformApplyCapability, terraformCapabilityPlugin } = await import("./capability-plugin");
+
+beforeEach(() => {
+  calls.length = 0;
+  applyResult = { applied: true };
+  changeSet = undefined;
+});
+
+describe("terraform-apply", () => {
+  test("the plugin contributes it", () => {
+    expect(terraformCapabilityPlugin.capabilities().map((c) => c.kind)).toEqual(["terraform-apply"]);
+  });
+
+  test("plan inits and plans the root, with its vars, and names the root as the member", async () => {
+    const planned = await terraformApplyCapability.plan!({ env: "test", component: "app" }, { root: "app", vars: { vpc: "v-1" } });
+    expect(planned).toEqual({
+      member: "app",
+      planDigest: "jcs1-sha256:app",
+      artifact: { planFile: "chant.tfplan", planDigest: "jcs1-sha256:app" },
+    });
+    expect(calls).toEqual(["init app", 'plan app {"vpc":"v-1"}']);
+  });
+
+  test("plan hands on the root's change-set part, outside the artifact run receives (#3183)", async () => {
+    changeSet = { member: { member: "app" }, entries: [] };
+    const planned = await terraformApplyCapability.plan!({ env: "test", component: "app" }, { root: "app" });
+    expect(planned.changeSet).toEqual(changeSet);
+    expect(planned.artifact).toEqual({ planFile: "chant.tfplan", planDigest: "jcs1-sha256:app" });
+  });
+
+  test("outputs inits the root and reads what its state exposes, planning nothing (#3183)", async () => {
+    expect(await terraformApplyCapability.outputs!({ env: "test", component: "net" }, { root: "net" })).toEqual({ id: "net-id" });
+    expect(calls).toEqual(["init net", "output net"]);
+  });
+
+  test("run applies the wave's plan file without planning again, and returns the root's outputs", async () => {
+    const out = await terraformApplyCapability.run(
+      { env: "test", component: "app", plans: { app: { planFile: "chant.tfplan", planDigest: "jcs1-sha256:app" } } },
+      { root: "app" },
+    );
+    expect(calls).toEqual(["apply app chant.tfplan", "output app"]);
+    expect(out).toEqual({ root: "app", planDigest: "jcs1-sha256:app", fromWavePlan: true, outputs: { id: "app-id" } });
+  });
+
+  test("run without a wave plan plans and applies in one go", async () => {
+    const out = await terraformApplyCapability.run({ env: "test", component: "app" }, { root: "app" });
+    expect(calls).toEqual(["init app", "plan app {}", "apply app chant.tfplan", "output app"]);
+    expect(out.fromWavePlan).toBe(false);
+  });
+
+  test("a refused plan fails the step", async () => {
+    applyResult = { applied: false, refused: "approval-mismatch", refusal: "The approved plan no longer matches the live system" };
+    await expect(
+      terraformApplyCapability.run(
+        { env: "test", component: "app", plans: { app: { planFile: "chant.tfplan", planDigest: "d" } } },
+        { root: "app" },
+      ),
+    ).rejects.toThrow(/refused the plan it was given \(approval-mismatch\)/);
+    expect(calls).not.toContain("output app");
+  });
+});

package/src/components/capability-plugin.ts

@@ -0,0 +1,131 @@
+/**
+ * `terraformCapabilityPlugin` — the terraform lexicon's capability plugin
+ * (#3049). It contributes `terraform-apply`, which lets a component deploy a
+ * root named in `terraform.roots`, so a change across many roots runs as a
+ * `chant components fan-out`: in an order derived from each component's
+ * `dependsOn`, and, with `--wave-gate`, a gate per wave bound to the wave's
+ * set digest.
+ *
+ * The step is `{ kind: "terraform-apply", root: "<name>" }`, with optional
+ * `vars` (passed as `-var`, so `stackOutput()` can hand one root's output to
+ * another) and `cwd`. It works the same for `terraform`, `tofu` and
+ * `choudoufu`, since all three go through the lexicon's activities.
+ *
+ * ## Plan, then apply exactly that plan
+ *
+ * `plan` runs `init` and `plan -out`, and answers with the root as the member
+ * and `terraformPlanDigest` as its digest: the value a `TerraformApplyOp`
+ * gate on this root alone binds (#2300). A gated-wave fan-out folds those into
+ * the wave's set digest and hands the plan file back to `run`, which applies
+ * that file and nothing else. terraform and tofu refuse a saved plan whose
+ * state moved since it was written; choudoufu re-plans against the live
+ * system and refuses with exit 3 when its fresh plan differs (choudoufu
+ * #878). Either refusal fails the step.
+ *
+ * Run without a wave plan (`chant run --components`, or a fan-out with no
+ * wave gate), `run` plans and applies in one go, which is what `terraform
+ * apply` with no plan file does too.
+ */
+
+import type { Capability, DeployContext, CapabilityPlan } from "@intentius/chant/components/capability";
+import type { ChangeSetPart } from "@intentius/chant/change-set";
+import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { terraformApply, terraformInit, terraformOutputs, terraformPlan } from "../op/activities/terraform";
+
+/** The `terraform-apply` step's input. */
+export interface TerraformApplyStepInput {
+  /** Key into `terraform.roots`. Also the member's name in a wave's set digest. */
+  root: string;
+  /** Input variables, after the root's var files. See `TerraformPlanArgs.vars`. */
+  vars?: Record<string, unknown>;
+  /** Where the `chant.config.*` search starts. Default: the current directory. */
+  cwd?: string;
+}
+
+/** What `terraform-apply` returns. `outputs` is what a dependent's `stackOutput()` reads. */
+export interface TerraformApplyStepOutput {
+  root: string;
+  planDigest: string;
+  /** Whether the plan applied came from the wave's plan rather than one made here. */
+  fromWavePlan: boolean;
+  /** `terraform output -json`, as `{ name: value }`. */
+  outputs: Record<string, unknown>;
+}
+
+/** What `plan` hands `run` through `DeployContext.plans`. */
+interface PlannedRoot {
+  planFile: string;
+  planDigest: string;
+}
+
+const rootArgs = (input: TerraformApplyStepInput) => ({ root: input.root, ...(input.cwd ? { cwd: input.cwd } : {}) });
+
+function requireRoot(input: TerraformApplyStepInput): void {
+  if (typeof input.root !== "string" || input.root === "") {
+    throw new Error('terraform-apply: "root" is required and names an entry in terraform.roots');
+  }
+}
+
+async function planRoot(input: TerraformApplyStepInput): Promise<PlannedRoot & { changeSet?: ChangeSetPart }> {
+  requireRoot(input);
+  await terraformInit(rootArgs(input));
+  const planned = await terraformPlan({ ...rootArgs(input), ...(input.vars ? { vars: input.vars } : {}) });
+  return {
+    planFile: planned.planFile,
+    planDigest: planned.planDigest,
+    ...(planned.changeSet ? { changeSet: planned.changeSet } : {}),
+  };
+}
+
+function isPlannedRoot(value: unknown): value is PlannedRoot {
+  const v = value as Partial<PlannedRoot> | undefined;
+  return typeof v?.planFile === "string" && typeof v.planDigest === "string";
+}
+
+export const terraformApplyCapability: Capability<TerraformApplyStepInput, TerraformApplyStepOutput> = {
+  kind: "terraform-apply",
+  // A root's apply has no undo short of applying the previous configuration,
+  // which is a change of its own. COMP003 asks the component to say so.
+  rollbackPolicy: "needs-opt-out",
+  async plan(_ctx: DeployContext, input: TerraformApplyStepInput): Promise<CapabilityPlan> {
+    const { changeSet, ...planned } = await planRoot(input);
+    return { member: input.root, planDigest: planned.planDigest, artifact: planned, ...(changeSet ? { changeSet } : {}) };
+  },
+  // The root's outputs as its state holds them now (#3183): what a dependent
+  // planned before this root applies reads through `stackOutput()`.
+  async outputs(_ctx: DeployContext, input: TerraformApplyStepInput): Promise<Record<string, unknown>> {
+    requireRoot(input);
+    await terraformInit(rootArgs(input));
+    return terraformOutputs(rootArgs(input));
+  },
+  async run(ctx: DeployContext, input: TerraformApplyStepInput): Promise<TerraformApplyStepOutput> {
+    const fromWave = ctx.plans?.[input.root];
+    const planned: PlannedRoot = isPlannedRoot(fromWave) ? fromWave : await planRoot(input);
+    const applied = await terraformApply({ ...rootArgs(input), planFile: planned.planFile });
+    if (!applied.applied) {
+      throw new Error(
+        `terraform-apply: root "${input.root}" refused the plan it was given (${applied.refused ?? "refused"}). ` +
+          (applied.refusal ?? ""),
+      );
+    }
+    const outputs = await terraformOutputs(rootArgs(input));
+    return { root: input.root, planDigest: planned.planDigest, fromWavePlan: isPlannedRoot(fromWave), outputs };
+  },
+};
+
+export const TERRAFORM_VERB_FAMILIES = {
+  apply: ["terraform-apply"],
+} as const;
+
+export const terraformCapabilityPlugin: CapabilityPlugin = {
+  name: "terraform",
+  get version(): string {
+    return ownPackageVersion(import.meta.url);
+  },
+  capabilities(): Array<Capability<never, unknown>> {
+    return [terraformApplyCapability as Capability<never, unknown>];
+  },
+  families(): Record<string, readonly string[]> {
+    return TERRAFORM_VERB_FAMILIES;
+  },
+};