@intentius/terragucci 0.4.2 → 0.4.4

package/dist/report-index.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/report-index/v1/report-index.schema.json",
+  "title": "terragucci.report-index/v1",
+  "description": "A reports bucket's index.json: one row per run, newest first. Within v1 fields are only added, and an existing field never changes meaning.",
+  "type": "object",
+  "required": ["schema", "reports"],
+  "properties": {
+    "schema": { "const": "terragucci.report-index/v1" },
+    "reports": {
+      "type": "array",
+      "description": "Newest first: up to 500 rows, then the newest row of each project, stage and wave beyond them.",
+      "items": { "$ref": "#/$defs/row" }
+    }
+  },
+  "$defs": {
+    "totals": {
+      "type": "object",
+      "required": ["create", "update", "replace", "delete"],
+      "properties": {
+        "create": { "type": "integer" },
+        "update": { "type": "integer" },
+        "replace": { "type": "integer" },
+        "delete": { "type": "integer" }
+      }
+    },
+    "row": {
+      "type": "object",
+      "required": ["project", "commit", "stage", "finished", "path", "roots", "groups", "totals", "refused", "destroys"],
+      "properties": {
+        "project": { "type": "string", "description": "<host>/<path> of the repo." },
+        "commit": { "type": "string" },
+        "stage": { "enum": ["tf-plan", "tf-apply", "tf-drift"] },
+        "wave": { "type": "integer", "description": "The wave of a tf-apply run." },
+        "share": { "type": "integer", "description": "The share of a tf-apply wave split across jobs." },
+        "finished": { "type": "string", "description": "When the run finished, ISO 8601." },
+        "path": { "type": "string", "description": "The run's directory, relative to this index: <yyyy>/<mm>/<commit>/<stage>[-wave-N[-share-S]] in a project's index, prefixed with the project in the top index." },
+        "roots": { "type": "integer" },
+        "groups": { "type": "integer" },
+        "totals": { "$ref": "#/$defs/totals" },
+        "refused": { "type": "integer", "description": "Roots that refused to plan." },
+        "failed": { "type": "integer", "description": "Roots that failed to plan or apply. Absent on rows written before it was kept." },
+        "changed": { "type": "integer", "description": "Roots with at least one change; on a tf-drift row, the roots that drifted." },
+        "approval": { "enum": ["waiting", "approved", "not-required"], "description": "A tf-apply wave's gate." },
+        "waiting_since": { "type": "string", "description": "When a waiting wave began waiting for an approval of its digest." },
+        "applied": { "type": "string", "description": "When a tf-apply wave finished applying." },
+        "overridden": { "type": "integer", "description": "Roots the policy denied that a recorded override let through. Absent when none." },
+        "wave_digests": { "type": "array", "items": { "type": "string" }, "description": "A tf-plan row: each wave's set digest and review digest, the digests an apply of the same plans binds. Absent when no wave has one." },
+        "drifted_roots": { "type": "array", "items": { "type": "string" }, "description": "A tf-drift row: the roots that drifted, at most 50. Absent when none drifted." },
+        "drift_since": { "type": "string", "description": "A tf-drift row that found drift: when the project's open drift was first found, by this run or an earlier one." },
+        "drift_cleared": {
+          "type": "object",
+          "description": "A tf-drift row that found none after a row that found some: when that drift was first found, and its roots.",
+          "required": ["since", "roots"],
+          "properties": { "since": { "type": "string" }, "roots": { "type": "array", "items": { "type": "string" } } }
+        },
+        "destroys": { "type": "array", "items": { "type": "string" }, "description": "Destroys and replacements as `<root>: <address>`, at most 50." },
+        "destroys_total": { "type": "integer", "description": "How many destroys and replacements there are, when there are more than the row lists." },
+        "commit_url": { "type": "string" },
+        "pull_request": { "type": "string" },
+        "pull_request_url": { "type": "string" },
+        "job_url": { "type": "string" },
+        "trace_url": { "type": "string" }
+      }
+    }
+  }
+}

package/dist/report.schema.json

@@ -17,6 +17,7 @@
         "base": { "type": "string" },
         "stage": { "enum": ["tf-plan", "tf-apply", "tf-drift"] },
         "wave": { "type": "integer" },
+        "share": { "type": "integer", "minimum": 1, "description": "On a tf-apply wave split across jobs (waves.jobs), the share this report applied; waves[0].roots are its roots (minor 20)." },
         "binary": { "type": "string" },
         "runtime": { "type": "string" },
         "started": { "type": "string" },
@@ -70,6 +71,16 @@
         "required": ["path", "status", "plan_digest", "counts", "plan", "changes", "highlights", "fold", "why"],
         "properties": {
           "path": { "type": "string" },
+          "binary": {
+            "description": "The binary the root ran, its version, and where the root pinned that version when it did (minor 18).",
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string" },
+              "version": { "type": "string" },
+              "pin": { "type": "string" }
+            }
+          },
           "terragrunt": {
             "description": "Set when the root is a Terragrunt unit (minor 1).",
             "type": "object",
@@ -169,6 +180,68 @@
                 }
               }
             }
