@intentius/sql-yodeler 0.2.0 → 0.3.0

package/dist/waves/record.d.ts

@@ -0,0 +1,24 @@
+/** A wave's decision as the history records it (#87). Pure, for ../report/audit.ts. */
+/** The pipeline's name, and the op chant records the wave gates under. */
+export declare const WAVES_PIPELINE = "yodel-apply";
+/**
+ * What a wave's apply records of chant's decision, in each migration's
+ * `started` history row (`note.wave`): the gate and the set digest it was
+ * let through on, so `yodel report` finds the approval on the wave's gate
+ * (`<op>-wave-<k>`) and not the migrations Op's, and knows a wave whose
+ * policy at the base needed none.
+ */
+export interface WaveRecord {
+    wave: number;
+    /** chant's op the wave gates are recorded under (the spec's name), and the wave's gate. */
+    op: string;
+    gate: string;
+    /** The wave's set digest. */
+    digest: string;
+    status: "approved" | "not-required";
+    /** For `not-required`: the policy and the commit it was read at. */
+    policy?: string;
+    base?: string;
+}
+/** Reads `note.wave` from a history row's note, or undefined. */
+export declare function waveRecordOf(note: string): WaveRecord | undefined;

package/dist/waves/record.js

@@ -0,0 +1,20 @@
+/** A wave's decision as the history records it (#87). Pure, for ../report/audit.ts. */
+/** The pipeline's name, and the op chant records the wave gates under. */
+export const WAVES_PIPELINE = "yodel-apply";
+/** Reads `note.wave` from a history row's note, or undefined. */
+export function waveRecordOf(note) {
+    if (!note.startsWith("{"))
+        return undefined;
+    try {
+        const w = JSON.parse(note).wave;
+        if (!w || typeof w.gate !== "string" || typeof w.digest !== "string" || typeof w.op !== "string")
+            return undefined;
+        if (w.status !== "approved" && w.status !== "not-required")
+            return undefined;
+        return w;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=record.js.map

package/dist/waves/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/waves/record.ts"],"names":[],"mappings":"AAAA,uFAAuF;AAEvF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;AAsB5C,iEAAiE;AACjE,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,CAAC,GAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAoC,CAAC,IAAI,CAAC;QACpE,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACnH,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,MAAM,KAAK,cAAc;YAAE,OAAO,SAAS,CAAC;QAC7E,OAAO,CAAe,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/sql-yodeler",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Schema management and migrations for ClickHouse and Postgres, on chant's sql lexicon",
   "license": "Apache-2.0",
   "repository": {
@@ -12,6 +12,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./webhook": {
+      "types": "./dist/notify/verify.d.ts",
+      "default": "./dist/notify/verify.js"
     }
   },
   "bin": {
@@ -41,16 +45,16 @@
     "bench": "npm run build && tsx bench/run.ts"
   },
   "dependencies": {
-    "@intentius/chant": "^0.115.0",
-    "@intentius/chant-lexicon-sql": "^0.115.0",
+    "@intentius/chant": "^0.117.0",
+    "@intentius/chant-lexicon-forgejo": "^0.117.0",
+    "@intentius/chant-lexicon-github": "^0.117.0",
+    "@intentius/chant-lexicon-gitlab": "^0.117.0",
+    "@intentius/chant-lexicon-sql": "^0.117.0",
     "tsx": "^4.23.15"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@intentius/chant-lexicon-docker": "^0.115.0",
-    "@intentius/chant-lexicon-forgejo": "^0.115.0",
-    "@intentius/chant-lexicon-github": "^0.115.0",
-    "@intentius/chant-lexicon-gitlab": "^0.115.0",
+    "@intentius/chant-lexicon-docker": "^0.117.0",
     "@types/node": "^22.20.5",
     "@types/pg": "^8.23.1",
     "ajv": "^8.20.0",

package/schemas/apply.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/sql-yodeler/schemas/v1/apply.schema.json",
   "title": "yodel apply <env> --json",
-  "description": "Version 1. On a project with migrations, the status (status.schema.json) with mode \"versioned\" and what apply did; with --execute (the migrations Op's Apply step), what the step applied; on a project without migrations, the declarative outcome with chant's plan. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "description": "Version 1. On a project with migrations, the status (status.schema.json) with mode \"versioned\" and what apply did; with --execute (the migrations Op's Apply step) or --wave-apply (a wave job's apply), what the step applied; with --wave-plan, the wave plan it wrote; on a project without migrations, the declarative outcome with chant's plan. Within a version, fields are only added; a reader ignores fields it does not know.",
   "oneOf": [
     {
       "$ref": "#/$defs/versioned"
@@ -10,6 +10,9 @@
     {
       "$ref": "#/$defs/execute"
     },
+    {
+      "$ref": "#/$defs/wavePlan"
+    },
     {
       "$ref": "#/$defs/declarative"
     }
@@ -35,6 +38,27 @@
         },
         "notice": {
           "type": "string"
+        },
+        "waited": {
+          "description": "The run waited for another apply's lock (--lock-wait): for how long, who held it when the run first found it held, and where.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ms",
+            "heldBy",
+            "where"
+          ],
+          "properties": {
+            "ms": {
+              "type": "integer"
+            },
+            "heldBy": {
+              "type": "string"
+            },
+            "where": {
+              "type": "string"
+            }
+          }
         }
       }
     },
