@intentius/chant 0.124.91 → 0.124.93

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 (108) hide show
  1. package/dist/__golden__/notify-defaults-plain.json +52 -0
  2. package/dist/__golden__/notify-defaults-relay.json +92 -0
  3. package/dist/ci-comment-commands.d.ts +11 -1
  4. package/dist/ci-comment-commands.d.ts.map +1 -1
  5. package/dist/ci-comment-commands.js +10 -3
  6. package/dist/ci-job-guard.d.ts +22 -8
  7. package/dist/ci-job-guard.d.ts.map +1 -1
  8. package/dist/ci-job-guard.js +93 -49
  9. package/dist/ci-jobs.d.ts +22 -0
  10. package/dist/ci-jobs.d.ts.map +1 -1
  11. package/dist/ci-jobs.js +23 -0
  12. package/dist/ci-product.d.ts +42 -1
  13. package/dist/ci-product.d.ts.map +1 -1
  14. package/dist/ci-product.js +44 -3
  15. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  16. package/dist/cli/handlers/pr-comment.js +15 -2
  17. package/dist/cli/handlers/pr.d.ts.map +1 -1
  18. package/dist/cli/handlers/pr.js +4 -1
  19. package/dist/components/pr-pipeline.d.ts +4 -2
  20. package/dist/components/pr-pipeline.d.ts.map +1 -1
  21. package/dist/components/pr-pipeline.js +7 -4
  22. package/dist/components/product-pipeline.d.ts +71 -7
  23. package/dist/components/product-pipeline.d.ts.map +1 -1
  24. package/dist/components/product-pipeline.js +84 -22
  25. package/dist/components/product-plan.d.ts +7 -0
  26. package/dist/components/product-plan.d.ts.map +1 -1
  27. package/dist/components/product-plan.js +1 -0
  28. package/dist/floor-table.data.d.ts.map +1 -1
  29. package/dist/floor-table.data.js +15 -5
  30. package/dist/lexicon.d.ts +59 -1
  31. package/dist/lexicon.d.ts.map +1 -1
  32. package/dist/notify.d.ts +8 -0
  33. package/dist/notify.d.ts.map +1 -1
  34. package/dist/notify.js +8 -3
  35. package/dist/op/before-merge-decide.d.ts +2 -0
  36. package/dist/op/before-merge-decide.d.ts.map +1 -1
  37. package/dist/op/before-merge.d.ts +8 -0
  38. package/dist/op/before-merge.d.ts.map +1 -1
  39. package/dist/op/before-merge.js +6 -0
  40. package/dist/op/index.d.ts +1 -1
  41. package/dist/op/index.d.ts.map +1 -1
  42. package/dist/op/index.js +1 -1
  43. package/dist/op/op-waves-evidence-jobs.d.ts +3 -2
  44. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  45. package/dist/op/op-waves-evidence-jobs.js +4 -3
  46. package/dist/op/op-waves-follow-on.d.ts +2 -0
  47. package/dist/op/op-waves-follow-on.d.ts.map +1 -1
  48. package/dist/op/op-waves-follow-on.js +8 -2
  49. package/dist/op/op-waves-names.d.ts +145 -0
  50. package/dist/op/op-waves-names.d.ts.map +1 -0
  51. package/dist/op/op-waves-names.js +201 -0
  52. package/dist/op/op-waves-run.d.ts +2 -0
  53. package/dist/op/op-waves-run.d.ts.map +1 -1
  54. package/dist/op/op-waves-run.js +2 -2
  55. package/dist/op/op-waves-stand-down.d.ts +9 -1
  56. package/dist/op/op-waves-stand-down.d.ts.map +1 -1
  57. package/dist/op/op-waves-stand-down.js +14 -2
  58. package/dist/op/op-waves.d.ts +12 -1
  59. package/dist/op/op-waves.d.ts.map +1 -1
  60. package/dist/op/op-waves.js +2 -0
  61. package/dist/pr-forge-job.d.ts +8 -0
  62. package/dist/pr-forge-job.d.ts.map +1 -1
  63. package/dist/pr-forge-job.js +13 -0
  64. package/dist/pr-plan-record.d.ts +3 -1
  65. package/dist/pr-plan-record.d.ts.map +1 -1
  66. package/dist/pr-plan-record.js +1 -1
  67. package/dist/pr-post.d.ts +9 -3
  68. package/dist/pr-post.d.ts.map +1 -1
  69. package/dist/pr-post.js +5 -2
  70. package/dist/release-floors.d.ts +1 -1
  71. package/dist/release-floors.d.ts.map +1 -1
  72. package/dist/release-floors.js +4 -4
  73. package/dist/wave-runtime.mjs +305 -305
  74. package/package.json +1 -1
  75. package/src/__golden__/notify-defaults-plain.json +52 -0
  76. package/src/__golden__/notify-defaults-relay.json +92 -0
  77. package/src/ci-comment-commands.test.ts +19 -5
  78. package/src/ci-comment-commands.ts +18 -3
  79. package/src/ci-job-guard.default-branch.test.ts +125 -0
  80. package/src/ci-job-guard.ts +64 -10
  81. package/src/ci-jobs.ts +26 -0
  82. package/src/ci-product.ts +54 -3
  83. package/src/cli/handlers/pr-comment.ts +12 -2
  84. package/src/cli/handlers/pr.ts +4 -1
  85. package/src/components/pr-pipeline.ts +7 -4
  86. package/src/components/product-job-names.test.ts +176 -0
  87. package/src/components/product-pipeline.ts +143 -31
  88. package/src/components/product-plan.ts +8 -0
  89. package/src/floor-table.data.ts +15 -5
  90. package/src/lexicon.ts +59 -1
  91. package/src/notify-bundle.test.ts +3 -2
  92. package/src/notify-relay-name.test.ts +72 -0
  93. package/src/notify.ts +16 -3
  94. package/src/op/before-merge-decide.ts +2 -0
  95. package/src/op/before-merge.ts +12 -0
  96. package/src/op/index.ts +1 -1
  97. package/src/op/op-waves-evidence-jobs.ts +4 -3
  98. package/src/op/op-waves-follow-on.ts +10 -2
  99. package/src/op/op-waves-names.test.ts +131 -0
  100. package/src/op/op-waves-names.ts +289 -0
  101. package/src/op/op-waves-run.ts +4 -2
  102. package/src/op/op-waves-stand-down.ts +15 -2
  103. package/src/op/op-waves.ts +13 -1
  104. package/src/pr-forge-job.ts +13 -0
  105. package/src/pr-plan-record.ts +4 -2
  106. package/src/pr-post-head.test.ts +116 -0
  107. package/src/pr-post.ts +15 -5
  108. package/src/release-floors.ts +4 -4
