@intentius/chant 0.124.88 → 0.124.90

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (377) hide show
  1. package/dist/actor.d.ts +36 -1
  2. package/dist/actor.d.ts.map +1 -1
  3. package/dist/actor.js +39 -1
  4. package/dist/chant-install.d.ts.map +1 -1
  5. package/dist/chant-install.js +1 -2
  6. package/dist/ci-base.d.ts +30 -0
  7. package/dist/ci-base.d.ts.map +1 -0
  8. package/dist/ci-base.js +33 -0
  9. package/dist/ci-comment-commands.d.ts +193 -0
  10. package/dist/ci-comment-commands.d.ts.map +1 -0
  11. package/dist/ci-comment-commands.js +353 -0
  12. package/dist/ci-comment-replies.d.ts +40 -0
  13. package/dist/ci-comment-replies.d.ts.map +1 -0
  14. package/dist/ci-comment-replies.js +59 -0
  15. package/dist/ci-evidence-from-job.d.ts +25 -0
  16. package/dist/ci-evidence-from-job.d.ts.map +1 -1
  17. package/dist/ci-evidence-from-job.js +43 -2
  18. package/dist/ci-evidence-jobs.d.ts +30 -1
  19. package/dist/ci-evidence-jobs.d.ts.map +1 -1
  20. package/dist/ci-evidence-jobs.js +46 -3
  21. package/dist/ci-image.d.ts +21 -4
  22. package/dist/ci-image.d.ts.map +1 -1
  23. package/dist/ci-image.js +62 -10
  24. package/dist/ci-job-guard.d.ts +42 -45
  25. package/dist/ci-job-guard.d.ts.map +1 -1
  26. package/dist/ci-job-guard.js +206 -3
  27. package/dist/ci-note-commands.d.ts +104 -4
  28. package/dist/ci-note-commands.d.ts.map +1 -1
  29. package/dist/ci-note-commands.js +131 -38
  30. package/dist/ci-product-words.d.ts +42 -0
  31. package/dist/ci-product-words.d.ts.map +1 -1
  32. package/dist/ci-product-words.js +25 -0
  33. package/dist/ci-product.d.ts +72 -1
  34. package/dist/ci-product.d.ts.map +1 -1
  35. package/dist/ci-product.js +73 -6
  36. package/dist/cli/commands/build.d.ts.map +1 -1
  37. package/dist/cli/commands/build.js +29 -2
  38. package/dist/cli/handlers/approve.d.ts.map +1 -1
  39. package/dist/cli/handlers/approve.js +2 -1
  40. package/dist/cli/handlers/ci-check.d.ts +1 -1
  41. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  42. package/dist/cli/handlers/ci-check.js +17 -7
  43. package/dist/cli/handlers/ci-evidence.d.ts.map +1 -1
  44. package/dist/cli/handlers/ci-evidence.js +33 -7
  45. package/dist/cli/handlers/components.d.ts.map +1 -1
  46. package/dist/cli/handlers/components.js +3 -1
  47. package/dist/cli/handlers/generated-check.d.ts +8 -0
  48. package/dist/cli/handlers/generated-check.d.ts.map +1 -1
  49. package/dist/cli/handlers/generated-check.js +31 -1
  50. package/dist/cli/handlers/lock.d.ts.map +1 -1
  51. package/dist/cli/handlers/lock.js +121 -4
  52. package/dist/cli/handlers/pr-comment.d.ts +33 -0
  53. package/dist/cli/handlers/pr-comment.d.ts.map +1 -0
  54. package/dist/cli/handlers/pr-comment.js +201 -0
  55. package/dist/cli/handlers/pr-env.d.ts.map +1 -1
  56. package/dist/cli/handlers/pr-env.js +6 -3
  57. package/dist/cli/handlers/pr-notes.d.ts.map +1 -1
  58. package/dist/cli/handlers/pr-notes.js +23 -1
  59. package/dist/cli/handlers/pr.d.ts +23 -1
  60. package/dist/cli/handlers/pr.d.ts.map +1 -1
  61. package/dist/cli/handlers/pr.js +71 -23
  62. package/dist/cli/handlers/promote.d.ts.map +1 -1
  63. package/dist/cli/handlers/promote.js +2 -1
  64. package/dist/cli/handlers/release.d.ts.map +1 -1
  65. package/dist/cli/handlers/release.js +11 -2
  66. package/dist/cli/handlers/run-wave.d.ts.map +1 -1
  67. package/dist/cli/handlers/run-wave.js +180 -4
  68. package/dist/cli/handlers/run.d.ts.map +1 -1
  69. package/dist/cli/handlers/run.js +2 -1
  70. package/dist/cli/main.d.ts.map +1 -1
  71. package/dist/cli/main.js +41 -2
  72. package/dist/cli/parse-args.d.ts.map +1 -1
  73. package/dist/cli/parse-args.js +31 -0
  74. package/dist/cli/registry.d.ts +19 -1
  75. package/dist/cli/registry.d.ts.map +1 -1
  76. package/dist/components/auto-release.d.ts.map +1 -1
  77. package/dist/components/auto-release.js +2 -1
  78. package/dist/components/pr-checks.d.ts +97 -6
  79. package/dist/components/pr-checks.d.ts.map +1 -1
  80. package/dist/components/pr-checks.js +107 -13
  81. package/dist/components/pr-pipeline.d.ts +19 -14
  82. package/dist/components/pr-pipeline.d.ts.map +1 -1
  83. package/dist/components/pr-pipeline.js +7 -13
  84. package/dist/components/product-pipeline.d.ts +96 -3
  85. package/dist/components/product-pipeline.d.ts.map +1 -1
  86. package/dist/components/product-pipeline.js +120 -14
  87. package/dist/components/product-plan.d.ts +203 -6
  88. package/dist/components/product-plan.d.ts.map +1 -1
  89. package/dist/components/product-plan.js +250 -43
  90. package/dist/drift-record.d.ts +7 -0
  91. package/dist/drift-record.d.ts.map +1 -1
  92. package/dist/drift-record.js +19 -0
  93. package/dist/floor-table.data.d.ts.map +1 -1
  94. package/dist/floor-table.data.js +63 -31
  95. package/dist/forge-check/contract.d.ts +11 -1
  96. package/dist/forge-check/contract.d.ts.map +1 -1
  97. package/dist/forge-check/contract.js +4 -1
  98. package/dist/forge-check/index.d.ts +2 -0
  99. package/dist/forge-check/index.d.ts.map +1 -1
  100. package/dist/forge-check/index.js +2 -0
  101. package/dist/gate-resume-run.d.ts +9 -1
  102. package/dist/gate-resume-run.d.ts.map +1 -1
  103. package/dist/gate-resume-run.js +26 -3
  104. package/dist/generated-check.d.ts +18 -4
  105. package/dist/generated-check.d.ts.map +1 -1
  106. package/dist/generated-check.js +37 -5
  107. package/dist/image-pins.d.ts +26 -0
  108. package/dist/image-pins.d.ts.map +1 -0
  109. package/dist/image-pins.js +19 -0
  110. package/dist/lexicon.d.ts +93 -4
  111. package/dist/lexicon.d.ts.map +1 -1
  112. package/dist/lifecycle/gate-applied.d.ts +9 -0
  113. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  114. package/dist/lifecycle/git.d.ts +11 -0
  115. package/dist/lifecycle/git.d.ts.map +1 -1
  116. package/dist/lifecycle/git.js +30 -3
  117. package/dist/lifecycle/publish-npm.d.ts +11 -0
  118. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  119. package/dist/lifecycle/publish-npm.js +27 -1
  120. package/dist/lifecycle/reach-locks.d.ts +131 -0
  121. package/dist/lifecycle/reach-locks.d.ts.map +1 -0
  122. package/dist/lifecycle/reach-locks.js +118 -0
  123. package/dist/lifecycle/release-cut.d.ts +3 -1
  124. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  125. package/dist/lifecycle/release-cut.js +15 -0
  126. package/dist/lifecycle/release-images.d.ts.map +1 -1
  127. package/dist/lifecycle/release-images.js +1 -2
  128. package/dist/notify-product.d.ts +12 -3
  129. package/dist/notify-product.d.ts.map +1 -1
  130. package/dist/notify-product.js +10 -6
  131. package/dist/op/activities/source-release.d.ts.map +1 -1
  132. package/dist/op/activities/source-release.js +2 -1
  133. package/dist/op/activities/source-rollback.d.ts.map +1 -1
  134. package/dist/op/activities/source-rollback.js +2 -1
  135. package/dist/op/apply-status.d.ts +84 -0
  136. package/dist/op/apply-status.d.ts.map +1 -0
  137. package/dist/op/apply-status.js +106 -0
  138. package/dist/op/before-merge-decide.d.ts +102 -0
  139. package/dist/op/before-merge-decide.d.ts.map +1 -0
  140. package/dist/op/before-merge-decide.js +142 -0
  141. package/dist/op/before-merge-done.d.ts +56 -0
  142. package/dist/op/before-merge-done.d.ts.map +1 -0
  143. package/dist/op/before-merge-done.js +69 -0
  144. package/dist/op/before-merge-store.d.ts +20 -0
  145. package/dist/op/before-merge-store.d.ts.map +1 -0
  146. package/dist/op/before-merge-store.js +48 -0
  147. package/dist/op/before-merge.d.ts +150 -0
  148. package/dist/op/before-merge.d.ts.map +1 -0
  149. package/dist/op/before-merge.js +207 -0
  150. package/dist/op/follow-on-run.d.ts +117 -0
  151. package/dist/op/follow-on-run.d.ts.map +1 -0
  152. package/dist/op/follow-on-run.js +154 -0
  153. package/dist/op/follow-on-store.d.ts +17 -0
  154. package/dist/op/follow-on-store.d.ts.map +1 -0
  155. package/dist/op/follow-on-store.js +54 -0
  156. package/dist/op/gate.d.ts +6 -0
  157. package/dist/op/gate.d.ts.map +1 -1
  158. package/dist/op/gate.js +10 -1
  159. package/dist/op/index.d.ts +5 -1
  160. package/dist/op/index.d.ts.map +1 -1
  161. package/dist/op/index.js +2 -0
  162. package/dist/op/op-waves-after-plan.d.ts +13 -0
  163. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  164. package/dist/op/op-waves-evidence-jobs.d.ts +10 -2
  165. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  166. package/dist/op/op-waves-evidence-jobs.js +19 -5
  167. package/dist/op/op-waves-follow-on.d.ts +162 -0
  168. package/dist/op/op-waves-follow-on.d.ts.map +1 -0
  169. package/dist/op/op-waves-follow-on.js +355 -0
  170. package/dist/op/op-waves-render-spec.d.ts +100 -0
  171. package/dist/op/op-waves-render-spec.d.ts.map +1 -0
  172. package/dist/op/op-waves-render-spec.js +162 -0
  173. package/dist/op/op-waves-run.d.ts +148 -6
  174. package/dist/op/op-waves-run.d.ts.map +1 -1
  175. package/dist/op/op-waves-run.js +873 -100
  176. package/dist/op/op-waves-split.d.ts +122 -0
  177. package/dist/op/op-waves-split.d.ts.map +1 -0
  178. package/dist/op/op-waves-split.js +166 -0
  179. package/dist/op/op-waves.d.ts +24 -0
  180. package/dist/op/op-waves.d.ts.map +1 -1
  181. package/dist/op/op-waves.js +18 -1
  182. package/dist/op/schedule-overdue.d.ts +15 -1
  183. package/dist/op/schedule-overdue.d.ts.map +1 -1
  184. package/dist/op/schedule-overdue.js +77 -5
  185. package/dist/op/stage-hooks.d.ts +36 -1
  186. package/dist/op/stage-hooks.d.ts.map +1 -1
  187. package/dist/op/stage-hooks.js +17 -3
  188. package/dist/op/wave-stop.d.ts +67 -0
  189. package/dist/op/wave-stop.d.ts.map +1 -0
  190. package/dist/op/wave-stop.js +129 -0
  191. package/dist/planned-files.d.ts +76 -0
  192. package/dist/planned-files.d.ts.map +1 -0
  193. package/dist/planned-files.js +108 -0
  194. package/dist/pr-forge-job.d.ts +22 -0
  195. package/dist/pr-forge-job.d.ts.map +1 -0
  196. package/dist/pr-forge-job.js +46 -0
  197. package/dist/pr-loop.d.ts +3 -6
  198. package/dist/pr-loop.d.ts.map +1 -1
  199. package/dist/pr-loop.js +4 -81
  200. package/dist/pr-plan-note.d.ts +97 -0
  201. package/dist/pr-plan-note.d.ts.map +1 -1
  202. package/dist/pr-plan-note.js +94 -1
  203. package/dist/pr-post.d.ts +28 -3
  204. package/dist/pr-post.d.ts.map +1 -1
  205. package/dist/pr-post.js +146 -13
  206. package/dist/pr-status.d.ts +16 -0
  207. package/dist/pr-status.d.ts.map +1 -0
  208. package/dist/pr-status.js +90 -0
  209. package/dist/ref-gate-init.d.ts +16 -2
  210. package/dist/ref-gate-init.d.ts.map +1 -1
  211. package/dist/ref-gate-init.js +24 -13
  212. package/dist/release-floors.d.ts +39 -1
  213. package/dist/release-floors.d.ts.map +1 -1
  214. package/dist/release-floors.js +63 -25
  215. package/dist/render-module.d.ts +15 -0
  216. package/dist/render-module.d.ts.map +1 -0
  217. package/dist/render-module.js +73 -0
  218. package/dist/state-migration.d.ts.map +1 -1
  219. package/dist/state-migration.js +1 -2
  220. package/dist/wave-blocked.d.ts +7 -1
  221. package/dist/wave-blocked.d.ts.map +1 -1
  222. package/dist/wave-blocked.js +7 -2
  223. package/dist/wave-runtime.mjs +366 -350
  224. package/dist/workspace/ci-green-cli.d.ts.map +1 -1
  225. package/dist/workspace/ci-green-cli.js +3 -2
  226. package/dist/workspace/release-train.d.ts.map +1 -1
  227. package/dist/workspace/release-train.js +2 -1
  228. package/dist/workspace/release-workflow.d.ts +4 -3
  229. package/dist/workspace/release-workflow.d.ts.map +1 -1
  230. package/dist/workspace/release-workflow.js +10 -7
  231. package/dist/workspace/trust/check-evidence-report.d.ts +7 -2
  232. package/dist/workspace/trust/check-evidence-report.d.ts.map +1 -1
  233. package/dist/workspace/trust/check-evidence-report.js +15 -8
  234. package/dist/workspace/trust/ref-gate-cli.d.ts +10 -1
  235. package/dist/workspace/trust/ref-gate-cli.d.ts.map +1 -1
  236. package/dist/workspace/trust/ref-gate-cli.js +30 -10
  237. package/dist/workspace/workspace-run.d.ts.map +1 -1
  238. package/dist/workspace/workspace-run.js +2 -1
  239. package/package.json +1 -1
  240. package/src/actor.test.ts +68 -2
  241. package/src/actor.ts +61 -1
  242. package/src/chant-install.test.ts +2 -3
  243. package/src/chant-install.ts +1 -2
  244. package/src/ci-base.test.ts +41 -0
  245. package/src/ci-base.ts +43 -0
  246. package/src/ci-comment-commands.test.ts +439 -0
  247. package/src/ci-comment-commands.ts +428 -0
  248. package/src/ci-comment-replies.ts +78 -0
  249. package/src/ci-commit.test.ts +2 -3
  250. package/src/ci-evidence-from-job.test.ts +18 -0
  251. package/src/ci-evidence-from-job.ts +58 -2
  252. package/src/ci-evidence-jobs.ts +50 -5
  253. package/src/ci-image.test.ts +130 -10
  254. package/src/ci-image.ts +85 -12
  255. package/src/ci-job-guard.before-merge.test.ts +148 -0
  256. package/src/ci-job-guard.follow-on-record.test.ts +137 -0
  257. package/src/ci-job-guard.follow-on.test.ts +144 -0
  258. package/src/ci-job-guard.ts +221 -3
  259. package/src/ci-note-commands.test.ts +76 -1
  260. package/src/ci-note-commands.ts +198 -46
  261. package/src/ci-product-words.ts +59 -0
  262. package/src/ci-product.ts +90 -6
  263. package/src/cli/commands/build.test.ts +41 -0
  264. package/src/cli/commands/build.ts +27 -2
  265. package/src/cli/handlers/approve.ts +2 -1
  266. package/src/cli/handlers/ci-check.ts +19 -7
  267. package/src/cli/handlers/ci-evidence.ts +29 -8
  268. package/src/cli/handlers/components.ts +3 -1
  269. package/src/cli/handlers/generated-check.ts +31 -1
  270. package/src/cli/handlers/lock-reach.test.ts +103 -0
  271. package/src/cli/handlers/lock.ts +100 -4
  272. package/src/cli/handlers/pr-comment.ts +187 -0
  273. package/src/cli/handlers/pr-env.ts +6 -3
  274. package/src/cli/handlers/pr-notes.ts +30 -6
  275. package/src/cli/handlers/pr-record.test.ts +1 -1
  276. package/src/cli/handlers/pr.ts +64 -21
  277. package/src/cli/handlers/promote.ts +2 -1
  278. package/src/cli/handlers/release.e2e.test.ts +35 -0
  279. package/src/cli/handlers/release.ts +14 -2
  280. package/src/cli/handlers/run-wave.ts +170 -4
  281. package/src/cli/handlers/run.ts +2 -1
  282. package/src/cli/main.ts +41 -2
  283. package/src/cli/parse-args.ts +23 -0
  284. package/src/cli/registry.ts +19 -1
  285. package/src/components/auto-release.ts +2 -1
  286. package/src/components/pr-checks.ts +165 -17
  287. package/src/components/pr-pipeline.ts +22 -18
  288. package/src/components/product-pipeline.apply-status.test.ts +50 -0
  289. package/src/components/product-pipeline.ts +204 -17
  290. package/src/components/product-plan.test.ts +60 -4
  291. package/src/components/product-plan.ts +367 -50
  292. package/src/drift-record.test.ts +20 -0
  293. package/src/drift-record.ts +16 -0
  294. package/src/floor-table.data.ts +63 -31
  295. package/src/forge-check/contract.ts +12 -1
  296. package/src/forge-check/forge-check.test.ts +17 -0
  297. package/src/forge-check/index.ts +2 -0
  298. package/src/gate-resume-run.ts +27 -3
  299. package/src/generated-check.e2e.test.ts +21 -1
  300. package/src/generated-check.test.ts +66 -0
  301. package/src/generated-check.ts +51 -10
  302. package/src/image-pins.ts +31 -0
  303. package/src/lexicon.ts +89 -1
  304. package/src/lifecycle/gate-applied.ts +7 -0
  305. package/src/lifecycle/git.test.ts +48 -0
  306. package/src/lifecycle/git.ts +27 -4
  307. package/src/lifecycle/publish-npm.ts +31 -1
  308. package/src/lifecycle/reach-locks.test.ts +87 -0
  309. package/src/lifecycle/reach-locks.ts +169 -0
  310. package/src/lifecycle/release-cut.ts +17 -1
  311. package/src/lifecycle/release-images.test.ts +56 -0
  312. package/src/lifecycle/release-images.ts +1 -2
  313. package/src/notify-product.ts +19 -8
  314. package/src/op/activities/source-release.ts +2 -1
  315. package/src/op/activities/source-rollback.ts +2 -1
  316. package/src/op/apply-status.test.ts +83 -0
  317. package/src/op/apply-status.ts +132 -0
  318. package/src/op/before-merge-decide.ts +190 -0
  319. package/src/op/before-merge-done.ts +99 -0
  320. package/src/op/before-merge-store.ts +44 -0
  321. package/src/op/before-merge.test.ts +201 -0
  322. package/src/op/before-merge.ts +266 -0
  323. package/src/op/follow-on-run.ts +206 -0
  324. package/src/op/follow-on-store.ts +54 -0
  325. package/src/op/gate-resume.test.ts +27 -0
  326. package/src/op/gate.ts +16 -1
  327. package/src/op/index.ts +15 -0
  328. package/src/op/op-waves-after-plan.ts +13 -0
  329. package/src/op/op-waves-evidence-jobs.ts +21 -7
  330. package/src/op/op-waves-follow-on-record.test.ts +152 -0
  331. package/src/op/op-waves-follow-on.test.ts +247 -0
  332. package/src/op/op-waves-follow-on.ts +385 -0
  333. package/src/op/op-waves-notify-words.test.ts +18 -0
  334. package/src/op/op-waves-render-spec.test.ts +159 -0
  335. package/src/op/op-waves-render-spec.ts +171 -0
  336. package/src/op/op-waves-run.ts +973 -94
  337. package/src/op/op-waves-split-product.test.ts +288 -0
  338. package/src/op/op-waves-split-step.test.ts +298 -0
  339. package/src/op/op-waves-split.test.ts +196 -0
  340. package/src/op/op-waves-split.ts +189 -0
  341. package/src/op/op-waves.ts +31 -3
  342. package/src/op/schedule-overdue.test.ts +72 -1
  343. package/src/op/schedule-overdue.ts +84 -6
  344. package/src/op/stage-hooks.ts +52 -4
  345. package/src/op/wave-stop.test.ts +72 -0
  346. package/src/op/wave-stop.ts +139 -0
  347. package/src/planned-files.test.ts +80 -0
  348. package/src/planned-files.ts +134 -0
  349. package/src/pr-forge-job.test.ts +53 -0
  350. package/src/pr-forge-job.ts +46 -0
  351. package/src/pr-loop-narrowed.test.ts +2 -1
  352. package/src/pr-loop-words.test.ts +2 -1
  353. package/src/pr-loop.test.ts +1 -2
  354. package/src/pr-loop.ts +4 -80
  355. package/src/pr-plan-note.ts +155 -3
  356. package/src/pr-post-replan.test.ts +144 -0
  357. package/src/pr-post-subject.test.ts +230 -0
  358. package/src/pr-post.test.ts +2 -1
  359. package/src/pr-post.ts +151 -15
  360. package/src/pr-status.ts +91 -0
  361. package/src/ref-gate-init.ts +30 -11
  362. package/src/release-floors.ts +81 -25
  363. package/src/render-module.ts +73 -0
  364. package/src/state-migration-record.test.ts +2 -3
  365. package/src/state-migration.ts +1 -2
  366. package/src/wave-blocked.ts +9 -4
  367. package/src/workspace/ci-green-cli.ts +3 -2
  368. package/src/workspace/ci-green-workflow.test.ts +32 -1
  369. package/src/workspace/release-train.ts +2 -1
  370. package/src/workspace/release-workflow.test.ts +36 -5
  371. package/src/workspace/release-workflow.ts +10 -7
  372. package/src/workspace/trust/check-evidence-report.ts +15 -8
  373. package/src/workspace/trust/check-evidence.test.ts +5 -0
  374. package/src/workspace/trust/ref-gate-cli.ts +30 -8
  375. package/src/workspace/trust/ref-gate-pieces.test.ts +46 -1
  376. package/src/workspace/trust/ref-gate.test.ts +10 -0
  377. package/src/workspace/workspace-run.ts +2 -1