@@ -51,17 +75,22 @@
           "const": "versioned"
         },
         "status": {
-          "description": "planned (--plan, something pending), unchanged, refused, denied (a policy rule denies the plan, with no override), gated (waiting at the Op's gate for a person's approval), failed, applied.",
+          "description": "planned (--plan, something pending), unchanged, refused, denied (a policy rule denies the plan, with no override), stood-down (--stand-down: a newer commit's apply applies this environment, so this one applied nothing), gated (waiting at the Op's gate for a person's approval), failed, applied.",
           "enum": [
             "planned",
             "unchanged",
             "refused",
             "denied",
+            "stood-down",
             "gated",
             "failed",
             "applied"
           ]
         },
+        "stoodDown": {
+          "description": "stood-down: why, in one line.",
+          "type": "string"
+        },
         "preChecks": {
           "description": "The first pending migration's checks, when one failed before the gate.",
           "type": "object",
@@ -173,7 +202,15 @@
           "type": "string"
         },
         "status": {
-          "const": "applied"
+          "description": "applied, or stood-down (--stand-down: a newer commit came while the step waited for the lock, and it applied nothing).",
+          "enum": [
+            "applied",
+            "stood-down"
+          ]
+        },
+        "stoodDown": {
+          "description": "stood-down: why, in one line.",
+          "type": "string"
         },
         "planDigest": {
           "description": "The digest the gate approved.",
@@ -204,6 +241,10 @@
         },
         "lock": {
           "$ref": "#/$defs/lock"
+        },
+        "wavePlanDigest": {
+          "description": "--wave-apply: the wave plan digest chant's wave decision named.",
+          "type": "string"
         }
       }
     },
@@ -264,6 +305,124 @@
           "$ref": "plan.schema.json#/$defs/declarative"
         }
       }
