@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
@@ -0,0 +1,355 @@
1
+ /**
2
+ * `rest` waves in a split pipeline (#4992): one wave per run, each run
3
+ * starting the next.
4
+ *
5
+ * Maintainer decision (2026-11-10): a follow-on run. Before merge (and on a
6
+ * push of the same pipeline) each wave is four jobs (./op-waves-split.ts),
7
+ * and the jobs of a wave the plan finds at run time cannot be rendered up
8
+ * front. So the rest wave's four jobs (the last rendered wave, N) run wave
9
+ * N in a run, and their record job, once every wave of the run applied and
10
+ * the plan found more waves, starts the waves workflow again for wave N+1:
11
+ *
12
+ * - GitHub and Forgejo dispatch the workflow on its branch with the inputs
13
+ * `wave` and, before merge, `pr`, `head` and `digest`, or, for a push,
14
+ * `commit` (the pushed commit, which every job of the follow-on checks
15
+ * out and checks is on the branch). GitHub dispatches with the job's
16
+ * token (`actions: write` on that job alone); Forgejo with the
17
+ * `CHANT_FORGE_TOKEN` secret, as its resume does.
18
+ * - GitLab starts a pipeline of the branch with the same values as
19
+ * variables (`CHANT_WAVES_WAVE`, the decision's three or
20
+ * `CHANT_WAVES_COMMIT`), with `CHANT_FORGE_TOKEN`, since the job token
21
+ * cannot start one.
22
+ *
23
+ * In the follow-on the jobs of waves 1 to N-1 do not run, and the rest
24
+ * wave's jobs run wave N+1 (`--wave "${CHANT_WAVES_WAVE:-N}"`, and their
25
+ * files at that wave's paths, {@link opWaveRestPath}). The guard admits the
26
+ * run as the same decided head (./follow-on-run.ts). It goes on until the
27
+ * wave the plan found last.
28
+ *
29
+ * The record job leaves a note in the outcome directory
30
+ * ({@link OP_WAVE_REST_NOTE}): the wave it ran, how many the plan found, and
31
+ * the wave it started, if it started one. `before-merge-done`, the control
32
+ * dispatch and the apply status read it, so a run that started a follow-on
33
+ * is not the last: nothing merges, the control repo hears from the last
34
+ * run, and the status stays pending with `wave k of M applied`.
35
+ *
36
+ * #4998: before it starts a follow-on, the record job records it on
37
+ * `chant/lifecycle` (./follow-on-run.ts, ./follow-on-store.ts): the wave it
38
+ * starts, its own run, the decision or the pushed commit, and the outcomes
39
+ * of every run of the chain so far, its own added. The follow-on's guard
40
+ * admits that wave alone. A follow-on's record job reads the record that
41
+ * started it and puts the earlier runs' outcomes in its note as `chain`, so
42
+ * the last run's control dispatch and apply status add up the whole chain
43
+ * ({@link withChainOutcomes}): a chain whose last wave changed nothing
44
+ * reports `applied` when an earlier run applied.
45
+ */
46
+ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
47
+ import { isAbsolute, join } from "node:path";
48
+ import { CHANT_EXIT } from "../exit-codes.js";
49
+ import { CONTROL_OUTCOME_VAR } from "../control/dispatch.js";
50
+ import { beforeMergeRunFromEnv, isBeforeMergeRun } from "./before-merge.js";
51
+ import { OP_WAVES_COMMIT_ENV, OP_WAVES_WAVE_ENV } from "./follow-on-run.js";
52
+ import { opWaveOutcomeDir, opWaveRecordPath } from "./op-waves.js";
53
+ export { FOLLOW_ON_INPUTS, OP_WAVES_COMMIT_ENV, OP_WAVES_WAVE_ENV } from "./follow-on-run.js";
54
+ /** The variable the rest wave's record job is told how to start a follow-on in: `{ "forge": ..., "workflow": ... }` as JSON. */
55
+ export const OP_WAVES_FOLLOW_ON_ENV = "CHANT_WAVES_FOLLOW_ON";
56
+ /**
57
+ * The variable the rest wave's record step hands the token that starts the
58
+ * follow-on in (GitHub: the job's token; Forgejo: the `CHANT_FORGE_TOKEN`
59
+ * secret), so no other line of the job reads it as the forge's token.
60
+ * Unset (GitLab), the record job reads {@link FORGE_TOKEN_VAR}.
61
+ */
62
+ export const FOLLOW_ON_TOKEN_ENV = "CHANT_WAVES_FOLLOW_ON_TOKEN";
63
+ /** The secret (Forgejo) or CI/CD variable (GitLab) a token that may start a run is kept in. */
64
+ export const FORGE_TOKEN_VAR = "CHANT_FORGE_TOKEN";
65
+ /** The rest wave's number when the spec's last wave has `rest`, else undefined. */
66
+ export function opWavesRestWave(spec) {
67
+ return spec.waves[spec.waves.length - 1]?.rest === true ? spec.waves.length : undefined;
68
+ }
69
+ /**
70
+ * A path of the rest wave's (`wave-N.json`, `wave-N/`, `outcome-wave-N-apply.json`,
71
+ * `run-record-wave-N.json`) with its wave number put as `token`, the form
72
+ * the forge reads `CHANT_WAVES_WAVE` in at that place.
73
+ */
74
+ export function opWaveRestPath(path, wave, token) {
75
+ return path.replace(new RegExp(`(^|[/-])wave-${wave}(?=[./-]|$)`, "g"), (_m, lead) => `${lead}wave-${token}`);
76
+ }
77
+ /** The value of {@link OP_WAVES_FOLLOW_ON_ENV} for a forge. */
78
+ export function opWavesFollowOnEnv(target) {
79
+ return JSON.stringify(target);
80
+ }
81
+ /** Read {@link OP_WAVES_FOLLOW_ON_ENV}; undefined when unset, and a value that is no target throws. */
82
+ export function parseFollowOnTarget(raw) {
83
+ if (raw === undefined || raw.trim() === "")
84
+ return undefined;
85
+ let v;
86
+ try {
87
+ v = JSON.parse(raw);
88
+ }
89
+ catch {
90
+ throw new Error(`${OP_WAVES_FOLLOW_ON_ENV} is not JSON`);
91
+ }
92
+ const o = v;
93
+ if (!o || (o.forge !== "github" && o.forge !== "forgejo" && o.forge !== "gitlab"))
94
+ throw new Error(`${OP_WAVES_FOLLOW_ON_ENV}.forge is github, forgejo or gitlab`);
95
+ if (o.forge !== "gitlab" && (typeof o.workflow !== "string" || !/^[A-Za-z0-9._-]+\.ya?ml$/.test(o.workflow)))
96
+ throw new Error(`${OP_WAVES_FOLLOW_ON_ENV}.workflow names the waves workflow's file`);
97
+ return { forge: o.forge, ...(o.workflow ? { workflow: o.workflow } : {}) };
98
+ }
99
+ /**
100
+ * The lines every job of the rest wave runs after its checkout (#4992): in
101
+ * a push's follow-on, stop (exit 9, `misplaced`) unless the commit it goes
102
+ * on with is on the branch the run checked out, then check that commit
103
+ * out. Nothing in any other run. The guard checked it is a commit sha.
104
+ */
105
+ export function followOnCommitScript(product) {
106
+ return [
107
+ `if [ -n "\${${OP_WAVES_COMMIT_ENV}:-}" ]; then`,
108
+ ` git merge-base --is-ancestor "$${OP_WAVES_COMMIT_ENV}" HEAD || { echo "${product}: the follow-on's commit $(printf %.12s "$${OP_WAVES_COMMIT_ENV}") is not on the branch this run checked out, so nothing is applied" >&2; exit ${CHANT_EXIT.misplaced}; }`,
109
+ ` git checkout -q --detach "$${OP_WAVES_COMMIT_ENV}" || exit 1`,
110
+ "fi",
111
+ ].join("\n");
112
+ }
113
+ /**
114
+ * The first line of the control dispatch's script in a pipeline with a rest
115
+ * wave (#4992): `chant run wave --waves-outcome` adds up nothing for a run
116
+ * that started a follow-on, and the dispatch sends nothing then; the last
117
+ * run of the waves sends the outcome.
118
+ */
119
+ export function followOnControlSkip(product) {
120
+ return `if [ -z "\${${CONTROL_OUTCOME_VAR}:-}" ]; then echo "${product}: this run started a follow-on run for the next wave, which tells the control repo how the waves ended"; exit 0; fi`;
121
+ }
122
+ /** The note the rest wave's record job leaves in the outcome directory. */
123
+ export const OP_WAVE_REST_NOTE = "rest-wave.json";
124
+ /** The outcomes of a chain's runs: a valid entry of each, the rest dropped. */
125
+ function chainOf(v) {
126
+ if (!v || typeof v !== "object")
127
+ return undefined;
128
+ const out = {};
129
+ for (const [member, o] of Object.entries(v)) {
130
+ if (!o || typeof o.status !== "string" || !Number.isInteger(o.wave) || typeof o.at !== "string" || (o.by !== undefined && typeof o.by !== "string"))
131
+ continue;
132
+ out[member] = { status: o.status, ...(o.by !== undefined ? { by: o.by } : {}), wave: o.wave, at: o.at };
133
+ }
134
+ return Object.keys(out).length > 0 ? out : undefined;
135
+ }
136
+ /**
137
+ * The outcomes the jobs after the waves add up (#4998): this run's, from
138
+ * its outcome files (`members`, `earlierWaveOutcomes` below wave `before`),
139
+ * with the chain's earlier runs' from the rest wave's note. A member's
140
+ * newer outcome wins. With no note, or one with no chain, `members`.
141
+ */
142
+ export function withChainOutcomes(members, note, before = Number.MAX_SAFE_INTEGER) {
143
+ const out = new Map();
144
+ for (const [member, o] of Object.entries(note?.chain ?? {}))
145
+ if (o.wave < before)
146
+ out.set(member, o);
147
+ for (const [member, o] of members) {
148
+ const had = out.get(member);
149
+ if (!had || had.at <= o.at)
150
+ out.set(member, o);
151
+ }
152
+ return out;
153
+ }
154
+ /** Where the record job writes the note. */
155
+ export function opWaveRestNotePath(spec) {
156
+ return `${opWaveOutcomeDir(spec)}/${OP_WAVE_REST_NOTE}`;
157
+ }
158
+ /** The note under `dirs` (downloaded artifacts keep it in a directory of their own, four deep at most), the newest wave's when there are more. */
159
+ export function readOpWaveRestNote(dirs) {
160
+ let found;
161
+ const walk = (dir, depth) => {
162
+ let names;
163
+ try {
164
+ names = readdirSync(dir);
165
+ }
166
+ catch {
167
+ return;
168
+ }
169
+ for (const name of names) {
170
+ const abs = join(dir, name);
171
+ let isDir = false;
172
+ try {
173
+ isDir = statSync(abs).isDirectory();
174
+ }
175
+ catch {
176
+ continue;
177
+ }
178
+ if (isDir) {
179
+ if (depth < 4)
180
+ walk(abs, depth + 1);
181
+ continue;
182
+ }
183
+ if (name !== OP_WAVE_REST_NOTE)
184
+ continue;
185
+ let v;
186
+ try {
187
+ v = JSON.parse(readFileSync(abs, "utf-8"));
188
+ }
189
+ catch {
190
+ continue;
191
+ }
192
+ if (!v || v.version !== 1 || typeof v.op !== "string" || !Number.isInteger(v.wave) || !Number.isInteger(v.found))
193
+ continue;
194
+ if (v.next !== undefined && (!Number.isInteger(v.next) || v.next !== v.wave + 1))
195
+ continue;
196
+ const chain = chainOf(v.chain);
197
+ if (!found || v.wave > found.wave)
198
+ found = { version: 1, op: v.op, wave: v.wave, found: v.found, ...(v.next !== undefined ? { next: v.next } : {}), ...(chain ? { chain } : {}) };
199
+ }
200
+ };
201
+ for (const d of dirs)
202
+ if (existsSync(d))
203
+ walk(d, 0);
204
+ return found;
205
+ }
206
+ /** What a chain is keyed by and what its record names (#4998): before merge the decision, for a push the commit the run applied. */
207
+ export function followOnChainOf(forge, env) {
208
+ const run = beforeMergeRunFromEnv(env);
209
+ if (isBeforeMergeRun(run))
210
+ return run.head ? { key: run.head, ...(run.pr && /^[1-9][0-9]*$/.test(run.pr) ? { pr: Number(run.pr) } : {}), ...(run.digest ? { digest: run.digest } : {}) } : undefined;
211
+ const commit = env[OP_WAVES_COMMIT_ENV]?.trim() || (forge === "gitlab" ? env.CI_COMMIT_SHA : env.GITHUB_SHA)?.trim();
212
+ return commit ? { key: commit, commit } : undefined;
213
+ }
214
+ /** The run a record job runs in, as the record names it: GitHub and Forgejo `GITHUB_RUN_ID`, GitLab `CI_PIPELINE_ID`, and its page when the forge says. */
215
+ function runOf(forge, env) {
216
+ if (forge === "gitlab") {
217
+ const url = env.CI_PIPELINE_URL?.trim();
218
+ return { run: env.CI_PIPELINE_ID?.trim() || "unknown", ...(url && /^https?:\/\//.test(url) ? { url } : {}) };
219
+ }
220
+ const id = env.GITHUB_RUN_ID?.trim();
221
+ const server = env.GITHUB_SERVER_URL?.trim().replace(/\/+$/, "");
222
+ const repo = env.GITHUB_REPOSITORY?.trim();
223
+ return { run: id || "unknown", ...(forge === "github" && id && server && repo && /^https?:\/\//.test(server) ? { url: `${server}/${repo}/actions/runs/${id}` } : {}) };
224
+ }
225
+ /**
226
+ * After the rest wave's record job wrote its run records (#4992): leave the
227
+ * note, and when the run applied every wave it ran and the plan found more,
228
+ * start the follow-on for the next one. Resolves to the job's exit: the
229
+ * record job's own, or failed when the follow-on could not be started (the
230
+ * note still says it was to be, so nothing after the run takes it for the
231
+ * last). A job that is not the rest wave's, or whose pipeline sets no
232
+ * {@link OP_WAVES_FOLLOW_ON_ENV}, is left as it is.
233
+ */
234
+ export async function followOnAfterRecord(i) {
235
+ const env = i.env ?? process.env;
236
+ const log = i.log ?? ((line) => console.error(line));
237
+ const rest = opWavesRestWave(i.spec);
238
+ if (rest === undefined || i.wave < rest)
239
+ return i.exitCode;
240
+ const target = parseFollowOnTarget(env[OP_WAVES_FOLLOW_ON_ENV]);
241
+ if (!target)
242
+ return i.exitCode;
243
+ const cwd = i.cwd ?? process.cwd();
244
+ let found;
245
+ try {
246
+ const decision = JSON.parse(readFileSync(join(cwd, opWaveRecordPath(i.spec, i.wave)), "utf-8"));
247
+ const w = decision?.discovered?.waves;
248
+ if (Number.isInteger(w))
249
+ found = w;
250
+ }
251
+ catch {
252
+ found = undefined;
253
+ }
254
+ const outcomeDir = opWaveOutcomeDir(i.spec);
255
+ const dir = isAbsolute(outcomeDir) ? outcomeDir : join(cwd, outcomeDir);
256
+ const { earlierWaveOutcomes } = await import("../wave-blocked.js");
257
+ const { applyOutcomeOf } = await import("../control/applied.js");
258
+ const own = earlierWaveOutcomes([dir], Number.MAX_SAFE_INTEGER).members;
259
+ const summary = applyOutcomeOf(own);
260
+ const through = summary.outcome === "applied" || summary.outcome === "unchanged";
261
+ const next = i.exitCode === CHANT_EXIT.done && through && found !== undefined && found > i.wave ? i.wave + 1 : undefined;
262
+ // #4998: a follow-on's record job reads the record that started it, for the outcomes of the chain's earlier runs.
263
+ const chainKey = followOnChainOf(target.forge, env);
264
+ let port = i.chain;
265
+ const chainPort = async () => (port ?? (port = (await import("./follow-on-store.js")).gitFollowOnChainPort({ cwd })));
266
+ let chain = {};
267
+ if (i.wave > rest && chainKey) {
268
+ try {
269
+ const started = await (await chainPort()).read(i.spec.name, chainKey.key);
270
+ if (started && started.wave === i.wave)
271
+ chain = started.outcomes;
272
+ else
273
+ log(`wave ${i.wave}: no record on chant/lifecycle started this wave for ${chainKey.key.slice(0, 12)}, so the outcomes of the chain's earlier runs are not added up`);
274
+ }
275
+ catch (err) {
276
+ log(`wave ${i.wave}: the record that started this run could not be read (${(err instanceof Error ? err.message : String(err)).split("\n")[0]}), so the outcomes of the chain's earlier runs are not added up`);
277
+ }
278
+ }
279
+ mkdirSync(dir, { recursive: true });
280
+ const note = { version: 1, op: i.spec.name, wave: i.wave, found: found ?? i.wave, ...(next !== undefined ? { next } : {}), ...(Object.keys(chain).length > 0 ? { chain } : {}) };
281
+ writeFileSync(join(dir, OP_WAVE_REST_NOTE), JSON.stringify(note, null, 2) + "\n");
282
+ if (next === undefined) {
283
+ if (found !== undefined && found > i.wave)
284
+ log(`wave ${i.wave}: the plan found ${found} waves, and this run ended ${summary.outcome} (exit ${i.exitCode}), so no run starts wave ${i.wave + 1}`);
285
+ return i.exitCode;
286
+ }
287
+ // #4998: record the follow-on before it starts: its guard admits the wave this record names, and no other.
288
+ try {
289
+ if (!chainKey)
290
+ throw new Error("the run names no decided head and no commit to go on with");
291
+ const outcomes = {};
292
+ for (const [member, o] of withChainOutcomes(own, note))
293
+ outcomes[member] = { status: o.status, ...(o.by !== undefined ? { by: o.by } : {}), wave: o.wave, at: o.at };
294
+ const record = { ...chainKey, wave: next, from: i.wave, ...runOf(target.forge, env), at: (i.now ?? (() => new Date()))().toISOString(), outcomes };
295
+ await (await chainPort()).write(i.spec.name, record);
296
+ }
297
+ catch (err) {
298
+ const message = err instanceof Error ? err.message : String(err);
299
+ log(`wave ${i.wave} applied, and the follow-on for wave ${next} could not be recorded on chant/lifecycle (${message.split("\n")[0]}), so none is started: its guard would refuse it`);
300
+ return CHANT_EXIT.failed;
301
+ }
302
+ try {
303
+ const started = await (i.start ?? startFollowOn)(target, next, env);
304
+ log(`wave ${i.wave} applied; the plan found ${found} waves, so a follow-on run${started.url ? ` (${started.url})` : ""} goes on with wave ${next}`);
305
+ return i.exitCode;
306
+ }
307
+ catch (err) {
308
+ const message = err instanceof Error ? err.message : String(err);
309
+ log(`wave ${i.wave} applied, and the follow-on run for wave ${next} could not be started (${message.split("\n")[0]}); start the waves workflow by hand with ${OP_WAVES_WAVE_ENV}=${next} and this run's other inputs`);
310
+ return CHANT_EXIT.failed;
311
+ }
312
+ }
313
+ /**
314
+ * Start the follow-on run for wave `wave` through the forge's API: the
315
+ * values the run carries come from the record job's own variables (the
316
+ * decision, or the commit the run applied).
317
+ */
318
+ export async function startFollowOn(target, wave, env, fetchFn = fetch) {
319
+ const run = beforeMergeRunFromEnv(env);
320
+ const bm = isBeforeMergeRun(run);
321
+ const commit = bm ? undefined : followOnChainOf(target.forge, env)?.commit;
322
+ if (!bm && !commit)
323
+ throw new Error("the run names no commit to go on with");
324
+ const values = bm ? { pr: run.pr, head: run.head, digest: run.digest, wave: String(wave) } : { wave: String(wave), commit: commit };
325
+ const { forgeTargetFromEnv } = await import("../pr-forge.js");
326
+ const tokenEnv = [FOLLOW_ON_TOKEN_ENV, FORGE_TOKEN_VAR].find((n) => env[n]?.trim());
327
+ const t = forgeTargetFromEnv(env, { kind: target.forge, ...(tokenEnv ? { tokenEnv } : {}) });
328
+ const post = async (url, headers, body) => {
329
+ const res = await fetchFn(url, { method: "POST", headers: { ...headers, Accept: "application/json", "Content-Type": "application/json" }, body: JSON.stringify(body) });
330
+ const text = await res.text();
331
+ if (!res.ok)
332
+ throw new Error(`POST ${url} answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
333
+ try {
334
+ return text ? JSON.parse(text) : null;
335
+ }
336
+ catch {
337
+ return null;
338
+ }
339
+ };
340
+ if (target.forge === "gitlab") {
341
+ const ref = env.CI_COMMIT_REF_NAME;
342
+ if (!ref)
343
+ throw new Error("the job names no branch (no CI_COMMIT_REF_NAME)");
344
+ const names = { pr: "CHANT_BEFORE_MERGE_PR", head: "CHANT_BEFORE_MERGE_HEAD", digest: "CHANT_BEFORE_MERGE_DIGEST", wave: OP_WAVES_WAVE_ENV, commit: OP_WAVES_COMMIT_ENV };
345
+ const variables = Object.entries(values).map(([k, value]) => ({ key: names[k], value, variable_type: "env_var" }));
346
+ const project = encodeURIComponent(decodeURIComponent(t.repo));
347
+ const v = (await post(`${t.apiBase}/projects/${project}/pipeline`, { [t.tokenHeader ?? "PRIVATE-TOKEN"]: t.token }, { ref, variables }));
348
+ return typeof v?.web_url === "string" && /^https?:\/\//.test(v.web_url) ? { url: v.web_url } : {};
349
+ }
350
+ const ref = env.GITHUB_REF_NAME?.trim() || env.GITHUB_REF?.replace(/^refs\/heads\//, "");
351
+ if (!ref)
352
+ throw new Error("the job names no branch (no GITHUB_REF_NAME)");
353
+ await post(`${t.apiBase}/repos/${t.repo}/actions/workflows/${encodeURIComponent(target.workflow)}/dispatches`, { Authorization: `token ${t.token}` }, { ref, inputs: values });
354
+ return {};
355
+ }
@@ -0,0 +1,100 @@
1
+ /**
2
+ * A waves spec the job renders at run time (#4982).
3
+ *
4
+ * A generated waves pipeline reads its spec from the file at `specFile`,
5
+ * and each wave job reads the gate policy from that file at the base
6
+ * commit. A product whose spec is built from its own config (terragucci
7
+ * builds `tf-apply` from `terragucci.yml` at base: the gate per
8
+ * environment, the approval mode, the policy and cost holds) cannot commit
9
+ * the spec once, so it used to render its own apply-wave jobs.
10
+ *
11
+ * With `renderSpec` on the generator's options, every wave, deciding and
12
+ * share job, and the policy step, runs `chant run wave --render-spec`, and
13
+ * `CHANT_WAVES_SPEC_COMMAND` on the job holds the product command that
14
+ * prints the spec, as a JSON argv. chant runs that command with
15
+ * `CHANT_WAVES_SPEC_AT` set to a commit and reads the spec from its
16
+ * standard output:
17
+ *
18
+ * - at the base, for the spec the job runs, which chant writes over the
19
+ * file at `specFile` so the hooks, the decision record and the share
20
+ * jobs read the same one;
21
+ * - at the base again, for the gate policy, the holds, the hooks and the
22
+ * evidence rules (`readOpWavePolicy`), in place of `git show
23
+ * <base>:<specFile>`;
24
+ * - at a newer commit on the branch, for the stand-down (#4581).
25
+ *
26
+ * The command's output is the gate policy, so it must read the product's
27
+ * config at the commit it is handed (`git show "$CHANT_WAVES_SPEC_AT:<file>"`),
28
+ * never from the working tree, which holds the change. It exits 0 and
29
+ * prints nothing when that commit has no config, which reads as a spec
30
+ * missing at base: every wave's gate is `always`. Any other exit fails the
31
+ * job.
32
+ *
33
+ * The spec the generator is handed is the pipeline's shape: its waves'
34
+ * names, shares and job groups, runners, environments, `cloud` and
35
+ * `holds.policy` decide the jobs and their steps. The rendered spec decides
36
+ * the rules. A share or job group the shape has and the rendered spec does
37
+ * not applies nothing and exits 0, since the job exists before the runs
38
+ * are known.
39
+ *
40
+ * Nothing here imports the wave runner, so the generators' bundles take
41
+ * the variables without it; `chant run wave` hands in its git reader.
42
+ */
43
+ import type { OpWaveShowAtBase } from "./op-waves-run.js";
44
+ import type { OpWavesSpec } from "./op-waves.js";
45
+ export { RUNTIME_WAVES_SPEC_FLOOR } from "../release-floors.js";
46
+ /** The job variable that holds the product command printing the spec, as a JSON argv. */
47
+ export declare const OP_WAVES_SPEC_COMMAND_ENV = "CHANT_WAVES_SPEC_COMMAND";
48
+ /** The variable chant hands that command: the full commit to render the spec at. */
49
+ export declare const OP_WAVES_SPEC_AT_ENV = "CHANT_WAVES_SPEC_AT";
50
+ /** The variable chant hands that command: the spec file's path, as the job names it. */
51
+ export declare const OP_WAVES_SPEC_FILE_ENV = "CHANT_WAVES_SPEC_FILE";
52
+ /** The `chant run wave` flag that renders the spec before the job runs. */
53
+ export declare const OP_WAVES_RENDER_SPEC_FLAG = "--render-spec";
54
+ /** `OpWavesPipelineOptions.renderSpec` (#4982). */
55
+ export interface OpWavesRenderSpec {
56
+ /** The product command that prints the spec at `CHANT_WAVES_SPEC_AT`, such as `["terragucci", "waves-spec"]`. */
57
+ command: string[];
58
+ }
59
+ /** What is wrong with a `renderSpec`, or nothing. */
60
+ export declare function opWavesRenderSpecProblems(value: unknown): string[];
61
+ /** The variables a wave job carries for `renderSpec`, or none without it. Throws on a `renderSpec` that is wrong. */
62
+ export declare function opWavesRenderSpecEnv(renderSpec: OpWavesRenderSpec | undefined): Record<string, string>;
63
+ /** The product command `CHANT_WAVES_SPEC_COMMAND` names. Throws when it is unset or not a JSON list of words. */
64
+ export declare function opWavesSpecCommandFromEnv(env?: NodeJS.ProcessEnv): string[];
65
+ /** Prints the spec at a full commit, or null when that commit has none. Injected for tests. */
66
+ export type OpWavesSpecRender = (sha: string) => string | null;
67
+ /** {@link OpWavesSpecRender} through the product's command, run in `cwd`. Its standard error goes to the job's log. */
68
+ export declare function commandSpecRender(command: readonly string[], specFile: string, cwd: string): OpWavesSpecRender;
69
+ /**
70
+ * An {@link OpWaveShowAtBase} that reads `specFile` at any commit from
71
+ * `render`, once per commit, and every other file through `fallback`
72
+ * (git, `gitShowAtBase`), which also resolves the commit.
73
+ */
74
+ export declare function renderedSpecShow(specFile: string, render: OpWavesSpecRender, fallback: OpWaveShowAtBase): OpWaveShowAtBase;
75
+ /**
76
+ * Render the job's spec at `base` (#4982): read it through `show`, parse it
77
+ * with `parse` (`parseOpWavesSpec`), write it over `specFile` in `cwd`, and
78
+ * return it. Throws when the command printed no spec, or one chant cannot
79
+ * read.
80
+ */
81
+ export declare function renderOpWavesSpecFile(options: {
82
+ specFile: string;
83
+ base: string;
84
+ cwd: string;
85
+ show: OpWaveShowAtBase;
86
+ parse: (text: string, where: string) => OpWavesSpec;
87
+ }): {
88
+ spec: OpWavesSpec;
89
+ sha: string;
90
+ };
91
+ /**
92
+ * Whether job `job` of wave `k` has anything in the rendered spec: a share
93
+ * past the wave's (or the group's) shares, or a group the wave does not
94
+ * have, has nothing. Undefined when it has; otherwise why not.
95
+ */
96
+ export declare function renderedJobMissing(spec: OpWavesSpec, k: number, job: {
97
+ share?: number;
98
+ group?: string;
99
+ }): string | undefined;
100
+ //# sourceMappingURL=op-waves-render-spec.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"op-waves-render-spec.d.ts","sourceRoot":"","sources":["../../src/op/op-waves-render-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,yFAAyF;AACzF,eAAO,MAAM,yBAAyB,6BAA6B,CAAC;AACpE,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,wBAAwB,CAAC;AAC1D,wFAAwF;AACxF,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAC9D,2EAA2E;AAC3E,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,iHAAiH;IACjH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,qDAAqD;AACrD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAMlE;AAED,qHAAqH;AACrH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKtG;AAED,iHAAiH;AACjH,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,EAAE,CAWxF;AAED,+FAA+F;AAC/F,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAE/D,uHAAuH;AACvH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAiB9G;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,CAS1H;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,WAAW,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAQ/M;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CAW5H"}
@@ -0,0 +1,162 @@
1
+ /**
2
+ * A waves spec the job renders at run time (#4982).
3
+ *
4
+ * A generated waves pipeline reads its spec from the file at `specFile`,
5
+ * and each wave job reads the gate policy from that file at the base
6
+ * commit. A product whose spec is built from its own config (terragucci
7
+ * builds `tf-apply` from `terragucci.yml` at base: the gate per
8
+ * environment, the approval mode, the policy and cost holds) cannot commit
9
+ * the spec once, so it used to render its own apply-wave jobs.
10
+ *
11
+ * With `renderSpec` on the generator's options, every wave, deciding and
12
+ * share job, and the policy step, runs `chant run wave --render-spec`, and
13
+ * `CHANT_WAVES_SPEC_COMMAND` on the job holds the product command that
14
+ * prints the spec, as a JSON argv. chant runs that command with
15
+ * `CHANT_WAVES_SPEC_AT` set to a commit and reads the spec from its
16
+ * standard output:
17
+ *
18
+ * - at the base, for the spec the job runs, which chant writes over the
19
+ * file at `specFile` so the hooks, the decision record and the share
20
+ * jobs read the same one;
21
+ * - at the base again, for the gate policy, the holds, the hooks and the
22
+ * evidence rules (`readOpWavePolicy`), in place of `git show
23
+ * <base>:<specFile>`;
24
+ * - at a newer commit on the branch, for the stand-down (#4581).
25
+ *
26
+ * The command's output is the gate policy, so it must read the product's
27
+ * config at the commit it is handed (`git show "$CHANT_WAVES_SPEC_AT:<file>"`),
28
+ * never from the working tree, which holds the change. It exits 0 and
29
+ * prints nothing when that commit has no config, which reads as a spec
30
+ * missing at base: every wave's gate is `always`. Any other exit fails the
31
+ * job.
32
+ *
33
+ * The spec the generator is handed is the pipeline's shape: its waves'
34
+ * names, shares and job groups, runners, environments, `cloud` and
35
+ * `holds.policy` decide the jobs and their steps. The rendered spec decides
36
+ * the rules. A share or job group the shape has and the rendered spec does
37
+ * not applies nothing and exits 0, since the job exists before the runs
38
+ * are known.
39
+ *
40
+ * Nothing here imports the wave runner, so the generators' bundles take
41
+ * the variables without it; `chant run wave` hands in its git reader.
42
+ */
43
+ import { execFileSync } from "node:child_process";
44
+ import { writeFileSync, mkdirSync } from "node:fs";
45
+ import { dirname, isAbsolute, join, posix } from "node:path";
46
+ export { RUNTIME_WAVES_SPEC_FLOOR } from "../release-floors.js";
47
+ /** The job variable that holds the product command printing the spec, as a JSON argv. */
48
+ export const OP_WAVES_SPEC_COMMAND_ENV = "CHANT_WAVES_SPEC_COMMAND";
49
+ /** The variable chant hands that command: the full commit to render the spec at. */
50
+ export const OP_WAVES_SPEC_AT_ENV = "CHANT_WAVES_SPEC_AT";
51
+ /** The variable chant hands that command: the spec file's path, as the job names it. */
52
+ export const OP_WAVES_SPEC_FILE_ENV = "CHANT_WAVES_SPEC_FILE";
53
+ /** The `chant run wave` flag that renders the spec before the job runs. */
54
+ export const OP_WAVES_RENDER_SPEC_FLAG = "--render-spec";
55
+ /** What is wrong with a `renderSpec`, or nothing. */
56
+ export function opWavesRenderSpecProblems(value) {
57
+ const command = value?.command;
58
+ if (!Array.isArray(command) || command.length === 0 || command.some((w) => typeof w !== "string" || w.length === 0)) {
59
+ return ['renderSpec.command must be the product command that prints the spec, as a list of words: ["terragucci", "waves-spec"]'];
60
+ }
61
+ return [];
62
+ }
63
+ /** The variables a wave job carries for `renderSpec`, or none without it. Throws on a `renderSpec` that is wrong. */
64
+ export function opWavesRenderSpecEnv(renderSpec) {
65
+ if (renderSpec === undefined)
66
+ return {};
67
+ const problems = opWavesRenderSpecProblems(renderSpec);
68
+ if (problems.length > 0)
69
+ throw new Error(problems.join("; "));
70
+ return { [OP_WAVES_SPEC_COMMAND_ENV]: JSON.stringify(renderSpec.command) };
71
+ }
72
+ /** The product command `CHANT_WAVES_SPEC_COMMAND` names. Throws when it is unset or not a JSON list of words. */
73
+ export function opWavesSpecCommandFromEnv(env = process.env) {
74
+ const raw = env[OP_WAVES_SPEC_COMMAND_ENV];
75
+ if (!raw)
76
+ throw new Error(`${OP_WAVES_RENDER_SPEC_FLAG} runs the command ${OP_WAVES_SPEC_COMMAND_ENV} names, and it is unset`);
77
+ let command;
78
+ try {
79
+ command = JSON.parse(raw);
80
+ }
81
+ catch {
82
+ command = undefined;
83
+ }
84
+ if (opWavesRenderSpecProblems({ command }).length > 0)
85
+ throw new Error(`${OP_WAVES_SPEC_COMMAND_ENV} must be a JSON list of words, such as ["terragucci","waves-spec"]: got ${raw}`);
86
+ return command;
87
+ }
88
+ /** {@link OpWavesSpecRender} through the product's command, run in `cwd`. Its standard error goes to the job's log. */
89
+ export function commandSpecRender(command, specFile, cwd) {
90
+ return (sha) => {
91
+ let out;
92
+ try {
93
+ out = execFileSync(command[0], command.slice(1), {
94
+ cwd,
95
+ encoding: "utf-8",
96
+ stdio: ["ignore", "pipe", "inherit"],
97
+ env: { ...process.env, [OP_WAVES_SPEC_AT_ENV]: sha, [OP_WAVES_SPEC_FILE_ENV]: specFile },
98
+ maxBuffer: 64 * 1024 * 1024,
99
+ });
100
+ }
101
+ catch (err) {
102
+ const status = err.status;
103
+ throw new Error(`the spec command (${command.join(" ")}) ${typeof status === "number" ? `exited ${status}` : `did not run: ${err instanceof Error ? err.message : String(err)}`} at ${sha.slice(0, 12)}, so the wave's spec cannot be read`);
104
+ }
105
+ return out.trim() === "" ? null : out;
106
+ };
107
+ }
108
+ const posixPath = (p) => p.replace(/^\.\//, "").split("\\").join(posix.sep);
109
+ /**
110
+ * An {@link OpWaveShowAtBase} that reads `specFile` at any commit from
111
+ * `render`, once per commit, and every other file through `fallback`
112
+ * (git, `gitShowAtBase`), which also resolves the commit.
113
+ */
114
+ export function renderedSpecShow(specFile, render, fallback) {
115
+ const target = posixPath(specFile);
116
+ const seen = new Map();
117
+ return (base, path, cwd) => {
118
+ if (posixPath(path) !== target)
119
+ return fallback(base, path, cwd);
120
+ const { sha } = fallback(base, path, cwd);
121
+ if (!seen.has(sha))
122
+ seen.set(sha, render(sha));
123
+ return { sha, text: seen.get(sha) };
124
+ };
125
+ }
126
+ /**
127
+ * Render the job's spec at `base` (#4982): read it through `show`, parse it
128
+ * with `parse` (`parseOpWavesSpec`), write it over `specFile` in `cwd`, and
129
+ * return it. Throws when the command printed no spec, or one chant cannot
130
+ * read.
131
+ */
132
+ export function renderOpWavesSpecFile(options) {
133
+ const { sha, text } = options.show(options.base, options.specFile, options.cwd);
134
+ if (text === null)
135
+ throw new Error(`the spec command printed no spec at ${options.base} (${sha.slice(0, 12)}), so the wave has nothing to run`);
136
+ const spec = options.parse(text, `the spec rendered at ${sha.slice(0, 12)}`);
137
+ const path = isAbsolute(options.specFile) ? options.specFile : join(options.cwd, options.specFile);
138
+ mkdirSync(dirname(path), { recursive: true });
139
+ writeFileSync(path, text.endsWith("\n") ? text : `${text}\n`);
140
+ return { spec, sha };
141
+ }
142
+ /**
143
+ * Whether job `job` of wave `k` has anything in the rendered spec: a share
144
+ * past the wave's (or the group's) shares, or a group the wave does not
145
+ * have, has nothing. Undefined when it has; otherwise why not.
146
+ */
147
+ export function renderedJobMissing(spec, k, job) {
148
+ const wave = spec.waves[k - 1];
149
+ if (!wave)
150
+ return undefined;
151
+ if (job.group !== undefined) {
152
+ const group = wave.jobs?.find((g) => g.name === job.group);
153
+ if (!group)
154
+ return `wave ${k} (${wave.name}) has no job group "${job.group}" in the spec rendered at base`;
155
+ if (job.share !== undefined && job.share > (group.shares ?? 1))
156
+ return `job group "${job.group}" of wave ${k} (${wave.name}) has ${group.shares ?? 1} share${(group.shares ?? 1) === 1 ? "" : "s"} in the spec rendered at base`;
157
+ return undefined;
158
+ }
159
+ if (job.share !== undefined && wave.jobs === undefined && job.share > (wave.shares ?? 1))
160
+ return `wave ${k} (${wave.name}) has ${wave.shares ?? 1} share${(wave.shares ?? 1) === 1 ? "" : "s"} in the spec rendered at base`;
161
+ return undefined;
162
+ }