@intentius/chant 0.124.55 → 0.124.56

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 (370) hide show
  1. package/dist/ci-agent.d.ts.map +1 -1
  2. package/dist/ci-agent.js +1 -2
  3. package/dist/ci-audit/attribution.d.ts +111 -0
  4. package/dist/ci-audit/attribution.d.ts.map +1 -0
  5. package/dist/ci-audit/attribution.js +194 -0
  6. package/dist/ci-audit/audit-log.d.ts +144 -0
  7. package/dist/ci-audit/audit-log.d.ts.map +1 -0
  8. package/dist/ci-audit/audit-log.js +149 -0
  9. package/dist/ci-audit/index.d.ts +12 -0
  10. package/dist/ci-audit/index.d.ts.map +1 -0
  11. package/dist/ci-audit/index.js +12 -0
  12. package/dist/ci-audit/unrecorded.d.ts +74 -0
  13. package/dist/ci-audit/unrecorded.d.ts.map +1 -0
  14. package/dist/ci-audit/unrecorded.js +95 -0
  15. package/dist/ci-audit.d.ts +3 -0
  16. package/dist/ci-audit.d.ts.map +1 -0
  17. package/dist/ci-audit.js +2 -0
  18. package/dist/ci-control.d.ts.map +1 -1
  19. package/dist/ci-control.js +3 -4
  20. package/dist/ci-estate.d.ts +24 -0
  21. package/dist/ci-estate.d.ts.map +1 -1
  22. package/dist/ci-estate.js +1 -2
  23. package/dist/ci-identity.d.ts.map +1 -1
  24. package/dist/ci-identity.js +2 -3
  25. package/dist/ci-job-guard.d.ts +139 -0
  26. package/dist/ci-job-guard.d.ts.map +1 -0
  27. package/dist/ci-job-guard.js +287 -0
  28. package/dist/ci-jobs.d.ts +7 -0
  29. package/dist/ci-jobs.d.ts.map +1 -1
  30. package/dist/ci-jobs.js +7 -0
  31. package/dist/ci-product-words.d.ts +7 -1
  32. package/dist/ci-product-words.d.ts.map +1 -1
  33. package/dist/ci-product-words.js +38 -4
  34. package/dist/ci-product.d.ts +35 -0
  35. package/dist/ci-product.d.ts.map +1 -1
  36. package/dist/ci-product.js +38 -3
  37. package/dist/ci-respond-run.d.ts +73 -0
  38. package/dist/ci-respond-run.d.ts.map +1 -0
  39. package/dist/ci-respond-run.js +247 -0
  40. package/dist/ci-respond.d.ts +189 -0
  41. package/dist/ci-respond.d.ts.map +1 -0
  42. package/dist/ci-respond.js +285 -0
  43. package/dist/cli/handlers/audit-log.d.ts +12 -0
  44. package/dist/cli/handlers/audit-log.d.ts.map +1 -0
  45. package/dist/cli/handlers/audit-log.js +81 -0
  46. package/dist/cli/handlers/build.d.ts +7 -0
  47. package/dist/cli/handlers/build.d.ts.map +1 -1
  48. package/dist/cli/handlers/build.js +81 -0
  49. package/dist/cli/handlers/ci-check-job.d.ts +11 -0
  50. package/dist/cli/handlers/ci-check-job.d.ts.map +1 -0
  51. package/dist/cli/handlers/ci-check-job.js +27 -0
  52. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  53. package/dist/cli/handlers/ci-check.js +38 -9
  54. package/dist/cli/handlers/e2e-safe-run.d.ts +12 -0
  55. package/dist/cli/handlers/e2e-safe-run.d.ts.map +1 -0
  56. package/dist/cli/handlers/e2e-safe-run.js +23 -0
  57. package/dist/cli/handlers/pr.d.ts +5 -0
  58. package/dist/cli/handlers/pr.d.ts.map +1 -1
  59. package/dist/cli/handlers/pr.js +259 -4
  60. package/dist/cli/handlers/run-wave.js +89 -1
  61. package/dist/cli/main.d.ts.map +1 -1
  62. package/dist/cli/main.js +56 -2
  63. package/dist/cli/parse-args.d.ts.map +1 -1
  64. package/dist/cli/parse-args.js +107 -0
  65. package/dist/cli/registry.d.ts +38 -0
  66. package/dist/cli/registry.d.ts.map +1 -1
  67. package/dist/components/adoption.d.ts.map +1 -1
  68. package/dist/components/adoption.js +1 -2
  69. package/dist/components/capability.d.ts +37 -0
  70. package/dist/components/capability.d.ts.map +1 -1
  71. package/dist/components/capability.js +25 -0
  72. package/dist/components/check-hooks.d.ts +4 -1
  73. package/dist/components/check-hooks.d.ts.map +1 -1
  74. package/dist/components/check-steps.d.ts +74 -0
  75. package/dist/components/check-steps.d.ts.map +1 -0
  76. package/dist/components/check-steps.js +102 -0
  77. package/dist/components/ci-services.d.ts.map +1 -1
  78. package/dist/components/ci-services.js +1 -2
  79. package/dist/components/driver.d.ts +12 -0
  80. package/dist/components/driver.d.ts.map +1 -1
  81. package/dist/components/driver.js +35 -1
  82. package/dist/components/groups.d.ts.map +1 -1
  83. package/dist/components/groups.js +4 -3
  84. package/dist/components/pr-env-ledger.d.ts.map +1 -1
  85. package/dist/components/pr-env-ledger.js +1 -2
  86. package/dist/components/pr-environment.d.ts +1 -1
  87. package/dist/components/pr-environment.d.ts.map +1 -1
  88. package/dist/components/pr-environment.js +1 -1
  89. package/dist/components/pr-pipeline.d.ts +129 -3
  90. package/dist/components/pr-pipeline.d.ts.map +1 -1
  91. package/dist/components/pr-pipeline.js +153 -17
  92. package/dist/components/pr-run.d.ts +8 -0
  93. package/dist/components/pr-run.d.ts.map +1 -1
  94. package/dist/components/pr-run.js +9 -4
  95. package/dist/components/product-pipeline.d.ts +35 -2
  96. package/dist/components/product-pipeline.d.ts.map +1 -1
  97. package/dist/components/product-pipeline.js +24 -5
  98. package/dist/components/wave-plan.d.ts +8 -0
  99. package/dist/components/wave-plan.d.ts.map +1 -1
  100. package/dist/components/wave-plan.js +18 -2
  101. package/dist/e2e-harness/bucket.d.ts +21 -0
  102. package/dist/e2e-harness/bucket.d.ts.map +1 -0
  103. package/dist/e2e-harness/bucket.js +61 -0
  104. package/dist/e2e-harness/claim.d.ts +70 -0
  105. package/dist/e2e-harness/claim.d.ts.map +1 -0
  106. package/dist/e2e-harness/claim.js +98 -0
  107. package/dist/e2e-harness/driver.d.ts +64 -0
  108. package/dist/e2e-harness/driver.d.ts.map +1 -0
  109. package/dist/e2e-harness/driver.js +243 -0
  110. package/dist/e2e-harness/forgejo.d.ts +77 -0
  111. package/dist/e2e-harness/forgejo.d.ts.map +1 -0
  112. package/dist/e2e-harness/forgejo.js +205 -0
  113. package/dist/e2e-harness/git.d.ts +32 -0
  114. package/dist/e2e-harness/git.d.ts.map +1 -0
  115. package/dist/e2e-harness/git.js +67 -0
  116. package/dist/e2e-harness/index.d.ts +22 -0
  117. package/dist/e2e-harness/index.d.ts.map +1 -0
  118. package/dist/e2e-harness/index.js +48 -0
  119. package/dist/e2e-harness/jobs.d.ts +8 -0
  120. package/dist/e2e-harness/jobs.d.ts.map +1 -0
  121. package/dist/e2e-harness/jobs.js +34 -0
  122. package/dist/e2e-harness/pins.d.ts +45 -0
  123. package/dist/e2e-harness/pins.d.ts.map +1 -0
  124. package/dist/e2e-harness/pins.js +44 -0
  125. package/dist/e2e-harness/ports.d.ts +113 -0
  126. package/dist/e2e-harness/ports.d.ts.map +1 -0
  127. package/dist/e2e-harness/ports.js +4 -0
  128. package/dist/e2e-harness/reports.d.ts +45 -0
  129. package/dist/e2e-harness/reports.d.ts.map +1 -0
  130. package/dist/e2e-harness/reports.js +57 -0
  131. package/dist/e2e-harness/safe-run-cli.d.ts +17 -0
  132. package/dist/e2e-harness/safe-run-cli.d.ts.map +1 -0
  133. package/dist/e2e-harness/safe-run-cli.js +43 -0
  134. package/dist/e2e-harness/safe-run.d.ts +61 -0
  135. package/dist/e2e-harness/safe-run.d.ts.map +1 -0
  136. package/dist/e2e-harness/safe-run.js +172 -0
  137. package/dist/e2e-harness/scenario.d.ts +11 -0
  138. package/dist/e2e-harness/scenario.d.ts.map +1 -0
  139. package/dist/e2e-harness/scenario.js +89 -0
  140. package/dist/e2e-harness/schemas/demo-cycle.schema.json +282 -0
  141. package/dist/e2e-harness/schemas/demo-step.schema.json +245 -0
  142. package/dist/e2e-harness/schemas/e2e-claim-row.schema.json +33 -0
  143. package/dist/e2e-harness/schemas/e2e-claims.schema.json +18 -0
  144. package/dist/e2e-harness/schemas/e2e-scenario.schema.json +150 -0
  145. package/dist/e2e-harness/schemas/index.d.ts +191 -0
  146. package/dist/e2e-harness/schemas/index.d.ts.map +1 -0
  147. package/dist/e2e-harness/schemas/index.js +62 -0
  148. package/dist/e2e-harness/stack.d.ts +124 -0
  149. package/dist/e2e-harness/stack.d.ts.map +1 -0
  150. package/dist/e2e-harness/stack.js +207 -0
  151. package/dist/e2e-harness/steps.d.ts +11 -0
  152. package/dist/e2e-harness/steps.d.ts.map +1 -0
  153. package/dist/e2e-harness/steps.js +22 -0
  154. package/dist/e2e-harness.d.ts +3 -0
  155. package/dist/e2e-harness.d.ts.map +1 -0
  156. package/dist/e2e-harness.js +2 -0
  157. package/dist/exit-codes.d.ts +7 -1
  158. package/dist/exit-codes.d.ts.map +1 -1
  159. package/dist/exit-codes.js +7 -1
  160. package/dist/lexicon.d.ts +46 -0
  161. package/dist/lexicon.d.ts.map +1 -1
  162. package/dist/lifecycle/gate-ledger.d.ts.map +1 -1
  163. package/dist/lifecycle/gate-ledger.js +2 -3
  164. package/dist/lifecycle/gated-request.d.ts.map +1 -1
  165. package/dist/lifecycle/gated-request.js +1 -2
  166. package/dist/lifecycle/query.d.ts.map +1 -1
  167. package/dist/lifecycle/query.js +4 -5
  168. package/dist/lifecycle/release-catalog.d.ts.map +1 -1
  169. package/dist/lifecycle/release-catalog.js +1 -1
  170. package/dist/lifecycle/release-ledger.d.ts.map +1 -1
  171. package/dist/lifecycle/release-ledger.js +1 -2
  172. package/dist/lifecycle/release-status.d.ts +20 -0
  173. package/dist/lifecycle/release-status.d.ts.map +1 -1
  174. package/dist/lifecycle/release-status.js +1 -22
  175. package/dist/lifecycle/wave-plans.d.ts +23 -7
  176. package/dist/lifecycle/wave-plans.d.ts.map +1 -1
  177. package/dist/lifecycle/wave-plans.js +9 -2
  178. package/dist/op/approval-status.d.ts +103 -0
  179. package/dist/op/approval-status.d.ts.map +1 -0
  180. package/dist/op/approval-status.js +197 -0
  181. package/dist/op/index.d.ts +1 -1
  182. package/dist/op/index.d.ts.map +1 -1
  183. package/dist/op/index.js +1 -1
  184. package/dist/op/op-waves-capability-spec.d.ts +8 -0
  185. package/dist/op/op-waves-capability-spec.d.ts.map +1 -1
  186. package/dist/op/op-waves-capability-spec.js +21 -0
  187. package/dist/op/op-waves-release.d.ts.map +1 -1
  188. package/dist/op/op-waves-release.js +1 -2
  189. package/dist/op/op-waves-run.d.ts +7 -2
  190. package/dist/op/op-waves-run.d.ts.map +1 -1
  191. package/dist/op/op-waves-run.js +96 -4
  192. package/dist/op/op-waves-stand-down.d.ts.map +1 -1
  193. package/dist/op/op-waves-stand-down.js +1 -2
  194. package/dist/op/op-waves.d.ts +35 -0
  195. package/dist/op/op-waves.d.ts.map +1 -1
  196. package/dist/op/op-waves.js +46 -6
  197. package/dist/op/runtime.d.ts +4 -0
  198. package/dist/op/runtime.d.ts.map +1 -1
  199. package/dist/op/runtime.js +2 -3
  200. package/dist/otlp.d.ts.map +1 -1
  201. package/dist/otlp.js +1 -2
  202. package/dist/parallelism.d.ts +17 -0
  203. package/dist/parallelism.d.ts.map +1 -0
  204. package/dist/parallelism.js +33 -0
  205. package/dist/policy-source.d.ts.map +1 -1
  206. package/dist/policy-source.js +1 -2
  207. package/dist/pr-forge.d.ts.map +1 -1
  208. package/dist/pr-forge.js +56 -39
  209. package/dist/pr-loop.d.ts +9 -0
  210. package/dist/pr-loop.d.ts.map +1 -1
  211. package/dist/pr-loop.js +22 -3
  212. package/dist/pr-merge.d.ts +64 -0
  213. package/dist/pr-merge.d.ts.map +1 -0
  214. package/dist/pr-merge.js +78 -0
  215. package/dist/pr-post.d.ts +70 -1
  216. package/dist/pr-post.d.ts.map +1 -1
  217. package/dist/pr-post.js +116 -5
  218. package/dist/pr-report-url.d.ts.map +1 -1
  219. package/dist/pr-report-url.js +1 -2
  220. package/dist/release-floors.d.ts +1 -1
  221. package/dist/release-floors.js +1 -1
  222. package/dist/run-event.d.ts.map +1 -1
  223. package/dist/run-event.js +1 -2
  224. package/dist/scheduled-op-cloud.d.ts +32 -0
  225. package/dist/scheduled-op-cloud.d.ts.map +1 -0
  226. package/dist/scheduled-op-cloud.js +69 -0
  227. package/dist/wave-runtime.mjs +340 -327
  228. package/dist/workspace/ci-lock-grain.d.ts +5 -0
  229. package/dist/workspace/ci-lock-grain.d.ts.map +1 -1
  230. package/dist/workspace/ci-lock-grain.js +1 -7
  231. package/dist/workspace/ci-run.d.ts.map +1 -1
  232. package/dist/workspace/ci-run.js +5 -1
  233. package/dist/workspace/pr-report.schema.json +5 -0
  234. package/package.json +1 -1
  235. package/src/ci-agent.ts +1 -2
  236. package/src/ci-audit/__fixtures__/cloudtrail-lookup-bucket.json +37 -0
  237. package/src/ci-audit/__fixtures__/cloudtrail-writes-window.json +59 -0
  238. package/src/ci-audit/attribution.ts +260 -0
  239. package/src/ci-audit/audit-log.ts +220 -0
  240. package/src/ci-audit/ci-audit.test.ts +175 -0
  241. package/src/ci-audit/index.ts +15 -0
  242. package/src/ci-audit/unrecorded.ts +140 -0
  243. package/src/ci-audit.ts +2 -0
  244. package/src/ci-control.ts +3 -4
  245. package/src/ci-estate.ts +1 -2
  246. package/src/ci-identity-database.test.ts +2 -3
  247. package/src/ci-identity-targets.test.ts +1 -3
  248. package/src/ci-identity.ts +2 -3
  249. package/src/ci-job-guard.test.ts +154 -0
  250. package/src/ci-job-guard.ts +319 -0
  251. package/src/ci-jobs.ts +8 -0
  252. package/src/ci-product-comment-targets.test.ts +45 -0
  253. package/src/ci-product-words.ts +35 -6
  254. package/src/ci-product.ts +55 -3
  255. package/src/ci-respond-run.ts +291 -0
  256. package/src/ci-respond.test.ts +264 -0
  257. package/src/ci-respond.ts +412 -0
  258. package/src/cli/handlers/audit-log.ts +74 -0
  259. package/src/cli/handlers/build-pr-loop-flags.test.ts +98 -0
  260. package/src/cli/handlers/build.ts +69 -0
  261. package/src/cli/handlers/ci-check-job.test.ts +114 -0
  262. package/src/cli/handlers/ci-check-job.ts +33 -0
  263. package/src/cli/handlers/ci-check.ts +38 -8
  264. package/src/cli/handlers/e2e-safe-run.ts +27 -0
  265. package/src/cli/handlers/pr-plan-comment-targets.test.ts +166 -0
  266. package/src/cli/handlers/pr-plan-flags.test.ts +161 -0
  267. package/src/cli/handlers/pr.ts +228 -4
  268. package/src/cli/handlers/run-wave.ts +79 -1
  269. package/src/cli/main.test.ts +1 -1
  270. package/src/cli/main.ts +56 -2
  271. package/src/cli/parse-args.ts +77 -0
  272. package/src/cli/registry.ts +38 -0
  273. package/src/components/adoption.ts +1 -2
  274. package/src/components/capability.ts +50 -0
  275. package/src/components/check-hooks.ts +4 -1
  276. package/src/components/check-steps.test.ts +70 -0
  277. package/src/components/check-steps.ts +158 -0
  278. package/src/components/ci-services.ts +1 -2
  279. package/src/components/driver.ts +35 -1
  280. package/src/components/groups.ts +4 -2
  281. package/src/components/plan-flags.test.ts +46 -0
  282. package/src/components/pr-comment-preview-targets.test.ts +34 -0
  283. package/src/components/pr-env-ledger.ts +1 -2
  284. package/src/components/pr-env-run-bundle.test.ts +0 -20
  285. package/src/components/pr-environment.ts +1 -1
  286. package/src/components/pr-pipeline-runners.test.ts +80 -0
  287. package/src/components/pr-pipeline.ts +232 -17
  288. package/src/components/pr-run.ts +17 -6
  289. package/src/components/pr-stale-job.test.ts +34 -0
  290. package/src/components/product-pipeline.ts +50 -8
  291. package/src/components/wave-plan.ts +18 -2
  292. package/src/e2e-harness/__project__/chant.config.ts +4 -0
  293. package/src/e2e-harness/__project__/src/compose.ts +33 -0
  294. package/src/e2e-harness/bucket.ts +69 -0
  295. package/src/e2e-harness/claim.test.ts +150 -0
  296. package/src/e2e-harness/claim.ts +140 -0
  297. package/src/e2e-harness/driver.test.ts +304 -0
  298. package/src/e2e-harness/driver.ts +294 -0
  299. package/src/e2e-harness/forgejo.ts +267 -0
  300. package/src/e2e-harness/git.ts +96 -0
  301. package/src/e2e-harness/index.ts +50 -0
  302. package/src/e2e-harness/jobs.ts +35 -0
  303. package/src/e2e-harness/pins.ts +52 -0
  304. package/src/e2e-harness/ports.ts +130 -0
  305. package/src/e2e-harness/reports.ts +79 -0
  306. package/src/e2e-harness/safe-run-cli.test.ts +102 -0
  307. package/src/e2e-harness/safe-run-cli.ts +54 -0
  308. package/src/e2e-harness/safe-run.ts +198 -0
  309. package/src/e2e-harness/scenario.ts +89 -0
  310. package/src/e2e-harness/schemas/README.md +62 -0
  311. package/src/e2e-harness/schemas/demo-cycle.schema.json +282 -0
  312. package/src/e2e-harness/schemas/demo-step.schema.json +245 -0
  313. package/src/e2e-harness/schemas/e2e-claim-row.schema.json +33 -0
  314. package/src/e2e-harness/schemas/e2e-claims.schema.json +18 -0
  315. package/src/e2e-harness/schemas/e2e-scenario.schema.json +150 -0
  316. package/src/e2e-harness/schemas/index.ts +220 -0
  317. package/src/e2e-harness/schemas.test.ts +145 -0
  318. package/src/e2e-harness/stack.test.ts +124 -0
  319. package/src/e2e-harness/stack.ts +306 -0
  320. package/src/e2e-harness/steps.ts +30 -0
  321. package/src/e2e-harness.ts +2 -0
  322. package/src/exit-codes.test.ts +3 -2
  323. package/src/exit-codes.ts +7 -1
  324. package/src/gate-decision-bundle.test.ts +0 -2
  325. package/src/lexicon.ts +48 -0
  326. package/src/lifecycle/control-entries-ledger.test.ts +2 -3
  327. package/src/lifecycle/gate-ledger.ts +2 -3
  328. package/src/lifecycle/gated-request.ts +1 -2
  329. package/src/lifecycle/query.ts +4 -5
  330. package/src/lifecycle/release-catalog.test.ts +3 -4
  331. package/src/lifecycle/release-catalog.ts +1 -1
  332. package/src/lifecycle/release-ledger.ts +1 -2
  333. package/src/lifecycle/release-status.test.ts +3 -4
  334. package/src/lifecycle/release-status.ts +1 -2
  335. package/src/lifecycle/wave-plans.ts +33 -5
  336. package/src/op/approval-status.test.ts +134 -0
  337. package/src/op/approval-status.ts +235 -0
  338. package/src/op/gate-review.test.ts +2 -1
  339. package/src/op/index.ts +2 -0
  340. package/src/op/op-waves-after-plan.test.ts +12 -0
  341. package/src/op/op-waves-capability-spec.ts +20 -0
  342. package/src/op/op-waves-parallelism.test.ts +89 -0
  343. package/src/op/op-waves-pull-request.test.ts +78 -1
  344. package/src/op/op-waves-release.ts +1 -2
  345. package/src/op/op-waves-run.ts +94 -4
  346. package/src/op/op-waves-stand-down.ts +1 -2
  347. package/src/op/op-waves.ts +63 -6
  348. package/src/op/runtime.ts +6 -3
  349. package/src/otlp.ts +1 -2
  350. package/src/parallelism.test.ts +38 -0
  351. package/src/parallelism.ts +33 -0
  352. package/src/policy-source.ts +1 -2
  353. package/src/pr-forge-bundle.test.ts +1 -1
  354. package/src/pr-forge.ts +54 -35
  355. package/src/pr-loop-bundle.test.ts +1 -1
  356. package/src/pr-loop-narrowed.test.ts +63 -0
  357. package/src/pr-loop.ts +30 -3
  358. package/src/pr-merge.test.ts +100 -0
  359. package/src/pr-merge.ts +105 -0
  360. package/src/pr-post-stale.test.ts +163 -0
  361. package/src/pr-post.ts +159 -5
  362. package/src/pr-report-url.ts +1 -2
  363. package/src/product-subpaths-plain-node.e2e.test.ts +1 -0
  364. package/src/release-floors.ts +1 -1
  365. package/src/run-event.ts +1 -2
  366. package/src/scheduled-op-cloud.ts +68 -0
  367. package/src/stage-hooks-bundle.test.ts +0 -2
  368. package/src/workspace/ci-lock-grain.ts +1 -2
  369. package/src/workspace/ci-run.ts +5 -1
  370. package/src/workspace/pr-report.schema.json +5 -0