+    },
+    "wavePlan": {
+      "description": "--wave-plan: the plan file chant run wave reads, as written.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "planDigest",
+        "destructive",
+        "empty",
+        "environment",
+        "migrations",
+        "gate",
+        "base",
+        "pending",
+        "destructiveSteps",
+        "requires"
+      ],
+      "properties": {
+        "planDigest": {
+          "description": "The wave plan digest: over the migrations' digest, the gate policy at the base commit and whether a pending step is destructive.",
+          "type": "string"
+        },
+        "destructive": {
+          "type": "boolean"
+        },
+        "empty": {
+          "description": "Nothing is pending.",
+          "type": "boolean"
+        },
+        "environment": {
+          "type": "string"
+        },
+        "migrations": {
+          "description": "The migrations' plan digest, as yodel apply --digest prints it.",
+          "type": "string"
+        },
+        "gate": {
+          "enum": [
+            "always",
+            "on-destructive",
+            "never"
+          ]
+        },
+        "base": {
+          "description": "The base commit the gate was read at.",
+          "type": "string"
+        },
+        "pending": {
+          "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "destructiveSteps": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/destructiveStep"
+          }
+        },
+        "requires": {
+          "description": "Each environment this one requires, and the pending migrations its history records applied; part of the plan digest.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "env",
+              "applied"
+            ],
+            "properties": {
+              "env": {
+                "type": "string"
+              },
+              "applied": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "id",
+                    "checksum"
+                  ],
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "checksum": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "destructiveStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "migration",
+        "step",
+        "what",
+        "why"
+      ],
+      "properties": {
+        "migration": {
+          "type": "string"
+        },
+        "step": {
+          "type": "integer"
+        },
+        "what": {
+          "type": "string"
+        },
+        "why": {
+          "description": "The lint rules that class it (destructive, pg-rewrite, pg-lock, ch-mutation, ch-rebuild), or op-step, manual-step.",
+          "type": "string"
+        }
+      }
     }
   }
 }

package/schemas/checkpoint.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/checkpoint.schema.json",
+  "title": "yodel checkpoint <name> --json",
+  "description": "Version 1. The checkpoint written: its id and directory, the migration whose recorded schema it creates (its parent), its checksum, how many statements it holds, and the SHA-256 of the recorded schema it was written from. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["written", "id", "path", "parent", "checksum", "dialect", "statements", "schema"],
+  "properties": {
+    "written": { "const": true },
+    "id": { "type": "string" },
+    "path": { "type": "string" },
+    "parent": { "type": "string" },
+    "checksum": { "type": "string" },
+    "dialect": { "$ref": "common.schema.json#/$defs/dialect" },
+    "statements": { "type": "integer", "minimum": 1 },
+    "schema": { "type": "string" }
+  }
+}

package/schemas/drift.schema.json

@@ -31,6 +31,31 @@
       "type": "object",
       "additionalProperties": { "$ref": "common.schema.json#/$defs/stringList" }
     },
-    "drifted": { "description": "A declared object changed or is gone: the command exits 2.", "type": "boolean" }
+    "against": {
+      "description": "What the server was compared with: src, the project's declarations; or history, the schema the newest applied migration records (migration null when none is applied yet).",
+      "oneOf": [
+        { "type": "object", "additionalProperties": false, "required": ["source"], "properties": { "source": { "const": "src" } } },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["source", "migration"],
+          "properties": { "source": { "const": "history" }, "migration": { "type": ["string", "null"] } }
+        }
+      ]
+    },
+    "drifted": { "description": "A declared object changed or is gone: the command exits 2.", "type": "boolean" },
+    "fingerprint": { "description": "A hash of the environment and what drifted: the same for the same drift, run after run.", "type": "string" },
+    "issue": {
+      "description": "--issue: what yodel did with the environment's tracking issue, and the issue when there is one.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action"],
+      "properties": {
+        "action": { "enum": ["opened", "updated", "unchanged", "closed", "left", "none"] },
+        "number": { "type": "integer" },
+        "url": { "type": "string" }
+      }
+    },
+    "issueError": { "description": "--issue: the tracking issue could not be written, and why.", "type": "string" }
   }
 }