@@ -0,0 +1,134 @@
1
+ /**
2
+ * `@intentius/chant/planned-files` (#4966): the files a product's init or
3
+ * render plans, written in one call, and the generated files it no longer
4
+ * renders.
5
+ *
6
+ * Each product carried its own: terragucci's `init.ts` plans a
7
+ * `FileChange` per file and writes or unlinks them in a loop, with a
8
+ * `chmodSync` beside its image recipe's writes; plywood's `init.ts` `put`
9
+ * writes a file when it differs; sql-yodeler's `yodel ci` finds the
10
+ * pipeline files that open with its header and removes the ones it no
11
+ * longer renders (its #348).
12
+ *
13
+ * - {@link planFile} plans one file against what is on disk, its mode
14
+ * included, and writes nothing, so a dry run prints the plan as it is.
15
+ * - {@link planRemoval} plans the removal of a file an earlier run wrote.
16
+ * - {@link writePlannedFiles} writes the plan: each directory made, each
17
+ * file's mode set, each removed file unlinked, an unchanged one left as
18
+ * it is.
19
+ * - {@link staleGeneratedFiles} lists the files under some directories that
20
+ * open with a product's header and that the product no longer renders.
21
+ *
22
+ * `@intentius/chant/ref-gate-init` writes its plan with
23
+ * {@link writePlannedFiles}.
24
+ *
25
+ * This module imports only Node's own modules.
26
+ */
27
+
28
+ import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
29
+ import { dirname, join } from "node:path";
30
+
31
+ /** One planned file. */
32
+ export interface PlannedFile {
33
+ /** Where it is written. Absolute, or relative to the process's directory. */
34
+ path: string;
35
+ /** `removed`: a file an earlier run wrote that this one no longer asks for. */
36
+ status: "created" | "updated" | "unchanged" | "removed";
37
+ /** The text to write; empty for a removal. */
38
+ content: string;
39
+ /** The permission bits to set, such as `0o755` for a script. Unset, a new file gets the process's default and an existing one keeps its own. */
40
+ mode?: number;
41
+ /** In the git directory or otherwise never committed, such as a hook. */
42
+ local?: boolean;
43
+ }
44
+
45
+ /** The permission bits of the file at `path`, or undefined when there is none. */
46
+ function modeOf(path: string): number | undefined {
47
+ try {
48
+ return statSync(path).mode & 0o777;
49
+ } catch {
50
+ return undefined;
51
+ }
52
+ }
53
+
54
+ /**
55
+ * Plan `content` at `path`: `created` when there is no file, `unchanged`
56
+ * when the file holds the content (and, with `mode`, has that mode),
57
+ * `updated` otherwise. Writes nothing.
58
+ */
59
+ export function planFile(path: string, content: string, extra: Pick<PlannedFile, "mode" | "local"> = {}): PlannedFile {
60
+ const own = { ...(extra.mode !== undefined ? { mode: extra.mode } : {}), ...(extra.local ? { local: true } : {}) };
61
+ if (!existsSync(path)) return { path, status: "created", content, ...own };
62
+ const same = readFileSync(path, "utf-8") === content && (extra.mode === undefined || modeOf(path) === extra.mode);
63
+ return { path, status: same ? "unchanged" : "updated", content, ...own };
64
+ }
65
+
66
+ /** Plan the removal of the file at `path`; undefined when there is nothing there to remove. */
67
+ export function planRemoval(path: string): PlannedFile | undefined {
68
+ return existsSync(path) ? { path, status: "removed", content: "" } : undefined;
69
+ }
70
+
71
+ /**
72
+ * Write a plan: each created or updated file written, its directory made
73
+ * and its mode set; each removed file unlinked; an unchanged file not
74
+ * touched. A removed file that is already gone is not an error.
75
+ */
76
+ export function writePlannedFiles(files: readonly Pick<PlannedFile, "path" | "status" | "content" | "mode">[]): void {
77
+ for (const f of files) {
78
+ if (f.status === "unchanged") continue;
79
+ if (f.status === "removed") {
80
+ if (existsSync(f.path)) unlinkSync(f.path);
81
+ continue;
82
+ }
83
+ mkdirSync(dirname(f.path), { recursive: true });
84
+ writeFileSync(f.path, f.content);
85
+ if (f.mode !== undefined) chmodSync(f.path, f.mode);
86
+ }
87
+ }
88
+
89
+ export interface StaleGeneratedOptions {
90
+ /** The directory the paths are relative to: a product's checkout. */
91
+ root: string;
92
+ /** Directories, relative to `root`, whose files (not their subdirectories) may be generated. */
93
+ dirs?: readonly string[];
94
+ /** Single files, relative to `root`, that may be generated, such as `.gitlab-ci.yml`. */
95
+ files?: readonly string[];
96
+ /** The names in `dirs` to look at. Default every file. */
97
+ match?: RegExp;
98
+ /** The product's header: its first line, which a generated file opens with, or a test of the file's text. */
99
+ header: string | ((text: string) => boolean);
100
+ /** The paths, relative to `root` and written with `/`, the product renders now. */
101
+ rendered: Iterable<string>;
102
+ }
103
+
104
+ /**
105
+ * The files under `dirs` and among `files` that open with the product's
106
+ * header and that it does not render now, relative to `root`, in the order
107
+ * found (each directory's names sorted). A file without the header is the
108
+ * person's own and never listed.
109
+ */
110
+ export function staleGeneratedFiles(options: StaleGeneratedOptions): string[] {
111
+ const { root } = options;
112
+ const header = options.header;
113
+ const isGenerated = typeof header === "string" ? (text: string) => text.split(/\r?\n/, 1)[0] === header : header;
114
+ const candidates = [...(options.files ?? [])];
115
+ for (const d of options.dirs ?? []) {
116
+ const abs = join(root, d);
117
+ if (!existsSync(abs)) continue;
118
+ const prefix = d.replace(/\/+$/, "");
119
+ for (const e of readdirSync(abs, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
120
+ if (e.isFile() && (!options.match || options.match.test(e.name))) candidates.push(prefix === "" || prefix === "." ? e.name : `${prefix}/${e.name}`);
121
+ }
122
+ }
123
+ const rendered = new Set(options.rendered);
124
+ const out: string[] = [];
125
+ for (const p of candidates) {
126
+ if (rendered.has(p) || out.includes(p)) continue;
127
+ const abs = join(root, p);
128
+ if (!existsSync(abs) || !statSync(abs).isFile()) continue;
129
+ if (isGenerated(readFileSync(abs, "utf-8"))) out.push(p);
130
+ }
131
+ return out;
132
+ }
133
+
134
+ export { PLANNED_FILES_FLOOR } from "./release-floors";
@@ -0,0 +1,53 @@
1
+ /**
2
+ * #4964: a GitHub pull_request run plans, checks and signs its merge
3
+ * preview (`GITHUB_SHA`), and the forge shows no status of that commit on
4
+ * the pull request, so the plan note's, the check evidence's and the ref
5
+ * gate's statuses for it go on the pull request's head.
6
+ */
7
+ import { mkdtempSync, writeFileSync } from "node:fs";
8
+ import { tmpdir } from "node:os";
9
+ import { join } from "node:path";
10
+ import { describe, expect, test } from "vitest";
11
+ import type { ForgeFetch } from "./pr-forge";
12
+ import { forgeFromJobEnv } from "./pr-forge-job";
13
+
14
+ const HEAD = "a".repeat(40);
15
+ const MERGE = "b".repeat(40);
16
+ const OTHER = "c".repeat(40);
17
+
18
+ function recorder(): { fetch: ForgeFetch; posted: string[] } {
19
+ const posted: string[] = [];
20
+ const fetch: ForgeFetch = async (url) => {
21
+ posted.push(url.replace(/^.*\/statuses\//, ""));
22
+ return { ok: true, status: 201, text: async () => "{}" };
23
+ };
24
+ return { fetch, posted };
25
+ }
26
+
27
+ function eventFile(body: unknown): string {
28
+ const path = join(mkdtempSync(join(tmpdir(), "chant-4964-")), "event.json");
29
+ writeFileSync(path, JSON.stringify(body));
30
+ return path;
31
+ }
32
+
33
+ const status = { context: "chant/plan", state: "success" as const, description: "d" };
34
+
35
+ describe("statuses of a pull_request run on the pull request's head (#4964)", () => {
36
+ const env = { GITHUB_REPOSITORY: "acme/infra", GITHUB_TOKEN: "t", GITHUB_EVENT_NAME: "pull_request", GITHUB_SHA: MERGE, GITHUB_EVENT_PATH: eventFile({ number: 7, pull_request: { number: 7, head: { sha: HEAD } } }) };
37
+
38
+ test("a status for the merge preview goes on the head; one for another commit where it was asked", async () => {
39
+ const { fetch, posted } = recorder();
40
+ const forge = forgeFromJobEnv("github", env, fetch);
41
+ await forge.setStatus(MERGE, status);
42
+ await forge.setStatus(OTHER, status);
43
+ expect(posted).toEqual([HEAD, OTHER]);
44
+ });
45
+
46
+ test("a run of another event, or one whose payload names no head, posts where it was asked", async () => {
47
+ const { fetch, posted } = recorder();
48
+ await forgeFromJobEnv("github", { ...env, GITHUB_EVENT_NAME: "push" }, fetch).setStatus(MERGE, status);
49
+ await forgeFromJobEnv("github", { ...env, GITHUB_EVENT_PATH: eventFile({ ref: "refs/heads/main" }) }, fetch).setStatus(MERGE, status);
50
+ await forgeFromJobEnv("github", { ...env, GITHUB_EVENT_PATH: join(tmpdir(), "chant-4964-missing.json") }, fetch).setStatus(MERGE, status);
51
+ expect(posted).toEqual([MERGE, MERGE, MERGE]);
52
+ });
53
+ });
@@ -0,0 +1,46 @@
1
+ /**
2
+ * The forge client a chant command in a CI job posts with (#4964): the
3
+ * pull request loop's {@link forgeFromEnv}, with each commit status for the
4
+ * run's own commit put on the pull request's head.
5
+ *
6
+ * A GitHub `pull_request` run checks out `GITHUB_SHA`, the merge preview
7
+ * (`refs/pull/<n>/merge`), and the loop's jobs plan, check and sign that
8
+ * commit, as a merge would make it. The forge shows no status of that commit
9
+ * on the pull request, and a required status is read from the head, so a
10
+ * status the plan note, the check evidence or the ref gate sets for it goes
11
+ * on `pull_request.head.sha` instead. Forgejo's run is of the head already,
12
+ * and so is a status for any other commit; both are posted as asked. GitLab
13
+ * is left as it is: its merge request pipeline runs on the head.
14
+ *
15
+ * Kept out of ./pr-forge.ts, whose bundle a product posts with.
16
+ */
17
+
18
+ import { readFileSync } from "node:fs";
19
+ import { forgeFromEnv, type ForgeKind, type PrForge } from "./pr-forge";
20
+
21
+ /** The pull request's head from a GitHub-style `pull_request` run's event payload, or undefined for any other run. */
22
+ export function pullRequestEventHead(env: Record<string, string | undefined>): string | undefined {
23
+ if (!env.GITHUB_EVENT_NAME?.startsWith("pull_request") || !env.GITHUB_EVENT_PATH) return undefined;
24
+ try {
25
+ const event = JSON.parse(readFileSync(env.GITHUB_EVENT_PATH, "utf8")) as { pull_request?: { head?: { sha?: unknown } } };
26
+ const sha = event.pull_request?.head?.sha;
27
+ return typeof sha === "string" && /^[0-9a-f]{40,64}$/.test(sha) ? sha : undefined;
28
+ } catch {
29
+ return undefined;
30
+ }
31
+ }
32
+
33
+ /** {@link forgeFromEnv}, whose statuses for the run's merge preview go on the pull request's head (#4964). */
34
+ export function forgeFromJobEnv(kind: ForgeKind, env: Record<string, string | undefined> = process.env, fetchImpl?: Parameters<typeof forgeFromEnv>[2]): PrForge {
35
+ const forge = forgeFromEnv(kind, env, fetchImpl);
36
+ const merge = env.GITHUB_SHA;
37
+ const head = kind === "gitlab" ? undefined : pullRequestEventHead(env);
38
+ if (!head || !merge || head === merge) return forge;
39
+ const at = (sha: string): string => (sha === merge ? head : sha);
40
+ const { setStatus, setCommitStatus } = forge;
41
+ return {
42
+ ...forge,
43
+ setStatus: (sha, status) => setStatus(at(sha), status),
44
+ ...(setCommitStatus ? { setCommitStatus: (sha: string, status: Parameters<typeof setCommitStatus>[1]) => setCommitStatus(at(sha), status) } : {}),
45
+ };
46
+ }
@@ -6,7 +6,8 @@
6
6
  */
7
7
  import { describe, expect, test } from "vitest";
8
8
  import { composeChangeSet } from "./change-set";
9
- import { memberCounts, PR_REPORT_SCHEMA_ID, prStatusDescription, renderPrNote, type PrReport } from "./pr-loop";
9
+ import { memberCounts, PR_REPORT_SCHEMA_ID, renderPrNote, type PrReport } from "./pr-loop";
10
+ import { prStatusDescription } from "./pr-status";
10
11
  import { assertProductWords } from "./ci-product-words";
11
12
  import { PLYWOOD } from "./__fixtures__/product-words";
12
13
 
@@ -5,7 +5,8 @@
5
5
  */
6
6
  import { describe, expect, test } from "vitest";
7
7
  import { composeChangeSet } from "./change-set";
8
- import { memberCounts, PR_REPORT_SCHEMA_ID, prApproveCommand, prApproveCommands, prMergeSentence, prStatusContext, prStatusDescription, renderPrNote, type PrReport } from "./pr-loop";
8
+ import { memberCounts, PR_REPORT_SCHEMA_ID, prApproveCommand, prApproveCommands, prMergeSentence, prStatusContext, renderPrNote, type PrReport } from "./pr-loop";
9
+ import { prStatusDescription } from "./pr-status";
9
10
  import { assertProductWords, CHANT_WORDS } from "./ci-product-words";
10
11
  import { PLYWOOD, TERRAGUCCI, YODEL } from "./__fixtures__/product-words";
11
12
 
@@ -23,11 +23,10 @@ import {
23
23
  PR_GATE_OP,
24
24
  prOp,
25
25
  prStatusContext,
26
- prStatusDescription,
27
- prStatusState,
28
26
  renderPrNote,
29
27
  type PrReport,
30
28
  } from "./pr-loop";
29
+ import { prStatusDescription, prStatusState } from "./pr-status";
31
30
  import { contract, validSchema } from "./workspace/__fixtures__/contract-repo";
32
31
  import schema from "./workspace/pr-report.schema.json";
33
32
  import changeSetSchema from "./workspace/change-set.schema.json";
package/src/pr-loop.ts CHANGED
@@ -6,8 +6,9 @@
6
6
  * `chant components pr-plan` and `chant components pr-apply` run it, and the
7
7
  * generated CI for GitHub, GitLab and Forgejo calls them
8
8
  * (`components/pr-pipeline.ts`). This module holds the parts that need no
9
- * runner: the gate's names, the report both commands write, the pull-request
10
- * note rendered from it and the status line. terragucci reads the report and
9
+ * runner: the gate's names, the report both commands write and the
10
+ * pull-request note rendered from it; the status line is in `./pr-status.ts`
11
+ * (#4966), outside the bundle. terragucci reads the report and
11
12
  * renders the note from one bundled file with no TypeScript toolchain
12
13
  * (#3421), so this imports `./change-set` and `./plan-summary` and nothing
13
14
  * else; `pr-loop-bundle.test.ts` holds that.
@@ -1244,81 +1245,4 @@ function narrowedLines(report: PrReport, words: CiProductWords): string[] {
1244
1245
  return ["", `This ${words.verbs.plan[0]} was narrowed with \`--target\`: ${each}. The approval binds the narrowed plan. On merge each ${words.noun[0]} is ${words.verbs.plan[1]} whole.`];
1245
1246
  }
1246
1247
 
1247
- /** A commit status's description, at most 140 characters (GitHub's limit). */
1248
- export function prStatusDescription(report: PrReport, words: CiProductWords = activeProductWords()): string {
1249
- const n = report.members.length;
1250
- const many = (k: number): string => `${k} ${words.noun[k === 1 ? 0 : 1]}`;
1251
- const sum = report.members.reduce(
1252
- (acc, m) => ({ change: acc.change + m.counts.create + m.counts.update + m.counts.replace, destroy: acc.destroy + m.counts.delete + m.counts.replace }),
1253
- { change: 0, destroy: 0 },
1254
- );
1255
- const digest = report.digest ? `; plan ${report.digest.replace(/^(?:jcs1-)?sha256:/, "").slice(0, 12)}` : "";
1256
- let text: string;
1257
- switch (report.status) {
1258
- case "nothing":
1259
- text = "nothing to plan";
1260
- break;
1261
- case "planned": {
1262
- const unknown = report.members.filter((m) => memberHoleReasons(report, m.member).length > 0).length;
1263
- // #4626: a narrowed plan says so in its status.
1264
- const narrowed = Object.values(report.narrowed ?? {}).filter((a) => a.length > 0).length;
1265
- text = `${many(n)}${narrowed > 0 ? ` (${narrowed} narrowed with --target)` : ""}: ${sum.change} to change, ${sum.destroy} to destroy or replace${unknown > 0 ? `, ${unknown} with holes` : ""}${digest}`;
1266
- break;
1267
- }
1268
- case "plan-failed":
1269
- text = `a ${words.noun[0]} failed to ${words.verbs.plan[0]}${digest}`;
1270
- break;
1271
- case "recorded":
1272
- text = `recorded ${many(n)}: ${report.approval.status === "approved" ? "the approved plan" : report.approval.status === "changed" ? "the plan differs from the approved one" : "no approval for this plan"}${digest}`;
1273
- break;
1274
- case "applied":
1275
- text = `${words.verbs.apply[1]} ${many(n)}${digest}`;
1276
- break;
1277
- case "wave-applied": {
1278
- const last = (report.waves ?? []).filter((w) => w.status === "applied").at(-1);
1279
- text = `applied wave ${last?.wave ?? "?"} of ${report.selection.waves.length}${last ? ` under ${last.approval === "pull-request" ? "the pull request's approval" : `${last.gate}`}` : ""}`;
1280
- break;
1281
- }
1282
- case "failed":
1283
- text = `apply failed for ${report.members.filter((m) => m.status === "failed").map((m) => m.member).join(", ")}`;
1284
- break;
1285
- case "waiting":
1286
- text = `waiting: ${report.members.filter((m) => m.status === "waiting").map((m) => m.member).join(", ")} planned again after an upstream applied, not approved yet`;
1287
- break;
1288
- case "refused": {
1289
- const waiting = report.waves?.find((w) => w.status === "waiting");
1290
- if (waiting && (report.refusal === "wave-not-approved" || report.refusal === "wave-plan-changed")) {
1291
- text = `wave ${waiting.wave} waits at ${waiting.gate}: ${report.refusal === "wave-plan-changed" ? "its plan changed after its approval" : "its plan moved, approve it"}`;
1292
- break;
1293
- }
1294
- if (report.refusal === "earlier-wave") {
1295
- text = "refused: an earlier wave has not applied";
1296
- break;
1297
- }
1298
- if (report.refusal === "requires-unmet" || report.refusal === "before-merge-off") {
1299
- const unmet = (report.beforeMerge?.requires ?? []).filter((r) => !r.passed).map((r) => r.name);
1300
- text = report.refusal === "before-merge-off" ? "refused: this workspace does not apply before merge" : `refused: ${unmet.join(", ") || "a require"} unmet for an apply before merge`;
1301
- break;
1302
- }
1303
- if (report.refusal === "policy-denied" || report.refusal === "policy-error") {
1304
- text = report.refusal === "policy-denied" ? `refused: the policy denied the plan (${(report.policy?.rules ?? []).join(", ")})` : "refused: the policy could not be checked";
1305
- break;
1306
- }
1307
- text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "author-approved" ? "the approver wrote the change" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : report.refusal === "locked" ? "another pull request holds a target lock" : "the plan is not approved"}`;
1308
- break;
1309
- }
1310
- }
1311
- return text.length > 140 ? text.slice(0, 137) + "..." : text;
1312
- }
1313
-
1314
- /** The commit status state for a report: success, failure, or pending while it waits on approval. */
1315
- export function prStatusState(report: PrReport): "success" | "failure" | "pending" {
1316
- // #4168 decision 1: a merge whose plan differs from the approved one is recorded, and its status fails.
1317
- if (report.status === "recorded") return report.approval.status === "changed" ? "failure" : "success";
1318
- // #4294: a plan the policy denied, with no override, or one it could not check, fails at the plan stage as it would at the apply.
1319
- if (report.status === "planned" && report.policy && (report.policy.result === "error" || (report.policy.result === "denied" && !report.policy.override))) return "failure";
1320
- if (report.status === "planned" || report.status === "applied" || report.status === "wave-applied" || report.status === "nothing") return "success";
1321
- if (report.status === "refused" && (report.refusal === "not-approved" || report.refusal === "wave-not-approved")) return "pending";
1322
- if (report.status === "waiting") return "pending";
1323
- return "failure";
1324
- }
1248
+ // The commit status's description and state (`prStatusDescription`, `prStatusState`) are in ./pr-status.ts (#4966).
@@ -68,6 +68,85 @@ export interface PrPlanNoteHandoff {
68
68
  * one space, at most {@link PRODUCT_MARKER_LIMIT} characters.
69
69
  */
70
70
  marker?: string;
71
+ /**
72
+ * What the plan is taken over (#4972), such as sql-yodeler's plan digest
73
+ * and its subject's parts: `pr-post` compares it with the subject it kept
74
+ * in the previous note for the same environment and member, says what
75
+ * changed when its id differs, and keeps this one in the new note.
76
+ */
77
+ subject?: PrPlanSubject;
78
+ }
79
+
80
+ /**
81
+ * A plan's subject (#4972), as a plan verb hands it to the note job, which
82
+ * compares it with the previous note's, so the plan job needs no forge
83
+ * token to read the previous note on any forge. Both are the change's code,
84
+ * so each word is checked against {@link PLAN_SUBJECT_WORD}.
85
+ */
86
+ export interface PrPlanSubject {
87
+ /** The plan as one word, such as its digest: a different id is a changed plan. */
88
+ id: string;
89
+ /**
90
+ * The parts the id is taken over, each `<group>` or `<group>/<item>` to a
91
+ * word (a checksum, a list joined by commas): `pr-post` names the parts
92
+ * added, gone and changed, group by group, in the note words'
93
+ * `subjectParts`. Absent: the line says only that the plan changed.
94
+ */
95
+ parts?: Record<string, string>;
96
+ }
97
+
98
+ /** A word of a plan subject (#4972): letters, digits and `_.,:+=-`, at most 1024 characters, nothing that ends a comment or mentions anyone. */
99
+ export const PLAN_SUBJECT_WORD = /^[A-Za-z0-9_.,:+=-]{1,1024}$/;
100
+
101
+ /** A plan subject part's key (#4972): `<group>` or `<group>/<item>`. */
102
+ export const PLAN_SUBJECT_KEY = /^[A-Za-z0-9_.:+=-]{1,128}(\/[A-Za-z0-9_.,:+=-]{1,256})?$/;
103
+
104
+ /** The most characters the note's kept subject line holds (#4972); a subject with more parts is kept by its id alone. */
105
+ export const PLAN_SUBJECT_LIMIT = 16_384;
106
+
107
+ /** Why `subject` is not a {@link PrPlanSubject} (#4972), or undefined when it is one. */
108
+ export function planSubjectProblem(subject: unknown): string | undefined {
109
+ if (!subject || typeof subject !== "object" || Array.isArray(subject)) return "is not an object";
110
+ const s = subject as Record<string, unknown>;
111
+ if (typeof s.id !== "string" || !PLAN_SUBJECT_WORD.test(s.id)) return "has no id of letters, digits and _.,:+=-";
112
+ if (s.parts === undefined) return undefined;
113
+ if (!s.parts || typeof s.parts !== "object" || Array.isArray(s.parts)) return "has parts that are not an object";
114
+ for (const [k, v] of Object.entries(s.parts)) {
115
+ if (!PLAN_SUBJECT_KEY.test(k)) return `has a part ${JSON.stringify(k.slice(0, 64))} that is not <group> or <group>/<item>`;
116
+ if (typeof v !== "string" || !PLAN_SUBJECT_WORD.test(v)) return `has a part ${k} whose value is not a word of letters, digits and _.,:+=-`;
117
+ }
118
+ return undefined;
119
+ }
120
+
121
+ /** How the note words name one group's changes (#4972), each over `{group}` and `{items}`, the group's items as `item` writes them, joined by ", ". */
122
+ export interface PrPlanSubjectPartWords {
123
+ added?: string;
124
+ gone?: string;
125
+ changed?: string;
126
+ /** One item, over `{item}`, `{before}` and `{after}`. Default `{item}`, or for a part with no item `{before} -> {after}` (changed), `{after}` (added), `{before}` (gone). */
127
+ item?: string;
128
+ }
129
+
130
+ /**
131
+ * A product's plan note hand-off whose note is the product's own text
132
+ * (#4963), in place of a {@link PrPlanNote}: sql-yodeler's tenant set note,
133
+ * which chant's note cannot carry yet. `pr-post` checks it as it checks a
134
+ * {@link PrPlanNoteHandoff}, writes every `<!--` in `body` as `&lt;!--`,
135
+ * puts chant's marker and the product's line (`marker`) above it, adds the
136
+ * overdue Ops and the note job's notices under it, and cuts it to the
137
+ * forge's limit.
138
+ */
139
+ export interface PrPlanBodyHandoff extends Omit<PrPlanNoteHandoff, "note"> {
140
+ /** The note's markdown, at most {@link PLAN_BODY_LIMIT} characters. */
141
+ body: string;
142
+ }
143
+
144
+ /** The most characters a {@link PrPlanBodyHandoff.body} holds (#4963). */
145
+ export const PLAN_BODY_LIMIT = 1_000_000;
146
+
147
+ /** The hand-off for a product's own note text (#4963), as a plan verb writes it to {@link PR_PLAN_NOTE_FILE}. */
148
+ export function planBodyHandoff(body: string, at: { pr: number; head: string; env: string; member?: string; state: PrPlanNoteHandoff["state"]; description: string; marker?: string; subject?: PrPlanSubject }): PrPlanBodyHandoff {
149
+ return { kind: "plan-note-handoff", contract: PR_PLAN_NOTE_CONTRACT, pr: at.pr, head: at.head, env: at.env, ...(at.member !== undefined ? { member: at.member } : {}), state: at.state, description: at.description, body, ...(at.marker !== undefined ? { marker: at.marker } : {}), ...(at.subject !== undefined ? { subject: at.subject } : {}) };
71
150
  }
72
151
 
73
152
  /** The most characters a hand-off's {@link PrPlanNoteHandoff.marker} holds (#4931). */
@@ -85,8 +164,8 @@ export function productMarkerLine(name: string, body: string): string {
85
164
  }
86
165
 
87
166
  /** The hand-off for `note` (#4799), as a product's plan verb writes it to {@link PR_PLAN_NOTE_FILE}. */
88
- export function planNoteHandoff(note: PrPlanNote, at: { pr: number; env: string; member?: string; state: PrPlanNoteHandoff["state"]; description: string; marker?: string }): PrPlanNoteHandoff {
89
- return { kind: "plan-note-handoff", contract: PR_PLAN_NOTE_CONTRACT, pr: at.pr, head: note.head, env: at.env, ...(at.member !== undefined ? { member: at.member } : {}), state: at.state, description: at.description, note, ...(at.marker !== undefined ? { marker: at.marker } : {}) };
167
+ export function planNoteHandoff(note: PrPlanNote, at: { pr: number; env: string; member?: string; state: PrPlanNoteHandoff["state"]; description: string; marker?: string; subject?: PrPlanSubject }): PrPlanNoteHandoff {
168
+ return { kind: "plan-note-handoff", contract: PR_PLAN_NOTE_CONTRACT, pr: at.pr, head: note.head, env: at.env, ...(at.member !== undefined ? { member: at.member } : {}), state: at.state, description: at.description, note, ...(at.marker !== undefined ? { marker: at.marker } : {}), ...(at.subject !== undefined ? { subject: at.subject } : {}) };
90
169
  }
91
170
 
92
171
  /** One change line of a group, as chant's plan summary groups them. */
@@ -258,9 +337,82 @@ export interface PrPlanNoteWords {
258
337
  * note by it. Absent: a hand-off's marker is dropped.
259
338
  */
260
339
  productMarker?: string;
340
+ /**
341
+ * The line `pr-post` adds when a hand-off's subject differs from the
342
+ * previous note's (#4972), over `{previous}` (the previous subject's id)
343
+ * and `{changes}` (what changed, part by part, joined by "; "). Default
344
+ * "Since the previous version of this note (`{previous}`): {changes}.".
345
+ */
346
+ sinceLast?: string;
347
+ /**
348
+ * The line when no part says what changed (#4972): the subject has no
349
+ * parts, or the previous note kept its id alone. Over `{previous}`.
350
+ * Default "The plan changed since the previous version of this note (`{previous}`).".
351
+ */
352
+ sinceLastOnly?: string;
353
+ /** How `{changes}` names each group of the subject's parts (#4972), by group. Default "{group}: {items} added" (gone, changed). */
354
+ subjectParts?: Record<string, PrPlanSubjectPartWords>;
355
+ }
356
+
357
+ /** The {@link PrPlanNoteWords.sinceLast} default (#4972). */
358
+ export const SINCE_LAST_LINE = "Since the previous version of this note (`{previous}`): {changes}.";
359
+ /** The {@link PrPlanNoteWords.sinceLastOnly} default (#4972). */
360
+ export const SINCE_LAST_ONLY_LINE = "The plan changed since the previous version of this note (`{previous}`).";
361
+
362
+ /**
363
+ * What changed from `before` to `after`, group by group (#4972): each
364
+ * group's added, gone and changed parts in the note words, groups in the
365
+ * order `after` names them, then those only `before` names.
366
+ */
367
+ export function subjectChanges(before: Record<string, string>, after: Record<string, string>, words: Record<string, PrPlanSubjectPartWords> = {}): string[] {
368
+ const groupOf = (k: string): [string, string] => {
369
+ const at = k.indexOf("/");
370
+ return at < 0 ? [k, ""] : [k.slice(0, at), k.slice(at + 1)];
371
+ };
372
+ const has = (o: object, k: string): boolean => Object.prototype.hasOwnProperty.call(o, k);
373
+ const groups: string[] = [];
374
+ for (const k of [...Object.keys(after), ...Object.keys(before)]) {
375
+ const [g] = groupOf(k);
376
+ if (!groups.includes(g)) groups.push(g);
377
+ }
378
+ const fill = (t: string, v: Record<string, string>): string => t.replace(/\{(group|items|item|before|after)\}/g, (_, n: string) => v[n] ?? "");
379
+ const out: string[] = [];
380
+ for (const group of groups) {
381
+ const w = has(words, group) ? words[group]! : {};
382
+ const kinds: Record<"added" | "gone" | "changed", string[]> = { added: [], gone: [], changed: [] };
383
+ const say = (kind: "added" | "gone" | "changed", item: string, b: string, a: string) => {
384
+ const dflt = item !== "" ? "{item}" : kind === "changed" ? "{before} -> {after}" : kind === "added" ? "{after}" : "{before}";
385
+ kinds[kind].push(fill(w.item ?? dflt, { item, before: b, after: a, group }));
386
+ };
387
+ for (const k of Object.keys(after)) {
388
+ const [g, item] = groupOf(k);
389
+ if (g !== group) continue;
390
+ if (!has(before, k)) say("added", item, "", after[k]!);
391
+ else if (before[k] !== after[k]) say("changed", item, before[k]!, after[k]!);
392
+ }
393
+ for (const k of Object.keys(before)) {
394
+ const [g, item] = groupOf(k);
395
+ if (g === group && !has(after, k)) say("gone", item, before[k]!, "");
396
+ }
397
+ for (const kind of ["added", "gone", "changed"] as const) {
398
+ if (kinds[kind].length > 0) out.push(fill(w[kind] ?? `{group}: {items} ${kind}`, { group, items: kinds[kind].join(", ") }));
399
+ }
400
+ }
401
+ return out;
402
+ }
403
+
404
+ /**
405
+ * The line for a plan whose subject is no longer `previous`'s (#4972), in
406
+ * the note words, or undefined when the ids are the same.
407
+ */
408
+ export function sinceLastLine(previous: PrPlanSubject, now: PrPlanSubject, words: Pick<PrPlanNoteWords, "sinceLast" | "sinceLastOnly" | "subjectParts"> = {}): string | undefined {
409
+ if (previous.id === now.id) return undefined;
410
+ const changes = previous.parts && now.parts ? subjectChanges(previous.parts, now.parts, words.subjectParts) : [];
411
+ const fill = (t: string): string => t.replace(/\{(previous|changes)\}/g, (_, n: string) => (n === "previous" ? previous.id : changes.join("; ")));
412
+ return changes.length > 0 ? fill(words.sinceLast ?? SINCE_LAST_LINE) : fill(words.sinceLastOnly ?? SINCE_LAST_ONLY_LINE);
261
413
  }
262
414
 
263
- const NOTE_WORDS: Required<Omit<PrPlanNoteWords, "marker" | "productMarker">> = {
415
+ const NOTE_WORDS: Required<Omit<PrPlanNoteWords, "marker" | "productMarker" | "sinceLast" | "sinceLastOnly" | "subjectParts">> = {
264
416
  footer: "",
265
417
  page: "report.html",
266
418
  artifact: "chant-pr",