@intentius/chant-lexicon-terraform 0.102.0 → 0.104.0

package/dist/terragrunt/wave.d.ts

@@ -0,0 +1,89 @@
+/**
+ * One wave of Terragrunt units as one `terragrunt run --all` (#3414): the
+ * arguments, the environment, the run report and the change-set parts.
+ *
+ * A wave names its units with explicit path filters, so it plans and applies
+ * exactly those units. `.terragrunt-filters` is not read by a wave run:
+ * Terragrunt unions its filters with the ones given on the command line
+ * (observed on 1.1.6), so a filters file selecting `live/prod/**` would pull
+ * every prod unit into every wave. Discovery reads it; the wave's paths came
+ * from discovery.
+ *
+ * Plan writes `<outDir>/<unit>/tfplan.tfplan` and
+ * `<jsonOutDir>/<unit>/tfplan.json`; apply reads the saved plans from the
+ * same `outDir` with the same filters.
+ *
+ * Pure: nothing here spawns or reads files, so terragucci can bundle it. It
+ * imports `../change-set` and chant's `change-set` types only.
+ */
+import type { ChangeSetPart, ChangeSetPlanner } from "@intentius/chant/change-set";
+export type TerragruntWaveCommand = "plan" | "apply";
+export interface TerragruntWaveArgsInput {
+    /** The wave's units, by path relative to where Terragrunt runs. */
+    units: readonly string[];
+    command: TerragruntWaveCommand;
+    /** Where plan writes and apply reads the saved plan files. */
+    outDir: string;
+    /** Where plan writes each unit's `show -json`. Plan only. */
+    jsonOutDir?: string;
+    /** Where Terragrunt writes the run report (JSON). */
+    reportFile: string;
+    /** A destroy wave: plan runs `plan -destroy`, and both pass `--filter-allow-destroy`. */
+    destroy?: boolean;
+    /** `--parallelism`. Unset, Terragrunt runs every unit of the wave at once. */
+    parallelism?: number;
+    /** Arguments after `--`, beside the ones the command needs (`-lock-timeout=5m`). */
+    extra?: readonly string[];
+}
+/** Arguments to `terragrunt` for one wave. Throws on an empty wave: with no filter, `run --all` runs every unit. */
+export declare function terragruntWaveArgs(input: TerragruntWaveArgsInput): string[];
+/**
+ * The environment a wave adds: `TG_TF_PATH` when the project names a binary,
+ * nothing otherwise, so Terragrunt's own choice (tofu, then terraform, or a
+ * unit's `terraform_binary`) stands.
+ */
+export declare function terragruntEnv(binary: string | undefined): Record<string, string>;
+/** One row of a Terragrunt run report (`run/report` JSON). */
+export interface TerragruntReportRow {
+    name: string;
+    /** `succeeded`, `failed`, `early exit`, `excluded`, as Terragrunt writes them. */
+    result: string;
+    reason?: string;
+    cause?: string;
+    cmd?: string;
+    started?: string;
+    ended?: string;
+}
+/** The rows of a run report, keyed by unit path. Malformed rows are dropped. */
+export declare function parseTerragruntReport(text: string | unknown): Map<string, TerragruntReportRow>;
+/** How one unit of a wave ended. */
+export interface TerragruntUnitResult {
+    unit: string;
+    /** `succeeded` only when the run report says so; a unit missing from it did not run. */
+    status: "succeeded" | "failed";
+    /** The report's result, or `not run` when the unit is not in it. */
+    result: string;
+    /** Why it failed, from the report's reason and cause. */
+    error?: string;
+}
+/** Each of the wave's units against the run report. A unit the report leaves out failed: nothing says it ran. */
+export declare function terragruntUnitResults(units: readonly string[], report: Map<string, TerragruntReportRow>): TerragruntUnitResult[];
+export interface TerragruntWavePartsInput {
+    units: readonly string[];
+    report: Map<string, TerragruntReportRow>;
+    /** A unit's `tfplan.json`, parsed, or undefined when plan wrote none. */
+    planFor: (unit: string) => unknown;
+    /** The binary Terragrunt called. */
+    planner: ChangeSetPlanner;
+    /** The scope a unit's member carries. Default: its stack, {@link stackOfUnit}. */
+    scopeFor?: (unit: string) => string | undefined;
+}
+/**
+ * The change-set parts of a planned wave: one member per unit, named by the
+ * unit's path. A unit the run report marks succeeded, with a plan JSON, goes
+ * through {@link terraformChangeSetPart}; any other is a failed member
+ * carrying the report's result, so a unit that never planned cannot read as
+ * planned with nothing to do.
+ */
+export declare function terragruntWaveParts(input: TerragruntWavePartsInput): ChangeSetPart[];
+//# sourceMappingURL=wave.d.ts.map

