@intentius/chant 0.124.88 → 0.124.89

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 (303) 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 +177 -0
  10. package/dist/ci-comment-commands.d.ts.map +1 -0
  11. package/dist/ci-comment-commands.js +325 -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-note-commands.d.ts +63 -3
  25. package/dist/ci-note-commands.d.ts.map +1 -1
  26. package/dist/ci-note-commands.js +69 -35
  27. package/dist/ci-product-words.d.ts +42 -0
  28. package/dist/ci-product-words.d.ts.map +1 -1
  29. package/dist/ci-product-words.js +25 -0
  30. package/dist/ci-product.d.ts +31 -0
  31. package/dist/ci-product.d.ts.map +1 -1
  32. package/dist/ci-product.js +34 -4
  33. package/dist/cli/commands/build.d.ts.map +1 -1
  34. package/dist/cli/commands/build.js +29 -2
  35. package/dist/cli/handlers/approve.d.ts.map +1 -1
  36. package/dist/cli/handlers/approve.js +2 -1
  37. package/dist/cli/handlers/ci-check.d.ts +1 -1
  38. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  39. package/dist/cli/handlers/ci-check.js +17 -7
  40. package/dist/cli/handlers/ci-evidence.d.ts.map +1 -1
  41. package/dist/cli/handlers/ci-evidence.js +33 -7
  42. package/dist/cli/handlers/components.d.ts.map +1 -1
  43. package/dist/cli/handlers/components.js +3 -1
  44. package/dist/cli/handlers/generated-check.d.ts +8 -0
  45. package/dist/cli/handlers/generated-check.d.ts.map +1 -1
  46. package/dist/cli/handlers/generated-check.js +31 -1
  47. package/dist/cli/handlers/lock.d.ts.map +1 -1
  48. package/dist/cli/handlers/lock.js +121 -4
  49. package/dist/cli/handlers/pr-comment.d.ts +21 -0
  50. package/dist/cli/handlers/pr-comment.d.ts.map +1 -0
  51. package/dist/cli/handlers/pr-comment.js +112 -0
  52. package/dist/cli/handlers/pr-env.d.ts.map +1 -1
  53. package/dist/cli/handlers/pr-env.js +6 -3
  54. package/dist/cli/handlers/pr.d.ts +23 -1
  55. package/dist/cli/handlers/pr.d.ts.map +1 -1
  56. package/dist/cli/handlers/pr.js +55 -9
  57. package/dist/cli/handlers/promote.d.ts.map +1 -1
  58. package/dist/cli/handlers/promote.js +2 -1
  59. package/dist/cli/handlers/release.d.ts.map +1 -1
  60. package/dist/cli/handlers/release.js +11 -2
  61. package/dist/cli/handlers/run-wave.d.ts.map +1 -1
  62. package/dist/cli/handlers/run-wave.js +28 -2
  63. package/dist/cli/handlers/run.d.ts.map +1 -1
  64. package/dist/cli/handlers/run.js +2 -1
  65. package/dist/cli/main.d.ts.map +1 -1
  66. package/dist/cli/main.js +24 -2
  67. package/dist/cli/parse-args.d.ts.map +1 -1
  68. package/dist/cli/parse-args.js +16 -0
  69. package/dist/cli/registry.d.ts +11 -0
  70. package/dist/cli/registry.d.ts.map +1 -1
  71. package/dist/components/auto-release.d.ts.map +1 -1
  72. package/dist/components/auto-release.js +2 -1
  73. package/dist/components/pr-checks.d.ts +70 -6
  74. package/dist/components/pr-checks.d.ts.map +1 -1
  75. package/dist/components/pr-checks.js +74 -13
  76. package/dist/components/pr-pipeline.d.ts +16 -12
  77. package/dist/components/pr-pipeline.d.ts.map +1 -1
  78. package/dist/components/pr-pipeline.js +3 -11
  79. package/dist/components/product-pipeline.d.ts +42 -1
  80. package/dist/components/product-pipeline.d.ts.map +1 -1
  81. package/dist/components/product-pipeline.js +64 -12
  82. package/dist/components/product-plan.d.ts +190 -5
  83. package/dist/components/product-plan.d.ts.map +1 -1
  84. package/dist/components/product-plan.js +220 -39
  85. package/dist/drift-record.d.ts +7 -0
  86. package/dist/drift-record.d.ts.map +1 -1
  87. package/dist/drift-record.js +19 -0
  88. package/dist/floor-table.data.d.ts.map +1 -1
  89. package/dist/floor-table.data.js +54 -31
  90. package/dist/forge-check/contract.d.ts +11 -1
  91. package/dist/forge-check/contract.d.ts.map +1 -1
  92. package/dist/forge-check/contract.js +4 -1
  93. package/dist/forge-check/index.d.ts +2 -0
  94. package/dist/forge-check/index.d.ts.map +1 -1
  95. package/dist/forge-check/index.js +2 -0
  96. package/dist/gate-resume-run.d.ts +9 -1
  97. package/dist/gate-resume-run.d.ts.map +1 -1
  98. package/dist/gate-resume-run.js +26 -3
  99. package/dist/generated-check.d.ts +18 -4
  100. package/dist/generated-check.d.ts.map +1 -1
  101. package/dist/generated-check.js +37 -5
  102. package/dist/image-pins.d.ts +26 -0
  103. package/dist/image-pins.d.ts.map +1 -0
  104. package/dist/image-pins.js +19 -0
  105. package/dist/lexicon.d.ts +11 -0
  106. package/dist/lexicon.d.ts.map +1 -1
  107. package/dist/lifecycle/git.d.ts +11 -0
  108. package/dist/lifecycle/git.d.ts.map +1 -1
  109. package/dist/lifecycle/git.js +30 -3
  110. package/dist/lifecycle/publish-npm.d.ts +11 -0
  111. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  112. package/dist/lifecycle/publish-npm.js +27 -1
  113. package/dist/lifecycle/reach-locks.d.ts +131 -0
  114. package/dist/lifecycle/reach-locks.d.ts.map +1 -0
  115. package/dist/lifecycle/reach-locks.js +118 -0
  116. package/dist/lifecycle/release-cut.d.ts +3 -1
  117. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  118. package/dist/lifecycle/release-cut.js +15 -0
  119. package/dist/lifecycle/release-images.d.ts.map +1 -1
  120. package/dist/lifecycle/release-images.js +1 -2
  121. package/dist/notify-product.d.ts +12 -3
  122. package/dist/notify-product.d.ts.map +1 -1
  123. package/dist/notify-product.js +10 -6
  124. package/dist/op/activities/source-release.d.ts.map +1 -1
  125. package/dist/op/activities/source-release.js +2 -1
  126. package/dist/op/activities/source-rollback.d.ts.map +1 -1
  127. package/dist/op/activities/source-rollback.js +2 -1
  128. package/dist/op/index.d.ts +2 -0
  129. package/dist/op/index.d.ts.map +1 -1
  130. package/dist/op/index.js +1 -0
  131. package/dist/op/op-waves-evidence-jobs.d.ts +6 -1
  132. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  133. package/dist/op/op-waves-evidence-jobs.js +9 -3
  134. package/dist/op/op-waves-render-spec.d.ts +100 -0
  135. package/dist/op/op-waves-render-spec.d.ts.map +1 -0
  136. package/dist/op/op-waves-render-spec.js +162 -0
  137. package/dist/op/op-waves-run.d.ts +2 -0
  138. package/dist/op/op-waves-run.d.ts.map +1 -1
  139. package/dist/op/op-waves-run.js +2 -1
  140. package/dist/op/op-waves.d.ts +4 -0
  141. package/dist/op/op-waves.d.ts.map +1 -1
  142. package/dist/op/op-waves.js +4 -1
  143. package/dist/op/schedule-overdue.d.ts.map +1 -1
  144. package/dist/op/schedule-overdue.js +59 -3
  145. package/dist/op/wave-stop.d.ts +64 -0
  146. package/dist/op/wave-stop.d.ts.map +1 -0
  147. package/dist/op/wave-stop.js +127 -0
  148. package/dist/planned-files.d.ts +76 -0
  149. package/dist/planned-files.d.ts.map +1 -0
  150. package/dist/planned-files.js +108 -0
  151. package/dist/pr-forge-job.d.ts +22 -0
  152. package/dist/pr-forge-job.d.ts.map +1 -0
  153. package/dist/pr-forge-job.js +46 -0
  154. package/dist/pr-loop.d.ts +3 -6
  155. package/dist/pr-loop.d.ts.map +1 -1
  156. package/dist/pr-loop.js +4 -81
  157. package/dist/pr-plan-note.d.ts +97 -0
  158. package/dist/pr-plan-note.d.ts.map +1 -1
  159. package/dist/pr-plan-note.js +94 -1
  160. package/dist/pr-post.d.ts +28 -3
  161. package/dist/pr-post.d.ts.map +1 -1
  162. package/dist/pr-post.js +145 -13
  163. package/dist/pr-status.d.ts +16 -0
  164. package/dist/pr-status.d.ts.map +1 -0
  165. package/dist/pr-status.js +90 -0
  166. package/dist/ref-gate-init.d.ts +16 -2
  167. package/dist/ref-gate-init.d.ts.map +1 -1
  168. package/dist/ref-gate-init.js +24 -13
  169. package/dist/release-floors.d.ts +37 -1
  170. package/dist/release-floors.d.ts.map +1 -1
  171. package/dist/release-floors.js +61 -25
  172. package/dist/render-module.d.ts +15 -0
  173. package/dist/render-module.d.ts.map +1 -0
  174. package/dist/render-module.js +73 -0
  175. package/dist/state-migration.d.ts.map +1 -1
  176. package/dist/state-migration.js +1 -2
  177. package/dist/wave-runtime.mjs +304 -301
  178. package/dist/workspace/ci-green-cli.d.ts.map +1 -1
  179. package/dist/workspace/ci-green-cli.js +3 -2
  180. package/dist/workspace/release-train.d.ts.map +1 -1
  181. package/dist/workspace/release-train.js +2 -1
  182. package/dist/workspace/release-workflow.d.ts +4 -3
  183. package/dist/workspace/release-workflow.d.ts.map +1 -1
  184. package/dist/workspace/release-workflow.js +10 -7
  185. package/dist/workspace/trust/check-evidence-report.d.ts +7 -2
  186. package/dist/workspace/trust/check-evidence-report.d.ts.map +1 -1
  187. package/dist/workspace/trust/check-evidence-report.js +15 -8
  188. package/dist/workspace/trust/ref-gate-cli.d.ts +10 -1
  189. package/dist/workspace/trust/ref-gate-cli.d.ts.map +1 -1
  190. package/dist/workspace/trust/ref-gate-cli.js +30 -10
  191. package/dist/workspace/workspace-run.d.ts.map +1 -1
  192. package/dist/workspace/workspace-run.js +2 -1
  193. package/package.json +1 -1
  194. package/src/actor.test.ts +68 -2
  195. package/src/actor.ts +61 -1
  196. package/src/chant-install.test.ts +2 -3
  197. package/src/chant-install.ts +1 -2
  198. package/src/ci-base.test.ts +41 -0
  199. package/src/ci-base.ts +43 -0
  200. package/src/ci-comment-commands.test.ts +376 -0
  201. package/src/ci-comment-commands.ts +389 -0
  202. package/src/ci-comment-replies.ts +78 -0
  203. package/src/ci-commit.test.ts +2 -3
  204. package/src/ci-evidence-from-job.test.ts +18 -0
  205. package/src/ci-evidence-from-job.ts +58 -2
  206. package/src/ci-evidence-jobs.ts +50 -5
  207. package/src/ci-image.test.ts +130 -9
  208. package/src/ci-image.ts +85 -12
  209. package/src/ci-note-commands.ts +104 -41
  210. package/src/ci-product-words.ts +59 -0
  211. package/src/ci-product.ts +40 -4
  212. package/src/cli/commands/build.test.ts +41 -0
  213. package/src/cli/commands/build.ts +27 -2
  214. package/src/cli/handlers/approve.ts +2 -1
  215. package/src/cli/handlers/ci-check.ts +19 -7
  216. package/src/cli/handlers/ci-evidence.ts +29 -8
  217. package/src/cli/handlers/components.ts +3 -1
  218. package/src/cli/handlers/generated-check.ts +31 -1
  219. package/src/cli/handlers/lock-reach.test.ts +103 -0
  220. package/src/cli/handlers/lock.ts +100 -4
  221. package/src/cli/handlers/pr-comment.ts +104 -0
  222. package/src/cli/handlers/pr-env.ts +6 -3
  223. package/src/cli/handlers/pr-record.test.ts +1 -1
  224. package/src/cli/handlers/pr.ts +50 -10
  225. package/src/cli/handlers/promote.ts +2 -1
  226. package/src/cli/handlers/release.e2e.test.ts +35 -0
  227. package/src/cli/handlers/release.ts +14 -2
  228. package/src/cli/handlers/run-wave.ts +28 -2
  229. package/src/cli/handlers/run.ts +2 -1
  230. package/src/cli/main.ts +24 -2
  231. package/src/cli/parse-args.ts +12 -0
  232. package/src/cli/registry.ts +11 -0
  233. package/src/components/auto-release.ts +2 -1
  234. package/src/components/pr-checks.ts +112 -17
  235. package/src/components/pr-pipeline.ts +17 -15
  236. package/src/components/product-pipeline.ts +93 -11
  237. package/src/components/product-plan.test.ts +40 -2
  238. package/src/components/product-plan.ts +331 -45
  239. package/src/drift-record.test.ts +20 -0
  240. package/src/drift-record.ts +16 -0
  241. package/src/floor-table.data.ts +54 -31
  242. package/src/forge-check/contract.ts +12 -1
  243. package/src/forge-check/forge-check.test.ts +17 -0
  244. package/src/forge-check/index.ts +2 -0
  245. package/src/gate-resume-run.ts +27 -3
  246. package/src/generated-check.e2e.test.ts +21 -1
  247. package/src/generated-check.test.ts +66 -0
  248. package/src/generated-check.ts +51 -10
  249. package/src/image-pins.ts +31 -0
  250. package/src/lexicon.ts +11 -0
  251. package/src/lifecycle/git.test.ts +48 -0
  252. package/src/lifecycle/git.ts +27 -4
  253. package/src/lifecycle/publish-npm.ts +31 -1
  254. package/src/lifecycle/reach-locks.test.ts +87 -0
  255. package/src/lifecycle/reach-locks.ts +169 -0
  256. package/src/lifecycle/release-cut.ts +17 -1
  257. package/src/lifecycle/release-images.test.ts +56 -0
  258. package/src/lifecycle/release-images.ts +1 -2
  259. package/src/notify-product.ts +19 -8
  260. package/src/op/activities/source-release.ts +2 -1
  261. package/src/op/activities/source-rollback.ts +2 -1
  262. package/src/op/gate-resume.test.ts +27 -0
  263. package/src/op/index.ts +10 -0
  264. package/src/op/op-waves-evidence-jobs.ts +10 -4
  265. package/src/op/op-waves-notify-words.test.ts +18 -0
  266. package/src/op/op-waves-render-spec.test.ts +160 -0
  267. package/src/op/op-waves-render-spec.ts +171 -0
  268. package/src/op/op-waves-run.ts +2 -1
  269. package/src/op/op-waves.ts +5 -2
  270. package/src/op/schedule-overdue.test.ts +43 -0
  271. package/src/op/schedule-overdue.ts +57 -3
  272. package/src/op/wave-stop.test.ts +72 -0
  273. package/src/op/wave-stop.ts +137 -0
  274. package/src/planned-files.test.ts +80 -0
  275. package/src/planned-files.ts +134 -0
  276. package/src/pr-forge-job.test.ts +53 -0
  277. package/src/pr-forge-job.ts +46 -0
  278. package/src/pr-loop-narrowed.test.ts +2 -1
  279. package/src/pr-loop-words.test.ts +2 -1
  280. package/src/pr-loop.test.ts +1 -2
  281. package/src/pr-loop.ts +4 -80
  282. package/src/pr-plan-note.ts +155 -3
  283. package/src/pr-post-replan.test.ts +144 -0
  284. package/src/pr-post-subject.test.ts +230 -0
  285. package/src/pr-post.test.ts +2 -1
  286. package/src/pr-post.ts +150 -15
  287. package/src/pr-status.ts +91 -0
  288. package/src/ref-gate-init.ts +30 -11
  289. package/src/release-floors.ts +78 -25
  290. package/src/render-module.ts +73 -0
  291. package/src/state-migration-record.test.ts +2 -3
  292. package/src/state-migration.ts +1 -2
  293. package/src/workspace/ci-green-cli.ts +3 -2
  294. package/src/workspace/ci-green-workflow.test.ts +32 -1
  295. package/src/workspace/release-train.ts +2 -1
  296. package/src/workspace/release-workflow.test.ts +36 -5
  297. package/src/workspace/release-workflow.ts +10 -7
  298. package/src/workspace/trust/check-evidence-report.ts +15 -8
  299. package/src/workspace/trust/check-evidence.test.ts +5 -0
  300. package/src/workspace/trust/ref-gate-cli.ts +30 -8
  301. package/src/workspace/trust/ref-gate-pieces.test.ts +46 -1
  302. package/src/workspace/trust/ref-gate.test.ts +10 -0
  303. package/src/workspace/workspace-run.ts +2 -1