@@ -195,6 +195,14 @@ export interface OpWavesBeforeMerge {
195
195
  mergeTokenSecret?: string;
196
196
  /** The lock file the change's locks are in, `_locks/<gate>.json`, which `merge: "auto"` releases. Default the pull request loop's. */
197
197
  gate?: string;
198
+ /**
199
+ * The forge environment the job after the last wave runs in (#5037), so
200
+ * a merge token scoped to it reaches that job alone, such as terragucci's
201
+ * `terragucci-merge`. GitLab: `environment: { name, action: access }`,
202
+ * which deploys nothing. GitHub: `environment: <name>`, whose secrets the
203
+ * job reads. Forgejo has no environments and refuses it. Absent: none.
204
+ */
205
+ environment?: string;
198
206
  }
199
207
 
200
208
  /** The job after the last wave of a before-merge run (#4984). */
@@ -208,6 +216,10 @@ export function assertOpWavesBeforeMerge(forge: "github" | "forgejo" | "gitlab",
208
216
  if (bm.merge !== undefined && bm.merge !== "auto" && bm.merge !== "manual") throw new Error(`beforeMerge.merge is auto or manual, not ${JSON.stringify(bm.merge)}`);
209
217
  if (bm.mergeTokenSecret !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(bm.mergeTokenSecret)) throw new Error(`beforeMerge.mergeTokenSecret ${JSON.stringify(bm.mergeTokenSecret)} is not a variable name`);
210
218
  if (bm.gate !== undefined && !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(bm.gate)) throw new Error(`beforeMerge.gate ${JSON.stringify(bm.gate)} is not a lock file name`);
219
+ if (bm.environment !== undefined) {
220
+ if (forge === "forgejo") throw new Error("beforeMerge.environment names a forge environment, and Forgejo Actions has none; scope the merge token another way, or leave it out");
221
+ if (typeof bm.environment !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.\/-]{0,254}$/.test(bm.environment)) throw new Error(`beforeMerge.environment ${JSON.stringify(bm.environment)} is not an environment name`);
222
+ }
211
223
  if (bm.merge === "auto" && forge !== "github" && !bm.mergeTokenSecret) {
212
224
  throw new Error(`beforeMerge.merge auto on ${forge} needs mergeTokenSecret: ${forge === "forgejo" ? "Forgejo refuses a merge made with the job's own token" : "GitLab's job token cannot merge"}`);
213
225
  }
package/src/op/index.ts CHANGED
@@ -150,7 +150,7 @@ export {
150
150
  opWavesRenderSpecProblems,
151
151
  } from "./op-waves-render-spec";
152
152
  export type { OpWavesRenderSpec } from "./op-waves-render-spec";
153
- export { OP_WAVE_STAND_DOWN_FLOOR, gitOpWaveNewerCommit, newerCommitOnBranch, opWaveRunBranch, opWaveStandDownReason, tipAppliesTargets } from "./op-waves-stand-down";
153
+ export { OP_WAVE_STAND_DOWN_FLOOR, gitOpWaveNewerCommit, newerCommitOnBranch, opWaveDefaultBranch, opWaveRunBranch, opWaveStandDownReason, tipAppliesTargets } from "./op-waves-stand-down";
154
154
  export type { OpWaveNewerCommit, OpWaveNewerCommitPort } from "./op-waves-stand-down";
155
155
  export { OP_WAVE_RELEASE_RECORD_FLOOR, opWaveReleaseNames, opWaveReleaseProblems, releaseOfCommit } from "./op-waves-release";
156
156
  export { gitOpWaveReleasePort } from "./op-waves-release-port";
