@intentius/chant 0.124.13 → 0.124.14

package/dist/op/op-waves.js

@@ -0,0 +1,409 @@
+/**
+ * Gated waves of Op runs (#3679): a pipeline that applies one Op per
+ * environment, or per target in a set, in order, each wave behind one gate.
+ *
+ * A product built on chant that applies a migration to dev, then staging, then
+ * prod, or the same change to every tenant database of an environment, used to
+ * render that ordering itself, once per forge, and compute each wave's set
+ * digest itself. This module holds the forge-neutral part: the spec, the jobs
+ * it becomes and the commands they run. Each forge lexicon (github, gitlab,
+ * forgejo) renders these jobs with its own transport, so the three cannot
+ * disagree about order or commands. `./op-waves-run.ts` is what the jobs run.
+ *
+ * ## Jobs
+ *
+ * A wave is one job, `wave-<k>-<name>`, running `chant run wave --spec <file>
+ * --wave <k>`: plan every run, decide the wave's gate, apply. A wide wave
+ * (`shares` > 1) is a deciding job that plans every run and decides the gate,
+ * plus `shares` jobs that each apply a slice of the runs and refuse a run
+ * whose plan moved since the decision. Each wave's jobs need the previous
+ * wave's last jobs, so a wave that waits (exit 3) or fails stops every later
+ * wave.
+ *
+ * ## The gate
+ *
+ * Wave k waits on `waveGateName(<gate>, k)`, or the spec's `gateName` pattern
+ * ({@link opWaveGateName}, #3821), recorded under the spec's name, bound to
+ * {@link waveSetDigest} over its runs' plan digests (`../gated-waves.ts`, the
+ * same digest a component fan-out's wave binds), or with `digest.over:
+ * "changing"` over the runs whose plan changes something. Whether it waits at all
+ * is the wave's gate policy, read from the base commit's copy of the spec
+ * file, so a change cannot loosen the rule that gates its own merge.
+ *
+ * So is which approvals count (#3684), the wave's `approval`: `ledger` (any
+ * `chant approve` of the digest), `sealed` (only one whose seal verifies
+ * against the signers file at base) or `pr-review` (also the merged pull
+ * request's review of its head, by a writer other than its author, when the
+ * head planned the same digest). See `./gate-review.ts`.
+ *
+ * ## Spent approvals (#3784)
+ *
+ * With `approvals: { spend: true }` (read at base, like the policy), a wave
+ * records each approval it applies under in `_gates/<name>/applied.jsonl` on
+ * `chant/lifecycle`, as terragucci's wave gate does, and that approval is
+ * spent: the same digest needs a new approval to apply again.
+ *
+ * ## Wave-level commands and hooks (#3762)
+ *
+ * A product whose tool plans a whole wave in one call (Terragrunt's `run
+ * --all`, an apply by rows) gives `planWave` and `applyWave` in place of the
+ * per-run `plan` and `apply`: one call plans every run and lists each run's
+ * plan, and the wave's digest and gate come from that list as from per-run
+ * plans. Stage hooks (`hooks`) run commands before and after the plan and the
+ * apply; like the policy they are read from the spec at the base commit, and
+ * one whose `onFailure` is `approve` holds the wave for an approval whatever
+ * its policy says.
+ *
+ * ## A gate that asks a decision point (#3836)
+ *
+ * With `point` (on the spec, or on a wave, whose own wins), read at base like
+ * the policy, a wave that needs an approval asks that workspace decision
+ * point instead of reading the ledger for a `chant approve`, the way an Op
+ * gate with a `point` does (#3170): `gate.planDigest` is the wave's set
+ * digest, so each plan is its own question. An open question waits (exit 3,
+ * the pending fact cites it), an answer the gate passes on records the
+ * resolution that cites it and the wave goes on, and any other answer refuses
+ * the wave (exit 8). See `./op-waves-run.ts`.
+ */
+import { gatePointProblems } from "./gate-point.js";
+import { notifyConfigProblem } from "../notify.js";
+/**
+ * The variables a wave job reads its notify secrets from, for the lexicons
+ * that generate wave pipelines. Re-exported here because a lexicon's source
+ * in this repository cannot import `@intentius/chant/notify`: under any
+ * loader that entry resolves its `import` condition to the compiled
+ * `dist/notify.js` (#3803), which only a packed release carries.
+ */
+export { notifyVariables } from "../notify.js";
+export const OP_WAVE_GATE_POLICIES = ["always", "on-destructive", "never"];
+export const GATE_APPROVAL_SOURCES = ["ledger", "pr-review", "sealed"];
+/** A wave's or a spec's `point` as an {@link OpWavePoint}, or undefined when it names none. */
+export function opWavePointOf(point) {
+    if (point === undefined)
+        return undefined;
+    return typeof point === "string" ? { name: point } : point;
+}
+/** What is wrong with a wave's `point`, empty when nothing is (#3836). */
+export function opWavePointProblems(point) {
+    if (point !== null && typeof point === "object" && !Array.isArray(point) && "timeout" in point) {
+        const { timeout, ...rest } = point;
+        const problems = gatePointProblems(rest);
+        if (typeof timeout !== "string" || !/^(\d+(ms|s|m|h|d))+$/.test(timeout))
+            problems.push("`point.timeout` is a duration such as \"48h\"");
+        return problems;
+    }
+    return gatePointProblems(point);
+}
+/** The point wave `name`'s gate asks (#3836): the wave's own, else the spec's, else none. */
+export function opWavePointAt(spec, name) {
+    const wave = spec.waves.find((w) => w.name === name);
+    return opWavePointOf(wave?.point ?? spec.point);
+}
+export const OP_WAVE_HOOK_FAILURES = ["fail", "approve"];
+/**
+ * Every moment, in the order a wave reaches them. `after-gate` (#3821) runs
+ * once the gate decided, whatever it decided: approved, let through,
+ * waiting, or refused by a policy denial.
+ */
+export const OP_WAVE_HOOK_MOMENTS = ["before-plan", "after-plan", "after-gate", "before-apply", "after-apply"];
+export const OP_WAVE_APPLY_HOOKS_RUNNERS = ["chant", "apply"];
+export const OP_WAVES_DIGEST_OVER = ["all", "changing"];
+/** The default gate name pattern. */
+export const OP_WAVE_DEFAULT_GATE_NAME = "{gate}-wave-{k}";
+/** The gate wave `k` waits on (#3821): the spec's `gateName` pattern, by default `<gate>-wave-<k>`. */
+export function opWaveGateName(spec, k) {
+    return (spec.gateName ?? OP_WAVE_DEFAULT_GATE_NAME).replaceAll("{gate}", spec.gate ?? spec.name).replaceAll("{k}", String(k));
+}
+/** The command a resume job runs. */
+export function opWavesResumeCommand(spec) {
+    return ["chant", "run", "resume", "--op", spec.name];
+}
+/** The default apply command. */
+export const OP_WAVE_DEFAULT_APPLY = ["chant", "run", "{op}", "--env", "{target}"];
+/** Where the runner keeps a wave's decision; a wide wave's deciding job hands it to its share jobs. */
+export function opWaveRecordPath(spec, wave) {
+    return `.chant/op-waves/${spec.name}/wave-${wave}.json`;
+}
+const NAME = /^[a-z0-9][a-z0-9_-]*$/;
+/** Refuse a spec no job could run, naming what is wrong. */
+export function assertOpWavesSpec(spec) {
+    const where = `Op waves "${spec.name}"`;
+    if (!NAME.test(spec.name))
+        throw new Error(`${where}: the name must be lowercase letters, digits, "-" and "_"`);
+    if (!spec.op)
+        throw new Error(`${where} names no \`op\`. Name the Op a run runs when it names none.`);
+    if (spec.plan !== undefined && spec.planWave !== undefined) {
+        throw new Error(`${where} has both \`plan\` and \`planWave\`. A wave is planned one run at a time or all at once; give one.`);
+    }
+    if (spec.apply !== undefined && spec.applyWave !== undefined) {
+        throw new Error(`${where} has both \`apply\` and \`applyWave\`. A wave is applied one run at a time or all at once; give one.`);
+    }
+    if (spec.planWave !== undefined) {
+        assertArgv(where, "planWave", spec.planWave);
+        if (!spec.planWave.some((part) => part.includes("{plans}"))) {
+            throw new Error(`${where}: the \`planWave\` command never names {plans}, the file it writes each run's plan digest to.`);
+        }
+    }
+    else {
+        if (!Array.isArray(spec.plan) || spec.plan.length === 0) {
+            throw new Error(`${where} has no \`plan\` command. Each wave plans its runs to bind its gate to their plan digests; give \`plan\` or \`planWave\`.`);
+        }
+        assertArgv(where, "plan", spec.plan);
+        if (!spec.plan.some((part) => part.includes("{plan}"))) {
+            throw new Error(`${where}: the \`plan\` command never names {plan}, the file it writes the plan digest to.`);
+        }
+    }
+    if (spec.apply !== undefined)
+        assertArgv(where, "apply", spec.apply);
+    if (spec.applyWave !== undefined) {
+        assertArgv(where, "applyWave", spec.applyWave);
+        if (!spec.applyWave.some((part) => part.includes("{runs}"))) {
+            throw new Error(`${where}: the \`applyWave\` command never names {runs}, the file listing the approved runs it applies.`);
+        }
+    }
+    assertOpWaveHooks(where, spec.hooks);
+    if (spec.waves.length === 0)
+        throw new Error(`${where} has no waves.`);
+    if (spec.resume !== undefined && (typeof spec.resume.schedule !== "string" || spec.resume.schedule.trim().split(/\s+/).length !== 5)) {
+        throw new Error(`${where}: resume.schedule must be a five-field cron expression, such as "*/10 * * * *".`);
+    }
+    if (spec.approvals !== undefined) {
+        const a = spec.approvals;
+        if (a === null || typeof a !== "object" || Array.isArray(a))
+            throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false }.`);
+        for (const [key, value] of Object.entries(a)) {
+            if (key !== "spend")
+                throw new Error(`${where}: approvals.${key} is not a setting; the one there is approvals.spend.`);
+            if (typeof value !== "boolean")
+                throw new Error(`${where}: approvals.spend must be true or false.`);
+        }
+    }
+    if (spec.gateName !== undefined) {
+        if (typeof spec.gateName !== "string" || !spec.gateName.includes("{k}") || /\s/.test(spec.gateName)) {
+            throw new Error(`${where}: gateName must be a pattern with {k}, the wave's number, and no spaces, such as "${OP_WAVE_DEFAULT_GATE_NAME}" or "wave-{k}".`);
+        }
+        const left = spec.gateName.replaceAll("{gate}", "").replaceAll("{k}", "").match(/\{[^}]*\}/);
+        if (left)
+            throw new Error(`${where}: gateName names ${left[0]}; the pattern fills in {gate} and {k} only.`);
+    }
+    if (spec.digest !== undefined) {
+        const d = spec.digest;
+        if (d === null || typeof d !== "object" || Array.isArray(d))
+            throw new Error(`${where}: \`digest\` must be { "over"?: "all" | "changing" }.`);
+        for (const [key, value] of Object.entries(d)) {
+            if (key !== "over")
+                throw new Error(`${where}: digest.${key} is not a setting; the one there is digest.over.`);
+            if (!OP_WAVES_DIGEST_OVER.includes(value))
+                throw new Error(`${where}: digest.over is ${JSON.stringify(value)}; use "all" or "changing".`);
+        }
+    }
+    if (spec.override !== undefined) {
+        const o = spec.override;
+        if (o === null || typeof o !== "object" || Array.isArray(o))
+            throw new Error(`${where}: \`override\` must be { "overriders"?: "<file at base>" }.`);
+        for (const [key, value] of Object.entries(o)) {
+            if (key !== "overriders")
+                throw new Error(`${where}: override.${key} is not a setting; the one there is override.overriders.`);
+            if (typeof value !== "string" || value.trim() === "")
+                throw new Error(`${where}: override.overriders must be a path, such as ".chant/overriders".`);
+        }
+    }
+    if (spec.point !== undefined) {
+        const problems = opWavePointProblems(spec.point);
+        if (problems.length > 0)
+            throw new Error(`${where}: ${problems.join("; ")}.`);
+    }
+    if (spec.neverOverMcp !== undefined && typeof spec.neverOverMcp !== "boolean")
+        throw new Error(`${where}: neverOverMcp must be true or false.`);
+    if (spec.notify !== undefined) {
+        const problem = notifyConfigProblem(spec.notify, "notify");
+        if (problem)
+            throw new Error(`${where}: ${problem}`);
+    }
+    const names = new Set();
+    for (const wave of spec.waves) {
+        if (!NAME.test(wave.name)) {
+            throw new Error(`${where}: wave "${wave.name}" must be named with lowercase letters, digits, "-" and "_"`);
+        }
+        if (names.has(wave.name))
+            throw new Error(`${where} names wave "${wave.name}" twice.`);
+        names.add(wave.name);
+        if (wave.gate !== undefined && !OP_WAVE_GATE_POLICIES.includes(wave.gate)) {
+            throw new Error(`${where}: wave "${wave.name}" has gate "${wave.gate}"; use ${OP_WAVE_GATE_POLICIES.join(", ")}.`);
+        }
+        if (wave.approval !== undefined && !GATE_APPROVAL_SOURCES.includes(wave.approval)) {
+            throw new Error(`${where}: wave "${wave.name}" has approval "${wave.approval}"; use ${GATE_APPROVAL_SOURCES.join(", ")}.`);
+        }
+        assertOpWaveHooks(`${where}, wave "${wave.name}"`, wave.hooks);
+        if (wave.point !== undefined) {
+            const problems = opWavePointProblems(wave.point);
+            if (problems.length > 0)
+                throw new Error(`${where}: wave "${wave.name}": ${problems.join("; ")}.`);
+        }
+        if (wave.discover !== undefined && typeof wave.discover !== "boolean")
+            throw new Error(`${where}: wave "${wave.name}" has discover ${JSON.stringify(wave.discover)}; use true or false.`);
+        if (wave.rest !== undefined && typeof wave.rest !== "boolean")
+            throw new Error(`${where}: wave "${wave.name}" has rest ${JSON.stringify(wave.rest)}; use true or false.`);
+        if (wave.discover) {
+            if (spec.planWave === undefined)
+                throw new Error(`${where}: wave "${wave.name}" discovers its runs, which only \`planWave\` can report. Give planWave.`);
+            if ((wave.runs ?? []).length > 0)
+                throw new Error(`${where}: wave "${wave.name}" discovers its runs, so it lists none.`);
+        }
+        if (wave.rest) {
+            if (!wave.discover)
+                throw new Error(`${where}: wave "${wave.name}" has rest, which follows the waves planWave discovers; set discover too.`);
+            if (wave !== spec.waves[spec.waves.length - 1])
+                throw new Error(`${where}: wave "${wave.name}" has rest, which only the last wave can have.`);
+            if ((wave.shares ?? 1) > 1)
+                throw new Error(`${where}: wave "${wave.name}" has rest and shares; the waves after it run in its one job, so it cannot be split.`);
+        }
+        if (wave.discover) {
+            const shares = wave.shares ?? 1;
+            if (!Number.isInteger(shares) || shares < 1)
+                throw new Error(`${where}: wave "${wave.name}" has shares ${wave.shares}; use a whole number from 1.`);
+            continue;
+        }
+        if (!Array.isArray(wave.runs) || wave.runs.length === 0)
+            throw new Error(`${where}: wave "${wave.name}" has no runs.`);
+        const targets = new Set();
+        for (const run of wave.runs) {
+            if (!run.target)
+                throw new Error(`${where}: wave "${wave.name}" has a run with no target.`);
+            if (targets.has(run.target))
+                throw new Error(`${where}: wave "${wave.name}" names target "${run.target}" twice.`);
+            targets.add(run.target);
+        }
+        const shares = wave.shares ?? 1;
+        if (!Number.isInteger(shares) || shares < 1) {
+            throw new Error(`${where}: wave "${wave.name}" has shares ${wave.shares}; use a whole number from 1.`);
+        }
+        if (shares > wave.runs.length) {
+            throw new Error(`${where}: wave "${wave.name}" has ${shares} shares for ${wave.runs.length} runs, so a share would apply nothing.`);
+        }
+    }
+}
+function assertArgv(where, field, argv) {
+    if (!Array.isArray(argv) || argv.length === 0 || !argv.every((part) => typeof part === "string") || argv[0] === "") {
+        throw new Error(`${where}: \`${field}\` must be a command as argv, a non-empty array of strings.`);
+    }
+}
+/** Refuse hooks no runner could run, naming what is wrong (#3762). */
+export function assertOpWaveHooks(where, hooks) {
+    if (hooks === undefined)
+        return;
+    if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)) {
+        throw new Error(`${where}: \`hooks\` must be { "before"?: { "plan"?, "apply"? }, "after"?: { "plan"?, "apply"? } }.`);
+    }
+    for (const [side, stages] of Object.entries(hooks)) {
+        if (side === "apply") {
+            const runBy = stages?.runBy;
+            if (stages === null || typeof stages !== "object" || Array.isArray(stages) || Object.keys(stages).some((key) => key !== "runBy")) {
+                throw new Error(`${where}: hooks.apply must be { "runBy"?: "chant" | "apply" }.`);
+            }
+            if (runBy !== undefined && !OP_WAVE_APPLY_HOOKS_RUNNERS.includes(runBy)) {
+                throw new Error(`${where}: hooks.apply.runBy is ${JSON.stringify(runBy)}; use ${OP_WAVE_APPLY_HOOKS_RUNNERS.map((r) => `"${r}"`).join(" or ")}.`);
+            }
+            continue;
+        }
+        if (side !== "before" && side !== "after")
+            throw new Error(`${where}: hooks.${side} is not a moment; use hooks.before or hooks.after (or hooks.apply.runBy).`);
+        if (stages === null || typeof stages !== "object" || Array.isArray(stages))
+            throw new Error(`${where}: hooks.${side} must be { "plan"?: [...], "apply"?: [...] }.`);
+        for (const [stage, list] of Object.entries(stages)) {
+            const at = `hooks.${side}.${stage}`;
+            if (stage === "gate" && side === "before")
+                throw new Error(`${where}: ${at} is not a moment; a hook runs after the gate (hooks.after.gate), or before the plan or the apply.`);
+            if (stage !== "plan" && stage !== "apply" && stage !== "gate")
+                throw new Error(`${where}: ${at} is not a stage; a hook runs before or after plan or apply, or after the gate.`);
+            if (!Array.isArray(list))
+                throw new Error(`${where}: ${at} must be a list of hooks.`);
+            list.forEach((hook, i) => {
+                const which = `${at}[${i}]${hook && typeof hook === "object" && typeof hook.name === "string" ? ` (${hook.name})` : ""}`;
+                if (!hook || typeof hook !== "object")
+                    throw new Error(`${where}: ${which} must be { "command": [...], "onFailure"?, "perRun"? }.`);
+                assertArgv(where, `${which}.command`, hook.command);
+                if (hook.onFailure !== undefined && !OP_WAVE_HOOK_FAILURES.includes(hook.onFailure)) {
+                    throw new Error(`${where}: ${which} has onFailure "${hook.onFailure}"; use ${OP_WAVE_HOOK_FAILURES.join(" or ")}.`);
+                }
+                if (hook.onFailure === "approve" && side === "after" && stage === "apply") {
+                    throw new Error(`${where}: ${which} has onFailure "approve", but after the apply there is nothing left to hold. Use "fail".`);
+                }
+                if (hook.onFailure === "approve" && stage === "gate") {
+                    throw new Error(`${where}: ${which} has onFailure "approve", but the gate has already decided when it runs. Use "fail", or hold the wave from an after.plan hook.`);
+                }
+                if (hook.perRun !== undefined && typeof hook.perRun !== "boolean")
+                    throw new Error(`${where}: ${which}.perRun must be true or false.`);
+                if (!hook.perRun) {
+                    const named = hook.command.find((part) => part.includes("{target}") || part.includes("{plan}"));
+                    if (named)
+                        throw new Error(`${where}: ${which} runs once for the wave, so it has no {target} or {plan} ("${named}"). Set "perRun": true, or read the runs from {runs}.`);
+                }
+                else if (side === "before" && stage === "plan" && hook.command.some((part) => part.includes("{plan}"))) {
+                    throw new Error(`${where}: ${which} runs before the plan, so it has no {plan} yet.`);
+                }
+            });
+        }
+    }
+}
+/** The hooks of each moment for wave `name`: the spec's, then the wave's own. */
+export function opWaveHooksAt(spec, name) {
+    const wave = spec.waves.find((w) => w.name === name);
+    const at = (hooks, moment) => {
+        const [side, stage] = moment.split("-");
+        return hooks?.[side]?.[stage] ?? [];
+    };
+    return Object.fromEntries(OP_WAVE_HOOK_MOMENTS.map((m) => [m, [...at(spec.hooks, m), ...at(wave?.hooks, m)]]));
+}
+/** Who runs wave `name`'s apply-stage hooks (#3804): the wave's `hooks.apply.runBy`, else the spec's, else `chant`. */
+export function opWaveApplyHooksRunBy(spec, name) {
+    const wave = spec.waves.find((w) => w.name === name);
+    return wave?.hooks?.apply?.runBy ?? spec.hooks?.apply?.runBy ?? "chant";
+}
+/**
+ * The runs share `share` (1-based) of `shares` applies: the wave's runs sorted
+ * by target, cut into contiguous slices whose sizes differ by at most one.
+ */
+export function opWaveShare(runs, share, shares) {
+    const sorted = [...runs].sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
+    const base = Math.floor(sorted.length / shares);
+    const extra = sorted.length % shares;
+    const start = (share - 1) * base + Math.min(share - 1, extra);
+    const size = base + (share <= extra ? 1 : 0);
+    return sorted.slice(start, start + size);
+}
+/**
+ * The jobs of an Op waves pipeline, in order. `specFile` is the spec's path
+ * from the job's working directory, which every command names.
+ */
+export function opWaveJobs(spec, specFile) {
+    assertOpWavesSpec(spec);
+    const jobs = [];
+    let previous = [];
+    spec.waves.forEach((wave, index) => {
+        const k = index + 1;
+        const command = ["chant", "run", "wave", "--spec", specFile, "--wave", String(k), ...(spec.base ? ["--base", spec.base] : [])];
+        const prefix = `wave-${k}-${wave.name}`;
+        const shares = wave.shares ?? 1;
+        if (shares === 1) {
+            jobs.push({ jobName: prefix, wave: k, waveName: wave.name, kind: "wave", needs: previous, command });
+            previous = [prefix];
+            return;
+        }
+        const record = opWaveRecordPath(spec, k);
+        const decide = `${prefix}-decide`;
+        jobs.push({ jobName: decide, wave: k, waveName: wave.name, kind: "decide", needs: previous, command: [...command, "--decide"], record });
+        const shareJobs = [];
+        for (let share = 1; share <= shares; share++) {
+            const jobName = `${prefix}-share-${share}`;
+            shareJobs.push(jobName);
+            jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", share, needs: [decide], command: [...command, "--share", String(share)], record });
+        }
+        previous = shareJobs;
+    });
+    return jobs;
+}
+/** The wave a job belongs to. */
+export function opWaveOf(spec, job) {
+    return spec.waves[job.wave - 1];
+}