@intentius/chant 0.124.88 → 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 (377) hide show
  1. package/dist/actor.d.ts +36 -1
  2. package/dist/actor.d.ts.map +1 -1
  3. package/dist/actor.js +39 -1
  4. package/dist/chant-install.d.ts.map +1 -1
  5. package/dist/chant-install.js +1 -2
  6. package/dist/ci-base.d.ts +30 -0
  7. package/dist/ci-base.d.ts.map +1 -0
  8. package/dist/ci-base.js +33 -0
  9. package/dist/ci-comment-commands.d.ts +193 -0
  10. package/dist/ci-comment-commands.d.ts.map +1 -0
  11. package/dist/ci-comment-commands.js +353 -0
  12. package/dist/ci-comment-replies.d.ts +40 -0
  13. package/dist/ci-comment-replies.d.ts.map +1 -0
  14. package/dist/ci-comment-replies.js +59 -0
  15. package/dist/ci-evidence-from-job.d.ts +25 -0
  16. package/dist/ci-evidence-from-job.d.ts.map +1 -1
  17. package/dist/ci-evidence-from-job.js +43 -2
  18. package/dist/ci-evidence-jobs.d.ts +30 -1
  19. package/dist/ci-evidence-jobs.d.ts.map +1 -1
  20. package/dist/ci-evidence-jobs.js +46 -3
  21. package/dist/ci-image.d.ts +21 -4
  22. package/dist/ci-image.d.ts.map +1 -1
  23. package/dist/ci-image.js +62 -10
  24. package/dist/ci-job-guard.d.ts +42 -45
  25. package/dist/ci-job-guard.d.ts.map +1 -1
  26. package/dist/ci-job-guard.js +206 -3
  27. package/dist/ci-note-commands.d.ts +104 -4
  28. package/dist/ci-note-commands.d.ts.map +1 -1
  29. package/dist/ci-note-commands.js +131 -38
  30. package/dist/ci-product-words.d.ts +42 -0
  31. package/dist/ci-product-words.d.ts.map +1 -1
  32. package/dist/ci-product-words.js +25 -0
  33. package/dist/ci-product.d.ts +72 -1
  34. package/dist/ci-product.d.ts.map +1 -1
  35. package/dist/ci-product.js +73 -6
  36. package/dist/cli/commands/build.d.ts.map +1 -1
  37. package/dist/cli/commands/build.js +29 -2
  38. package/dist/cli/handlers/approve.d.ts.map +1 -1
  39. package/dist/cli/handlers/approve.js +2 -1
  40. package/dist/cli/handlers/ci-check.d.ts +1 -1
  41. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  42. package/dist/cli/handlers/ci-check.js +17 -7
  43. package/dist/cli/handlers/ci-evidence.d.ts.map +1 -1
  44. package/dist/cli/handlers/ci-evidence.js +33 -7
  45. package/dist/cli/handlers/components.d.ts.map +1 -1
  46. package/dist/cli/handlers/components.js +3 -1
  47. package/dist/cli/handlers/generated-check.d.ts +8 -0
  48. package/dist/cli/handlers/generated-check.d.ts.map +1 -1
  49. package/dist/cli/handlers/generated-check.js +31 -1
  50. package/dist/cli/handlers/lock.d.ts.map +1 -1
  51. package/dist/cli/handlers/lock.js +121 -4
  52. package/dist/cli/handlers/pr-comment.d.ts +33 -0
  53. package/dist/cli/handlers/pr-comment.d.ts.map +1 -0
  54. package/dist/cli/handlers/pr-comment.js +201 -0
  55. package/dist/cli/handlers/pr-env.d.ts.map +1 -1
  56. package/dist/cli/handlers/pr-env.js +6 -3
  57. package/dist/cli/handlers/pr-notes.d.ts.map +1 -1
  58. package/dist/cli/handlers/pr-notes.js +23 -1
  59. package/dist/cli/handlers/pr.d.ts +23 -1
  60. package/dist/cli/handlers/pr.d.ts.map +1 -1
  61. package/dist/cli/handlers/pr.js +71 -23
  62. package/dist/cli/handlers/promote.d.ts.map +1 -1
  63. package/dist/cli/handlers/promote.js +2 -1
  64. package/dist/cli/handlers/release.d.ts.map +1 -1
  65. package/dist/cli/handlers/release.js +11 -2
  66. package/dist/cli/handlers/run-wave.d.ts.map +1 -1
  67. package/dist/cli/handlers/run-wave.js +180 -4
  68. package/dist/cli/handlers/run.d.ts.map +1 -1
  69. package/dist/cli/handlers/run.js +2 -1
  70. package/dist/cli/main.d.ts.map +1 -1
  71. package/dist/cli/main.js +41 -2
  72. package/dist/cli/parse-args.d.ts.map +1 -1
  73. package/dist/cli/parse-args.js +31 -0
  74. package/dist/cli/registry.d.ts +19 -1
  75. package/dist/cli/registry.d.ts.map +1 -1
  76. package/dist/components/auto-release.d.ts.map +1 -1
  77. package/dist/components/auto-release.js +2 -1
  78. package/dist/components/pr-checks.d.ts +97 -6
  79. package/dist/components/pr-checks.d.ts.map +1 -1
  80. package/dist/components/pr-checks.js +107 -13
  81. package/dist/components/pr-pipeline.d.ts +19 -14
  82. package/dist/components/pr-pipeline.d.ts.map +1 -1
  83. package/dist/components/pr-pipeline.js +7 -13
  84. package/dist/components/product-pipeline.d.ts +96 -3
  85. package/dist/components/product-pipeline.d.ts.map +1 -1
  86. package/dist/components/product-pipeline.js +120 -14
  87. package/dist/components/product-plan.d.ts +203 -6
  88. package/dist/components/product-plan.d.ts.map +1 -1
  89. package/dist/components/product-plan.js +250 -43
  90. package/dist/drift-record.d.ts +7 -0
  91. package/dist/drift-record.d.ts.map +1 -1
  92. package/dist/drift-record.js +19 -0
  93. package/dist/floor-table.data.d.ts.map +1 -1
  94. package/dist/floor-table.data.js +63 -31
  95. package/dist/forge-check/contract.d.ts +11 -1
  96. package/dist/forge-check/contract.d.ts.map +1 -1
  97. package/dist/forge-check/contract.js +4 -1
  98. package/dist/forge-check/index.d.ts +2 -0
  99. package/dist/forge-check/index.d.ts.map +1 -1
  100. package/dist/forge-check/index.js +2 -0
  101. package/dist/gate-resume-run.d.ts +9 -1
  102. package/dist/gate-resume-run.d.ts.map +1 -1
  103. package/dist/gate-resume-run.js +26 -3
  104. package/dist/generated-check.d.ts +18 -4
  105. package/dist/generated-check.d.ts.map +1 -1
  106. package/dist/generated-check.js +37 -5
  107. package/dist/image-pins.d.ts +26 -0
  108. package/dist/image-pins.d.ts.map +1 -0
  109. package/dist/image-pins.js +19 -0
  110. package/dist/lexicon.d.ts +93 -4
  111. package/dist/lexicon.d.ts.map +1 -1
  112. package/dist/lifecycle/gate-applied.d.ts +9 -0
  113. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  114. package/dist/lifecycle/git.d.ts +11 -0
  115. package/dist/lifecycle/git.d.ts.map +1 -1
  116. package/dist/lifecycle/git.js +30 -3
  117. package/dist/lifecycle/publish-npm.d.ts +11 -0
  118. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  119. package/dist/lifecycle/publish-npm.js +27 -1
  120. package/dist/lifecycle/reach-locks.d.ts +131 -0
  121. package/dist/lifecycle/reach-locks.d.ts.map +1 -0
  122. package/dist/lifecycle/reach-locks.js +118 -0
  123. package/dist/lifecycle/release-cut.d.ts +3 -1
  124. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  125. package/dist/lifecycle/release-cut.js +15 -0
  126. package/dist/lifecycle/release-images.d.ts.map +1 -1
  127. package/dist/lifecycle/release-images.js +1 -2
  128. package/dist/notify-product.d.ts +12 -3
  129. package/dist/notify-product.d.ts.map +1 -1
  130. package/dist/notify-product.js +10 -6
  131. package/dist/op/activities/source-release.d.ts.map +1 -1
  132. package/dist/op/activities/source-release.js +2 -1
  133. package/dist/op/activities/source-rollback.d.ts.map +1 -1
  134. package/dist/op/activities/source-rollback.js +2 -1
  135. package/dist/op/apply-status.d.ts +84 -0
  136. package/dist/op/apply-status.d.ts.map +1 -0
  137. package/dist/op/apply-status.js +106 -0
  138. package/dist/op/before-merge-decide.d.ts +102 -0
  139. package/dist/op/before-merge-decide.d.ts.map +1 -0
  140. package/dist/op/before-merge-decide.js +142 -0
  141. package/dist/op/before-merge-done.d.ts +56 -0
  142. package/dist/op/before-merge-done.d.ts.map +1 -0
  143. package/dist/op/before-merge-done.js +69 -0
  144. package/dist/op/before-merge-store.d.ts +20 -0
  145. package/dist/op/before-merge-store.d.ts.map +1 -0
  146. package/dist/op/before-merge-store.js +48 -0
  147. package/dist/op/before-merge.d.ts +150 -0
  148. package/dist/op/before-merge.d.ts.map +1 -0
  149. package/dist/op/before-merge.js +207 -0
  150. package/dist/op/follow-on-run.d.ts +117 -0
  151. package/dist/op/follow-on-run.d.ts.map +1 -0
  152. package/dist/op/follow-on-run.js +154 -0
  153. package/dist/op/follow-on-store.d.ts +17 -0
  154. package/dist/op/follow-on-store.d.ts.map +1 -0
  155. package/dist/op/follow-on-store.js +54 -0
  156. package/dist/op/gate.d.ts +6 -0
  157. package/dist/op/gate.d.ts.map +1 -1
  158. package/dist/op/gate.js +10 -1
  159. package/dist/op/index.d.ts +5 -1
  160. package/dist/op/index.d.ts.map +1 -1
  161. package/dist/op/index.js +2 -0
  162. package/dist/op/op-waves-after-plan.d.ts +13 -0
  163. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  164. package/dist/op/op-waves-evidence-jobs.d.ts +10 -2
  165. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  166. package/dist/op/op-waves-evidence-jobs.js +19 -5
  167. package/dist/op/op-waves-follow-on.d.ts +162 -0
  168. package/dist/op/op-waves-follow-on.d.ts.map +1 -0
  169. package/dist/op/op-waves-follow-on.js +355 -0
  170. package/dist/op/op-waves-render-spec.d.ts +100 -0
  171. package/dist/op/op-waves-render-spec.d.ts.map +1 -0
  172. package/dist/op/op-waves-render-spec.js +162 -0
  173. package/dist/op/op-waves-run.d.ts +148 -6
  174. package/dist/op/op-waves-run.d.ts.map +1 -1
  175. package/dist/op/op-waves-run.js +873 -100
  176. package/dist/op/op-waves-split.d.ts +122 -0
  177. package/dist/op/op-waves-split.d.ts.map +1 -0
  178. package/dist/op/op-waves-split.js +166 -0
  179. package/dist/op/op-waves.d.ts +24 -0
  180. package/dist/op/op-waves.d.ts.map +1 -1
  181. package/dist/op/op-waves.js +18 -1
  182. package/dist/op/schedule-overdue.d.ts +15 -1
  183. package/dist/op/schedule-overdue.d.ts.map +1 -1
  184. package/dist/op/schedule-overdue.js +77 -5
  185. package/dist/op/stage-hooks.d.ts +36 -1
  186. package/dist/op/stage-hooks.d.ts.map +1 -1
  187. package/dist/op/stage-hooks.js +17 -3
  188. package/dist/op/wave-stop.d.ts +67 -0
  189. package/dist/op/wave-stop.d.ts.map +1 -0
  190. package/dist/op/wave-stop.js +129 -0
  191. package/dist/planned-files.d.ts +76 -0
  192. package/dist/planned-files.d.ts.map +1 -0
  193. package/dist/planned-files.js +108 -0
  194. package/dist/pr-forge-job.d.ts +22 -0
  195. package/dist/pr-forge-job.d.ts.map +1 -0
  196. package/dist/pr-forge-job.js +46 -0
  197. package/dist/pr-loop.d.ts +3 -6
  198. package/dist/pr-loop.d.ts.map +1 -1
  199. package/dist/pr-loop.js +4 -81
  200. package/dist/pr-plan-note.d.ts +97 -0
  201. package/dist/pr-plan-note.d.ts.map +1 -1
  202. package/dist/pr-plan-note.js +94 -1
  203. package/dist/pr-post.d.ts +28 -3
  204. package/dist/pr-post.d.ts.map +1 -1
  205. package/dist/pr-post.js +146 -13
  206. package/dist/pr-status.d.ts +16 -0
  207. package/dist/pr-status.d.ts.map +1 -0
  208. package/dist/pr-status.js +90 -0
  209. package/dist/ref-gate-init.d.ts +16 -2
  210. package/dist/ref-gate-init.d.ts.map +1 -1
  211. package/dist/ref-gate-init.js +24 -13
  212. package/dist/release-floors.d.ts +39 -1
  213. package/dist/release-floors.d.ts.map +1 -1
  214. package/dist/release-floors.js +63 -25
  215. package/dist/render-module.d.ts +15 -0
  216. package/dist/render-module.d.ts.map +1 -0
  217. package/dist/render-module.js +73 -0
  218. package/dist/state-migration.d.ts.map +1 -1
  219. package/dist/state-migration.js +1 -2
  220. package/dist/wave-blocked.d.ts +7 -1
  221. package/dist/wave-blocked.d.ts.map +1 -1
  222. package/dist/wave-blocked.js +7 -2
  223. package/dist/wave-runtime.mjs +366 -350
  224. package/dist/workspace/ci-green-cli.d.ts.map +1 -1
  225. package/dist/workspace/ci-green-cli.js +3 -2
  226. package/dist/workspace/release-train.d.ts.map +1 -1
  227. package/dist/workspace/release-train.js +2 -1
  228. package/dist/workspace/release-workflow.d.ts +4 -3
  229. package/dist/workspace/release-workflow.d.ts.map +1 -1
  230. package/dist/workspace/release-workflow.js +10 -7
  231. package/dist/workspace/trust/check-evidence-report.d.ts +7 -2
  232. package/dist/workspace/trust/check-evidence-report.d.ts.map +1 -1
  233. package/dist/workspace/trust/check-evidence-report.js +15 -8
  234. package/dist/workspace/trust/ref-gate-cli.d.ts +10 -1
  235. package/dist/workspace/trust/ref-gate-cli.d.ts.map +1 -1
  236. package/dist/workspace/trust/ref-gate-cli.js +30 -10
  237. package/dist/workspace/workspace-run.d.ts.map +1 -1
  238. package/dist/workspace/workspace-run.js +2 -1
  239. package/package.json +1 -1
  240. package/src/actor.test.ts +68 -2
  241. package/src/actor.ts +61 -1
  242. package/src/chant-install.test.ts +2 -3
  243. package/src/chant-install.ts +1 -2
  244. package/src/ci-base.test.ts +41 -0
  245. package/src/ci-base.ts +43 -0
  246. package/src/ci-comment-commands.test.ts +439 -0
  247. package/src/ci-comment-commands.ts +428 -0
  248. package/src/ci-comment-replies.ts +78 -0
  249. package/src/ci-commit.test.ts +2 -3
  250. package/src/ci-evidence-from-job.test.ts +18 -0
  251. package/src/ci-evidence-from-job.ts +58 -2
  252. package/src/ci-evidence-jobs.ts +50 -5
  253. package/src/ci-image.test.ts +130 -10
  254. package/src/ci-image.ts +85 -12
  255. package/src/ci-job-guard.before-merge.test.ts +148 -0
  256. package/src/ci-job-guard.follow-on-record.test.ts +137 -0
  257. package/src/ci-job-guard.follow-on.test.ts +144 -0
  258. package/src/ci-job-guard.ts +221 -3
  259. package/src/ci-note-commands.test.ts +76 -1
  260. package/src/ci-note-commands.ts +198 -46
  261. package/src/ci-product-words.ts +59 -0
  262. package/src/ci-product.ts +90 -6
  263. package/src/cli/commands/build.test.ts +41 -0
  264. package/src/cli/commands/build.ts +27 -2
  265. package/src/cli/handlers/approve.ts +2 -1
  266. package/src/cli/handlers/ci-check.ts +19 -7
  267. package/src/cli/handlers/ci-evidence.ts +29 -8
  268. package/src/cli/handlers/components.ts +3 -1
  269. package/src/cli/handlers/generated-check.ts +31 -1
  270. package/src/cli/handlers/lock-reach.test.ts +103 -0
  271. package/src/cli/handlers/lock.ts +100 -4
  272. package/src/cli/handlers/pr-comment.ts +187 -0
  273. package/src/cli/handlers/pr-env.ts +6 -3
  274. package/src/cli/handlers/pr-notes.ts +30 -6
  275. package/src/cli/handlers/pr-record.test.ts +1 -1
  276. package/src/cli/handlers/pr.ts +64 -21
  277. package/src/cli/handlers/promote.ts +2 -1
  278. package/src/cli/handlers/release.e2e.test.ts +35 -0
  279. package/src/cli/handlers/release.ts +14 -2
  280. package/src/cli/handlers/run-wave.ts +170 -4
  281. package/src/cli/handlers/run.ts +2 -1
  282. package/src/cli/main.ts +41 -2
  283. package/src/cli/parse-args.ts +23 -0
  284. package/src/cli/registry.ts +19 -1
  285. package/src/components/auto-release.ts +2 -1
  286. package/src/components/pr-checks.ts +165 -17
  287. package/src/components/pr-pipeline.ts +22 -18
  288. package/src/components/product-pipeline.apply-status.test.ts +50 -0
  289. package/src/components/product-pipeline.ts +204 -17
  290. package/src/components/product-plan.test.ts +60 -4
  291. package/src/components/product-plan.ts +367 -50
  292. package/src/drift-record.test.ts +20 -0
  293. package/src/drift-record.ts +16 -0
  294. package/src/floor-table.data.ts +63 -31
  295. package/src/forge-check/contract.ts +12 -1
  296. package/src/forge-check/forge-check.test.ts +17 -0
  297. package/src/forge-check/index.ts +2 -0
  298. package/src/gate-resume-run.ts +27 -3
  299. package/src/generated-check.e2e.test.ts +21 -1
  300. package/src/generated-check.test.ts +66 -0
  301. package/src/generated-check.ts +51 -10
  302. package/src/image-pins.ts +31 -0
  303. package/src/lexicon.ts +89 -1
  304. package/src/lifecycle/gate-applied.ts +7 -0
  305. package/src/lifecycle/git.test.ts +48 -0
  306. package/src/lifecycle/git.ts +27 -4
  307. package/src/lifecycle/publish-npm.ts +31 -1
  308. package/src/lifecycle/reach-locks.test.ts +87 -0
  309. package/src/lifecycle/reach-locks.ts +169 -0
  310. package/src/lifecycle/release-cut.ts +17 -1
  311. package/src/lifecycle/release-images.test.ts +56 -0
  312. package/src/lifecycle/release-images.ts +1 -2
  313. package/src/notify-product.ts +19 -8
  314. package/src/op/activities/source-release.ts +2 -1
  315. package/src/op/activities/source-rollback.ts +2 -1
  316. package/src/op/apply-status.test.ts +83 -0
  317. package/src/op/apply-status.ts +132 -0
  318. package/src/op/before-merge-decide.ts +190 -0
  319. package/src/op/before-merge-done.ts +99 -0
  320. package/src/op/before-merge-store.ts +44 -0
  321. package/src/op/before-merge.test.ts +201 -0
  322. package/src/op/before-merge.ts +266 -0
  323. package/src/op/follow-on-run.ts +206 -0
  324. package/src/op/follow-on-store.ts +54 -0
  325. package/src/op/gate-resume.test.ts +27 -0
  326. package/src/op/gate.ts +16 -1
  327. package/src/op/index.ts +15 -0
  328. package/src/op/op-waves-after-plan.ts +13 -0
  329. package/src/op/op-waves-evidence-jobs.ts +21 -7
  330. package/src/op/op-waves-follow-on-record.test.ts +152 -0
  331. package/src/op/op-waves-follow-on.test.ts +247 -0
  332. package/src/op/op-waves-follow-on.ts +385 -0
  333. package/src/op/op-waves-notify-words.test.ts +18 -0
  334. package/src/op/op-waves-render-spec.test.ts +159 -0
  335. package/src/op/op-waves-render-spec.ts +171 -0
  336. package/src/op/op-waves-run.ts +973 -94
  337. package/src/op/op-waves-split-product.test.ts +288 -0
  338. package/src/op/op-waves-split-step.test.ts +298 -0
  339. package/src/op/op-waves-split.test.ts +196 -0
  340. package/src/op/op-waves-split.ts +189 -0
  341. package/src/op/op-waves.ts +31 -3
  342. package/src/op/schedule-overdue.test.ts +72 -1
  343. package/src/op/schedule-overdue.ts +84 -6
  344. package/src/op/stage-hooks.ts +52 -4
  345. package/src/op/wave-stop.test.ts +72 -0
  346. package/src/op/wave-stop.ts +139 -0
  347. package/src/planned-files.test.ts +80 -0
  348. package/src/planned-files.ts +134 -0
  349. package/src/pr-forge-job.test.ts +53 -0
  350. package/src/pr-forge-job.ts +46 -0
  351. package/src/pr-loop-narrowed.test.ts +2 -1
  352. package/src/pr-loop-words.test.ts +2 -1
  353. package/src/pr-loop.test.ts +1 -2
  354. package/src/pr-loop.ts +4 -80
  355. package/src/pr-plan-note.ts +155 -3
  356. package/src/pr-post-replan.test.ts +144 -0
  357. package/src/pr-post-subject.test.ts +230 -0
  358. package/src/pr-post.test.ts +2 -1
  359. package/src/pr-post.ts +151 -15
  360. package/src/pr-status.ts +91 -0
  361. package/src/ref-gate-init.ts +30 -11
  362. package/src/release-floors.ts +81 -25
  363. package/src/render-module.ts +73 -0
  364. package/src/state-migration-record.test.ts +2 -3
  365. package/src/state-migration.ts +1 -2
  366. package/src/wave-blocked.ts +9 -4
  367. package/src/workspace/ci-green-cli.ts +3 -2
  368. package/src/workspace/ci-green-workflow.test.ts +32 -1
  369. package/src/workspace/release-train.ts +2 -1
  370. package/src/workspace/release-workflow.test.ts +36 -5
  371. package/src/workspace/release-workflow.ts +10 -7
  372. package/src/workspace/trust/check-evidence-report.ts +15 -8
  373. package/src/workspace/trust/check-evidence.test.ts +5 -0
  374. package/src/workspace/trust/ref-gate-cli.ts +30 -8
  375. package/src/workspace/trust/ref-gate-pieces.test.ts +46 -1
  376. package/src/workspace/trust/ref-gate.test.ts +10 -0
  377. package/src/workspace/workspace-run.ts +2 -1
