@intentius/chant-lexicon-terraform 0.124.78 → 0.124.80

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/dist/change-set.d.ts +1 -0
  2. package/dist/change-set.d.ts.map +1 -1
  3. package/dist/change-set.js +19 -0
  4. package/dist/components/capability-plugin.d.ts +75 -2
  5. package/dist/components/capability-plugin.d.ts.map +1 -1
  6. package/dist/components/capability-plugin.js +250 -142
  7. package/dist/components/compose-group.d.ts +2 -1
  8. package/dist/components/compose-group.d.ts.map +1 -1
  9. package/dist/components/compose-group.js +6 -6
  10. package/dist/index.d.ts +1 -1
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +3 -1
  13. package/dist/integrity.json +2 -2
  14. package/dist/manifest.json +1 -1
  15. package/dist/op/activities/terraform.d.ts +33 -0
  16. package/dist/op/activities/terraform.d.ts.map +1 -1
  17. package/dist/op/activities/terraform.js +37 -5
  18. package/dist/state-reads.d.ts +20 -3
  19. package/dist/state-reads.d.ts.map +1 -1
  20. package/dist/state-reads.js +20 -4
  21. package/dist/terragrunt/capability.d.ts +129 -0
  22. package/dist/terragrunt/capability.d.ts.map +1 -0
  23. package/dist/terragrunt/capability.js +352 -0
  24. package/dist/terragrunt/index.d.ts +3 -1
  25. package/dist/terragrunt/index.d.ts.map +1 -1
  26. package/dist/terragrunt/index.js +3 -1
  27. package/dist/terragrunt/units.d.ts +9 -0
  28. package/dist/terragrunt/units.d.ts.map +1 -1
  29. package/dist/terragrunt/units.js +25 -0
  30. package/package.json +2 -2
  31. package/src/change-set.test.ts +27 -1
  32. package/src/change-set.ts +19 -0
  33. package/src/components/capability-plugin.test.ts +61 -6
  34. package/src/components/capability-plugin.ts +290 -139
  35. package/src/components/compose-group.ts +8 -7
  36. package/src/components/compose-op-wave.test.ts +134 -0
  37. package/src/components/terraform-apply-op-wave.test.ts +295 -0
  38. package/src/index.ts +5 -0
  39. package/src/op/activities/terraform.test.ts +21 -0
  40. package/src/op/activities/terraform.ts +64 -4
  41. package/src/state-reads.ts +23 -5
  42. package/src/terragrunt/capability.test.ts +348 -0
  43. package/src/terragrunt/capability.ts +437 -0
  44. package/src/terragrunt/index.ts +3 -1
  45. package/src/terragrunt/units.ts +25 -0
