@intentius/terragucci 0.4.4 → 0.4.5

package/README.md

@@ -1,13 +1,13 @@
 # @intentius/terragucci
 
-The whole Terraform and Terragrunt lifecycle, handled. terragucci writes your repo's pipeline for GitHub, GitLab or Forgejo. Most repos need no config file at all.
+terragucci writes the pipeline that runs the whole lifecycle of your Terraform or Terragrunt repo on GitHub, GitLab or Forgejo.
 
 ```bash
 npm i -D @intentius/terragucci
 npx terragucci init
 ```
 
-`init` reads the repo to decide what the pipeline needs, then writes it and reports what it found:
+`init` reads the repo and writes the pipeline it needs, then reports what it found:
 
 ```
 found 15 roots in 2 layers, tofu 1.13.1 (.opentofu-version), forge github (the origin remote (github.com))

package/dist/audit.schema.json

@@ -2,17 +2,17 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/terragucci/schemas/audit/v1/audit.schema.json",
   "title": "terragucci.audit/v1",
-  "description": "One line of audit.jsonl at the top of a reports prefix: an approval, apply, policy override, refused wave or state migration. Within v1 fields are only added, and an existing field never changes meaning.",
+  "description": "One line of audit.jsonl at the top of a reports prefix: an approval, apply, policy override, refused wave, state migration or state export. Within v1 fields are only added, and an existing field never changes meaning.",
   "type": "object",
   "required": ["schema", "id", "kind", "project", "at", "who", "what", "digest", "result", "evidence"],
   "properties": {
     "schema": { "const": "terragucci.audit/v1" },
     "id": { "type": "string", "description": "sha256: over where the entry came from; the same records give the same id." },
-    "kind": { "enum": ["approval-requested", "approval", "approval-revoked", "override-requested", "override", "override-revoked", "apply", "refused", "migration", "unlock"] },
+    "kind": { "enum": ["approval-requested", "approval", "approval-revoked", "override-requested", "override", "override-revoked", "apply", "refused", "migration", "unlock", "state-export", "ephemeral-apply", "ephemeral-destroy"] },
     "project": { "type": "string", "description": "<host>/<path> of the repo." },
     "at": { "type": "string", "description": "When it happened, ISO 8601." },
     "who": { "type": ["string", "null"], "description": "The approver, the overrider, whoever removed the line, or for an apply the approver it applied under. Null when nobody did." },
-    "what": { "type": "string", "description": "The gate (wave-<k>, or a migration's name) or, for an override, the root." },
+    "what": { "type": "string", "description": "The gate (wave-<k>, or a migration's name) or, for an override or a state export, the root." },
     "digest": { "type": ["string", "null"], "description": "The wave's set digest, or the digest an override binds. Null when a root failed to plan." },
     "result": { "type": "string" },
     "evidence": {

package/dist/estate.schema.json

@@ -19,7 +19,8 @@
         "failed_roots": { "type": "integer" },
         "unreadable": { "type": "integer", "description": "Projects whose index could not be read." },
         "overridden_roots": { "type": "integer", "description": "Roots the newest apply waves applied under a policy override. Absent when none." },
-        "resources": { "type": "integer", "description": "Resources across every project's inventory. Absent when no project has one." }
+        "resources": { "type": "integer", "description": "Resources across every project's inventory. Absent when no project has one." },
+        "ephemeral": { "type": "integer", "description": "Live ephemeral environments across every project. Absent when none is live." }
       }
     },
     "projects": { "type": "array", "items": { "$ref": "#/$defs/project" } },
@@ -169,6 +170,7 @@
         "overridden": { "type": "integer", "description": "Roots the newest commit's apply waves applied under a policy override. Absent when none." },
         "inventory": { "$ref": "#/$defs/inventory", "description": "The resources its roots hold, from its inventory.json. Absent until an apply records them." },
         "states": { "type": "array", "description": "Each root's state versions, from its states.json. Absent until an apply records them.", "items": { "$ref": "#/$defs/stateRoot" } },
+        "edges": { "type": "array", "description": "Each cross-state edge, from its edges.json: a consumer root, the producer root whose state it reads, the consumer's last plan and the producer's last apply that changed it. Absent until a run records an edge.", "items": { "$ref": "#/$defs/edge" } },
         "run_view": {
           "type": "object",
           "description": "The run view of the project's newest applied commit, which the dependency graph read: its commit, when a wave last wrote it, and its run.html when the page can link it. Absent until a wave writes one.",
@@ -178,9 +180,70 @@
             "updated": { "type": "string" },
             "page": { "type": "string" }
           }
+        },
+        "applying": {
+          "type": "array",
+          "description": "The waves of that run view still applying whose resources are followed (a choudoufu wave): how many are done, in flight and waiting at the last read of the records.",
+          "items": {
+            "type": "object",
+            "required": ["wave", "read", "total", "done", "in_flight", "waiting"],
+            "properties": {
+              "wave": { "type": "integer" },
+              "read": { "type": "string" },
+              "total": { "type": "integer" },
+              "done": { "type": "integer" },
+              "in_flight": { "type": "integer" },
+              "waiting": { "type": "integer" }
+            }
+          }
+        },
+        "ephemeral": {
+          "type": "array",
+          "description": "The live ephemeral environments, from its ephemeral.json: each pull request's copy of the ephemeral roots, their state keys, and when it expires. Absent when none is live.",
+          "items": {
+            "type": "object",
+            "required": ["pull_request", "suffix", "roots", "commit", "applied", "expires", "status"],
+            "properties": {
+              "pull_request": { "type": "integer" },
+              "pull_request_url": { "type": "string" },
+              "suffix": { "type": "string", "description": "What the copy's state keys end in: pr-<n>." },
+              "roots": { "type": "array", "items": { "type": "object", "required": ["root", "location"], "properties": { "root": { "type": "string" }, "location": { "type": "string" } } } },
+              "commit": { "type": "string", "description": "The head the copy last applied from." },
+              "applied": { "type": "string" },
+              "expires": { "type": "string" },
+              "approved_by": { "type": "string" },
+              "status": { "enum": ["live", "destroy-failed"] }
+            }
+          }
         }
       }
     },
+    "edgeRun": {
+      "type": "object",
+      "required": ["stage", "commit", "finished"],
+      "properties": {
+        "stage": { "type": "string" },
+        "commit": { "type": "string" },
+        "finished": { "type": "string" },
+        "wave": { "type": "integer" },
+        "pull_request": { "type": "string" },
+        "version_id": { "type": "string" },
+        "report": { "type": "string", "description": "The run's report.html, when the page can link it." }
+      }
+    },
+    "edge": {
+      "type": "object",
+      "description": "One root reading another's state. stale: the producer applied a change after the consumer's last plan; current: the consumer's last plan is newer than that apply; unknown: either run is not recorded.",
+      "required": ["consumer", "producer", "via", "status"],
+      "properties": {
+        "consumer": { "type": "string" },
+        "producer": { "type": "string" },
+        "via": { "enum": ["terraform_remote_state", "dependency"] },
+        "consumer_planned": { "$ref": "#/$defs/edgeRun" },
+        "producer_applied": { "$ref": "#/$defs/edgeRun" },
+        "status": { "enum": ["current", "stale", "unknown"] }
+      }
+    },
     "stateRoot": {
       "type": "object",
       "description": "One root's state: where it is, whether its backend keeps versions, and the version ids its applies left, newest first. Never the state's contents.",

package/dist/report.schema.json

@@ -78,7 +78,16 @@
             "properties": {
               "name": { "type": "string" },
               "version": { "type": "string" },
-              "pin": { "type": "string" }
+              "pin": { "type": "string" },
+              "terragrunt": {
+                "description": "A Terragrunt unit: the Terragrunt release that ran it, and terragrunt_version_constraint when the unit pinned it (minor 24).",
+                "type": "object",
+                "required": ["version"],
+                "properties": {
+                  "version": { "type": "string" },
+                  "pin": { "type": "string" }
+                }
+              }
             }
           },
           "terragrunt": {
@@ -87,6 +96,7 @@
             "required": ["stack", "selection", "provisional", "run_result"],
             "properties": {
               "stack": { "type": "string" },
+              "stack_file": { "description": "The terragrunt.stack.hcl that generates the unit, when an explicit stack does (minor 29).", "type": "string" },
               "selection": { "type": "string" },
               "provisional": { "type": "boolean" },
               "run_result": { "type": "string" }
@@ -201,6 +211,11 @@
               }
             }
           },
+          "dependencies": {
+            "description": "A Terragrunt unit's dependency and dependencies blocks: the units whose outputs it reads, as plain paths in its terragrunt.hcl (minor 23). For a plain root, the roots waves.after puts before it. Absent when it names none.",
+            "type": "array",
+            "items": { "type": "string" }
+          },
           "state": {
             "description": "On a tf-apply wave, a root that applied or had nothing to apply: the state version its backend holds afterwards, read from the object's metadata, never its contents (minor 20).",
             "type": "object",
@@ -242,7 +257,20 @@
                 "why": { "type": "string" }
               }
             }
-          }
+          },
+          "unknown_reads": {
+            "description": "Its terraform_remote_state blocks whose state the code does not address, an expression or a value the backend takes from the environment: no edge orders the root after the root that writes that state, so the edge is unknown (minor 30).",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["data", "why"],
+              "properties": {
+                "data": { "type": "string", "description": "The block's label." },
+                "why": { "type": "string" }
+              }
+            }
+          },
+          "unaddressed": { "type": "string", "description": "Why the code does not address the root's own state, when a root of the run reads state through terraform_remote_state: a reader of it is not ordered after it (minor 30)." }
         }
       }
     },
@@ -305,7 +333,26 @@
           },
           "state": { "enum": ["planned", "waiting", "applying", "applied", "refused", "failed"], "description": "Where the wave stands (minor 21): a tf-plan wave is planned; a tf-apply wave waiting, applying, applied, refused or failed." },
           "reads": { "type": "array", "items": { "type": "integer" }, "description": "The waves whose roots' state its roots read (minor 21)." },
-          "replans_after": { "type": "array", "items": { "type": "integer" }, "description": "A tf-plan wave whose plans read outputs known only once these waves apply: it plans again after they apply and waits for an approval of that plan; its review digest is null (minor 21)." }
+          "replans_after": { "type": "array", "items": { "type": "integer" }, "description": "A tf-plan wave whose plans read outputs known only once these waves apply: it plans again after they apply and waits for an approval of that plan; its review digest is null (minor 21)." },
+          "preview": {
+            "type": "object",
+            "required": ["pull_request", "units"],
+            "description": "A tf-apply wave of Terragrunt units: its plans against the preview of them the merged pull request's plan note showed (minor 25).",
+            "properties": {
+              "pull_request": { "type": "integer" },
+              "units": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["unit"],
+                  "properties": {
+                    "unit": { "type": "string" },
+                    "differences": { "type": "array", "items": { "type": "string" }, "description": "How its plan differs from the preview. Absent when it plans as previewed." }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -354,7 +401,7 @@
       }
     },
     "blast": {
-      "description": "A tf-plan run's blast radius (minor 22): the roots whose plan changes a resource or an output, and every root of the repo that reads their state through terraform_remote_state, followed through, nearest first. Absent when no root's plan changes anything, on a Terragrunt repo, and on other stages.",
+      "description": "A tf-plan run's blast radius (minor 22): the roots whose plan changes a resource or an output, and every root of the repo that reads their state through terraform_remote_state (in a Terragrunt repo, every unit that depends on them through a dependency or dependencies block), followed through, nearest first. Absent when no root's plan changes anything, and on other stages.",
       "type": "object",
       "required": ["roots", "downstream"],
       "properties": {
@@ -372,6 +419,36 @@
               "planned": { "type": "boolean", "description": "Whether this run planned it." }
             }
           }
+        },
+        "resources": {
+          "description": "The radius by resource (minor 31), when a root is downstream: each resource a plan changes and the resources that depend on it, from the plans' references and the outputs each root reads, nearest first. A changed resource that nothing depends on is left out. Absent in a Terragrunt repo.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["root", "address", "actions", "reaches"],
+            "properties": {
+              "root": { "type": "string" },
+              "address": { "type": "string", "description": "The changed resource instance's address." },
+              "actions": { "type": "array", "items": { "type": "string" } },
+              "reaches": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["root", "address"],
+                  "properties": {
+                    "root": { "type": "string" },
+                    "address": { "type": "string", "description": "Its address in the root's configuration, with no instance key." },
+                    "through": {
+                      "type": "object",
+                      "required": ["root", "output"],
+                      "description": "In another root: the output it reads, and the root that makes it.",
+                      "properties": { "root": { "type": "string" }, "output": { "type": "string" } }
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },

package/dist/run.schema.json

@@ -30,10 +30,10 @@
           "root": { "type": "string" },
           "wave": { "type": "integer" },
           "reads": { "type": "array", "items": { "type": "string" } },
-          "state": { "$ref": "#/$defs/state", "description": "The state its backend block names, which a root of another project may read." },
+          "state": { "$ref": "#/$defs/state", "description": "The state its backend block names, which a root of another project may read. Under choudoufu, the records of the estate its live block owns: tofu-records/<estate>, with no bucket." },
           "external": {
             "type": "array",
-            "description": "Its terraform_remote_state reads of a state no root of the project holds: the block's label and the state it names. The estate page matches them to other projects' roots.",
+            "description": "Its terraform_remote_state reads of a state no root of the project holds: the block's label and the state it names. Under choudoufu, its terraform_estate_outputs reads of an estate no root of the project owns, as that estate's records. The estate page matches them to other projects' roots.",
             "items": {
               "type": "object",
               "required": ["data", "key"],
@@ -80,6 +80,28 @@
               }
             }
           },
+          "progress": {
+            "type": "object",
+            "description": "A choudoufu wave's resources while it applies and once it ended: each change its plans make, done, in flight, waiting or not applied, as its estates' records stood at the last read.",
+            "required": ["read", "resources"],
+            "properties": {
+              "read": { "type": "string", "description": "When the records were last read." },
+              "resources": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["root", "address", "action", "status"],
+                  "properties": {
+                    "root": { "type": "string" },
+                    "address": { "type": "string" },
+                    "action": { "enum": ["create", "update", "replace", "delete", "forget"] },
+                    "status": { "enum": ["done", "in-flight", "waiting", "not-applied"] },
+                    "done_at": { "type": "string", "description": "When a read first found it done." }
+                  }
+                }
+              }
+            }
+          },
           "updated": { "type": "string" }
         }
       }

package/dist/state-edges.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/state-edges/v1/state-edges.schema.json",
+  "title": "terragucci.state-edges/v1",
+  "description": "edges.json in a project's directory of a reports prefix: for each root, the roots whose state it reads, the newest run that planned it and the newest tf-apply wave that changed it. Root paths and run facts, never a state's contents or an output's value. Within v1 fields are only added, and an existing field never changes meaning.",
+  "type": "object",
+  "required": ["schema", "roots"],
+  "$defs": {
+    "run": {
+      "type": "object",
+      "required": ["stage", "commit", "finished", "path"],
+      "properties": {
+        "stage": { "type": "string", "description": "tf-plan, tf-drift or tf-apply." },
+        "commit": { "type": "string" },
+        "finished": { "type": "string" },
+        "wave": { "type": "integer" },
+        "path": { "type": "string", "description": "The run's directory, relative to the project's index.json." },
+        "pull_request": { "type": "string", "description": "The pull or merge request a plan was for." },
+        "version_id": { "type": "string", "description": "An apply: the state version it left, when the backend keeps versions." }
+      }
+    }
+  },
+  "properties": {
+    "schema": { "const": "terragucci.state-edges/v1" },
+    "roots": {
+      "type": "array",
+      "description": "By root path.",
+      "items": {
+        "type": "object",
+        "required": ["root", "reads"],
+        "properties": {
+          "root": { "type": "string" },
+          "reads": {
+            "type": "array",
+            "description": "The roots whose state it reads, as the newest default-branch run found them in its code.",
+            "items": {
+              "type": "object",
+              "required": ["root", "via"],
+              "properties": {
+                "root": { "type": "string" },
+                "via": { "enum": ["terraform_remote_state", "dependency"] }
+              }
+            }
+          },
+          "reads_seen": { "type": "string", "description": "When the run that found its reads finished." },
+          "planned": { "$ref": "#/$defs/run", "description": "The newest run that planned it: a pull request's plan, a drift check or an apply wave's plan." },
+          "applied": { "$ref": "#/$defs/run", "description": "The newest tf-apply wave that changed one of its resources." }
+        }
+      }
+    }
+  }
+}

package/dist/state-versions.schema.json

@@ -16,7 +16,7 @@
         "properties": {
           "root": { "type": "string" },
           "backend": { "type": "string", "description": "The backend the root initialised: s3, local, gcs and so on." },
-          "location": { "type": "string", "description": "s3://<bucket>/<key>, or the local file's path in the root." },
+          "location": { "type": "string", "description": "s3://<bucket>/<key>, gs://<bucket>/<key>, az://<account>/<container>/<key>, or the local file's path in the root." },
           "versioning": { "enum": ["on", "off", "unknown"], "description": "As the newest apply found it." },
           "note": { "type": "string", "description": "Why the version could not be read, or what off means for this backend." },
           "checked": { "type": "string", "description": "When the newest apply that recorded the root finished." },