package/dist/terragrunt/wave.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wave.d.ts","sourceRoot":"","sources":["../../src/terragrunt/wave.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAInF,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,oHAAoH;AACpH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,EAAE,CA4B3E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEhF;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAoB9F;AAED,oCAAoC;AACpC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iHAAiH;AACjH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,oBAAoB,EAAE,CAQhI;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACzC,yEAAyE;IACzE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,oCAAoC;IACpC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACjD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,aAAa,EAAE,CAsBpF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-terraform",
-  "version": "0.102.0",
+  "version": "0.104.0",
   "type": "module",
   "files": [
     "src/",
@@ -29,6 +29,16 @@
       "types": "./dist/op/activity-contracts.d.ts",
       "default": "./src/op/activity-contracts.ts"
     },
+    "./pin": {
+      "development": "./src/pin/index.ts",
+      "types": "./dist/pin/index.d.ts",
+      "default": "./src/pin/index.ts"
+    },
+    "./terragrunt": {
+      "development": "./src/terragrunt/index.ts",
+      "types": "./dist/terragrunt/index.d.ts",
+      "default": "./src/terragrunt/index.ts"
+    },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
@@ -57,7 +67,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.102.0",
+    "@intentius/chant": "^0.104.0",
     "typescript": "^5.9.3",
     "zod": "^4.3.6"
   },

package/src/__fixtures__/change-set/choudoufu-set-plan.change-set.golden.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json",
+  "contract": 1,
+  "digest": "jcs1-sha256:5724486f4166eb1db89bba1d5807aaf1dc592726af2ecaf47da782e8d246cafb",
+  "members": [
+    {
+      "member": "estates/e01",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "scope": "est-e01",
+      "status": "planned",
+      "planDigest": "jcs1-sha256:31049a9763b3c11a83416e1f5cde08b23d9ce14caff09ad6aa5770dab95dfaf1",
+      "nativeDigest": "sha256:bbe048fb0f7df99fcd65f00351d8b3c3be9b8a2a25a99a706b1c16d81277bb97",
+      "holes": []
+    },
+    {
+      "member": "estates/e02",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "scope": "est-e02",
+      "status": "planned",
+      "planDigest": "jcs1-sha256:5aaf171a0523f7ee14ee9b144c170ac7aea0820080d17708fcc6aa6d0467496b",
+      "nativeDigest": "sha256:be83b6c9faebeaf63391a7f45dafa02f87f58a01de31f9a0649b1898218b2127",
+      "holes": []
+    },
+    {
+      "member": "estates/e03",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "scope": "est-e03",
+      "status": "failed",
+      "error": "e03 broke at init on purpose",
+      "planDigest": null,
+      "nativeDigest": "sha256:b1f431ac6f4c9c24d0744f4cecb7581149918ece30e4ad22f4c3982c62c90874",
+      "holes": []
+    }
+  ],
+  "entries": [
+    {
+      "member": "estates/e01",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "address": "terraform_data.x",
+      "type": "terraform_data",
+      "name": "x",
+      "action": "create",
+      "scope": "est-e01",
+      "attributes": []
+    },
+    {
+      "member": "estates/e02",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "address": "terraform_data.x",
+      "type": "terraform_data",
+      "name": "x",
+      "action": "no-op",
+      "scope": "est-e02",
+      "attributes": []
+    }
+  ],
+  "summary": {
+    "members": 3,
+    "entries": 2,
+    "actions": {
+      "create": 1,
+      "update": 0,
+      "replace": 0,
+      "delete": 0,
+      "read": 0,
+      "no-op": 1,
+      "forget": 0
+    },
+    "types": {
+      "terraform_data": {
+        "create": 1,
+        "no-op": 1
+      }
+    },
+    "byMember": {
+      "estates/e01": {
+        "create": 1
+      },
+      "estates/e02": {
+        "no-op": 1
+      }
+    },
+    "deletes": [],
+    "replacements": [],
+    "failed": [
+      "estates/e03"
+    ],
+    "holes": 0
+  }
+}

package/src/__fixtures__/change-set/choudoufu-set-plan.json