+          },
+          "resources": {
+            "description": "On a tf-apply wave, a root that applied or had nothing to apply: every managed resource it holds afterwards, from the plan's planned values. Never a value (minor 14).",
+            "type": "array",
+            "items": { "$ref": "#/$defs/resource" }
+          },
+          "applied_changes": {
+            "description": "On a tf-apply wave, a root that applied: what the apply did to each resource, and the top-level attributes an update or a replacement changed, by name. Never a value (minor 15).",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["address", "type", "actions", "attributes"],
+              "properties": {
+                "address": { "type": "string" },
+                "type": { "type": "string" },
+                "actions": { "type": "array", "items": { "enum": ["create", "update", "replace", "delete", "import", "move", "forget"] } },
+                "attributes": { "type": "array", "items": { "type": "string" } },
+                "previous_address": { "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",
+            "required": ["backend", "versioning"],
+            "properties": {
+              "backend": { "type": "string" },
+              "location": { "type": "string" },
+              "version_id": { "type": "string" },
+              "versioning": { "enum": ["on", "off", "unknown"] },
+              "note": { "type": "string" }
+            }
+          },
+          "steps": {
+            "description": "The steps that ran for the root, in the order they ran (minor 17). failed: the root failed; approval: an on_failure: approve step failed, so the root's wave waits for an approval.",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name", "when", "status", "exit", "seconds"],
+              "properties": {
+                "name": { "type": "string" },
+                "when": { "enum": ["before-init", "after-init", "before-plan", "after-plan", "before-apply", "after-apply", "before-drift", "after-drift"] },
+                "status": { "enum": ["passed", "failed", "approval"] },
+                "exit": { "type": ["integer", "null"] },
+                "seconds": { "type": "number" }
+              }
+            }
+          },
+          "reads": {
+            "description": "The roots whose state the root reads through terraform_remote_state, and which outputs it planned on: planned, the upstream's plan in this run, with the outputs known only once it applies under unknown; applied, its state as it stands (minor 21).",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["upstream", "data", "outputs"],
+              "properties": {
+                "upstream": { "type": "string" },
+                "data": { "type": "string" },
+                "outputs": { "enum": ["planned", "applied"] },
+                "unknown": { "type": "array", "items": { "type": "string" } },
+                "why": { "type": "string" }
+              }
+            }
           }
         }
       }
@@ -201,7 +274,38 @@
               "by": { "type": "string" },
               "roots": { "type": "array", "items": { "type": "string" } }
             }
-          }
+          },
+          "review": {
+            "type": "object",
+            "description": "A waiting tf-apply wave under approval: pr-review: the pull request whose approving review of its head would approve the wave, and the page to review it on (minor 13).",
+            "required": ["pull_request", "url"],
+            "properties": {
+              "pull_request": { "type": "integer" },
+              "url": { "type": "string" }
+            }
+          },
+          "held_by_steps": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "The roots whose on_failure: approve step failed: the gate holds the wave whatever the gate policy says, when it changes anything (minor 17)."
+          },
+          "cost": {
+            "type": "object",
+            "description": "The wave's monthly cost, when cost is on (minor 19): the sums over its roots estimated, and with cost.approve_above at base whether the change is over it, so the wave waits for an approval whatever the gate.",
+            "required": ["currency", "monthly_delta", "monthly_total", "past_monthly_total"],
+            "properties": {
+              "currency": { "type": "string" },
+              "monthly_delta": { "type": ["number", "null"] },
+              "monthly_total": { "type": ["number", "null"] },
+              "past_monthly_total": { "type": ["number", "null"] },
+              "unestimated": { "type": "array", "items": { "type": "string" } },
+              "approve_above": { "type": "number" },
+              "over": { "type": "boolean" }
+            }
+          },
+          "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)." }
         }
       }
     },
@@ -249,8 +353,30 @@
         "overriders": { "type": "array", "items": { "type": "string" }, "description": "Who may override a denial, from policy.override at base (minor 10)." }
       }
     },
+    "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.",
+      "type": "object",
+      "required": ["roots", "downstream"],
+      "properties": {
+        "roots": { "type": "array", "items": { "type": "string" } },
+        "downstream": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["root", "reads", "depth", "planned"],
+            "properties": {
+              "root": { "type": "string" },
+              "reads": { "type": "array", "items": { "type": "string" }, "description": "The roots in the radius whose state it reads." },
+              "depth": { "type": "integer", "minimum": 1, "description": "1 when it reads a changed root's state itself, 2 when it reads such a reader's, and so on." },
+              "wave": { "type": "integer", "description": "The apply wave it is in." },
+              "planned": { "type": "boolean", "description": "Whether this run planned it." }
+            }
+          }
+        }
+      }
+    },
     "cost": {
-      "description": "The cost estimate of a tf-plan run, when cost is on (minor 12): each root's monthly cost from the estimator, and the sums over the roots estimated.",
+      "description": "The cost estimate of a tf-plan run, or of a tf-apply wave's plans (minor 19), when cost is on (minor 12): each root's monthly cost from the estimator, and the sums over the roots estimated.",
       "type": "object",
       "required": ["estimator", "currency", "monthly_delta", "monthly_total", "past_monthly_total", "roots"],
       "properties": {
@@ -379,6 +505,15 @@
     }
   },
   "$defs": {
+    "resource": {
+      "type": "object",
+      "required": ["address", "type", "provider"],
+      "properties": {
+        "address": { "type": "string" },
+        "type": { "type": "string" },
+        "provider": { "type": "string", "description": "The provider's source address, such as registry.opentofu.org/hashicorp/aws." }
+      }
+    },
     "timingDetail": { "enum": ["resources", "aggregate", "none"] },
     "timingSource": { "description": "binary: terragucci timed each run of the binary; terragrunt: from Terragrunt's run report (minor 3).", "enum": ["binary", "terragrunt"] },
     "rootTimings": {

package/dist/run.schema.json

@@ -0,0 +1,88 @@
+{
+  "$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." },
+          "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.",
+            "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." }
+              }
+            }
+          },
+          "updated": { "type": "string" }
+        }
+      }
+    }
+  }
+}

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>, 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." }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}