@intentius/chant 0.124.88 → 0.124.89

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (303) hide show
  1. package/dist/actor.d.ts +36 -1
  2. package/dist/actor.d.ts.map +1 -1
  3. package/dist/actor.js +39 -1
  4. package/dist/chant-install.d.ts.map +1 -1
  5. package/dist/chant-install.js +1 -2
  6. package/dist/ci-base.d.ts +30 -0
  7. package/dist/ci-base.d.ts.map +1 -0
  8. package/dist/ci-base.js +33 -0
  9. package/dist/ci-comment-commands.d.ts +177 -0
  10. package/dist/ci-comment-commands.d.ts.map +1 -0
  11. package/dist/ci-comment-commands.js +325 -0
  12. package/dist/ci-comment-replies.d.ts +40 -0
  13. package/dist/ci-comment-replies.d.ts.map +1 -0
  14. package/dist/ci-comment-replies.js +59 -0
  15. package/dist/ci-evidence-from-job.d.ts +25 -0
  16. package/dist/ci-evidence-from-job.d.ts.map +1 -1
  17. package/dist/ci-evidence-from-job.js +43 -2
  18. package/dist/ci-evidence-jobs.d.ts +30 -1
  19. package/dist/ci-evidence-jobs.d.ts.map +1 -1
  20. package/dist/ci-evidence-jobs.js +46 -3
  21. package/dist/ci-image.d.ts +21 -4
  22. package/dist/ci-image.d.ts.map +1 -1
  23. package/dist/ci-image.js +62 -10
  24. package/dist/ci-note-commands.d.ts +63 -3
  25. package/dist/ci-note-commands.d.ts.map +1 -1
  26. package/dist/ci-note-commands.js +69 -35
  27. package/dist/ci-product-words.d.ts +42 -0
  28. package/dist/ci-product-words.d.ts.map +1 -1
  29. package/dist/ci-product-words.js +25 -0
  30. package/dist/ci-product.d.ts +31 -0
  31. package/dist/ci-product.d.ts.map +1 -1
  32. package/dist/ci-product.js +34 -4
  33. package/dist/cli/commands/build.d.ts.map +1 -1
  34. package/dist/cli/commands/build.js +29 -2
  35. package/dist/cli/handlers/approve.d.ts.map +1 -1
  36. package/dist/cli/handlers/approve.js +2 -1
  37. package/dist/cli/handlers/ci-check.d.ts +1 -1
  38. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  39. package/dist/cli/handlers/ci-check.js +17 -7
  40. package/dist/cli/handlers/ci-evidence.d.ts.map +1 -1
  41. package/dist/cli/handlers/ci-evidence.js +33 -7
  42. package/dist/cli/handlers/components.d.ts.map +1 -1
  43. package/dist/cli/handlers/components.js +3 -1
  44. package/dist/cli/handlers/generated-check.d.ts +8 -0
  45. package/dist/cli/handlers/generated-check.d.ts.map +1 -1
  46. package/dist/cli/handlers/generated-check.js +31 -1
  47. package/dist/cli/handlers/lock.d.ts.map +1 -1
  48. package/dist/cli/handlers/lock.js +121 -4
  49. package/dist/cli/handlers/pr-comment.d.ts +21 -0
  50. package/dist/cli/handlers/pr-comment.d.ts.map +1 -0
  51. package/dist/cli/handlers/pr-comment.js +112 -0
  52. package/dist/cli/handlers/pr-env.d.ts.map +1 -1
  53. package/dist/cli/handlers/pr-env.js +6 -3
  54. package/dist/cli/handlers/pr.d.ts +23 -1
  55. package/dist/cli/handlers/pr.d.ts.map +1 -1
  56. package/dist/cli/handlers/pr.js +55 -9
  57. package/dist/cli/handlers/promote.d.ts.map +1 -1
  58. package/dist/cli/handlers/promote.js +2 -1
  59. package/dist/cli/handlers/release.d.ts.map +1 -1
  60. package/dist/cli/handlers/release.js +11 -2
  61. package/dist/cli/handlers/run-wave.d.ts.map +1 -1
  62. package/dist/cli/handlers/run-wave.js +28 -2
  63. package/dist/cli/handlers/run.d.ts.map +1 -1
  64. package/dist/cli/handlers/run.js +2 -1
  65. package/dist/cli/main.d.ts.map +1 -1
  66. package/dist/cli/main.js +24 -2
  67. package/dist/cli/parse-args.d.ts.map +1 -1
  68. package/dist/cli/parse-args.js +16 -0
  69. package/dist/cli/registry.d.ts +11 -0
  70. package/dist/cli/registry.d.ts.map +1 -1
  71. package/dist/components/auto-release.d.ts.map +1 -1
  72. package/dist/components/auto-release.js +2 -1
  73. package/dist/components/pr-checks.d.ts +70 -6
  74. package/dist/components/pr-checks.d.ts.map +1 -1
  75. package/dist/components/pr-checks.js +74 -13
  76. package/dist/components/pr-pipeline.d.ts +16 -12
  77. package/dist/components/pr-pipeline.d.ts.map +1 -1
  78. package/dist/components/pr-pipeline.js +3 -11
  79. package/dist/components/product-pipeline.d.ts +42 -1
  80. package/dist/components/product-pipeline.d.ts.map +1 -1
  81. package/dist/components/product-pipeline.js +64 -12
  82. package/dist/components/product-plan.d.ts +190 -5
  83. package/dist/components/product-plan.d.ts.map +1 -1
  84. package/dist/components/product-plan.js +220 -39
  85. package/dist/drift-record.d.ts +7 -0
  86. package/dist/drift-record.d.ts.map +1 -1
  87. package/dist/drift-record.js +19 -0
  88. package/dist/floor-table.data.d.ts.map +1 -1
  89. package/dist/floor-table.data.js +54 -31
  90. package/dist/forge-check/contract.d.ts +11 -1
  91. package/dist/forge-check/contract.d.ts.map +1 -1
  92. package/dist/forge-check/contract.js +4 -1
  93. package/dist/forge-check/index.d.ts +2 -0
  94. package/dist/forge-check/index.d.ts.map +1 -1
  95. package/dist/forge-check/index.js +2 -0
  96. package/dist/gate-resume-run.d.ts +9 -1
  97. package/dist/gate-resume-run.d.ts.map +1 -1
  98. package/dist/gate-resume-run.js +26 -3
  99. package/dist/generated-check.d.ts +18 -4
  100. package/dist/generated-check.d.ts.map +1 -1
  101. package/dist/generated-check.js +37 -5
  102. package/dist/image-pins.d.ts +26 -0
  103. package/dist/image-pins.d.ts.map +1 -0
  104. package/dist/image-pins.js +19 -0
  105. package/dist/lexicon.d.ts +11 -0
  106. package/dist/lexicon.d.ts.map +1 -1
  107. package/dist/lifecycle/git.d.ts +11 -0
  108. package/dist/lifecycle/git.d.ts.map +1 -1
  109. package/dist/lifecycle/git.js +30 -3
  110. package/dist/lifecycle/publish-npm.d.ts +11 -0
  111. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  112. package/dist/lifecycle/publish-npm.js +27 -1
  113. package/dist/lifecycle/reach-locks.d.ts +131 -0
  114. package/dist/lifecycle/reach-locks.d.ts.map +1 -0
  115. package/dist/lifecycle/reach-locks.js +118 -0
  116. package/dist/lifecycle/release-cut.d.ts +3 -1
  117. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  118. package/dist/lifecycle/release-cut.js +15 -0
  119. package/dist/lifecycle/release-images.d.ts.map +1 -1
  120. package/dist/lifecycle/release-images.js +1 -2
  121. package/dist/notify-product.d.ts +12 -3
  122. package/dist/notify-product.d.ts.map +1 -1
  123. package/dist/notify-product.js +10 -6
  124. package/dist/op/activities/source-release.d.ts.map +1 -1
  125. package/dist/op/activities/source-release.js +2 -1
  126. package/dist/op/activities/source-rollback.d.ts.map +1 -1
  127. package/dist/op/activities/source-rollback.js +2 -1
  128. package/dist/op/index.d.ts +2 -0
  129. package/dist/op/index.d.ts.map +1 -1
  130. package/dist/op/index.js +1 -0
  131. package/dist/op/op-waves-evidence-jobs.d.ts +6 -1
  132. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  133. package/dist/op/op-waves-evidence-jobs.js +9 -3
  134. package/dist/op/op-waves-render-spec.d.ts +100 -0
  135. package/dist/op/op-waves-render-spec.d.ts.map +1 -0
  136. package/dist/op/op-waves-render-spec.js +162 -0
  137. package/dist/op/op-waves-run.d.ts +2 -0
  138. package/dist/op/op-waves-run.d.ts.map +1 -1
  139. package/dist/op/op-waves-run.js +2 -1
  140. package/dist/op/op-waves.d.ts +4 -0
  141. package/dist/op/op-waves.d.ts.map +1 -1
  142. package/dist/op/op-waves.js +4 -1
  143. package/dist/op/schedule-overdue.d.ts.map +1 -1
  144. package/dist/op/schedule-overdue.js +59 -3
  145. package/dist/op/wave-stop.d.ts +64 -0
  146. package/dist/op/wave-stop.d.ts.map +1 -0
  147. package/dist/op/wave-stop.js +127 -0
  148. package/dist/planned-files.d.ts +76 -0
  149. package/dist/planned-files.d.ts.map +1 -0
  150. package/dist/planned-files.js +108 -0
  151. package/dist/pr-forge-job.d.ts +22 -0
  152. package/dist/pr-forge-job.d.ts.map +1 -0
  153. package/dist/pr-forge-job.js +46 -0
  154. package/dist/pr-loop.d.ts +3 -6
  155. package/dist/pr-loop.d.ts.map +1 -1
  156. package/dist/pr-loop.js +4 -81
  157. package/dist/pr-plan-note.d.ts +97 -0
  158. package/dist/pr-plan-note.d.ts.map +1 -1
  159. package/dist/pr-plan-note.js +94 -1
  160. package/dist/pr-post.d.ts +28 -3
  161. package/dist/pr-post.d.ts.map +1 -1
  162. package/dist/pr-post.js +145 -13
  163. package/dist/pr-status.d.ts +16 -0
  164. package/dist/pr-status.d.ts.map +1 -0
  165. package/dist/pr-status.js +90 -0
  166. package/dist/ref-gate-init.d.ts +16 -2
  167. package/dist/ref-gate-init.d.ts.map +1 -1
  168. package/dist/ref-gate-init.js +24 -13
  169. package/dist/release-floors.d.ts +37 -1
  170. package/dist/release-floors.d.ts.map +1 -1
  171. package/dist/release-floors.js +61 -25
  172. package/dist/render-module.d.ts +15 -0
  173. package/dist/render-module.d.ts.map +1 -0
  174. package/dist/render-module.js +73 -0
  175. package/dist/state-migration.d.ts.map +1 -1
  176. package/dist/state-migration.js +1 -2
  177. package/dist/wave-runtime.mjs +304 -301
  178. package/dist/workspace/ci-green-cli.d.ts.map +1 -1
  179. package/dist/workspace/ci-green-cli.js +3 -2
  180. package/dist/workspace/release-train.d.ts.map +1 -1
  181. package/dist/workspace/release-train.js +2 -1
  182. package/dist/workspace/release-workflow.d.ts +4 -3
  183. package/dist/workspace/release-workflow.d.ts.map +1 -1
  184. package/dist/workspace/release-workflow.js +10 -7
  185. package/dist/workspace/trust/check-evidence-report.d.ts +7 -2
  186. package/dist/workspace/trust/check-evidence-report.d.ts.map +1 -1
  187. package/dist/workspace/trust/check-evidence-report.js +15 -8
  188. package/dist/workspace/trust/ref-gate-cli.d.ts +10 -1
  189. package/dist/workspace/trust/ref-gate-cli.d.ts.map +1 -1
  190. package/dist/workspace/trust/ref-gate-cli.js +30 -10
  191. package/dist/workspace/workspace-run.d.ts.map +1 -1
  192. package/dist/workspace/workspace-run.js +2 -1
  193. package/package.json +1 -1
  194. package/src/actor.test.ts +68 -2
  195. package/src/actor.ts +61 -1
  196. package/src/chant-install.test.ts +2 -3
  197. package/src/chant-install.ts +1 -2
  198. package/src/ci-base.test.ts +41 -0
  199. package/src/ci-base.ts +43 -0
  200. package/src/ci-comment-commands.test.ts +376 -0
  201. package/src/ci-comment-commands.ts +389 -0
  202. package/src/ci-comment-replies.ts +78 -0
  203. package/src/ci-commit.test.ts +2 -3
  204. package/src/ci-evidence-from-job.test.ts +18 -0
  205. package/src/ci-evidence-from-job.ts +58 -2
  206. package/src/ci-evidence-jobs.ts +50 -5
  207. package/src/ci-image.test.ts +130 -9
  208. package/src/ci-image.ts +85 -12
  209. package/src/ci-note-commands.ts +104 -41
  210. package/src/ci-product-words.ts +59 -0
  211. package/src/ci-product.ts +40 -4
  212. package/src/cli/commands/build.test.ts +41 -0
  213. package/src/cli/commands/build.ts +27 -2
  214. package/src/cli/handlers/approve.ts +2 -1
  215. package/src/cli/handlers/ci-check.ts +19 -7
  216. package/src/cli/handlers/ci-evidence.ts +29 -8
  217. package/src/cli/handlers/components.ts +3 -1
  218. package/src/cli/handlers/generated-check.ts +31 -1
  219. package/src/cli/handlers/lock-reach.test.ts +103 -0
  220. package/src/cli/handlers/lock.ts +100 -4
  221. package/src/cli/handlers/pr-comment.ts +104 -0
  222. package/src/cli/handlers/pr-env.ts +6 -3
  223. package/src/cli/handlers/pr-record.test.ts +1 -1
  224. package/src/cli/handlers/pr.ts +50 -10
  225. package/src/cli/handlers/promote.ts +2 -1
  226. package/src/cli/handlers/release.e2e.test.ts +35 -0
  227. package/src/cli/handlers/release.ts +14 -2
  228. package/src/cli/handlers/run-wave.ts +28 -2
  229. package/src/cli/handlers/run.ts +2 -1
  230. package/src/cli/main.ts +24 -2
  231. package/src/cli/parse-args.ts +12 -0
  232. package/src/cli/registry.ts +11 -0
  233. package/src/components/auto-release.ts +2 -1
  234. package/src/components/pr-checks.ts +112 -17
  235. package/src/components/pr-pipeline.ts +17 -15
  236. package/src/components/product-pipeline.ts +93 -11
  237. package/src/components/product-plan.test.ts +40 -2
  238. package/src/components/product-plan.ts +331 -45
  239. package/src/drift-record.test.ts +20 -0
  240. package/src/drift-record.ts +16 -0
  241. package/src/floor-table.data.ts +54 -31
  242. package/src/forge-check/contract.ts +12 -1
  243. package/src/forge-check/forge-check.test.ts +17 -0
  244. package/src/forge-check/index.ts +2 -0
  245. package/src/gate-resume-run.ts +27 -3
  246. package/src/generated-check.e2e.test.ts +21 -1
  247. package/src/generated-check.test.ts +66 -0
  248. package/src/generated-check.ts +51 -10
  249. package/src/image-pins.ts +31 -0
  250. package/src/lexicon.ts +11 -0
  251. package/src/lifecycle/git.test.ts +48 -0
  252. package/src/lifecycle/git.ts +27 -4
  253. package/src/lifecycle/publish-npm.ts +31 -1
  254. package/src/lifecycle/reach-locks.test.ts +87 -0
  255. package/src/lifecycle/reach-locks.ts +169 -0
  256. package/src/lifecycle/release-cut.ts +17 -1
  257. package/src/lifecycle/release-images.test.ts +56 -0
  258. package/src/lifecycle/release-images.ts +1 -2
  259. package/src/notify-product.ts +19 -8
  260. package/src/op/activities/source-release.ts +2 -1
  261. package/src/op/activities/source-rollback.ts +2 -1
  262. package/src/op/gate-resume.test.ts +27 -0
  263. package/src/op/index.ts +10 -0
  264. package/src/op/op-waves-evidence-jobs.ts +10 -4
  265. package/src/op/op-waves-notify-words.test.ts +18 -0
  266. package/src/op/op-waves-render-spec.test.ts +160 -0
  267. package/src/op/op-waves-render-spec.ts +171 -0
  268. package/src/op/op-waves-run.ts +2 -1
  269. package/src/op/op-waves.ts +5 -2
  270. package/src/op/schedule-overdue.test.ts +43 -0
  271. package/src/op/schedule-overdue.ts +57 -3
  272. package/src/op/wave-stop.test.ts +72 -0
  273. package/src/op/wave-stop.ts +137 -0
  274. package/src/planned-files.test.ts +80 -0
  275. package/src/planned-files.ts +134 -0
  276. package/src/pr-forge-job.test.ts +53 -0
  277. package/src/pr-forge-job.ts +46 -0
  278. package/src/pr-loop-narrowed.test.ts +2 -1
  279. package/src/pr-loop-words.test.ts +2 -1
  280. package/src/pr-loop.test.ts +1 -2
  281. package/src/pr-loop.ts +4 -80
  282. package/src/pr-plan-note.ts +155 -3
  283. package/src/pr-post-replan.test.ts +144 -0
  284. package/src/pr-post-subject.test.ts +230 -0
  285. package/src/pr-post.test.ts +2 -1
  286. package/src/pr-post.ts +150 -15
  287. package/src/pr-status.ts +91 -0
  288. package/src/ref-gate-init.ts +30 -11
  289. package/src/release-floors.ts +78 -25
  290. package/src/render-module.ts +73 -0
  291. package/src/state-migration-record.test.ts +2 -3
  292. package/src/state-migration.ts +1 -2
  293. package/src/workspace/ci-green-cli.ts +3 -2
  294. package/src/workspace/ci-green-workflow.test.ts +32 -1
  295. package/src/workspace/release-train.ts +2 -1
  296. package/src/workspace/release-workflow.test.ts +36 -5
  297. package/src/workspace/release-workflow.ts +10 -7
  298. package/src/workspace/trust/check-evidence-report.ts +15 -8
  299. package/src/workspace/trust/check-evidence.test.ts +5 -0
  300. package/src/workspace/trust/ref-gate-cli.ts +30 -8
  301. package/src/workspace/trust/ref-gate-pieces.test.ts +46 -1
  302. package/src/workspace/trust/ref-gate.test.ts +10 -0
  303. package/src/workspace/workspace-run.ts +2 -1