package/schemas/event.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/event.schema.json",
+  "title": "a yodel webhook event",
+  "description": "Version 1. The body yodel apply, yodel plan and yodel drift post to the webhook yodel.config.ts notify names, signed with HMAC-SHA256 over '<x-yodel-timestamp>.<body>' in the x-yodel-signature header. Within a version, fields are only added; a receiver ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "id", "event", "at", "environment", "command", "status", "summary", "migrations"],
+  "properties": {
+    "version": { "const": 1 },
+    "id": { "type": "string", "description": "Unique per event; also the x-yodel-delivery header." },
+    "event": { "enum": ["waiting", "refused", "failed", "drift"] },
+    "at": { "type": "string", "format": "date-time" },
+    "environment": { "type": "string" },
+    "command": { "enum": ["apply", "plan", "drift"] },
+    "status": { "type": "string", "description": "The command's own word for the outcome: gated, refused, denied, failed, incomplete, drifted." },
+    "summary": { "type": "string" },
+    "migrations": { "type": "array", "items": { "type": "string" }, "description": "The pending migrations, for apply and plan." },
+    "digest": { "type": "string", "description": "The plan digest the run computed." },
+    "approve": { "type": "string", "description": "On waiting: the command that approves the plan." },
+    "reason": { "type": "string" },
+    "drift": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["changed", "missing"],
+      "properties": {
+        "changed": { "type": "array", "items": { "type": "string" } },
+        "missing": { "type": "array", "items": { "type": "string" } },
+        "fingerprint": { "type": "string", "description": "The same drift has the same fingerprint run after run, so a receiver can tell a repeat from new drift." }
+      }
+    },
+    "runUrl": { "type": "string" },
+    "repository": { "type": "string" },
+    "commit": { "type": "string" }
+  }
+}

package/schemas/lint.schema.json

@@ -152,6 +152,10 @@
         },
         "skipped": {
           "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "checkpoint": {
+          "description": "A checkpoint, replayed on its own into an empty database after the chain.",
+          "const": true
         }
       }
     },

package/schemas/plan.schema.json

@@ -341,6 +341,124 @@
           "description": "The project declares no migrations Op for the environment: the first line of how to declare one.",
           "type": "string"
         },
