@intentius/chant-lexicon-terraform 0.102.0 → 0.104.0

package/src/lint/post-synth/tf044.ts

@@ -0,0 +1,51 @@
+/**
+ * TF044: a Terragrunt config keeps state in a local backend.
+ *
+ * Read from `remote_state { backend = "local" }` and from a `generate` block
+ * whose `contents` declare `backend "local"`. State on the runner's disk is
+ * gone when the job ends, a second job cannot read what the first applied, and
+ * a git-range run, which checks out each side in a temporary directory, never
+ * sees state at all. A shared backend (S3, GCS, azurerm, a Terraform HTTP
+ * backend) holds it.
+ *
+ * A backend named by an expression is not determined and passes. A local
+ * backend is sometimes right for a throwaway sandbox; suppress the rule there
+ * with `# chant-ignore TF044`.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { TERRAGRUNT_GENERATE_TYPE, TERRAGRUNT_REMOTE_STATE_TYPE } from "../../hcl/parse";
+import { terragruntEntities } from "./terragrunt";
+
+const LOCAL_BACKEND_BLOCK = /\bbackend\s+"local"/;
+
+export const tf044: PostSynthCheck = {
+  id: "TF044",
+  description: "Terragrunt config keeps state in a local backend",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const report = (key: string, file: string, how: string): void => {
+      diagnostics.push({
+        checkId: "TF044",
+        severity: "warning",
+        message:
+          `${how} in ${file} keeps state in a local backend. The state lives on the runner's disk, so a later job cannot read it ` +
+          "and a git-range run, which checks out each side in a temporary directory, never sees it. Use a shared backend such as S3 or GCS.",
+        entity: key,
+        lexicon: "terraform",
+      });
+    };
+
+    for (const block of terragruntEntities(ctx.entities, TERRAGRUNT_REMOTE_STATE_TYPE)) {
+      if (block.body.backend === "local") report(block.key, block.file, "`remote_state` sets `backend = \"local\"`");
+    }
+    for (const block of terragruntEntities(ctx.entities, TERRAGRUNT_GENERATE_TYPE)) {
+      const contents = block.body.contents;
+      if (typeof contents === "string" && LOCAL_BACKEND_BLOCK.test(contents)) {
+        report(block.key, block.file, `\`generate "${block.address.replace(/^generate\./, "")}"\` writes a \`backend "local"\` block`);
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/tf045.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "vitest";
+import { loadTreeFixture } from "./fixtures/load";
+import { tf045 } from "./tf045";
+
+describe("TF045: no Terragrunt config sets terragrunt_version_constraint", () => {
+  test("flags a root.hcl with none, once, anchored on root.hcl", async () => {
+    const ctx = await loadTreeFixture("TF045", "positive");
+    const diags = tf045.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0]).toMatchObject({ checkId: "TF045", severity: "warning", lexicon: "terraform" });
+    expect((ctx.entities.get(diags[0].entity!) as unknown as { props: { file: string } }).props.file).toBe("root.hcl");
+    expect(diags[0].message).toContain("root.hcl");
+  });
+
+  test("a constraint in root.hcl passes", async () => {
+    expect(tf045.check(await loadTreeFixture("TF045", "negative"))).toEqual([]);
+  });
+
+  test("a unit that includes a parent that was not read is not determined", async () => {
+    expect(tf045.check(await loadTreeFixture("TF045", "unit-only"))).toEqual([]);
+  });
+
+  test("a repo with no Terragrunt config reports nothing", async () => {
+    expect(tf045.check({ outputs: new Map(), entities: new Map() } as never)).toEqual([]);
+  });
+
+  test("check metadata", () => {
+    expect(tf045.id).toBe("TF045");
+  });
+});

package/src/lint/post-synth/tf045.ts

@@ -0,0 +1,47 @@
+/**
+ * TF045: no Terragrunt config sets `terragrunt_version_constraint`.
+ *
+ * The attribute makes Terragrunt refuse to run on a release outside the range.
+ * Without it each machine and each CI image runs whatever Terragrunt it
+ * installed, and a behaviour change between releases reaches a plan with no
+ * diff. It is usually set once, in the root config every unit includes.
+ *
+ * The rule looks at the whole set of configs in the scan and reports once. It
+ * reports only when the set holds a config that includes no other file (the
+ * root config, or a self-contained unit) and none of the configs sets the
+ * attribute. A set made only of units that include a parent it did not read,
+ * such as one unit directory passed alone, is not determined: the parent may
+ * set it. The finding is anchored on `root.hcl` when the set has one.
+ *
+ * Off by default: the `report-only` tier keeps it out of the `recommended`
+ * preset, since many repos pin Terragrunt in the toolchain (`.tool-versions`,
+ * a CI image) rather than in config.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { TERRAGRUNT_CONFIG_TYPE } from "../../hcl/parse";
+import { terragruntEntities } from "./terragrunt";
+
+export const tf045: PostSynthCheck = {
+  id: "TF045",
+  description: "No Terragrunt config sets terragrunt_version_constraint",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const configs = terragruntEntities(ctx.entities, TERRAGRUNT_CONFIG_TYPE);
+    if (configs.some((c) => c.body.terragrunt_version_constraint !== undefined)) return [];
+    const tops = configs.filter((c) => Array.isArray(c.body.includes) && c.body.includes.length === 0);
+    if (tops.length === 0) return [];
+    const anchor = [...tops].sort((a, b) => Number(b.file === "root.hcl") - Number(a.file === "root.hcl") || a.key.localeCompare(b.key))[0];
+    return [
+      {
+        checkId: "TF045",
+        severity: "warning",
+        message:
+          `No Terragrunt config sets \`terragrunt_version_constraint\` (${anchor.file} is the top config read). ` +
+          'Set it once in the root config, for example `terragrunt_version_constraint = ">= 1.1.0"`, so every machine runs a release the repo was tested with.',
+        entity: anchor.key,
+        lexicon: "terraform",
+      },
+    ];
+  },
+};

package/src/op/activities/index.ts

@@ -16,6 +16,8 @@
  *   - choudoufuLiveLs: `live-ls -estate=<estate> -json [-consistent]` (#2103).
  *   - choudoufuLiveCheck: `live-check -json`, no cloud calls (#2103).
  *   - choudoufuAdopt: the tag writes that claim an adoption ledger's matches (#2105).
+ *   - terraformPinRollout: one run of a pin-bump rollout, opening at most one
+ *     wave's pull request (#3189). It loads the HCL parser on first call.
  *
  * The module is dependency-light on purpose: it shells out to the configured
  * binary and reads the `terraform` config namespace, and never touches the
@@ -82,3 +84,5 @@ export type {
 } from "./terraform";
 
 export { detectLiveEstate } from "./live-detect";
+export { terraformPinRollout } from "./pin-rollout";
+export type { TerraformPinRolloutArgs, TerraformPinRolloutResult } from "./pin-rollout";

package/src/op/activities/pin-rollout.ts

@@ -0,0 +1,77 @@
+/**
+ * `terraformPinRollout`: one run of a pin-bump rollout (#3189), as an Op
+ * activity. `chant terraform pin-rollout` calls the same function.
+ *
+ * Each run reads where the rollout stands on the forge and opens at most one
+ * wave's pull request (`../../pin/rollout.ts`). Run it again, by hand or on
+ * an Op `schedule`, to move on once a wave's PR has merged and its roots have
+ * applied. A run that finds a failed root or a PR closed without merging
+ * throws, naming it, so the run fails rather than reporting success.
+ *
+ * The HCL parser, the pin code and the TypeScript editor load on first call,
+ * so importing the activities loads none of them.
+ */
+
+import { readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import type { PinRoot, PinRolloutMode, PinRolloutResult } from "../../pin";
+
+export interface TerraformPinRolloutArgs {
+  /** The module, as its `source` names it without the pin: `oci://registry.example.com/modules/vpc`. */
+  module: string;
+  /** The pin the roots are at now. */
+  from: string;
+  /** The pin to move them to: an exact version, tag, ref or `sha256:` digest. */
+  to: string;
+  /** The roots, by directory relative to the repository. Default: every root that calls the module. */
+  roots?: PinRoot[];
+  /** Roots that form wave 1. */
+  canaries?: string[];
+  /** A `choudoufu live-waves -json` document to take the waves from, instead of canaries and dependency order. */
+  wavesFrom?: string;
+  /** The directory choudoufu ran in, relative to the repository, when its roots are relative to that. */
+  wavesPrefix?: string;
+  /** `report` (default) or `pull-request`. */
+  mode?: PinRolloutMode;
+  /** The branch PRs target. Default: the remote's default branch. */
+  base?: string;
+  /** Default `origin`. */
+  remote?: string;
+  /** The apply check each root reports on the merge commit, with `{root}` for its directory. Default `apply/{root}`. */
+  appliedCheck?: string;
+  /** A directory in the repository. Default: the working directory. */
+  cwd?: string;
+}
+
+export type TerraformPinRolloutResult = PinRolloutResult;
+
+/** Run one step of a pin-bump rollout. Throws when the rollout has stopped. */
+export async function terraformPinRollout(args: TerraformPinRolloutArgs): Promise<TerraformPinRolloutResult> {
+  const result = await readPinRollout(args);
+  if (result.status === "stopped") throw new Error(`pin rollout stopped: ${result.stop}\n${result.summary}`);
+  return result;
+}
+
+/** The same run, returning a stopped rollout instead of throwing. `chant terraform pin-rollout` calls this. */
+export async function readPinRollout(args: TerraformPinRolloutArgs): Promise<TerraformPinRolloutResult> {
+  const { loadHcl2json } = await import("@intentius/chant/terraform/hcl2json");
+  const { runPinRollout, wavesFromChoudoufu } = await import("../../pin");
+  const { editPinsInTs } = await import("../../pin/edit-ts");
+  const cwd = args.cwd ?? process.cwd();
+  const waves = args.wavesFrom ? wavesFromChoudoufu(JSON.parse(readFileSync(isAbsolute(args.wavesFrom) ? args.wavesFrom : join(cwd, args.wavesFrom), "utf-8")), args.wavesPrefix) : undefined;
+  return runPinRollout({
+    module: args.module,
+    from: args.from,
+    to: args.to,
+    cwd,
+    parser: await loadHcl2json(),
+    editTs: editPinsInTs,
+    ...(args.roots ? { roots: args.roots } : {}),
+    ...(args.canaries ? { canaries: args.canaries } : {}),
+    ...(waves ? { waves } : {}),
+    ...(args.mode ? { mode: args.mode } : {}),
+    ...(args.base ? { base: args.base } : {}),
+    ...(args.remote ? { remote: args.remote } : {}),
+    ...(args.appliedCheck ? { appliedCheck: args.appliedCheck } : {}),
+  });
+}

package/src/op/activities/terraform.test.ts

@@ -205,6 +205,19 @@ describe("terraformPlanCommand (#2086)", () => {
   test("-destroy is opt-in", () => {
     expect(terraformPlanCommand({ binary: "tofu", planFile: "p", destroy: true })).toContain(" -destroy ");
   });
+
+  test("vars become -var flags after the var files, sorted, non-strings as JSON (#3049)", () => {
+    expect(
+      terraformPlanCommand({
+        binary: "tofu",
+        planFile: "p",
+        varFiles: ["prod.tfvars"],
+        vars: { zones: ["a", "b"], vpc_id: "vpc-1 x" },
+      }),
+    ).toBe(
+      `tofu plan -input=false -detailed-exitcode -var-file=prod.tfvars -var='vpc_id=vpc-1 x' -var='zones=["a","b"]' -out=p`,
+    );
+  });
 });
 
 describe("terraformApplyCommand (#2086)", () => {

package/src/op/activities/terraform.ts

@@ -45,7 +45,9 @@ import { promisify } from "node:util";
 import { resolve, dirname, join } from "node:path";
 import { loadChantConfigUpward } from "@intentius/chant/config";
 import { liveReadKey, memoLiveRead } from "@intentius/chant/live-read-session";
-import { computePlanDigest } from "@intentius/chant/op";
+import { terraformPlanDigest } from "../../plan-digest";
+import { plannerForBinary, terraformChangeSetPart } from "../../change-set";
+import type { ChangeSetPart } from "@intentius/chant/change-set";
 import type { TerraformConfig, TerraformRootConfig } from "../../config";
 import { detectLiveEstate } from "./live-detect";
 import {
@@ -148,6 +150,14 @@ export interface TerraformPlanArgs extends TerraformRootArgs {
   planFile?: string;
   /** `-destroy`: plan the removal of everything the root manages. */
   destroy?: boolean;
+  /**
+   * Input variables, passed as `-var` after the root's `-var-file`s, so they
+   * win over a var file that sets the same name (#3049). A string goes as it
+   * is; anything else as JSON, which terraform reads as HCL for a list, a map
+   * or an object. This is how a value another root produced, wired with
+   * `stackOutput()`, reaches the plan.
+   */
+  vars?: Record<string, unknown>;
 }
 
 export interface TerraformApplyArgs extends TerraformRootArgs {
@@ -249,91 +259,7 @@ export interface PlanChangeCounts {
   destroys: number;
 }
 
-/**
- * One resource's proposed change, as a plan digest sees it (#2300) — the
- * projection of a `terraform show -json` `resource_changes` entry that
- * survives into {@link terraformPlanDigest}.
- */
-export interface TerraformPlannedChange {
-  address: unknown;
-  mode: unknown;
-  type: unknown;
-  name: unknown;
-  index: unknown;
-  provider_name: unknown;
-  deposed: unknown;
-  actions: unknown;
-  before: unknown;
-  after: unknown;
-  after_unknown: unknown;
-  replace_paths: unknown;
-  importing: unknown;
-}
-
-/**
- * The change set a `terraform show -json` plan describes, canonicalised
- * (#2300): every proposed change, at its address, with the values that would
- * be written, sorted so two renderings of the same plan project identically.
- *
- * Everything else in the document is dropped, and the drops are the point —
- * see `packages/core/src/lifecycle/plan-digest.ts` for the general rule. Here
- * that means `timestamp` and `terraform_version` (when the plan was taken and
- * by which binary), `format_version` (how it was rendered), `prior_state` and
- * `planned_values` (restatements of the same change set from another angle),
- * `configuration` (the source that produced it, which can be refactored
- * without changing a single proposed action) and `checks` / `relevant_
- * attributes` (diagnostics about the plan, not the plan). What is left is
- * what applying it would do.
- */
-export function terraformPlanChangeSet(planJson: unknown): {
-  resourceChanges: TerraformPlannedChange[];
-  outputChanges: unknown;
-} {
-  const doc = planJson as { resource_changes?: unknown; output_changes?: unknown } | null | undefined;
-  const raw = Array.isArray(doc?.resource_changes) ? doc.resource_changes : [];
-  const resourceChanges = raw.map((entry): TerraformPlannedChange => {
-    const e = (entry ?? {}) as Record<string, unknown>;
-    const change = (e.change ?? {}) as Record<string, unknown>;
-    return {
-      address: e.address,
-      mode: e.mode,
-      type: e.type,
-      name: e.name,
-      index: e.index,
-      provider_name: e.provider_name,
-      deposed: e.deposed,
-      actions: change.actions,
-      before: change.before,
-      after: change.after,
-      after_unknown: change.after_unknown,
-      replace_paths: change.replace_paths,
-      importing: change.importing,
-    };
-  });
-  // terraform already emits these in address order, but nothing in the format
-  // promises it, and a digest that depends on the emitter's iteration order
-  // would refuse a plan that is identical in every way that matters.
-  resourceChanges.sort((a, b) =>
-    `${String(a.address)}\u0000${String(a.deposed ?? "")}`.localeCompare(
-      `${String(b.address)}\u0000${String(b.deposed ?? "")}`,
-    ),
-  );
-  return { resourceChanges, outputChanges: doc?.output_changes ?? {} };
-}
-
-/**
- * The identity of a terraform plan (#2300): {@link terraformPlanChangeSet}
- * hashed. This is what a `TerraformApplyOp` gate binds its approval to, and
- * what a later run recomputes and compares.
- *
- * Taken over the `show -json` rendering rather than the plan file's bytes on
- * purpose: the file is an opaque, version-stamped archive, and two runs of
- * `plan -out` over an unchanged root produce different bytes. The rendering
- * is the same plan both times.
- */
-export function terraformPlanDigest(planJson: unknown): string {
-  return computePlanDigest("terraform-plan", terraformPlanChangeSet(planJson));
-}
+export { terraformPlanChangeSet, terraformPlanDigest, type TerraformPlannedChange } from "../../plan-digest";
 
 /** What {@link terraformPlan} resolved. Carries the plan itself, so no later step re-plans. */
 export interface TerraformPlanResult extends PlanChangeCounts {
@@ -354,6 +280,13 @@ export interface TerraformPlanResult extends PlanChangeCounts {
    * plan.out.planDigest })`.
    */
   planDigest: string;
+  /**
+   * This root's part of a change-set document (#3181): every proposed change
+   * as an entry, the root's name as the member, and {@link planDigest} as the
+   * member's plan digest. Hand the parts of a run's roots to
+   * `composeChangeSet` and bind the run's gate to the document's digest.
+   */
+  changeSet: ChangeSetPart;
 }
 
 /**
@@ -596,11 +529,16 @@ export function terraformPlanCommand(opts: {
   binary: string;
   planFile: string;
   varFiles?: string[];
+  vars?: Record<string, unknown>;
   destroy?: boolean;
 }): string {
   const parts = [opts.binary, "plan", "-input=false", "-detailed-exitcode"];
   if (opts.destroy) parts.push("-destroy");
   for (const varFile of opts.varFiles ?? []) parts.push(`-var-file=${quoteArg(varFile)}`);
+  for (const [name, value] of Object.entries(opts.vars ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+    if (value === undefined) continue;
+    parts.push(`-var=${quoteArg(`${name}=${typeof value === "string" ? value : JSON.stringify(value)}`)}`);
+  }
   parts.push(`-out=${quoteArg(opts.planFile)}`);
   return parts.join(" ");
 }
@@ -957,6 +895,7 @@ export async function terraformPlan(
     binary,
     planFile,
     ...(root.varFiles ? { varFiles: root.varFiles } : {}),
+    ...(args.vars ? { vars: args.vars } : {}),
     ...(args.destroy ? { destroy: true } : {}),
   });
 
@@ -991,6 +930,12 @@ export async function terraformPlan(
     json,
     text: textRun.stdout,
     planDigest: terraformPlanDigest(json),
+    changeSet: terraformChangeSetPart({
+      member: args.root,
+      plan: json,
+      planner: plannerForBinary(binary),
+      ...((root.estate ?? root.workspace) ? { scope: root.estate ?? root.workspace } : {}),
+    }),
     ...countPlanChanges(json),
   };
 }
@@ -1069,6 +1014,21 @@ export async function terraformApply(
   }
 }
 
+/**
+ * `terraform output -json` in the named root, as `{ name: value }` (#3049).
+ * A sensitive output's value comes back like any other, since the caller
+ * asked for the values to hand them on.
+ */
+export async function terraformOutputs(
+  args: TerraformRootArgs,
+  signal?: AbortSignal,
+): Promise<Record<string, unknown>> {
+  const { binary, root, dir } = await resolveRoot(args, signal);
+  const { stdout } = await run(`${binary} output -json`, dir, terraformEnvironment(root), signal);
+  const parsed = JSON.parse(stdout || "{}") as Record<string, { value?: unknown }>;
+  return Object.fromEntries(Object.entries(parsed).map(([name, entry]) => [name, entry?.value]));
+}
+
 /**
  * `terraform show` over current state, or over a saved plan when `planFile` is
  * given. Returns the parsed `-json` output and the `-no-color` render, plus

package/src/op/activity-contracts.test.ts

@@ -23,6 +23,7 @@ const ACTIVITY_NAMES = [
   "choudoufuLiveLs",
   "choudoufuLiveCheck",
   "choudoufuAdopt",
+  "terraformPinRollout",
 ];
 
 describe("terraform activity contracts (#2101)", () => {
@@ -51,9 +52,11 @@ describe("terraform activity contracts (#2101)", () => {
   });
 
   test("`root` is declared as the entity every step touches (#2022)", () => {
-    for (const name of ACTIVITY_NAMES) {
+    for (const name of ACTIVITY_NAMES.filter((n) => n !== "terraformPinRollout")) {
       expect(CONTRACTS.get(name)?.entities).toEqual(["root"]);
     }
+    // A pin rollout names no `terraform.roots` key: it moves a module across roots found by directory.
+    expect(CONTRACTS.get("terraformPinRollout")?.entities).toBeUndefined();
   });
 
   // ── The failure classes the contracts exist to catch ───────────────────

package/src/op/activity-contracts.ts

@@ -76,6 +76,7 @@ export const terraformPlanContract = activityContract(
     ...rootArgs,
     planFile: z.string().optional(),
     destroy: z.boolean().optional(),
+    vars: z.record(z.string(), z.unknown()).optional(),
   }),
   z.object({
     ...planChangeCounts,
@@ -85,6 +86,8 @@ export const terraformPlanContract = activityContract(
     json: z.unknown(),
     text: z.string(),
     planDigest: z.string(),
+    /** The root's change-set part (#3181); its shape is `@intentius/chant/change-set`'s `ChangeSetPart`. */
+    changeSet: z.object({ member: z.object({ member: z.string(), planDigest: z.string().nullable() }).passthrough(), entries: z.array(z.unknown()) }),
   }),
   rootEntity,
 );
@@ -177,3 +180,42 @@ export const choudoufuAdoptContract = activityContract(
   }),
   rootEntity,
 );
+
+/** One root of a pin-bump rollout ({@link PinRoot} in `../pin/waves.ts`). */
+const pinRoot = z.strictObject({ root: z.string(), dependsOn: z.array(z.string()).optional(), tsSource: z.string().optional() });
+
+/**
+ * `terraformPinRollout` (#3189). It names no `terraform.roots` key: a rollout
+ * moves a module's pin across many roots, found by directory, so it carries no
+ * `rootEntity`. `status` and `summary` are the fields an Op reads: the run's
+ * outcome and a body for a report step.
+ */
+export const terraformPinRolloutContract = activityContract(
+  "terraformPinRollout",
+  z.strictObject({
+    module: z.string(),
+    from: z.string(),
+    to: z.string(),
+    roots: z.array(pinRoot).optional(),
+    canaries: z.array(z.string()).optional(),
+    wavesFrom: z.string().optional(),
+    wavesPrefix: z.string().optional(),
+    mode: z.enum(["report", "pull-request"]).optional(),
+    base: z.string().optional(),
+    remote: z.string().optional(),
+    appliedCheck: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({
+    module: z.string(),
+    from: z.string(),
+    to: z.string(),
+    mode: z.enum(["report", "pull-request"]),
+    base: z.string(),
+    status: z.enum(["complete", "opened", "would-open", "waiting", "stopped"]),
+    roots: z.array(z.object({}).loose()),
+    waves: z.array(z.object({}).loose()),
+    stop: z.string().optional(),
+    summary: z.string(),
+  }),
+);

package/src/op/builders.ts

@@ -32,6 +32,7 @@ import type {
   ChoudoufuLiveCheckArgs,
   ChoudoufuAdoptArgs,
 } from "./activities/terraform";
+import type { TerraformPinRolloutArgs } from "./activities/pin-rollout";
 
 /** Extra opts every wrapper below accepts alongside its activity's own fields. */
 type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
@@ -184,3 +185,15 @@ export const terraformShow = (
     { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) },
   );
 };
+
+/**
+ * One run of a pin-bump rollout (#3189). `opts` is
+ * {@link TerraformPinRolloutArgs} itself. It names no root: the rollout finds
+ * the roots that call the module. Defaults to the `fastIdempotent` profile: a
+ * repeated run reads the forge again and finds the PR an earlier attempt
+ * opened.
+ */
+export const terraformPinRollout = (opts: WithStepRefs<TerraformPinRolloutArgs> & StepOpts): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown>);
+  return activity("terraformPinRollout", args, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};

package/src/pin/bundle.test.ts

@@ -0,0 +1,53 @@
+/**
+ * The pin subpath bundles small (#3189, ruling #3421).
+ *
+ * terragucci's `tf-rollout` stage runs this code from one bundled file with
+ * no TypeScript toolchain. So `@intentius/chant-lexicon-terraform/pin` must
+ * not reach `typescript`, esbuild, zod, the HCL parser's wasm package, or
+ * chant's fold, lint and codegen modules. The TypeScript editor for generated
+ * roots (`./edit-ts.ts`) stays out of it. This bundles the entry point the way
+ * terragucci would and reads esbuild's own list of what went in, the same
+ * check `packages/core/src/change-set-bundle.test.ts` makes.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+
+const REPO = join(new URL(".", import.meta.url).pathname, "..", "..", "..", "..");
+
+/** About 35 KB today, unminified. */
+const BUDGET_BYTES = 60 * 1024;
+
+const FORBIDDEN = [/node_modules\/typescript\//, /node_modules\/esbuild\//, /node_modules\/zod\//, /node_modules\/@cdktn\//, /\/src\/fold\//, /\/src\/lint\//, /\/src\/codegen\//, /edit-ts\.ts$/];
+
+describe("the pin bundle", () => {
+  test("holds the edit, the wave plan and the rollout, and nothing heavier", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "lexicons", "terraform", "src", "pin", "index.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    expect(inputs.map((i) => i.replace(/^.*?(packages|lexicons)\//, "$1/")).sort()).toEqual([
+      "lexicons/terraform/src/pin/edit.ts",
+      "lexicons/terraform/src/pin/forge.ts",
+      "lexicons/terraform/src/pin/index.ts",
+      "lexicons/terraform/src/pin/rollout.ts",
+      "lexicons/terraform/src/pin/scan.ts",
+      "lexicons/terraform/src/pin/source.ts",
+      "lexicons/terraform/src/pin/waves.ts",
+      "packages/core/src/components/layers.ts",
+    ]);
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(BUDGET_BYTES);
+  });
+});

package/src/pin/edit-ts.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "vitest";
+import { editPinsInTs } from "./edit-ts";
+
+const OCI = "oci://registry.example.com/modules/vpc";
+
+describe("editPinsInTs (#3189)", () => {
+  test("moves the pin in a module declaration and leaves every other byte", () => {
+    const before = [
+      `// source: "${OCI}?tag=1.3.0" in a comment is not a declaration`,
+      `export const vpc = module("vpc", {`,
+      `  source: '${OCI}?tag=1.3.0',`,
+      `  cidr: "10.0.0.0/16",`,
+      `});`,
+      `export const registry = new TerraformModule({ source: "app.terraform.io/acme/vpc/aws", version: "= 1.3.0" });`,
+      `export const other = module("dns", { source: "${OCI.replace("vpc", "dns")}?tag=1.3.0" });`,
+      ``,
+    ].join("\n");
+    const after = editPinsInTs(before, "infra/vpc.ts", { module: OCI, from: "1.3.0", to: "1.4.0" });
+    expect(after.content).toBe(before.replace(`'${OCI}?tag=1.3.0'`, `'${OCI}?tag=1.4.0'`));
+    expect(after.calls).toMatchObject([{ outcome: "moved", file: "infra/vpc.ts", call: "line 2" }]);
+
+    const registry = editPinsInTs(before, "infra/vpc.ts", { module: "app.terraform.io/acme/vpc/aws", from: "1.3.0", to: "1.4.0" });
+    expect(registry.content).toBe(before.replace(`version: "= 1.3.0"`, `version: "= 1.4.0"`));
+  });
+
+  test("refuses a floating constraint with its reason", () => {
+    const before = `export const m = { source: "app.terraform.io/acme/vpc/aws", version: "~> 1.3" };\n`;
+    const result = editPinsInTs(before, "m.ts", { module: "app.terraform.io/acme/vpc/aws", from: "1.3.0", to: "1.4.0" });
+    expect(result.content).toBe(before);
+    expect(result.calls).toMatchObject([{ outcome: "refused", reason: expect.stringMatching(/is a constraint, not a pin/) }]);
+  });
+
+  test("refuses a version built from an expression", () => {
+    const before = `const v = "1.3.0";\nexport const m = { source: "app.terraform.io/acme/vpc/aws", version: v };\n`;
+    const result = editPinsInTs(before, "m.ts", { module: "app.terraform.io/acme/vpc/aws", from: "1.3.0", to: "1.4.0" });
+    expect(result.content).toBe(before);
+    expect(result.calls).toMatchObject([{ outcome: "refused", reason: expect.stringMatching(/expression/) }]);
+  });
+});