@@ -33,7 +33,15 @@
33
33
  *
34
34
  * The commit is the one the plan job checked out and every other status of
35
35
  * the loop names: `github.sha` on GitHub and Forgejo, `CI_COMMIT_SHA` in a
36
- * GitLab merge request pipeline.
36
+ * GitLab merge request pipeline. On a GitHub `pull_request` run that is the
37
+ * merge preview, and the status goes on the pull request's head, where the
38
+ * forge shows and requires it (#4964, ../pr-forge-job.ts).
39
+ *
40
+ * #4964: a workspace member's pipeline takes all three. The check job runs
41
+ * in the member's directory, the product's own service containers,
42
+ * variables, lines and report directory come with `PrCheckJobOptions`, and
43
+ * a product's own workflow renders the jobs through the lexicons'
44
+ * `productCheckJobs`.
37
45
  */
38
46
 
39
47
  import type { ForgeKind } from "../pr-forge";
@@ -56,15 +64,57 @@ export const PR_CHECK_REPORT_DIR = ".chant/check";
56
64
  /** The artifact the check report is kept as. */
57
65
  export const PR_CHECK_ARTIFACT = "chant-pr-check";
58
66
 
67
+ /**
68
+ * A service container the check job starts beside it (#4964), such as a
69
+ * throwaway database its hooks replay into. The job reaches it by `name`.
70
+ * GitHub and Forgejo hold the job's steps until `health` passes; GitLab
71
+ * does not wait, so a check job there waits in its `before` lines.
72
+ */
73
+ export interface PrCheckService {
74
+ /** The service's host name on the job's network: lower-case letters, digits, `.`, `_` and `-`. */
75
+ name: string;
76
+ image: string;
77
+ /** The service container's environment. */
78
+ env?: Record<string, string>;
79
+ /** A command the forge runs in the service container until it passes (GitHub's and Forgejo's `--health-cmd`). */
80
+ health?: string;
81
+ }
82
+
83
+ /**
84
+ * The check job's own settings (#4964), as a product passes them in
85
+ * `checkJob: { ... }`. `true` is all of them left out.
86
+ */
87
+ export interface PrCheckJobOptions {
88
+ /** Service containers beside the job. */
89
+ services?: PrCheckService[];
90
+ /** Variables of the check step, such as a service's URL. No forge token, runner key or `BASE_SHA`. */
91
+ env?: Record<string, string>;
92
+ /** Lines the check step runs before `chant ci check`, after the tokens are dropped, such as a wait for a service. */
93
+ before?: string[];
94
+ /** The report directory, repository-relative from the job's directory: `chant ci check --output <dir>`. Default `.chant/check`. */
95
+ dir?: string;
96
+ /** Arguments after `--base` (and `--output`), each one word, quoted where the shell needs it: `--summary <file>` and the targets a `perRun` hook runs for. */
97
+ args?: string[];
98
+ }
99
+
100
+ /** One shell word: as it is when it needs no quoting, else in single quotes. */
101
+ function shellWord(word: string): string {
102
+ return /^[A-Za-z0-9._\/=:@+,-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
103
+ }
104
+
59
105
  /** The check job (#4935): its command and the values it reads. */
60
106
  export interface PrCheckJob {
61
107
  jobName: string;
62
- /** `chant ci check --base "$BASE_SHA"`, through the words' bin. */
108
+ /** `chant ci check --base "$BASE_SHA"`, through the words' bin, with `--output <dir>` for a directory of the product's own. */
63
109
  command: string;
64
- /** `BASE_SHA`, as the forge spells it. */
110
+ /** `BASE_SHA`, as the forge spells it, and the product's own variables (#4964). */
65
111
  env: Record<string, string>;
66
112
  /** The report directory it writes and hands on. */
67
113
  dir: string;
114
+ /** The service containers beside it (#4964). */
115
+ services?: PrCheckService[];
116
+ /** The lines before the command (#4964). */
117
+ before?: string[];
68
118
  /**
69
119
  * With `evidence`: the signing job's lines and variables. GitHub and
70
120
  * Forgejo run them in `check-evidence` after taking the report back;
@@ -77,16 +127,54 @@ export interface PrCheckJob {
77
127
  evidence?: { jobName: string; lines: string[]; env: Record<string, string>; dir?: string; idToken?: true; idTokens?: Record<string, { aud: string }> };
78
128
  }
79
129
 
80
- /** The check job for `forge` (#4935), with the check evidence job when `evidence` names a runner identity. */
81
- export function prCheckJob(forge: ForgeKind, opts: { bin?: string; evidence?: PipelineEvidence; noForks?: boolean } = {}): PrCheckJob {
130
+ /** The variables a check job's own `env` may not set: the ones the job and its handover read, and the credentials it drops. */
131
+ const CHECK_RESERVED_ENV = /^(BASE_SHA|HEAD_SHA|CHECK_RESULT|CHANT_RUNNER_KEY|CHANT_RUNNER_IDENTITY|CHANT_LOCAL_EVIDENCE_KEY|CHANT_CHECKOUT_TOKEN|GITHUB_TOKEN|GH_TOKEN|FORGEJO_TOKEN|GITLAB_TOKEN|CI_JOB_TOKEN|CHANT_FORGE_TOKEN|ACTIONS_ID_TOKEN_REQUEST_(URL|TOKEN))$/;
132
+
133
+ /** Refuse check job settings no job could hold (#4964). */
134
+ function assertCheckJobOptions(opts: PrCheckJobOptions): void {
135
+ if (opts.dir !== undefined && (!/^[A-Za-z0-9._][A-Za-z0-9._\/-]*$/.test(opts.dir) || opts.dir.split("/").includes(".."))) {
136
+ throw new Error(`the check job's report directory ${JSON.stringify(opts.dir)} is not a relative path inside the checkout`);
137
+ }
138
+ for (const a of opts.args ?? []) {
139
+ if (a === "" || /[\0\n]/.test(a) || a === "--base" || a === "--output" || a === "-o") throw new Error(`the check job's argument ${JSON.stringify(a)} is not one it takes: --base and --output are its own`);
140
+ }
141
+ const names = new Set<string>();
142
+ for (const s of opts.services ?? []) {
143
+ if (!/^[a-z0-9][a-z0-9._-]*$/.test(s.name)) throw new Error(`the check job's service name ${JSON.stringify(s.name)} is not a host name: lower-case letters, digits, . _ -`);
144
+ if (names.has(s.name)) throw new Error(`the check job names service ${s.name} twice`);
145
+ names.add(s.name);
146
+ if (!s.image.trim() || /\s/.test(s.image)) throw new Error(`the check job's service ${s.name} needs an image reference`);
147
+ }
148
+ for (const name of Object.keys(opts.env ?? {})) {
149
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`the check job's variable ${JSON.stringify(name)} is not a variable name`);
150
+ if (CHECK_RESERVED_ENV.test(name)) throw new Error(`the check job sets ${name} itself, or drops it before the hooks run, so checkJob.env cannot name it`);
151
+ }
152
+ }
153
+
154
+ /**
155
+ * The check job for `forge` (#4935), with the check evidence job when
156
+ * `evidence` names a runner identity. #4964: the product's services,
157
+ * variables, lines and report directory (`PrCheckJobOptions`), and for a
158
+ * workspace member's GitLab file (`member`) the jobs named
159
+ * `<member>-check` and `<member>-check-evidence`, with the report read from
160
+ * the artifact at the member's `reportPath`, as GitLab includes every
161
+ * member's file in one pipeline. On GitHub and Forgejo a member's workflow
162
+ * is a file of its own, and the jobs keep their names.
163
+ */
164
+ export function prCheckJob(forge: ForgeKind, opts: { bin?: string; evidence?: PipelineEvidence; noForks?: boolean; member?: { name: string; reportPath: string } } & PrCheckJobOptions = {}): PrCheckJob {
82
165
  assertPipelineEvidence(opts.evidence);
166
+ assertCheckJobOptions(opts);
83
167
  const gitlab = forge === "gitlab";
84
168
  const base = gitlab ? "$CI_MERGE_REQUEST_DIFF_BASE_SHA" : "${{ github.event.pull_request.base.sha }}";
169
+ const dir = opts.dir ?? PR_CHECK_REPORT_DIR;
170
+ const named = (job: string) => (gitlab && opts.member ? `${opts.member.name}-${job}` : job);
85
171
  const job: PrCheckJob = {
86
- jobName: PR_CHECK_JOB,
87
- command: withProductBin('chant ci check --base "$BASE_SHA"', opts.bin),
88
- env: { BASE_SHA: base },
89
- dir: PR_CHECK_REPORT_DIR,
172
+ jobName: named(PR_CHECK_JOB),
173
+ command: withProductBin(`chant ci check --base "$BASE_SHA"${dir === PR_CHECK_REPORT_DIR ? "" : ` --output ${dir}`}${(opts.args ?? []).map((a) => ` ${shellWord(a)}`).join("")}`, opts.bin),
174
+ env: { BASE_SHA: base, ...opts.env },
175
+ dir,
176
+ ...(opts.services?.length ? { services: opts.services } : {}),
177
+ ...(opts.before?.length ? { before: opts.before } : {}),
90
178
  };
91
179
  const evidence = opts.evidence;
92
180
  if (!evidence) return job;
@@ -95,15 +183,15 @@ export function prCheckJob(forge: ForgeKind, opts: { bin?: string; evidence?: Pi
95
183
  if (gitlab) {
96
184
  // #4914: the job runs in the target branch's plan notes pipeline and signs every open merge request's
97
185
  // settled check job from its artifact; no job of a merge request pipeline holds the key.
98
- const dir = gitlabOpenEvidenceDir(PR_CHECK_JOB);
186
+ const out = gitlabOpenEvidenceDir(job.jobName);
99
187
  return {
100
188
  ...job,
101
189
  evidence: {
102
- jobName: PR_CHECK_EVIDENCE_JOB,
190
+ jobName: named(PR_CHECK_EVIDENCE_JOB),
103
191
  // A fork's check job runs too, as it holds nothing; with noForks (a product plan's forks: "skip") its hooks are not signed for.
104
- lines: openEvidenceLines({ job: PR_CHECK_JOB, dir: PR_CHECK_REPORT_DIR, out: dir, ...bin, ...(opts.noForks ? { noForks: true } : {}) }),
192
+ lines: openEvidenceLines({ job: job.jobName, dir: opts.member?.reportPath ?? dir, out, ...bin, ...(opts.noForks ? { noForks: true } : {}) }),
105
193
  env: key,
106
- dir,
194
+ dir: out,
107
195
  ...(evidenceKeyless(evidence) ? { idTokens: evidenceIdTokens(evidence) } : {}),
108
196
  },
109
197
  };
@@ -112,7 +200,7 @@ export function prCheckJob(forge: ForgeKind, opts: { bin?: string; evidence?: Pi
112
200
  ...job,
113
201
  evidence: {
114
202
  jobName: PR_CHECK_EVIDENCE_JOB,
115
- lines: planEvidenceLines({ dir: PR_CHECK_REPORT_DIR, at: '"$HEAD_SHA"', base: '"$BASE_SHA"', result: '"$CHECK_RESULT"', ...bin }),
203
+ lines: planEvidenceLines({ dir, at: '"$HEAD_SHA"', base: '"$BASE_SHA"', result: '"$CHECK_RESULT"', ...bin }),
116
204
  env: { HEAD_SHA: "${{ github.sha }}", BASE_SHA: base, CHECK_RESULT: `\${{ needs.${PR_CHECK_JOB}.result }}`, ...key },
117
205
  ...(evidenceKeyless(evidence) ? { idToken: true as const } : {}),
118
206
  },
@@ -134,12 +222,19 @@ export interface PrRefGateJob {
134
222
  * The ref gate's status job for `forge` (#4935). `branch` is the target
135
223
  * branch on GitHub and Forgejo (default `main`); GitLab's job runs in a
136
224
  * pipeline of the target branch and names it from `CI_COMMIT_BRANCH`.
225
+ *
226
+ * #4964: in a workspace member's GitLab file (`member`) the job is
227
+ * `<member>-ref-gate`. Each member's pipeline decides the whole update
228
+ * against the one rule and sets the one status, so the last job to run
229
+ * after the evidence it needs is in sets success; one that ran before
230
+ * another member's evidence was in set failure, and a re-run settles it.
231
+ * None sets success while a required check lacks evidence.
137
232
  */
138
- export function prRefGateJob(forge: ForgeKind, opts: { bin?: string; branch?: string } = {}): PrRefGateJob {
233
+ export function prRefGateJob(forge: ForgeKind, opts: { bin?: string; branch?: string; member?: string } = {}): PrRefGateJob {
139
234
  const notes = "'+refs/notes/chant/evidence:refs/notes/chant/evidence'";
140
235
  if (forge === "gitlab") {
141
236
  return {
142
- jobName: PR_REF_GATE_JOB,
237
+ jobName: opts.member ? `${opts.member}-${PR_REF_GATE_JOB}` : PR_REF_GATE_JOB,
143
238
  // The heads are fetched by the command, one merge request at a time.
144
239
  setup: [`git fetch --quiet --no-tags origin ${notes} || true`],
145
240
  command: withProductBin('chant workspace ref-gate status --open --ref "refs/heads/$CI_COMMIT_BRANCH" --base "$CI_COMMIT_SHA"', opts.bin),
@@ -156,4 +251,4 @@ export function prRefGateJob(forge: ForgeKind, opts: { bin?: string; branch?: st
156
251
  };
157
252
  }
158
253
 
159
- export { CHECK_JOB_FLOOR, GITLAB_OPEN_EVIDENCE_FLOOR, PR_LOOP_EVIDENCE_FLOOR, REF_GATE_STATUS_JOB_FLOOR } from "../release-floors";
254
+ export { CHECK_JOB_FLOOR, GITLAB_OPEN_EVIDENCE_FLOOR, MEMBER_SIGNED_CHECKS_FLOOR, PR_LOOP_EVIDENCE_FLOOR, PRODUCT_CHECK_JOBS_FLOOR, REF_GATE_STATUS_JOB_FLOOR } from "../release-floors";
@@ -102,6 +102,7 @@ import { CHANT_EXIT } from "../exit-codes";
102
102
  import type { ControlTarget } from "../control/dispatch";
103
103
  import { CI_RESPOND_ENV, respondList, type CiResponses } from "../ci-respond";
104
104
  import type { PipelineEvidence } from "../ci-evidence-jobs";
105
+ import type { PrCheckJobOptions } from "./pr-checks";
105
106
 
106
107
  /** The variable `chant ci run` reads its runner key from (`RUNNER_KEY_ENV` in ../workspace/ci-green.ts). */
107
108
  const RUNNER_KEY_ENV = "CHANT_RUNNER_KEY";
@@ -401,35 +402,36 @@ export interface PrLoopPipelineOptions {
401
402
  * With `checkJob`, the `check-evidence` job signs each passed hook. Set
402
403
  * from `--evidence-runner-key-secret`, or `--evidence-identity oidc` with
403
404
  * an optional `--evidence-audience`. Absent: nothing is signed, and every
404
- * job is as before. Refused on a workspace member's pipeline: the checks
405
- * are the commit's, so one pipeline signs them.
405
+ * job is as before. #4964: a workspace member's pipeline plans that member
406
+ * alone, so it signs `plan:<member>` and `policy:<member>`
407
+ * (`memberEvidenceCheck`), which the `refs` rule names for each member.
406
408
  */
407
409
  evidence?: PipelineEvidence;
408
410
  /**
409
411
  * The check job (#4935, ./pr-checks.ts): `chant ci check --base <base>` on
410
412
  * the pull request's commit, with no forge token, runner key or OIDC token
411
- * while the hooks run. Set from `--check-job`. Refused on a member's
412
- * pipeline: the hooks are the workspace's.
413
+ * while the hooks run. Set from `--check-job`. #4964: an object gives the
414
+ * job service containers, variables, lines before the check and its own
415
+ * report directory (`PrCheckJobOptions`). In a workspace member's pipeline
416
+ * it runs in the member's directory: the top level's hooks and the
417
+ * member's, each signed by its own name, the same for every member that
418
+ * runs it.
413
419
  */
414
- checkJob?: boolean;
420
+ checkJob?: boolean | PrCheckJobOptions;
415
421
  /**
416
422
  * The ref gate's status job (#4935, ./pr-checks.ts): `chant workspace
417
423
  * ref-gate status` for the pull request's commit, after the note and the
418
424
  * check evidence, so `chant/ref-gate` can be a required status. Set from
419
- * `--ref-gate-status`. Refused on a member's pipeline.
425
+ * `--ref-gate-status`. #4964: in a member's pipeline it decides the whole
426
+ * update against the one rule, as the root's does, and sets the one
427
+ * status (`prRefGateJob`).
420
428
  */
421
429
  refGateStatus?: boolean;
422
430
  }
423
431
 
424
- /**
425
- * Refuse the loop's `evidence`, `checkJob` and `refGateStatus` (#4935) on a
426
- * workspace member's pipeline: a check and its evidence are the commit's,
427
- * so the root pipeline runs and signs them once.
428
- */
429
- export function assertRootChecks(options: Pick<PrLoopPipelineOptions, "evidence" | "checkJob" | "refGateStatus">, member: string | undefined): void {
430
- if (!member) return;
431
- const given = [...(options.evidence ? ["evidence"] : []), ...(options.checkJob ? ["checkJob"] : []), ...(options.refGateStatus ? ["refGateStatus"] : [])];
432
- if (given.length > 0) throw new Error(`${given.join(", ")} sign and judge the pull request's commit once, for the whole workspace, so give ${given.length === 1 ? "it" : "them"} on the root pipeline, not member ${member}'s`);
432
+ /** The check job's own settings from `checkJob` (#4964): undefined when there is no check job, `{}` for `true`. */
433
+ export function checkJobOptions(checkJob: boolean | PrCheckJobOptions | undefined): PrCheckJobOptions | undefined {
434
+ return checkJob === true ? {} : checkJob ? checkJob : undefined;
433
435
  }
434
436
 
435
437
  /** The `CHANT_RESPOND` value of `respond` (#4629), or undefined when every event is at its default. Throws on a description check with no decide service. */
@@ -28,23 +28,25 @@ import { controlNoteCheckout, type ControlNoteCheckout } from "../control/dispat
28
28
  import {
29
29
  assertProductWords,
30
30
  CHANT_WORDS,
31
+ CI_PRODUCT_COMMANDS,
31
32
  commentLine,
32
33
  type CiProductApplyMode,
33
34
  type CiProductCommand,
34
35
  type CiProductWords,
35
36
  type CiProductWordsInput,
36
37
  } from "../ci-product-words";
37
- import { prActionJob, prCommentLockJobs, prCommentPreviewJob, prLoopJobs, prLoopPostJob, prLoopRunner, prNoteCommandsJob, prStaleJob, withProductBin, type PrActionJob, type PrCommentLockJob, type PrCommentPreviewJob, type PrLoopJob, type PrLoopPipelineOptions } from "./pr-pipeline";
38
+ import { checkJobOptions, PR_LOOP_REPORT_DIR, prActionJob, prCommentLockJobs, prCommentPreviewJob, prLoopJobs, prLoopPostJob, prLoopRunner, prNoteCommandsJob, prStaleJob, withProductBin, type PrActionJob, type PrCommentLockJob, type PrCommentPreviewJob, type PrLoopJob, type PrLoopPipelineOptions } from "./pr-pipeline";
38
39
  import type { DriverComponent } from "./driver";
39
40
  import type { ScheduledOpSpec } from "../lexicon";
40
41
  import type { CiRunner } from "../ci-jobs";
41
42
  import { resolveAgentSpec, type OpAgentSpec } from "../ci-agent";
42
43
  import { resolveCommitSpec, type OpCommitSpec } from "../ci-commit";
43
44
  import type { CiResponses } from "../ci-respond";
44
- import { planEvidenceOf, productPlanJobs, type ProductPlanJob, type ProductPlanOptions } from "./product-plan";
45
+ import { planEvidenceOf, productPlanJobs, productPlanReachLock, type ProductPlanJob, type ProductPlanOptions, type ProductPlanReachLock } from "./product-plan";
45
46
  import { gitlabOpenEvidenceDir, type PipelineEvidence } from "../ci-evidence-jobs";
46
47
  import { prCheckJob, prRefGateJob, type PrCheckJob, type PrRefGateJob } from "./pr-checks";
47
- import { assertRootChecks } from "./pr-pipeline";
48
+ import { COMMENT_JOBS_ENV, PR_COMMENT_JOB, type CommentJobs } from "../ci-comment-commands";
49
+ import { GITHUB_JOB_TOKEN } from "../ci-jobs";
48
50
 
49
51
  /** Where the generator writes a product's waves spec, which chant reads at base (#4550). */
50
52
  export const PRODUCT_WAVES_SPEC_DIR = ".chant/op-waves";
@@ -134,6 +136,31 @@ export interface ProductPipelineOptions extends Omit<PrLoopPipelineOptions, "wor
134
136
  * Absent: nothing is signed, and the jobs are as before.
135
137
  */
136
138
  evidence?: PipelineEvidence;
139
+ /**
140
+ * The comment job (#4946), GitHub and Forgejo: one job on every
141
+ * `/<product>` comment (and every alias's) that answers what no other job
142
+ * of the pipeline takes, with `chant components pr-comment`: a refusal,
143
+ * a command the pipeline has no job for (the words' `replies`, else
144
+ * chant's), and with waves on merge the re-run of a merged pull request's
145
+ * apply. The jobs it leaves comments to are the ones these options write.
146
+ * On GitLab the note-commands job answers every note already; refused
147
+ * there.
148
+ */
149
+ commentJob?: boolean;
150
+ }
151
+
152
+ /** The comment job (#4946): its command, the values it reads, and the comment prefixes that start it. */
153
+ export interface ProductCommentJob {
154
+ jobName: typeof PR_COMMENT_JOB;
155
+ /** `<bin> components pr-comment --forge <forge>`. */
156
+ command: string;
157
+ /** `GITHUB_TOKEN` and {@link COMMENT_JOBS_ENV}. */
158
+ env: Record<string, string>;
159
+ /** What a comment starts with for the job to start: `/<product>`, then each alias. */
160
+ prefixes: string[];
161
+ /** The jobs it leaves comments to. */
162
+ jobs: CommentJobs;
163
+ runner?: CiRunner;
137
164
  }
138
165
 
139
166
  /** The jobs of one product pipeline. */
@@ -212,6 +239,14 @@ export interface ProductPipelineJobs {
212
239
  check?: PrCheckJob & { runner?: CiRunner; evidenceRunner?: CiRunner };
213
240
  /** The ref gate's status job (#4935), with `refGateStatus` (./pr-checks.ts). */
214
241
  refGate?: PrRefGateJob & { runner?: CiRunner };
242
+ /** The comment job (#4946), with `commentJob`. */
243
+ comment?: ProductCommentJob;
244
+ /**
245
+ * The reach lock job (#4979), with `locks: "plan"` and the product plan's
246
+ * `reach`: `chant lock --reach`, in place of the lock jobs that read a
247
+ * `PrReport`. The forge lexicons render it.
248
+ */
249
+ reachLock?: ProductPlanReachLock;
215
250
  }
216
251
 
217
252
  /** An agent's settings as a product passes them (#4616): {@link OpAgentSpec} without the trigger, which the pipeline names. */
@@ -313,11 +348,11 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
313
348
  // Words that ask for before-merge keep it when the pipeline has that job beside its waves.
314
349
  const built: CiProductApplyMode = options.waves || options.componentWaves ? "on-merge" : options.applyBeforeMerge ? "before-merge" : "release";
315
350
  const applyMode: CiProductApplyMode = options.words.applyMode === "before-merge" && options.applyBeforeMerge ? "before-merge" : built;
316
- const words = assertProductWords({ ...options.words, applyMode }, { jobs });
317
- const { waves: given, wavesSpecFile, member, agent: _agent, commits: _commits, actions: _actions, componentWaves, productPlan, evidence, ...loop } = options;
351
+ // #4946: the comment job answers every command but a commit word (the commit job's) with a reply, so the words may name any.
352
+ const answered: CiProductCommand[] = options.commentJob ? [...new Set<CiProductCommand>([...jobs, ...CI_PRODUCT_COMMANDS.filter((c) => c !== "commit")])] : jobs;
353
+ const words = assertProductWords({ ...options.words, applyMode }, { jobs: answered });
354
+ const { waves: given, wavesSpecFile, member, agent: _agent, commits: _commits, actions: _actions, componentWaves, productPlan, evidence, commentJob: _commentJob, ...loop } = options;
318
355
  const { respond } = options;
319
- // #4935: the check job and the ref gate's status judge the commit once, from the root pipeline.
320
- assertRootChecks({ checkJob: options.checkJob, refGateStatus: options.refGateStatus }, member);
321
356
  // #4629: the pull request loop puts the responses on the apply and note jobs, as `chant build --pr-loop --respond` does.
322
357
  const prLoop: PrLoopPipelineOptions = { ...loop, words, gate: options.gate ?? words.prGate };
323
358
  const [plan, apply, record] = prLoopJobs(forge, env, prLoop, member);
@@ -337,21 +372,26 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
337
372
  const out: ProductPipelineJobs = {
338
373
  words,
339
374
  plan: plan!,
340
- // #4870: the note job signs the plan job's plan and policy checks before it posts.
341
- post: { ...post, ...(controlTarget ? { control: controlNoteCheckout(forge, controlTarget, words) } : {}), ...defaultRunner, ...(evidence ? { evidence: planEvidenceOf(forge, evidence, words, plan!.jobName) } : {}) },
375
+ // #4870: the note job signs the plan job's plan and policy checks before it posts; #4964: a member's under its name.
376
+ post: { ...post, ...(controlTarget ? { control: controlNoteCheckout(forge, controlTarget, words) } : {}), ...defaultRunner, ...(evidence ? { evidence: planEvidenceOf(forge, evidence, words, plan!.jobName, member ? { member: { name: member, reportPath: PR_LOOP_REPORT_DIR } } : {}) } : {}) },
342
377
  comments,
343
378
  ...(options.applyBeforeMerge ? { applyBeforeMerge: apply! } : {}),
344
379
  // #4799: the product's plan verb, a plan job and a note job per target.
345
380
  ...(productPlan ? { productPlan: productPlanJobs(forge, env, { ...prLoop, plan: productPlan }, words, evidence) } : {}),
346
381
  };
347
382
  // #4935: the check job runs the change's code on the plan runner; the signing and the status run on the default one.
348
- if (options.checkJob) {
383
+ // #4964: with the product's own services, variables, lines and report directory.
384
+ const checkOptions = checkJobOptions(options.checkJob);
385
+ if (checkOptions) {
349
386
  const planRunner = prLoopRunner(options, "plan");
350
- out.check = { ...prCheckJob(forge, { ...(words.bin ? { bin: words.bin } : {}), ...(evidence ? { evidence } : {}), ...(productPlan?.forks === "skip" ? { noForks: true } : {}) }), ...(planRunner !== undefined ? { runner: planRunner } : {}), ...(runnerOfDefault !== undefined ? { evidenceRunner: runnerOfDefault } : {}) };
387
+ out.check = { ...prCheckJob(forge, { ...checkOptions, ...(words.bin ? { bin: words.bin } : {}), ...(evidence ? { evidence } : {}), ...(productPlan?.forks === "skip" ? { noForks: true } : {}) }), ...(planRunner !== undefined ? { runner: planRunner } : {}), ...(runnerOfDefault !== undefined ? { evidenceRunner: runnerOfDefault } : {}) };
351
388
  }
352
389
  if (options.refGateStatus) out.refGate = { ...prRefGateJob(forge, { ...(words.bin ? { bin: words.bin } : {}), ...(options.branch ? { branch: options.branch } : {}) }), ...defaultRunner };
353
390
  const locks = prCommentLockJobs(forge, { locks: options.locks, words });
354
391
  if (locks.length > 0) out.locks = locks.map((job) => ({ ...job, ...defaultRunner }));
392
+ // #4979: the product plan's reach says what the lock job locks.
393
+ const reachLock = productPlan ? productPlanReachLock(forge, { ...prLoop, plan: productPlan }, words) : undefined;
394
+ if (reachLock) out.reachLock = reachLock;
355
395
  const action = prActionJob(forge, prLoop);
356
396
  if (action) out.action = { ...action, ...(prLoopRunner(options, "apply") !== undefined ? { runner: prLoopRunner(options, "apply")! } : {}) };
357
397
  const stale = prStaleJob(forge, env, prLoop, member);
@@ -380,6 +420,29 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
380
420
  const spec = given ?? (componentWaves
381
421
  ? componentWavesSpec(componentWaves.components, words, componentWaveSteps({ ...(words.bin ? { bin: words.bin } : {}), env, base: componentWaves.base ?? "HEAD^1", ...(member ? { member } : {}), op, gate: prLoop.gate }), { ...(componentWaves.waveGate ? { gate: componentWaves.waveGate } : {}) })
382
422
  : undefined);
423
+ // #4946: the comment job answers what no other job of the pipeline takes, so it is told which jobs there are.
424
+ if (options.commentJob) {
425
+ // #4963's re-plan reply answers the same stray comments, so one of the two answers them.
426
+ if (typeof productPlan?.replan === "object" && productPlan.replan.reply) throw new Error("commentJob answers every /<product> comment no other job takes, and so does the product plan's replan.reply; drop replan.reply, since the comment job answers the re-plan's refusals too");
427
+ // The product plan's re-plan skips a target that is none of its own and, with forks: "skip", a fork's pull request without a word; the comment job says why.
428
+ const planTargets = productPlan?.replan ? productPlan.targets?.map((t) => t.name) : undefined;
429
+ const commentJobs: CommentJobs = {
430
+ ...(productPlan?.replan || options.previewComment ? { preview: true } : {}),
431
+ ...(planTargets?.length ? { targets: planTargets } : {}),
432
+ ...(productPlan?.replan && productPlan.forks === "skip" ? { skipForks: true } : {}),
433
+ ...(options.applyBeforeMerge ? { applyBeforeMerge: true } : {}),
434
+ ...(given || componentWaves ? { applyOnMerge: true } : {}),
435
+ // #4979: the waves' op (the name productWavesSpec gives them) and count, so a wave-<n> stops a re-run after wave n.
436
+ ...(spec ? { waves: { op: words.op ?? spec.name, count: spec.waves.length } } : {}),
437
+ // #4979: the product plan's re-plan takes no flags, so the comment job answers a plan comment that carries them.
438
+ ...(productPlan?.replan ? { noPlanFlags: true } : {}),
439
+ ...(locks.length > 0 ? { locks: true } : {}),
440
+ ...(out.agent ? { agent: true } : {}),
441
+ ...(out.commits ? { commits: true } : {}),
442
+ ...(options.actions || options.actionJob ? { actions: true } : {}),
443
+ };
444
+ out.comment = { ...productCommentJob(forge, words, commentJobs), ...defaultRunner };
445
+ }
383
446
  if (!spec) return { ...out, record: record! };
384
447
  const wavesRespond = respond ? Object.fromEntries(Object.entries(respond).filter(([e]) => e !== "description")) : {};
385
448
  // #4625: the waves run on the apply runner and with the plan's parallelism, unless the spec names its own.
@@ -508,6 +571,25 @@ export function componentWavesSpec(
508
571
  };
509
572
  }
510
573
 
574
+ /**
575
+ * The comment job's descriptor (#4946): `chant components pr-comment
576
+ * --forge <forge>` through the words' bin, the jobs it leaves comments to as
577
+ * {@link COMMENT_JOBS_ENV}, and the comment prefixes the forge's `if:`
578
+ * starts it on. Throws on GitLab, whose note-commands job answers every
579
+ * note.
580
+ */
581
+ export function productCommentJob(forge: ForgeKind, words: CiProductWords, jobs: CommentJobs): ProductCommentJob {
582
+ if (forge === "gitlab") throw new Error("the comment job answers a GitHub or Forgejo comment; on GitLab the note-commands job (noteCommands) answers every note, so drop commentJob");
583
+ for (const a of words.aliases) if (/['\\]/.test(a.from)) throw new Error(`the alias ${JSON.stringify(a.from)} holds a quote, which the comment job's condition cannot carry`);
584
+ return {
585
+ jobName: PR_COMMENT_JOB,
586
+ command: withProductBin(`chant components pr-comment --forge ${forge}`, words.bin),
587
+ env: { GITHUB_TOKEN: GITHUB_JOB_TOKEN, [COMMENT_JOBS_ENV]: JSON.stringify(jobs) },
588
+ prefixes: [`/${words.product}`, ...words.aliases.map((a) => a.from)],
589
+ jobs,
590
+ };
591
+ }
592
+
511
593
  /** A shell line with the product's bin in place of `chant`, for a product's own jobs beside these. */
512
594
  export function productCommand(words: CiProductWords, line: string): string {
513
595
  return withProductBin(line, words.bin);
@@ -181,8 +181,46 @@ describe("the re-plan decision and the pending status scripts (#4899)", () => {
181
181
  });
182
182
 
183
183
  test("PRODUCT_PLAN_STEPS_FLOOR marks the plan-job steps in the ci-product entry", async () => {
184
- const { NEXT_RELEASE } = await import("../release-floors");
185
184
  const ciProduct = (await import("../ci-product")) as Record<string, unknown>;
186
- expect(ciProduct.PRODUCT_PLAN_STEPS_FLOOR).toBe(NEXT_RELEASE);
185
+ expect(ciProduct.PRODUCT_PLAN_STEPS_FLOOR).toBe("0.124.88");
187
186
  expect(ciProduct.PLAN_NOTE_NOTICES_ENV).toBe("CHANT_PLAN_NOTE_NOTICES");
188
187
  });
188
+
189
+ describe("what terragucci's and sql-yodeler's plan jobs need (#4963)", () => {
190
+ const trade = { aws: { region: "us-east-1", audience: "sts.amazonaws.com", role: "arn:aws:iam::123456789012:role/plan" } };
191
+
192
+ test("PRODUCT_PLAN_REPLAN_FLOOR is the next release, in the ci-product entry", async () => {
193
+ const ciProduct = (await import("../ci-product")) as Record<string, unknown>;
194
+ const { NEXT_RELEASE } = await import("../release-floors");
195
+ expect(ciProduct.PRODUCT_PLAN_REPLAN_FLOOR).toBe(NEXT_RELEASE);
196
+ expect(typeof ciProduct.planBodyHandoff).toBe("function");
197
+ });
198
+
199
+ test("a trade's OIDC token is the job's, beside its own; a target's login or trade stands in for the plan's", () => {
200
+ const [one] = productPipelineJobs("gitlab", "default", { words: terragucci, productPlan: { command: "x", trade, idTokens: { TG_OIDC: "tg" } } }).productPlan!;
201
+ expect(one!.trade).toEqual(trade);
202
+ expect(one!.idTokens).toEqual({ CHANT_ID_TOKEN_AWS: "sts.amazonaws.com", TG_OIDC: "tg" });
203
+ const [a, b] = productPipelineJobs("github", "default", { words: yodel, productPlan: { ...environments, trade, targets: [{ name: "a", login: { aws: { role: "arn:aws:iam::1:role/r" } } }, { name: "b" }] } }).productPlan!;
204
+ expect(a!.trade).toBeUndefined();
205
+ expect(a!.login).toBeDefined();
206
+ expect(b!.trade).toEqual(trade);
207
+ expect(() => productPipelineJobs("github", "default", { words: terragucci, productPlan: { command: "x", trade, idTokens: { CHANT_ID_TOKEN_AWS: "other" } } })).toThrow(/the trade's, with another audience/);
208
+ });
209
+
210
+ test("the re-plan's options are checked", () => {
211
+ const plan = (replan: unknown) => () => productPipelineJobs("github", "default", { words: terragucci, productPlan: { command: "x", replan: replan as never } });
212
+ expect(plan({ dispatch: { argument: "pr" } })).toThrow(/input name/);
213
+ expect(plan({ dispatch: { argument: "Root Dir" } })).toThrow(/input name/);
214
+ expect(plan({ reply: { others: ["/plywood up"] } })).toThrow(/not a \/terragucci comment/);
215
+ expect(plan({ reply: { others: ["/terragucci it's"] } })).toThrow(/quote/);
216
+ const [p] = productPipelineJobs("github", "default", { words: terragucci, productPlan: { command: "x", replan: { dispatch: true, reply: true, notAffected: true } } }).productPlan!;
217
+ expect(p!.replan).toMatchObject({ dispatch: { argument: "argument" }, reply: { prefix: "/terragucci", others: [] }, notAffected: true });
218
+ expect(p!.replan!.post.command).toMatch(/ --not-affected "\$CHANT_PLAN_ARGUMENT"$/);
219
+ expect(p!.post.command).not.toContain("--not-affected");
220
+ });
221
+
222
+ test("previousMarker names chant's marker for the target and the product's marker", () => {
223
+ const [, prod] = productPipelineJobs("forgejo", "default", { words: yodel, productPlan: { ...environments, previousMarker: true, noteWords: { productMarker: "yodel:plan" } } }).productPlan!;
224
+ expect(prod!.previous).toEqual({ marker: "<!-- chant-pr:default:prod -->", name: "yodel:plan" });
225
+ });
226
+ });