@@ -25,6 +25,9 @@
25
25
  * target's own variables and secrets, and an optional write probe before the
26
26
  * plan. A target is the note's and the status's member: `pr-post --member
27
27
  * <target>`, so each target has its note and its `<product>/plan/<target>`.
28
+ * With `evidence`, a target's note job (GitLab: `<target>-plan-evidence`)
29
+ * signs `plan:<target>` and `policy:<target>` (#4978,
30
+ * `targetEvidenceCheck`): one target's plan says nothing of another's.
28
31
  *
29
32
  * The forge lexicons render these descriptors
30
33
  * (`generateProductPlanPipeline` in each): the products call them in
@@ -36,7 +39,8 @@ import type { CiRunner } from "../ci-jobs";
36
39
  import type { CiProductWords } from "../ci-product-words";
37
40
  import type { PrPlanNoteWords } from "../pr-plan-note";
38
41
  import { assertPipelineEvidence, evidenceIdTokens, evidenceKeyEnv, evidenceKeyless, gitlabOpenEvidenceDir, openEvidenceLines, planEvidenceLines, type PipelineEvidence } from "../ci-evidence-jobs";
39
- import { gitlabPlanJobName, PR_LOOP_REPORT_DIR, PR_PLAN_NOTE_JOB, prLoopPassedEnv, prLoopPostJob, prLoopRunner, type PrLoopPipelineOptions } from "./pr-pipeline";
42
+ import { gitlabPlanJobName, PR_LOCK_JOB, PR_LOOP_REPORT_DIR, PR_PLAN_NOTE_JOB, prLoopPassedEnv, prLoopPostJob, prLoopRunner, withProductBin, type PrLoopPipelineOptions } from "./pr-pipeline";
43
+ import { LOCK_REACH_ENV } from "../lifecycle/reach-locks";
40
44
  import { GITHUB_JOB_TOKEN } from "../ci-jobs";
