@intentius/chant 0.124.89 → 0.124.90

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 (163) hide show
  1. package/dist/ci-comment-commands.d.ts +18 -2
  2. package/dist/ci-comment-commands.d.ts.map +1 -1
  3. package/dist/ci-comment-commands.js +30 -2
  4. package/dist/ci-job-guard.d.ts +42 -45
  5. package/dist/ci-job-guard.d.ts.map +1 -1
  6. package/dist/ci-job-guard.js +206 -3
  7. package/dist/ci-note-commands.d.ts +41 -1
  8. package/dist/ci-note-commands.d.ts.map +1 -1
  9. package/dist/ci-note-commands.js +64 -5
  10. package/dist/ci-product.d.ts +41 -1
  11. package/dist/ci-product.d.ts.map +1 -1
  12. package/dist/ci-product.js +44 -7
  13. package/dist/cli/handlers/pr-comment.d.ts +13 -1
  14. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  15. package/dist/cli/handlers/pr-comment.js +90 -1
  16. package/dist/cli/handlers/pr-notes.d.ts.map +1 -1
  17. package/dist/cli/handlers/pr-notes.js +23 -1
  18. package/dist/cli/handlers/pr.js +16 -14
  19. package/dist/cli/handlers/run-wave.d.ts.map +1 -1
  20. package/dist/cli/handlers/run-wave.js +154 -4
  21. package/dist/cli/main.d.ts.map +1 -1
  22. package/dist/cli/main.js +17 -0
  23. package/dist/cli/parse-args.d.ts.map +1 -1
  24. package/dist/cli/parse-args.js +15 -0
  25. package/dist/cli/registry.d.ts +8 -1
  26. package/dist/cli/registry.d.ts.map +1 -1
  27. package/dist/components/pr-checks.d.ts +28 -1
  28. package/dist/components/pr-checks.d.ts.map +1 -1
  29. package/dist/components/pr-checks.js +35 -2
  30. package/dist/components/pr-pipeline.d.ts +3 -2
  31. package/dist/components/pr-pipeline.d.ts.map +1 -1
  32. package/dist/components/pr-pipeline.js +4 -2
  33. package/dist/components/product-pipeline.d.ts +54 -2
  34. package/dist/components/product-pipeline.d.ts.map +1 -1
  35. package/dist/components/product-pipeline.js +59 -5
  36. package/dist/components/product-plan.d.ts +13 -1
  37. package/dist/components/product-plan.d.ts.map +1 -1
  38. package/dist/components/product-plan.js +36 -10
  39. package/dist/floor-table.data.d.ts.map +1 -1
  40. package/dist/floor-table.data.js +32 -23
  41. package/dist/lexicon.d.ts +82 -4
  42. package/dist/lexicon.d.ts.map +1 -1
  43. package/dist/lifecycle/gate-applied.d.ts +9 -0
  44. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  45. package/dist/op/apply-status.d.ts +84 -0
  46. package/dist/op/apply-status.d.ts.map +1 -0
  47. package/dist/op/apply-status.js +106 -0
  48. package/dist/op/before-merge-decide.d.ts +102 -0
  49. package/dist/op/before-merge-decide.d.ts.map +1 -0
  50. package/dist/op/before-merge-decide.js +142 -0
  51. package/dist/op/before-merge-done.d.ts +56 -0
  52. package/dist/op/before-merge-done.d.ts.map +1 -0
  53. package/dist/op/before-merge-done.js +69 -0
  54. package/dist/op/before-merge-store.d.ts +20 -0
  55. package/dist/op/before-merge-store.d.ts.map +1 -0
  56. package/dist/op/before-merge-store.js +48 -0
  57. package/dist/op/before-merge.d.ts +150 -0
  58. package/dist/op/before-merge.d.ts.map +1 -0
  59. package/dist/op/before-merge.js +207 -0
  60. package/dist/op/follow-on-run.d.ts +117 -0
  61. package/dist/op/follow-on-run.d.ts.map +1 -0
  62. package/dist/op/follow-on-run.js +154 -0
  63. package/dist/op/follow-on-store.d.ts +17 -0
  64. package/dist/op/follow-on-store.d.ts.map +1 -0
  65. package/dist/op/follow-on-store.js +54 -0
  66. package/dist/op/gate.d.ts +6 -0
  67. package/dist/op/gate.d.ts.map +1 -1
  68. package/dist/op/gate.js +10 -1
  69. package/dist/op/index.d.ts +3 -1
  70. package/dist/op/index.d.ts.map +1 -1
  71. package/dist/op/index.js +1 -0
  72. package/dist/op/op-waves-after-plan.d.ts +13 -0
  73. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  74. package/dist/op/op-waves-evidence-jobs.d.ts +4 -1
  75. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  76. package/dist/op/op-waves-evidence-jobs.js +10 -2
  77. package/dist/op/op-waves-follow-on.d.ts +162 -0
  78. package/dist/op/op-waves-follow-on.d.ts.map +1 -0
  79. package/dist/op/op-waves-follow-on.js +355 -0
  80. package/dist/op/op-waves-run.d.ts +146 -6
  81. package/dist/op/op-waves-run.d.ts.map +1 -1
  82. package/dist/op/op-waves-run.js +871 -99
  83. package/dist/op/op-waves-split.d.ts +122 -0
  84. package/dist/op/op-waves-split.d.ts.map +1 -0
  85. package/dist/op/op-waves-split.js +166 -0
  86. package/dist/op/op-waves.d.ts +20 -0
  87. package/dist/op/op-waves.d.ts.map +1 -1
  88. package/dist/op/op-waves.js +15 -1
  89. package/dist/op/schedule-overdue.d.ts +15 -1
  90. package/dist/op/schedule-overdue.d.ts.map +1 -1
  91. package/dist/op/schedule-overdue.js +18 -2
  92. package/dist/op/stage-hooks.d.ts +36 -1
  93. package/dist/op/stage-hooks.d.ts.map +1 -1
  94. package/dist/op/stage-hooks.js +17 -3
  95. package/dist/op/wave-stop.d.ts +4 -1
  96. package/dist/op/wave-stop.d.ts.map +1 -1
  97. package/dist/op/wave-stop.js +4 -2
  98. package/dist/pr-post.d.ts.map +1 -1
  99. package/dist/pr-post.js +2 -1
  100. package/dist/release-floors.d.ts +3 -1
  101. package/dist/release-floors.d.ts.map +1 -1
  102. package/dist/release-floors.js +21 -19
  103. package/dist/wave-blocked.d.ts +7 -1
  104. package/dist/wave-blocked.d.ts.map +1 -1
  105. package/dist/wave-blocked.js +7 -2
  106. package/dist/wave-runtime.mjs +364 -351
  107. package/package.json +1 -1
  108. package/src/ci-comment-commands.test.ts +63 -0
  109. package/src/ci-comment-commands.ts +43 -4
  110. package/src/ci-image.test.ts +1 -2
  111. package/src/ci-job-guard.before-merge.test.ts +148 -0
  112. package/src/ci-job-guard.follow-on-record.test.ts +137 -0
  113. package/src/ci-job-guard.follow-on.test.ts +144 -0
  114. package/src/ci-job-guard.ts +221 -3
  115. package/src/ci-note-commands.test.ts +76 -1
  116. package/src/ci-note-commands.ts +96 -7
  117. package/src/ci-product.ts +55 -7
  118. package/src/cli/handlers/pr-comment.ts +85 -2
  119. package/src/cli/handlers/pr-notes.ts +30 -6
  120. package/src/cli/handlers/pr.ts +14 -11
  121. package/src/cli/handlers/run-wave.ts +144 -4
  122. package/src/cli/main.ts +17 -0
  123. package/src/cli/parse-args.ts +11 -0
  124. package/src/cli/registry.ts +8 -1
  125. package/src/components/pr-checks.ts +55 -2
  126. package/src/components/pr-pipeline.ts +5 -3
  127. package/src/components/product-pipeline.apply-status.test.ts +50 -0
  128. package/src/components/product-pipeline.ts +113 -8
  129. package/src/components/product-plan.test.ts +23 -5
  130. package/src/components/product-plan.ts +43 -12
  131. package/src/floor-table.data.ts +32 -23
  132. package/src/lexicon.ts +78 -1
  133. package/src/lifecycle/gate-applied.ts +7 -0
  134. package/src/op/apply-status.test.ts +83 -0
  135. package/src/op/apply-status.ts +132 -0
  136. package/src/op/before-merge-decide.ts +190 -0
  137. package/src/op/before-merge-done.ts +99 -0
  138. package/src/op/before-merge-store.ts +44 -0
  139. package/src/op/before-merge.test.ts +201 -0
  140. package/src/op/before-merge.ts +266 -0
  141. package/src/op/follow-on-run.ts +206 -0
  142. package/src/op/follow-on-store.ts +54 -0
  143. package/src/op/gate.ts +16 -1
  144. package/src/op/index.ts +5 -0
  145. package/src/op/op-waves-after-plan.ts +13 -0
  146. package/src/op/op-waves-evidence-jobs.ts +11 -3
  147. package/src/op/op-waves-follow-on-record.test.ts +152 -0
  148. package/src/op/op-waves-follow-on.test.ts +247 -0
  149. package/src/op/op-waves-follow-on.ts +385 -0
  150. package/src/op/op-waves-render-spec.test.ts +1 -2
  151. package/src/op/op-waves-run.ts +971 -93
  152. package/src/op/op-waves-split-product.test.ts +288 -0
  153. package/src/op/op-waves-split-step.test.ts +298 -0
  154. package/src/op/op-waves-split.test.ts +196 -0
  155. package/src/op/op-waves-split.ts +189 -0
  156. package/src/op/op-waves.ts +28 -3
  157. package/src/op/schedule-overdue.test.ts +29 -1
  158. package/src/op/schedule-overdue.ts +27 -3
  159. package/src/op/stage-hooks.ts +52 -4
  160. package/src/op/wave-stop.ts +5 -3
  161. package/src/pr-post.ts +2 -1
  162. package/src/release-floors.ts +22 -19
  163. package/src/wave-blocked.ts +9 -4