@@ -0,0 +1,437 @@
1
+ /**
2
+ * `terragrunt-apply` (#4842): Terragrunt units as an op wave's step. A
3
+ * `discover` wave finds its units at plan time from `terragrunt find`, and a
4
+ * `together` wave plans and applies them with one `terragrunt run --all`, the
5
+ * way a Terragrunt repo runs a layer of its graph:
6
+ *
7
+ * ```json
8
+ * { "step": { "kind": "terragrunt-apply", "unit": "{target}" },
9
+ * "waves": [{ "name": "layer", "runs": [], "discover": true, "together": true },
10
+ * { "name": "rest", "runs": [], "discover": true, "together": true, "rest": true }] }
11
+ * ```
12
+ *
13
+ * - `discoverRuns` runs `terragrunt find` and cuts the units into waves by
14
+ * their dependencies (`terragruntWaves`), or, with `layers`, cuts each
15
+ * listed wave again by the graph (`terragruntListedWaves`). It answers
16
+ * wave k's units and how many waves there are.
17
+ * - `planGroup` plans the wave's units with one `run --all` into the work
18
+ * directory (`planTerragruntWave`, which refuses a wave that would read
19
+ * `mock_outputs`). Each unit's member is its change-set part, and its
20
+ * artifact names its plan JSON (`planJson`), which a cost hold and the
21
+ * after-plan hooks read. A unit that did not plan fails the wave.
22
+ * - `runGroup` applies exactly those saved plans with one `run --all`
23
+ * (`applyTerragruntWave`) and says how each unit's part ended.
24
+ * - `plan` and `run` do the same for one unit, for a wave planned run by
25
+ * run (a share job's slice).
26
+ *
27
+ * A run hook's `processEnv` is laid over the environment Terragrunt runs
28
+ * with; the units of one `run --all` must agree on it. Terragrunt has no
29
+ * init of its own before the plan, so `afterInit` is called before it plans.
30
+ * A product passes its own `exec` (`terragruntApplyCapability`) to wrap
31
+ * Terragrunt, as terragucci adds its lock timeout and its backend bootstrap.
32
+ *
33
+ * A unit may pin its own releases (#4849): the binary Terragrunt calls and
34
+ * Terragrunt itself. One `run --all` runs one Terragrunt with one
35
+ * `TG_TF_PATH`, so `resolveUnit` says what each unit runs, and a wave plans
36
+ * and applies as one `run --all` per pair of releases, each in a work
37
+ * directory of its own. The units of a wave read none of each other, so
38
+ * splitting it changes only how many processes run it. Each unit keeps its
39
+ * member digest, and the wave its `(wave plan)` member. A product passes its
40
+ * own resolver (terragucci's `UnitBinaries`), or
41
+ * {@link terragruntUnitPinResolver}, which reads the pins from the units'
42
+ * files and asks the product where each pinned release is.
43
+ */
44
+
45
+ import { createHash } from "node:crypto";
46
+ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
47
+ import { basename, join } from "node:path";
48
+ import type { Capability, CapabilityGroupOutcome, CapabilityGroupPlan, CapabilityPlan, DeployContext, DiscoveredRuns, GroupMember, GroupMemberOutcome, RunDiscoveryContext } from "@intentius/chant/components/capability";
49
+ import type { ChangeSetPart } from "@intentius/chant/change-set";
50
+ import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
51
+ import { applyTerragruntWave, defaultTerragruntExec, discoverTerragruntUnits, planTerragruntWave, TerragruntMockRefusal, type TerragruntExec } from "./run";
52
+ import { terragruntListedWaves, terragruntWaves } from "./units";
53
+
54
+ /** The step's input. Each string has `{target}`, `{op}` and `{wave}` filled per run in an op wave. */
55
+ export interface TerragruntApplyStepInput {
56
+ /** The unit, by path relative to `dir`: `{target}`. */
57
+ unit: string;
58
+ /** The project directory Terragrunt runs in. Default: the job's directory. */
59
+ dir?: string;
60
+ /** The `terragrunt` executable. Default `terragrunt` on PATH. */
61
+ terragrunt?: string;
62
+ /** The binary Terragrunt calls (`TG_TF_PATH`). Unset leaves Terragrunt's own choice. */
63
+ binary?: string;
64
+ /** Globs discovery leaves out, beside catalog templates and the module cache. */
65
+ exclude?: string[];
66
+ /** Discovery: the waves as a pipeline lists them, each cut again by the graph. Default: the graph's own layers. */
67
+ layers?: string[][];
68
+ /** Discovery without `layers`: unit globs that form the first waves. */
69
+ canary?: string[];
70
+ /** `--parallelism` for a `run --all`. */
71
+ parallelism?: number;
72
+ /** Where the saved plans go, relative to `dir`. Default `.chant/terragrunt-apply`. */
73
+ workDir?: string;
74
+ /** Plan a destroy (`plan -destroy`, `--filter-allow-destroy`). */
75
+ destroy?: boolean;
76
+ }
77
+
78
+ /** What `run` and `runGroup` hand back for a unit. */
79
+ export interface TerragruntApplyStepOutput {
80
+ unit: string;
81
+ applied: true;
82
+ }
83
+
84
+ /** What `plan` and `planGroup` keep for the apply: the work directory and the units planned into it. */
85
+ interface TerragruntWaveArtifact {
86
+ kind: "terragrunt-apply";
87
+ /** The first group's work directory. */
88
+ workDir: string;
89
+ units: string[];
90
+ /** Each group's units, work directory and releases (#4849). Absent on a plan from before them: one group on the step's releases. */
91
+ groups?: TerragruntUnitGroup[];
92
+ }
93
+
94
+ /** The units of a wave that run one pair of releases, as one `run --all`. */
95
+ interface TerragruntUnitGroup {
96
+ units: string[];
97
+ workDir: string;
98
+ terragrunt?: string;
99
+ binary?: string;
100
+ }
101
+
102
+ /** What one unit runs (#4849): the `terragrunt` and the binary it calls. An unset field runs the step's. */
103
+ export interface TerragruntUnitTools {
104
+ terragrunt?: string;
105
+ binary?: string;
106
+ }
107
+
108
+ /** Says what a unit runs, from its pins (#4849). It may install a release, and is asked once per unit per plan or apply. */
109
+ export type TerragruntUnitResolver = (unit: string, input: TerragruntApplyStepInput) => TerragruntUnitTools | Promise<TerragruntUnitTools>;
110
+
111
+ /** A unit's own artifact: its plan document, for `{planJson}`. */
112
+ interface TerragruntUnitArtifact {
113
+ kind: "terragrunt-apply-unit";
114
+ workDir: string;
115
+ unit: string;
116
+ planJson: string;
117
+ }
118
+
119
+ export interface TerragruntApplyDeps {
120
+ /** How Terragrunt runs. Default {@link defaultTerragruntExec}. */
121
+ exec?: TerragruntExec;
122
+ /** What each unit runs, when units pin their own releases (#4849). Unset: every unit runs the step's `terragrunt` and `binary`. */
123
+ resolveUnit?: TerragruntUnitResolver;
124
+ }
125
+
126
+ /** The binaries a unit may pin a release of, and the file that pins each. */
127
+ const VERSION_FILES = { tofu: ".opentofu-version", terraform: ".terraform-version" } as const;
128
+ type PinnedTool = keyof typeof VERSION_FILES;
129
+ const RELEASE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.]+)?$/;
130
+
131
+ /** What a unit's own files pin (#4849). */
132
+ export interface TerragruntUnitPins {
133
+ binary?: { tool: PinnedTool; version: string; source: ".opentofu-version" | ".terraform-version" | "required_version" };
134
+ terragrunt?: { version: string; source: "terragrunt_version_constraint" };
135
+ }
136
+
137
+ const stripComments = (text: string): string => text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"])(#|\/\/).*$/gm, "$1");
138
+
139
+ /** Every exact `required_version` (`= 1.13.1` or `1.13.1`) in one directory's Terraform files. */
140
+ function exactRequiredVersions(dir: string): string[] {
141
+ let names: string[];
142
+ try {
143
+ names = readdirSync(dir).filter((n) => n.endsWith(".tf") || n.endsWith(".tofu") || n.endsWith(".tf.json") || n.endsWith(".tofu.json"));
144
+ } catch {
145
+ return [];
146
+ }
147
+ const out: string[] = [];
148
+ for (const n of names) {
149
+ const f = join(dir, n);
150
+ if (!statSync(f).isFile()) continue;
151
+ const m = stripComments(readFileSync(f, "utf-8")).match(/required_version\s*=\s*"\s*=?\s*(\d+\.\d+\.\d+)\s*"/);
152
+ if (m && !out.includes(m[1]!)) out.push(m[1]!);
153
+ }
154
+ return out;
155
+ }
156
+
157
+ /**
158
+ * What `unit` (relative to `dir`) pins, read as terragucci reads it: the
159
+ * binary from a `.opentofu-version` (tofu) or `.terraform-version`
160
+ * (terraform), whose first line that is not a comment is an exact release,
161
+ * else one exact `required_version` in its Terraform files; Terragrunt from
162
+ * an exact `terragrunt_version_constraint` (`"= 1.1.5"`) in its
163
+ * `terragrunt.hcl`. `binary` is the one the step runs: only tofu and
164
+ * terraform are pinned. A product's own pins, such as terragucci.yml's
165
+ * `version` map, go in its own resolver.
166
+ */
167
+ export function terragruntUnitPins(dir: string, unit: string, binary: string): TerragruntUnitPins {
168
+ const at = join(dir, unit);
169
+ const out: TerragruntUnitPins = {};
170
+ const name = basename(binary);
171
+ if (name === "tofu" || name === "terraform") {
172
+ const file = join(at, VERSION_FILES[name]);
173
+ const line = existsSync(file) ? readFileSync(file, "utf-8").split("\n").map((l) => l.trim()).find((l) => l !== "" && !l.startsWith("#")) : undefined;
174
+ const v = line?.replace(/^v/, "");
175
+ const required = exactRequiredVersions(at);
176
+ if (v && RELEASE.test(v)) out.binary = { tool: name, version: v, source: VERSION_FILES[name] };
177
+ else if (required.length === 1) out.binary = { tool: name, version: required[0]!, source: "required_version" };
178
+ }
179
+ const hcl = join(at, "terragrunt.hcl");
180
+ if (existsSync(hcl)) {
181
+ const text = readFileSync(hcl, "utf-8").replace(/(^|[^:"])(#|\/\/).*$/gm, "$1");
182
+ const tg = /^\s*terragrunt_version_constraint\s*=\s*"\s*=?\s*v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)\s*"/m.exec(text)?.[1];
183
+ if (tg) out.terragrunt = { version: tg, source: "terragrunt_version_constraint" };
184
+ }
185
+ return out;
186
+ }
187
+
188
+ export interface TerragruntUnitPinResolverOptions {
189
+ /** The path of a pinned release's executable, installing it if it must. Asked once per tool and version. */
190
+ release: (tool: PinnedTool | "terragrunt", version: string, unit: string) => string | Promise<string>;
191
+ /** The releases the step's own `binary` and `terragrunt` are: a unit pinned to one of them runs the step's. */
192
+ carried?: Partial<Record<PinnedTool | "terragrunt", string>>;
193
+ }
194
+
195
+ /** A {@link TerragruntUnitResolver} from the units' own pins ({@link terragruntUnitPins}). The step's `binary` defaults to tofu, as Terragrunt's does. */
196
+ export function terragruntUnitPinResolver(options: TerragruntUnitPinResolverOptions): TerragruntUnitResolver {
197
+ const releases = new Map<string, Promise<string>>();
198
+ const releaseOf = (tool: PinnedTool | "terragrunt", version: string, unit: string): Promise<string> => {
199
+ const key = `${tool}@${version}`;
200
+ let p = releases.get(key);
201
+ if (!p) {
202
+ p = Promise.resolve(options.release(tool, version, unit));
203
+ releases.set(key, p);
204
+ }
205
+ return p;
206
+ };
207
+ return async (unit, input) => {
208
+ const pins = terragruntUnitPins(dirOf(input), unit, input.binary ?? "tofu");
209
+ const out: TerragruntUnitTools = {};
210
+ if (pins.binary && pins.binary.version !== options.carried?.[pins.binary.tool]) out.binary = await releaseOf(pins.binary.tool, pins.binary.version, unit);
211
+ if (pins.terragrunt && pins.terragrunt.version !== options.carried?.terragrunt) out.terragrunt = await releaseOf("terragrunt", pins.terragrunt.version, unit);
212
+ return out;
213
+ };
214
+ }
215
+
216
+ const DEFAULT_WORK_DIR = ".chant/terragrunt-apply";
217
+
218
+ const dirOf = (input: TerragruntApplyStepInput): string => input.dir ?? process.cwd();
219
+
220
+ /** The step's input with the wave's directory as its `dir` when it names none (chant#4854). */
221
+ const atDir = <T extends TerragruntApplyStepInput | undefined>(input: T, cwd: string | undefined): T => (input && input.dir === undefined && cwd !== undefined ? { ...input, dir: cwd } : input);
222
+
223
+ /** The work directory of a `run --all` over `units`: one per set of units, so a wave and a unit of it never share one. */
224
+ function workDirOf(input: TerragruntApplyStepInput, units: readonly string[]): string {
225
+ const key = createHash("sha256").update(JSON.stringify([...units].sort())).digest("hex").slice(0, 16);
226
+ return join(input.workDir ?? DEFAULT_WORK_DIR, key);
227
+ }
228
+
229
+ /** `exec` with `env` laid over what each call adds. */
230
+ function withEnv(exec: TerragruntExec, env: Record<string, string> | undefined): TerragruntExec {
231
+ if (!env) return exec;
232
+ return (file, args, o) => exec(file, args, { ...o, env: { ...o.env, ...env } });
233
+ }
234
+
235
+ /** The settings every unit of one `run --all` shares; throws when members disagree. */
236
+ function shared(members: readonly GroupMember<TerragruntApplyStepInput>[]): { input: TerragruntApplyStepInput; units: string[]; env?: Record<string, string> } {
237
+ if (members.length === 0) throw new Error("terragrunt-apply: a wave needs at least one unit");
238
+ const inputs = members.map((m) => atDir(m.input ?? (m.step as unknown as TerragruntApplyStepInput), m.ctx.cwd));
239
+ for (const i of inputs) if (typeof i.unit !== "string" || i.unit === "") throw new Error("terragrunt-apply: each run names its unit");
240
+ const first = inputs[0]!;
241
+ const key = (i: TerragruntApplyStepInput) => JSON.stringify([i.dir, i.terragrunt, i.binary, i.parallelism, i.workDir, i.destroy === true]);
242
+ if (inputs.some((i) => key(i) !== key(first))) throw new Error("terragrunt-apply: the wave's units run as one run --all, so they need the same dir, terragrunt, binary, parallelism, workDir and destroy");
243
+ const envs = members.map((m) => JSON.stringify(m.ctx.processEnv ?? {}));
244
+ if (envs.some((e) => e !== envs[0])) throw new Error("terragrunt-apply: the wave's units run as one run --all with one environment, and the run hooks gave them different ones");
245
+ const env = members[0]!.ctx.processEnv;
246
+ return { input: first, units: inputs.map((i) => i.unit), ...(env ? { env } : {}) };
247
+ }
248
+
249
+ /** Each unit's plan from a planned wave, or throws naming each unit that did not plan. */
250
+ function unitPlans(parts: readonly ChangeSetPart[], units: readonly string[], workDir: string, dir: string): Map<string, CapabilityPlan> {
251
+ const failed = parts.filter((p) => p.member.status === "failed" || typeof p.member.planDigest !== "string");
252
+ if (failed.length > 0) throw new Error(`terragrunt-apply: ${failed.map((p) => `${p.member.member}: ${p.member.error ?? "not planned"}`).join("; ")}`);
253
+ const out = new Map<string, CapabilityPlan>();
254
+ for (const part of parts) {
255
+ const unit = part.member.member;
256
+ const artifact: TerragruntUnitArtifact = { kind: "terragrunt-apply-unit", workDir, unit, planJson: join(dir, workDir, "json", unit, "tfplan.json") };
257
+ out.set(unit, { member: unit, planDigest: part.member.planDigest as string, artifact, changeSet: part });
258
+ }
259
+ const missing = units.filter((u) => !out.has(u));
260
+ if (missing.length > 0) throw new Error(`terragrunt-apply: Terragrunt planned no ${missing.join(", ")}`);
261
+ return out;
262
+ }
263
+
264
+ async function planUnits(exec: TerragruntExec, input: TerragruntApplyStepInput, units: readonly string[], env: Record<string, string> | undefined): Promise<{ workDir: string; plans: Map<string, CapabilityPlan> }> {
265
+ const dir = dirOf(input);
266
+ const workDir = workDirOf(input, units);
267
+ const planned = await planTerragruntWave({
268
+ dir,
269
+ units,
270
+ workDir,
271
+ exec: withEnv(exec, env),
272
+ ...(input.terragrunt ? { terragrunt: input.terragrunt } : {}),
273
+ ...(input.binary ? { binary: input.binary } : {}),
274
+ ...(input.parallelism !== undefined ? { parallelism: input.parallelism } : {}),
275
+ ...(input.destroy ? { destroy: true } : {}),
276
+ });
277
+ return { workDir, plans: unitPlans(planned.parts, units, workDir, dir) };
278
+ }
279
+
280
+ async function applyUnits(exec: TerragruntExec, input: TerragruntApplyStepInput, units: readonly string[], workDir: string, env: Record<string, string> | undefined) {
281
+ return applyTerragruntWave({
282
+ dir: dirOf(input),
283
+ units,
284
+ workDir,
285
+ exec: withEnv(exec, env),
286
+ ...(input.terragrunt ? { terragrunt: input.terragrunt } : {}),
287
+ ...(input.binary ? { binary: input.binary } : {}),
288
+ ...(input.parallelism !== undefined ? { parallelism: input.parallelism } : {}),
289
+ ...(input.destroy ? { destroy: true } : {}),
290
+ });
291
+ }
292
+
293
+ /** The step's input with what `unit` runs in place of the step's `terragrunt` and `binary`. */
294
+ async function unitInput(resolveUnit: TerragruntUnitResolver | undefined, input: TerragruntApplyStepInput, unit: string): Promise<TerragruntApplyStepInput> {
295
+ if (!resolveUnit) return input;
296
+ const t = await resolveUnit(unit, input);
297
+ return { ...input, ...(t.terragrunt ? { terragrunt: t.terragrunt } : {}), ...(t.binary ? { binary: t.binary } : {}) };
298
+ }
299
+
300
+ /** A wave's units by the pair of releases they run, the step's own pair first, each with the input its `run --all` takes. */
301
+ async function groupUnits(resolveUnit: TerragruntUnitResolver | undefined, input: TerragruntApplyStepInput, units: readonly string[]): Promise<{ input: TerragruntApplyStepInput; units: string[] }[]> {
302
+ const key = (i: TerragruntApplyStepInput): string => JSON.stringify([i.terragrunt ?? null, i.binary ?? null]);
303
+ const own = key(input);
304
+ const byKey = new Map<string, { input: TerragruntApplyStepInput; units: string[] }>();
305
+ for (const u of units) {
306
+ const i = await unitInput(resolveUnit, input, u);
307
+ const k = key(i);
308
+ if (!byKey.has(k)) byKey.set(k, { input: i, units: [] });
309
+ byKey.get(k)!.units.push(u);
310
+ }
311
+ const groups = [...byKey.entries()];
312
+ groups.sort(([a], [b]) => (a === own ? -1 : b === own ? 1 : 0));
313
+ return groups.map(([, g]) => g);
314
+ }
315
+
316
+ /**
317
+ * Plan each group with its own `run --all`. A group whose units would read
318
+ * `mock_outputs` is refused as one wave is: every group still plans, then one
319
+ * refusal names every read.
320
+ */
321
+ async function planGroups(exec: TerragruntExec, groups: { input: TerragruntApplyStepInput; units: string[] }[], env: Record<string, string> | undefined): Promise<{ groups: TerragruntUnitGroup[]; plans: Map<string, CapabilityPlan> }> {
322
+ const reads: TerragruntMockRefusal["reads"] = [];
323
+ const out: TerragruntUnitGroup[] = [];
324
+ const plans = new Map<string, CapabilityPlan>();
325
+ for (const g of groups) {
326
+ let planned: Awaited<ReturnType<typeof planUnits>>;
327
+ try {
328
+ planned = await planUnits(exec, g.input, g.units, env);
329
+ } catch (e) {
330
+ if (e instanceof TerragruntMockRefusal && groups.length > 1) {
331
+ reads.push(...e.reads);
332
+ continue;
333
+ }
334
+ throw e;
335
+ }
336
+ out.push({ units: g.units, workDir: planned.workDir, ...(g.input.terragrunt ? { terragrunt: g.input.terragrunt } : {}), ...(g.input.binary ? { binary: g.input.binary } : {}) });
337
+ for (const [u, p] of planned.plans) plans.set(u, p);
338
+ }
339
+ if (reads.length > 0) throw new TerragruntMockRefusal(reads);
340
+ return { groups: out, plans };
341
+ }
342
+
343
+ const isWaveArtifact = (v: unknown): v is TerragruntWaveArtifact => (v as { kind?: unknown } | undefined)?.kind === "terragrunt-apply" && Array.isArray((v as { units?: unknown }).units);
344
+ const isUnitArtifact = (v: unknown): v is TerragruntUnitArtifact => (v as { kind?: unknown } | undefined)?.kind === "terragrunt-apply-unit";
345
+
346
+ /** The `terragrunt-apply` capability, with `deps` in place of the defaults. */
347
+ export function terragruntApplyCapability(deps: TerragruntApplyDeps = {}): Capability<TerragruntApplyStepInput, TerragruntApplyStepOutput> {
348
+ const exec = deps.exec ?? defaultTerragruntExec;
349
+ const resolveUnit = deps.resolveUnit;
350
+ return {
351
+ kind: "terragrunt-apply",
352
+ rollbackPolicy: "needs-opt-out",
353
+ // A unit plans and applies as a whole, and Terragrunt takes each unit's own backend lock.
354
+ defaultLockGrain: () => "target",
355
+
356
+ async discoverRuns(ctx: RunDiscoveryContext, given: TerragruntApplyStepInput): Promise<DiscoveredRuns> {
357
+ const input = atDir(given, ctx.cwd);
358
+ const found = await discoverTerragruntUnits({
359
+ dir: dirOf(input),
360
+ exec,
361
+ ...(input.terragrunt ? { terragrunt: input.terragrunt } : {}),
362
+ ...(input.binary ? { binary: input.binary } : {}),
363
+ ...(input.exclude ? { exclude: input.exclude } : {}),
364
+ });
365
+ const waves = (input.layers ? terragruntListedWaves(input.layers, found.units) : terragruntWaves(found.units, input.canary ? { canary: input.canary } : {})).filter((w) => w.length > 0);
366
+ return { targets: waves[ctx.wave.number - 1] ?? [], waves: waves.length };
367
+ },
368
+
369
+ async plan(ctx: DeployContext, given: TerragruntApplyStepInput): Promise<CapabilityPlan> {
370
+ const input = atDir(given, ctx.cwd);
371
+ if (typeof input.unit !== "string" || input.unit === "") throw new Error("terragrunt-apply: the step names no unit");
372
+ await ctx.afterInit?.();
373
+ const { plans } = await planUnits(exec, await unitInput(resolveUnit, input, input.unit), [input.unit], ctx.processEnv);
374
+ return plans.get(input.unit)!;
375
+ },
376
+
377
+ async run(ctx: DeployContext, step: TerragruntApplyStepInput): Promise<TerragruntApplyStepOutput> {
378
+ const input = atDir(step, ctx.cwd);
379
+ const given = ctx.plans?.[input.unit];
380
+ const own = await unitInput(resolveUnit, input, input.unit);
381
+ // A unit with no plan from the wave plans now and applies that plan.
382
+ const workDir = isUnitArtifact(given) ? given.workDir : (await planUnits(exec, own, [input.unit], ctx.processEnv)).workDir;
383
+ const applied = await applyUnits(exec, own, [input.unit], workDir, ctx.processEnv);
384
+ const result = applied.results.find((r) => r.unit === input.unit);
385
+ if (result?.status !== "succeeded") throw new Error(`terragrunt-apply: ${input.unit}: ${result?.error ?? "Terragrunt did not apply it"}`);
386
+ return { unit: input.unit, applied: true };
387
+ },
388
+
389
+ async planGroup(_ctx, members): Promise<CapabilityGroupPlan> {
390
+ const { input, units, env } = shared(members);
391
+ for (const m of members) await m.ctx.afterInit?.();
392
+ const { groups, plans } = await planGroups(exec, await groupUnits(resolveUnit, input, units), env);
393
+ const artifact: TerragruntWaveArtifact = { kind: "terragrunt-apply", workDir: groups[0]!.workDir, units: [...units], groups };
394
+ // One group hashes as a wave always has; more name each group's units. Not the releases' paths, which depend on where a job installed them: each unit's plan digest covers what its release planned.
395
+ const digest = computePlanDigest("terragrunt-apply-wave", {
396
+ units: [...units].sort(),
397
+ destroy: input.destroy === true,
398
+ ...(groups.length > 1 ? { groups: groups.map((g) => [...g.units].sort()).sort((a, b) => a.join("\u0000").localeCompare(b.join("\u0000"))) } : {}),
399
+ });
400
+ return { members: Object.fromEntries(members.map((m) => [m.component, plans.get(m.input?.unit ?? (m.step.unit as string))!])), digest, artifact };
401
+ },
402
+
403
+ async runGroup(_ctx, run, members): Promise<CapabilityGroupOutcome> {
404
+ const { input, units, env } = shared(members);
405
+ if (!isWaveArtifact(run.artifact)) throw new Error("terragrunt-apply: no plan of the wave to apply");
406
+ const planned = new Set(run.artifact.units);
407
+ const unplanned = units.filter((u) => !planned.has(u));
408
+ if (unplanned.length > 0) throw new Error(`terragrunt-apply: ${unplanned.join(", ")} ${unplanned.length === 1 ? "is" : "are"} not in the wave's plan`);
409
+ const want = new Set(units);
410
+ const groups: TerragruntUnitGroup[] = run.artifact.groups ?? [{ units: run.artifact.units, workDir: run.artifact.workDir, ...(input.terragrunt ? { terragrunt: input.terragrunt } : {}), ...(input.binary ? { binary: input.binary } : {}) }];
411
+ const grouped = new Set(groups.flatMap((g) => g.units));
412
+ const ungrouped = units.filter((u) => !grouped.has(u));
413
+ if (ungrouped.length > 0) throw new Error(`terragrunt-apply: ${ungrouped.join(", ")} ${ungrouped.length === 1 ? "is" : "are"} in no group of the wave's plan`);
414
+ const applied: { results: Awaited<ReturnType<typeof applyUnits>>["results"]; code: number | null } = { results: [], code: 0 };
415
+ // Each group applies its own saved plans with its own releases.
416
+ for (const g of groups) {
417
+ const mine = g.units.filter((u) => want.has(u));
418
+ if (mine.length === 0) continue;
419
+ const { terragrunt: _tg, binary: _bin, ...rest } = input;
420
+ const a = await applyUnits(exec, { ...rest, ...(g.terragrunt ? { terragrunt: g.terragrunt } : {}), ...(g.binary ? { binary: g.binary } : {}) }, mine, g.workDir, env);
421
+ applied.results.push(...a.results);
422
+ if (applied.code === 0) applied.code = a.code;
423
+ }
424
+ const byUnit = new Map(applied.results.map((r) => [r.unit, r]));
425
+ const out: Record<string, GroupMemberOutcome> = {};
426
+ for (const m of members) {
427
+ const unit = m.input?.unit ?? (m.step.unit as string);
428
+ const r = byUnit.get(unit);
429
+ out[m.component] = r?.status === "succeeded" ? { status: "applied" } : { status: "failed", error: r?.error ?? "Terragrunt did not apply it" };
430
+ }
431
+ return { members: out, ...(applied.code !== 0 && applied.results.every((r) => r.status === "succeeded") ? { error: `terragrunt exited ${applied.code}` } : {}) };
432
+ },
433
+ };
434
+ }
435
+
436
+ /** `terragrunt-apply` with Terragrunt on PATH. */
437
+ export const terragruntApply: Capability<TerragruntApplyStepInput, TerragruntApplyStepOutput> = terragruntApplyCapability();
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * Terragrunt units as roots (#3414). `./units`, `./wave` and `./mocks` are pure and
3
3
  * bundle without TypeScript; `./run` spawns `terragrunt`. `./affected` picks
4
- * the units a git range touches (#3415).
4
+ * the units a git range touches (#3415). `./capability` is `terragrunt-apply`,
5
+ * the units as an op wave's step (#4842).
5
6
  */
6
7
 
7
8
  export * from "./units";
@@ -9,3 +10,4 @@ export * from "./wave";
9
10
  export * from "./mocks";
10
11
  export * from "./run";
11
12
  export * from "./affected";
13
+ export * from "./capability";
@@ -205,6 +205,31 @@ export function terragruntWaves(units: readonly TerragruntUnit[], options: Terra
205
205
  return [...layer(nodes.filter((n) => canaries.has(n.name))), ...layer(nodes.filter((n) => !canaries.has(n.name)))];
206
206
  }
207
207
 
208
+ /**
209
+ * The waves a pipeline lists (#4842), cut again by the graph discovery gives
210
+ * now: each listed wave split into its own dependency layers, the listed
211
+ * order kept, so canary waves listed first stay first. A pipeline written
212
+ * with the graph comes back as it is. A unit that depends on a unit of a
213
+ * later listed wave is refused, since the list is stale; units the pipeline
214
+ * does not list stay out. Empty layers are dropped.
215
+ */
216
+ export function terragruntListedWaves(listed: readonly (readonly string[])[], units: readonly TerragruntUnit[]): string[][] {
217
+ const deps = new Map(units.map((u) => [u.path, u.dependencies]));
218
+ const waveOf = new Map<string, number>();
219
+ listed.forEach((w, i) => w.forEach((u) => waveOf.set(u, i)));
220
+ const out: string[][] = [];
221
+ listed.forEach((wave, i) => {
222
+ const members = new Set(wave);
223
+ for (const u of wave) {
224
+ const later = (deps.get(u) ?? []).filter((d) => (waveOf.get(d) ?? -1) > i);
225
+ if (later.length > 0) throw new TerragruntWaveError(`${u} depends on ${later.join(", ")}, which the pipeline applies in a later wave; cut the waves again`);
226
+ }
227
+ const sub = wave.map((path) => ({ path, dependencies: (deps.get(path) ?? []).filter((d) => members.has(d)) }));
228
+ out.push(...terragruntWaves(sub).filter((w) => w.length > 0));
229
+ });
230
+ return out;
231
+ }
232
+
208
233
  /**
209
234
  * Every unit that depends on one of `changed`, directly or through other
210
235
  * units, not counting `changed` itself. Sorted by path.