41
45
  import { cloudLogin, type CloudLoginSpec } from "../ci-login";
42
46
  import type { OpWaveRunStep } from "../lexicon";
@@ -44,6 +48,9 @@ import { controlNoteCheckout, type ControlNoteCheckout, type ControlTarget } fro
44
48
  import { commentLine, productStatusContext } from "../ci-product-words";
45
49
  import { PLAN_WATCHES_ENV, scheduledWatchProblem, type ScheduledWatch } from "../op/schedule-overdue";
46
50
  import { PLAN_RUN_OP, PLAN_RUN_RECORD_FILE } from "../pr-plan-record";
51
+ import { idTokenVar, tradedClouds, type CloudTradeSpec } from "../ci-identity";
52
+ import { prNoteMarker } from "../pr-loop";
53
+ import { PRODUCT_MARKER_NAME } from "../pr-plan-note";
47
54
 
48
55
  /** The variable the plan-note job reads the product's note words from (#4799), as JSON. Set from the pipeline, never from the report. */
49
56
  export const PR_PLAN_NOTE_WORDS_ENV = "CHANT_PLAN_NOTE_WORDS";
@@ -71,6 +78,45 @@ export interface ProductPlanTarget {
71
78
  login?: CloudLoginSpec;
72
79
  /** OIDC tokens this target's plan job requests besides its login's, `{ <variable>: <audience> }`, in place of the plan's {@link ProductPlanOptions.idTokens}. */
73
80
  idTokens?: Record<string, string>;
81
+ /** This target's trade (#4963), in place of the plan's {@link ProductPlanOptions.trade}. A target gives one of `login` and `trade`. */
82
+ trade?: CloudTradeSpec;
83
+ }
84
+
85
+ /**
86
+ * What the comment re-plan does besides answering the plan command (#4963),
87
+ * `replan: { ... }` in place of `replan: true`.
88
+ */
89
+ export interface ProductPlanReplanOptions {
90
+ /**
91
+ * Re-plan from `workflow_dispatch` too, on GitHub and Forgejo: the inputs
92
+ * `pr` (the pull request) and `argument` (default `argument`; the target,
93
+ * or the one word {@link PLAN_ARGUMENT_ENV} reads, such as terragucci's
94
+ * `root`). Either forge lets only someone who can write to the repository
95
+ * dispatch, so the decision asks no permission for it. On GitLab a web
96
+ * pipeline of the target branch with `CHANT_PREVIEW_PR` and
97
+ * `CHANT_PREVIEW_COMMENT` is the dispatch already, so it renders nothing
98
+ * more there.
99
+ */
100
+ dispatch?: boolean | { argument?: string };
101
+ /**
102
+ * Reply to a `/<product>` comment no other job takes (#4963), on GitHub
103
+ * and Forgejo: a word that is not the plan command, a target that is none
104
+ * of the plan's, and a pull request from a fork with `forks: "skip"`. The
105
+ * reply names the commands. `others` are the comments the product's own
106
+ * jobs answer, such as `/terragucci apply`: the re-plan leaves them alone.
107
+ * With targets, the first target's re-plan job replies. GitLab's
108
+ * note-commands job answers every comment already.
109
+ */
110
+ reply?: boolean | { others?: string[] };
111
+ /**
112
+ * Reply "not affected" for a re-plan narrowed to one argument the change
113
+ * does not reach (#4963): when the hand-off's note says `nothing` (or a
114
+ * `PrReport` says `nothing`), the re-plan's note job comments
115
+ * `<product>: <argument> is not affected by this pull request, so
116
+ * nothing was planned.` and leaves the note and the status as they were
117
+ * (`pr-post --not-affected <argument>`).
118
+ */
119
+ notAffected?: boolean;
74
120
  }
75
121
 
76
122
  /**
@@ -109,6 +155,12 @@ export interface ProductPlanReplanJob {
109
155
  post: { command: string; env: Record<string, string>; setup?: string[] };
110
156
  /** The artifact the note job (GitHub, Forgejo) or the re-plan job (GitLab) keeps the directory as. */
111
157
  artifact: string;
158
+ /** With `dispatch` (#4963), GitHub and Forgejo: the `workflow_dispatch` input that names the argument. */
159
+ dispatch?: { argument: string };
160
+ /** With `reply` (#4963), GitHub and Forgejo, on one re-plan job: the product's prefix and the comments other jobs answer. */
161
+ reply?: { prefix: string; others: string[] };
162
+ /** With `notAffected` (#4963): the note job's command carries `--not-affected`, and reads the argument as {@link PLAN_ARGUMENT_ENV}. */
163
+ notAffected?: true;
112
164
  }
113
165
 
114
166
  /** The variable a comment re-plan's one argument reaches the plan verb in (#4899). Empty on a pull request's own plan. */
