@intentius/chant 0.124.89 → 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 (163) hide show
  1. package/dist/ci-comment-commands.d.ts +18 -2
  2. package/dist/ci-comment-commands.d.ts.map +1 -1
  3. package/dist/ci-comment-commands.js +30 -2
  4. package/dist/ci-job-guard.d.ts +42 -45
  5. package/dist/ci-job-guard.d.ts.map +1 -1
  6. package/dist/ci-job-guard.js +206 -3
  7. package/dist/ci-note-commands.d.ts +41 -1
  8. package/dist/ci-note-commands.d.ts.map +1 -1
  9. package/dist/ci-note-commands.js +64 -5
  10. package/dist/ci-product.d.ts +41 -1
  11. package/dist/ci-product.d.ts.map +1 -1
  12. package/dist/ci-product.js +44 -7
  13. package/dist/cli/handlers/pr-comment.d.ts +13 -1
  14. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  15. package/dist/cli/handlers/pr-comment.js +90 -1
  16. package/dist/cli/handlers/pr-notes.d.ts.map +1 -1
  17. package/dist/cli/handlers/pr-notes.js +23 -1
  18. package/dist/cli/handlers/pr.js +16 -14
  19. package/dist/cli/handlers/run-wave.d.ts.map +1 -1
  20. package/dist/cli/handlers/run-wave.js +154 -4
  21. package/dist/cli/main.d.ts.map +1 -1
  22. package/dist/cli/main.js +17 -0
  23. package/dist/cli/parse-args.d.ts.map +1 -1
  24. package/dist/cli/parse-args.js +15 -0
  25. package/dist/cli/registry.d.ts +8 -1
  26. package/dist/cli/registry.d.ts.map +1 -1
  27. package/dist/components/pr-checks.d.ts +28 -1
  28. package/dist/components/pr-checks.d.ts.map +1 -1
  29. package/dist/components/pr-checks.js +35 -2
  30. package/dist/components/pr-pipeline.d.ts +3 -2
  31. package/dist/components/pr-pipeline.d.ts.map +1 -1
  32. package/dist/components/pr-pipeline.js +4 -2
  33. package/dist/components/product-pipeline.d.ts +54 -2
  34. package/dist/components/product-pipeline.d.ts.map +1 -1
  35. package/dist/components/product-pipeline.js +59 -5
  36. package/dist/components/product-plan.d.ts +13 -1
  37. package/dist/components/product-plan.d.ts.map +1 -1
  38. package/dist/components/product-plan.js +36 -10
  39. package/dist/floor-table.data.d.ts.map +1 -1
  40. package/dist/floor-table.data.js +32 -23
  41. package/dist/lexicon.d.ts +82 -4
  42. package/dist/lexicon.d.ts.map +1 -1
  43. package/dist/lifecycle/gate-applied.d.ts +9 -0
  44. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  45. package/dist/op/apply-status.d.ts +84 -0
  46. package/dist/op/apply-status.d.ts.map +1 -0
  47. package/dist/op/apply-status.js +106 -0
  48. package/dist/op/before-merge-decide.d.ts +102 -0
  49. package/dist/op/before-merge-decide.d.ts.map +1 -0
  50. package/dist/op/before-merge-decide.js +142 -0
  51. package/dist/op/before-merge-done.d.ts +56 -0
  52. package/dist/op/before-merge-done.d.ts.map +1 -0
  53. package/dist/op/before-merge-done.js +69 -0
  54. package/dist/op/before-merge-store.d.ts +20 -0
  55. package/dist/op/before-merge-store.d.ts.map +1 -0
  56. package/dist/op/before-merge-store.js +48 -0
  57. package/dist/op/before-merge.d.ts +150 -0
  58. package/dist/op/before-merge.d.ts.map +1 -0
  59. package/dist/op/before-merge.js +207 -0
  60. package/dist/op/follow-on-run.d.ts +117 -0
  61. package/dist/op/follow-on-run.d.ts.map +1 -0
  62. package/dist/op/follow-on-run.js +154 -0
  63. package/dist/op/follow-on-store.d.ts +17 -0
  64. package/dist/op/follow-on-store.d.ts.map +1 -0
  65. package/dist/op/follow-on-store.js +54 -0
  66. package/dist/op/gate.d.ts +6 -0
  67. package/dist/op/gate.d.ts.map +1 -1
  68. package/dist/op/gate.js +10 -1
  69. package/dist/op/index.d.ts +3 -1
  70. package/dist/op/index.d.ts.map +1 -1
  71. package/dist/op/index.js +1 -0
  72. package/dist/op/op-waves-after-plan.d.ts +13 -0
  73. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  74. package/dist/op/op-waves-evidence-jobs.d.ts +4 -1
  75. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  76. package/dist/op/op-waves-evidence-jobs.js +10 -2
  77. package/dist/op/op-waves-follow-on.d.ts +162 -0
  78. package/dist/op/op-waves-follow-on.d.ts.map +1 -0
  79. package/dist/op/op-waves-follow-on.js +355 -0
  80. package/dist/op/op-waves-run.d.ts +146 -6
  81. package/dist/op/op-waves-run.d.ts.map +1 -1
  82. package/dist/op/op-waves-run.js +871 -99
  83. package/dist/op/op-waves-split.d.ts +122 -0
  84. package/dist/op/op-waves-split.d.ts.map +1 -0
  85. package/dist/op/op-waves-split.js +166 -0
  86. package/dist/op/op-waves.d.ts +20 -0
  87. package/dist/op/op-waves.d.ts.map +1 -1
  88. package/dist/op/op-waves.js +15 -1
  89. package/dist/op/schedule-overdue.d.ts +15 -1
  90. package/dist/op/schedule-overdue.d.ts.map +1 -1
  91. package/dist/op/schedule-overdue.js +18 -2
  92. package/dist/op/stage-hooks.d.ts +36 -1
  93. package/dist/op/stage-hooks.d.ts.map +1 -1
  94. package/dist/op/stage-hooks.js +17 -3
  95. package/dist/op/wave-stop.d.ts +4 -1
  96. package/dist/op/wave-stop.d.ts.map +1 -1
  97. package/dist/op/wave-stop.js +4 -2
  98. package/dist/pr-post.d.ts.map +1 -1
  99. package/dist/pr-post.js +2 -1
  100. package/dist/release-floors.d.ts +3 -1
  101. package/dist/release-floors.d.ts.map +1 -1
  102. package/dist/release-floors.js +21 -19
  103. package/dist/wave-blocked.d.ts +7 -1
  104. package/dist/wave-blocked.d.ts.map +1 -1
  105. package/dist/wave-blocked.js +7 -2
  106. package/dist/wave-runtime.mjs +364 -351
  107. package/package.json +1 -1
  108. package/src/ci-comment-commands.test.ts +63 -0
  109. package/src/ci-comment-commands.ts +43 -4
  110. package/src/ci-image.test.ts +1 -2
  111. package/src/ci-job-guard.before-merge.test.ts +148 -0
  112. package/src/ci-job-guard.follow-on-record.test.ts +137 -0
  113. package/src/ci-job-guard.follow-on.test.ts +144 -0
  114. package/src/ci-job-guard.ts +221 -3
  115. package/src/ci-note-commands.test.ts +76 -1
  116. package/src/ci-note-commands.ts +96 -7
  117. package/src/ci-product.ts +55 -7
  118. package/src/cli/handlers/pr-comment.ts +85 -2
  119. package/src/cli/handlers/pr-notes.ts +30 -6
  120. package/src/cli/handlers/pr.ts +14 -11
  121. package/src/cli/handlers/run-wave.ts +144 -4
  122. package/src/cli/main.ts +17 -0
  123. package/src/cli/parse-args.ts +11 -0
  124. package/src/cli/registry.ts +8 -1
  125. package/src/components/pr-checks.ts +55 -2
  126. package/src/components/pr-pipeline.ts +5 -3
  127. package/src/components/product-pipeline.apply-status.test.ts +50 -0
  128. package/src/components/product-pipeline.ts +113 -8
  129. package/src/components/product-plan.test.ts +23 -5
  130. package/src/components/product-plan.ts +43 -12
  131. package/src/floor-table.data.ts +32 -23
  132. package/src/lexicon.ts +78 -1
  133. package/src/lifecycle/gate-applied.ts +7 -0
  134. package/src/op/apply-status.test.ts +83 -0
  135. package/src/op/apply-status.ts +132 -0
  136. package/src/op/before-merge-decide.ts +190 -0
  137. package/src/op/before-merge-done.ts +99 -0
  138. package/src/op/before-merge-store.ts +44 -0
  139. package/src/op/before-merge.test.ts +201 -0
  140. package/src/op/before-merge.ts +266 -0
  141. package/src/op/follow-on-run.ts +206 -0
  142. package/src/op/follow-on-store.ts +54 -0
  143. package/src/op/gate.ts +16 -1
  144. package/src/op/index.ts +5 -0
  145. package/src/op/op-waves-after-plan.ts +13 -0
  146. package/src/op/op-waves-evidence-jobs.ts +11 -3
  147. package/src/op/op-waves-follow-on-record.test.ts +152 -0
  148. package/src/op/op-waves-follow-on.test.ts +247 -0
  149. package/src/op/op-waves-follow-on.ts +385 -0
  150. package/src/op/op-waves-render-spec.test.ts +1 -2
  151. package/src/op/op-waves-run.ts +971 -93
  152. package/src/op/op-waves-split-product.test.ts +288 -0
  153. package/src/op/op-waves-split-step.test.ts +298 -0
  154. package/src/op/op-waves-split.test.ts +196 -0
  155. package/src/op/op-waves-split.ts +189 -0
  156. package/src/op/op-waves.ts +28 -3
  157. package/src/op/schedule-overdue.test.ts +29 -1
  158. package/src/op/schedule-overdue.ts +27 -3
  159. package/src/op/stage-hooks.ts +52 -4
  160. package/src/op/wave-stop.ts +5 -3
  161. package/src/pr-post.ts +2 -1
  162. package/src/release-floors.ts +22 -19
  163. package/src/wave-blocked.ts +9 -4
