@intentius/terragucci 0.4.3 → 0.4.5

package/dist/run.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/run/v1/run.schema.json",
+  "title": "terragucci.run/v1",
+  "description": "run.json under <prefix>/<project>/runs/<commit>/: the apply of one commit, every wave of it, the roots in each and the roots whose state each reads, and where each wave stands at its gate. Each tf-apply wave job rewrites its own row when it starts applying and when it ends. Within v1 fields are only added, and an existing field never changes meaning.",
+  "type": "object",
+  "required": ["schema", "project", "commit", "updated", "roots", "waves"],
+  "$defs": {
+    "state": {
+      "type": "object",
+      "required": ["key"],
+      "properties": {
+        "bucket": { "type": "string" },
+        "key": { "type": "string" }
+      }
+    }
+  },
+  "properties": {
+    "schema": { "const": "terragucci.run/v1" },
+    "project": { "type": "string" },
+    "commit": { "type": "string" },
+    "updated": { "type": "string", "description": "When a wave job last wrote it." },
+    "roots": {
+      "type": "array",
+      "description": "Each root, its wave, and the roots whose state it reads through terraform_remote_state. Empty for a Terragrunt repo.",
+      "items": {
+        "type": "object",
+        "required": ["root", "wave", "reads"],
+        "properties": {
+          "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. 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. 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"],
+              "properties": {
+                "data": { "type": "string" },
+                "bucket": { "type": "string" },
+                "key": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "waves": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["number", "roots", "reads", "state", "gate"],
+        "properties": {
+          "number": { "type": "integer" },
+          "roots": { "type": "array", "items": { "type": "string" } },
+          "reads": { "type": "array", "items": { "type": "integer" }, "description": "The waves whose roots' state its roots read." },
+          "state": { "enum": ["not-started", "planned", "waiting", "applying", "applied", "refused", "failed"] },
+          "gate": { "type": "string", "description": "Its gate on the ledger, wave-<n>." },
+          "policy": { "type": "string", "description": "The gate policy it ran under: always, on-destroy or never." },
+          "approval": { "enum": ["not-requested", "waiting", "approved", "not-required"] },
+          "digest": { "type": ["string", "null"], "description": "The set digest its gate decided on." },
+          "command": { "type": "string", "description": "The command that approves it, while it waits." },
+          "report": { "type": "string", "description": "Its report's directory, relative to the project's index.json." },
+          "shares": { "type": "integer", "description": "A wave split across jobs: how many share jobs apply it." },
+          "shares_applied": { "type": "array", "items": { "type": "integer" }, "description": "The shares that applied; the wave is applied once every share has." },
+          "changed": { "type": "array", "items": { "type": "string" }, "description": "The roots whose plan in this wave changes a resource or an output: where the run's blast radius starts." },
+          "spans": {
+            "type": "array",
+            "description": "The wave's time, oldest first: each plan, each wait at its gate (no end while it waits) and each apply (no end while it applies). At most 24.",
+            "items": {
+              "type": "object",
+              "required": ["phase", "start"],
+              "properties": {
+                "phase": { "enum": ["plan", "gate", "apply"] },
+                "start": { "type": "string" },
+                "end": { "type": "string" },
+                "share": { "type": "integer", "description": "The share of a wave split across jobs that planned or applied." }
+              }
+            }
+          },
+          "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

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/state-versions/v1/state-versions.schema.json",
+  "title": "terragucci.state-versions/v1",
+  "description": "states.json in a project's directory of a reports prefix: for each root, where its state is, whether its backend keeps versions, and the version ids its tf-apply waves left, newest first. Version ids, never a state's contents. Within v1 fields are only added, and an existing field never changes meaning.",
+  "type": "object",
+  "required": ["schema", "roots"],
+  "properties": {
+    "schema": { "const": "terragucci.state-versions/v1" },
+    "roots": {
+      "type": "array",
+      "description": "By root path.",
+      "items": {
+        "type": "object",
+        "required": ["root", "backend", "versioning", "checked", "versions"],
+        "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>, 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." },
+          "versions": {
+            "type": "array",
+            "description": "Newest first, at most 20.",
+            "items": {
+              "type": "object",
+              "required": ["version_id", "commit", "finished", "path"],
+              "properties": {
+                "version_id": { "type": "string" },
+                "commit": { "type": "string" },
+                "finished": { "type": "string", "description": "When the wave that recorded the version finished." },
+                "wave": { "type": "integer" },
+                "path": { "type": "string", "description": "The wave's run directory, relative to the project's index.json." }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}