@@ -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, type CiRunner } from "./ci-jobs";
46
76
  import { CHANT_EXIT } from "./exit-codes";
77
+ import { BEFORE_MERGE_DIGEST_ENV, BEFORE_MERGE_HEAD_ENV, BEFORE_MERGE_PR_ENV, beforeMergePath, beforeMergeProblems, beforeMergeRunFromEnv, isBeforeMergeRun, parseBeforeMerge, type BeforeMergeRecord, type BeforeMergeRun } from "./op/before-merge";
78
+ import { followOnPath, followOnProblems, followOnRecordProblems, followOnRunFromEnv, OP_WAVES_COMMIT_ENV, OP_WAVES_WAVE_ENV, parseFollowOn, type FollowOnRecord, type FollowOnRun } from "./op/follow-on-run";
47
79
 
48
80
  /** The variable the generated step carries its expectation in. */
49
81
  export const JOB_GUARD_ENV = "CHANT_JOB_GUARD";
@@ -68,6 +100,10 @@ export interface JobGuardSpec {
68
100
  runnerTags?: string[];
69
101
  /** GitHub and Forgejo: the runner must be self-hosted. */
70
102
  selfHosted?: boolean;
103
+ /** The waves have a before-merge mode (#4984): a run that names a head runs only as op `op`'s recorded decision. */
104
+ beforeMerge?: { op: string };
105
+ /** The job is one of the `rest` wave's (#4992), rendered as this wave: a follow-on run may name a later one. */
106
+ rest?: number;
71
107
  }
