@intentius/chant 0.124.93 → 0.124.95

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/dist/ci-comment-commands.d.ts +12 -1
  2. package/dist/ci-comment-commands.d.ts.map +1 -1
  3. package/dist/ci-comment-commands.js +29 -0
  4. package/dist/ci-note-commands.d.ts +1 -1
  5. package/dist/ci-note-commands.d.ts.map +1 -1
  6. package/dist/ci-note-commands.js +11 -1
  7. package/dist/ci-product.d.ts +19 -1
  8. package/dist/ci-product.d.ts.map +1 -1
  9. package/dist/ci-product.js +25 -8
  10. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  11. package/dist/cli/handlers/pr-comment.js +11 -4
  12. package/dist/cli/handlers/run-wave.js +17 -3
  13. package/dist/cli/main.d.ts.map +1 -1
  14. package/dist/cli/main.js +4 -1
  15. package/dist/components/product-pipeline.d.ts.map +1 -1
  16. package/dist/components/product-pipeline.js +4 -2
  17. package/dist/components/product-plan.d.ts +6 -0
  18. package/dist/components/product-plan.d.ts.map +1 -1
  19. package/dist/components/product-plan.js +9 -1
  20. package/dist/floor-table.data.d.ts.map +1 -1
  21. package/dist/floor-table.data.js +15 -6
  22. package/dist/gate-resume-run.d.ts +7 -0
  23. package/dist/gate-resume-run.d.ts.map +1 -1
  24. package/dist/gate-resume-run.js +42 -3
  25. package/dist/lexicon.d.ts +47 -1
  26. package/dist/lexicon.d.ts.map +1 -1
  27. package/dist/lifecycle/gate-applied.d.ts +18 -0
  28. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  29. package/dist/op/before-merge-decide.d.ts +39 -2
  30. package/dist/op/before-merge-decide.d.ts.map +1 -1
  31. package/dist/op/before-merge-decide.js +59 -0
  32. package/dist/op/gate-run-locator.d.ts +17 -0
  33. package/dist/op/gate-run-locator.d.ts.map +1 -1
  34. package/dist/op/index.d.ts +3 -1
  35. package/dist/op/index.d.ts.map +1 -1
  36. package/dist/op/index.js +2 -1
  37. package/dist/op/op-waves-names.d.ts +40 -0
  38. package/dist/op/op-waves-names.d.ts.map +1 -1
  39. package/dist/op/op-waves-names.js +79 -0
  40. package/dist/op/op-waves-remainder.d.ts +110 -0
  41. package/dist/op/op-waves-remainder.d.ts.map +1 -0
  42. package/dist/op/op-waves-remainder.js +120 -0
  43. package/dist/op/op-waves-render-spec.d.ts +63 -5
  44. package/dist/op/op-waves-render-spec.d.ts.map +1 -1
  45. package/dist/op/op-waves-render-spec.js +68 -10
  46. package/dist/op/op-waves-run.d.ts +27 -1
  47. package/dist/op/op-waves-run.d.ts.map +1 -1
  48. package/dist/op/op-waves-run.js +192 -4
  49. package/dist/op/op-waves-split-resume.d.ts +57 -0
  50. package/dist/op/op-waves-split-resume.d.ts.map +1 -0
  51. package/dist/op/op-waves-split-resume.js +94 -0
  52. package/dist/op/op-waves.d.ts +26 -1
  53. package/dist/op/op-waves.d.ts.map +1 -1
  54. package/dist/op/op-waves.js +11 -2
  55. package/dist/release-floors.d.ts +13 -1
  56. package/dist/release-floors.d.ts.map +1 -1
  57. package/dist/release-floors.js +13 -1
  58. package/dist/wave-runtime.mjs +360 -360
  59. package/package.json +1 -1
  60. package/src/ci-comment-commands.test.ts +147 -0
  61. package/src/ci-comment-commands.ts +29 -1
  62. package/src/ci-note-commands.ts +12 -2
  63. package/src/ci-product.ts +28 -8
  64. package/src/cli/handlers/pr-comment.ts +10 -4
  65. package/src/cli/handlers/run-wave.ts +16 -3
  66. package/src/cli/main.ts +4 -1
  67. package/src/components/product-pipeline.ts +4 -2
  68. package/src/components/product-plan.ts +9 -2
  69. package/src/floor-table.data.ts +15 -6
  70. package/src/gate-resume-run.ts +38 -3
  71. package/src/lexicon.ts +47 -1
  72. package/src/lifecycle/gate-applied.ts +16 -0
  73. package/src/op/before-merge-decide.ts +74 -2
  74. package/src/op/gate-run-locator.ts +14 -0
  75. package/src/op/index.ts +5 -0
  76. package/src/op/op-waves-names.ts +80 -0
  77. package/src/op/op-waves-remainder.test.ts +341 -0
  78. package/src/op/op-waves-remainder.ts +146 -0
  79. package/src/op/op-waves-render-spec.test.ts +106 -0
  80. package/src/op/op-waves-render-spec.ts +81 -10
  81. package/src/op/op-waves-run.ts +200 -5
  82. package/src/op/op-waves-split-resume.test.ts +148 -0
  83. package/src/op/op-waves-split-resume.ts +109 -0
  84. package/src/op/op-waves.ts +33 -2
  85. package/src/release-floors.ts +19 -1
