@intentius/sql-yodeler 0.2.0 → 0.4.0

package/dist/waves/promotion.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Promotion (#43): an environment applies only migrations the environment
+ * before it recorded as applied.
+ *
+ * `waves[].requires` names that environment; it defaults to the wave
+ * before, and `false` turns it off. Before anything is applied (and before
+ * the gate), `yodel apply <env>` reads each required environment's history
+ * with that environment's own profile, which outside an apply job is its
+ * reader, and refuses (exit 4) any pending migration the history does not
+ * record as applied with the checksum its files have now. The requirement
+ * is read from the working tree's yodel.config.ts and from the base
+ * commit's, and both are enforced, so a change that drops its own
+ * requirement is still held to the base's.
+ */
+import type { YodelConfig } from "../config/define.js";
+import type { Migration } from "../migrations/index.js";
+import { YodelError, type Project } from "../project.js";
+import type { PendingMigration } from "../versioned/state.js";
+/** The environment `env` requires in `config`: `requires`, else the wave before; undefined for none. */
+export declare function requiredIn(config: YodelConfig | undefined, env: string): string | undefined;
+/**
+ * Each required environment and where the requirement comes from: the
+ * working tree, the base commit, or both. A tenant (#56) requires what its
+ * environment requires: the same tenant when that environment has a tenant
+ * set too, else the environment.
+ */
+export declare function requiredEnvironments(project: Project, env: string): Promise<Array<{
+    env: string;
+    from: string;
+}>>;
+/** What one required environment's history says of each pending migration. */
+export interface Promotion {
+    /** The required environment. */
+    env: string;
+    from: string;
+    migrations: Array<{
+        id: string;
+        checksum: string;
+        ran: "applied" | "not applied" | "applied with another checksum";
+        recorded?: string;
+    }>;
+}
+/** Reads each required environment's history for `pending`. */
+export declare function readPromotions(project: Project, env: string, ordered: readonly Migration[], pending: ReadonlyArray<Pick<PendingMigration, "id" | "checksum">>): Promise<Promotion[]>;
+/** The refusal for the promotions, or undefined when every pending migration ran where it had to. */
+export declare function promotionRefusal(env: string, promotions: readonly Promotion[]): YodelError | undefined;
+/** Reads the required environments and throws the refusal when a pending migration has not run there. */
+export declare function enforcePromotion(project: Project, env: string, ordered: readonly Migration[], pending: ReadonlyArray<Pick<PendingMigration, "id" | "checksum">>): Promise<Promotion[]>;
+/** What the wave plan digest takes of the promotions: each required environment and the pending migrations' checksums it recorded. */
+export declare const promotionEvidence: (promotions: readonly Promotion[]) => {
+    env: string;
+    applied: {
+        id: string;
+        checksum: string;
+    }[];
+}[];

package/dist/waves/promotion.js

@@ -0,0 +1,108 @@
+/**
+ * Promotion (#43): an environment applies only migrations the environment
+ * before it recorded as applied.
+ *
+ * `waves[].requires` names that environment; it defaults to the wave
+ * before, and `false` turns it off. Before anything is applied (and before
+ * the gate), `yodel apply <env>` reads each required environment's history
+ * with that environment's own profile, which outside an apply job is its
+ * reader, and refuses (exit 4) any pending migration the history does not
+ * record as applied with the checksum its files have now. The requirement
+ * is read from the working tree's yodel.config.ts and from the base
+ * commit's, and both are enforced, so a change that drops its own
+ * requirement is still held to the base's.
+ */
+import { loadYodelConfigAtBase } from "../config/base.js";
+import { EXIT_REFUSED } from "../exit.js";
+import { resolveEnvironment, YodelError } from "../project.js";
+import { closeVersioned, inspect, openVersioned } from "../versioned/engine.js";
+import { splitTarget, tenantTarget } from "../tenants/target.js";
+/** The environment `env` requires in `config`: `requires`, else the wave before; undefined for none. */
+export function requiredIn(config, env) {
+    const waves = config?.waves ?? [];
+    const i = waves.findIndex((w) => w.env === env);
+    const wave = waves[i];
+    if (!wave || wave.requires === false)
+        return undefined;
+    return wave.requires ?? waves[i - 1]?.env;
+}
+/**
+ * Each required environment and where the requirement comes from: the
+ * working tree, the base commit, or both. A tenant (#56) requires what its
+ * environment requires: the same tenant when that environment has a tenant
+ * set too, else the environment.
+ */
+export async function requiredEnvironments(project, env) {
+    const out = new Map();
+    const { env: base, tenant } = splitTarget(env);
+    const add = (e, from) => {
+        const target = e && tenant !== undefined && project.yodel?.config.environments?.[e]?.tenants ? tenantTarget(e, tenant) : e;
+        if (target && target !== env)
+            out.set(target, [...(out.get(target) ?? []), from]);
+    };
+    add(requiredIn(project.yodel?.config, base), "yodel.config.ts");
+    try {
+        const at = await loadYodelConfigAtBase(project.dir);
+        add(requiredIn(at.config, base), `yodel.config.ts at ${at.sha.slice(0, 12)}`);
+    }
+    catch {
+        // No git, or no base commit (a repository's first commit): the working tree's requirement alone.
+    }
+    return [...out].map(([e, from]) => ({ env: e, from: from.join(" and ") }));
+}
+/** Reads each required environment's history for `pending`. */
+export async function readPromotions(project, env, ordered, pending) {
+    const out = [];
+    for (const req of await requiredEnvironments(project, env)) {
+        let environment;
+        try {
+            environment = resolveEnvironment(project, req.env);
+        }
+        catch (e) {
+            throw new YodelError(`refused: ${env} requires ${req.env} (${req.from}), and ${e instanceof Error ? e.message : String(e)}; nothing was applied`, EXIT_REFUSED);
+        }
+        const venv = await openVersioned(project, environment);
+        try {
+            const { status } = await inspect(venv, ordered, { sync: false });
+            const applied = new Map(status.applied.map((a) => [a.id, a.checksum]));
+            out.push({
+                env: req.env,
+                from: req.from,
+                migrations: pending.map((p) => {
+                    const recorded = applied.get(p.id);
+                    if (recorded === undefined)
+                        return { id: p.id, checksum: p.checksum, ran: "not applied" };
+                    return recorded === p.checksum ? { id: p.id, checksum: p.checksum, ran: "applied" } : { id: p.id, checksum: p.checksum, ran: "applied with another checksum", recorded };
+                }),
+            });
+        }
+        finally {
+            await closeVersioned(venv);
+        }
+    }
+    return out;
+}
+/** The refusal for the promotions, or undefined when every pending migration ran where it had to. */
+export function promotionRefusal(env, promotions) {
+    const lines = promotions.flatMap((p) => p.migrations
+        .filter((m) => m.ran !== "applied")
+        .map((m) => `  ${m.id}: ${m.ran === "not applied" ? `${p.env}'s history does not record it applied` : `${p.env} applied it with checksum ${m.recorded ?? "?"}, and its files now hash to ${m.checksum}`} (required by ${p.from})`));
+    if (lines.length === 0)
+        return undefined;
+    const envs = [...new Set(promotions.filter((p) => p.migrations.some((m) => m.ran !== "applied")).map((p) => p.env))];
+    return new YodelError(`refused: ${env} applies only migrations ${envs.join(" and ")} applied first, and ${String(lines.length)} pending ${lines.length === 1 ? "one has" : "ones have"} not run there:\n${lines.join("\n")}\n` +
+        `Nothing was applied. Apply ${lines.length === 1 ? "it" : "them"} to ${envs.join(" and ")} first.`, EXIT_REFUSED);
+}
+/** Reads the required environments and throws the refusal when a pending migration has not run there. */
+export async function enforcePromotion(project, env, ordered, pending) {
+    if (pending.length === 0)
+        return [];
+    const promotions = await readPromotions(project, env, ordered, pending);
+    const refusal = promotionRefusal(env, promotions);
+    if (refusal)
+        throw refusal;
+    return promotions;
+}
+/** What the wave plan digest takes of the promotions: each required environment and the pending migrations' checksums it recorded. */
+export const promotionEvidence = (promotions) => promotions.map((p) => ({ env: p.env, applied: p.migrations.filter((m) => m.ran === "applied").map((m) => ({ id: m.id, checksum: m.checksum })) }));
+//# sourceMappingURL=promotion.js.map

package/dist/waves/promotion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promotion.js","sourceRoot":"","sources":["../../src/waves/promotion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAgB,MAAM,eAAe,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGjE,wGAAwG;AACxG,MAAM,UAAU,UAAU,CAAC,MAA+B,EAAE,GAAW;IACrE,MAAM,KAAK,GAA0B,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC;IACzD,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IACvD,OAAO,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAgB,EAAE,GAAW;IACtE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IACxC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,CAAC,CAAqB,EAAE,IAAY,EAAE,EAAE;QAClD,MAAM,MAAM,GAAG,CAAC,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3H,IAAI,MAAM,IAAI,MAAM,KAAK,GAAG;YAAE,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACpF,CAAC,CAAC;IACF,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAChE,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACpD,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,sBAAsB,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,iGAAiG;IACnG,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;AAC7E,CAAC;AAUD,+DAA+D;AAC/D,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAgB,EAAE,GAAW,EAAE,OAA6B,EAAE,OAAiE;IAClK,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,MAAM,oBAAoB,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;QAC3D,IAAI,WAAW,CAAC;QAChB,IAAI,CAAC;YACH,WAAW,GAAG,kBAAkB,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,UAAU,CAAC,YAAY,GAAG,aAAa,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,IAAI,UAAU,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,uBAAuB,EAAE,YAAY,CAAC,CAAC;QAClK,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACvD,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACjE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YACvE,GAAG,CAAC,IAAI,CAAC;gBACP,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;oBACnC,IAAI,QAAQ,KAAK,SAAS;wBAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC;oBAC1F,OAAO,QAAQ,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,+BAA+B,EAAE,QAAQ,EAAE,CAAC;gBAC3K,CAAC,CAAC;aACH,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,UAAgC;IAC5E,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CACrC,CAAC,CAAC,UAAU;SACT,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC;SAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,KAAK,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,uCAAuC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,6BAA6B,CAAC,CAAC,QAAQ,IAAI,GAAG,+BAA+B,CAAC,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC,IAAI,GAAG,CAAC,CACrO,CAAC;IACF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACrH,OAAO,IAAI,UAAU,CACnB,YAAY,GAAG,4BAA4B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,uBAAuB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,oBAAoB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACtM,8BAA8B,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EACpG,YAAY,CACb,CAAC;AACJ,CAAC;AAED,yGAAyG;AACzG,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgB,EAAE,GAAW,EAAE,OAA6B,EAAE,OAAiE;IACpK,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAClD,IAAI,OAAO;QAAE,MAAM,OAAO,CAAC;IAC3B,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,sIAAsI;AACtI,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,UAAgC,EAAE,EAAE,CACpE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/waves/record.d.ts

@@ -0,0 +1,34 @@
+/** 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;
+    /** Which approvals counted (#48), when not `ledger`. */
+    approval?: string;
+    /** Under `pr-review`, the review that approved the wave: the pull request, the head it approved and its approvers. */
+    review?: {
+        pr: number;
+        head: string;
+        approvers: string[];
+    };
+    /** Under `sealed`, the signer whose seal verified. */
+    signer?: 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;AA4B5C,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.4.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.118.1",
+    "@intentius/chant-lexicon-forgejo": "^0.118.1",
+    "@intentius/chant-lexicon-github": "^0.118.1",
+    "@intentius/chant-lexicon-gitlab": "^0.118.1",
+    "@intentius/chant-lexicon-sql": "^0.118.1",
     "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.118.1",
     "@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, pg-access, ch-mutation, ch-rebuild, ch-access), 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/cleanup.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/cleanup.schema.json",
+  "title": "yodel cleanup <env> --json",
+  "description": "Version 1. What steps kept in the environment (a rebuild's old table, a column migration's old column), each with its retention date and whether it is due, the digest an approval of the drop binds when something is due, and what was dropped. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["environment", "now", "retained", "due", "dropped"],
+  "properties": {
+    "environment": { "type": "string" },
+    "now": { "description": "The server's clock when it was read (ISO 8601).", "type": "string" },
+    "retained": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "name", "of", "due", "identity"],
+        "properties": {
+          "kind": { "enum": ["table", "column"] },
+          "name": { "description": "db.table__chant_old, or schema.table.column.", "type": "string" },
+          "of": { "description": "The rebuild (db.table) or column migration (schema.table.column) that kept it.", "type": "string" },
+          "retainUntil": { "description": "Its retention date (ISO 8601), from its comment; absent when its comment has none, and then it is never due.", "type": "string" },
+          "due": { "type": "boolean" },
+          "identity": { "description": "The table's UUID, or the column's table oid and attribute number.", "type": "string" },
+          "trigger": {
+            "description": "Postgres: the dual-write trigger and function dropped with the column.",
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "fn"],
+            "properties": { "name": { "type": "string" }, "fn": { "type": "string" } }
+          }
+        }
+      }
+    },
+    "due": { "type": "integer", "minimum": 0 },
+    "planDigest": { "description": "When something is due: the digest an approval of the drop binds.", "type": "string" },
+    "approve": { "description": "When something is due and not approved: the command that approves it.", "type": "string" },
+    "dropped": { "$ref": "common.schema.json#/$defs/stringList" }
+  }
+}

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-rules.schema.json

@@ -41,6 +41,10 @@
         "description": "The dialect it applies to; both when absent.",
         "$ref": "common.schema.json#/$defs/dialect"
       },
+      "schema": {
+        "description": "One of the sql lexicon's schema checks, run on each migration's recorded schema.",
+        "type": "boolean"
+      },
       "configured": {
         "description": "The level in this project.",
         "enum": [