@@ -42,6 +42,10 @@
42
42
  * variables, lines and report directory come with `PrCheckJobOptions`, and
43
43
  * a product's own workflow renders the jobs through the lexicons'
44
44
  * `productCheckJobs`.
45
+ *
46
+ * #4988: on GitLab the check job keeps a product's own files beside the
47
+ * report (`artifacts: { paths, reports }`), such as a lint hook's code
48
+ * quality report, so a product's lint job can move onto chant's.
45
49
  */
46
50
 
47
51
  import type { ForgeKind } from "../pr-forge";
@@ -95,6 +99,28 @@ export interface PrCheckJobOptions {
95
99
  dir?: string;
96
100
  /** Arguments after `--base` (and `--output`), each one word, quoted where the shell needs it: `--summary <file>` and the targets a `perRun` hook runs for. */
97
101
  args?: string[];
102
+ /**
103
+ * GitLab only (#4988): files the check job keeps beside its report, such
104
+ * as a hook's code quality report. See {@link PrCheckArtifacts}.
105
+ */
106
+ artifacts?: PrCheckArtifacts;
107
+ }
108
+
109
+ /**
110
+ * What a GitLab check job keeps besides its report directory (#4988),
111
+ * relative to the job's directory as `dir` is: `paths`, more files or
112
+ * directories for `artifacts:paths`, and `reports`, GitLab's
113
+ * `artifacts:reports` by report type, such as `{ codequality:
114
+ * "gl-code-quality-report.json" }`, so a merge request shows a hook's
115
+ * findings. Kept when the check fails too, as the report is.
116
+ *
117
+ * GitHub and Forgejo take none: the check step is the job's last step
118
+ * (#4295), so no upload step can follow it, and a hook there shows its
119
+ * findings as annotations in the log (`--format forge`).
120
+ */
121
+ export interface PrCheckArtifacts {
122
+ paths?: string[];
123
+ reports?: Record<string, string | string[]>;
98
124
  }
99
125
 
100
126
  /** One shell word: as it is when it needs no quoting, else in single quotes. */