+        "wave": {
+          "description": "The environment's wave of the apply pipeline, when yodel.config.ts declares waves and names it.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "wave",
+            "gate",
+            "base",
+            "baseSource",
+            "destructiveSteps",
+            "waits",
+            "planDigest",
+            "digest",
+            "approve",
+            "promotions",
+            "blocked"
+          ],
+          "properties": {
+            "wave": {
+              "description": "1-based, in yodel.config.ts waves.",
+              "type": "integer",
+              "minimum": 1
+            },
+            "gate": {
+              "description": "The gate policy at the base commit.",
+              "enum": [
+                "always",
+                "on-destructive",
+                "never"
+              ]
+            },
+            "base": {
+              "type": "string"
+            },
+            "baseSource": {
+              "type": "string"
+            },
+            "destructiveSteps": {
+              "type": "array",
+              "items": {
+                "$ref": "apply.schema.json#/$defs/destructiveStep"
+              }
+            },
+            "waits": {
+              "description": "Under that gate, the wave waits for an approval of this plan.",
+              "type": "boolean"
+            },
+            "planDigest": {
+              "description": "The wave plan digest.",
+              "type": "string"
+            },
+            "digest": {
+              "description": "The set digest the wave's gate binds.",
+              "type": "string"
+            },
+            "approve": {
+              "description": "The chant approve command for the wave, for a person to run.",
+              "type": "string"
+            },
+            "promotions": {
+              "description": "Each environment this one requires (waves[].requires) and what its history records of each pending migration.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "env",
+                  "from",
+                  "migrations"
+                ],
+                "properties": {
+                  "env": {
+                    "type": "string"
+                  },
+                  "from": {
+                    "description": "Where the requirement is declared: yodel.config.ts, at the base commit, or both.",
+                    "type": "string"
+                  },
+                  "migrations": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "id",
+                        "checksum",
+                        "ran"
+                      ],
+                      "properties": {
+                        "id": {
+                          "type": "string"
+                        },
+                        "checksum": {
+                          "type": "string"
+                        },
+                        "ran": {
+                          "enum": [
+                            "applied",
+                            "not applied",
+                            "applied with another checksum"
+                          ]
+                        },
+                        "recorded": {
+                          "description": "The checksum the required environment recorded, when it differs.",
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            "blocked": {
+              "description": "A pending migration has not run where it must first: the wave refuses it until it has.",
+              "type": "boolean"
+            }
+          }
+        },
         "sinceLast": {
           "description": "The pull request comment this plan replaces showed another digest: what moved since.",
           "type": "object",

package/schemas/report.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/report.schema.json",
+  "title": "yodel report [<env>...] --json",
+  "description": "Version 1. Every environment's migrations side by side, the audit log derived from each environment's history table and chant's gate ledger, and the gaps those sources show. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "generatedAt", "project", "dialect", "migrations", "environments", "audit", "gaps"],
+  "properties": {
+    "version": { "const": 1 },
+    "generatedAt": { "type": "string", "description": "When the report was read, ISO 8601 UTC." },
+    "project": { "type": "string", "description": "The project directory." },
+    "dialect": { "enum": ["clickhouse", "postgres"] },
+    "migrations": { "type": "array", "items": { "type": "string" }, "description": "The migrations in chain order, then any an environment applied that the directory no longer has." },
+    "environments": { "type": "array", "items": { "$ref": "#/$defs/environment" } },
+    "audit": { "type": "array", "items": { "$ref": "#/$defs/entry" }, "description": "Every environment's audit entries, oldest first." },
+    "gaps": { "type": "array", "items": { "$ref": "#/$defs/gap" } },
+    "auditFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "appended", "missing"],
+      "description": "With --audit: the file, how many entries were appended (0 with --check), and the entries of the file the sources no longer give.",
+      "properties": {
+        "path": { "type": "string" },
+        "appended": { "type": "integer", "minimum": 0 },
+        "missing": { "type": "array", "items": { "$ref": "#/$defs/entry" } }
+      }
+    }
+  },
+  "$defs": {
+    "environment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "notes", "migrations"],
+      "properties": {
+        "name": { "type": "string" },
+        "history": { "type": "string", "description": "<database>.history" },
+        "op": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name", "gate"],
+          "properties": { "name": { "type": "string" }, "gate": { "type": "string" } }
+        },
+        "error": { "type": "string", "description": "Why the environment could not be read." },
+        "notes": { "type": "array", "items": { "type": "string" } },
+        "migrations": { "type": "array", "items": { "$ref": "#/$defs/migration" } }
+      }
+    },
+    "migration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "state", "inDirectory"],
+      "properties": {
+        "id": { "type": "string" },
+        "state": { "enum": ["applied", "pending", "failed", "started", "reverted"] },
+        "inDirectory": { "type": "boolean" },
+        "at": { "type": "string" },
+        "by": { "type": "string" },
+        "digest": { "type": "string" },
+        "approvedBy": { "type": "string" },
+        "approvedAt": { "type": "string" }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "at", "environment", "kind", "source"],
+      "description": "One audit entry; audit.jsonl holds one per line.",
+      "properties": {
+        "id": { "type": "string", "description": "A hash of the entry and its source: the same sources give the same id." },
+        "at": { "type": "string" },
+        "environment": { "type": "string" },
+        "kind": { "enum": ["approval-requested", "approved", "override", "silenced", "applied", "refused", "failed", "repaired", "reverted"] },
+        "by": { "type": "string" },
+        "migration": { "type": "string" },
+        "digest": { "type": "string" },
+        "detail": { "type": "string" },
+        "wave": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["gate", "digest", "status"],
+          "description": "On an applied entry a wave of the apply pipeline applied: the wave's gate, its set digest, and whether the wave was approved or its policy at the base needed no approval.",
+          "properties": { "gate": { "type": "string" }, "digest": { "type": "string" }, "status": { "enum": ["approved", "not-required"] } }
+        },
+        "source": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["ledger", "op", "gate"],
+              "properties": { "ledger": { "type": "string" }, "op": { "type": "string" }, "gate": { "type": "string" } }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["history", "seq", "run"],
+              "properties": { "history": { "type": "string" }, "seq": { "type": "integer", "minimum": 1 }, "run": { "type": "string" } }
+            }
+          ]
+        }
+      }
+    },
+    "gap": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["environment", "kind", "detail"],
+      "properties": {
+        "environment": { "type": "string" },
+        "kind": { "enum": ["history-row", "approval"] },
+        "detail": { "type": "string" }
+      }
+    }
+  }
+}