@@ -0,0 +1,161 @@
1
+ /**
2
+ * `pr-plan --refresh` and `--target-dependents` (#4627): each reaches the
3
+ * planned members' capability plans through `DeployContext`, the digest
4
+ * binds it, `--target-dependents` needs a target, a member whose capability
5
+ * cannot honour one is refused by name before anything plans, and pr-apply
6
+ * takes neither. The setup is pr-plan-targets.test.ts's. Written for the
7
+ * ci-products post-merge pass.
8
+ */
9
+
10
+ import { mkdtemp, readFile, rm } from "node:fs/promises";
11
+ import { tmpdir } from "node:os";
12
+ import { join } from "node:path";
13
+ import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
14
+ import type { DriverComponent } from "../../components/driver";
15
+ import type { DeployContext } from "../../components/capability";
16
+ import type { ParsedArgs } from "../registry";
17
+
18
+ const HEAD = "a".repeat(40);
19
+ const BASE = "b".repeat(40);
20
+
21
+ vi.mock("../../workspace/security", async (original) => ({
22
+ ...(await original<typeof import("../../workspace/security")>()),
23
+ securityGroupsAt: () => new Set<string>(),
24
+ }));
25
+ vi.mock("../../components/pr-hooks", async (original) => ({
26
+ ...(await original<typeof import("../../components/pr-hooks")>()),
27
+ prLoopHooksAt: (_cwd: string, base: string) => ({ hooks: {}, base }),
28
+ }));
29
+ vi.mock("../../workspace/ci-locks", () => ({ ciLocksAt: () => null }));
30
+ vi.mock("../../components/pr-policy", async (original) => ({
31
+ ...(await original<typeof import("../../components/pr-policy")>()),
32
+ prLoopPolicyAt: (_cwd: string, base: string) => ({ base }),
33
+ runPrPolicy: () => undefined,
34
+ }));
35
+ vi.mock("../../components/changed-files", () => ({
36
+ resolveCommit: async () => HEAD,
37
+ resolveMergeBase: async () => BASE,
38
+ }));
39
+ vi.mock("../../config", async () => {
40
+ const actual = await vi.importActual<typeof import("../../config")>("../../config");
41
+ return { ...actual, loadChantConfig: async () => ({ config: {} }) };
42
+ });
43
+ vi.mock("./fan-out", () => ({
44
+ resolveChangedUnits: async () => ({ units: { changed: ["net"], indeterminate: [] } }),
45
+ }));
46
+ vi.mock("../../lifecycle/git", async () => {
47
+ const actual = await vi.importActual<typeof import("../../lifecycle/git")>("../../lifecycle/git");
48
+ return { ...actual, pushLifecycleReport: async () => { throw new Error("pr-plan-flags.test must not push chant/lifecycle"); } };
49
+ });
50
+ vi.mock("./run", () => ({
51
+ GATED_EXIT_CODE: 3,
52
+ autoReleaseRun: (id: string) => ({ runId: id, runOrigin: { forge: "local" } }),
53
+ recordAutoReleasesForRun: async () => [],
54
+ }));
55
+ let gateLedger: ReturnType<typeof import("../../op/gate").memoryGateLedgerPort>;
56
+ vi.mock("../../op/gate", async () => {
57
+ const actual = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
58
+ return { ...actual, gitGateLedgerPort: () => gateLedger, gateIsSealed: async () => false };
59
+ });
60
+
61
+ /** The targets each member's plan was asked for. */
62
+ const asked = new Map<string, string[] | undefined>();
63
+ /** The plan flags each member's plan was asked for (#4627). */
64
+ const flagsAsked = new Map<string, { refresh: boolean; targetDependents: boolean }>();
65
+ let estate: DriverComponent[] = [];
66
+ vi.mock("../../components/fan-out-support", async () => {
67
+ const { CapabilityRegistry } = await import("../../components/capability");
68
+ const { planFanOut } = await import("../../components/fan-out");
69
+ const { computePlanDigest } = await import("../../lifecycle/plan-digest");
70
+ const registry = new CapabilityRegistry();
71
+ const plan = (kind: string) => async (ctx: DeployContext, input: { root: string }) => {
72
+ asked.set(input.root, ctx.targets);
73
+ flagsAsked.set(input.root, { refresh: ctx.refresh === true, targetDependents: ctx.targetDependents === true });
74
+ const planDigest = computePlanDigest(kind, { root: input.root });
75
+ return {
76
+ member: input.root,
77
+ planDigest,
78
+ artifact: { planDigest },
79
+ ...(ctx.targets ? { targets: ctx.targets } : {}),
80
+ changeSet: { member: { member: input.root, lexicon: "terraform", planner: "tofu", status: "planned", planDigest, holes: [] }, entries: [] },
81
+ };
82
+ };
83
+ registry.register({ kind: "narrowing-root", targets: "accept", planFlags: { refresh: "accept", targetDependents: "accept" }, plan: plan("narrowing-root"), async outputs() { return {}; }, async run() { return { outputs: {} }; } } as never);
84
+ registry.register({ kind: "whole-root", targets: "accept", planFlags: { refresh: "accept", targetDependents: { refuse: "a whole-root has no flag for dependents" } }, plan: plan("whole-root"), async outputs() { return {}; }, async run() { return { outputs: {} }; } } as never);
85
+ return {
86
+ fanOutRegistry: async () => registry,
87
+ deriveFanOut: async () => ({
88
+ success: true,
89
+ components: estate,
90
+ plan: planFanOut({ components: estate, changed: estate.map((c) => c.name) }),
91
+ signal: { changed: estate.map((c) => c.name), indeterminate: [], unclaimed: [] },
92
+ }),
93
+ };
94
+ });
95
+
96
+ const root = (name: string, kind = "narrowing-root"): DriverComponent => ({ name, dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind, root: name }] }] });
97
+
98
+ const { memoryGateLedgerPort } = await import("../../op/gate");
99
+ const { runComponentsPrApply, runComponentsPrPlan } = await import("./pr");
100
+
101
+ let dir: string;
102
+ let errors: string[];
103
+
104
+ const ctx = (a: Partial<ParsedArgs>) =>
105
+ ({ args: { command: "components", path: "pr-plan", format: "", fix: false, watch: false, verbose: false, help: false, live: false, base: "main", env: "prod", output: dir, pr: 12, ...a } as ParsedArgs, plugins: [] }) as never;
106
+
107
+ beforeEach(async () => {
108
+ dir = await mkdtemp(join(tmpdir(), "pr-targets-"));
109
+ errors = [];
110
+ asked.clear();
111
+ flagsAsked.clear();
112
+ estate = [root("net"), root("app")];
113
+ gateLedger = memoryGateLedgerPort();
114
+ vi.spyOn(process.stdout, "write").mockImplementation(() => true);
115
+ vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.map(String).join(" ")); });
116
+ vi.spyOn(console, "log").mockImplementation(() => {});
117
+ });
118
+
119
+ afterEach(async () => {
120
+ vi.restoreAllMocks();
121
+ await rm(dir, { recursive: true, force: true });
122
+ });
123
+
124
+ const digest = async (): Promise<string> => JSON.parse(await readFile(join(dir, "pr-plan.json"), "utf8")).digest as string;
125
+
126
+ describe("pr-plan --refresh and --target-dependents (#4627)", () => {
127
+ test("--refresh reaches every plan, and the digest binds it", async () => {
128
+ expect(await runComponentsPrPlan(ctx({}))).toBe(0);
129
+ const plain = await digest();
130
+ expect(await runComponentsPrPlan(ctx({ refresh: true }))).toBe(0);
131
+ expect(flagsAsked.get("net")).toEqual({ refresh: true, targetDependents: false });
132
+ expect(await digest()).not.toBe(plain);
133
+ });
134
+
135
+ test("--target-dependents reaches the targeted members' plans, and moves the digest", async () => {
136
+ expect(await runComponentsPrPlan(ctx({ targets: ["net:module.vpc"] }))).toBe(0);
137
+ const narrowed = await digest();
138
+ expect(await runComponentsPrPlan(ctx({ targets: ["net:module.vpc"], targetDependents: true }))).toBe(0);
139
+ expect(flagsAsked.get("net")).toEqual({ refresh: false, targetDependents: true });
140
+ expect(flagsAsked.get("app")).toEqual({ refresh: false, targetDependents: false });
141
+ expect(await digest()).not.toBe(narrowed);
142
+ });
143
+
144
+ test("--target-dependents without a target is refused", async () => {
145
+ expect(await runComponentsPrPlan(ctx({ targetDependents: true }))).toBe(1);
146
+ expect(flagsAsked.size).toBe(0);
147
+ expect(errors.join("\n")).toMatch(/widens a --target/);
148
+ });
149
+
150
+ test("a member whose capability cannot widen is refused by name, before anything plans", async () => {
151
+ estate = [root("net"), root("db", "whole-root")];
152
+ expect(await runComponentsPrPlan(ctx({ targets: ["aws_s3_bucket.logs"], targetDependents: true }))).toBe(1);
153
+ expect(flagsAsked.size).toBe(0);
154
+ expect(errors.join("\n")).toMatch(/whole-root refuses --target-dependents: a whole-root has no flag for dependents/);
155
+ });
156
+
157
+ test("pr-apply takes neither", async () => {
158
+ expect(await runComponentsPrApply(ctx({ path: "pr-apply", refresh: true }))).toBe(1);
159
+ expect(errors.join("\n")).toMatch(/takes no --refresh/);
160
+ });
161
+ });
@@ -122,7 +122,7 @@ import {
122
122
  import { FORGE_KINDS, forgeFromEnv, forgePrincipalOf, type ForgeKind, type PrForge } from "../../pr-forge";
123
123
  import { GITHUB_COMMENT_LIMIT, GITLAB_NOTE_LIMIT } from "../../plan-summary";
124
124
  import { upsertPlanNote } from "../../pr-post";
125
- import { activeProductWords, productContext } from "../../ci-product-words";
125
+ import { activeProductWords, commandWord, parseProductComment, productContext } from "../../ci-product-words";
126
126
  import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
127
127
  import { formatError, formatInfo, formatSuccess, formatWarning } from "../format";
128
128
  import { reportUninstalledDependencies } from "../dependencies";
@@ -135,9 +135,10 @@ import type { CommandContext } from "../registry";
135
135
  import { parseArgs } from "../parse-args";
136
136
  import { withComponentEndpoint } from "../component-endpoint";
137
137
  import type { ComponentChangeSignal, FanOutPlan } from "../../components/fan-out";
138
- import { assertTargetsAccepted, failedRunExitCode, type DriverComponent } from "../../components/driver";
139
- import { TargetsRefusedError, type CapabilityRegistry } from "../../components/capability";
138
+ import { assertPlanFlagsAccepted, assertTargetsAccepted, failedRunExitCode, type DriverComponent } from "../../components/driver";
139
+ import { PLAN_FLAG_ARGS, PlanFlagRefusedError, TargetsRefusedError, type CapabilityRegistry } from "../../components/capability";
140
140
  import { prPlanTargets } from "../../components/pr-targets";
141
+ import { PREVIEW_COMMENT_ENV } from "../../components/pr-pipeline";
141
142
  import type { ComponentEnvironmentDeclaration } from "../../components/component";
142
143
  import { prLoopHooksAt, runPrHooks, type PrHoldSettled, type PrHookPlace, type PrLoopHooks } from "../../components/pr-hooks";
143
144
  import { decidePrPolicyOverride, policyReviewOf, prLoopPolicyAt, prPolicyReport, runPrPolicy, spendPrPolicyOverride, type PrLoopPolicy } from "../../components/pr-policy";
@@ -181,6 +182,11 @@ export interface Prepared {
181
182
  hookPlace?: PrHookPlace;
182
183
  /** `pr-plan --target` (#4620): the addresses each planned member's capability plan narrows to. */
183
184
  targets?: Record<string, string[]>;
185
+ /** `pr-plan --parallelism <n>` (#4625): how many members of a wave plan at once. */
186
+ parallelism?: number;
187
+ /** `pr-plan --refresh` and `--target-dependents` (#4627). */
188
+ refresh?: boolean;
189
+ targetDependents?: boolean;
184
190
  /**
185
191
  * Set when `ci.branches` or `ci.labels` (#4292) leave the member out of this
186
192
  * stage: why. The plan is then empty, so the stage reports `nothing`.
@@ -224,6 +230,10 @@ export async function prepare(ctx: CommandContext, stage: "plan" | "apply" | "re
224
230
  if (stage !== "plan" && args.targets && args.targets.length > 0) {
225
231
  return fail(`pr-${stage} applies or records what the pull request's approved plan covers, so it takes no --target`, "Narrow the plan with pr-plan --target, and approve that plan.");
226
232
  }
233
+ // #4627: refresh and target dependents change what the preview plans, as a target does.
234
+ if (stage !== "plan" && (args.refresh || args.targetDependents)) {
235
+ return fail(`pr-${stage} applies or records what the pull request's approved plan covers, so it takes no ${args.refresh ? "--refresh" : "--target-dependents"}`, "Plan with pr-plan --refresh or --target-dependents, and approve that plan.");
236
+ }
227
237
  let member: string | undefined;
228
238
  if (args.members?.length) {
229
239
  const checked = await checkMember(projectPath, args.members);
@@ -502,9 +512,58 @@ export async function planBare(p: Prepared, onRunEvent?: RunEventSink): Promise<
502
512
  policyBase: p.base,
503
513
  ...(onRunEvent ? { onRunEvent } : {}),
504
514
  ...(p.targets ? { targets: p.targets } : {}),
515
+ ...(p.parallelism !== undefined ? { parallelism: p.parallelism } : {}),
516
+ ...(p.refresh ? { refresh: true } : {}),
517
+ ...(p.targetDependents ? { targetDependents: true } : {}),
505
518
  });
506
519
  }
507
520
 
521
+ /**
522
+ * `pr-plan --refresh` and `--target-dependents` (#4627), from the line or
523
+ * the preview comment: set on `p`, or the exit code when a planned member's
524
+ * capability cannot honour one, named before anything plans, as
525
+ * {@link narrowToTargets} does for targets. `--target-dependents` needs a
526
+ * target.
527
+ */
528
+ function planWithFlags(p: Prepared, flags: { refresh?: boolean; targetDependents?: boolean }): number | undefined {
529
+ if (!flags.refresh && !flags.targetDependents) return undefined;
530
+ if (flags.targetDependents && !p.targets) return fail("--target-dependents widens a --target to what depends on it, and nothing was narrowed", "Give --target <address> with it.");
531
+ const byName = new Map(p.components.map((c) => [c.name, c]));
532
+ for (const name of p.plan.order) {
533
+ const component = byName.get(name);
534
+ if (!component) continue;
535
+ try {
536
+ assertPlanFlagsAccepted(component, p.registry, { ...(flags.refresh ? { refresh: true } : {}), ...(flags.targetDependents && p.targets?.[name] ? { targetDependents: true } : {}) });
537
+ } catch (err) {
538
+ if (err instanceof PlanFlagRefusedError) return fail(`${err.message}, so nothing was planned`, `Drop ${PLAN_FLAG_ARGS[err.flag]}, or plan only members whose steps take it.`);
539
+ throw err;
540
+ }
541
+ }
542
+ if (flags.refresh) p.refresh = true;
543
+ if (flags.targetDependents) p.targetDependents = true;
544
+ console.error(formatInfo(`planning with ${[flags.refresh ? "--refresh" : "", flags.targetDependents ? "--target-dependents" : ""].filter(Boolean).join(" and ")}`));
545
+ return undefined;
546
+ }
547
+
548
+ /**
549
+ * `pr-plan --comment-targets` (#4626): the `--target` addresses of the
550
+ * preview comment in {@link PREVIEW_COMMENT_ENV}, read with the product's
551
+ * grammar, or the exit code when the comment is refused. No comment, or one
552
+ * with no target: none. The checks `--target` makes follow in
553
+ * {@link narrowToTargets}.
554
+ */
555
+ function commentTargets(env: NodeJS.ProcessEnv = process.env): { targets: string[]; refresh?: true; targetDependents?: true } | number {
556
+ const body = env[PREVIEW_COMMENT_ENV];
557
+ if (body === undefined || body.trim() === "") return { targets: [] };
558
+ const words = activeProductWords();
559
+ const parsed = parseProductComment(words, body, env);
560
+ if (parsed === undefined) return { targets: [] };
561
+ if (parsed.kind === "refused") return fail(`the preview comment is refused: ${parsed.reason}, so nothing was planned`, `/${words.product} ${commandWord(words, "plan") ?? "plan"} --target <address> narrows the preview to the address.`);
562
+ if (parsed.kind !== "plan") return { targets: [] };
563
+ // #4627: the comment's --refresh and --target-dependents too.
564
+ return { targets: parsed.targets ?? [], ...(parsed.refresh ? { refresh: true as const } : {}), ...(parsed.targetDependents ? { targetDependents: true as const } : {}) };
565
+ }
566
+
508
567
  /**
509
568
  * `pr-plan --target` (#4620): the addresses by member, set on `p`, or the
510
569
  * exit code when a value is refused or a targeted member has a capability
@@ -813,8 +872,14 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
813
872
  }
814
873
  const p = await prepare(ctx, "plan");
815
874
  if (typeof p === "number") return p;
816
- const narrowed = narrowToTargets(p, ctx.args.targets);
875
+ // #4626: the preview comment's --target addresses, read from the comment the job carries in a variable.
876
+ const fromComment = ctx.args.commentTargets ? commentTargets() : { targets: [] };
877
+ if (typeof fromComment === "number") return fromComment;
878
+ const narrowed = narrowToTargets(p, [...(ctx.args.targets ?? []), ...fromComment.targets]);
817
879
  if (narrowed !== undefined) return narrowed;
880
+ const flagged = planWithFlags(p, { refresh: ctx.args.refresh === true || fromComment.refresh === true, targetDependents: ctx.args.targetDependents === true || fromComment.targetDependents === true });
881
+ if (flagged !== undefined) return flagged;
882
+ if (ctx.args.parallelism !== undefined) p.parallelism = ctx.args.parallelism;
818
883
  const op = prOp(ctx.args.pr, p.member);
819
884
  placeHooks(ctx, p, "plan", op);
820
885
  const upload = openUpload(stage, "plan", ctx.args.pr, p);
@@ -955,6 +1020,9 @@ export function runComponentsPrApply(ctx: CommandContext): Promise<number> {
955
1020
  // #4301: an apply before merge asks the forge its requires checks before any of the head's code loads, the config included.
956
1021
  let beforeMerge: PrBeforeMerge | undefined;
957
1022
  if (ctx.args.requires && !ctx.args.beforeMerge) return fail("--requires names the checks of an apply before merge, so it needs --before-merge --pr <n>");
1023
+ // #4636: the merge after the update, checked before anything applies.
1024
+ const mergeProblem = await mergeArgsProblem(ctx.args);
1025
+ if (mergeProblem) return fail(mergeProblem);
958
1026
  if (ctx.args.beforeMerge) {
959
1027
  const checked = await beforeMergeChecks(ctx);
960
1028
  if (typeof checked === "number") return checked;
@@ -1268,9 +1336,65 @@ async function prApply(ctx: CommandContext, stage: StageEvents, beforeMerge?: Pr
1268
1336
  if (green && applied.status === "applied") await recordGreenApplied(p, green, set.doc.digest, approval, via);
1269
1337
  const code = await stop(report, exit, applied.run.status === "gated" ? "gated" : undefined);
1270
1338
  if (applied.status === "applied" && !afterFailed) console.error(formatSuccess(`applied the plan ${report.digest} approved by ${(approval.approvedBy ?? []).join(", ")}`));
1339
+ // #4636: an update before merge that applied every member merges the pull request, never the other way round.
1340
+ if (code === 0 && beforeMerge && pr !== null && args.merge === "auto" && applied.status === "applied" && !afterFailed) return mergeAfterUpdate(ctx, p, pr);
1271
1341
  return code;
1272
1342
  }
1273
1343
 
1344
+ /** `--merge`, `--merge-token-env` and `--merge-method` as one problem, or undefined when they hold together. */
1345
+ async function mergeArgsProblem(args: CommandContext["args"]): Promise<string | undefined> {
1346
+ const { PR_APPLY_MERGES, PR_MERGE_METHODS } = await import("../../pr-merge");
1347
+ if (args.merge === undefined) {
1348
+ if (args.mergeTokenEnv || args.mergeMethod) return "--merge-token-env and --merge-method go with --merge auto";
1349
+ return undefined;
1350
+ }
1351
+ if (!(PR_APPLY_MERGES as readonly string[]).includes(args.merge)) return `--merge takes ${PR_APPLY_MERGES.join(" or ")}, not ${args.merge}`;
1352
+ if (args.merge === "manual") return args.mergeTokenEnv || args.mergeMethod ? "--merge manual leaves the merge to a person, so it takes no --merge-token-env or --merge-method" : undefined;
1353
+ if (!args.beforeMerge) return "--merge auto merges a pull request once its update before merge applied, so it needs --before-merge --pr <n>";
1354
+ if (!args.mergeTokenEnv) return "--merge auto merges with a token of its own, never the job's: --merge-token-env <VAR> (on GitLab a protected variable)";
1355
+ if (args.mergeMethod && !(PR_MERGE_METHODS as readonly string[]).includes(args.mergeMethod)) return `--merge-method takes ${PR_MERGE_METHODS.join(", ")}, not ${args.mergeMethod}`;
1356
+ return undefined;
1357
+ }
1358
+
1359
+ /**
1360
+ * The merge after an update before merge applied (#4636): the apply's
1361
+ * records pushed to the ledger, the head checked again, then the forge's
1362
+ * merge with the token `--merge-token-env` names alone. A refusal is posted
1363
+ * on the pull request and exits as waiting (3); the update stays applied.
1364
+ */
1365
+ async function mergeAfterUpdate(ctx: CommandContext, p: Prepared, pr: number): Promise<number> {
1366
+ const { mergeAfterApply, mergeTokenEnv } = await import("../../pr-merge");
1367
+ const { pushLifecycleReport } = await import("../../lifecycle/git");
1368
+ const kind = p.forge?.kind ?? (ctx.args.forge as ForgeKind | undefined);
1369
+ if (!kind) return fail("--merge auto needs --forge <kind> to merge on");
1370
+ const env = mergeTokenEnv(ctx.args.mergeTokenEnv!);
1371
+ if ("error" in env) {
1372
+ console.error(formatWarning({ message: `the pull request was not merged: ${env.error}` }));
1373
+ return CHANT_EXIT.waiting;
1374
+ }
1375
+ let forge: PrForge;
1376
+ try {
1377
+ forge = forgeFromEnv(kind, env);
1378
+ } catch (err) {
1379
+ console.error(formatWarning({ message: `the pull request was not merged: ${err instanceof Error ? err.message : String(err)}` }));
1380
+ return CHANT_EXIT.waiting;
1381
+ }
1382
+ const pushed = await pushLifecycleReport();
1383
+ const merged = await mergeAfterApply({
1384
+ forge,
1385
+ pr,
1386
+ head: p.head,
1387
+ ...(ctx.args.mergeMethod ? { method: ctx.args.mergeMethod as "merge" | "squash" | "rebase" } : {}),
1388
+ recorded: { pushed: pushed.pushed, ...(pushed.pushWarning ? { warning: pushed.pushWarning } : {}) },
1389
+ });
1390
+ if (merged.merged) {
1391
+ console.error(formatSuccess(`merged ${kind === "gitlab" ? `!${pr}` : `#${pr}`} at ${p.head.slice(0, 12)}${merged.sha ? ` as ${merged.sha.slice(0, 12)}` : ""}`));
1392
+ return 0;
1393
+ }
1394
+ console.error(formatWarning({ message: `the pull request was not merged: ${merged.reason}${merged.posted ? "; the reason is posted on it" : ""}` }));
1395
+ return CHANT_EXIT.waiting;
1396
+ }
1397
+
1274
1398
  /**
1275
1399
  * Under `ci.locks` (#4293): the refusal when another open pull request holds
1276
1400
  * a lock on a component this apply reaches, else null. The targets are the
@@ -1635,6 +1759,8 @@ function stopper(ctx: CommandContext, p: Prepared, events: RunEventStream | unde
1635
1759
  return async (report: PrReport, code: number, settle?: RunEventSettleStatus): Promise<number> => {
1636
1760
  events?.settle(settle ?? settleOf(report.status), report.status === "plan-failed" || report.status === "failed" ? report.message ?? `pr-${report.stage} ${report.status}` : undefined);
1637
1761
  await finish(ctx, p, report, upload);
1762
+ // #4629: a failed apply's triage and a refused apply's diff, on the pull request.
1763
+ if (report.stage === "apply" && (report.status === "failed" || report.status === "refused") && !ctx.args.noStatus) await respondApply(ctx, p, report);
1638
1764
  console.error((code === 0 ? formatInfo : (m: string) => formatWarning({ message: m }))(`pr-${report.stage}: ${report.status}${report.refusal ? ` (${report.refusal})` : ""}`));
1639
1765
  if (report.message) console.error(report.message);
1640
1766
  printMembers(report);
@@ -1642,6 +1768,22 @@ function stopper(ctx: CommandContext, p: Prepared, events: RunEventStream | unde
1642
1768
  };
1643
1769
  }
1644
1770
 
1771
+ /** The responses an apply's report calls for (#4629), from `--respond` over `CHANT_RESPOND`. Never throws. */
1772
+ async function respondApply(ctx: CommandContext, p: Prepared, report: PrReport): Promise<void> {
1773
+ try {
1774
+ const { parseRespondList } = await import("../../ci-respond");
1775
+ const given = ctx.args.respond ? parseRespondList(ctx.args.respond) : {};
1776
+ if ("error" in given) {
1777
+ console.error(formatWarning({ message: `no response was posted: ${given.error}` }));
1778
+ return;
1779
+ }
1780
+ const { respondPrApply } = await import("../../ci-respond-run");
1781
+ await respondPrApply(p.forge, report, given);
1782
+ } catch (err) {
1783
+ console.error(formatWarning({ message: `the apply's responses were not posted: ${err instanceof Error ? err.message : String(err)}` }));
1784
+ }
1785
+ }
1786
+
1645
1787
  /** Why `--require-review` does not count an approval, or why the reviews could not be read. */
1646
1788
  type ReviewStop = { refusal: "author-approved" | "not-a-reviewer"; message: string } | { error: string } | undefined;
1647
1789
 
@@ -2574,6 +2716,7 @@ function writeWaveChangeSet(ctx: CommandContext, wave: number, doc: PrPlanSet["d
2574
2716
  */
2575
2717
  export async function runComponentsPrPost(ctx: CommandContext): Promise<number> {
2576
2718
  const { args } = ctx;
2719
+ if (args.stale) return runComponentsPrPostStale(ctx);
2577
2720
  if (args.open) return runComponentsPrPostOpen(ctx);
2578
2721
  if (args.pr === undefined) return fail("pr-post needs the pull or merge request: --pr <n>");
2579
2722
  if (!args.head || !/^[0-9a-f]{40}$/.test(args.head)) return fail("pr-post needs the full commit the plan job checked out: --head <sha>");
@@ -2588,6 +2731,8 @@ export async function runComponentsPrPost(ctx: CommandContext): Promise<number>
2588
2731
  }
2589
2732
  const { postPlanReport } = await import("../../pr-post");
2590
2733
  const member = args.members?.[0];
2734
+ const description = await descriptionCheckOf(ctx, forge);
2735
+ if (typeof description === "number") return description;
2591
2736
  const posted = await postPlanReport({
2592
2737
  forge,
2593
2738
  dir: resolve(args.output ?? PR_REPORT_DIR),
@@ -2598,6 +2743,10 @@ export async function runComponentsPrPost(ctx: CommandContext): Promise<number>
2598
2743
  ...(args.planResult ? { result: args.planResult } : {}),
2599
2744
  // #4289: the plan job could not ask the forge, so the note job does, from the Ops at the commit it checked out.
2600
2745
  overdue: () => overdueOps(forge, member),
2746
+ ...(description ? { description } : {}),
2747
+ // #4628: the target branch's commit for the note's tip line, and the job summary where the forge keeps one.
2748
+ ...(args.tip ? { baseTip: args.tip } : {}),
2749
+ ...(args.forge !== "gitlab" && process.env.GITHUB_STEP_SUMMARY ? { summaryFile: process.env.GITHUB_STEP_SUMMARY } : {}),
2601
2750
  });
2602
2751
  for (const message of posted.warnings) console.error(formatWarning({ message }));
2603
2752
  if (posted.refused) console.error(formatWarning({ message: `the plan report was not used: ${posted.refused}` }));
@@ -2605,6 +2754,76 @@ export async function runComponentsPrPost(ctx: CommandContext): Promise<number>
2605
2754
  return 0;
2606
2755
  }
2607
2756
 
2757
+ /**
2758
+ * The description check pr-post runs after the note (#4629), when the
2759
+ * responses turn it on (`--respond description=check`, or `CHANT_RESPOND`):
2760
+ * the `decide.backends` entry `--decide-backend` names, from chant.config
2761
+ * at the commit this job checked out (the target branch's, never the pull
2762
+ * request's), and the model `--decide-model` pins. On with no backend is
2763
+ * refused, so a pipeline that asks for the check learns it never ran.
2764
+ */
2765
+ async function descriptionCheckOf(ctx: CommandContext, forge: PrForge): Promise<((report: PrReport) => Promise<void>) | undefined | number> {
2766
+ const { parseRespondList, resolveResponses } = await import("../../ci-respond");
2767
+ const given = ctx.args.respond ? parseRespondList(ctx.args.respond) : {};
2768
+ if ("error" in given) return fail(given.error);
2769
+ if (resolveResponses(given, process.env, (m) => console.error(formatWarning({ message: m }))).description !== "check") return undefined;
2770
+ const name = ctx.args.decideBackend;
2771
+ if (!name || !ctx.args.decideModel) return fail("the description check asks a decide service, so it needs --decide-backend <name> and --decide-model <id>", "Name a decide.backends entry of chant.config, or turn the check off: --respond description=off");
2772
+ const { loadChantConfig } = await import("../../config");
2773
+ let backend;
2774
+ try {
2775
+ const loaded = await loadChantConfig(process.cwd());
2776
+ backend = loaded.config.decide?.backends?.[name];
2777
+ } catch (err) {
2778
+ return fail(`could not read decide.backends from chant.config: ${err instanceof Error ? err.message : String(err)}`);
2779
+ }
2780
+ if (!backend) return fail(`the description check names the backend ${name}, and chant.config has no decide.backends.${name}`);
2781
+ const { backendDescriptionAsk, respondDescription } = await import("../../ci-respond-run");
2782
+ const ask = backendDescriptionAsk(backend, { name, model: ctx.args.decideModel, cwd: process.cwd() });
2783
+ return async (report) => {
2784
+ await respondDescription(forge, report, { ask });
2785
+ };
2786
+ }
2787
+
2788
+ /**
2789
+ * `pr-post --stale --tip <sha> --env <env> --forge <kind> [--branch <branch>]
2790
+ * [--member <name>] [--preview-comment]` (#4628): after a push to the target
2791
+ * branch, mark each open pull request's note that was posted against
2792
+ * another commit stale, naming the comment that previews again with
2793
+ * `--preview-comment`, and set its plan status back to pending
2794
+ * (`markStaleNotes`, ../../pr-post.ts). The branch is `--branch`, else the
2795
+ * job's (`GITHUB_REF_NAME`, `CI_COMMIT_BRANCH`). It exits 0 once it has
2796
+ * marked, as `pr-post` does.
2797
+ */
2798
+ async function runComponentsPrPostStale(ctx: CommandContext): Promise<number> {
2799
+ const { args } = ctx;
2800
+ if (args.pr !== undefined || args.head) return fail("pr-post --stale finds each open pull request and its head itself, so it takes no --pr or --head");
2801
+ if (!args.tip) return fail("pr-post --stale needs the target branch's commit now: --tip <sha>");
2802
+ if (!args.env) return fail("pr-post needs the environment the plan was for: --env <env>");
2803
+ if (!args.forge || !(FORGE_KINDS as readonly string[]).includes(args.forge)) return fail(`pr-post posts to a forge: --forge ${FORGE_KINDS.join("|")}`);
2804
+ if (args.members && args.members.length > 1) return fail(`pr-post takes one --member, not ${args.members.join(", ")}`);
2805
+ const branch = args.branch ?? process.env.CI_COMMIT_BRANCH ?? process.env.GITHUB_REF_NAME;
2806
+ if (!branch) return fail("pr-post --stale marks the notes of the pull requests into a branch: run it in a job of a push, or pass --branch <branch>");
2807
+ let forge: PrForge;
2808
+ try {
2809
+ forge = forgeFromEnv(args.forge as ForgeKind);
2810
+ } catch (err) {
2811
+ return fail(err instanceof Error ? err.message : String(err));
2812
+ }
2813
+ const member = args.members?.[0];
2814
+ const { markStaleNotes } = await import("../../pr-post");
2815
+ let done: Awaited<ReturnType<typeof markStaleNotes>>;
2816
+ try {
2817
+ done = await markStaleNotes({ forge, branch, tip: args.tip, env: args.env, ...(member ? { member } : {}), ...(args.previewComment ? { previewComment: true } : {}) });
2818
+ } catch (err) {
2819
+ return fail(err instanceof Error ? err.message : String(err));
2820
+ }
2821
+ for (const message of done.warnings) console.error(formatWarning({ message }));
2822
+ const marked = done.marks.filter((m) => m.marked).map((m) => `#${m.pr}`);
2823
+ console.error(formatInfo(`pr-post --stale: ${marked.length > 0 ? `marked ${marked.join(", ")} stale` : "no note to mark"} after ${branch} moved to ${args.tip.slice(0, 12)}`));
2824
+ return 0;
2825
+ }
2826
+
2608
2827
  /**
2609
2828
  * `pr-post --open` (#4328): in a pipeline of the target branch on GitLab,
2610
2829
  * post the plan note and status of every open merge request into it whose
@@ -2632,6 +2851,8 @@ async function runComponentsPrPostOpen(ctx: CommandContext): Promise<number> {
2632
2851
  const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf-8" });
2633
2852
  if (top.status !== 0) return fail("pr-post --open reads the plan report's path from the repository root, and this directory is not in a git repository");
2634
2853
  const member = args.members?.[0];
2854
+ const description = await descriptionCheckOf(ctx, forge);
2855
+ if (typeof description === "number") return description;
2635
2856
  const artifactDir = relative(realpathSync(top.stdout.trim()), resolve(args.output ?? PR_REPORT_DIR)).split(sep).join("/");
2636
2857
  const { postOpenPlanReports } = await import("../../pr-post");
2637
2858
  const { gitlabPlanJobName } = await import("../../components/pr-pipeline");
@@ -2646,6 +2867,9 @@ async function runComponentsPrPostOpen(ctx: CommandContext): Promise<number> {
2646
2867
  ...(member ? { member } : {}),
2647
2868
  // #4289: the Ops at the commit this pipeline checked out, the target branch's.
2648
2869
  overdue: () => overdueOps(forge, member),
2870
+ ...(description ? { description } : {}),
2871
+ // #4628: the target branch's commit this pipeline runs at, which each note's tip line names.
2872
+ ...(args.tip ? { baseTip: args.tip } : {}),
2649
2873
  });
2650
2874
  } catch (err) {
2651
2875
  return fail(err instanceof Error ? err.message : String(err));
@@ -56,6 +56,7 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
56
56
  return 1;
57
57
  }
58
58
  }
59
+ if (specFile && args.approvalStatus) return runApprovalStatus(ctx, specFile);
59
60
  if (specFile && args.wavesOutcome) {
60
61
  // #4617: the outcome the control job's dispatch carries, from every wave job's outcome file.
61
62
  try {
@@ -118,11 +119,88 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
118
119
  if (args.json) console.log(JSON.stringify(result, null, 2));
119
120
  // #3761: tell people, when the spec says where. Delivery never changes the exit code.
120
121
  await notifyOpWave(spec, args.wave, { result }, job);
122
+ // #4629: a refused wave's diff and a failed apply's triage, on the pull request or a tracking issue.
123
+ await respondWave(spec, args.wave, { result });
121
124
  return result.exitCode;
122
125
  } catch (err) {
123
126
  const message = err instanceof Error ? err.message : String(err);
124
127
  console.error(formatError({ message }));
125
- if (spec) await notifyOpWave(spec, args.wave, { error: message }, job);
128
+ if (spec) {
129
+ await notifyOpWave(spec, args.wave, { error: message }, job);
130
+ await respondWave(spec, args.wave, { error: message });
131
+ }
132
+ return 1;
133
+ }
134
+ }
135
+
136
+ /**
137
+ * The wave job's responses (#4629), through the forge the job's variables
138
+ * name. A job with no forge token posts nothing. Never throws.
139
+ */
140
+ async function respondWave(spec: OpWavesSpec, k: number, outcome: import("../../op/op-waves-notify").OpWaveOutcome): Promise<void> {
141
+ try {
142
+ const { respondOpWave, triageOfOpWave } = await import("../../ci-respond-run");
143
+ const { resolveResponses } = await import("../../ci-respond");
144
+ const responses = resolveResponses(spec.respond);
145
+ if (responses["wave-refused"] === "off" && responses["apply-failed"] === "off") return;
146
+ if (outcome.result && outcome.result.exitCode === 0 && !triageOfOpWave(spec, k, outcome)) return;
147
+ const { detectForge, forgeFromEnv } = await import("../../pr-forge");
148
+ const kind = detectForge();
149
+ if (!kind) return;
150
+ let forge;
151
+ try {
152
+ forge = forgeFromEnv(kind);
153
+ } catch {
154
+ return;
155
+ }
156
+ const head = process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA;
157
+ await respondOpWave(spec, k, outcome, { forge, ...(head ? { head } : {}) });
158
+ } catch (err) {
159
+ console.error(formatWarning({ message: `the wave's responses were not posted: ${err instanceof Error ? err.message : String(err)}` }));
160
+ }
161
+ }
162
+
163
+ /**
164
+ * `chant run wave --spec <file> --approval-status` (#4630): post
165
+ * `<product>/approval` on an open pull request's head, from its recorded
166
+ * plans and its reviews, or for a `pull-request` wave the pull request's
167
+ * own approval on the ledger. `--pr`, `--head` and `--base` name one pull
168
+ * request (GitHub and Forgejo); `--open` posts on every open one into
169
+ * `--branch` (GitLab's scheduled pipeline, or any forge by hand). It exits 0 once it posted, and
170
+ * 1 when it could not.
171
+ */
172
+ async function runApprovalStatus(ctx: CommandContext, specFile: string): Promise<number> {
173
+ const { args } = ctx;
174
+ const fail = (message: string): number => {
175
+ console.error(formatError({ message }));
126
176
  return 1;
177
+ };
178
+ const { FORGE_KINDS, forgeFromEnv } = await import("../../pr-forge");
179
+ if (!args.forge || !(FORGE_KINDS as readonly string[]).includes(args.forge)) return fail(`--approval-status posts on a forge: --forge ${FORGE_KINDS.join("|")}`);
180
+ let spec: OpWavesSpec;
181
+ let forge;
182
+ try {
183
+ spec = parseOpWavesSpec(readFileSync(resolve(specFile), "utf-8"), `--spec ${specFile}`);
184
+ forge = forgeFromEnv(args.forge as (typeof FORGE_KINDS)[number]);
185
+ } catch (err) {
186
+ return fail(err instanceof Error ? err.message : String(err));
187
+ }
188
+ const { postApprovalStatus, postOpenApprovalStatuses } = await import("../../op/approval-status");
189
+ const file = relative(process.cwd(), resolve(specFile));
190
+ try {
191
+ if (args.open) {
192
+ const branch = args.branch ?? process.env.CI_COMMIT_BRANCH;
193
+ if (!branch) return fail("--approval-status --open posts for the pull requests into a branch: run it in a branch pipeline, or pass --branch <branch>");
194
+ const done = await postOpenApprovalStatuses({ spec, specFile: file, forge, branch });
195
+ for (const w of done.warnings) console.error(formatWarning({ message: w }));
196
+ for (const p of done.posted) console.error(`!${p.pr}: ${p.status.state}: ${p.status.description}`);
197
+ return done.warnings.length > 0 && done.posted.length === 0 ? 1 : 0;
198
+ }
199
+ if (args.pr === undefined || !args.head || !args.base) return fail("--approval-status needs the pull request, its head and its base: --pr <n> --head <sha> --base <sha>, or --open");
200
+ const status = await postApprovalStatus({ spec, specFile: file, forge, pr: args.pr, head: args.head, base: args.base });
201
+ console.error(`#${args.pr}: ${status.state}: ${status.description}`);
202
+ return 0;
203
+ } catch (err) {
204
+ return fail(`the approval status was not posted: ${err instanceof Error ? err.message : String(err)}`);
127
205
  }
128
206
  }
@@ -1078,7 +1078,7 @@ describe("chant --help", () => {
1078
1078
  test("lists every top-level command in the registry", () => {
1079
1079
  const source = readFileSync(join(import.meta.dirname, "main.ts"), "utf-8");
1080
1080
  const help = source.slice(source.indexOf("function printHelp("), source.indexOf("Options:", source.indexOf("function printHelp(")));
1081
- const listed = new Set([...help.matchAll(/^ {2}([a-z][a-z-]*)\b/gm)].map((m) => m[1]));
1081
+ const listed = new Set([...help.matchAll(/^ {2}([a-z][a-z0-9-]*)\b/gm)].map((m) => m[1]));
1082
1082
  const commands = new Set(commandRegistry.map((def) => def.name.split(" ")[0]));
1083
1083
  expect([...commands].filter((name) => !listed.has(name))).toEqual([]);
1084
1084
  });