@@ -115,6 +141,8 @@ export interface PrCheckJob {
115
141
  services?: PrCheckService[];
116
142
  /** The lines before the command (#4964). */
117
143
  before?: string[];
144
+ /** GitLab: the files kept beside the report (#4988). */
145
+ artifacts?: PrCheckArtifacts;
118
146
  /**
119
147
  * With `evidence`: the signing job's lines and variables. GitHub and
120
148
  * Forgejo run them in `check-evidence` after taking the report back;
@@ -130,9 +158,32 @@ export interface PrCheckJob {
130
158
  /** The variables a check job's own `env` may not set: the ones the job and its handover read, and the credentials it drops. */
131
159
  const CHECK_RESERVED_ENV = /^(BASE_SHA|HEAD_SHA|CHECK_RESULT|CHANT_RUNNER_KEY|CHANT_RUNNER_IDENTITY|CHANT_LOCAL_EVIDENCE_KEY|CHANT_CHECKOUT_TOKEN|GITHUB_TOKEN|GH_TOKEN|FORGEJO_TOKEN|GITLAB_TOKEN|CI_JOB_TOKEN|CHANT_FORGE_TOKEN|ACTIONS_ID_TOKEN_REQUEST_(URL|TOKEN))$/;
132
160
 
161
+ /** A relative path inside the checkout: no leading `/`, no `..`, and with `glob` GitLab's `*` wildcards. */
162
+ function insideCheckout(path: string, glob = false): boolean {
163
+ return (glob ? /^[A-Za-z0-9._*][A-Za-z0-9._*\/-]*$/ : /^[A-Za-z0-9._][A-Za-z0-9._\/-]*$/).test(path) && !path.split("/").includes("..");
164
+ }
165
+
166
+ /** The check job's extra artifacts (#4988), or undefined when they name nothing; refused off GitLab and for a path outside the checkout. */
167
+ function checkArtifacts(forge: ForgeKind, artifacts: PrCheckArtifacts | undefined): PrCheckArtifacts | undefined {
168
+ const paths = artifacts?.paths ?? [];
169
+ const reports = Object.entries(artifacts?.reports ?? {});
170
+ if (paths.length === 0 && reports.length === 0) return undefined;
171
+ if (forge !== "gitlab") throw new Error("the check job's artifacts are GitLab's artifacts:paths and artifacts:reports; on GitHub and Forgejo the check is the job's last step, so leave artifacts out there");
172
+ for (const p of paths) {
173
+ if (!insideCheckout(p, true)) throw new Error(`the check job's artifact path ${JSON.stringify(p)} is not a relative path inside the checkout`);
174
+ }
175
+ for (const [type, value] of reports) {
176
+ if (!/^[a-z][a-z_]*$/.test(type)) throw new Error(`the check job's artifact report ${JSON.stringify(type)} is not a GitLab report type`);
177
+ if (type === "coverage_report") throw new Error("the check job's artifact reports take a path for each report type, and GitLab's coverage_report takes a format besides; keep it in a job of the product's own");
178
+ const list = Array.isArray(value) ? value : [value];
179
+ if (list.length === 0 || list.some((p) => !insideCheckout(p, true))) throw new Error(`the check job's ${type} report ${JSON.stringify(value)} is not a relative path inside the checkout`);
180
+ }
181
+ return { ...(paths.length > 0 ? { paths } : {}), ...(reports.length > 0 ? { reports: Object.fromEntries(reports) } : {}) };
182
+ }
183
+
133
184
  /** Refuse check job settings no job could hold (#4964). */
134
185
  function assertCheckJobOptions(opts: PrCheckJobOptions): void {
135
- if (opts.dir !== undefined && (!/^[A-Za-z0-9._][A-Za-z0-9._\/-]*$/.test(opts.dir) || opts.dir.split("/").includes(".."))) {
186
+ if (opts.dir !== undefined && !insideCheckout(opts.dir)) {
136
187
  throw new Error(`the check job's report directory ${JSON.stringify(opts.dir)} is not a relative path inside the checkout`);
137
188
  }
138
189
  for (const a of opts.args ?? []) {
@@ -164,6 +215,7 @@ function assertCheckJobOptions(opts: PrCheckJobOptions): void {
164
215
  export function prCheckJob(forge: ForgeKind, opts: { bin?: string; evidence?: PipelineEvidence; noForks?: boolean; member?: { name: string; reportPath: string } } & PrCheckJobOptions = {}): PrCheckJob {
165
216
  assertPipelineEvidence(opts.evidence);
166
217
  assertCheckJobOptions(opts);
218
+ const artifacts = checkArtifacts(forge, opts.artifacts);
167
219
  const gitlab = forge === "gitlab";
168
220
  const base = gitlab ? "$CI_MERGE_REQUEST_DIFF_BASE_SHA" : "${{ github.event.pull_request.base.sha }}";
169
221
  const dir = opts.dir ?? PR_CHECK_REPORT_DIR;
@@ -175,6 +227,7 @@ export function prCheckJob(forge: ForgeKind, opts: { bin?: string; evidence?: Pi
175
227
  dir,
176
228
  ...(opts.services?.length ? { services: opts.services } : {}),
177
229
  ...(opts.before?.length ? { before: opts.before } : {}),
230
+ ...(artifacts ? { artifacts } : {}),
178
231
  };
179
232
  const evidence = opts.evidence;
180
233
  if (!evidence) return job;
@@ -251,4 +304,4 @@ export function prRefGateJob(forge: ForgeKind, opts: { bin?: string; branch?: st
251
304
  };
252
305
  }
253
306
 
254
- export { CHECK_JOB_FLOOR, GITLAB_OPEN_EVIDENCE_FLOOR, MEMBER_SIGNED_CHECKS_FLOOR, PR_LOOP_EVIDENCE_FLOOR, PRODUCT_CHECK_JOBS_FLOOR, REF_GATE_STATUS_JOB_FLOOR } from "../release-floors";
307
+ export { CHECK_JOB_ARTIFACTS_FLOOR, CHECK_JOB_FLOOR, GITLAB_OPEN_EVIDENCE_FLOOR, MEMBER_SIGNED_CHECKS_FLOOR, PR_LOOP_EVIDENCE_FLOOR, PRODUCT_CHECK_JOBS_FLOOR, REF_GATE_STATUS_JOB_FLOOR } from "../release-floors";
@@ -1037,15 +1037,17 @@ export const PR_STALE_JOB = "stale-notes";
1037
1037
  * `staleNotes`: on a push to the target branch, at its commit, `pr-post
1038
1038
  * --stale` marks each open pull request's note posted against another
1039
1039
  * commit stale and sets its plan status back to pending. It names the plan
1040
- * comment with `previewComment`. Undefined without `staleNotes`.
1040
+ * comment with `previewComment`. Undefined without `staleNotes`. A list
1041
+ * of members (#4987, a product plan's targets) marks each one's note.
1041
1042
  */
1042
- export function prStaleJob(forge: ForgeKind, env: string, options: Pick<PrLoopPipelineOptions, "staleNotes" | "previewComment" | "branch" | "words"> = {}, member?: string): { command: string; env: Record<string, string> } | undefined {
1043
+ export function prStaleJob(forge: ForgeKind, env: string, options: Pick<PrLoopPipelineOptions, "staleNotes" | "previewComment" | "branch" | "words"> = {}, member?: string | readonly string[]): { command: string; env: Record<string, string> } | undefined {
1043
1044
  if (!options.staleNotes) return undefined;
1044
1045
  const words = resolveProductWords(options.words);
1046
+ const members = member === undefined ? [] : typeof member === "string" ? [member] : [...member];
1045
1047
  const command = [
1046
1048
  "chant", "components", "pr-post", "--stale", "--tip", '"$TIP_SHA"', "--env", env, "--forge", forge,
1047
1049
  ...(options.branch ? ["--branch", JSON.stringify(options.branch)] : []),
1048
- ...(member ? ["--member", member] : []),
1050
+ ...members.flatMap((m) => ["--member", m]),
1049
1051
  ...(options.previewComment ? ["--preview-comment"] : []),
1050
1052
  ].join(" ");
1051
1053
  return {
@@ -0,0 +1,50 @@
1
+ /**
2
+ * #4987 in the product pipeline: `applyStatus` and a product plan's
3
+ * `staleNotes` come back in `waves.pipeline` for the generators, the stale
4
+ * marking with one `--member` per plan target, and each target's note
5
+ * carries the target branch's commit it was planned against.
6
+ */
7
+ import { describe, expect, test } from "vitest";
8
+ import type { OpWavesSpec } from "../op/op-waves";
9
+ import { productPipelineJobs } from "./product-pipeline";
10
+
11
+ const words = { product: "terragucci", noun: ["root", "roots"] as [string, string], commands: { plan: "plan" as const, apply: "apply" as const }, approval: "per-wave" as const, op: "tf-apply", bin: "npx --no-install terragucci" };
12
+ const waves: OpWavesSpec = { name: "tf-apply", op: "tf-apply", step: { kind: "terraform-apply", root: "{target}" }, waves: [{ name: "dev", runs: [{ target: "envs/dev" }] }] } as OpWavesSpec;
13
+ const productPlan = { command: "terragucci plan {target} --out {output}", workflow: "terragucci-pr", targets: [{ name: "dev" }, { name: "prod" }] };
14
+ const base = { words, waves, productPlan, staleNotes: true, applyStatus: true };
15
+
16
+ describe("the apply statuses and the stale notes in the product pipeline (#4987)", () => {
17
+ test.each(["github", "forgejo", "gitlab"] as const)("on %s, the waves get the status context and the stale marking per target", (forge) => {
18
+ const jobs = productPipelineJobs(forge, "default", base);
19
+ expect(jobs.waves!.pipeline.applyStatus).toEqual({ context: "terragucci/apply" });
20
+ const stale = jobs.waves!.pipeline.staleNotes!;
21
+ expect(stale.command).toBe(`npx --no-install terragucci components pr-post --stale --tip "$TIP_SHA" --env default --forge ${forge} --member dev --member prod`);
22
+ expect(stale.env.TIP_SHA).toBe(forge === "gitlab" ? "$CI_COMMIT_SHA" : "${{ github.sha }}");
23
+ // The pull request loop's own stale job is not the product plan's.
24
+ expect(jobs.stale).toBeUndefined();
25
+ // Each target's note carries the target branch's commit, so the push can tell it is stale.
26
+ for (const p of jobs.productPlan!) {
27
+ expect(p.post.command).toContain('--tip "$TIP_SHA"');
28
+ expect(p.post.env.TIP_SHA).toBe(forge === "gitlab" ? "$CI_COMMIT_SHA" : "${{ github.event.pull_request.base.sha }}");
29
+ }
30
+ });
31
+
32
+ test("the re-plan's note carries its tip too, and the stale line names the re-plan comment", () => {
33
+ const jobs = productPipelineJobs("github", "default", { ...base, productPlan: { ...productPlan, replan: true } });
34
+ const replan = jobs.productPlan![0]!.replan!;
35
+ expect(replan.post.command).toContain('--tip "$TIP_SHA"');
36
+ expect(replan.post.env.TIP_SHA).toBe("${{ github.sha }}");
37
+ expect(jobs.waves!.pipeline.staleNotes!.command).toContain("--preview-comment");
38
+ });
39
+
40
+ test("a member's status context, and nothing without the options", () => {
41
+ expect(productPipelineJobs("github", "default", { ...base, member: "net" }).waves!.pipeline.applyStatus).toEqual({ context: "terragucci/apply/net" });
42
+ expect(productPipelineJobs("github", "default", { words, waves, productPlan }).waves!.pipeline).toEqual({});
43
+ });
44
+
45
+ test("refused without waves", () => {
46
+ const planOnly = { ...words, commands: { plan: "plan" as const } };
47
+ expect(() => productPipelineJobs("github", "default", { words: planOnly, productPlan, applyStatus: true })).toThrow("applyStatus posts the waves' apply statuses, and there are none");
48
+ expect(() => productPipelineJobs("github", "default", { words: planOnly, productPlan, staleNotes: true })).toThrow("staleNotes with the product plan marks the notes from the waves workflow's push run");
49
+ });
50
+ });
@@ -30,6 +30,7 @@ import {
30
30
  CHANT_WORDS,
31
31
  CI_PRODUCT_COMMANDS,
32
32
  commentLine,
33
+ productStatusContext,
33
34
  type CiProductApplyMode,
34
35
  type CiProductCommand,
35
36
  type CiProductWords,
@@ -37,7 +38,7 @@ import {
37
38
  } from "../ci-product-words";
38
39
  import { checkJobOptions, PR_LOOP_REPORT_DIR, prActionJob, prCommentLockJobs, prCommentPreviewJob, prLoopJobs, prLoopPostJob, prLoopRunner, prNoteCommandsJob, prStaleJob, withProductBin, type PrActionJob, type PrCommentLockJob, type PrCommentPreviewJob, type PrLoopJob, type PrLoopPipelineOptions } from "./pr-pipeline";
39
40
  import type { DriverComponent } from "./driver";
40
- import type { ScheduledOpSpec } from "../lexicon";
41
+ import type { OpWavesPipelineOptions, ScheduledOpSpec } from "../lexicon";
41
42
  import type { CiRunner } from "../ci-jobs";
42
43
  import { resolveAgentSpec, type OpAgentSpec } from "../ci-agent";
43
44
  import { resolveCommitSpec, type OpCommitSpec } from "../ci-commit";
@@ -47,6 +48,10 @@ import { gitlabOpenEvidenceDir, type PipelineEvidence } from "../ci-evidence-job
47
48
  import { prCheckJob, prRefGateJob, type PrCheckJob, type PrRefGateJob } from "./pr-checks";
48
49
  import { COMMENT_JOBS_ENV, PR_COMMENT_JOB, type CommentJobs } from "../ci-comment-commands";
49
50
  import { GITHUB_JOB_TOKEN } from "../ci-jobs";
51
+ import type { OpWavesBeforeMerge } from "../op/before-merge";
52
+ import { defaultPipelineFiles, type WavesBeforeMergeJobs } from "../op/before-merge-decide";
53
+ import type { PrApplyRequire } from "../pr-requires";
54
+ import { LOCK_REACH_ENV } from "../lifecycle/reach-locks";
50
55
 
51
56
  /** Where the generator writes a product's waves spec, which chant reads at base (#4550). */
52
57
  export const PRODUCT_WAVES_SPEC_DIR = ".chant/op-waves";
@@ -147,6 +152,43 @@ export interface ProductPipelineOptions extends Omit<PrLoopPipelineOptions, "wor
147
152
  * there.
148
153
  */
149
154
  commentJob?: boolean;
155
+ /**
156
+ * Waves before merge (#4984, maintainer decision 2026-11-10): `/<product>
157
+ * apply [wave-<n>]` on an open pull request runs the waves on its head.
158
+ * The comment job (GitHub, Forgejo; needs `commentJob`) or the note poll
159
+ * (GitLab; needs `noteCommands`) decides it by the product plan's rules
160
+ * (../op/before-merge-decide.ts): this repository's pull request into the
161
+ * default branch, its head unmoved, `requires` met, every plan status
162
+ * passed on the head, none of `pipelineFiles` touched, and with the
163
+ * product plan's `reach` the locks at stage apply. It records the head
164
+ * and the decision's digest on `chant/lifecycle` and starts the waves
165
+ * workflow for it, whose guard admits that head alone. After the last
166
+ * wave, `merge: "auto"` merges the pull request at that head and releases
167
+ * its locks. Needs `waves` (or `componentWaves`).
168
+ */
169
+ wavesBeforeMerge?: ProductWavesBeforeMerge;
170
+ /**
171
+ * The apply statuses (#4987): the waves workflow posts `<product>/apply`
172
+ * (`<product>/apply/<member>` for a member) on the commit the waves
173
+ * applied, from a job after each wave that runs none of the change's
174
+ * code (`@intentius/chant/op/apply-status`): pending after each wave,
175
+ * success after the last, failed when a run failed. Needs `waves` (or
176
+ * `componentWaves`); the product passes `waves.pipeline` on when it
177
+ * renders them.
178
+ */
179
+ applyStatus?: boolean;
180
+ }
181
+
182
+ /** {@link ProductPipelineOptions.wavesBeforeMerge} (#4984). */
183
+ export interface ProductWavesBeforeMerge {
184
+ /** The requires the forge is asked before the apply (`apply.requires`). Default every one: approved, mergeable, undiverged, checks. */
185
+ requires?: PrApplyRequire[];
186
+ /** `auto`: merge after the last wave, and release the locks. `manual` (default): reply that it is ready. */
187
+ merge?: "auto" | "manual";
188
+ /** The merge token's secret or CI/CD variable, with `merge: "auto"` (needed on Forgejo and GitLab). */
189
+ mergeTokenSecret?: string;
190
+ /** Paths a change may not touch to apply before merge; one ending in `/` is a directory. Default the forge's workflow directory and `.chant/op-waves/`. */
191
+ pipelineFiles?: string[];
150
192
  }
151
193
 
152
194
  /** The comment job (#4946): its command, the values it reads, and the comment prefixes that start it. */
@@ -183,8 +225,25 @@ export interface ProductPipelineJobs {
183
225
  applyBeforeMerge?: PrLoopJob;
184
226
  /** The comment each command answers, `/<product> <word>`, for the commands the pipeline has a job for. */
185
227
  comments: Partial<Record<CiProductCommand, string>>;
186
- /** The apply on merge: the spec with the words' names, its file, and a job per wave (per share or group). */
187
- waves?: { spec: OpWavesSpec; specFile: string; jobs: OpWaveJob[] };
228
+ /**
229
+ * The apply on merge: the spec with the words' names, its file, and a job
230
+ * per wave (per share or group). With `wavesBeforeMerge` (#4984),
231
+ * `beforeMerge` is the generators' `OpWavesPipelineOptions.beforeMerge`:
232
+ * the product passes it on when it renders the waves.
233
+ */
234
+ waves?: {
235
+ spec: OpWavesSpec;
236
+ specFile: string;
237
+ jobs: OpWaveJob[];
238
+ beforeMerge?: OpWavesBeforeMerge;
239
+ /**
240
+ * What the generators take from the pipeline (#4987): `beforeMerge`,
241
+ * `applyStatus` and, with `staleNotes`, the stale marking job that runs
242
+ * beside wave 1 on a push (one `--member` per product plan target). The
243
+ * product spreads it into the `OpWavesPipelineOptions` it renders with.
244
+ */
245
+ pipeline: Pick<OpWavesPipelineOptions, "beforeMerge" | "applyStatus" | "staleNotes">;
246
+ };
188
247
  /**
189
248
  * The comment lock and unlock jobs (#4588), under `locks: "plan"`:
190
249
  * `/<product> lock` keeps the locks the plan took, `/<product> unlock`
@@ -212,7 +271,7 @@ export interface ProductPipelineJobs {
212
271
  * lexicon renders the same job from `chant build --pr-loop
213
272
  * --note-commands`. Refused on GitHub and Forgejo.
214
273
  */
215
- noteCommands?: { command: string; runner?: CiRunner };
274
+ noteCommands?: { command: string; runner?: CiRunner; env?: Record<string, string> };
216
275
  /**
217
276
  * The agent (#4616), with `agent`: the comment it answers, `/<product>
218
277
  * agent <ask>`, and the scheduled Op spec whose generated workflow runs
@@ -351,7 +410,8 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
351
410
  // #4946: the comment job answers every command but a commit word (the commit job's) with a reply, so the words may name any.
352
411
  const answered: CiProductCommand[] = options.commentJob ? [...new Set<CiProductCommand>([...jobs, ...CI_PRODUCT_COMMANDS.filter((c) => c !== "commit")])] : jobs;
353
412
  const words = assertProductWords({ ...options.words, applyMode }, { jobs: answered });
354
- const { waves: given, wavesSpecFile, member, agent: _agent, commits: _commits, actions: _actions, componentWaves, productPlan, evidence, commentJob: _commentJob, ...loop } = options;
413
+ const { waves: given, wavesSpecFile, member, agent: _agent, commits: _commits, actions: _actions, componentWaves, productPlan, evidence, commentJob: _commentJob, wavesBeforeMerge, applyStatus: _applyStatus, ...loop } = options;
414
+ if (options.applyStatus && !given && !componentWaves) throw new Error("applyStatus posts the waves' apply statuses, and there are none: give waves (or componentWaves)");
355
415
  const { respond } = options;
356
416
  // #4629: the pull request loop puts the responses on the apply and note jobs, as `chant build --pr-loop --respond` does.
357
417
  const prLoop: PrLoopPipelineOptions = { ...loop, words, gate: options.gate ?? words.prGate };
@@ -394,7 +454,12 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
394
454
  if (reachLock) out.reachLock = reachLock;
395
455
  const action = prActionJob(forge, prLoop);
396
456
  if (action) out.action = { ...action, ...(prLoopRunner(options, "apply") !== undefined ? { runner: prLoopRunner(options, "apply")! } : {}) };
397
- const stale = prStaleJob(forge, env, prLoop, member);
457
+ // #4987: a product plan's notes are marked from the waves workflow's push run, one --member per target, naming the re-plan comment.
458
+ const planStale = productPlan
459
+ ? prStaleJob(forge, env, { ...prLoop, ...(productPlan.replan ? { previewComment: true } : {}) }, productPlan.targets?.map((t) => t.name) ?? member)
460
+ : undefined;
461
+ if (planStale && !options.waves && !options.componentWaves) throw new Error("staleNotes with the product plan marks the notes from the waves workflow's push run, beside wave 1, and there are no waves: give waves (or componentWaves), or drop staleNotes");
462
+ const stale = productPlan ? undefined : prStaleJob(forge, env, prLoop, member);
398
463
  if (stale) out.stale = { ...stale, ...defaultRunner };
399
464
  // #4785: GitLab's comment commands, polled from the notes; waves on merge are retried by an apply on a merged merge request.
400
465
  // #4899: the product plan's comment re-plan runs in the preview's pipeline, so the poll starts it as it starts a preview.
@@ -420,6 +485,32 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
420
485
  const spec = given ?? (componentWaves
421
486
  ? componentWavesSpec(componentWaves.components, words, componentWaveSteps({ ...(words.bin ? { bin: words.bin } : {}), env, base: componentWaves.base ?? "HEAD^1", ...(member ? { member } : {}), op, gate: prLoop.gate }), { ...(componentWaves.waveGate ? { gate: componentWaves.waveGate } : {}) })
422
487
  : undefined);
488
+ // #4984: the waves before merge: the comment job (the note poll on GitLab) decides an open pull request's apply and starts them.
489
+ const wavesOp = spec ? (words.op ?? spec.name) : undefined;
490
+ let bmJobs: WavesBeforeMergeJobs | undefined;
491
+ if (wavesBeforeMerge) {
492
+ if (!spec || !wavesOp) throw new Error("wavesBeforeMerge runs the waves on an open pull request's head, and there are none: give waves (or componentWaves)");
493
+ if (options.applyBeforeMerge) throw new Error("wavesBeforeMerge and applyBeforeMerge both answer an open pull request's apply; give one");
494
+ if (forge === "gitlab" ? !options.noteCommands : !options.commentJob) throw new Error(`wavesBeforeMerge is decided by ${forge === "gitlab" ? "the note poll: set noteCommands" : "the comment job: set commentJob"}`);
495
+ const targets = productPlan?.targets?.map((t) => t.name);
496
+ bmJobs = {
497
+ ...(forge !== "gitlab" ? { workflow: `${wavesOp}.yml` } : {}),
498
+ ...(wavesBeforeMerge.requires ? { requires: [...wavesBeforeMerge.requires] } : {}),
499
+ plan: targets?.length ? targets.map((t) => productStatusContext(words, "plan", t)) : [productStatusContext(words, "plan", member)],
500
+ pipelineFiles: wavesBeforeMerge.pipelineFiles ?? defaultPipelineFiles(forge),
501
+ ...(productPlan?.reach ? { locks: { ...(productPlan.reach.gate ? { gate: productPlan.reach.gate } : {}) } } : {}),
502
+ };
503
+ }
504
+ // #4984: GitLab's note poll writes a wave stop for a merged merge request, and decides the waves before merge.
505
+ if (out.noteCommands && spec && wavesOp) {
506
+ out.noteCommands = {
507
+ ...out.noteCommands,
508
+ env: {
509
+ [COMMENT_JOBS_ENV]: JSON.stringify({ waves: { op: wavesOp, count: spec.waves.length }, ...(bmJobs ? { wavesBeforeMerge: bmJobs } : {}) }),
510
+ ...(bmJobs && productPlan?.reach ? { [LOCK_REACH_ENV]: productPlan.reach.command } : {}),
511
+ },
512
+ };
513
+ }
423
514
  // #4946: the comment job answers what no other job of the pipeline takes, so it is told which jobs there are.
424
515
  if (options.commentJob) {
425
516
  // #4963's re-plan reply answers the same stray comments, so one of the two answers them.
@@ -434,6 +525,7 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
434
525
  ...(given || componentWaves ? { applyOnMerge: true } : {}),
435
526
  // #4979: the waves' op (the name productWavesSpec gives them) and count, so a wave-<n> stops a re-run after wave n.
436
527
  ...(spec ? { waves: { op: words.op ?? spec.name, count: spec.waves.length } } : {}),
528
+ ...(bmJobs ? { wavesBeforeMerge: bmJobs } : {}),
437
529
  // #4979: the product plan's re-plan takes no flags, so the comment job answers a plan comment that carries them.
438
530
  ...(productPlan?.replan ? { noPlanFlags: true } : {}),
439
531
  ...(locks.length > 0 ? { locks: true } : {}),
@@ -441,7 +533,10 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
441
533
  ...(out.commits ? { commits: true } : {}),
442
534
  ...(options.actions || options.actionJob ? { actions: true } : {}),
443
535
  };
444
- out.comment = { ...productCommentJob(forge, words, commentJobs), ...defaultRunner };
536
+ const comment = productCommentJob(forge, words, commentJobs);
537
+ // #4984: the decision before merge locks what the reach line prints, at stage apply.
538
+ if (bmJobs && productPlan?.reach) comment.env = { ...comment.env, [LOCK_REACH_ENV]: productPlan.reach.command };
539
+ out.comment = { ...comment, ...defaultRunner };
445
540
  }
446
541
  if (!spec) return { ...out, record: record! };
447
542
  const wavesRespond = respond ? Object.fromEntries(Object.entries(respond).filter(([e]) => e !== "description")) : {};
@@ -459,7 +554,17 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
459
554
  ...(Object.keys(wavesRespond).length > 0 ? { respond: { ...(spec.respond ?? {}), ...wavesRespond } } : {}),
460
555
  };
461
556
  const specFile = wavesSpecFile ?? productWavesSpecFile(named.name);
462
- return { ...out, waves: { spec: named, specFile, jobs: opWaveJobs(named, specFile, { bin: words.bin }) } };
557
+ // #4984: what the generator's before-merge mode takes: the merge after the last wave and the lock file it releases.
558
+ const beforeMerge: OpWavesBeforeMerge | undefined = wavesBeforeMerge
559
+ ? { ...(wavesBeforeMerge.merge ? { merge: wavesBeforeMerge.merge } : {}), ...(wavesBeforeMerge.mergeTokenSecret ? { mergeTokenSecret: wavesBeforeMerge.mergeTokenSecret } : {}), ...(productPlan?.reach?.gate ? { gate: productPlan.reach.gate } : {}) }
560
+ : undefined;
561
+ // #4987: the apply statuses after each wave, and with a product plan the stale marking beside wave 1, one --member per target.
562
+ const pipeline: Pick<OpWavesPipelineOptions, "beforeMerge" | "applyStatus" | "staleNotes"> = {
563
+ ...(beforeMerge ? { beforeMerge } : {}),
564
+ ...(options.applyStatus ? { applyStatus: { context: productStatusContext(words, "apply", member) } } : {}),
565
+ ...(planStale ? { staleNotes: planStale } : {}),
566
+ };
567
+ return { ...out, waves: { spec: named, specFile, jobs: opWaveJobs(named, specFile, { bin: words.bin, ...(beforeMerge ? { beforeMerge: true } : {}) }), ...(beforeMerge ? { beforeMerge } : {}), pipeline } };
463
568
  }
464
569
 
465
570
  /** The capability steps a component waves spec runs (#4545, #4541): argv templates over `{runs}` and `{plans}`. */
@@ -65,6 +65,17 @@ describe("the product plan (#4799)", () => {
65
65
  expect(() => productPipelineJobs(forge, "default", { words: terragucci, productPlan: { command: "terragucci plan", watches: [drift, drift] } })).toThrow(/name an Op twice/);
66
66
  });
67
67
 
68
+ // #4988: an environment's drift watch scoped to that environment's note, as sql-yodeler warned per environment.
69
+ test.each(["github", "forgejo", "gitlab"] as const)("on %s, a watch's targets reach every target's note job, and a target the plan lacks is refused", (forge) => {
70
+ const staging = { op: "yodel-watch-staging", cron: "0 6 * * *", targets: ["staging"] };
71
+ const prod = { op: "yodel-watch-prod", cron: "0 6 * * *", targets: ["prod"] };
72
+ const jobs = productPipelineJobs(forge, "default", { words: yodel, productPlan: { ...environments, watches: [staging, prod] } }).productPlan!;
73
+ // pr-post --member <target> picks its own (watchesForTarget), so every note job reads the one list.
74
+ for (const j of jobs) expect(JSON.parse(j.post.env[PLAN_WATCHES_ENV]!)).toEqual([staging, prod]);
75
+ expect(() => productPipelineJobs(forge, "default", { words: yodel, productPlan: { ...environments, watches: [{ ...prod, targets: ["dev"] }] } })).toThrow("the product plan's watch yodel-watch-prod names target dev, which the plan does not have");
76
+ expect(() => productPipelineJobs(forge, "default", { words: terragucci, productPlan: { command: "terragucci plan", watches: [prod] } })).toThrow("the product plan's watch yodel-watch-prod names target prod, which the plan cannot scope to: it has no targets");
77
+ });
78
+
68
79
  test("the pipeline's passed values reach every target, and a name both give is refused", () => {
69
80
  const [staging] = productPipelineJobs("github", "default", { words: yodel, variables: { YODEL_LOG: "info" }, productPlan: environments }).productPlan!;
70
81
  expect(staging!.env.YODEL_LOG).toBe("info");
@@ -82,7 +93,7 @@ describe("the product plan (#4799)", () => {
82
93
 
83
94
  test.each([
84
95
  ["previewComment", { previewComment: true }],
85
- ["staleNotes", { staleNotes: true }],
96
+ // #4987: staleNotes is carried now, one note per target, marked from the waves' push run (product-pipeline.apply-status.test.ts).
86
97
  ["applyBeforeMerge", { applyBeforeMerge: true }],
87
98
  ["build", { build: true }],
88
99
  ])("refuses %s, which the product plan does not carry", (key, extra) => {
@@ -175,9 +186,17 @@ describe("the re-plan decision and the pending status scripts (#4899)", () => {
175
186
  const { gitlabReplanCommentIf } = await import("./product-plan");
176
187
  expect(gitlabReplanCommentIf({ comments: ["/yodel plan"], gated: [] }, "prod")).toBe("$CHANT_PREVIEW_COMMENT =~ /^\\/yodel plan( +prod)? *$/");
177
188
  expect(gitlabReplanCommentIf({ comments: ["/terragucci plan"], gated: [{ comment: "atlantis plan", when: "TG_ATLANTIS_COMMENTS" }] })).toBe(
178
- "$CHANT_PREVIEW_COMMENT =~ /^\\/terragucci plan( +[A-Za-z0-9_.\\/@+=,:-]+)? *$/ || ($TG_ATLANTIS_COMMENTS && $CHANT_PREVIEW_COMMENT =~ /^atlantis plan( +[A-Za-z0-9_.\\/@+=,:-]+)? *$/)",
189
+ "$CHANT_PREVIEW_COMMENT =~ /^\\/terragucci plan( +[A-Za-z0-9_.\\/@+=,:][A-Za-z0-9_.\\/@+=,:-]*)? *$/ || ($TG_ATLANTIS_COMMENTS && $CHANT_PREVIEW_COMMENT =~ /^atlantis plan( +[A-Za-z0-9_.\\/@+=,:][A-Za-z0-9_.\\/@+=,:-]*)? *$/)",
179
190
  );
180
191
  });
192
+
193
+ test("a re-plan word never starts with - (#4984), so a flag is not read as a root", async () => {
194
+ const { isReplanWord } = await import("./product-plan");
195
+ expect(isReplanWord("live/app")).toBe(true);
196
+ expect(isReplanWord("a-b")).toBe(true);
197
+ expect(isReplanWord("--target=x")).toBe(false);
198
+ expect(isReplanWord("-r")).toBe(false);
199
+ });
181
200
  });
182
201
 
183
202
  test("PRODUCT_PLAN_STEPS_FLOOR marks the plan-job steps in the ci-product entry", async () => {
@@ -189,10 +208,9 @@ test("PRODUCT_PLAN_STEPS_FLOOR marks the plan-job steps in the ci-product entry"
189
208
  describe("what terragucci's and sql-yodeler's plan jobs need (#4963)", () => {
190
209
  const trade = { aws: { region: "us-east-1", audience: "sts.amazonaws.com", role: "arn:aws:iam::123456789012:role/plan" } };
191
210
 
192
- test("PRODUCT_PLAN_REPLAN_FLOOR is the next release, in the ci-product entry", async () => {
211
+ test("PRODUCT_PLAN_REPLAN_FLOOR is the release that shipped it, in the ci-product entry", async () => {
193
212
  const ciProduct = (await import("../ci-product")) as Record<string, unknown>;
194
- const { NEXT_RELEASE } = await import("../release-floors");
195
- expect(ciProduct.PRODUCT_PLAN_REPLAN_FLOOR).toBe(NEXT_RELEASE);
213
+ expect(ciProduct.PRODUCT_PLAN_REPLAN_FLOOR).toBe("0.124.89");
196
214
  expect(typeof ciProduct.planBodyHandoff).toBe("function");
197
215
  });
198
216
 
@@ -163,6 +163,22 @@ export interface ProductPlanReplanJob {
163
163
  notAffected?: true;
164
164
  }
165
165
 
166
+ /**
167
+ * The one word a comment re-plan takes after the command (#4899): letters,
168
+ * digits and `_./@+=,:-`, and (#4984) never starting with `-`, so a flag
169
+ * such as `--target=x` is refused rather than read as a root. The source
170
+ * of a regular expression, without anchors.
171
+ */
172
+ export const REPLAN_WORD_SOURCE = "[A-Za-z0-9_.\\/@+=,:][A-Za-z0-9_.\\/@+=,:-]*";
173
+
174
+ /** {@link REPLAN_WORD_SOURCE} anchored, as the re-plan's `node -e` program writes it between slashes. */
175
+ const REPLAN_WORD_JS = `^${REPLAN_WORD_SOURCE}$`;
176
+
177
+ /** Whether `word` is one a re-plan takes (#4984). */
178
+ export function isReplanWord(word: string): boolean {
179
+ return new RegExp(`^${REPLAN_WORD_SOURCE}$`).test(word);
180
+ }
181
+
166
182
  /** The variable a comment re-plan's one argument reaches the plan verb in (#4899). Empty on a pull request's own plan. */
167
183
  export const PLAN_ARGUMENT_ENV = "CHANT_PLAN_ARGUMENT";
168
184
 
@@ -313,7 +329,10 @@ export interface ProductPlanOptions {
313
329
  * so `pr-post` asks the forge when each last ran, in its checkout of the
314
330
  * target branch's commit, and adds the line for one that is overdue under
315
331
  * the note's counts. They reach it as `CHANT_PLAN_WATCHES`, from the
316
- * pipeline, never from the plan job's report.
332
+ * pipeline, never from the plan job's report. #4988: a watch's `targets`
333
+ * scope it to those targets' notes, such as an environment's drift
334
+ * watch to that environment's note; left out, every target's note checks
335
+ * it.
317
336
  */
318
337
  watches?: ScheduledWatch[];
319
338
  /**
@@ -462,11 +481,10 @@ const TARGET_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
462
481
 
463
482
  /** The pull request loop's options the product plan's jobs do not carry, and what each needs. Each is refused with `plan` (#4799). */
464
483
  const NOT_WITH_PLAN: ReadonlyArray<[keyof PrLoopPipelineOptions, string]> = [
465
- ["applyBeforeMerge", "the apply before merge runs pr-apply on pr-plan's report"],
484
+ ["applyBeforeMerge", "the apply before merge runs pr-apply on pr-plan's report; give wavesBeforeMerge to run the waves on an open pull request's head (#4984)"],
466
485
  ["applyOnMerge", "the apply on merge runs on op waves, from the waves spec"],
467
486
  ["waveGate", "the apply on merge runs on op waves, from the waves spec"],
468
487
  ["previewComment", "the comment preview re-runs pr-plan"],
469
- ["staleNotes", "the stale marking names one note per pipeline"],
470
488
  ["identity", "the identity trade runs before pr-plan's checkout; give the product plan's trade or login (or a target's) instead"],
471
489
  ["build", "the plan verb builds what it plans"],
472
490
  ["buildCommand", "the plan verb builds what it plans"],
@@ -542,6 +560,10 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
542
560
  for (const w of plan.watches ?? []) {
543
561
  const problem = scheduledWatchProblem(w);
544
562
  if (problem) throw new Error(`the product plan's watches: ${problem}`);
563
+ // #4988: a watch scoped to targets names the plan's own.
564
+ for (const t of w.targets ?? []) {
565
+ if (!seen.has(t)) throw new Error(`the product plan's watch ${w.op} names target ${t}, which the plan ${targets?.length ? "does not have" : "cannot scope to: it has no targets"}`);
566
+ }
545
567
  }
546
568
  if (new Set((plan.watches ?? []).map((w) => w.op)).size !== (plan.watches ?? []).length) throw new Error("the product plan's watches name an Op twice");
547
569
  // The note job's variables from the pipeline: the note words, and the product's watches (#4888).
@@ -560,7 +582,8 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
560
582
  if (key in shared) throw new Error(`target ${name}'s ${key} is the pipeline's too; give it on the target or on the pipeline`);
561
583
  if (key in jobEnv) throw new Error(`target ${name}'s ${key} is the product plan's env too; give it once`);
562
584
  }
563
- const post0 = prLoopPostJob(forge, env, name, words);
585
+ // #4987: with staleNotes each target's note carries the target branch's commit, so the waves' push can mark it stale.
586
+ const post0 = prLoopPostJob(forge, env, name, words, loop.staleNotes ? { staleNotes: true } : {});
564
587
  // #4899: the note job records the plan job's run, named by that job.
565
588
  const post1 = plan.record ? { ...post0, command: `${post0.command} --record-run ${jobName}` } : post0;
566
589
  // #4914: on GitLab the signing job of the same pipeline keeps each merge request's evidence, which the note's checks line reads.
@@ -589,7 +612,7 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
589
612
  const replies = github && Boolean(replanOpts.reply) && (targets === undefined || target === targets[0]);
590
613
  const replan0 = replanComments
591
614
  ? {
592
- ...replanJobOf(forge, env, words, name, artifact, noteWords, { notAffected: replanOpts.notAffected === true }),
615
+ ...replanJobOf(forge, env, words, name, artifact, noteWords, { notAffected: replanOpts.notAffected === true, ...(loop.staleNotes ? { staleNotes: true } : {}) }),
593
616
  ...replanComments,
594
617
  ...(github && dispatchArg !== undefined ? { dispatch: { argument: dispatchArg } } : {}),
595
618
  ...(replies ? { reply: { prefix: `/${words.product}`, others } } : {}),
@@ -639,15 +662,18 @@ function replanCommentsOf(words: CiProductWords): { comments: string[]; gated: A
639
662
  }
640
663
 
641
664
  /** The re-plan's jobs for one target (#4899), its comments filled in by the caller. */
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"> {
665
+ function replanJobOf(forge: ForgeKind, env: string, words: CiProductWords, name: string | undefined, artifact: string, noteWords0: Record<string, string>, opts: { notAffected?: boolean; staleNotes?: boolean } = {}): Omit<ProductPlanReplanJob, "comments" | "gated"> {
643
666
  const github = forge !== "gitlab";
644
667
  const jobName = github ? (name ? `${REPLAN_JOB}-${name}` : REPLAN_JOB) : name ? `${name}-${REPLAN_JOB}` : REPLAN_JOB;
645
668
  const noteJobName = github ? (name ? `${REPLAN_NOTE_JOB}-${name}` : REPLAN_NOTE_JOB) : name ? `${name}-${REPLAN_NOTE_JOB}` : REPLAN_NOTE_JOB;
646
669
  // 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.
647
- const command0 = github ? prLoopPostJob(forge, env, name, words).command : prLoopPostJob("github", env, name, words).command.replace(" --forge github ", " --forge gitlab ");
670
+ // #4987: with staleNotes the note's tip line is the target branch's commit the re-plan ran at, as the comment preview's is.
671
+ const stale = opts.staleNotes ? { staleNotes: true } : {};
672
+ const command0 = github ? prLoopPostJob(forge, env, name, words, stale).command : prLoopPostJob("github", env, name, words, stale).command.replace(" --forge github ", " --forge gitlab ");
648
673
  // #4963: the argument the re-plan was narrowed to, which pr-post answers "not affected" for when the change does not reach it.
649
674
  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;
675
+ const noteWords1 = opts.notAffected && github ? { ...noteWords0, [PLAN_ARGUMENT_ENV]: `\${{ needs.${jobName}.outputs.argument }}` } : noteWords0;
676
+ const noteWords = opts.staleNotes ? { ...noteWords1, TIP_SHA: github ? "${{ github.sha }}" : "$CI_COMMIT_SHA" } : noteWords1;
651
677
  const post = github
652
678
  ? {
653
679
  command,
@@ -691,7 +717,8 @@ function literal(text: string): string {
691
717
  * a target, the command with at most one word after it.
692
718
  */
693
719
  export function gitlabReplanCommentIf(replan: Pick<ProductPlanReplanJob, "comments" | "gated">, target?: string): string {
694
- const arg = target ? `( +${literal(target)})?` : "( +[A-Za-z0-9_.\\/@+=,:-]+)?";
720
+ // #4984: the one word never starts with `-`, so a flag such as `--target=x` starts no re-plan.
721
+ const arg = target ? `( +${literal(target)})?` : `( +${REPLAN_WORD_SOURCE})?`;
695
722
  const one = (c: string): string => `$${GITLAB_REPLAN_COMMENT_VAR} =~ /^${literal(c)}${arg} *$/`;
696
723
  return [...replan.comments.map(one), ...replan.gated.map((g) => `($${g.when} && ${one(g.comment)})`)].join(" || ");
697
724
  }
@@ -739,15 +766,19 @@ export function replanDecideJs(opts: { dispatch?: boolean; reply?: boolean } = {
739
766
  'const body=String((e.comment&&e.comment.body)||"").trim();',
740
767
  'const cmds=JSON.parse(process.env.CHANT_REPLAN_COMMANDS||"[]");',
741
768
  '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;",
769
+ "let arg,flag;",
743
770
  ...(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
771
  ...(dispatch
745
772
  ? [
746
773
  '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 ',
774
+ `const k=process.env.CHANT_REPLAN_DISPATCH_ARGUMENT||"argument",a=String(inputs[k]==null?"":inputs[k]).trim();if(a&&!/${REPLAN_WORD_JS}/.test(a)){console.error("chant: the dispatch\\u0027s "+k+" input is one word of letters, digits and _./@+=,:-, not starting with -");process.exit(1)}arg=a}else `,
748
775
  ]
749
776
  : []),
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}}}',
777
+ // #4984: a word that starts with `-` is a flag (`--target=x`), which the re-plan does not take.
778
+ `for(const c of cmds){if(body===c){arg="";break}if(body.startsWith(c+" ")){const r=body.slice(c.length).trim();if(r.startsWith("-")){flag=r.split(/\\s/)[0];break}if(/${REPLAN_WORD_JS}/.test(r)){arg=r;break}}}`,
779
+ reply
780
+ ? 'if(flag!==undefined){refusal="the re-plan takes no flags, and "+flag+" is one: write the command alone, or with one word that does not start with -";arg=""}'
781
+ : 'if(flag!==undefined){say("the re-plan takes no flags, and "+flag+" is one, so nothing is planned again");process.exit(0)}',
751
782
  reply
752
783
  ? '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
784
  : 'if(arg===undefined){say("the comment asks for no plan");process.exit(0)}',