@intentius/sql-yodeler 0.1.0 → 0.3.0

package/dist/versioned/stand-down.js

@@ -0,0 +1,56 @@
+/**
+ * `yodel apply --stand-down` (`YODEL_STAND_DOWN=1`): an apply that a newer
+ * commit will make anyway steps aside instead of queueing for the lock.
+ *
+ * The branch is the one the run is for: `GITHUB_REF_NAME` (GitHub and
+ * Forgejo Actions), `CI_COMMIT_BRANCH` (GitLab CI), else the checked-out
+ * branch. Its tip is fetched from `origin`; when that tip is a different
+ * commit that contains this one, a newer commit is on the branch, and its
+ * own apply job applies the same environment, this run included. Anything
+ * that cannot be told (no branch, no origin, a fetch that fails, a tip that
+ * does not contain this commit, as after a force-push) is not a newer
+ * commit: the apply goes ahead.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+export const STAND_DOWN_ENV = "YODEL_STAND_DOWN";
+/** Whether the environment asks for stand-down: `YODEL_STAND_DOWN=1` (or `true`). */
+export const standDownFromEnv = (env) => env[STAND_DOWN_ENV] === "1" || env[STAND_DOWN_ENV] === "true";
+async function git(dir, args) {
+    try {
+        const { stdout } = await exec("git", args, { cwd: dir, timeout: 60_000 });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The branch a run is for; see the module comment. */
+export async function runBranch(dir, env) {
+    const named = env.GITHUB_REF_NAME || env.CI_COMMIT_BRANCH;
+    if (named)
+        return named;
+    return (await git(dir, ["symbolic-ref", "--quiet", "--short", "HEAD"])) || undefined;
+}
+/** The newer commit on the run's branch, or `undefined` when there is none or it cannot be told. */
+export async function newerCommit(dir, env = process.env) {
+    const branch = await runBranch(dir, env);
+    if (!branch)
+        return undefined;
+    const head = await git(dir, ["rev-parse", "HEAD"]);
+    if (!head)
+        return undefined;
+    if ((await git(dir, ["fetch", "--quiet", "--no-tags", "origin", `refs/heads/${branch}`])) === undefined)
+        return undefined;
+    const tip = await git(dir, ["rev-parse", "FETCH_HEAD"]);
+    if (!tip || tip === head)
+        return undefined;
+    // A tip that contains this commit is newer; one that does not (a force-push, another line) is not.
+    if ((await git(dir, ["merge-base", "--is-ancestor", head, tip])) === undefined)
+        return undefined;
+    return { branch, head, tip };
+}
+/** What a run that stands down says. */
+export const standDownLine = (env, n) => `standing down: ${n.branch} on origin is at ${n.tip.slice(0, 12)}, newer than this run's ${n.head.slice(0, 12)}, and its own apply applies ${env}. Nothing was applied by this run.`;
+//# sourceMappingURL=stand-down.js.map

package/dist/versioned/stand-down.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stand-down.js","sourceRoot":"","sources":["../../src/versioned/stand-down.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAEjC,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAEjD,qFAAqF;AACrF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAsB,EAAW,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,KAAK,MAAM,CAAC;AAWnI,KAAK,UAAU,GAAG,CAAC,GAAW,EAAE,IAAc;IAC5C,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAC1E,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW,EAAE,GAAsB;IACjE,MAAM,KAAK,GAAG,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,gBAAgB,CAAC;IAC1D,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,OAAO,CAAC,MAAM,GAAG,CAAC,GAAG,EAAE,CAAC,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;AACvF,CAAC;AAED,oGAAoG;AACpG,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW,EAAE,MAAyB,OAAO,CAAC,GAAG;IACjF,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,MAAM,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1H,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC3C,mGAAmG;IACnG,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACjG,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAC/B,CAAC;AAED,wCAAwC;AACxC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAW,EAAE,CAAc,EAAU,EAAE,CACnE,kBAAkB,CAAC,CAAC,MAAM,oBAAoB,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,2BAA2B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,+BAA+B,GAAG,oCAAoC,CAAC"}

package/dist/versioned/state.d.ts

@@ -21,6 +21,16 @@
  * migration that failed part way may be edited before it resumes (to fix
  * the statement that failed), as long as every statement that already
  * succeeded is unchanged: those are compared statement by statement.
+ *
+ * ## Checkpoints (#63)
+ *
+ * A checkpoint creates its parent's recorded schema from nothing. An
+ * environment whose history is empty starts at the newest checkpoint: the
+ * migrations before it are skipped, never run there. An environment whose
+ * history records a checkpoint started there, and skips the migrations
+ * before it the same way. Any other checkpoint is skipped: the environment
+ * ran (or started past) the migrations it stands for. A skipped migration
+ * is neither applied nor pending, so it is never out of order either.
  */
 import type { MigrationStep } from "@intentius/chant-lexicon-sql/migration-statements";
 import { type Migration } from "../migrations/index.js";
@@ -59,6 +69,11 @@ export interface PendingMigration {
     /** Before a migration the history records applied. */
     outOfOrder: boolean;
     partWay: PartWay | undefined;
+    /** It was applied, then `yodel revert` (#55) undid it: who reverted it and when. Applied again, every statement runs again. */
+    reverted?: {
+        by: string;
+        at: string;
+    };
     /** Its Op steps `apply` runs: a ClickHouse rebuild, a backfill (#12). */
     opSteps: Array<{
         index: number;
@@ -93,12 +108,22 @@ export type Mismatch = {
     recorded: string;
     message: string;
 };
+/** A migration this environment never runs, because of a checkpoint (#63). */
+export interface SkippedMigration {
+    id: string;
+    /** `covered`: it comes before the checkpoint the environment starts from. `checkpoint`: a checkpoint the environment does not start from. */
+    reason: "covered" | "checkpoint";
+    /** `covered`: the checkpoint the environment starts from. */
+    checkpoint?: string;
+}
 export interface VersionedStatus {
     /** In chain order; then any the directory no longer has, in the order they were applied. */
     applied: AppliedMigration[];
     /** In chain order. */
     pending: PendingMigration[];
     mismatches: Mismatch[];
+    /** In chain order: the migrations a checkpoint leaves out here. Absent when there are none. */
+    skipped?: SkippedMigration[];
 }
 export declare const outOfOrder: (s: VersionedStatus) => PendingMigration[];
 export declare const partWay: (s: VersionedStatus) => PendingMigration[];

package/dist/versioned/state.js

@@ -21,9 +21,19 @@
  * migration that failed part way may be edited before it resumes (to fix
  * the statement that failed), as long as every statement that already
  * succeeded is unchanged: those are compared statement by statement.
+ *
+ * ## Checkpoints (#63)
+ *
+ * A checkpoint creates its parent's recorded schema from nothing. An
+ * environment whose history is empty starts at the newest checkpoint: the
+ * migrations before it are skipped, never run there. An environment whose
+ * history records a checkpoint started there, and skips the migrations
+ * before it the same way. Any other checkpoint is skipped: the environment
+ * ran (or started past) the migrations it stands for. A skipped migration
+ * is neither applied nor pending, so it is never out of order either.
  */
-import { computeChecksum } from "../migrations/index.js";
-import { isApplied, statementDone } from "../history/index.js";
+import { computeChecksum, isCheckpoint } from "../migrations/index.js";
+import { isApplied, isReverted, statementDone } from "../history/index.js";
 import { planStep, stepSha } from "../steps/index.js";
 export const outOfOrder = (s) => s.pending.filter((p) => p.outOfOrder);
 export const partWay = (s) => s.pending.filter((p) => p.partWay !== undefined);
@@ -125,13 +135,36 @@ export function compareHistory(ordered, state) {
             message: `${r.id} is recorded applied, but the migrations directory no longer has it; restore it, or ${repair(r.id)}`,
         });
     }
+    // The checkpoint this environment starts from: the newest one its history records, or, for an empty history, the newest one in the chain.
+    let start = -1;
+    for (const [i, m] of ordered.entries())
+        if (isCheckpoint(m) && state.byId.has(m.id))
+            start = i;
+    if (start < 0 && state.migrations.length === 0)
+        for (const [i, m] of ordered.entries())
+            if (isCheckpoint(m))
+                start = i;
+    const startId = start < 0 ? undefined : ordered[start]?.id;
+    const skipped = [];
     const pending = [];
     for (const [i, m] of ordered.entries()) {
         const rec = state.byId.get(m.id);
         if (isApplied(rec))
             continue;
+        if (!rec && i < start) {
+            skipped.push({ id: m.id, reason: "covered", ...(startId ? { checkpoint: startId } : {}) });
+            continue;
+        }
+        if (!rec && i !== start && isCheckpoint(m)) {
+            skipped.push({ id: m.id, reason: "checkpoint" });
+            continue;
+        }
         const actual = computeChecksum(m.files);
         let pw;
+        if (rec && isReverted(rec)) {
+            pending.push({ id: m.id, index: i, checksum: actual, outOfOrder: i < lastApplied, partWay: undefined, reverted: { by: rec.appliedBy, at: rec.recordedAt }, ...classifySteps(m), migration: m });
+            continue;
+        }
         if (rec) {
             const r = partWayOf(m, rec, actual);
             pw = r.partWay;
@@ -148,6 +181,6 @@ export function compareHistory(ordered, state) {
             migration: m,
         });
     }
-    return { applied, pending, mismatches };
+    return { applied, pending, mismatches, ...(skipped.length > 0 ? { skipped } : {}) };
 }
 //# sourceMappingURL=state.js.map

package/dist/versioned/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/versioned/state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/versioned/state.ts"],"names":[],"mappings":"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"}

package/dist/waves/index.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Environment waves (#42): the apply pipeline as chant's Op waves, one wave
+ * per environment, each behind a gate policy of its own.
+ *
+ * The project's CI script renders `yodel.config.ts` `waves` as a chant Op
+ * waves spec, {@link WAVES_SPEC_FILE}, and the pipeline from it (`chant run
+ * --generate <forge> --spec`, or `generateOpWavesPipeline`). Every wave's
+ * job runs `chant run wave`, which calls back into yodel twice per
+ * environment:
+ *
+ * - `yodel apply <env> --wave-plan <file>` ({@link writeWavePlan}): the
+ *   plan file chant binds the wave's gate to. Its `planDigest` covers the
+ *   migrations' plan digest (what `--digest` prints), the environment's gate
+ *   policy as the base commit's `yodel.config.ts` has it, and whether a
+ *   pending step is destructive, which is what `on-destructive` waits on.
+ * - `yodel apply <env> --wave-apply <file>` ({@link applyWave}): applies
+ *   that plan, under the lock, only when chant's decision for the wave lets
+ *   it through: an approval of the wave's set digest in the gate ledger, or
+ *   a policy at the base commit that needs none. The plan is computed again
+ *   under the lock and must be the one the decision was made on.
+ *
+ * chant reads the policy from the spec file at the first parent, so a pull
+ * request that loosens its own environment's gate merges under the old one.
+ */
+import { type ConfigAtBase } from "../config/base.js";
+import type { WaveGate, YodelConfig } from "../config/define.js";
+import type { Migration } from "../migrations/index.js";
+import { type Project } from "../project.js";
+import { type VersionedEnv } from "../versioned/engine.js";
+import type { PendingMigration } from "../versioned/state.js";
+import { type WaveRecord } from "./record.js";
+import { type Promotion } from "./promotion.js";
+export * from "./promotion.js";
+export * from "./record.js";
+/** The waves spec the CI script writes and every wave job reads. */
+export declare const WAVES_SPEC_FILE = "yodel-waves.json";
+export declare const WAVE_PLAN_KIND = "yodel-wave";
+/** The gate policy an environment no wave names gets. */
+export declare const DEFAULT_WAVE_GATE: WaveGate;
+/** `env`'s wave gate in `config`; a tenant's is its environment's. */
+export declare function waveGate(config: YodelConfig | undefined, env: string): {
+    gate: WaveGate;
+    declared: boolean;
+};
+/** A pending step `on-destructive` waits on, and why. */
+export interface DestructiveStep {
+    migration: string;
+    step: number;
+    what: string;
+    /** The lint rule that classes it, or `op-step` / `manual-step`. */
+    why: string;
+}
+/**
+ * The steps of `pending` that `on-destructive` waits on: a destructive
+ * statement or Op step, a Postgres rewrite or lock-heavy statement, a
+ * ClickHouse mutation or rebuild (lint's statement rules, whatever their
+ * level or silences), and any Op or manual step.
+ */
+export declare function destructiveSteps(dialect: "clickhouse" | "postgres", pending: ReadonlyArray<Pick<PendingMigration, "id"> & {
+    migration: Pick<Migration, "document">;
+}>): DestructiveStep[];
+/** What `--wave-plan` writes: chant's plan file, and what yodel needs to apply exactly it. */
+export interface WavePlanFile {
+    /** chant's: what the wave's set digest is taken over. */
+    planDigest: string;
+    destructive: boolean;
+    empty: boolean;
+    environment: string;
+    /** The migrations' plan digest, as `yodel apply --digest` prints it; the history records it. */
+    migrations: string;
+    /** The gate policy at the base commit, and that commit. */
+    gate: WaveGate;
+    base: string;
+    pending: string[];
+    destructiveSteps: DestructiveStep[];
+    /** Each environment this one requires, and the pending migrations its history records applied. */
+    requires: Array<{
+        env: string;
+        applied: Array<{
+            id: string;
+            checksum: string;
+        }>;
+    }>;
+}
+/** The wave plan's digest: over what the run would do and the policy it is gated under. */
+export declare function wavePlanDigest(subject: {
+    environment: string;
+    migrations: string;
+    gate: WaveGate;
+    destructive: boolean;
+    requires?: ReadonlyArray<{
+        env: string;
+        applied: ReadonlyArray<{
+            id: string;
+            checksum: string;
+        }>;
+    }>;
+}): Promise<string>;
+/** The gate policy for `env` at the base commit. */
+export declare function gateAtBase(project: Project, env: string): Promise<{
+    gate: WaveGate;
+    at: ConfigAtBase;
+    declared: boolean;
+}>;
+/** The wave plan for one environment, now. A refusal (out of order, a checksum) throws, as `--digest` does. */
+export declare function planWave(project: Project, venv: VersionedEnv, ordered: readonly Migration[], options: {
+    allowOutOfOrder: boolean;
+}): Promise<WavePlanFile>;
+/** `--wave-plan <file>`: writes the plan file. */
+export declare function writeWavePlan(project: Project, venv: VersionedEnv, ordered: readonly Migration[], file: string, options: {
+    allowOutOfOrder: boolean;
+}): Promise<WavePlanFile>;
+/**
+ * Throws unless chant's decision for `env`'s wave lets `planDigest` apply:
+ * the decision names this plan for `env`, and either the gate ledger holds
+ * an approval of the wave's set digest, or the wave's policy at the base
+ * commit needs no approval for these plans.
+ */
+export declare function verifyWaveDecision(cwd: string, specFile: string, env: string, planDigest: string): Promise<{
+    line: string;
+    wave: WaveRecord;
+}>;
+/** chant's decision for a wave, as `chant run wave` will make it once this plan is written. */
+export interface WaveForecast {
+    wave: number;
+    name: string;
+    gate: string;
+    digest: string;
+    policy: string;
+    base: string;
+    /** No approval of `digest` stands and the policy asks for one: chant exits 3. */
+    waits: boolean;
+    /** `chant approve <op> <gate> --plan <digest>`. */
+    approve: string;
+}
+/** Where chant run wave writes a run's plan file (chant's opWavePlanPath). */
+export declare const wavePlanPath: (op: string, wave: number, target: string) => string;
+/**
+ * The decision chant makes for `plan`'s wave right after `--wave-plan`,
+ * made the same way and from the same sources: the policy from the spec at
+ * yodel's base, chant's own rule, and the gate ledger for an approval of
+ * the wave's set digest. A tenant set's wave (#56) has a run per tenant,
+ * which chant plans in order: the forecast is made at the last run, from
+ * the plan files the runs before it wrote; at any other run it is
+ * undefined.
+ */
+export declare function forecastWave(cwd: string, specFile: string, plan: WavePlanFile): Promise<WaveForecast | undefined>;
+/** Reads a plan file `--wave-plan` wrote. */
+export declare function readWavePlan(file: string): WavePlanFile;
+/** What `yodel plan` and the pull request comment show of an environment's wave. */
+export interface WaveView {
+    /** 1-based, in yodel.config.ts `waves`. */
+    wave: number;
+    gate: WaveGate;
+    /** The base commit the gate was read at, and how it was chosen. */
+    base: string;
+    baseSource: string;
+    destructiveSteps: DestructiveStep[];
+    /** Under the gate at the base, the wave waits for an approval of this plan. */
+    waits: boolean;
+    /** The wave plan digest and the set digest the wave's gate binds. */
+    planDigest: string;
+    digest: string;
+    /** `chant approve yodel-apply yodel-apply-wave-<k> --plan <digest>`. */
+    approve: string;
+    /** What each required environment's history records of the pending migrations. */
+    promotions: Promotion[];
+    /** A pending migration has not run where it must first: the wave refuses until it has, so there is nothing to approve yet. */
+    blocked: boolean;
+}
+/**
+ * `env`'s wave, as the apply pipeline will plan it after the merge, when
+ * yodel.config.ts declares waves and names `env`; undefined otherwise. The
+ * gate is the base commit's: on a pull request, the merge base with the
+ * target branch.
+ */
+export declare function waveView(project: Project, env: string, ordered: readonly Migration[], pending: readonly PendingMigration[], migrations: string): Promise<WaveView | undefined>;
+/** One line on the wave, for text and markdown. */
+export declare function describeWave(w: WaveView, code?: (s: string) => string): string;