@intentius/chant 0.116.0 → 0.118.0

package/src/op/op-waves.ts

@@ -27,6 +27,12 @@
  * the same digest a component fan-out's wave binds). 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`.
  */
 
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
@@ -42,6 +48,17 @@ export type OpWaveGatePolicy =
 
 export const OP_WAVE_GATE_POLICIES: readonly OpWaveGatePolicy[] = ["always", "on-destructive", "never"];
 
+/** Which approvals of a gate's digest count (#3684). See `./gate-review.ts`. */
+export type GateApprovalSource =
+  /** Any resolution on `chant/lifecycle` that names the digest. */
+  | "ledger"
+  /** As `ledger`, and the merged pull request's review of its head, by a writer other than its author. */
+  | "pr-review"
+  /** Only a resolution sealed by a key the signers file at base lists for its approver. */
+  | "sealed";
+
+export const GATE_APPROVAL_SOURCES: readonly GateApprovalSource[] = ["ledger", "pr-review", "sealed"];
+
 /** One Op run in a wave: an Op applied to one target (an environment, a database, a tenant). */
 export interface OpWaveRun {
   /** What the run applies to. Unique within its wave; it names the run in the set digest. */
@@ -60,6 +77,11 @@ export interface OpWave {
    * spec file at the base commit, never from the change being applied.
    */
   gate?: OpWaveGatePolicy;
+  /**
+   * Which approvals of the wave's digest count (#3684). Default `"ledger"`.
+   * Like `gate`, the runner reads it from the spec file at the base commit.
+   */
+  approval?: GateApprovalSource;
   /**
    * Split the wave into a deciding job and this many share jobs, each
    * applying a slice of the runs. Default 1: one job plans, decides and
@@ -103,6 +125,29 @@ export interface OpWavesSpec {
   /** Apply one run whose plan is at `{plan}`. Default `chant run {op} --env {target}`. */
   apply?: string[];
   waves: OpWave[];
+  /**
+   * A scheduled job that starts again a wave job whose approval has arrived
+   * (#3683): it runs `chant run resume --op <name>`, which re-runs the
+   * GitHub run, retries the GitLab job or dispatches the Forgejo workflow.
+   * It approves nothing. Absent, no such job is rendered and an approval is
+   * followed by `chant approve --resume` or a re-run by hand.
+   */
+  resume?: OpWavesResume;
+}
+
+/** The scheduled resume job of an Op waves pipeline (#3683). */
+export interface OpWavesResume {
+  /**
+   * Five-field cron, such as `"*\/10 * * * *"`. GitHub and Forgejo put it
+   * in the workflow; GitLab runs the job in a pipeline schedule you create,
+   * which sets the cron.
+   */
+  schedule: string;
+}
+
+/** The command a resume job runs. */
+export function opWavesResumeCommand(spec: Pick<OpWavesSpec, "name">): string[] {
+  return ["chant", "run", "resume", "--op", spec.name];
 }
 
 /** The default apply command. */
@@ -146,6 +191,9 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
     throw new Error(`${where}: the \`plan\` command never names {plan}, the file it writes the plan digest to.`);
   }
   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 * * * *".`);
+  }
   const names = new Set<string>();
   for (const wave of spec.waves) {
     if (!NAME.test(wave.name)) {
@@ -156,6 +204,9 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
     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(", ")}.`);
+    }
     if (wave.runs.length === 0) throw new Error(`${where}: wave "${wave.name}" has no runs.`);
     const targets = new Set<string>();
     for (const run of wave.runs) {