@@ -206,7 +258,37 @@ export interface ProductPlanOptions {
206
258
  * pipeline of the target branch for the comment, which runs the re-plan
207
259
  * jobs whose target the comment names.
208
260
  */
209
- replan?: boolean;
261
+ replan?: boolean | ProductPlanReplanOptions;
262
+ /**
263
+ * The plan job's trade (#4963): chant's trade of the job's OIDC token for
264
+ * the plan identities' own credentials (`@intentius/chant/ci-identity`,
265
+ * #4296), before the change is checked out, as terragucci's re-plan
266
+ * trades. The plan job and the re-plan job trade in a step of their own
267
+ * (GitHub, Forgejo: after the pending status and the re-plan's decision,
268
+ * before the checkout; GitLab: the script's first lines, before the
269
+ * re-plan checks out the head), and every later step starts without the
270
+ * variables a token is requested with, so the change's code holds the
271
+ * traded credentials and no OIDC token. Give one of `login` and `trade`.
272
+ */
273
+ trade?: CloudTradeSpec;
274
+ /**
275
+ * The previous note's product marker for the plan verb (#4963), on GitHub
276
+ * and Forgejo: a step before the checkout, which alone holds the job's
277
+ * token, finds the pull request's note by chant's marker and sets
278
+ * `CHANT_PLAN_PREVIOUS_MARKER` to the body of its second line, the
279
+ * product's own (`noteWords.productMarker`, a hand-off's `marker`), so a
280
+ * plan verb such as `yodel plan` reads the digest subject it left there
281
+ * and says what moved. Empty when there is no note yet. The body was
282
+ * checked against the marker's pattern before chant posted it, and is
283
+ * checked again. Needs `noteWords.productMarker`. GitLab's plan job holds
284
+ * no token to read a note with, so it takes none.
285
+ *
286
+ * @deprecated #4972: hand the plan's `subject` in the plan note hand-off
287
+ * instead. The note job compares it with the previous note's on every
288
+ * forge and says what changed, so the plan job reads no note. This option
289
+ * still works on GitHub and Forgejo.
290
+ */
291
+ previousMarker?: boolean;
210
292
  /**
211
293
  * Lines the note job runs (#4931), on GitHub and Forgejo, in the job that
212
294
  * holds the token and none of the change's code: `before` after the report
@@ -216,8 +298,13 @@ export interface ProductPlanOptions {
216
298
  * note's counts, such as terragucci's notice naming whose review does not
217
299
  * count. They reach the job's token as `GITHUB_TOKEN`. GitLab's note job
218
300
  * posts every open merge request's note in one run, so it takes none.
301
+ *
302
+ * With `pullRequest` (#4963) the lines also read the pull request and the
303
+ * commit planned as `PR_NUMBER` and `HEAD_SHA`, the note's own, which in
304
+ * a re-plan's note job come from the re-plan job, such as terragucci's
305
+ * notice and approval status, which ask the forge about the head.
219
306
  */
220
- noteSteps?: { before?: string[]; after?: string[] };
307
+ noteSteps?: { before?: string[]; after?: string[]; pullRequest?: boolean };
221
308
  /**
222
309
  * The product's own scheduled jobs the note job checks for having stopped
223
310
  * (#4888), such as terragucci's drift job: each a `ScheduledWatch` with
@@ -243,6 +330,64 @@ export interface ProductPlanOptions {
243
330
  * Unsigned, as `pr-plan`'s is (#4328). Default off.
244
331
  */
245
332
  record?: boolean;
333
+ /**
334
+ * What the lock job locks under `locks: "plan"` (#4979): the targets the
335
+ * change reaches, by the product's reach line, in place of what a
336
+ * `PrReport` selected. `command` is one shell line that prints the target
337
+ * names the change from `$BASE_SHA` to `$HEAD_SHA` reaches, one a line,
338
+ * reading the change's files as data from git (`git diff`, `git show`),
339
+ * such as terragucci's roots, Terragrunt units or Atmos instances. It
340
+ * runs at the target branch's commit, after chant fetched the pull
341
+ * request's head and checked it is the head the job was started for
342
+ * (`chant lock --reach`, ../lifecycle/reach-locks.ts), so none of the
343
+ * change's code runs in the job that holds the write token. `gate` names
344
+ * the lock file, `_locks/<gate>.json` (default the pull request loop's).
345
+ *
346
+ * GitHub and Forgejo run one `lock` job on each push of a pull request
347
+ * from this repository, beside the plan, and the `unlock` job on close.
348
+ * On GitLab, where a merge request's pipeline is built from its own files,
349
+ * the `lock` job runs in the target branch's plan notes pipeline and locks
350
+ * every open merge request (`--open`), releasing the locks of one that is
351
+ * no longer open; with `noteCommands` the comment lock and unlock jobs
352
+ * answer `/<product> lock` and `/<product> unlock` there too.
353
+ */
354
+ reach?: { command: string; gate?: string };
355
+ }
356
+
357
+ /** The lock job a product plan with {@link ProductPlanOptions.reach} writes (#4979): its command and the values the command reads. */
358
+ export interface ProductPlanReachLock {
359
+ jobName: typeof PR_LOCK_JOB;
360
+ command: string;
361
+ env: Record<string, string>;
362
+ runner?: CiRunner;
363
+ }
364
+
365
+ /**
366
+ * The reach lock job (#4979), under `locks: "plan"` with `reach`: `chant lock
367
+ * --reach` through the words' bin, with the reach line as
368
+ * {@link LOCK_REACH_ENV}. On GitHub and Forgejo it locks the pull request of
369
+ * the event; on GitLab every open merge request into the branch.
370
+ */
371
+ export function productPlanReachLock(forge: ForgeKind, loop: Pick<PrLoopPipelineOptions, "locks" | "runners"> & { plan: Pick<ProductPlanOptions, "reach"> }, words: CiProductWords): ProductPlanReachLock | undefined {
372
+ const reach = loop.plan.reach;
373
+ if (!reach) return undefined;
374
+ if (loop.locks !== "plan") throw new Error("the product plan's reach says what the lock job locks, and there is none without locks: \"plan\"; set locks: \"plan\", or drop reach");
375
+ if (!reach.command.trim()) throw new Error("the product plan's reach.command is empty; give the line that prints the targets a change reaches");
376
+ if (/[\r\n]/.test(reach.command)) throw new Error("the product plan's reach.command is one shell line");
377
+ if (reach.gate !== undefined) {
378
+ // The lock file's name, as ../lifecycle/target-lock.ts takes it.
379
+ if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(reach.gate)) throw new Error(`the product plan's reach.gate ${JSON.stringify(reach.gate)} is not a lock file name: letters, digits, '.', '_' and '-', starting with a letter or digit`);
380
+ }
381
+ const gate = reach.gate !== undefined ? ["--gate", reach.gate] : [];
382
+ const github = forge !== "gitlab";
383
+ const line = github
384
+ ? ["chant", "lock", "--reach", "--pr", '"$PR_NUMBER"', "--head", '"$HEAD_SHA"', "--base", '"$BASE_SHA"', "--stage", "plan", ...gate, "--forge", forge]
385
+ : ["chant", "lock", "--reach", "--open", "--base", '"$CI_COMMIT_SHA"', "--stage", "plan", ...gate, "--forge", "gitlab"];
386
+ const env: Record<string, string> = github
387
+ ? { PR_NUMBER: "${{ github.event.pull_request.number }}", HEAD_SHA: "${{ github.event.pull_request.head.sha }}", BASE_SHA: "${{ github.event.pull_request.base.sha }}", GITHUB_TOKEN: GITHUB_JOB_TOKEN, [LOCK_REACH_ENV]: reach.command }
388
+ : { [LOCK_REACH_ENV]: reach.command };
389
+ const runner = prLoopRunner(loop, "default");
390
+ return { jobName: PR_LOCK_JOB, command: withProductBin(line.join(" "), words.bin), env, ...(runner !== undefined ? { runner } : {}) };
246
391
  }
247
392
 
248
393
  /** The file a product plan job writes its run record to under the hand-off directory, and the Op it is recorded under: `pr-plan`'s (#4899, ../pr-plan-record.ts). */
@@ -275,7 +420,8 @@ export interface ProductPlanJob {
275
420
  noteRunner?: CiRunner;
276
421
  /**
277
422
  * With the pipeline's `evidence` (#4870): the lines that sign the plan
278
- * job's `plan` and `policy` checks from its report, and their variables
423
+ * job's `plan` and `policy` checks from its report (with a target,
424
+ * `plan:<target>` and `policy:<target>`, #4978), and their variables
279
425
  * (the runner key from its secret). GitHub and Forgejo run them in the
280
426
  * note job before `pr-post`; GitLab in a job of their own, `jobName`, in
281
427
  * the target branch's plan notes pipeline before the note job (#4914),
@@ -302,8 +448,12 @@ export interface ProductPlanJob {
302
448
  report?: string;
303
449
  /** The comment re-plan's jobs for this target (#4899). */
304
450
  replan?: ProductPlanReplanJob;
305
- /** The note job's own lines (#4931). */
306
- noteSteps?: { before: string[]; after: string[] };
451
+ /** The note job's own lines (#4931); with `pullRequest` (#4963) they read `PR_NUMBER` and `HEAD_SHA`. */
452
+ noteSteps?: { before: string[]; after: string[]; pullRequest?: true };
453
+ /** The trade before the checkout (#4963), and on GitLab the `id_tokens` it reads (in `idTokens` too). */
454
+ trade?: CloudTradeSpec;
455
+ /** With `previousMarker` (#4963): the note's marker and the product marker's name the read step looks for. */
456
+ previous?: { marker: string; name: string };
307
457
  /** With `record` (#4899): the plan step writes the run record, `env` its op, environment and labels as {@link PLAN_RUN_RECORD_ENV}; the note job's command records it. */
308
458
  record?: { env: Record<string, string> };
309
459
  }
@@ -315,10 +465,9 @@ const NOT_WITH_PLAN: ReadonlyArray<[keyof PrLoopPipelineOptions, string]> = [
315
465
  ["applyBeforeMerge", "the apply before merge runs pr-apply on pr-plan's report"],
316
466
  ["applyOnMerge", "the apply on merge runs on op waves, from the waves spec"],
317
467
  ["waveGate", "the apply on merge runs on op waves, from the waves spec"],
318
- ["locks", "the lock job reads pr-plan's report"],
319
468
  ["previewComment", "the comment preview re-runs pr-plan"],
320
469
  ["staleNotes", "the stale marking names one note per pipeline"],
321
- ["identity", "the identity trade runs before pr-plan's checkout; give the product plan's login (or a target's) instead"],
470
+ ["identity", "the identity trade runs before pr-plan's checkout; give the product plan's trade or login (or a target's) instead"],
322
471
  ["build", "the plan verb builds what it plans"],
323
472
  ["buildCommand", "the plan verb builds what it plans"],
324
473
  ["refresh", "--refresh is a pr-plan flag"],
@@ -344,6 +493,9 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
344
493
  const value = loop[key];
345
494
  if (value !== undefined && value !== false) throw new Error(`the product plan (plan) takes no ${key}: ${why}`);
346
495
  }