@@ -32,6 +32,10 @@
32
32
  * the reply says so.
33
33
  * - with `noPlanFlags` (#4979), a plan comment with flags the product
34
34
  * plan's re-plan cannot take, with the reason.
35
+ * - with `wavesBeforeMerge` (#4984), `/<product> apply [wave-<n>]` on an
36
+ * open pull request: the decision before merge
37
+ * (./op/before-merge-decide.ts) records the head on `chant/lifecycle`
38
+ * and dispatches the waves workflow on the default branch for it.
35
39
  *
36
40
  * Who asked comes first. On GitHub the commenter's permission is read from
37
41
  * the forge; Forgejo answers 403 when a job's token asks for another user's
@@ -49,6 +53,7 @@ import { type ApplyRerun, type ChantNoteJobs, type StartedRun } from "./ci-note-
49
53
  import { type CiProductWords, type ParsedProductComment } from "./ci-product-words.js";
50
54
  import { type ForgeFetch, type PrForge } from "./pr-forge.js";
51
55
  import type { ForgeReads } from "./pr-forge-reads.js";
56
+ import type { DecideBeforeMergeInput, WavesBeforeMergeJobs } from "./op/before-merge-decide.js";
52
57
  /** The comment job's name in a generated workflow (#4946). */
53
58
  export declare const PR_COMMENT_JOB = "comment";
54
59
  /** The variable the comment job reads the pipeline's jobs from, as JSON ({@link CommentJobs}), written by the generator (#4946). */
@@ -88,7 +93,16 @@ export interface CommentJobs extends Omit<ChantNoteJobs, "members"> {
88
93
  op: string;
89
94
  count: number;
90
95
  };
96
+ /**
97
+ * The waves before merge (#4984), with `waves`: `/<product> apply
98
+ * [wave-<n>]` on an open pull request is this job's. It decides
99
+ * (./op/before-merge-decide.ts), records the decided head on
100
+ * `chant/lifecycle`, and dispatches the waves workflow for it.
101
+ */
102
+ wavesBeforeMerge?: WavesBeforeMergeJobs;
91
103
  }
104
+ /** What the decision before merge reads and writes with (#4984), the comment job's handler's. */
105
+ export type CommentBeforeMerge = Pick<DecideBeforeMergeInput, "requires" | "statuses" | "git" | "cwd" | "lock" | "record" | "stop" | "now">;
92
106
  /** Writes a wave stop for op `op` at `sha` on `chant/lifecycle`, or clears it (#4979). */
93
107
  export type CommentWaveStops = (op: string, sha: string, stop: {
94
108
  through: number;
@@ -106,8 +120,8 @@ export declare const RERUN_APPLY_JOBS: RegExp;
106
120
  export interface CommentRuns {
107
121
  /** GitHub: `POST /repos/{repo}/actions/runs/{run}/rerun-failed-jobs`. */
108
122
  rerunFailed(run: number): Promise<StartedRun>;
109
- /** Forgejo: `POST /repos/{repo}/actions/workflows/{workflow}/dispatches` on `ref`. */
110
- dispatch(workflow: string, ref: string): Promise<StartedRun>;
123
+ /** Forgejo (and before merge, #4984, both): `POST /repos/{repo}/actions/workflows/{workflow}/dispatches` on `ref`, with `inputs`. */
124
+ dispatch(workflow: string, ref: string, inputs?: Record<string, string>): Promise<StartedRun>;
111
125
  }
112
126
  /** The writes for a GitHub or Forgejo API root, repository and token. */
113
127
  export declare function commentRuns(opts: {
@@ -139,6 +153,8 @@ export interface AnswerCommentOptions {
139
153
  stops?: CommentWaveStops;
140
154
  /** The time a stop is written at. Default now. */
141
155
  now?: () => string;
156
+ /** With `jobs.wavesBeforeMerge` (#4984): what the decision reads and writes with. Absent: an open pull request's apply is refused, as before. */
157
+ beforeMerge?: CommentBeforeMerge;
142
158
  }
143
159
  /** What the comment job did. */
144
160
  export interface CommentOutcome {
@@ -1 +1 @@
1
- {"version":3,"file":"ci-comment-commands.d.ts","sourceRoot":"","sources":["../src/ci-comment-commands.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"ci-comment-commands.d.ts","sourceRoot":"","sources":["../src/ci-comment-commands.ts"],"names":[],"mappings":"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"}
@@ -32,6 +32,10 @@
32
32
  * the reply says so.
33
33
  * - with `noPlanFlags` (#4979), a plan comment with flags the product
34
34
  * plan's re-plan cannot take, with the reason.
35
+ * - with `wavesBeforeMerge` (#4984), `/<product> apply [wave-<n>]` on an
36
+ * open pull request: the decision before merge
37
+ * (./op/before-merge-decide.ts) records the head on `chant/lifecycle`
38
+ * and dispatches the waves workflow on the default branch for it.
35
39
  *
36
40
  * Who asked comes first. On GitHub the commenter's permission is read from
37
41
  * the forge; Forgejo answers 403 when a job's token asks for another user's
@@ -73,7 +77,7 @@ export function commentRuns(opts) {
73
77
  };
74
78
  return {
75
79
  rerunFailed: (run) => post(`/actions/runs/${run}/rerun-failed-jobs`, {}),
76
- dispatch: (workflow, ref) => post(`/actions/workflows/${encodeURIComponent(workflow)}/dispatches`, { ref }),
80
+ dispatch: (workflow, ref, inputs) => post(`/actions/workflows/${encodeURIComponent(workflow)}/dispatches`, { ref, ...(inputs ? { inputs } : {}) }),
77
81
  };
78
82
  }
79
83
  /** Permissions on GitHub that may ask for a command: the same as may push. */
@@ -202,7 +206,7 @@ export async function answerProductComment(o) {
202
206
  break;
203
207
  }
204
208
  // An apply: the apply before merge answers an open pull request; this job a merged one, with applyOnMerge.
205
- if (!o.jobs.applyBeforeMerge && !o.jobs.applyOnMerge)
209
+ if (!o.jobs.applyBeforeMerge && !o.jobs.applyOnMerge && !o.jobs.wavesBeforeMerge)
206
210
  return reply(notRunReply(o.words, "apply", o.forge));
207
211
  let pr;
208
212
  try {
@@ -218,6 +222,30 @@ export async function answerProductComment(o) {
218
222
  if (pr.state === "open") {
219
223
  if (o.jobs.applyBeforeMerge)
220
224
  return silent("the apply before merge answers this comment", command);
225
+ // #4984: the waves before merge: decide, record the head and dispatch the waves workflow for it.
226
+ const bm = o.jobs.wavesBeforeMerge;
227
+ if (bm && o.jobs.waves && o.beforeMerge) {
228
+ const workflow = bm.workflow;
229
+ if (!workflow)
230
+ return broke("the waves before merge name no workflow to dispatch", command);
231
+ const { decideWavesBeforeMerge } = await import("./op/before-merge-decide.js");
232
+ const done = await decideWavesBeforeMerge({
233
+ ...o.beforeMerge,
234
+ forge: o.forge,
235
+ pr,
236
+ user,
237
+ base: o.base,
238
+ ...(parsed.wave !== undefined ? { wave: parsed.wave } : {}),
239
+ op: o.jobs.waves.op,
240
+ count: o.jobs.waves.count,
241
+ jobs: bm,
242
+ words: o.words,
243
+ start: (r) => o.runs.dispatch(workflow, o.base, { pr: String(r.pr), head: r.head, digest: r.digest }),
244
+ });
245
+ if (done.kind === "fail")
246
+ return broke(done.reason, command);
247
+ return reply(done.text, done.kind === "ran", done.kind === "ran" ? done.url : undefined);
248
+ }
221
249
  return reply(`${at} is not merged: \`/${o.words.product} ${typedApply(o.words)}\` runs the ${verb[0]} of a merged ${t.request} again, from the default branch, and never ${verb[0]}s a ${t.request}'s branch`);
222
250
  }
223
251
  if (pr.state === "closed")
@@ -1,48 +1,6 @@
1
- /**
2
- * The apply-job guard (#4624): the first step of each op-wave job checks
3
- * that the job runs where the spec set it to run, and stops it otherwise,
4
- * before any token is traded and before the checkout.
5
- *
6
- * What the job is expected to see is written into the job when the pipeline
7
- * is rendered, as JSON in {@link JOB_GUARD_ENV}: the guard reads no file of
8
- * the commit it runs on. What it sees comes from the forge:
9
- *
10
- * forge environment GitHub: the `environment` claim of an OIDC token the
11
- * guard requests for its own audience
12
- * ({@link JOB_GUARD_AUDIENCE}), decodes and drops. GitHub
13
- * sets no variable with the job's environment, so a job
14
- * that may request no token is not checked for it.
15
- * GitLab: CI_ENVIRONMENT_NAME. Forgejo has no
16
- * environments: not checked.
17
- * ref GitHub and Forgejo: GITHUB_REF is refs/heads/<branch>
18
- * for one of the branches the waves apply from. GitLab:
19
- * CI_COMMIT_REF_NAME is one of them, and
20
- * CI_COMMIT_REF_PROTECTED is "true".
21
- * runner GitLab: CI_RUNNER_TAGS holds each of the job's tags.
22
- * GitHub and Forgejo expose no labels, only whether the
23
- * runner is self-hosted: when the job's labels include
24
- * `self-hosted`, the token's runner_environment claim,
25
- * else RUNNER_ENVIRONMENT, is `self-hosted`. Neither
26
- * set: not checked.
27
- *
28
- * The generated step runs {@link jobGuardLine}: `node -e` from `/`, as the
29
- * cloud trade does, so no file of the checkout is in reach and the guard
30
- * needs nothing installed. `chant ci check-job` (and so a product's bin,
31
- * `plywood ci check-job`, `terragucci ci check-job`) runs the same check
32
- * from the same variable, through {@link checkJob}, for a product that
33
- * renders its own jobs. The lines name the product from its words.
34
- *
35
- * A refusal exits chant's `misplaced` (9), as does a variable the guard
36
- * cannot read. GitLab's op-wave jobs allow exit 1 as a failure the next wave
37
- * runs after, and 9 is outside that set, so a refused job fails and the
38
- * waves after it stop.
39
- *
40
- * The guard catches a hand edit, a dropped `environment:` or a mistyped
41
- * label. Someone who can edit the workflow can delete it too: the forge's
42
- * environment and runner settings and the cloud role's trust are what keep
43
- * a job out.
44
- */
45
1
  import { type CiRunner } from "./ci-jobs.js";
2
+ import { type BeforeMergeRecord, type BeforeMergeRun } from "./op/before-merge.js";
3
+ import { type FollowOnRecord, type FollowOnRun } from "./op/follow-on-run.js";
46
4
  /** The variable the generated step carries its expectation in. */
47
5
  export declare const JOB_GUARD_ENV = "CHANT_JOB_GUARD";
48
6
  /** The audience of the token the guard requests on GitHub, which no cloud role should trust. */
@@ -63,6 +21,12 @@ export interface JobGuardSpec {
63
21
  runnerTags?: string[];
64
22
  /** GitHub and Forgejo: the runner must be self-hosted. */
65
23
  selfHosted?: boolean;
24
+ /** The waves have a before-merge mode (#4984): a run that names a head runs only as op `op`'s recorded decision. */
25
+ beforeMerge?: {
26
+ op: string;
27
+ };
28
+ /** The job is one of the `rest` wave's (#4992), rendered as this wave: a follow-on run may name a later one. */
29
+ rest?: number;
66
30
  }
67
31
  /** What the job sees. Undefined: the forge did not say. */
68
32
  export interface JobSeen {
@@ -74,6 +38,18 @@ export interface JobSeen {
74
38
  refProtected?: string;
75
39
  runnerTags?: string[];
76
40
  runnerEnvironment?: string;
41
+ /** The decision the run names (#4984), from its variables. */
42
+ beforeMerge?: BeforeMergeRun;
43
+ /** The recorded decision for that head; null when there is none. Read only when the spec has a before-merge mode. */
44
+ beforeMergeRecord?: BeforeMergeRecord | null;
45
+ /** Why the decisions could not be read, when they could not. */
46
+ beforeMergeError?: string;
47
+ /** The follow-on variables the run names (#4992). */
48
+ followOn?: FollowOnRun;
49
+ /** The follow-on record of the run's chain (#4998); null when there is none. Read only for a follow-on the rest wave's job would admit. */
50
+ followOnRecord?: FollowOnRecord | null;
51
+ /** Why the follow-on records could not be read, when they could not. */
52
+ followOnError?: string;
77
53
  }
78
54
  export interface JobGuardResult {
79
55
  /** One line per value that does not match, naming the expected and found values. */
@@ -96,6 +72,12 @@ export interface JobGuardInput {
96
72
  runner?: CiRunner;
97
73
  /** GitHub: the job may request an OIDC token (`id-token: write`), so the guard can read its environment. */
98
74
  idToken?: boolean;
75
+ /** The waves' before-merge mode (#4984), with the op its decisions are recorded under. */
76
+ beforeMerge?: {
77
+ op: string;
78
+ };
79
+ /** The job is one of the `rest` wave's (#4992), whose number this is. */
80
+ rest?: number;
99
81
  }
100
82
  /**
101
83
  * The expectation a generator writes into a job. GitHub checks the forge
@@ -111,7 +93,22 @@ export declare function tokenClaims(token: string): Record<string, unknown>;
111
93
  /** Compare what the job sees with what the spec expects. */
112
94
  export declare function checkJob(expect: JobGuardSpec, seen: JobSeen): JobGuardResult;
113
95
  /** What the job sees, from the forge's variables, and on GitHub from its token's claims when the forge environment is to be checked. */
114
- export declare function jobSeen(expect: JobGuardSpec, env?: NodeJS.ProcessEnv, fetchFn?: typeof fetch): Promise<JobSeen>;
96
+ export declare function jobSeen(expect: JobGuardSpec, env?: NodeJS.ProcessEnv, fetchFn?: typeof fetch, readLifecycle?: LifecycleFileReader): Promise<JobSeen>;
97
+ /** Reads one file of `chant/lifecycle` as the remote has it; null when the branch has no such file (#4984). */
98
+ export type LifecycleFileReader = (forge: JobGuardForge, env: NodeJS.ProcessEnv, path: string) => string | null;
99
+ /** The repository's git URL and the job token's basic credentials, as the guard fetches with them (#4984). */
100
+ export declare function guardRemote(forge: JobGuardForge, env: NodeJS.ProcessEnv): {
101
+ url: string;
102
+ user: string;
103
+ token: string;
104
+ };
105
+ /**
106
+ * {@link LifecycleFileReader} through git: `chant/lifecycle` fetched at depth
107
+ * one into a directory of the guard's own, outside the checkout, with the
108
+ * token as a basic credential header, and the file shown from it. The
109
+ * `node -e` program does the same.
110
+ */
111
+ export declare const lifecycleFileByGit: LifecycleFileReader;
115
112
  /** The lines the guard prints, and whether the job may go on. */
116
113
  export declare function describeJobGuard(expect: JobGuardSpec, result: JobGuardResult): {
117
114
  ok: boolean;
@@ -1 +1 @@
1
- {"version":3,"file":"ci-job-guard.d.ts","sourceRoot":"","sources":["../src/ci-job-guard.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"ci-job-guard.d.ts","sourceRoot":"","sources":["../src/ci-job-guard.ts"],"names":[],"mappings":"AA0EA,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAwK,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACtP,OAAO,EAAqI,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE9M,kEAAkE;AAClE,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5D,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,aAAa,CAAC;IACrB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oHAAoH;IACpH,WAAW,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,gHAAgH;IAChH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,2DAA2D;AAC3D,MAAM,WAAW,OAAO;IACtB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,sEAAsE;IACtE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,qHAAqH;IACrH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC7C,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,2IAA2I;IAC3I,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oCAAoC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,aAAa,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,4GAA4G;IAC5G,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0FAA0F;IAC1F,WAAW,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAc/D;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAkBvE;AAID,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAY1E;AAED,+HAA+H;AAC/H,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOlE;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,GAAG,cAAc,CAkE5E;AAcD,wIAAwI;AACxI,wBAAsB,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,OAAO,GAAE,OAAO,KAAa,EAAE,aAAa,GAAE,mBAAwC,GAAG,OAAO,CAAC,OAAO,CAAC,CA6BlM;AAED,+GAA+G;AAC/G,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAEhH,8GAA8G;AAC9G,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAOtH;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,mBAWhC,CAAC;AA2BF,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAW5H;AAgED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,QAyCf,CAAC;AAEX,oGAAoG;AACpG,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,kIAAkI;AAClI,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAM/J"}
@@ -41,9 +41,41 @@
41
41
  * label. Someone who can edit the workflow can delete it too: the forge's
42
42
  * environment and runner settings and the cloud role's trust are what keep
43
43
  * a job out.
44
+ *
45
+ * Before merge (#4984): a waves workflow with a before-merge mode carries
46
+ * `beforeMerge: { op }`. A run started for an open pull request's head
47
+ * names it in `CHANT_BEFORE_MERGE_PR`, `CHANT_BEFORE_MERGE_HEAD` and
48
+ * `CHANT_BEFORE_MERGE_DIGEST` (./op/before-merge.ts), and still runs on one
49
+ * of the spec's branches. The guard then fetches `chant/lifecycle` into a
50
+ * directory of its own, with the job's token (GitHub and Forgejo
51
+ * `GITHUB_TOKEN`, GitLab `CI_JOB_TOKEN`), reads the decision for that head,
52
+ * and admits the run only when the pull request and the digest are the
53
+ * decision's and the decision's fields still give its digest. A job of a
54
+ * workflow without the mode refuses any run that names a head.
55
+ *
56
+ * A follow-on run (#4992, ./op/follow-on-run.ts): a job of a `rest` wave
57
+ * carries `rest: <its wave number>`. A run the rest wave's record job
58
+ * started names a later wave in `CHANT_WAVES_WAVE`, with the same decision
59
+ * (admitted as above, so a follow-on for another head or digest is refused)
60
+ * or, for a push, the pushed commit in `CHANT_WAVES_COMMIT`. The guard
61
+ * admits it only in a job of the rest wave and only for a wave after it; any
62
+ * other job refuses a run that names either variable.
63
+ *
64
+ * #4998: and only for the wave the newest record job of its chain started.
65
+ * The guard reads the follow-on records of the op (`_waves/<op>.follow-on.json`
66
+ * on `chant/lifecycle`, as it reads the decisions) and admits the run when
67
+ * the entry for its decided head, or a push's commit, names the run's wave
68
+ * and, before merge, the run's decision digest. A wave started by hand past
69
+ * the one the chain reached is refused, though each wave's gate would ask.
44
70
  */
71
+ import { spawnSync } from "node:child_process";
72
+ import { mkdtempSync } from "node:fs";
73
+ import { tmpdir } from "node:os";
74
+ import { join } from "node:path";
45
75
  import { isRunnerGroup } from "./ci-jobs.js";
46
76
  import { CHANT_EXIT } from "./exit-codes.js";
77
+ import { BEFORE_MERGE_DIGEST_ENV, BEFORE_MERGE_HEAD_ENV, BEFORE_MERGE_PR_ENV, beforeMergePath, beforeMergeProblems, beforeMergeRunFromEnv, isBeforeMergeRun, parseBeforeMerge } from "./op/before-merge.js";
78
+ import { followOnPath, followOnProblems, followOnRecordProblems, followOnRunFromEnv, OP_WAVES_COMMIT_ENV, OP_WAVES_WAVE_ENV, parseFollowOn } from "./op/follow-on-run.js";
47
79
  /** The variable the generated step carries its expectation in. */
48
80
  export const JOB_GUARD_ENV = "CHANT_JOB_GUARD";
49
81
  /** The audience of the token the guard requests on GitHub, which no cloud role should trust. */
@@ -63,6 +95,8 @@ export function jobGuardSpec(input) {
63
95
  branches: [...input.branches],
64
96
  ...(input.forge === "gitlab" && labels.length > 0 ? { runnerTags: labels } : {}),
65
97
  ...(input.forge !== "gitlab" && labels.includes("self-hosted") ? { selfHosted: true } : {}),
98
+ ...(input.beforeMerge ? { beforeMerge: { op: input.beforeMerge.op } } : {}),
99
+ ...(input.rest !== undefined ? { rest: input.rest } : {}),
66
100
  };
67
101
  }
68
102
  /** Read {@link JOB_GUARD_ENV}'s JSON, refusing one that is not a guard spec. */
@@ -89,6 +123,10 @@ export function parseJobGuardSpec(raw) {
89
123
  throw new Error(`${JOB_GUARD_ENV}.forgeEnvironment is not a name`);
90
124
  if (o.runnerTags !== undefined && (!Array.isArray(o.runnerTags) || o.runnerTags.some((t) => typeof t !== "string")))
91
125
  throw new Error(`${JOB_GUARD_ENV}.runnerTags is not a list of tags`);
126
+ if (o.beforeMerge !== undefined && (typeof o.beforeMerge !== "object" || o.beforeMerge === null || typeof o.beforeMerge.op !== "string"))
127
+ throw new Error(`${JOB_GUARD_ENV}.beforeMerge is { op }`);
128
+ if (o.rest !== undefined && (!Number.isInteger(o.rest) || o.rest < 1))
129
+ throw new Error(`${JOB_GUARD_ENV}.rest is the rest wave's number`);
92
130
  return o;
93
131
  }
94
132
  const shown = (v) => (v === undefined || v === null || v === "" ? "none" : v);
@@ -154,6 +192,38 @@ export function checkJob(expect, seen) {
154
192
  else
155
193
  out.checked.push(`ref ${seen.ref}`);
156
194
  }
195
+ // #4984: a run started for an open pull request's head runs only as the decision recorded for it.
196
+ const run = seen.beforeMerge;
197
+ if (run && isBeforeMergeRun(run)) {
198
+ if (!expect.beforeMerge)
199
+ out.problems.push(`before merge: the run names pull request ${run.pr ?? "none"}'s head ${run.head ?? "none"}, and this job applies only the pushes to its branches`);
200
+ else if (seen.beforeMergeError !== undefined)
201
+ out.problems.push(`before merge: the decisions on chant/lifecycle could not be read: ${seen.beforeMergeError}`);
202
+ else {
203
+ const problems = beforeMergeProblems(expect.beforeMerge.op, run, seen.beforeMergeRecord ?? undefined);
204
+ if (problems.length > 0)
205
+ out.problems.push(...problems);
206
+ else
207
+ out.checked.push(`before merge: pull request ${run.pr}'s decided head ${run.head.slice(0, 12)}`);
208
+ }
209
+ }
210
+ // #4992: a follow-on run of the rest wave, admitted in the rest wave's jobs alone and for a later wave.
211
+ const bmRun = run !== undefined && isBeforeMergeRun(run);
212
+ const follow = followOnProblems(expect.rest, seen.followOn ?? {}, bmRun);
213
+ out.problems.push(...follow.problems);
214
+ if (follow.checked) {
215
+ // #4998: and only for the wave the newest record job of its chain started.
216
+ const key = (bmRun ? run.head : seen.followOn?.commit) ?? "";
217
+ const rec = !expect.beforeMerge
218
+ ? ["follow-on: this job names no op whose follow-on records it reads, so it admits no follow-on"]
219
+ : seen.followOnError !== undefined
220
+ ? [`follow-on: the follow-on records on chant/lifecycle could not be read: ${seen.followOnError}`]
221
+ : followOnRecordProblems(expect.beforeMerge.op, seen.followOn.wave, key, bmRun ? (run.digest ?? "") : undefined, seen.followOnRecord);
222
+ if (rec.length > 0)
223
+ out.problems.push(...rec);
224
+ else
225
+ out.checked.push(follow.checked);
226
+ }
157
227
  if (expect.forge === "gitlab") {
158
228
  const want = expect.runnerTags ?? [];
159
229
  if (want.length > 0) {
@@ -192,7 +262,72 @@ async function githubClaims(env, fetchFn) {
192
262
  return tokenClaims(value);
193
263
  }
194
264
  /** What the job sees, from the forge's variables, and on GitHub from its token's claims when the forge environment is to be checked. */
195
- export async function jobSeen(expect, env = process.env, fetchFn = fetch) {
265
+ export async function jobSeen(expect, env = process.env, fetchFn = fetch, readLifecycle = lifecycleFileByGit) {
266
+ const seen = await forgeSeen(expect, env, fetchFn);
267
+ // #4992: the follow-on variables, whatever else the run names.
268
+ const follow = followOnRunFromEnv(env);
269
+ if (follow.wave !== undefined || follow.commit !== undefined)
270
+ seen.followOn = follow;
271
+ // #4984: the decision a run names, read only when the spec has a before-merge mode.
272
+ const run = beforeMergeRunFromEnv(env);
273
+ const bm = isBeforeMergeRun(run);
274
+ if (bm) {
275
+ seen.beforeMerge = run;
276
+ if (expect.beforeMerge && run.head) {
277
+ try {
278
+ const text = readLifecycle(expect.forge, env, beforeMergePath(expect.beforeMerge.op));
279
+ seen.beforeMergeRecord = parseBeforeMerge(text).heads[run.head] ?? null;
280
+ }
281
+ catch (e) {
282
+ seen.beforeMergeError = e.message;
283
+ }
284
+ }
285
+ }
286
+ // #4998: the record of the run's chain, read only for a follow-on the rest wave's job would admit.
287
+ const key = bm ? run.head : follow.commit;
288
+ if (expect.beforeMerge && key && followOnProblems(expect.rest, follow, bm).checked !== undefined) {
289
+ try {
290
+ seen.followOnRecord = parseFollowOn(readLifecycle(expect.forge, env, followOnPath(expect.beforeMerge.op))).chains[key] ?? null;
291
+ }
292
+ catch (e) {
293
+ seen.followOnError = e.message;
294
+ }
295
+ }
296
+ return seen;
297
+ }
298
+ /** The repository's git URL and the job token's basic credentials, as the guard fetches with them (#4984). */
299
+ export function guardRemote(forge, env) {
300
+ if (forge === "gitlab") {
301
+ if (!env.CI_SERVER_URL || !env.CI_PROJECT_PATH)
302
+ throw new Error("the job names no repository (no CI_SERVER_URL or CI_PROJECT_PATH)");
303
+ return { url: `${env.CI_SERVER_URL.replace(/\/+$/, "")}/${env.CI_PROJECT_PATH}.git`, user: "gitlab-ci-token", token: env.CI_JOB_TOKEN ?? "" };
304
+ }
305
+ if (!env.GITHUB_SERVER_URL || !env.GITHUB_REPOSITORY)
306
+ throw new Error("the job names no repository (no GITHUB_SERVER_URL or GITHUB_REPOSITORY)");
307
+ return { url: `${env.GITHUB_SERVER_URL.replace(/\/+$/, "")}/${env.GITHUB_REPOSITORY}.git`, user: "x-access-token", token: env.GITHUB_TOKEN ?? "" };
308
+ }
309
+ /**
310
+ * {@link LifecycleFileReader} through git: `chant/lifecycle` fetched at depth
311
+ * one into a directory of the guard's own, outside the checkout, with the
312
+ * token as a basic credential header, and the file shown from it. The
313
+ * `node -e` program does the same.
314
+ */
315
+ export const lifecycleFileByGit = (forge, env, path) => {
316
+ const remote = guardRemote(forge, env);
317
+ const dir = mkdtempSync(join(tmpdir(), "chant-guard-"));
318
+ const git = (args) => spawnSync("git", args, { cwd: dir, encoding: "utf-8", env: { ...env, GIT_TERMINAL_PROMPT: "0" } });
319
+ const init = git(["init", "-q"]);
320
+ if (init.status !== 0)
321
+ throw new Error(`git init failed: ${(init.stderr || "").trim()}`);
322
+ const auth = `Authorization: Basic ${Buffer.from(`${remote.user}:${remote.token}`).toString("base64")}`;
323
+ const fetched = git(["-c", `http.extraHeader=${auth}`, "fetch", "-q", "--depth=1", remote.url, "refs/heads/chant/lifecycle"]);
324
+ if (fetched.status !== 0)
325
+ throw new Error(`could not fetch chant/lifecycle: ${(fetched.stderr || "").trim().split("\n").pop()}`);
326
+ const shown = git(["show", `FETCH_HEAD:${path}`]);
327
+ return shown.status === 0 ? shown.stdout : null;
328
+ };
329
+ /** What the forge's own variables and token say, before the decision is read. */
330
+ async function forgeSeen(expect, env, fetchFn) {
196
331
  if (expect.forge === "gitlab") {
197
332
  return {
198
333
  forgeEnvironment: env.CI_ENVIRONMENT_NAME || null,
@@ -230,6 +365,66 @@ export function describeJobGuard(expect, result) {
230
365
  const skipped = result.skipped.length ? `; not checked: ${result.skipped.join(", ")}` : "";
231
366
  return { ok: true, out: [`${at}: ${result.checked.length ? result.checked.join(", ") : "nothing to check"}${skipped}`], err: [] };
232
367
  }
368
+ /**
369
+ * The before-merge part of the `node -e` program (#4984): the run's three
370
+ * variables, the read of `chant/lifecycle` as {@link lifecycleFileByGit}
371
+ * does it, the decision entry as {@link parseBeforeMerge} keeps it, and the
372
+ * lines of {@link beforeMergeProblems}, digest included. No single quote,
373
+ * since the program is one shell word in single quotes.
374
+ */
375
+ const BM_PATH = beforeMergePath("\u0000").split("\u0000");
376
+ /** Each apostrophe in the program's strings as `'`, since the whole program is one single-quoted shell word. */
377
+ const noQuote = (s) => s.replace(/'/g, "\\u0027");
378
+ const BEFORE_MERGE_JS = [
379
+ `const bmV=[${JSON.stringify(BEFORE_MERGE_PR_ENV)},${JSON.stringify(BEFORE_MERGE_HEAD_ENV)},${JSON.stringify(BEFORE_MERGE_DIGEST_ENV)}].map((k)=>String(E[k]||"").trim());`,
380
+ 'const bmRun={};if(bmV[0])bmRun.pr=bmV[0];if(bmV[1])bmRun.head=bmV[1];if(bmV[2])bmRun.digest=bmV[2];const bmOn=Boolean(bmV[0]||bmV[1]||bmV[2]);',
381
+ "const SHA=/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;",
382
+ String.raw `const bmRead=(file)=>{const cp=require("child_process"),fs=require("fs"),os=require("os"),pa=require("path");let url,user,tok;`,
383
+ String.raw `if(x.forge==="gitlab"){if(!E.CI_SERVER_URL||!E.CI_PROJECT_PATH)throw new Error("the job names no repository (no CI_SERVER_URL or CI_PROJECT_PATH)");url=E.CI_SERVER_URL.replace(/\/+$/,"")+"/"+E.CI_PROJECT_PATH+".git";user="gitlab-ci-token";tok=E.CI_JOB_TOKEN||""}`,
384
+ String.raw `else{if(!E.GITHUB_SERVER_URL||!E.GITHUB_REPOSITORY)throw new Error("the job names no repository (no GITHUB_SERVER_URL or GITHUB_REPOSITORY)");url=E.GITHUB_SERVER_URL.replace(/\/+$/,"")+"/"+E.GITHUB_REPOSITORY+".git";user="x-access-token";tok=E.GITHUB_TOKEN||""}`,
385
+ String.raw `const d=fs.mkdtempSync(pa.join(os.tmpdir(),"chant-guard-"));const g=(a)=>cp.spawnSync("git",a,{cwd:d,encoding:"utf-8",env:Object.assign({},E,{GIT_TERMINAL_PROMPT:"0"})});`,
386
+ String.raw `const i=g(["init","-q"]);if(i.status!==0)throw new Error("git init failed: "+String(i.stderr||"").trim());`,
387
+ String.raw `const f=g(["-c","http.extraHeader=Authorization: Basic "+Buffer.from(user+":"+tok).toString("base64"),"fetch","-q","--depth=1",url,"refs/heads/chant/lifecycle"]);`,
388
+ String.raw `if(f.status!==0)throw new Error("could not fetch chant/lifecycle: "+String(f.stderr||"").trim().split("\n").pop());`,
389
+ String.raw `const o=g(["show","FETCH_HEAD:"+file]);return o.status===0?o.stdout:null};`,
390
+ String.raw `const bmEntry=(t,h)=>{let v;try{v=JSON.parse(t===null?"null":t)}catch(e){return null}const hs=v&&typeof v==="object"&&v.version===1?v.heads:undefined;if(!hs||typeof hs!=="object"||!SHA.test(h))return null;const e=hs[h];`,
391
+ String.raw `if(!e||typeof e!=="object"||e.head!==h||!Number.isInteger(e.pr)||e.pr<1||typeof e.base!=="string"||!SHA.test(e.base)||typeof e.at!=="string"||typeof e.by!=="string"||typeof e.digest!=="string")return null;`,
392
+ String.raw `if(e.through!==undefined&&(!Number.isInteger(e.through)||e.through<1))return null;const r={pr:e.pr,head:h,base:e.base,at:e.at,by:e.by,digest:e.digest};if(e.through!==undefined)r.through=e.through;return r};`,
393
+ `const bmSeen=(s)=>{if(!bmOn)return s;s.beforeMerge=bmRun;if(!x.beforeMerge||!bmRun.head)return s;try{s.rec=bmEntry(bmRead(${JSON.stringify(BM_PATH[0])}+x.beforeMerge.op+${JSON.stringify(BM_PATH[1])}),bmRun.head)}catch(e){s.bmErr=e&&e.message?e.message:String(e)}return s};`,
394
+ 'const shownJ=(v)=>v===undefined||v===""?"none":JSON.stringify(v);',
395
+ String.raw `const bmProblems=(op,r,rec)=>{const p=[];if(!r.pr||!/^[1-9][0-9]{0,9}$/.test(r.pr))p.push("before merge: the run's pull request "+shownJ(r.pr)+" is not a number");`,
396
+ String.raw `if(!r.head||!SHA.test(r.head))p.push("before merge: the run's head "+shownJ(r.head)+" is not a commit sha");`,
397
+ String.raw `if(!r.digest||!/^sha256:[0-9a-f]{64}$/.test(r.digest))p.push("before merge: the run's digest "+shownJ(r.digest)+" is not a sha256 digest");`,
398
+ String.raw `if(p.length)return p;const h=r.head.slice(0,12);if(!rec)return["before merge: no decision on chant/lifecycle names head "+h+" of "+op+", so this run applies nothing"];`,
399
+ String.raw `if(rec.pr!==Number(r.pr))p.push("before merge: the decision for head "+h+" is pull request "+rec.pr+"'s, not "+r.pr+"'s");`,
400
+ String.raw `if(rec.digest!==r.digest)p.push("before merge: the run carries digest "+r.digest+", and the decision for head "+h+" has "+rec.digest);`,
401
+ String.raw `const dg="sha256:"+require("crypto").createHash("sha256").update(JSON.stringify(["chant-before-merge/1",op,rec.pr,rec.head,rec.base,rec.through===undefined?0:rec.through,rec.at,rec.by])).digest("hex");`,
402
+ String.raw `if(dg!==rec.digest)p.push("before merge: the decision for head "+h+" was changed after it was made: its fields give another digest");return p};`,
403
+ ].map(noQuote);
404
+ const FO_PATH = followOnPath("\u0000").split("\u0000");
405
+ /**
406
+ * The follow-on part of the program (#4992): the run's two variables and the lines of {@link followOnProblems}, and
407
+ * (#4998) the read of the chain's record and the lines of {@link followOnRecordProblems}. After {@link BEFORE_MERGE_JS},
408
+ * whose `SHA`, `bmRead` and decision variables it reads.
409
+ */
410
+ const FOLLOW_ON_JS = [
411
+ `const foV=[${JSON.stringify(OP_WAVES_WAVE_ENV)},${JSON.stringify(OP_WAVES_COMMIT_ENV)}].map((k)=>String(E[k]||"").trim());const foRun={};if(foV[0])foRun.wave=foV[0];if(foV[1])foRun.commit=foV[1];`,
412
+ String.raw `const foProblems=(rest,r,bm)=>{const w=r.wave,c=r.commit;`,
413
+ String.raw `if(rest===undefined){if(w===undefined&&c===undefined)return{p:[]};return{p:["follow-on: the run names wave "+(w===undefined?"none":w)+" and commit "+(c===undefined?"none":c)+", and this job is none of the rest wave's, which alone runs in a follow-on"]}}`,
414
+ String.raw `if(w===undefined||w===String(rest)){if(c===undefined)return{p:[]};return{p:["follow-on: the run names the commit "+c+" and no wave after wave "+rest+", so it is no follow-on"]}}`,
415
+ String.raw `if(!/^[1-9][0-9]{0,5}$/.test(w)||Number(w)<=rest)return{p:["follow-on: the run's wave "+JSON.stringify(w)+" is no wave after wave "+rest]};`,
416
+ String.raw `if(bm){if(c!==undefined)return{p:["follow-on: a follow-on of a decided head checks out that head, and the run names the commit "+c+" too"]};return{p:[],c:"follow-on wave "+w}}`,
417
+ String.raw `if(c===undefined||!SHA.test(c))return{p:["follow-on: a push's follow-on names the commit it goes on with, and the run's "+(c===undefined?"none":JSON.stringify(c))+" is not a commit sha"]};`,
418
+ String.raw `return{p:[],c:"follow-on wave "+w+" at "+c.slice(0,12)}};`,
419
+ // #4998: the record of the run's chain, as parseFollowOn keeps an entry, and the lines of followOnRecordProblems.
420
+ String.raw `const foEntry=(t,k)=>{let v;try{v=JSON.parse(t===null?"null":t)}catch(e){return null}const cs=v&&typeof v==="object"&&v.version===1?v.chains:undefined;if(!cs||typeof cs!=="object"||!SHA.test(k))return null;const e=cs[k];const W=(n,m)=>Number.isInteger(n)&&n>=m;`,
421
+ String.raw `if(!e||typeof e!=="object"||e.key!==k||!W(e.wave,2)||!W(e.from,1)||typeof e.run!=="string"||typeof e.at!=="string")return null;`,
422
+ String.raw `if((e.digest!==undefined&&typeof e.digest!=="string")||(e.pr!==undefined&&!W(e.pr,1))||(e.commit!==undefined&&(typeof e.commit!=="string"||!SHA.test(e.commit)))||!e.outcomes||typeof e.outcomes!=="object")return null;return e};`,
423
+ `const foSeen=(s)=>{const k=bmOn?bmRun.head:foRun.commit;if(!x.beforeMerge||!k||foProblems(x.rest,foRun,bmOn).c===undefined)return s;try{s.foRec=foEntry(bmRead(${JSON.stringify(FO_PATH[0])}+x.beforeMerge.op+${JSON.stringify(FO_PATH[1])}),k)}catch(e){s.foErr=e&&e.message?e.message:String(e)}return s};`,
424
+ String.raw `const foRecProblems=(op,w,k,dg,rec)=>{const what=dg!==undefined?"head":"commit";const sh=k.slice(0,12);if(!rec)return["follow-on: no record job of "+op+" started a follow-on for "+what+" "+sh+", so this run applies nothing"];const p=[];`,
425
+ String.raw `if(String(rec.wave)!==w)p.push("follow-on: the newest record job of "+op+" for "+what+" "+sh+" started wave "+rec.wave+", and this run names wave "+w);`,
426
+ String.raw `if(dg!==undefined&&rec.digest!==dg)p.push("follow-on: wave "+rec.wave+" of "+what+" "+sh+" was started for the decision with digest "+(rec.digest===undefined?"none":rec.digest)+", and the run carries "+dg);return p};`,
427
+ ].map(noQuote);
233
428
  /**
234
429
  * The guard as one `node -e` program: the same checks as {@link checkJob},
235
430
  * {@link jobSeen} and {@link describeJobGuard}, reading {@link JOB_GUARD_ENV}.
@@ -246,15 +441,17 @@ export const JOB_GUARD_JS = [
246
441
  "if(!x||![\"github\",\"gitlab\",\"forgejo\"].includes(x.forge)||!Array.isArray(x.branches))fail(\"" + JOB_GUARD_ENV + " is not a guard spec\");",
247
442
  'const tags=(r)=>{if(r===undefined)return undefined;const t=r.trim();if(t.startsWith("[")){try{const v=JSON.parse(t);if(Array.isArray(v))return v.map(String)}catch(e){}}return t===""?[]:t.split(",").map((s)=>s.trim()).filter((s)=>s!=="")};',
248
443
  'const claimsOf=(tok)=>{const p=tok.split(".")[1];if(!p)throw new Error("the forge\\u0027s OIDC token is not a JWT");const c=JSON.parse(Buffer.from(p.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf-8"));if(!c||typeof c!=="object")throw new Error("the forge\\u0027s OIDC token has no claims");return c};',
444
+ ...BEFORE_MERGE_JS,
445
+ ...FOLLOW_ON_JS,
249
446
  "async function seenOf(){",
250
- 'if(x.forge==="gitlab")return{forgeEnvironment:E.CI_ENVIRONMENT_NAME||null,ref:E.CI_COMMIT_REF_NAME,refProtected:E.CI_COMMIT_REF_PROTECTED,runnerTags:tags(E.CI_RUNNER_TAGS)};',
447
+ 'if(x.forge==="gitlab")return foSeen(bmSeen({forgeEnvironment:E.CI_ENVIRONMENT_NAME||null,ref:E.CI_COMMIT_REF_NAME,refProtected:E.CI_COMMIT_REF_PROTECTED,runnerTags:tags(E.CI_RUNNER_TAGS)}));',
251
448
  "const s={ref:E.GITHUB_REF};let c;",
252
449
  'if(x.forge==="github"&&x.forgeEnvironment!==undefined){try{',
253
450
  'if(!E.ACTIONS_ID_TOKEN_REQUEST_URL||!E.ACTIONS_ID_TOKEN_REQUEST_TOKEN)throw new Error("the job may request no OIDC token (no ACTIONS_ID_TOKEN_REQUEST_URL); it needs the id-token: write permission");',
254
451
  'const r=await fetch(E.ACTIONS_ID_TOKEN_REQUEST_URL+"&audience="+encodeURIComponent(A),{headers:{authorization:"bearer "+E.ACTIONS_ID_TOKEN_REQUEST_TOKEN}});',
255
452
  'if(!r.ok)throw new Error("the OIDC token request answered "+r.status);const v=(await r.json()).value;if(typeof v!=="string")throw new Error("the OIDC token request answered no token");',
256
453
  'c=claimsOf(v);s.forgeEnvironment=typeof c.environment==="string"&&c.environment!==""?c.environment:null}catch(e){s.forgeEnvironmentError=e&&e.message?e.message:String(e)}}',
257
- 'const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return s}',
454
+ 'const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return foSeen(bmSeen(s))}',
258
455
  "seenOf().then((s)=>{const P=[],C=[],S=[];const fe=x.forgeEnvironment;",
259
456
  'if(x.forge==="forgejo")S.push("forge environment (Forgejo has none)");',
260
457
  'else if(fe!==undefined){if(s.forgeEnvironmentError!==undefined)P.push("forge environment: expected "+fe+", and it could not be read: "+s.forgeEnvironmentError);else if(s.forgeEnvironment!==fe)P.push("forge environment: expected "+fe+", found "+shown(s.forgeEnvironment));else C.push("forge environment "+fe)}',
@@ -263,6 +460,12 @@ export const JOB_GUARD_JS = [
263
460
  'else if(x.forge==="gitlab"){if(!s.ref||!b.includes(s.ref))P.push("ref: expected "+b.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref);',
264
461
  'if(s.refProtected!=="true")P.push("ref: expected a protected ref (CI_COMMIT_REF_PROTECTED true), found "+shown(s.refProtected));else C.push("protected ref")}',
265
462
  'else{const refs=b.map((v)=>"refs/heads/"+v);if(!s.ref||!refs.includes(s.ref))P.push("ref: expected "+refs.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref)}',
463
+ ...[
464
+ String.raw `if(s.beforeMerge){const r=s.beforeMerge;if(!x.beforeMerge)P.push("before merge: the run names pull request "+(r.pr||"none")+"'s head "+(r.head||"none")+", and this job applies only the pushes to its branches");`,
465
+ String.raw `else if(s.bmErr!==undefined)P.push("before merge: the decisions on chant/lifecycle could not be read: "+s.bmErr);`,
466
+ String.raw `else{const Q=bmProblems(x.beforeMerge.op,r,s.rec||undefined);if(Q.length)P.push(...Q);else C.push("before merge: pull request "+r.pr+"'s decided head "+r.head.slice(0,12))}}`,
467
+ ].map(noQuote),
468
+ "{const F=foProblems(x.rest,foRun,bmOn);P.push(...F.p);if(F.c){const G=!x.beforeMerge?[\"follow-on: this job names no op whose follow-on records it reads, so it admits no follow-on\"]:s.foErr!==undefined?[\"follow-on: the follow-on records on chant/lifecycle could not be read: \"+s.foErr]:foRecProblems(x.beforeMerge.op,foRun.wave,(bmOn?bmRun.head:foRun.commit)||\"\",bmOn?(bmRun.digest||\"\"):undefined,s.foRec);if(G.length)P.push(...G);else C.push(F.c)}}",
266
469
  'if(x.forge==="gitlab"){const w=x.runnerTags||[];if(w.length>0){const h=s.runnerTags;const miss=w.filter((t)=>!(h||[]).includes(t));',
267
470
  'if(h===undefined)P.push("runner: expected tags "+w.join(", ")+", and the job has no CI_RUNNER_TAGS");else if(miss.length>0)P.push("runner: expected tags "+w.join(", ")+", found "+(h.length?h.join(", "):"none"));else C.push("runner tags "+w.join(", "))}}',
268
471
  'else if(x.selfHosted){if(s.runnerEnvironment===undefined)S.push("runner (the runner says nothing about itself: no RUNNER_ENVIRONMENT)");else if(s.runnerEnvironment!=="self-hosted")P.push("runner: expected self-hosted, found "+s.runnerEnvironment);else C.push("self-hosted runner")}',
@@ -29,6 +29,7 @@
29
29
  import { type CiProductWords, type ParsedProductComment } from "./ci-product-words.js";
30
30
  import { type ForgeKind, type GitlabForgeOptions, type PrForge } from "./pr-forge.js";
31
31
  import type { ForgeReads, PullRequestDetail, PullRequestNote, RunJob, WorkflowRun } from "./pr-forge-reads.js";
32
+ import type { DecideBeforeMergeInput, WavesBeforeMergeJobs } from "./op/before-merge-decide.js";
32
33
  export { GITLAB_NOTE_COMMANDS_VAR } from "./components/pr-pipeline.js";
33
34
  /** How far back the poll reads: merge requests updated, and notes written, in this many minutes. */
34
35
  export declare const NOTE_COMMANDS_WINDOW_MINUTES: number;
@@ -93,6 +94,15 @@ export type NoteRun =
93
94
  kind: "retry";
94
95
  sha: string;
95
96
  jobs?: RegExp;
97
+ /**
98
+ * With the waves' op (#4984, the GitLab half of #4979's stop): the
99
+ * stop written for `sha` on `chant/lifecycle` just before the retry,
100
+ * the last wave that runs, or null to clear an earlier one.
101
+ */
102
+ stop?: {
103
+ op: string;
104
+ through: number | null;
105
+ };
96
106
  }
97
107
  /** A reply, and nothing runs. */
98
108
  | {
@@ -155,6 +165,13 @@ export interface NoteCommandsOptions {
155
165
  env?: Record<string, string | undefined>;
156
166
  /** The commit words that take an argument, as `parseProductComment` takes them. */
157
167
  commitArgs?: Readonly<Record<string, RegExp>>;
168
+ /** Writes a retry's wave stop for op `op` at `sha`, or clears it (#4984). Absent: a retry that carries a stop is refused. */
169
+ stops?: (op: string, sha: string, stop: {
170
+ through: number;
171
+ at: string;
172
+ by?: string;
173
+ pr?: number;
174
+ } | null) => Promise<void>;
158
175
  }
159
176
  export interface NotePoll {
160
177
  outcomes: NoteOutcome[];
@@ -235,13 +252,36 @@ export interface ChantNoteJobs {
235
252
  * reply, and nothing starts. Absent: any member a comment may name.
236
253
  */
237
254
  members?: readonly string[];
255
+ /**
256
+ * The waves on merge (#4984, as the comment job's #4979): their op and
257
+ * count. With them a merged merge request's `wave-<n>` writes a stop for
258
+ * the merge commit before the retry, and an apply without a wave clears
259
+ * it; without them a `wave-<n>` is refused, as before.
260
+ */
261
+ waves?: {
262
+ op: string;
263
+ count: number;
264
+ };
265
+ /**
266
+ * The waves before merge (#4984), with `waves`: an open merge request's
267
+ * apply is decided here (./op/before-merge-decide.ts), recorded on
268
+ * `chant/lifecycle`, and runs in a pipeline of the default branch started
269
+ * with `CHANT_BEFORE_MERGE_PR`, `CHANT_BEFORE_MERGE_HEAD` and
270
+ * `CHANT_BEFORE_MERGE_DIGEST`.
271
+ */
272
+ wavesBeforeMerge?: WavesBeforeMergeJobs;
273
+ }
274
+ /** What {@link chantNoteRuns} reads and writes with besides the jobs (#4984). */
275
+ export interface ChantNoteRunsOptions {
276
+ /** With `jobs.wavesBeforeMerge`: what the decision before merge reads and writes with. */
277
+ beforeMerge?: Pick<DecideBeforeMergeInput, "requires" | "statuses" | "git" | "cwd" | "lock" | "record" | "stop" | "now">;
238
278
  }
239
279
  /**
240
280
  * What a command runs in chant's own GitLab pipeline, for the jobs it has.
241
281
  * A command no job runs gets the words' reply for it (`words.replies`,
242
282
  * #4946), else chant's.
243
283
  */
244
- export declare function chantNoteRuns(jobs: ChantNoteJobs): NoteCommandRuns;
284
+ export declare function chantNoteRuns(jobs: ChantNoteJobs, opts?: ChantNoteRunsOptions): NoteCommandRuns;
245
285
  /** The directory on `chant/lifecycle` that keeps the notes the poll answered. */
246
286
  export declare const NOTES_DIR = "_notes";
247
287
  /** A note's file in {@link NOTES_DIR}. */