@@ -0,0 +1,76 @@
+{
+  "format_version": "1",
+  "roots": [
+    {
+      "root": "estates/e01",
+      "estate": "est-e01",
+      "status": "planned",
+      "error": "",
+      "changes": true,
+      "plan_file": "out/estates/e01.tfplan",
+      "log_file": "out/estates/e01.log",
+      "duration_ms": 0,
+      "plan": {
+        "format_version": "1.2",
+        "resource_changes": [
+          {
+            "address": "terraform_data.x",
+            "change": {
+              "actions": [
+                "create"
+              ]
+            }
+          }
+        ]
+      },
+      "digest": "sha256:bbe048fb0f7df99fcd65f00351d8b3c3be9b8a2a25a99a706b1c16d81277bb97"
+    },
+    {
+      "root": "estates/e02",
+      "estate": "est-e02",
+      "status": "planned",
+      "error": "",
+      "changes": false,
+      "plan_file": "out/estates/e02.tfplan",
+      "log_file": "out/estates/e02.log",
+      "duration_ms": 0,
+      "plan": {
+        "format_version": "1.2",
+        "resource_changes": [
+          {
+            "address": "terraform_data.x",
+            "change": {
+              "actions": [
+                "no-op"
+              ]
+            }
+          }
+        ]
+      },
+      "digest": "sha256:be83b6c9faebeaf63391a7f45dafa02f87f58a01de31f9a0649b1898218b2127"
+    },
+    {
+      "root": "estates/e03",
+      "estate": "est-e03",
+      "status": "failed",
+      "error": "e03 broke at init on purpose",
+      "stage": "init",
+      "changes": false,
+      "plan_file": "",
+      "log_file": "out/estates/e03.log",
+      "duration_ms": 0,
+      "plan": null,
+      "digest": "sha256:b1f431ac6f4c9c24d0744f4cecb7581149918ece30e4ad22f4c3982c62c90874"
+    }
+  ],
+  "summary": {
+    "roots": 3,
+    "planned": 2,
+    "changed": 1,
+    "failed": 1
+  },
+  "digest": "sha256:2c4f5f352d4bef19ffcae056b5e40fff77042ec608ca19060bf8b2d5701e5222",
+  "exit_code": 4,
+  "plugin_cache_dir": "/shared/plugin-cache",
+  "parallel_estates": 2
+}

package/src/__fixtures__/change-set/choudoufu.part.golden.json

@@ -0,0 +1,173 @@
+{
+  "member": {
+    "member": "estate",
+    "lexicon": "terraform",
+    "planner": "choudoufu",
+    "status": "planned",
+    "planDigest": "jcs1-sha256:afd5c2a2f6754c832948f404ff9fb435ef3ffbb46de62a3e5f13970dcaaf4494",
+    "holes": []
+  },
+  "entries": [
+    {
+      "member": "estate",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "address": "terraform_data.config",
+      "type": "terraform_data",
+      "name": "config",
+      "action": "update",
+      "disruption": "in-place",
+      "attributes": [
+        {
+          "path": "input",
+          "before": {
+            "size": "small",
+            "tags": {
+              "team": "core"
+            }
+          },
+          "after": {
+            "size": "large",
+            "tags": {
+              "team": "core"
+            }
+          }
+        },
+        {
+          "path": "output",
+          "before": {
+            "size": "small",
+            "tags": {
+              "team": "core"
+            }
+          },
+          "unknown": true
+        }
+      ]
+    },
+    {
+      "member": "estate",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "address": "terraform_data.keep",
+      "type": "terraform_data",
+      "name": "keep",
+      "action": "no-op",
+      "attributes": []
+    },
+    {
+      "member": "estate",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "address": "terraform_data.old",
+      "type": "terraform_data",
+      "name": "old",
+      "action": "delete",
+      "disruption": "destroy",
+      "attributes": []
+    },
+    {
+      "member": "estate",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "address": "terraform_data.secret",
+      "type": "terraform_data",
+      "name": "secret",
+      "action": "update",
+      "disruption": "in-place",
+      "attributes": [
+        {
+          "path": "input",
+          "sensitive": true
+        },
+        {
+          "path": "output",
+          "before": "s3cr3t-1",
+          "unknown": true
+        }
+      ]
+    },
+    {
+      "member": "estate",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "address": "terraform_data.worker",
+      "type": "terraform_data",
+      "name": "worker",
+      "action": "replace",
+      "disruption": "destroy",
+      "attributes": [
+        {
+          "path": "id",
+          "before": "a3dad13f-ce42-3fd7-e1a5-ce79d5c3ae0e",
+          "unknown": true
+        },
+        {
+          "path": "output",
+          "before": "v1",
+          "unknown": true
+        },
+        {
+          "path": "triggers_replace",
+          "before": [
+            "build-1"
+          ],
+          "after": [
+            "build-2"
+          ],
+          "forcesReplacement": true
+        }
+      ]
+    },
+    {
+      "member": "estate",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "address": "module.app.terraform_data.instance[0]",
+      "type": "terraform_data",
+      "name": "instance",
+      "index": 0,
+      "module": "module.app",
+      "action": "create",
+      "attributes": [
+        {
+          "path": "id",
+          "unknown": true
+        },
+        {
+          "path": "input",
+          "after": "app-0"
+        },
+        {
+          "path": "output",
+          "unknown": true
+        }
+      ]
+    },
+    {
+      "member": "estate",
+      "lexicon": "terraform",
+      "planner": "choudoufu",
+      "address": "module.app.terraform_data.instance[1]",
+      "type": "terraform_data",
+      "name": "instance",
+      "index": 1,
+      "module": "module.app",
+      "action": "create",
+      "attributes": [
+        {
+          "path": "id",
+          "unknown": true
+        },
+        {
+          "path": "input",
+          "after": "app-1"
+        },
+        {
+          "path": "output",
+          "unknown": true
+        }
+      ]
+    }
+  ]
+}