496
+ // #4946: GitHub's and Forgejo's product plan writes the lock jobs around the plan verb's PrReport.
497
+ // #4979: GitLab's locks what each open merge request reaches, from the plan notes pipeline, so it needs the reach line.
498
+ if (loop.locks && forge === "gitlab" && !plan.reach) throw new Error("the product plan (plan) takes locks on GitLab only with reach: a merge request's pipeline is built from its own files, so the lock job runs in the target branch's plan notes pipeline and locks what reach prints for each open merge request");
347
499
  // #4899: GitLab's comment commands start the re-plan, so the note-commands job comes with it.
348
500
  if (loop.noteCommands && !plan.replan) throw new Error("the product plan (plan) takes no noteCommands without replan: the note-commands job starts its comment re-plan");
349
501
  if (!plan.command.trim()) throw new Error("the product plan's command is empty; give the product's plan verb");
@@ -367,6 +519,18 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
367
519
  }
368
520
  if (plan.concurrency?.group !== undefined && !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(plan.concurrency.group)) throw new Error(`the product plan's concurrency group ${JSON.stringify(plan.concurrency.group)} is not a name of letters, digits, ., - and _`);
369
521
  const replanComments = plan.replan ? replanCommentsOf(words) : undefined;
522
+ // #4963: what the re-plan does besides the plan command.
523
+ const replanOpts: ProductPlanReplanOptions = typeof plan.replan === "object" ? plan.replan : {};
524
+ const dispatchArg = replanOpts.dispatch ? (typeof replanOpts.dispatch === "object" && replanOpts.dispatch.argument !== undefined ? replanOpts.dispatch.argument : "argument") : undefined;
525
+ if (dispatchArg !== undefined && (dispatchArg === "pr" || !/^[a-z][a-z0-9_-]*$/.test(dispatchArg))) throw new Error(`the product plan's replan.dispatch.argument ${JSON.stringify(dispatchArg)} is not an input name of lowercase letters, digits, - and _ other than pr`);
526
+ const others = typeof replanOpts.reply === "object" ? (replanOpts.reply.others ?? []) : [];
527
+ for (const o of others) {
528
+ if (!o.startsWith(`/${words.product} `) && !o.startsWith(`/${words.product}\t`) && o !== `/${words.product}`) throw new Error(`the product plan's replan.reply.others ${JSON.stringify(o)} is not a /${words.product} comment`);
529
+ if (/['\r\n]/.test(o)) throw new Error(`the product plan's replan.reply.others ${JSON.stringify(o)} holds a quote or a line break`);
530
+ }
531
+ if (plan.previousMarker && !github) throw new Error("the product plan's previousMarker reads the pull request's note before the checkout, with the job's token, and GitLab's plan job holds no token to read a merge request's notes with; leave previousMarker out on GitLab");
532
+ const productMarker = plan.noteWords?.productMarker;
533
+ if (plan.previousMarker && (productMarker === undefined || !PRODUCT_MARKER_NAME.test(productMarker))) throw new Error("the product plan's previousMarker reads the note's product marker, and the note words name none; give noteWords.productMarker");
370
534
  if (plan.noteSteps && !github && ((plan.noteSteps.before?.length ?? 0) > 0 || (plan.noteSteps.after?.length ?? 0) > 0)) {
371
535
  throw new Error("the product plan's noteSteps run in the note job of one pull request, and GitLab's note job posts every open merge request's note in one run (pr-post --open); leave noteSteps out on GitLab");
372
536
  }
@@ -404,17 +568,34 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
404
568
  // The note job reads its own plan job's result, by that job's name.
405
569
  const postEnv: Record<string, string> = github ? { ...post.env, PLAN_RESULT: `\${{ needs.${jobName}.result }}`, ...noteWords } : { ...post.env, ...noteWords };
406
570
  // #4931: the target's login, else the plan's, from the OIDC token file (ci-login, #4788).
407
- const loginSpec = target?.login ?? plan.login;
571
+ // #4963: a target's own login or trade stands in for both of the plan's.
572
+ const own2 = target?.login !== undefined || target?.trade !== undefined;
573
+ const loginSpec = own2 ? target?.login : plan.login;
574
+ const tradeSpec = own2 ? target?.trade : plan.trade;
575
+ if (loginSpec && tradeSpec) throw new Error(`the product plan${name ? `'s target ${name}` : ""} gives both login and trade; the trade leaves no token for a login to read, so give one`);
576
+ if (tradeSpec && tradedClouds(tradeSpec).length === 0) throw new Error(`the product plan${name ? `'s target ${name}` : ""} trades for no identity; give the trade a cloud`);
408
577
  const login = loginSpec ? cloudLogin(forge, loginSpec) : undefined;
578
+ const tradeTokens: Record<string, string> = tradeSpec ? Object.fromEntries(tradedClouds(tradeSpec).map((c) => [idTokenVar(c), tradeSpec[c]!.audience])) : {};
409
579
  const ownTokens = target?.idTokens ?? plan.idTokens;
410
580
  for (const [v, aud] of Object.entries(ownTokens ?? {})) {
411
581
  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(v)) throw new Error(`the product plan's id token ${JSON.stringify(v)} is not a variable name`);
412
582
  if (!aud.trim() || /\s/.test(aud)) throw new Error(`the product plan's id token ${v} names no audience`);
413
583
  if (login && v in login.idTokens && login.idTokens[v] !== aud) throw new Error(`the product plan's id token ${v} is the login's, with another audience`);
584
+ if (v in tradeTokens && tradeTokens[v] !== aud) throw new Error(`the product plan's id token ${v} is the trade's, with another audience`);
414
585
  }
415
- const idTokens = { ...(login?.idTokens ?? {}), ...(ownTokens ?? {}) };
586
+ const idTokens = { ...(login?.idTokens ?? {}), ...tradeTokens, ...(ownTokens ?? {}) };
416
587
  const artifact = plan.artifact ? (name ? `${plan.artifact}-${name}` : plan.artifact) : name ? `chant-pr-plan-${name}` : "chant-pr-plan";
417
- const replan0 = replanComments ? { ...replanJobOf(forge, env, words, name, artifact, noteWords), ...replanComments } : undefined;
588
+ // #4963: on GitHub and Forgejo the first re-plan job replies to the comments no other job takes.
589
+ const replies = github && Boolean(replanOpts.reply) && (targets === undefined || target === targets[0]);
590
+ const replan0 = replanComments
591
+ ? {
592
+ ...replanJobOf(forge, env, words, name, artifact, noteWords, { notAffected: replanOpts.notAffected === true }),
593
+ ...replanComments,
594
+ ...(github && dispatchArg !== undefined ? { dispatch: { argument: dispatchArg } } : {}),
595
+ ...(replies ? { reply: { prefix: `/${words.product}`, others } } : {}),
596
+ ...(replanOpts.notAffected ? { notAffected: true as const } : {}),
597
+ }
598
+ : undefined;
418
599
  const replan = replan0 && plan.record ? { ...replan0, post: { ...replan0.post, command: `${replan0.post.command} --record-run ${replan0.jobName}` } } : replan0;
419
600
  const record = plan.record ? { env: { [PLAN_RUN_RECORD_ENV]: JSON.stringify({ op: PLAN_RUN_OP, env, labels: { Env: env, Pipeline: "pr", Job: "plan", ...(name ? { Target: name } : {}) } }) } } : undefined;
420
601
  const noteBefore = plan.noteSteps?.before ?? [];
@@ -430,7 +611,8 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
430
611
  artifact,
431
612
  ...(planRunner !== undefined ? { runner: planRunner } : {}),
432
613
  ...(noteRunner !== undefined ? { noteRunner } : {}),
433
- ...(evidence ? { evidence: planEvidenceOf(forge, evidence, words, jobName, plan.forks === "skip" ? { noForks: true } : {}) } : {}),
614
+ // #4978: a target's plan job plans that target alone, so its checks are `plan:<target>` and `policy:<target>`.
615
+ ...(evidence ? { evidence: planEvidenceOf(forge, evidence, words, jobName, { ...(plan.forks === "skip" ? { noForks: true } : {}), ...(name ? { member: { name, reportPath: PR_LOOP_REPORT_DIR } } : {}) }) } : {}),
434
616
  ...(Object.keys(jobEnv).length > 0 ? { jobEnv } : {}),
435
617
  ...(login && login.steps.length > 0 ? { login: login.steps } : {}),
436
618
  ...(Object.keys(idTokens).length > 0 ? { idTokens } : {}),
@@ -439,8 +621,10 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
439
621
  ...(plan.setup?.length ? { setup: plan.setup } : {}),
440
622
  ...(plan.report ? { report: fill(plan.report, name) } : {}),
441
623
  ...(replan ? { replan } : {}),
442
- ...(noteBefore.length > 0 || noteAfter.length > 0 ? { noteSteps: { before: noteBefore, after: noteAfter } } : {}),
624
+ ...(noteBefore.length > 0 || noteAfter.length > 0 ? { noteSteps: { before: noteBefore, after: noteAfter, ...(plan.noteSteps?.pullRequest ? { pullRequest: true as const } : {}) } } : {}),
443
625
  ...(record ? { record } : {}),
626
+ ...(tradeSpec ? { trade: tradeSpec } : {}),
627
+ ...(plan.previousMarker && productMarker ? { previous: { marker: prNoteMarker(env, name), name: productMarker } } : {}),
444
628
  };
445
629
  };