@@ -87,12 +87,13 @@ export function opWavePolicyStepName(wave: number, name: string): string {
87
87
  /**
88
88
  * The evidence job's `CHANT_EVIDENCE_SOURCES`: on GitHub and Forgejo the
89
89
  * command step for `plan:<wave>` and the policy step for `policy:<wave>`, by
90
- * name; on GitLab the wave job and its policy job.
90
+ * name; on GitLab the wave job and its policy job (`policyJob`, a
91
+ * product's name for it, #5022).
91
92
  */
92
- export function opWaveEvidenceSources(forge: "github" | "forgejo" | "gitlab", plan: OpWaveEvidencePlan, job: Pick<OpWaveJob, "jobName" | "wave">, waveName: string, commandStep: string): Record<string, EvidenceSourceSpec> {
93
+ export function opWaveEvidenceSources(forge: "github" | "forgejo" | "gitlab", plan: OpWaveEvidencePlan, job: Pick<OpWaveJob, "jobName" | "wave">, waveName: string, commandStep: string, policyJob = opWavePolicyJobName(job)): Record<string, EvidenceSourceSpec> {
93
94
  const out: Record<string, EvidenceSourceSpec> = {};
94
95
  for (const check of plan.evidenceJob?.checks ?? []) {
95
- if (forge === "gitlab") out[check] = check === plan.policy ? { job: opWavePolicyJobName(job) } : {};
96
+ if (forge === "gitlab") out[check] = check === plan.policy ? { job: policyJob } : {};
96
97
  else out[check] = { step: check === plan.policy ? opWavePolicyStepName(job.wave, waveName) : commandStep };
97
98
  }
98
99
  return out;
@@ -74,6 +74,8 @@ export interface OpWavesFollowOnTarget {
74
74
  forge: "github" | "forgejo" | "gitlab";
75
75
  /** GitHub and Forgejo: the waves workflow's file name, which the record job dispatches. */
76
76
  workflow?: string;
77
+ /** GitHub and Forgejo (#5022): the product's names of the dispatch inputs `pr`, `head`, `digest`, `wave` and `commit`, when it renamed any. */
78
+ inputs?: Partial<Record<"pr" | "head" | "digest" | "wave" | "commit", string>>;
77
79
  }
78
80
 
79
81
  /** The rest wave's number when the spec's last wave has `rest`, else undefined. */
@@ -107,7 +109,11 @@ export function parseFollowOnTarget(raw: string | undefined): OpWavesFollowOnTar
107
109
  const o = v as Partial<OpWavesFollowOnTarget> | null;
108
110
  if (!o || (o.forge !== "github" && o.forge !== "forgejo" && o.forge !== "gitlab")) throw new Error(`${OP_WAVES_FOLLOW_ON_ENV}.forge is github, forgejo or gitlab`);
109
111
  if (o.forge !== "gitlab" && (typeof o.workflow !== "string" || !/^[A-Za-z0-9._-]+\.ya?ml$/.test(o.workflow))) throw new Error(`${OP_WAVES_FOLLOW_ON_ENV}.workflow names the waves workflow's file`);
110
- return { forge: o.forge, ...(o.workflow ? { workflow: o.workflow } : {}) };
112
+ const inputs = o.inputs;
113
+ if (inputs !== undefined && (typeof inputs !== "object" || inputs === null || Object.entries(inputs).some(([k, n]) => !["pr", "head", "digest", "wave", "commit"].includes(k) || typeof n !== "string" || !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(n)))) {
114
+ throw new Error(`${OP_WAVES_FOLLOW_ON_ENV}.inputs names the dispatch inputs pr, head, digest, wave and commit`);
115
+ }
116
+ return { forge: o.forge, ...(o.workflow ? { workflow: o.workflow } : {}), ...(inputs ? { inputs: { ...inputs } } : {}) };
111
117
  }
112
118
 
113
119
  /**
@@ -380,6 +386,8 @@ export async function startFollowOn(target: OpWavesFollowOnTarget, wave: number,
380
386
  }
381
387
  const ref = env.GITHUB_REF_NAME?.trim() || env.GITHUB_REF?.replace(/^refs\/heads\//, "");
382
388
  if (!ref) throw new Error("the job names no branch (no GITHUB_REF_NAME)");
383
- await post(`${t.apiBase}/repos/${t.repo}/actions/workflows/${encodeURIComponent(target.workflow!)}/dispatches`, { Authorization: `token ${t.token}` }, { ref, inputs: values });
389
+ // #5022: the inputs under the product's names, when it renamed them.
390
+ const inputs = Object.fromEntries(Object.entries(values).map(([k, v]) => [target.inputs?.[k as keyof NonNullable<OpWavesFollowOnTarget["inputs"]>] ?? k, v]));
391
+ await post(`${t.apiBase}/repos/${t.repo}/actions/workflows/${encodeURIComponent(target.workflow!)}/dispatches`, { Authorization: `token ${t.token}` }, { ref, inputs });
384
392
  return {};
385
393
  }
@@ -0,0 +1,131 @@
1
+ /**
2
+ * #5022: a product's own names in an Op waves pipeline: the job names and
3
+ * their needs, the dispatch inputs and artifact names, the follow-on
4
+ * dispatch under the product's workflow and inputs, and the product
5
+ * pipeline's before-merge workflow and inputs.
6
+ */
7
+ import { describe, expect, test } from "vitest";
8
+ import { opWaveJobs, type OpWavesSpec } from "./op-waves";
9
+ import { opWaveSplitJobs } from "./op-waves-split";
10
+ import { opWavesArtifacts, opWavesDispatchInputs, opWavesInputsRenamed, opWavesNamer, opWavesWorkflowFile, type OpWavesJobRef } from "./op-waves-names";
11
+ import { parseFollowOnTarget, startFollowOn } from "./op-waves-follow-on";
12
+ import { productPipelineJobs } from "../components/product-pipeline";
13
+
14
+ const spec = {
15
+ name: "tf-apply",
16
+ op: "tf-apply",
17
+ planWave: ["terragucci", "plan-wave", "{runs}", "{plans}"],
18
+ apply: ["terragucci", "apply", "{target}", "--plan", "{plan}"],
19
+ waves: [
20
+ { name: "canary", runs: [], discover: true },
21
+ { name: "wide", runs: [], discover: true, shares: 2 },
22
+ { name: "rest", runs: [], discover: true, rest: true },
23
+ ],
24
+ } as unknown as OpWavesSpec;
25
+
26
+ const terragucci = (j: OpWavesJobRef): string | undefined => {
27
+ const w = j.rest ? "apply-rest" : `apply-wave-${j.wave}`;
28
+ if (j.role === "wave" || j.role === "decide") return w;
29
+ if (j.role === "share") return `${w}-share-${j.share}`;
30
+ if (j.role === "plan" || j.role === "gate" || j.role === "record") return `${w}-${j.role}`;
31
+ if (j.role === "apply") return j.share !== undefined ? `${w}-share-${j.share}` : w;
32
+ return undefined;
33
+ };
34
+
35
+ describe("the job names (#5022)", () => {
36
+ test("each job takes the product's name, and its needs follow", () => {
37
+ const jobs = opWavesNamer(spec, "github", terragucci).jobs(opWaveJobs(spec, "s.json"));
38
+ expect(jobs.map((j) => [j.jobName, j.needs])).toEqual([
39
+ ["apply-wave-1", []],
40
+ ["apply-wave-2", ["apply-wave-1"]],
41
+ ["apply-wave-2-share-1", ["apply-wave-2"]],
42
+ ["apply-wave-2-share-2", ["apply-wave-2"]],
43
+ ["apply-rest", ["apply-wave-2-share-1", "apply-wave-2-share-2"]],
44
+ ]);
45
+ });
46
+
47
+ test("a split pipeline's jobs, and the rest wave's, take theirs", () => {
48
+ const split = opWavesNamer(spec, "github", terragucci).jobs(opWaveSplitJobs(spec, opWaveJobs(spec, "s.json", { beforeMerge: true })));
49
+ expect(split.filter((j) => j.wave === 3).map((j) => [j.jobName, j.needs])).toEqual([
50
+ ["apply-rest-plan", ["apply-wave-2-record"]],
51
+ ["apply-rest-gate", ["apply-rest-plan"]],
52
+ ["apply-rest", ["apply-rest-gate"]],
53
+ ["apply-rest-record", ["apply-rest", "apply-rest-gate"]],
54
+ ]);
55
+ });
56
+
57
+ test("without names, chant's; the same job asked twice keeps its name", () => {
58
+ const namer = opWavesNamer(spec, "gitlab", undefined);
59
+ expect(namer.jobs(opWaveJobs(spec, "s.json")).map((j) => j.jobName)).toEqual(["wave-1-canary", "wave-2-wide-decide", "wave-2-wide-share-1", "wave-2-wide-share-2", "wave-3-rest"]);
60
+ expect(namer.name({ role: "control", name: "control-dispatch" })).toBe("control-dispatch");
61
+ expect(namer.name({ role: "control", name: "control-dispatch" })).toBe("control-dispatch");
62
+ });
63
+
64
+ test("refuses a name the forge cannot take, and two jobs that share one", () => {
65
+ const jobs = opWaveJobs(spec, "s.json");
66
+ expect(() => opWavesNamer(spec, "github", () => "1-apply").jobs(jobs)).toThrow(/not a job name/);
67
+ expect(() => opWavesNamer(spec, "gitlab", (j) => (j.role === "wave" ? "stages" : undefined)).jobs(jobs)).toThrow(/no GitLab keyword/);
68
+ expect(() => opWavesNamer(spec, "github", (j) => (j.role === "share" ? "apply" : undefined)).jobs(jobs)).toThrow(/names two jobs apply: wave-2-wide-share-1 and wave-2-wide-share-2/);
69
+ const namer = opWavesNamer(spec, "github", (j) => (j.role === "apply-status" ? "control-dispatch" : undefined));
70
+ namer.name({ role: "control", name: "control-dispatch" });
71
+ expect(() => namer.name({ role: "apply-status", name: "apply-status-1", wave: 1 })).toThrow(/names two jobs control-dispatch/);
72
+ });
73
+ });
74
+
75
+ describe("the dispatch inputs, artifacts and workflow file (#5022)", () => {
76
+ test("the inputs are chant's unless renamed, each a name and none twice", () => {
77
+ expect(opWavesDispatchInputs(undefined)).toEqual({ pr: "pr", head: "head", digest: "digest", wave: "wave", commit: "commit" });
78
+ expect(opWavesInputsRenamed(opWavesDispatchInputs({ pr: "pr" }))).toBe(false);
79
+ expect(opWavesDispatchInputs({ pr: "apply_pr", head: "apply_head" })).toMatchObject({ pr: "apply_pr", head: "apply_head", digest: "digest" });
80
+ expect(() => opWavesDispatchInputs({ pr: "head" })).toThrow(/names two inputs head: pr and head/);
81
+ expect(() => opWavesDispatchInputs({ pr: "a b" })).toThrow(/not an input name/);
82
+ expect(() => opWavesDispatchInputs({ root: "r" } as never)).toThrow(/none of pr, head, digest, wave and commit/);
83
+ });
84
+
85
+ test("the artifacts are chant's unless named, each template holding its mark", () => {
86
+ const chant = opWavesArtifacts(spec, undefined);
87
+ expect([chant.outcome("wave-1-canary"), chant.decision(2), chant.plan(2), chant.checks("j"), chant.earlier]).toEqual(["tf-apply-wave-1-canary-outcome", "tf-apply-wave-2-decision", "tf-apply-wave-2-plan", "tf-apply-j-checks", undefined]);
88
+ const tg = opWavesArtifacts(spec, { outcome: "terragucci-report-{job}-outcome", decision: "terragucci-wave-{wave}", earlier: "terragucci-report-apply-wave-*" });
89
+ expect([tg.outcome("apply-wave-1"), tg.decision(2), tg.earlier]).toEqual(["terragucci-report-apply-wave-1-outcome", "terragucci-wave-2", "terragucci-report-apply-wave-*"]);
90
+ expect(() => opWavesArtifacts(spec, { outcome: "outcome" })).toThrow(/artifactNames\.outcome "outcome" holds \{job\}/);
91
+ expect(() => opWavesArtifacts(spec, { decision: "d/{wave}" })).toThrow(/artifactNames\.decision/);
92
+ expect(() => opWavesArtifacts(spec, { decision: "w-{wave}", plan: "w-{wave}" })).toThrow(/the decision and the saved plan one name/);
93
+ expect(() => opWavesArtifacts(spec, { earlier: "a/b" })).toThrow(/artifactNames\.earlier/);
94
+ expect(opWavesWorkflowFile(spec, undefined)).toBe("tf-apply.yml");
95
+ expect(opWavesWorkflowFile(spec, "terragucci.yml")).toBe("terragucci.yml");
96
+ expect(() => opWavesWorkflowFile(spec, ".github/workflows/terragucci.yml")).toThrow(/workflow file's name/);
97
+ });
98
+ });
99
+
100
+ describe("the follow-on under the product's workflow and inputs (#5022)", () => {
101
+ test("the record job dispatches the product's workflow with its input names", async () => {
102
+ const target = parseFollowOnTarget(JSON.stringify({ forge: "github", workflow: "terragucci.yml", inputs: opWavesDispatchInputs({ pr: "apply_pr", head: "apply_head", digest: "apply_digest", wave: "apply_wave", commit: "apply_commit" }) }))!;
103
+ const posts: Array<{ url: string; body: unknown }> = [];
104
+ const fetchFn = (async (url: string, init: { body: string }) => (posts.push({ url, body: JSON.parse(init.body) }), new Response(null, { status: 204 }))) as unknown as typeof fetch;
105
+ const HEAD = "a".repeat(40);
106
+ const env = { GITHUB_REPOSITORY: "acme/infra", GITHUB_API_URL: "https://api.github.com", GITHUB_REF_NAME: "main", CHANT_WAVES_FOLLOW_ON_TOKEN: "t" };
107
+ await startFollowOn(target, 4, { ...env, CHANT_BEFORE_MERGE_PR: "7", CHANT_BEFORE_MERGE_HEAD: HEAD, CHANT_BEFORE_MERGE_DIGEST: `sha256:${"e".repeat(64)}` }, fetchFn);
108
+ expect(posts.at(-1)).toEqual({ url: "https://api.github.com/repos/acme/infra/actions/workflows/terragucci.yml/dispatches", body: { ref: "main", inputs: { apply_pr: "7", apply_head: HEAD, apply_digest: `sha256:${"e".repeat(64)}`, apply_wave: "4" } } });
109
+ await startFollowOn(target, 4, { ...env, CHANT_WAVES_COMMIT: "d".repeat(40) }, fetchFn);
110
+ expect(posts.at(-1)!.body).toEqual({ ref: "main", inputs: { apply_wave: "4", apply_commit: "d".repeat(40) } });
111
+ expect(() => parseFollowOnTarget(JSON.stringify({ forge: "github", workflow: "x.yml", inputs: { root: "r" } }))).toThrow(/inputs names the dispatch inputs/);
112
+ });
113
+ });
114
+
115
+ describe("the product pipeline's waves before merge in a product's workflow (#5022)", () => {
116
+ 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: "terragucci" };
117
+ const waves = { name: "tf-apply", op: "tf-apply", step: { kind: "terraform-apply", root: "{target}" }, waves: [{ name: "dev", runs: [{ target: "envs/dev" }] }] } as OpWavesSpec;
118
+ const productPlan = { command: "terragucci plan --out {output}" };
119
+
120
+ test("the comment job dispatches the product's workflow by its input names, and the generator is handed both", () => {
121
+ const dispatchInputs = { pr: "apply_pr", head: "apply_head", digest: "apply_digest" };
122
+ const jobs = productPipelineJobs("github", "default", { words, waves, productPlan, commentJob: true, wavesBeforeMerge: { workflowFile: "terragucci.yml", dispatchInputs } });
123
+ expect(jobs.comment!.jobs.wavesBeforeMerge).toMatchObject({ workflow: "terragucci.yml", inputs: dispatchInputs });
124
+ expect(jobs.waves!.pipeline).toMatchObject({ workflowFile: "terragucci.yml", dispatchInputs });
125
+ const chant = productPipelineJobs("github", "default", { words, waves, productPlan, commentJob: true, wavesBeforeMerge: {} });
126
+ expect(chant.comment!.jobs.wavesBeforeMerge!.workflow).toBe("tf-apply.yml");
127
+ expect(chant.comment!.jobs.wavesBeforeMerge!.inputs).toBeUndefined();
128
+ expect(chant.waves!.pipeline.workflowFile).toBeUndefined();
129
+ expect(() => productPipelineJobs("gitlab", "default", { words, waves, productPlan: { ...productPlan, replan: true }, noteCommands: true, wavesBeforeMerge: { workflowFile: "terragucci.yml" } })).toThrow(/GitLab's note poll starts a pipeline with variables/);
130
+ });
131
+ });
@@ -0,0 +1,289 @@
1
+ /**
2
+ * A product's own names in an Op waves pipeline (#5022), as the product
3
+ * plan keeps them (#5003).
4
+ *
5
+ * Maintainer decision (2026-11-11, on #5000): chant keeps a product's
6
+ * names. A product whose wave jobs live in its own workflow beside its plan
7
+ * jobs (terragucci's `apply-wave-<k>` in `terragucci.yml`) hands the
8
+ * generators the names, and they render them, so the product never renames
9
+ * or edits what chant wrote:
10
+ *
11
+ * - `jobNames`: a name for each job the generator writes (a wave's job, its
12
+ * deciding, share and job group jobs, a split wave's plan, gate, apply and
13
+ * record jobs, the policy and evidence jobs, the apply status, stale,
14
+ * before-merge done and control jobs). Every `needs:`, `if:`, artifact
15
+ * `{job}` and `--from-job` follows it.
16
+ * - `stageNames` (GitLab): a name for each stage.
17
+ * - `artifactNames` (GitHub, Forgejo): the outcome, decision, saved plan and
18
+ * check claims artifacts, and the pattern a wave job downloads the
19
+ * earlier outcomes with.
20
+ * - `workflowFile`, `runIf` and `dispatchInputs`: the jobs go in the
21
+ * product's workflow, each running only on a push `runIf` admits (or a
22
+ * before-merge or follow-on dispatch), and the dispatch inputs take the
23
+ * product's names so they never meet its own. On GitLab `runIf` joins
24
+ * every rule of every job.
25
+ *
26
+ * Left out, each is chant's, and the generators render as before.
27
+ */
28
+
29
+ import type { OpWaveJob, OpWavesSpec } from "./op-waves";
30
+
31
+ /** What a job of an Op waves pipeline is (#5022), for {@link OpWavesJobNames}. */
32
+ export type OpWavesJobRole =
33
+ | "wave"
34
+ | "decide"
35
+ | "share"
36
+ | "group"
37
+ | "plan"
38
+ | "gate"
39
+ | "apply"
40
+ | "record"
41
+ | "policy"
42
+ | "evidence"
43
+ | "apply-status"
44
+ | "stale-notes"
45
+ | "before-merge-done"
46
+ | "control"
47
+ | "resume";
48
+
49
+ /** One job the generator names (#5022). */
50
+ export interface OpWavesJobRef {
51
+ /** The name chant gives it. A policy or evidence job's is the job it belongs to's name, as the product named it, with `-policy` or `-evidence`. */
52
+ name: string;
53
+ /**
54
+ * `wave`: a wave's one job. `decide`, `share`, `group`: a wide wave's
55
+ * deciding job, a share's job and a job group's (or a group share's)
56
+ * job. `plan`, `gate`, `apply`, `record`: a split wave's jobs before merge
57
+ * (`apply` with `share` or `group` for a wide wave's). `policy` (GitLab),
58
+ * `evidence`: the jobs of a wave's checks. The rest are the jobs after
59
+ * or beside the waves; `resume` (#5034) is the scheduled job that starts
60
+ * a waiting wave's job again, `resume` in its own workflow on GitHub and
61
+ * Forgejo and `<spec>-resume` on GitLab.
62
+ */
63
+ role: OpWavesJobRole;
64
+ /** The wave's number from 1, and its name, on every job but the stale and control jobs and the before-merge done job. */
65
+ wave?: number;
66
+ waveName?: string;
67
+ share?: number;
68
+ group?: string;
69
+ /** A job of the spec's `rest` wave. */
70
+ rest?: true;
71
+ /** A policy or evidence job: the name of the job it belongs to. */
72
+ of?: string;
73
+ }
74
+
75
+ /** A product's job names (#5022): its name for a job, or undefined for chant's. */
76
+ export type OpWavesJobNames = (job: OpWavesJobRef) => string | undefined;
77
+
78
+ /** One GitLab stage the generator names (#5022). */
79
+ export interface OpWavesStageRef {
80
+ /** The name chant gives it: `plans`, `wave-<k>-<wave name>`, `before-merge-done`, `control` or `resume`. */
81
+ name: string;
82
+ role: "plans" | "wave" | "before-merge-done" | "control" | "resume";
83
+ wave?: number;
84
+ waveName?: string;
85
+ }
86
+
87
+ /** A product's GitLab stage names (#5022): its name for a stage, or undefined for chant's. Two stages may share a name. */
88
+ export type OpWavesStageNames = (stage: OpWavesStageRef) => string | undefined;
89
+
90
+ /**
91
+ * A product's artifact names (#5022, GitHub and Forgejo). `{job}` is the
92
+ * job's name as the product named it, `{wave}` the wave's number.
93
+ */
94
+ export interface OpWavesArtifactNames {
95
+ /** A job's outcome file. Default `<spec>-{job}-outcome`. */
96
+ outcome?: string;
97
+ /** A wave's decision, which its share, apply and record jobs download. Default `<spec>-wave-{wave}-decision`. */
98
+ decision?: string;
99
+ /** A split wave's saved plan (#4987). Default `<spec>-wave-{wave}-plan`. */
100
+ plan?: string;
101
+ /** A job's check claims, for its evidence job (#4926). Default `<spec>-{job}-checks`. */
102
+ checks?: string;
103
+ /**
104
+ * GitHub: the pattern a wave job downloads the earlier jobs' outcomes
105
+ * with, such as `terragucci-report-apply-wave-*`. It has to match every
106
+ * earlier outcome artifact. The jobs after the waves download every
107
+ * artifact of the run, and so does every job on Forgejo. Default: every
108
+ * artifact of the run.
109
+ */
110
+ earlier?: string;
111
+ }
112
+
113
+ /** The `workflow_dispatch` inputs of a waves workflow (#4984, #4992), by chant's name. */
114
+ export type OpWavesDispatchInput = "pr" | "head" | "digest" | "wave" | "commit";
115
+
116
+ /** The dispatch inputs' names, chant's unless the product gave its own (#5022). */
117
+ export function opWavesDispatchInputs(given: Partial<Record<OpWavesDispatchInput, string>> | undefined): Record<OpWavesDispatchInput, string> {
118
+ const out = { pr: "pr", head: "head", digest: "digest", wave: "wave", commit: "commit" } as Record<OpWavesDispatchInput, string>;
119
+ const seen = new Map<string, string>();
120
+ for (const key of Object.keys(out) as OpWavesDispatchInput[]) {
121
+ const v = given?.[key];
122
+ if (given && key in given && (typeof v !== "string" || !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(v))) throw new Error(`dispatchInputs.${key} ${JSON.stringify(v)} is not an input name of letters, digits, _ and -, starting with a letter or _`);
123
+ if (v !== undefined) out[key] = v;
124
+ const other = seen.get(out[key]);
125
+ if (other !== undefined) throw new Error(`dispatchInputs names two inputs ${out[key]}: ${other} and ${key}`);
126
+ seen.set(out[key], key);
127
+ }
128
+ for (const key of Object.keys(given ?? {})) if (!(key in out)) throw new Error(`dispatchInputs.${key} is none of pr, head, digest, wave and commit`);
129
+ return out;
130
+ }
131
+
132
+ /** Whether a product renamed any dispatch input (#5022). */
133
+ export function opWavesInputsRenamed(inputs: Record<OpWavesDispatchInput, string>): boolean {
134
+ return Object.entries(inputs).some(([k, v]) => k !== v);
135
+ }
136
+
137
+ const ARTIFACT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
138
+
139
+ /** The artifact names of a pipeline (#5022), from {@link OpWavesArtifactNames} or chant's. Throws on a template that cannot name one. */
140
+ export function opWavesArtifacts(spec: Pick<OpWavesSpec, "name">, given: OpWavesArtifactNames | undefined): {
141
+ outcome(job: string): string;
142
+ decision(wave: number): string;
143
+ plan(wave: number): string;
144
+ checks(job: string): string;
145
+ earlier?: string;
146
+ } {
147
+ const t = {
148
+ outcome: given?.outcome ?? `${spec.name}-{job}-outcome`,
149
+ decision: given?.decision ?? `${spec.name}-wave-{wave}-decision`,
150
+ plan: given?.plan ?? `${spec.name}-wave-{wave}-plan`,
151
+ checks: given?.checks ?? `${spec.name}-{job}-checks`,
152
+ };
153
+ const marks = { outcome: "{job}", decision: "{wave}", plan: "{wave}", checks: "{job}" } as const;
154
+ for (const key of Object.keys(marks) as Array<keyof typeof marks>) {
155
+ if (given?.[key] === undefined) continue;
156
+ const v = t[key];
157
+ if (!v.includes(marks[key]) || !ARTIFACT.test(v.replaceAll("{job}", "j").replaceAll("{wave}", "1"))) {
158
+ throw new Error(`artifactNames.${key} ${JSON.stringify(v)} holds ${marks[key]} and is otherwise letters, digits, '.', '_' and '-'`);
159
+ }
160
+ }
161
+ const distinct = new Set([t.outcome.replace("{job}", "x"), t.checks.replace("{job}", "x")]);
162
+ if (distinct.size < 2) throw new Error(`artifactNames gives the outcome and the check claims one name, ${JSON.stringify(t.outcome)}`);
163
+ if (t.decision === t.plan) throw new Error(`artifactNames gives the decision and the saved plan one name, ${JSON.stringify(t.plan)}`);
164
+ const earlier = given?.earlier;
165
+ if (earlier !== undefined && !/^[A-Za-z0-9._*-]+$/.test(earlier)) throw new Error(`artifactNames.earlier ${JSON.stringify(earlier)} is a pattern of letters, digits, '.', '_', '-' and '*'`);
166
+ return {
167
+ outcome: (job) => t.outcome.replaceAll("{job}", job),
168
+ decision: (wave) => t.decision.replaceAll("{wave}", String(wave)),
169
+ plan: (wave) => t.plan.replaceAll("{wave}", String(wave)),
170
+ checks: (job) => t.checks.replaceAll("{job}", job),
171
+ ...(earlier !== undefined ? { earlier } : {}),
172
+ };
173
+ }
174
+
175
+ /** The file a waves workflow goes in (#5022): `workflowFile`, else `<spec>.yml`. */
176
+ export function opWavesWorkflowFile(spec: Pick<OpWavesSpec, "name">, file: string | undefined): string {
177
+ if (file === undefined) return `${spec.name}.yml`;
178
+ if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.ya?ml$/.test(file)) throw new Error(`workflowFile ${JSON.stringify(file)} is a workflow file's name, like terragucci.yml, in the forge's workflow directory`);
179
+ return file;
180
+ }
181
+
182
+ /**
183
+ * The file the resume workflow goes in (#5034, GitHub and Forgejo):
184
+ * `resumeWorkflowFile`, such as terragucci's `terragucci-resume.yml`, else
185
+ * `<spec>-resume.yml`. Refused when it is the waves' own file.
186
+ */
187
+ export function opWavesResumeWorkflowFile(spec: Pick<OpWavesSpec, "name">, file: string | undefined, wavesFile: string): string {
188
+ if (file === undefined) return `${spec.name}-resume.yml`;
189
+ if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.ya?ml$/.test(file)) throw new Error(`resumeWorkflowFile ${JSON.stringify(file)} is a workflow file's name, like terragucci-resume.yml, in the forge's workflow directory`);
190
+ if (file === wavesFile) throw new Error(`resumeWorkflowFile ${JSON.stringify(file)} is the waves' own workflow; the resume runs on a schedule of its own`);
191
+ return file;
192
+ }
193
+
194
+ /**
195
+ * The product's own jobs the first wave's jobs need (#5032), such as
196
+ * terragucci's `check`: checked as job names of the forge, each once.
197
+ * Absent or empty: none, and the jobs render as before.
198
+ */
199
+ export function opWavesFirstWaveNeeds(given: readonly string[] | undefined, forge: "github" | "forgejo" | "gitlab"): string[] {
200
+ if (given === undefined) return [];
201
+ if (!Array.isArray(given)) throw new Error("firstWaveNeeds is a list of the product's job names");
202
+ const github = forge !== "gitlab";
203
+ for (const n of given) {
204
+ const ok = typeof n === "string" && (github ? /^[A-Za-z_][A-Za-z0-9_-]*$/.test(n) : /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(n) && !GITLAB_KEYWORDS.has(n));
205
+ if (!ok) throw new Error(`firstWaveNeeds names ${JSON.stringify(n)}, which is not a job name of letters, digits, _ and -${github ? ", starting with a letter or _" : ", and no GitLab keyword"}`);
206
+ }
207
+ if (new Set(given).size !== given.length) throw new Error(`firstWaveNeeds names a job twice: ${given.join(", ")}`);
208
+ return [...given];
209
+ }
210
+
211
+ /** Refuse a product job of {@link opWavesFirstWaveNeeds} that is a job the generator writes (#5032). */
212
+ export function assertFirstWaveNeedsOutside(needs: readonly string[], jobs: Iterable<string>): void {
213
+ const mine = new Set(jobs);
214
+ for (const n of needs) if (mine.has(n)) throw new Error(`firstWaveNeeds names ${n}, a job of the waves themselves; name the product's own jobs, such as its check`);
215
+ }
216
+
217
+ /**
218
+ * GitHub and Forgejo: the condition a first-wave job runs under with
219
+ * {@link opWavesFirstWaveNeeds} (#5032). Each product job passed; in a
220
+ * dispatched run (before merge), one that did not run is no hold, since a
221
+ * product's check runs on its pushes and pull requests.
222
+ */
223
+ export function githubFirstWaveIf(needs: readonly string[]): string {
224
+ return ["!cancelled()", ...needs.map((n) => `(needs.${n}.result == 'success' || (github.event_name == 'workflow_dispatch' && needs.${n}.result == 'skipped'))`)].join(" && ");
225
+ }
226
+
227
+ const GITLAB_KEYWORDS = new Set(["default", "include", "stages", "variables", "workflow", "image", "services", "cache", "before_script", "after_script", "spec", "pages"]);
228
+
229
+ /** A job of a pipeline as {@link opWavesNamer} reads it: an `opWaveJobs` job, or a split one with its phase. */
230
+ type NamedJob = OpWaveJob & { phase?: "plan" | "gate" | "apply" | "record"; rest?: true };
231
+
232
+ /** What a job is, for its {@link OpWavesJobRef}. */
233
+ function roleOf(job: NamedJob): OpWavesJobRole {
234
+ if (job.phase !== undefined) return job.phase;
235
+ return job.kind === "share" && job.group !== undefined ? "group" : job.kind;
236
+ }
237
+
238
+ /**
239
+ * The names of a pipeline's jobs (#5022): {@link OpWavesJobNames}, else
240
+ * chant's. `name` gives one job's (the same each time it is asked),
241
+ * `jobs` names a list of wave jobs and their `needs`, and `claim` keeps a
242
+ * name the generator writes as it is. Throws on a name the forge cannot
243
+ * take and on two jobs that share one.
244
+ */
245
+ export function opWavesNamer(spec: Pick<OpWavesSpec, "waves">, forge: "github" | "forgejo" | "gitlab", given: OpWavesJobNames | undefined): {
246
+ name(ref: OpWavesJobRef): string;
247
+ jobs<T extends NamedJob>(jobs: readonly T[]): T[];
248
+ claim(name: string): string;
249
+ } {
250
+ const github = forge !== "gitlab";
251
+ const byKey = new Map<string, string>();
252
+ const owner = new Map<string, string>();
253
+ const take = (key: string, name: string, what: string): string => {
254
+ const other = owner.get(name);
255
+ if (other !== undefined && other !== key) throw new Error(`the Op waves pipeline names two jobs ${name}: ${other.split("|")[1]} and ${what}`);
256
+ owner.set(name, key);
257
+ byKey.set(key, name);
258
+ return name;
259
+ };
260
+ const name = (ref: OpWavesJobRef): string => {
261
+ const key = `${ref.role}|${ref.name}`;
262
+ const known = byKey.get(key);
263
+ if (known !== undefined) return known;
264
+ const mine = given?.(ref);
265
+ if (mine !== undefined) {
266
+ const ok = typeof mine === "string" && (github ? /^[A-Za-z_][A-Za-z0-9_-]*$/.test(mine) : /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(mine) && !GITLAB_KEYWORDS.has(mine));
267
+ if (!ok) throw new Error(`jobNames gives the ${ref.role} job ${ref.name} the name ${JSON.stringify(mine)}, which is not a job name of letters, digits, _ and -, starting with a letter or _${github ? "" : " or a digit, and no GitLab keyword"}`);
268
+ }
269
+ return take(key, mine ?? ref.name, ref.name);
270
+ };
271
+ const restWave = spec.waves[spec.waves.length - 1]?.rest === true ? spec.waves.length : undefined;
272
+ const jobs = <T extends NamedJob>(list: readonly T[]): T[] => {
273
+ const renamed = new Map<string, string>();
274
+ for (const job of list) {
275
+ const ref: OpWavesJobRef = {
276
+ name: job.jobName,
277
+ role: roleOf(job),
278
+ wave: job.wave,
279
+ waveName: job.waveName,
280
+ ...(job.share !== undefined ? { share: job.share } : {}),
281
+ ...(job.group !== undefined ? { group: job.group } : {}),
282
+ ...(job.rest || job.wave === restWave ? { rest: true as const } : {}),
283
+ };
284
+ renamed.set(job.jobName, name(ref));
285
+ }
286
+ return list.map((job) => ({ ...job, jobName: renamed.get(job.jobName)!, needs: job.needs.map((n) => renamed.get(n) ?? n) }));
287
+ };
288
+ return { name, jobs, claim: (n) => take(`claim|${n}`, n, n) };
289
+ }
@@ -109,7 +109,7 @@ import { gitOpWaveReleasePort } from "./op-waves-release-port";
109
109
  import type { LockGrain } from "../lifecycle/lock-rows";
110
110
  import type { LockLiveness, LockRowsLease } from "../lifecycle/resource-lock";
111
111
  import type { GatePolicyExec } from "../gate-policy";
112
- import { gitOpWaveNewerCommit, opWaveStandDownReason, tipAppliesTargets, type OpWaveNewerCommitPort } from "./op-waves-stand-down";
112
+ import { gitOpWaveNewerCommit, opWaveDefaultBranch, opWaveStandDownReason, tipAppliesTargets, type OpWaveNewerCommitPort } from "./op-waves-stand-down";
113
113
  import { keyedSerial, mapLimited, type SerialSection } from "../parallelism";
114
114
  import {
115
115
  applyOpWaveStep,
@@ -936,6 +936,8 @@ export interface RunOpWaveOptions {
936
936
  standDown?: boolean;
937
937
  /** How the job finds a newer commit on its branch (#4581). Default: fetch the branch from `origin` ({@link gitOpWaveNewerCommit}). */
938
938
  newerCommit?: OpWaveNewerCommitPort;
939
+ /** The repository's default branch, for a spec with `defaultBranch` (#5032). Default {@link opWaveDefaultBranch} of the job's environment. */
940
+ defaultBranch?: string;
939
941
  /**
940
942
  * Where the job's run events go (#4555), on the run-event contract: a
941
943
  * phase `wave-<k>` per wave and a step per run target, settled as the
@@ -4726,7 +4728,7 @@ async function standDownForNewer(options: RunOpWaveOptions, ctx: WaveContext, de
4726
4728
  log(`wave ${k} (${wave.name}): ${newer.branch} has a newer commit ${newer.tip.slice(0, 12)}, and its spec cannot be read (${err instanceof Error ? err.message : String(err)}), so this job applies`);
4727
4729
  return false;
4728
4730
  }
4729
- if (!tipAppliesTargets(atTip, newer.branch, wave.name, targets)) {
4731
+ if (!tipAppliesTargets(atTip, newer.branch, wave.name, targets, options.defaultBranch ?? opWaveDefaultBranch())) {
4730
4732
  log(`wave ${k} (${wave.name}): ${newer.branch} has a newer commit ${newer.tip.slice(0, 12)}, and its wave does not apply every target of this job, so this job applies`);
4731
4733
  return false;
4732
4734
  }
@@ -86,13 +86,26 @@ export async function newerCommitOnBranch(cwd: string, env: NodeJS.ProcessEnv =
86
86
  /** The default port: {@link newerCommitOnBranch} with the job's environment. */
87
87
  export const gitOpWaveNewerCommit: OpWaveNewerCommitPort = (cwd, head) => newerCommitOnBranch(cwd, process.env, head);
88
88
 
89
+ /**
90
+ * The repository's default branch as the job's forge names it (#5032):
91
+ * `CHANT_DEFAULT_BRANCH` (a GitHub or Forgejo waves job sets it from the
92
+ * event), else GitLab's `CI_DEFAULT_BRANCH`. Undefined when neither is set.
93
+ */
94
+ export function opWaveDefaultBranch(env: NodeJS.ProcessEnv = process.env): string | undefined {
95
+ const named = (env.CHANT_DEFAULT_BRANCH || env.CI_DEFAULT_BRANCH || "").trim();
96
+ return named === "" ? undefined : named;
97
+ }
98
+
89
99
  /**
90
100
  * Whether the spec at the newer commit (`atTip`, null when the file is gone
91
101
  * there) applies every one of `targets` in wave `waveName` on `branch`.
102
+ * #5032: a spec with `defaultBranch` runs on `defaultBranch`, the name the
103
+ * forge gives the repository's default branch, beside its `branches`.
92
104
  */
93
- export function tipAppliesTargets(atTip: OpWavesSpec | null, branch: string, waveName: string, targets: readonly string[]): boolean {
105
+ export function tipAppliesTargets(atTip: OpWavesSpec | null, branch: string, waveName: string, targets: readonly string[], defaultBranch?: string): boolean {
94
106
  if (!atTip || !Array.isArray(atTip.waves)) return false;
95
- if (!(atTip.branches ?? ["main"]).includes(branch)) return false;
107
+ const onDefault = atTip.defaultBranch === true && defaultBranch !== undefined && branch === defaultBranch;
108
+ if (!onDefault && !(atTip.branches ?? (atTip.defaultBranch === true ? [] : ["main"])).includes(branch)) return false;
96
109
  const wave = atTip.waves.find((w) => w?.name === waveName);
97
110
  if (!wave) return false;
98
111
  if (wave.discover === true) return true;
@@ -483,8 +483,19 @@ export interface OpWavesSpec {
483
483
  * so a change cannot drop the rule for its own gates.
484
484
  */
485
485
  neverOverMcp?: boolean;
486
- /** Branches whose pushes run the waves. Default `["main"]`. */
486
+ /** Branches whose pushes run the waves. Default `["main"]`, or none beside the default branch with `defaultBranch`. */
487
487
  branches?: string[];
488
+ /**
489
+ * The pushes to the repository's default branch run the waves, by the
490
+ * name the forge gives it at run time (#5032): GitHub and Forgejo
491
+ * `github.event.repository.default_branch`, GitLab `$CI_DEFAULT_BRANCH`.
492
+ * `branches` names more beside it, and `main` is no longer the default.
493
+ * The job guard admits the default branch and those, the GitLab rules
494
+ * match the same, and the stand-down counts a newer commit on it. A
495
+ * product that renders the waves into a workflow of its own sets this
496
+ * when it never learns the branch's name. Default false.
497
+ */
498
+ defaultBranch?: boolean;
488
499
  /**
489
500
  * An apply stands down when a newer commit on the branch will apply the
490
501
  * same targets (#4581): its wave applies nothing, the job exits 6
@@ -996,6 +1007,7 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
996
1007
  }
997
1008
  assertOpWaveHooks(where, spec.hooks);
998
1009
  if (spec.standDown !== undefined && typeof spec.standDown !== "boolean") throw new Error(`${where}: \`standDown\` must be true or false.`);
1010
+ if (spec.defaultBranch !== undefined && typeof spec.defaultBranch !== "boolean") throw new Error(`${where}: \`defaultBranch\` must be true or false.`);
999
1011
  {
1000
1012
  const problems = opWaveReleaseProblems(spec);
1001
1013
  if (problems.length > 0) throw new Error(`${where}: ${problems.join("; ")}.`);
@@ -30,6 +30,19 @@ export function pullRequestEventHead(env: Record<string, string | undefined>): s
30
30
  }
31
31
  }
32
32
 
33
+ /**
34
+ * The commit a GitHub `pull_request` run's plan job checked out for `head`
35
+ * when it is not `head` (#5020): the run's merge preview, `GITHUB_SHA`, when
36
+ * `head` is the event's pull request head. The note job names the head, and
37
+ * takes a report for the merge preview as the head's. Undefined on any other
38
+ * run, on Forgejo (whose run is of the head) and on GitLab.
39
+ */
40
+ export function plannedForHead(head: string, env: Record<string, string | undefined> = process.env): string | undefined {
41
+ const merge = env.GITHUB_SHA;
42
+ if (!merge || merge === head || !/^[0-9a-f]{40,64}$/.test(merge)) return undefined;
43
+ return pullRequestEventHead(env) === head ? merge : undefined;
44
+ }
45
+
33
46
  /** {@link forgeFromEnv}, whose statuses for the run's merge preview go on the pull request's head (#4964). */
34
47
  export function forgeFromJobEnv(kind: ForgeKind, env: Record<string, string | undefined> = process.env, fetchImpl?: Parameters<typeof forgeFromEnv>[2]): PrForge {
35
48
  const forge = forgeFromEnv(kind, env, fetchImpl);
@@ -32,8 +32,10 @@ export const PLAN_RUN_OP = "pr-plan";
32
32
  export interface PlanRunExpect {
33
33
  /** The pipeline's environment, `--env`. */
34
34
  env: string;
35
- /** The commit the plan job checked out, `--head`. */
35
+ /** The pull request's head, `--head`. */
36
36
  head: string;
37
+ /** The commit the plan job checked out when it is not `head` (#5020): a GitHub `pull_request` run's merge preview. */
38
+ planned?: string;
37
39
  /** The target, `--member`. */
38
40
  target?: string;
39
41
  /** The plan job's result as the forge says it (`needs.<job>.result`, GitLab's job status). */
@@ -69,7 +71,7 @@ export function readPlanRunRecord(dir: string, expect: PlanRunExpect): { record:
69
71
  if (r.env !== expect.env) return { refused: `the run record is for environment ${JSON.stringify(r.env)}, not ${expect.env}` };
70
72
  const labels = r.labels && typeof r.labels === "object" && !Array.isArray(r.labels) ? (r.labels as Record<string, unknown>) : {};
71
73
  if ((labels.Target ?? undefined) !== expect.target) return { refused: `the run record is for target ${JSON.stringify(labels.Target ?? null)}, not ${JSON.stringify(expect.target ?? null)}` };
72
- if (r.gitSha !== undefined && r.gitSha !== expect.head) return { refused: `the run record is for commit ${JSON.stringify(r.gitSha)}, not ${expect.head}` };
74
+ if (r.gitSha !== undefined && r.gitSha !== expect.head && r.gitSha !== expect.planned) return { refused: `the run record is for commit ${JSON.stringify(r.gitSha)}, not ${expect.head}` };
73
75
  if (!SHA.test(expect.head)) return { refused: `the head ${JSON.stringify(expect.head)} is not a full commit` };
74
76
  const started = instant(r.started);
75
77
  const ended = instant(r.ended);