@@ -27,6 +27,13 @@
27
27
  * jobs before the gate run again too; they must be safe to repeat (a wave
28
28
  * whose runs already applied plans nothing and applies nothing new).
29
29
  *
30
+ * A killed split apply (#5052): a split wave's gate job writes the applied
31
+ * line, and its applying job is the one killed. On GitLab its locator names
32
+ * the wave's applying and record jobs (`retry`), and each applying job's
33
+ * newest try that failed or was cancelled is retried, then the record job.
34
+ * On Forgejo it carries the run's dispatch inputs (`inputs`), and the
35
+ * dispatch sends them, so a before-merge run plans the same decided head.
36
+ *
30
37
  * Resuming approves nothing. The resumed job decides the gate again from the
31
38
  * ledger, so resuming a run whose approval does not count only makes it wait
32
39
  * again. {@link resumeGateRun} skips a run that is still going, that ended
@@ -77,6 +84,8 @@ export function gitlabEvidenceJobOf(job: string): string {
77
84
 
78
85
  /** The GitLab job statuses of a job that ran and ended; a `skipped` or `created` job GitLab runs again after a retry itself. */
79
86
  const GITLAB_FINISHED = new Set(["success", "failed", "canceled"]);
87
+ /** The statuses of a job that is not going and will not start by itself: finished, skipped, or waiting for a person. */
88
+ const GITLAB_ENDED = new Set([...GITLAB_FINISHED, "skipped", "manual"]);
80
89
 
81
90
  const trimSlash = (s: string): string => s.replace(/\/+$/, "");
82
91
 
@@ -131,6 +140,28 @@ export async function resumeGateRun(loc: GateRunLocator, opts: ResumeGateRunOpti
131
140
  if (loc.forge === "gitlab") {
132
141
  const call = client(loc.api, { "PRIVATE-TOKEN": opts.token }, fetchImpl);
133
142
  const project = `/projects/${encodeURIComponent(decodeURIComponent(loc.repo))}`;
143
+ // #5052: a split wave's applying jobs, by name in the same pipeline, and its record job after them.
144
+ if (loc.retry?.apply.length) {
145
+ const listed = await call("GET", `${project}/pipelines/${loc.run}/jobs?per_page=100`);
146
+ // The list leaves retried jobs out, so the job of a name is its newest try.
147
+ const jobs = Array.isArray(listed) ? listed.filter(isObject) : [];
148
+ const newest = (name: string) => jobs.find((j) => j.name === name);
149
+ const applying = loc.retry.apply.map((name) => ({ name, job: newest(name) }));
150
+ const going = applying.find((a) => a.job && !GITLAB_ENDED.has(String(a.job.status)));
151
+ if (going) return skip(`job ${String(going.job!.id)} (${going.name}) is ${String(going.job!.status)}, not finished`);
152
+ const stopped = applying.filter((a) => a.job && (a.job.status === "failed" || a.job.status === "canceled"));
153
+ if (stopped.length > 0) {
154
+ const record = loc.retry.record ? newest(loc.retry.record) : undefined;
155
+ const after = record && GITLAB_FINISHED.has(String(record.status)) ? record : undefined;
156
+ const what = [...stopped.map((a) => `job ${String(a.job!.id)} (${a.name})`), ...(after ? [`its record job ${String(after.id)}`] : [])].join(" and ");
157
+ if (opts.dryRun) return wouldResume(`retry ${what}`);
158
+ for (const a of stopped) await call("POST", `${project}/jobs/${String(a.job!.id)}/retry`);
159
+ // It needs the applying jobs, so it waits for their new tries.
160
+ if (after) await call("POST", `${project}/jobs/${String(after.id)}/retry`);
161
+ return { status: "resumed", forge: "gitlab", how: `retried ${what}`, ...url };
162
+ }
163
+ // No applying job stopped: the gate job's own try says what is left (it succeeded, or stopped before them).
164
+ }
134
165
  const job = await call("GET", `${project}/jobs/${loc.job}`);
135
166
  if (!isObject(job)) throw new Error(`GET ${project}/jobs/${loc.job} returned no job`);
136
167
  const status = String(job.status);
@@ -172,16 +203,20 @@ export async function resumeGateRun(loc: GateRunLocator, opts: ResumeGateRunOpti
172
203
  const runs = isObject(listed) && Array.isArray(listed.workflow_runs) ? listed.workflow_runs : Array.isArray(listed) ? listed : [];
173
204
  // Forgejo reports `created` in whole seconds.
174
205
  const since = opts.since ? Math.floor(new Date(opts.since).getTime() / 1000) * 1000 : undefined;
206
+ // #5052: a run that a resume with inputs started is a dispatch; a push or a comment of the branch since is not one.
207
+ const inputs = loc.inputs && Object.keys(loc.inputs).length > 0 ? loc.inputs : undefined;
175
208
  const later = runs.find(
176
209
  (r) =>
177
210
  isObject(r) && Number(r.id) > Number(loc.run) &&
178
211
  (r.prettyref === undefined || r.prettyref === loc.ref) &&
212
+ (!inputs || r.event === undefined || r.event === "workflow_dispatch") &&
179
213
  (since === undefined || (typeof r.created === "string" && new Date(r.created).getTime() >= since)),
180
214
  );
181
215
  if (isObject(later)) return skip(`run ${String(later.id)} of ${loc.workflow} started after the approval`);
182
- if (opts.dryRun) return wouldResume(`dispatch ${loc.workflow} on ${loc.ref}`);
183
- await call("POST", `${repo}/actions/workflows/${encodeURIComponent(loc.workflow!)}/dispatches`, { ref: loc.ref });
184
- return { status: "resumed", forge: "forgejo", how: `dispatched ${loc.workflow} on ${loc.ref}`, ...url };
216
+ const with_ = inputs ? ` with ${Object.entries(inputs).map(([k, v]) => `${k}=${v}`).join(", ")}` : "";
217
+ if (opts.dryRun) return wouldResume(`dispatch ${loc.workflow} on ${loc.ref}${with_}`);
218
+ await call("POST", `${repo}/actions/workflows/${encodeURIComponent(loc.workflow!)}/dispatches`, { ref: loc.ref, ...(inputs ? { inputs } : {}) });
219
+ return { status: "resumed", forge: "forgejo", how: `dispatched ${loc.workflow} on ${loc.ref}${with_}`, ...url };
185
220
  }
186
221
 
187
222
  /**
package/src/lexicon.ts CHANGED
@@ -1182,7 +1182,11 @@ export interface OpWavesPipelineOptions
1182
1182
  * the commit in `CHANT_WAVES_SPEC_AT`. The spec handed to the generator
1183
1183
  * is the pipeline's shape (its waves, shares, job groups, `cloud`,
1184
1184
  * runners, environments and `holds.policy`); the rendered one sets the
1185
- * rules. Absent: the jobs read the committed spec as before.
1185
+ * rules. Absent: the jobs read the committed spec as before. With
1186
+ * `runsAtHead: true` (#5046) the jobs also carry
1187
+ * `CHANT_WAVES_SPEC_RUNS=head`: the job's own spec, its runs, is rendered
1188
+ * at the applied commit with `CHANT_WAVES_SPEC_BASE` set to the base, and
1189
+ * the rules still come from the render at base.
1186
1190
  */
1187
1191
  renderSpec?: import("./op/op-waves-render-spec").OpWavesRenderSpec;
1188
1192
  /**
@@ -1288,6 +1292,48 @@ export interface OpWavesPipelineOptions
1288
1292
  * the same workflow or pipeline, so this goes with `runIf`. Absent: none.
1289
1293
  */
1290
1294
  firstWaveNeeds?: string[];
1295
+ /**
1296
+ * GitHub and Forgejo (#5044): the job's token in the command step of the
1297
+ * jobs that run only the default branch's code (a push's wave, deciding,
1298
+ * share and job group jobs; a split wave's gate and record jobs), as
1299
+ * `GITHUB_TOKEN`, so the spec's `respond` posts a refused wave's diff and
1300
+ * a failed apply's triage, and a product's hooks can read the forge. The
1301
+ * jobs ask for `permissions` beside chant's own, such as terragucci's
1302
+ * `pull-requests: write` and, with its review agent, `actions: read`.
1303
+ * A split wave's plan and applying jobs run the change's code and never
1304
+ * get it. GitLab refuses it: its jobs read `CHANT_FORGE_TOKEN`. Absent:
1305
+ * no wave job holds a token, as before.
1306
+ */
1307
+ commandToken?: import("./op/op-waves-names").OpWavesCommandToken;
1308
+ /**
1309
+ * GitLab (#5045): the `cache:` of each job that runs the wave's command
1310
+ * (the wave's own, deciding, share and job group jobs, the policy job, and
1311
+ * a split wave's plan and applying jobs), one entry or a list as GitLab
1312
+ * takes them, such as terragucci's Terragrunt sources and providers cache.
1313
+ * The gate and record jobs plan and apply nothing, so they take none.
1314
+ * GitHub and Forgejo refuse it: a wave's `setup` step does this there.
1315
+ * Absent: no cache, as before.
1316
+ */
1317
+ cache?: Record<string, unknown> | Array<Record<string, unknown>>;
1318
+ /**
1319
+ * The control job's group (#5053), so the control repo gets one send per
1320
+ * commit when a push's run and a resume's run both reach it: GitHub and
1321
+ * Forgejo `concurrency: { group, cancel-in-progress: false }`, GitLab
1322
+ * `resource_group`. `{commit}` in it stands for the commit the job tells
1323
+ * the control repo about (`${{ github.sha }}`, or a follow-on run's commit
1324
+ * input; GitLab `$CI_COMMIT_SHA` or `CHANT_WAVES_COMMIT`), such as
1325
+ * terragucci's `terragucci-control-${{ github.repository }}-{commit}`.
1326
+ * Needs `control` on the spec. Absent: no group, as before.
1327
+ */
1328
+ controlGroup?: string;
1329
+ /**
1330
+ * GitLab (#5053): the resume job's `resource_group`, such as terragucci's
1331
+ * `terragucci-resume`, so two resume pipelines that overlap do not both
1332
+ * retry the same waiting job. GitHub and Forgejo refuse it: their resume
1333
+ * workflow has its own group, `<spec>-resume`. Needs `resume` on the
1334
+ * spec. Absent: no resource group, as before.
1335
+ */
1336
+ resumeGroup?: string;
1291
1337
  }
1292
1338
 
1293
1339
  /** A run step a product adds to a generated job (#4791): its name, and its shell lines in order. */
@@ -53,6 +53,22 @@ export interface AppliedGateRecord {
53
53
  * hook again under it; any other job reads it as spent.
54
54
  */
55
55
  rerun?: { head: string };
56
+ /**
57
+ * Under `approvals.remainder` (#5047): each change the approved plans
58
+ * make, a run's resource and its digest, sorted. A wave run again at
59
+ * `commit` whose plans make only some of them applies those under this
60
+ * line's approval while no finished line says the apply applied.
61
+ */
62
+ changes?: AppliedGateChange[];
63
+ /** With `changes` (#5047): the digest members that are no run (the wave's cost), as the approved set held them. */
64
+ extras?: { member: string; planDigest: string }[];
65
+ }
66
+
67
+ /** One change an approved plan makes (#5047): a run's resource, by the engine's address, and its digest. */
68
+ export interface AppliedGateChange {
69
+ target: string;
70
+ address: string;
71
+ digest: string;
56
72
  }
57
73
 
58
74
  /**
@@ -84,8 +84,15 @@ export interface DecideBeforeMergeInput {
84
84
  /** Git in the job's checkout of the default branch. */
85
85
  git: ReachRun;
86
86
  cwd?: string;
87
- /** Take the locks of what the change reaches at stage apply, for `by`; a refusal is the reply. Absent: the pipeline has no reach line, so nothing is locked. */
88
- lock?(pr: number, head: string, base: string, by: string): Promise<{ ok: true; targets: string[] } | { ok: false; text: string }>;
87
+ /**
88
+ * Take the locks of what the change reaches at stage apply, for `by`; a
89
+ * refusal is the reply, worded for an apply, or for `/<product> lock` when
90
+ * `asked` is `lock` (#5061). Absent: the pipeline has no reach line, so
91
+ * nothing is locked.
92
+ */
93
+ lock?(pr: number, head: string, base: string, by: string, asked?: "apply" | "lock"): Promise<{ ok: true; targets: string[] } | { ok: false; text: string }>;
94
+ /** With `lock` (#5061): release every lock pull request `pr` holds in the reach line's lock file, answering the targets released. Not read by the apply's decision. */
95
+ unlock?(pr: number): Promise<string[]>;
89
96
  /** Write the decision on chant/lifecycle. */
90
97
  record(d: BeforeMergeDecision): Promise<BeforeMergeRecord>;
91
98
  /** Write the head's wave stop, or clear it (null). */
@@ -190,3 +197,68 @@ export async function decideWavesBeforeMerge(i: DecideBeforeMergeInput): Promise
190
197
  const link = started.url ? ` (${started.url})` : "";
191
198
  return { kind: "ran", text: `started the waves of ${i.op}${link} on ${at}'s head ${short(head)}${through} for ${i.user}${locks}; each wave's gate decides, and the run says when the head applied`, ...(started.url ? { url: started.url } : {}) };
192
199
  }
200
+
201
+ /** What {@link decideLocksBeforeMerge} takes (#5061): the comment, and the lock and unlock of the reach line. */
202
+ export interface LocksBeforeMergeInput {
203
+ forge: ForgeKind;
204
+ pr: PullRequestDetail;
205
+ user: string;
206
+ /** The default branch. */
207
+ base: string;
208
+ kind: "lock" | "unlock";
209
+ words: CiProductWords;
210
+ git: ReachRun;
211
+ cwd?: string;
212
+ lock: NonNullable<DecideBeforeMergeInput["lock"]>;
213
+ unlock: NonNullable<DecideBeforeMergeInput["unlock"]>;
214
+ }
215
+
216
+ /**
217
+ * `/<product> lock` and `/<product> unlock` on a pull request whose waves
218
+ * run before merge with the product plan's reach line and no plan locks
219
+ * (#5061), moved from terragucci's own comment job. `lock` takes the locks
220
+ * of what the reach line prints at stage apply, as an apply would, without
221
+ * applying; `unlock` releases every lock the pull request holds. The reach
222
+ * line runs in the job's checkout of the default branch, so none of the
223
+ * change's code runs.
224
+ */
225
+ export async function decideLocksBeforeMerge(i: LocksBeforeMergeInput): Promise<{ kind: "reply"; text: string } | { kind: "fail"; reason: string }> {
226
+ const t = commentTerms(i.forge);
227
+ const at = t.at(i.pr.number);
228
+ const typed = (kind: "lock" | "unlock") => `/${i.words.product} ${Object.entries(i.words.commands).find(([, c]) => c === kind)?.[0] ?? kind}`;
229
+ const reply = (text: string) => ({ kind: "reply" as const, text });
230
+ const fail = (reason: string) => ({ kind: "fail" as const, reason });
231
+ const list = (xs: readonly string[]) => xs.map((x) => `\`${x}\``).join(", ");
232
+
233
+ if (!i.pr.sameRepo) return reply(forkReply(i.words, i.forge));
234
+ if (i.kind === "unlock") {
235
+ let released: string[];
236
+ try {
237
+ released = await i.unlock(i.pr.number);
238
+ } catch (e) {
239
+ return fail(`could not release the locks of ${at} (${message(e)})`);
240
+ }
241
+ return reply(released.length > 0 ? `released ${list(released)}, which ${at} held, for ${i.user}` : `${at} holds no lock, so there is nothing to unlock`);
242
+ }
243
+ if (i.pr.state !== "open") return reply(`${at} is not open, so it takes no lock`);
244
+ if (i.pr.base !== undefined && i.pr.base !== i.base) return reply(`${at} targets ${i.pr.base}, not the default branch ${i.base}, so it takes no lock`);
245
+ const head = i.pr.headSha;
246
+ if (!head || !SHA.test(head)) return fail(`${at} names no head commit`);
247
+ if (!BRANCH.test(i.base) || i.base.split("/").some((s) => s === ".." || s === "")) return fail(`the default branch ${JSON.stringify(i.base)} is not a branch name this job passes on`);
248
+ // The default branch's commit the change is measured from; the reach line fetches the head itself.
249
+ const baseRef = `refs/remotes/origin/${i.base}`;
250
+ const run = (args: string[]) => i.git(["git", ...args], { ...(i.cwd ? { cwd: i.cwd } : {}) });
251
+ const fetched = run(["fetch", "-q", "--no-tags", "origin", `+refs/heads/${i.base}:${baseRef}`]);
252
+ if (fetched.status !== 0) return fail(`could not fetch ${i.base} (${fetched.stderr.trim() || `git exited ${fetched.status}`})`);
253
+ const baseSha = run(["rev-parse", baseRef]).stdout.trim();
254
+ if (!SHA.test(baseSha)) return fail(`could not read the commit of ${i.base}`);
255
+ let l;
256
+ try {
257
+ l = await i.lock(i.pr.number, head, baseSha, i.user, "lock");
258
+ } catch (e) {
259
+ return fail(`could not take the locks of ${at} (${message(e)})`);
260
+ }
261
+ if (!l.ok) return reply(l.text);
262
+ if (l.targets.length === 0) return reply(`${at} reaches nothing at ${short(head)}, so it takes no lock`);
263
+ return reply(`locked ${list(l.targets)} for ${at} at ${short(head)} for ${i.user}, and nothing is ${i.words.verbs.apply[1]}; the locks hold until it merges or closes, or \`${typed("unlock")}\` releases them`);
264
+ }
@@ -28,6 +28,20 @@ export interface GateRunLocator {
28
28
  workflow?: string;
29
29
  /** Forgejo: the branch a dispatch runs on. */
30
30
  ref?: string;
31
+ /**
32
+ * GitLab (#5052): the jobs of the same pipeline a resume retries, by name,
33
+ * in place of `job`: a split wave's applying jobs, each retried when its
34
+ * newest try failed or was cancelled, and its record job, retried after
35
+ * them when it ran. The gate job that writes the applied line knows their
36
+ * names, not their ids.
37
+ */
38
+ retry?: { apply: string[]; record?: string };
39
+ /**
40
+ * Forgejo (#5052): the `workflow_dispatch` inputs a resume dispatches
41
+ * with, so a before-merge run or a follow-on is started again for the
42
+ * same decided head or commit instead of the branch's head.
43
+ */
44
+ inputs?: Record<string, string>;
31
45
  /** The run's page, for a person. */
32
46
  url?: string;
33
47
  }
package/src/op/index.ts CHANGED
@@ -143,13 +143,18 @@ export { notifyOpWave, opWaveNotifyFields } from "./op-waves-notify";
143
143
  export {
144
144
  OP_WAVES_RENDER_SPEC_FLAG,
145
145
  OP_WAVES_SPEC_AT_ENV,
146
+ OP_WAVES_SPEC_BASE_ENV,
146
147
  OP_WAVES_SPEC_COMMAND_ENV,
147
148
  OP_WAVES_SPEC_FILE_ENV,
149
+ OP_WAVES_SPEC_RUNS_ENV,
148
150
  RUNTIME_WAVES_SPEC_FLOOR,
151
+ RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR,
149
152
  opWavesRenderSpecEnv,
150
153
  opWavesRenderSpecProblems,
151
154
  } from "./op-waves-render-spec";
152
155
  export type { OpWavesRenderSpec } from "./op-waves-render-spec";
156
+ export { OP_WAVES_REMAINDER_FLOOR, opWaveApprovedChanges, opWaveCoverRemainder, opWaveRunCovered, opWaveStoppedApply, opWaveUnfinishedApply } from "./op-waves-remainder";
157
+ export type { AppliedGateChange, OpWaveCover, OpWaveRemainderMember } from "./op-waves-remainder";
153
158
  export { OP_WAVE_STAND_DOWN_FLOOR, gitOpWaveNewerCommit, newerCommitOnBranch, opWaveDefaultBranch, opWaveRunBranch, opWaveStandDownReason, tipAppliesTargets } from "./op-waves-stand-down";
154
159
  export type { OpWaveNewerCommit, OpWaveNewerCommitPort } from "./op-waves-stand-down";
155
160
  export { OP_WAVE_RELEASE_RECORD_FLOOR, opWaveReleaseNames, opWaveReleaseProblems, releaseOfCommit } from "./op-waves-release";
@@ -208,6 +208,86 @@ export function opWavesFirstWaveNeeds(given: readonly string[] | undefined, forg
208
208
  return [...given];
209
209
  }
210
210
 
211
+ /**
212
+ * The forge token a wave job's command step gets (#5044): with it, the
213
+ * jobs that run only the default branch's code (a push's wave, deciding,
214
+ * share and job group jobs; a split wave's gate and record jobs) hand their
215
+ * command step the job's token as `GITHUB_TOKEN`, so the spec's `respond`
216
+ * posts and a product's hooks can read the forge, and the job asks for
217
+ * `permissions` on top of chant's own. A split wave's plan and applying jobs
218
+ * run the change's code and never get it. GitHub and Forgejo only.
219
+ */
220
+ export interface OpWavesCommandToken {
221
+ /** GitHub's permission scopes the jobs ask for beside chant's own, such as `{ "pull-requests": "write", actions: "read" }`. `contents` and `id-token` are chant's. */
222
+ permissions?: Record<string, "read" | "write">;
223
+ }
224
+
225
+ /** The GitHub permission scopes a product may add with {@link OpWavesCommandToken}. `contents` and `id-token` stay chant's. */
226
+ const COMMAND_TOKEN_SCOPES = new Set(["actions", "attestations", "checks", "deployments", "discussions", "issues", "packages", "pages", "pull-requests", "repository-projects", "security-events", "statuses"]);
227
+
228
+ /**
229
+ * {@link OpWavesCommandToken}'s permissions, checked (#5044): each a scope
230
+ * GitHub knows that chant does not set itself, `read` or `write`. Undefined
231
+ * when there is no token to give. GitLab refuses it, since its jobs read
232
+ * `CHANT_FORGE_TOKEN`, a CI/CD variable.
233
+ */
234
+ export function opWavesCommandToken(token: OpWavesCommandToken | undefined, forge: "github" | "forgejo" | "gitlab"): Record<string, "read" | "write"> | undefined {
235
+ if (token === undefined) return undefined;
236
+ if (forge === "gitlab") throw new Error("commandToken gives a GitHub or Forgejo wave job its token; a GitLab job reads CHANT_FORGE_TOKEN, a CI/CD variable, so leave it out");
237
+ if (token === null || typeof token !== "object" || Array.isArray(token)) throw new Error("commandToken is { permissions }");
238
+ const permissions = token.permissions ?? {};
239
+ if (permissions === null || typeof permissions !== "object" || Array.isArray(permissions)) throw new Error("commandToken.permissions maps a permission scope to read or write");
240
+ for (const [scope, level] of Object.entries(permissions)) {
241
+ if (scope === "contents" || scope === "id-token") throw new Error(`commandToken.permissions names ${scope}, which chant sets on the wave jobs itself`);
242
+ if (!COMMAND_TOKEN_SCOPES.has(scope)) throw new Error(`commandToken.permissions names ${JSON.stringify(scope)}, which is not a GitHub permission scope`);
243
+ if (level !== "read" && level !== "write") throw new Error(`commandToken.permissions.${scope} is ${JSON.stringify(level)}; give read or write`);
244
+ }
245
+ return { ...permissions };
246
+ }
247
+
248
+ /**
249
+ * The control job's group a product names (#5053), checked, with `{commit}`
250
+ * put in as `commit`, the forge's expression of the commit the job tells the
251
+ * control repo about. Undefined when none. One line; a spec without
252
+ * `control` has no job to put it on.
253
+ */
254
+ export function opWavesControlGroup(group: string | undefined, hasControl: boolean, commit: string): string | undefined {
255
+ if (group === undefined) return undefined;
256
+ if (typeof group !== "string" || group.trim() === "" || /[\r\n]/.test(group)) throw new Error(`controlGroup ${JSON.stringify(group)} is one line naming the control job's group`);
257
+ if (!hasControl) throw new Error("controlGroup names the control job's group, and the spec has no control");
258
+ return group.split("{commit}").join(commit);
259
+ }
260
+
261
+ /**
262
+ * GitLab (#5053): the resume job's `resource_group` a product names, checked.
263
+ * Undefined when none. GitHub and Forgejo refuse it, since their resume
264
+ * workflow has its own group, `<spec>-resume`.
265
+ */
266
+ export function opWavesResumeGroup(group: string | undefined, hasResume: boolean, forge: "github" | "forgejo" | "gitlab"): string | undefined {
267
+ if (group === undefined) return undefined;
268
+ if (forge !== "gitlab") throw new Error("resumeGroup is the GitLab resume job's resource_group; the GitHub and Forgejo resume workflow has its own concurrency group, <spec>-resume");
269
+ if (typeof group !== "string" || group.trim() === "" || /[\r\n]/.test(group)) throw new Error(`resumeGroup ${JSON.stringify(group)} is one line naming the resume job's resource_group`);
270
+ if (!hasResume) throw new Error("resumeGroup names the resume job's resource_group, and the spec has no resume");
271
+ return group;
272
+ }
273
+
274
+ /**
275
+ * GitLab (#5045): the `cache:` a product gives the wave jobs that run the
276
+ * wave's command, one entry or a list of them as GitLab takes them, such as
277
+ * terragucci's `{ key: terragucci-terragrunt, paths: [.terragrunt-cache/] }`.
278
+ * Each entry is a mapping with `paths` or `key`. Undefined when none.
279
+ */
280
+ export function opWavesGitlabCache(cache: Record<string, unknown> | Array<Record<string, unknown>> | undefined): Record<string, unknown> | Array<Record<string, unknown>> | undefined {
281
+ if (cache === undefined) return undefined;
282
+ const entries = Array.isArray(cache) ? cache : [cache];
283
+ if (entries.length === 0) throw new Error("cache is a GitLab cache entry or a list of them; leave it out for none");
284
+ for (const entry of entries) {
285
+ if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new Error("cache holds GitLab cache entries, each a mapping such as { key, paths }");
286
+ if (entry.paths === undefined && entry.key === undefined) throw new Error("a cache entry names its paths or its key");
287
+ }
288
+ return cache;
289
+ }
290
+
211
291
  /** Refuse a product job of {@link opWavesFirstWaveNeeds} that is a job the generator writes (#5032). */
212
292
  export function assertFirstWaveNeedsOutside(needs: readonly string[], jobs: Iterable<string>): void {
213
293
  const mine = new Set(jobs);