446
630
  return targets ? targets.map(one) : [one()];
@@ -455,12 +639,15 @@ function replanCommentsOf(words: CiProductWords): { comments: string[]; gated: A
455
639
  }
456
640
 
457
641
  /** The re-plan's jobs for one target (#4899), its comments filled in by the caller. */
458
- function replanJobOf(forge: ForgeKind, env: string, words: CiProductWords, name: string | undefined, artifact: string, noteWords: Record<string, string>): Omit<ProductPlanReplanJob, "comments" | "gated"> {
642
+ function replanJobOf(forge: ForgeKind, env: string, words: CiProductWords, name: string | undefined, artifact: string, noteWords0: Record<string, string>, opts: { notAffected?: boolean } = {}): Omit<ProductPlanReplanJob, "comments" | "gated"> {
459
643
  const github = forge !== "gitlab";
460
644
  const jobName = github ? (name ? `${REPLAN_JOB}-${name}` : REPLAN_JOB) : name ? `${name}-${REPLAN_JOB}` : REPLAN_JOB;
461
645
  const noteJobName = github ? (name ? `${REPLAN_NOTE_JOB}-${name}` : REPLAN_NOTE_JOB) : name ? `${name}-${REPLAN_NOTE_JOB}` : REPLAN_NOTE_JOB;
462
646
  // pr-post reads the pull request and the head from the re-plan job, never the comment. GitLab's is GitHub's line with its own --forge.
463
- const command = github ? prLoopPostJob(forge, env, name, words).command : prLoopPostJob("github", env, name, words).command.replace(" --forge github ", " --forge gitlab ");
647
+ const command0 = github ? prLoopPostJob(forge, env, name, words).command : prLoopPostJob("github", env, name, words).command.replace(" --forge github ", " --forge gitlab ");
648
+ // #4963: the argument the re-plan was narrowed to, which pr-post answers "not affected" for when the change does not reach it.
649
+ const command = opts.notAffected ? `${command0} --not-affected "$${PLAN_ARGUMENT_ENV}"` : command0;
650
+ const noteWords = opts.notAffected && github ? { ...noteWords0, [PLAN_ARGUMENT_ENV]: `\${{ needs.${jobName}.outputs.argument }}` } : noteWords0;
464
651
  const post = github
465
652
  ? {
466
653
  command,
@@ -519,36 +706,127 @@ export function gitlabReplanCommentIf(replan: Pick<ProductPlanReplanJob, "commen
519
706
  * commenter), whether the commenter can write. It writes `go=1`, `pr`,
520
707
  * `head`, `base` and `argument` to the step's outputs.
521
708
  */
522
- export const REPLAN_DECIDE_JS = [
709
+ export const REPLAN_DECIDE_JS = replanDecideJs();
710
+
711
+ /**
712
+ * The re-plan's decision script (#4899) with what `replan`'s options add
713
+ * (#4963). With neither it is {@link REPLAN_DECIDE_JS}, as before.
714
+ *
715
+ * - `dispatch`: on `workflow_dispatch` the pull request is the `pr` input
716
+ * and the argument the input `CHANT_REPLAN_DISPATCH_ARGUMENT` names;
717
+ * a `pr` that is not a number, or an argument that is not one plain
718
+ * word, fails the job. No permission is asked: only a writer dispatches.
719
+ * - `reply`: a comment that starts with `CHANT_REPLAN_PRODUCT` and is not
720
+ * the plan command, nor one of `CHANT_REPLAN_OTHERS`, a target that is
721
+ * none of the plan's, and a fork's pull request with `forks: "skip"`
722
+ * get a reply comment with the reason, once the commenter's permission
723
+ * is known (Forgejo). A dispatch's reason goes to the log alone.
724
+ */
725
+ export function replanDecideJs(opts: { dispatch?: boolean; reply?: boolean } = {}): string {
726
+ const { dispatch = false, reply = false } = opts;
727
+ const replyLine = reply
728
+ ? [
729
+ // The reply, as the product: on a dispatch the log alone.
730
+ `const post=async(t)=>{say(t);${dispatch ? "if(dispatch)return;" : ""}const r=await fetch(api+"/repos/"+repo+"/issues/"+n+"/comments",{method:"POST",headers:{authorization:"token "+process.env.CHANT_REPLAN_TOKEN,accept:"application/json","content-type":"application/json"},body:JSON.stringify({body:product.slice(1)+": "+t})});if(!r.ok)console.error("chant: the reply was not posted: the forge answered "+r.status)};`,
731
+ ]
732
+ : [];
733
+ return [
734
+ 'const fs=require("fs");',
735
+ 'const say=(m)=>console.log("chant: "+m);',
736
+ 'const out=(k,v)=>fs.appendFileSync(process.env.GITHUB_OUTPUT,k+"="+v+"\\n");',
737
+ "let e;try{e=JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH,\"utf8\"))}catch{say(\"the event file does not read, so nothing is planned again\");process.exit(0)}",
738
+ ...(dispatch ? ['const dispatch=process.env.GITHUB_EVENT_NAME==="workflow_dispatch",inputs=e.inputs&&typeof e.inputs==="object"?e.inputs:{};'] : []),
739
+ 'const body=String((e.comment&&e.comment.body)||"").trim();',
740
+ 'const cmds=JSON.parse(process.env.CHANT_REPLAN_COMMANDS||"[]");',
741
+ 'for(const g of JSON.parse(process.env.CHANT_REPLAN_GATED||"[]")){const v=process.env[g.when]||"";if(v&&v!=="0"&&v!=="false")cmds.push(g.comment)}',
742
+ "let arg;",
743
+ ...(reply ? ['let refusal;const product=process.env.CHANT_REPLAN_PRODUCT||"",others=JSON.parse(process.env.CHANT_REPLAN_OTHERS||"[]");const says=(c)=>body===c||body.startsWith(c+" ")||body.startsWith(c+"\\t");'] : []),
744
+ ...(dispatch
745
+ ? [
746
+ 'if(dispatch){const pv=String(inputs.pr==null?"":inputs.pr).trim();if(!pv){say("the dispatch names no pull request");process.exit(0)}if(!/^[1-9][0-9]{0,9}$/.test(pv)){console.error("chant: the dispatch\\u0027s pr input is a pull request number, like 42");process.exit(1)}',
747
+ 'const k=process.env.CHANT_REPLAN_DISPATCH_ARGUMENT||"argument",a=String(inputs[k]==null?"":inputs[k]).trim();if(a&&!/^[A-Za-z0-9_.\\/@+=,:-]+$/.test(a)){console.error("chant: the dispatch\\u0027s "+k+" input is one word of letters, digits and _./@+=,:-");process.exit(1)}arg=a}else ',
748
+ ]
749
+ : []),
750
+ 'for(const c of cmds){if(body===c){arg="";break}if(body.startsWith(c+" ")){const r=body.slice(c.length).trim();if(/^[A-Za-z0-9_.\\/@+=,:-]+$/.test(r)){arg=r;break}}}',
751
+ reply
752
+ ? 'if(arg===undefined){if(product&&says(product)&&!others.some(says)){refusal="the commands are "+cmds.concat(others).map((c)=>"`"+c+"`").join(", ")}else{say("the comment asks for no plan");process.exit(0)}}'
753
+ : 'if(arg===undefined){say("the comment asks for no plan");process.exit(0)}',
754
+ 'const target=process.env.CHANT_REPLAN_TARGET||"",targets=JSON.parse(process.env.CHANT_REPLAN_TARGETS||"[]");',
755
+ reply
756
+ ? 'if(targets.length&&arg&&!targets.includes(arg)){refusal=arg+" is none of "+targets.join(", ")+", so nothing is planned again";arg=""}'
757
+ : 'if(targets.length&&arg&&!targets.includes(arg)){say(arg+" is none of "+targets.join(", ")+", so nothing is planned again");process.exit(0)}',
758
+ 'if(targets.length&&arg&&arg!==target){say("the comment plans "+arg+" again, not "+target);process.exit(0)}',
759
+ dispatch
760
+ ? 'const n=dispatch?Number(String(inputs.pr).trim()):e.issue&&e.issue.number;if(!dispatch&&(!Number.isInteger(n)||!(e.issue.pull_request||e.is_pull))){say("the comment is not on a pull request");process.exit(0)}'
761
+ : 'const n=e.issue&&e.issue.number;if(!Number.isInteger(n)||!(e.issue.pull_request||e.is_pull)){say("the comment is not on a pull request");process.exit(0)}',
762
+ 'const api=String(process.env.GITHUB_API_URL||"").replace(/\\/+$/,""),repo=process.env.GITHUB_REPOSITORY;',
763
+ 'const get=async(p)=>{const r=await fetch(api+"/repos/"+repo+p,{headers:{authorization:"token "+process.env.CHANT_REPLAN_TOKEN,accept:"application/json"}});if(!r.ok)throw new Error(p+" answered "+r.status);return r.json()};',
764
+ ...replyLine,
765
+ "(async()=>{",
766
+ ...(reply
767
+ ? [
768
+ // Who asked comes first: a commenter who cannot write gets no reply.
769
+ `if(process.env.CHANT_REPLAN_PERMISSION${dispatch ? "&&!dispatch" : ""}){const who=e.comment&&e.comment.user&&e.comment.user.login;const p=who?await get("/collaborators/"+encodeURIComponent(who)+"/permission"):{};`,
770
+ 'if(!["owner","admin","maintain","write"].includes(p.permission)){say((who||"the commenter")+" cannot write to "+repo+", so nothing is planned again");return}}',
771
+ "if(refusal){await post(refusal);return}",
772
+ 'const pr=await get("/pulls/"+n);',
773
+ 'if(pr.state!=="open"){say("pull request "+n+" is not open, so it is not planned again");return}',
774
+ 'const same=Boolean(pr.head&&pr.head.repo&&pr.head.repo.full_name===repo);',
775
+ 'if(!same&&process.env.CHANT_REPLAN_FORKS==="skip"){await post("pull request "+n+" is from a fork, and its code never runs with this repository\\u0027s credentials, so it is not planned again");return}',
776
+ ]
777
+ : [
778
+ 'const pr=await get("/pulls/"+n);',
779
+ 'if(pr.state!=="open"){say("pull request "+n+" is not open, so it is not planned again");return}',
780
+ 'const same=Boolean(pr.head&&pr.head.repo&&pr.head.repo.full_name===repo);',
781
+ 'if(!same&&process.env.CHANT_REPLAN_FORKS==="skip"){say("pull request "+n+" is from a fork, and its code never runs with this repository\\u0027s credentials");return}',
782
+ `if(process.env.CHANT_REPLAN_PERMISSION${dispatch ? "&&!dispatch" : ""}){const who=e.comment&&e.comment.user&&e.comment.user.login;const p=who?await get("/collaborators/"+encodeURIComponent(who)+"/permission"):{};`,
783
+ 'if(!["owner","admin","maintain","write"].includes(p.permission)){say((who||"the commenter")+" cannot write to "+repo+", so nothing is planned again");return}}',
784
+ ]),
785
+ 'const sha=/^[0-9a-f]{40}$/;if(!sha.test(String(pr.head&&pr.head.sha))||!sha.test(String(pr.base&&pr.base.sha)))throw new Error("the pull request names no head or base commit");',
786
+ 'out("go","1");out("pr",String(n));out("head",pr.head.sha);out("base",pr.base.sha);out("argument",arg);',
787
+ 'say("planning pull request "+n+" again at "+pr.head.sha.slice(0,12)+(arg?" for "+arg:""))',
788
+ '})().catch((err)=>{console.error("chant: the re-plan could not decide: "+(err&&err.message?err.message:String(err)));process.exit(1)});',
789
+ ].join("");
790
+ }
791
+
792
+ /**
793
+ * The previous note's read step on GitHub and Forgejo (#4963): `node -e`,
794
+ * from `/`, with the job's token in `CHANT_PREVIOUS_TOKEN` alone. It pages
795
+ * through pull request `CHANT_PREVIOUS_PR`'s comments for the one whose
796
+ * first line is `CHANT_PREVIOUS_NOTE` (chant's marker), takes its second
797
+ * line's body when it is `<!-- <CHANT_PREVIOUS_NAME> <body> -->` and the
798
+ * body is plain words, and appends `CHANT_PLAN_PREVIOUS_MARKER=<body>` to
799
+ * `$GITHUB_ENV`, empty when there is none. A forge that refuses is a
800
+ * warning: the plan verb plans without it.
801
+ */
802
+ export const PREVIOUS_MARKER_JS = [
523
803
  'const fs=require("fs");',
524
- 'const say=(m)=>console.log("chant: "+m);',
525
- 'const out=(k,v)=>fs.appendFileSync(process.env.GITHUB_OUTPUT,k+"="+v+"\\n");',
526
- "let e;try{e=JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH,\"utf8\"))}catch{say(\"the event file does not read, so nothing is planned again\");process.exit(0)}",
527
- 'const body=String((e.comment&&e.comment.body)||"").trim();',
528
- 'const cmds=JSON.parse(process.env.CHANT_REPLAN_COMMANDS||"[]");',
529
- 'for(const g of JSON.parse(process.env.CHANT_REPLAN_GATED||"[]")){const v=process.env[g.when]||"";if(v&&v!=="0"&&v!=="false")cmds.push(g.comment)}',
530
- "let arg;",
531
- 'for(const c of cmds){if(body===c){arg="";break}if(body.startsWith(c+" ")){const r=body.slice(c.length).trim();if(/^[A-Za-z0-9_.\\/@+=,:-]+$/.test(r)){arg=r;break}}}',
532
- 'if(arg===undefined){say("the comment asks for no plan");process.exit(0)}',
533
- 'const target=process.env.CHANT_REPLAN_TARGET||"",targets=JSON.parse(process.env.CHANT_REPLAN_TARGETS||"[]");',
534
- 'if(targets.length&&arg&&!targets.includes(arg)){say(arg+" is none of "+targets.join(", ")+", so nothing is planned again");process.exit(0)}',
535
- 'if(targets.length&&arg&&arg!==target){say("the comment plans "+arg+" again, not "+target);process.exit(0)}',
536
- 'const n=e.issue&&e.issue.number;if(!Number.isInteger(n)||!(e.issue.pull_request||e.is_pull)){say("the comment is not on a pull request");process.exit(0)}',
537
- 'const api=String(process.env.GITHUB_API_URL||"").replace(/\\/+$/,""),repo=process.env.GITHUB_REPOSITORY;',
538
- 'const get=async(p)=>{const r=await fetch(api+"/repos/"+repo+p,{headers:{authorization:"token "+process.env.CHANT_REPLAN_TOKEN,accept:"application/json"}});if(!r.ok)throw new Error(p+" answered "+r.status);return r.json()};',
804
+ 'const api=String(process.env.GITHUB_API_URL||"").replace(/\\/+$/,""),repo=process.env.GITHUB_REPOSITORY,n=process.env.CHANT_PREVIOUS_PR||"";',
805
+ 'const note=process.env.CHANT_PREVIOUS_NOTE||"",name=process.env.CHANT_PREVIOUS_NAME||"";',
806
+ 'const put=(v)=>fs.appendFileSync(process.env.GITHUB_ENV,"CHANT_PLAN_PREVIOUS_MARKER="+v+"\\n");',
807
+ 'const esc=(s)=>s.replace(/[.*+?^${}()|[\\]\\\\]/g,"\\\\$&");',
808
+ 'const own=new RegExp("^<!-- "+esc(name)+"(?: ([A-Za-z0-9_.,\\\\/@+=:-]+(?: [A-Za-z0-9_.,\\\\/@+=:-]+)*))? -->$");',
809
+ 'if(!/^[0-9]+$/.test(n)){console.log("chant: no pull request to read the previous note of");put("");process.exit(0)}',
539
810
  "(async()=>{",
540
- 'const pr=await get("/pulls/"+n);',
541
- 'if(pr.state!=="open"){say("pull request "+n+" is not open, so it is not planned again");return}',
542
- 'const same=Boolean(pr.head&&pr.head.repo&&pr.head.repo.full_name===repo);',
543
- 'if(!same&&process.env.CHANT_REPLAN_FORKS==="skip"){say("pull request "+n+" is from a fork, and its code never runs with this repository\\u0027s credentials");return}',
544
- 'if(process.env.CHANT_REPLAN_PERMISSION){const who=e.comment&&e.comment.user&&e.comment.user.login;const p=who?await get("/collaborators/"+encodeURIComponent(who)+"/permission"):{};',
545
- 'if(!["owner","admin","maintain","write"].includes(p.permission)){say((who||"the commenter")+" cannot write to "+repo+", so nothing is planned again");return}}',
546
- 'const sha=/^[0-9a-f]{40}$/;if(!sha.test(String(pr.head&&pr.head.sha))||!sha.test(String(pr.base&&pr.base.sha)))throw new Error("the pull request names no head or base commit");',
547
- 'out("go","1");out("pr",String(n));out("head",pr.head.sha);out("base",pr.base.sha);out("argument",arg);',
548
- 'say("planning pull request "+n+" again at "+pr.head.sha.slice(0,12)+(arg?" for "+arg:""))',
549
- '})().catch((err)=>{console.error("chant: the re-plan could not decide: "+(err&&err.message?err.message:String(err)));process.exit(1)});',
811
+ "for(let page=1;page<=50;page++){",
812
+ 'const r=await fetch(api+"/repos/"+repo+"/issues/"+n+"/comments?per_page=100&limit=50&page="+page,{headers:{authorization:"token "+process.env.CHANT_PREVIOUS_TOKEN,accept:"application/json"}});',
813
+ 'if(!r.ok)throw new Error("the forge answered "+r.status);',
814
+ "const list=await r.json();if(!Array.isArray(list)||list.length===0)break;",
815
+ 'for(const c of list){const lines=String(c&&c.body||"").replace(/\\r\\n/g,"\\n").split("\\n");if(lines[0]!==note)continue;const m=own.exec(lines[1]||"");const v=m&&m[1]&&m[1].length<=4096?m[1]:"";put(v);console.log("chant: the previous note"+(v?" carries "+name:" carries no "+name));return}',
816
+ "}",
817
+ 'put("");console.log("chant: the pull request has no note yet")',
818
+ '})().catch((err)=>{put("");console.log("chant: the previous note was not read: "+(err&&err.message?err.message:String(err)))});',
550
819
  ].join("");
551
820
 
821
+ /** The GitLab re-plan's lines that set {@link PLAN_ARGUMENT_ENV} from the comment's one word after the command (#4899), which the rule already held to plain characters. */
822
+ export function gitlabReplanArgumentLines(replan: Pick<ProductPlanReplanJob, "comments" | "gated">): string[] {
823
+ const byLength = [...replan.comments, ...replan.gated.map((g) => g.comment)].sort((a, b) => b.length - a.length);
824
+ return [
825
+ `case "$${GITLAB_REPLAN_COMMENT_VAR}" in ${byLength.map((c) => `"${c}"*) chant_rest="\${${GITLAB_REPLAN_COMMENT_VAR}#"${c}"}" ;;`).join(" ")} *) chant_rest="" ;; esac`,
826
+ `${PLAN_ARGUMENT_ENV}="$(printf '%s' "$chant_rest" | tr -d ' ')" && export ${PLAN_ARGUMENT_ENV}`,
827
+ ];
828
+ }
829
+
552
830
  /**
553
831
  * The pending step's script on GitHub and Forgejo (#4899): `node -e`, from
554
832
  * `/`, posting the plan status pending at `CHANT_PENDING_SHA` with the token
@@ -600,25 +878,33 @@ export const PLAN_RECORD_JS = [
600
878
  `fs.mkdirSync(dir,{recursive:true});fs.writeFileSync(path.join(dir,"${PLAN_RUN_RECORD_FILE}"),JSON.stringify(rec)+"\\n");`,
601
879
  ].join("");
602
880
 
603
- /** The evidence step of one plan job (#4870), as {@link ProductPlanJob.evidence}. */
604
- export function planEvidenceOf(forge: ForgeKind, evidence: PipelineEvidence, words: CiProductWords, planJob: string, opts: { noForks?: boolean } = {}): NonNullable<ProductPlanJob["evidence"]> {
881
+ /**
882
+ * The evidence step of one plan job (#4870), as {@link ProductPlanJob.evidence}.
883
+ * #4964: for a workspace member's pipeline (`member`) the checks are signed
884
+ * as `plan:<member>` and `policy:<member>` (`--member`), and on GitLab the
885
+ * report is read from the plan job's artifact at the member's `reportPath`.
886
+ * #4978: a product plan target's plan job is signed the same way, under the
887
+ * target's name.
888
+ */
889
+ export function planEvidenceOf(forge: ForgeKind, evidence: PipelineEvidence, words: CiProductWords, planJob: string, opts: { noForks?: boolean; member?: { name: string; reportPath: string } } = {}): NonNullable<ProductPlanJob["evidence"]> {
605
890
  assertPipelineEvidence(evidence);
606
891
  const key = evidenceKeyEnv(forge, evidence);
607
892
  const bin = words.bin;
893
+ const member = opts.member ? { member: opts.member.name } : {};
608
894
  if (forge === "gitlab") {
609
895
  // #4914: the job runs in the target branch's plan notes pipeline, before the note job, and signs every open
610
896
  // merge request's settled plan job from its artifact; no job of a merge request pipeline holds the key.
611
897
  const dir = gitlabOpenEvidenceDir(planJob);
612
898
  return {
613
899
  jobName: `${planJob}-evidence`,
614
- lines: openEvidenceLines({ job: planJob, dir: PR_LOOP_REPORT_DIR, out: dir, ...(bin ? { bin } : {}), ...(opts.noForks ? { noForks: true } : {}) }),
900
+ lines: openEvidenceLines({ job: planJob, dir: opts.member?.reportPath ?? PR_LOOP_REPORT_DIR, out: dir, ...(bin ? { bin } : {}), ...(opts.noForks ? { noForks: true } : {}), ...member }),
615
901
  env: key,
616
902
  dir,
617
903
  ...(evidenceKeyless(evidence) ? { idTokens: evidenceIdTokens(evidence) } : {}),
618
904
  };
619
905
  }
620
906
  return {
621
- lines: planEvidenceLines({ dir: PR_LOOP_REPORT_DIR, at: '"$HEAD_SHA"', base: '"$BASE_SHA"', result: '"$PLAN_RESULT"', ...(bin ? { bin } : {}) }),
907
+ lines: planEvidenceLines({ dir: PR_LOOP_REPORT_DIR, at: '"$HEAD_SHA"', base: '"$BASE_SHA"', result: '"$PLAN_RESULT"', ...(bin ? { bin } : {}), ...member }),
622
908
  env: { HEAD_SHA: "${{ github.sha }}", BASE_SHA: "${{ github.event.pull_request.base.sha }}", PLAN_RESULT: `\${{ needs.${planJob}.result }}`, ...key },
623
909
  ...(evidenceKeyless(evidence) ? { idToken: true as const } : {}),
624
910
  };
@@ -618,4 +618,24 @@ describe("one lexicon's section of lifecycle diff --live --json (#4896)", () =>
618
618
  expect(statusOf(lexiconDriftRecords({ ...base, section: { resources } }))["app.events"]).toBe("pending");
619
619
  expect(lexiconDriftRecords({ ...base, section: { deep } })).toEqual([]);
620
620
  });
621
+
622
+ test("a deep read's pending changes are drift on the entities behind them (#4944)", () => {
623
+ const withPending = {
624
+ ...deep,
625
+ pending: [
626
+ { subject: "column app.orders.note", change: "drop column note text, which the declaration does not have", entities: ["app.orders"] },
627
+ { subject: "column app.users.legacy", change: "drop column legacy text, which the declaration does not have", entities: ["app.users"] },
628
+ { subject: "grants app", change: "REVOKE INSERT ON `shop`.`events` FROM `app`" },
629
+ ],
630
+ } as DeepDiffResult;
631
+ const records = lexiconDriftRecords({ ...base, section: { resources, deep: withPending, absent: "missing" } });
632
+ expect(statusOf(records)).toEqual({ "app.audit": "not-observed", "app.events": "missing", "app.orders": "drifted", "app.users": "drifted", "grants app": "drifted" });
633
+ expect(records.find((r) => r.address === "app.orders")!.attributes).toEqual([{ path: "column app.orders.note", after: "drop column note text, which the declaration does not have" }]);
634
+ expect(records.find((r) => r.address === "app.users")!.attributes).toEqual([
635
+ { path: "column app.users.legacy", after: "drop column legacy text, which the declaration does not have" },
636
+ { path: "columns[1].type", before: "int", after: "bigint" },
637
+ ]);
638
+ expect(records.find((r) => r.address === "grants app")!.attributes).toEqual([{ path: "grants app", after: "REVOKE INSERT ON `shop`.`events` FROM `app`" }]);
639
+ roundTrip(records);
640
+ });
621
641
  });
@@ -1081,6 +1081,13 @@ export interface DeepDiffDriftInput extends DriftAdapterBase {
1081
1081
  * `undeclaredEntities` undeclared. Accepted and held paths are not drift and
1082
1082
  * are left out. To lay these over the thin read's records, so a deep hole
1083
1083
  * stays on the attribute surface, use {@link mergeDeepDrift}.
1084
+ *
1085
+ * A pending change (`pending`: a privilege granted by hand, a column the
1086
+ * declaration does not have) is drift too (#4944), as `lifecycle diff
1087
+ * --live` counts it: an attribute on each entity behind it, its path the
1088
+ * change's subject and its after what an apply would do, the entity's record
1089
+ * drifted unless it is not-observed. A pending change that names no entity
1090
+ * is a drifted record of its own, addressed by its subject.
1084
1091
  */
1085
1092
  export function deepDiffDriftRecords(input: DeepDiffDriftInput): DriftRecord[] {
1086
1093
  const { diff } = input;
@@ -1107,6 +1114,15 @@ export function deepDiffDriftRecords(input: DeepDiffDriftInput): DriftRecord[] {
1107
1114
  })),
1108
1115
  });
1109
1116
  }
1117
+ for (const p of diff.pending ?? []) {
1118
+ const attribute: DriftAttribute = { path: p.subject, after: p.change };
1119
+ for (const name of p.entities && p.entities.length > 0 ? p.entities : [p.subject]) {
1120
+ const had = out.get(name);
1121
+ if (had?.status === "not-observed") continue;
1122
+ if (had) out.set(name, driftRecord({ ...had, status: "drifted", attributes: [...(had.attributes ?? []), attribute] }));
1123
+ else put(name, { status: "drifted", attributes: [attribute] });
1124
+ }
1125
+ }
1110
1126
  for (const name of diff.undeclaredEntities ?? []) put(name, { status: "undeclared" });
1111
1127
  for (const name of diff.unchanged ?? []) put(name, { status: "in-sync" });
1112
1128
  return [...out.values()].sort((a, b) => byString(a.address, b.address));