72
108
 
73
109
  /** What the job sees. Undefined: the forge did not say. */
@@ -80,6 +116,18 @@ export interface JobSeen {
80
116
  refProtected?: string;
81
117
  runnerTags?: string[];
82
118
  runnerEnvironment?: string;
119
+ /** The decision the run names (#4984), from its variables. */
120
+ beforeMerge?: BeforeMergeRun;
121
+ /** The recorded decision for that head; null when there is none. Read only when the spec has a before-merge mode. */
122
+ beforeMergeRecord?: BeforeMergeRecord | null;
123
+ /** Why the decisions could not be read, when they could not. */
124
+ beforeMergeError?: string;
125
+ /** The follow-on variables the run names (#4992). */
126
+ followOn?: FollowOnRun;
127
+ /** 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. */
128
+ followOnRecord?: FollowOnRecord | null;
129
+ /** Why the follow-on records could not be read, when they could not. */
130
+ followOnError?: string;
83
131
  }
84
132
 
85
133
  export interface JobGuardResult {
@@ -104,6 +152,10 @@ export interface JobGuardInput {
104
152
  runner?: CiRunner;
105
153
  /** GitHub: the job may request an OIDC token (`id-token: write`), so the guard can read its environment. */
106
154
  idToken?: boolean;
155
+ /** The waves' before-merge mode (#4984), with the op its decisions are recorded under. */
156
+ beforeMerge?: { op: string };
157
+ /** The job is one of the `rest` wave's (#4992), whose number this is. */
158
+ rest?: number;
107
159
  }
108
160
 
109
161
  /**
@@ -121,6 +173,8 @@ export function jobGuardSpec(input: JobGuardInput): JobGuardSpec {
121
173
  branches: [...input.branches],
122
174
  ...(input.forge === "gitlab" && labels.length > 0 ? { runnerTags: labels } : {}),
123
175
  ...(input.forge !== "gitlab" && labels.includes("self-hosted") ? { selfHosted: true } : {}),
176
+ ...(input.beforeMerge ? { beforeMerge: { op: input.beforeMerge.op } } : {}),
177
+ ...(input.rest !== undefined ? { rest: input.rest } : {}),
124
178
  };
125
179
  }
126
180
 
@@ -140,6 +194,8 @@ export function parseJobGuardSpec(raw: string | undefined): JobGuardSpec {
140
194
  if (!Array.isArray(o.branches) || o.branches.some((b) => typeof b !== "string")) throw new Error(`${JOB_GUARD_ENV}.branches is not a list of branches`);
141
195
  if (o.forgeEnvironment !== undefined && typeof o.forgeEnvironment !== "string") throw new Error(`${JOB_GUARD_ENV}.forgeEnvironment is not a name`);
142
196
  if (o.runnerTags !== undefined && (!Array.isArray(o.runnerTags) || o.runnerTags.some((t) => typeof t !== "string"))) throw new Error(`${JOB_GUARD_ENV}.runnerTags is not a list of tags`);
197
+ if (o.beforeMerge !== undefined && (typeof o.beforeMerge !== "object" || o.beforeMerge === null || typeof o.beforeMerge.op !== "string")) throw new Error(`${JOB_GUARD_ENV}.beforeMerge is { op }`);
198
+ if (o.rest !== undefined && (!Number.isInteger(o.rest) || o.rest < 1)) throw new Error(`${JOB_GUARD_ENV}.rest is the rest wave's number`);
143
199
  return o as JobGuardSpec;
144
200
  }
145
201
 
@@ -194,6 +250,34 @@ export function checkJob(expect: JobGuardSpec, seen: JobSeen): JobGuardResult {
194
250
  else out.checked.push(`ref ${seen.ref}`);
195
251
  }
196
252
 
253
+ // #4984: a run started for an open pull request's head runs only as the decision recorded for it.
254
+ const run = seen.beforeMerge;
255
+ if (run && isBeforeMergeRun(run)) {
256
+ if (!expect.beforeMerge) 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`);
257
+ else if (seen.beforeMergeError !== undefined) out.problems.push(`before merge: the decisions on chant/lifecycle could not be read: ${seen.beforeMergeError}`);
258
+ else {
259
+ const problems = beforeMergeProblems(expect.beforeMerge.op, run, seen.beforeMergeRecord ?? undefined);
260
+ if (problems.length > 0) out.problems.push(...problems);
261
+ else out.checked.push(`before merge: pull request ${run.pr}'s decided head ${run.head!.slice(0, 12)}`);
262
+ }
263
+ }
264
+
265
+ // #4992: a follow-on run of the rest wave, admitted in the rest wave's jobs alone and for a later wave.
266
+ const bmRun = run !== undefined && isBeforeMergeRun(run);
267
+ const follow = followOnProblems(expect.rest, seen.followOn ?? {}, bmRun);
268
+ out.problems.push(...follow.problems);
269
+ if (follow.checked) {
270
+ // #4998: and only for the wave the newest record job of its chain started.
271
+ const key = (bmRun ? run!.head : seen.followOn?.commit) ?? "";
272
+ const rec = !expect.beforeMerge
273
+ ? ["follow-on: this job names no op whose follow-on records it reads, so it admits no follow-on"]
274
+ : seen.followOnError !== undefined
275
+ ? [`follow-on: the follow-on records on chant/lifecycle could not be read: ${seen.followOnError}`]
276
+ : followOnRecordProblems(expect.beforeMerge.op, seen.followOn!.wave!, key, bmRun ? (run!.digest ?? "") : undefined, seen.followOnRecord);
277
+ if (rec.length > 0) out.problems.push(...rec);
278
+ else out.checked.push(follow.checked);
279
+ }
280
+
197
281
  if (expect.forge === "gitlab") {
198
282
  const want = expect.runnerTags ?? [];
199
283
  if (want.length > 0) {
@@ -224,7 +308,71 @@ async function githubClaims(env: NodeJS.ProcessEnv, fetchFn: typeof fetch): Prom
224
308
  }
225
309
 
226
310
  /** 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. */
227
- export async function jobSeen(expect: JobGuardSpec, env: NodeJS.ProcessEnv = process.env, fetchFn: typeof fetch = fetch): Promise<JobSeen> {
311
+ export async function jobSeen(expect: JobGuardSpec, env: NodeJS.ProcessEnv = process.env, fetchFn: typeof fetch = fetch, readLifecycle: LifecycleFileReader = lifecycleFileByGit): Promise<JobSeen> {
312
+ const seen = await forgeSeen(expect, env, fetchFn);
313
+ // #4992: the follow-on variables, whatever else the run names.
314
+ const follow = followOnRunFromEnv(env);
315
+ if (follow.wave !== undefined || follow.commit !== undefined) seen.followOn = follow;
316
+ // #4984: the decision a run names, read only when the spec has a before-merge mode.
317
+ const run = beforeMergeRunFromEnv(env);
318
+ const bm = isBeforeMergeRun(run);
319
+ if (bm) {
320
+ seen.beforeMerge = run;
321
+ if (expect.beforeMerge && run.head) {
322
+ try {
323
+ const text = readLifecycle(expect.forge, env, beforeMergePath(expect.beforeMerge.op));
324
+ seen.beforeMergeRecord = parseBeforeMerge(text).heads[run.head] ?? null;
325
+ } catch (e) {
326
+ seen.beforeMergeError = (e as Error).message;
327
+ }
328
+ }
329
+ }
330
+ // #4998: the record of the run's chain, read only for a follow-on the rest wave's job would admit.
331
+ const key = bm ? run.head : follow.commit;
332
+ if (expect.beforeMerge && key && followOnProblems(expect.rest, follow, bm).checked !== undefined) {
333
+ try {
334
+ seen.followOnRecord = parseFollowOn(readLifecycle(expect.forge, env, followOnPath(expect.beforeMerge.op))).chains[key] ?? null;
335
+ } catch (e) {
336
+ seen.followOnError = (e as Error).message;
337
+ }
338
+ }
339
+ return seen;
340
+ }
341
+
342
+ /** Reads one file of `chant/lifecycle` as the remote has it; null when the branch has no such file (#4984). */
343
+ export type LifecycleFileReader = (forge: JobGuardForge, env: NodeJS.ProcessEnv, path: string) => string | null;
344
+
345
+ /** The repository's git URL and the job token's basic credentials, as the guard fetches with them (#4984). */
346
+ export function guardRemote(forge: JobGuardForge, env: NodeJS.ProcessEnv): { url: string; user: string; token: string } {
347
+ if (forge === "gitlab") {
348
+ if (!env.CI_SERVER_URL || !env.CI_PROJECT_PATH) throw new Error("the job names no repository (no CI_SERVER_URL or CI_PROJECT_PATH)");
349
+ return { url: `${env.CI_SERVER_URL.replace(/\/+$/, "")}/${env.CI_PROJECT_PATH}.git`, user: "gitlab-ci-token", token: env.CI_JOB_TOKEN ?? "" };
350
+ }
351
+ if (!env.GITHUB_SERVER_URL || !env.GITHUB_REPOSITORY) throw new Error("the job names no repository (no GITHUB_SERVER_URL or GITHUB_REPOSITORY)");
352
+ return { url: `${env.GITHUB_SERVER_URL.replace(/\/+$/, "")}/${env.GITHUB_REPOSITORY}.git`, user: "x-access-token", token: env.GITHUB_TOKEN ?? "" };
353
+ }
354
+
355
+ /**
356
+ * {@link LifecycleFileReader} through git: `chant/lifecycle` fetched at depth
357
+ * one into a directory of the guard's own, outside the checkout, with the
358
+ * token as a basic credential header, and the file shown from it. The
359
+ * `node -e` program does the same.
360
+ */
361
+ export const lifecycleFileByGit: LifecycleFileReader = (forge, env, path) => {
362
+ const remote = guardRemote(forge, env);
363
+ const dir = mkdtempSync(join(tmpdir(), "chant-guard-"));
364
+ const git = (args: string[]) => spawnSync("git", args, { cwd: dir, encoding: "utf-8", env: { ...env, GIT_TERMINAL_PROMPT: "0" } });
365
+ const init = git(["init", "-q"]);
366
+ if (init.status !== 0) throw new Error(`git init failed: ${(init.stderr || "").trim()}`);
367
+ const auth = `Authorization: Basic ${Buffer.from(`${remote.user}:${remote.token}`).toString("base64")}`;
368
+ const fetched = git(["-c", `http.extraHeader=${auth}`, "fetch", "-q", "--depth=1", remote.url, "refs/heads/chant/lifecycle"]);
369
+ if (fetched.status !== 0) throw new Error(`could not fetch chant/lifecycle: ${(fetched.stderr || "").trim().split("\n").pop()}`);
370
+ const shown = git(["show", `FETCH_HEAD:${path}`]);
371
+ return shown.status === 0 ? shown.stdout : null;
372
+ };
373
+
374
+ /** What the forge's own variables and token say, before the decision is read. */
375
+ async function forgeSeen(expect: JobGuardSpec, env: NodeJS.ProcessEnv, fetchFn: typeof fetch): Promise<JobSeen> {
228
376
  if (expect.forge === "gitlab") {
229
377
  return {
230
378
  forgeEnvironment: env.CI_ENVIRONMENT_NAME || null,
@@ -262,6 +410,68 @@ export function describeJobGuard(expect: JobGuardSpec, result: JobGuardResult):
262
410
  return { ok: true, out: [`${at}: ${result.checked.length ? result.checked.join(", ") : "nothing to check"}${skipped}`], err: [] };
263
411
  }
264
412
 
413
+ /**
414
+ * The before-merge part of the `node -e` program (#4984): the run's three
415
+ * variables, the read of `chant/lifecycle` as {@link lifecycleFileByGit}
416
+ * does it, the decision entry as {@link parseBeforeMerge} keeps it, and the
417
+ * lines of {@link beforeMergeProblems}, digest included. No single quote,
418
+ * since the program is one shell word in single quotes.
419
+ */
420
+ const BM_PATH = beforeMergePath("\u0000").split("\u0000") as [string, string];
421
+ /** Each apostrophe in the program's strings as `'`, since the whole program is one single-quoted shell word. */
422
+ const noQuote = (s: string): string => s.replace(/'/g, "\\u0027");
423
+ const BEFORE_MERGE_JS = [
424
+ `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());`,
425
+ '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]);',
426
+ "const SHA=/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;",
427
+ String.raw`const bmRead=(file)=>{const cp=require("child_process"),fs=require("fs"),os=require("os"),pa=require("path");let url,user,tok;`,
428
+ 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||""}`,
429
+ 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||""}`,
430
+ 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"})});`,
431
+ String.raw`const i=g(["init","-q"]);if(i.status!==0)throw new Error("git init failed: "+String(i.stderr||"").trim());`,
432
+ 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"]);`,
433
+ String.raw`if(f.status!==0)throw new Error("could not fetch chant/lifecycle: "+String(f.stderr||"").trim().split("\n").pop());`,
434
+ String.raw`const o=g(["show","FETCH_HEAD:"+file]);return o.status===0?o.stdout:null};`,
435
+ 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];`,
436
+ 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;`,
437
+ 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};`,
438
+ `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};`,
439
+ 'const shownJ=(v)=>v===undefined||v===""?"none":JSON.stringify(v);',
440
+ 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");`,
441
+ 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");`,
442
+ 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");`,
443
+ 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"];`,
444
+ 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");`,
445
+ 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);`,
446
+ 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");`,
447
+ 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};`,
448
+ ].map(noQuote);
449
+
450
+ const FO_PATH = followOnPath("\u0000").split("\u0000") as [string, string];
451
+ /**
452
+ * The follow-on part of the program (#4992): the run's two variables and the lines of {@link followOnProblems}, and
453
+ * (#4998) the read of the chain's record and the lines of {@link followOnRecordProblems}. After {@link BEFORE_MERGE_JS},
454
+ * whose `SHA`, `bmRead` and decision variables it reads.
455
+ */
456
+ const FOLLOW_ON_JS = [
457
+ `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];`,
458
+ String.raw`const foProblems=(rest,r,bm)=>{const w=r.wave,c=r.commit;`,
459
+ 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"]}}`,
460
+ 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"]}}`,
461
+ 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]};`,
462
+ 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}}`,
463
+ 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"]};`,
464
+ String.raw`return{p:[],c:"follow-on wave "+w+" at "+c.slice(0,12)}};`,
465
+ // #4998: the record of the run's chain, as parseFollowOn keeps an entry, and the lines of followOnRecordProblems.
466
+ 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;`,
467
+ 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;`,
468
+ 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};`,
469
+ `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};`,
470
+ 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=[];`,
471
+ 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);`,
472
+ 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};`,
473
+ ].map(noQuote);
474
+
265
475
  /**
266
476
  * The guard as one `node -e` program: the same checks as {@link checkJob},
267
477
  * {@link jobSeen} and {@link describeJobGuard}, reading {@link JOB_GUARD_ENV}.
@@ -278,15 +488,17 @@ export const JOB_GUARD_JS = [
278
488
  "if(!x||![\"github\",\"gitlab\",\"forgejo\"].includes(x.forge)||!Array.isArray(x.branches))fail(\"" + JOB_GUARD_ENV + " is not a guard spec\");",
279
489
  '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!=="")};',
280
490
  '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};',
491
+ ...BEFORE_MERGE_JS,
492
+ ...FOLLOW_ON_JS,
281
493
  "async function seenOf(){",
282
- '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)};',
494
+ '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)}));',
283
495
  "const s={ref:E.GITHUB_REF};let c;",
284
496
  'if(x.forge==="github"&&x.forgeEnvironment!==undefined){try{',
285
497
  '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");',
286
498
  'const r=await fetch(E.ACTIONS_ID_TOKEN_REQUEST_URL+"&audience="+encodeURIComponent(A),{headers:{authorization:"bearer "+E.ACTIONS_ID_TOKEN_REQUEST_TOKEN}});',
287
499
  '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");',
288
500
  '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)}}',
289
- 'const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return s}',
501
+ 'const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return foSeen(bmSeen(s))}',
290
502
  "seenOf().then((s)=>{const P=[],C=[],S=[];const fe=x.forgeEnvironment;",
291
503
  'if(x.forge==="forgejo")S.push("forge environment (Forgejo has none)");',
292
504
  '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)}',
@@ -295,6 +507,12 @@ export const JOB_GUARD_JS = [
295
507
  '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);',
296
508
  '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")}',
297
509
  '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)}',
510
+ ...[
511
+ 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");`,
512
+ String.raw`else if(s.bmErr!==undefined)P.push("before merge: the decisions on chant/lifecycle could not be read: "+s.bmErr);`,
513
+ 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))}}`,
514
+ ].map(noQuote),
515
+ "{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)}}",
298
516
  'if(x.forge==="gitlab"){const w=x.runnerTags||[];if(w.length>0){const h=s.runnerTags;const miss=w.filter((t)=>!(h||[]).includes(t));',
299
517
  '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(", "))}}',
300
518
  '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")}',
@@ -26,7 +26,9 @@ import {
26
26
  pollNoteCommands,
27
27
  type ChantNoteJobs,
28
28
  type NoteCommandRuns,
29
+ type NoteCommandsOptions,
29
30
  } from "./ci-note-commands";
31
+ import { beforeMergeDigest } from "./op/before-merge";
30
32
 
31
33
  const NOW = new Date("2026-10-07T12:00:00Z");
32
34
  const BOT = 900;
@@ -125,7 +127,7 @@ beforeEach(() => {
125
127
  const mr = (iid: number, over: Record<string, unknown> = {}) => ({ iid, state: "opened", sha: HEAD, source_branch: `feat-${iid}`, target_branch: "main", source_project_id: 7, target_project_id: 7, updated_at: recent(5), ...over });
126
128
  const note = (id: number, body: string, by = "alice", over: Record<string, unknown> = {}) => ({ id, body, system: false, author: user(by), created_at: recent(10), ...over });
127
129
 
128
- async function poll(w: World, o: { jobs?: ChantNoteJobs; runs?: NoteCommandRuns; log?: ReturnType<typeof memoryNoteLog>; minRole?: "developer" | "maintainer" } = {}) {
130
+ async function poll(w: World, o: { jobs?: ChantNoteJobs; runs?: NoteCommandRuns; log?: ReturnType<typeof memoryNoteLog>; minRole?: "developer" | "maintainer"; stops?: NoteCommandsOptions["stops"] } = {}) {
129
131
  world = w;
130
132
  const opts = { apiBase: base, project: "7", token: "t", host: "gitlab" };
131
133
  const log = o.log ?? memoryNoteLog();
@@ -139,6 +141,7 @@ async function poll(w: World, o: { jobs?: ChantNoteJobs; runs?: NoteCommandRuns;
139
141
  log,
140
142
  now: NOW,
141
143
  ...(o.minRole ? { minRole: o.minRole } : {}),
144
+ ...(o.stops ? { stops: o.stops } : {}),
142
145
  });
143
146
  return { ...got, log };
144
147
  }
@@ -351,6 +354,78 @@ describe("pollNoteCommands: apply on a merged merge request", () => {
351
354
  });
352
355
  });
353
356
 
357
+ describe("pollNoteCommands: the waves' stop and the waves before merge (#4984)", () => {
358
+ const members = { [uid("alice")]: 30 };
359
+ const pipelines = [{ id: 10, sha: MERGE, ref: "main", source: "push", status: "failed" }];
360
+ const applyJobs = { 10: [{ id: 2, name: "apply-wave-1", status: "success" }, { id: 3, name: "apply-wave-2", status: "failed" }] };
361
+ const waves = { op: "deploy", count: 3 };
362
+
363
+ test("a merged merge request's wave-<n> writes the stop for the merge commit before the retry, and an apply without one clears it", async () => {
364
+ const stops: unknown[] = [];
365
+ const stopsFn: NoteCommandsOptions["stops"] = async (op, sha, stop) => void stops.push([op, sha, stop && { through: stop.through, by: stop.by, pr: stop.pr }]);
366
+ const w: World = { mrs: [mr(3, { state: "merged", merge_commit_sha: MERGE })], notes: { 3: [note(41, "/plywood up wave-2")] }, members, pipelines, jobs: applyJobs };
367
+ const got = await poll(w, { jobs: { applyOnMerge: true, waves }, stops: stopsFn });
368
+ expect(stops).toEqual([["deploy", MERGE, { through: 2, by: "alice", pr: 3 }]]);
369
+ expect(posts(/\/retry$/)).toHaveLength(1);
370
+ expect(got.outcomes[0]!.reason).toMatch(/; it stops after `wave-2`, and the waves after it wait until `\/plywood up` runs it again$/);
371
+ await poll({ ...w, notes: { 3: [note(42, "/plywood up")] } }, { jobs: { applyOnMerge: true, waves }, stops: stopsFn });
372
+ expect(stops.at(-1)).toEqual(["deploy", MERGE, null]);
373
+ // A wave the waves do not have is refused before anything is written.
374
+ const over = await poll({ ...w, notes: { 3: [note(43, "/plywood up wave-4")] } }, { jobs: { applyOnMerge: true, waves }, stops: stopsFn });
375
+ expect(over.outcomes[0]!.reason).toBe("the update of this project runs in 3 waves, so there is no `wave-4`");
376
+ expect(stops).toHaveLength(2);
377
+ });
378
+
379
+ test("an open merge request's apply is decided, recorded, and started as a pipeline of the default branch with the decision's variables", async () => {
380
+ await withTestDir(async (dir) => {
381
+ const git = (...args: string[]) => {
382
+ const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8", env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" } });
383
+ if (r.status !== 0) throw new Error(r.stderr);
384
+ return r.stdout.trim();
385
+ };
386
+ // The default branch and the merge request's head ref, in one repository that is its own origin.
387
+ git("init", "-q", "-b", "main");
388
+ writeFileSync(join(dir, "main.tf"), "1");
389
+ git("add", ".");
390
+ git("commit", "-q", "-m", "base");
391
+ git("checkout", "-q", "-b", "feat-3");
392
+ writeFileSync(join(dir, "main.tf"), "2");
393
+ git("commit", "-q", "-am", "head");
394
+ const head = git("rev-parse", "HEAD");
395
+ git("update-ref", "refs/merge-requests/3/head", head);
396
+ git("checkout", "-q", "main");
397
+ git("remote", "add", "origin", dir);
398
+ const recorded: unknown[] = [];
399
+ const runs = chantNoteRuns(
400
+ { applyOnMerge: true, waves, wavesBeforeMerge: { plan: ["plywood/preview"], pipelineFiles: [".gitlab-ci.yml"] } },
401
+ {
402
+ beforeMerge: {
403
+ requires: async () => null,
404
+ statuses: async () => [{ context: "plywood/preview", state: "success" }],
405
+ git: (argv, o) => {
406
+ const r = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", ...(o.cwd ? { cwd: o.cwd } : {}) });
407
+ return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
408
+ },
409
+ cwd: dir,
410
+ record: async (d) => (recorded.push(d), { ...d, digest: beforeMergeDigest("deploy", d) }),
411
+ stop: async () => {},
412
+ now: () => NOW.toISOString(),
413
+ },
414
+ },
415
+ );
416
+ const w: World = { mrs: [mr(3, { sha: head })], notes: { 3: [note(41, "/plywood up")] }, members };
417
+ const got = await poll(w, { runs });
418
+ const started = posts(/^\/projects\/7\/pipeline$/);
419
+ expect(started).toHaveLength(1);
420
+ const vars = Object.fromEntries((started[0]!.body as { variables: Array<{ key: string; value: string }> }).variables.map((v) => [v.key, v.value]));
421
+ const decision = { pr: 3, head, base: git("rev-parse", "main"), at: NOW.toISOString(), by: "alice" };
422
+ expect(recorded).toEqual([decision]);
423
+ expect(vars).toEqual({ CHANT_BEFORE_MERGE_PR: "3", CHANT_BEFORE_MERGE_HEAD: head, CHANT_BEFORE_MERGE_DIGEST: beforeMergeDigest("deploy", decision) });
424
+ expect(got.outcomes[0]!.reason).toBe(`started pipeline http://gitlab/acme/infra/-/pipelines/78 on main to update !3's head ${head.slice(0, 8)} before it merges for alice`);
425
+ });
426
+ });
427
+ });
428
+
354
429
  describe("ledgerNoteLog", () => {
355
430
  const git = (dir: string, ...args: string[]): void => {
356
431
  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });