@intentius/chant 0.124.90 → 0.124.91

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 (63) hide show
  1. package/dist/actor.d.ts +5 -3
  2. package/dist/actor.d.ts.map +1 -1
  3. package/dist/actor.js +7 -5
  4. package/dist/audit/core.d.ts.map +1 -1
  5. package/dist/audit/core.js +11 -1
  6. package/dist/ci-product.d.ts +9 -0
  7. package/dist/ci-product.d.ts.map +1 -1
  8. package/dist/ci-product.js +18 -9
  9. package/dist/cli/handlers/pr-comment.js +2 -2
  10. package/dist/cli/handlers/pr.d.ts +2 -2
  11. package/dist/cli/handlers/pr.d.ts.map +1 -1
  12. package/dist/cli/handlers/pr.js +28 -9
  13. package/dist/cli/parse-args.d.ts.map +1 -1
  14. package/dist/cli/parse-args.js +13 -0
  15. package/dist/cli/registry.d.ts +4 -0
  16. package/dist/cli/registry.d.ts.map +1 -1
  17. package/dist/components/pr-checks.d.ts +11 -0
  18. package/dist/components/pr-checks.d.ts.map +1 -1
  19. package/dist/components/pr-checks.js +15 -5
  20. package/dist/components/pr-pipeline.d.ts +9 -2
  21. package/dist/components/pr-pipeline.d.ts.map +1 -1
  22. package/dist/components/pr-pipeline.js +16 -5
  23. package/dist/components/product-pipeline.d.ts.map +1 -1
  24. package/dist/components/product-pipeline.js +6 -3
  25. package/dist/components/product-plan.d.ts +79 -1
  26. package/dist/components/product-plan.d.ts.map +1 -1
  27. package/dist/components/product-plan.js +140 -16
  28. package/dist/floor-table.data.d.ts.map +1 -1
  29. package/dist/floor-table.data.js +14 -9
  30. package/dist/lexicon-module.d.ts +2 -0
  31. package/dist/lexicon-module.d.ts.map +1 -1
  32. package/dist/lexicon-module.js +6 -2
  33. package/dist/planned-files.d.ts +16 -8
  34. package/dist/planned-files.d.ts.map +1 -1
  35. package/dist/planned-files.js +12 -8
  36. package/dist/pr-post.d.ts +6 -0
  37. package/dist/pr-post.d.ts.map +1 -1
  38. package/dist/pr-post.js +5 -4
  39. package/dist/release-floors.d.ts +7 -1
  40. package/dist/release-floors.d.ts.map +1 -1
  41. package/dist/release-floors.js +8 -2
  42. package/dist/wave-runtime.mjs +215 -215
  43. package/package.json +1 -1
  44. package/src/actor.test.ts +14 -1
  45. package/src/actor.ts +8 -6
  46. package/src/audit/core.ts +13 -1
  47. package/src/audit/first-load.test.ts +101 -0
  48. package/src/ci-product.ts +20 -9
  49. package/src/cli/handlers/pr-comment.ts +2 -2
  50. package/src/cli/handlers/pr.ts +23 -9
  51. package/src/cli/parse-args.ts +9 -0
  52. package/src/cli/registry.ts +4 -0
  53. package/src/components/pr-checks.ts +16 -5
  54. package/src/components/pr-pipeline.ts +17 -7
  55. package/src/components/product-pipeline.ts +6 -3
  56. package/src/components/product-plan-names.test.ts +135 -0
  57. package/src/components/product-plan.ts +210 -18
  58. package/src/floor-table.data.ts +14 -9
  59. package/src/lexicon-module.ts +6 -2
  60. package/src/planned-files.test.ts +33 -0
  61. package/src/planned-files.ts +26 -10
  62. package/src/pr-post.ts +11 -4
  63. package/src/release-floors.ts +11 -2
@@ -0,0 +1,135 @@
1
+ /**
2
+ * #5003: the product plan keeps a product's names. A plan's own status
3
+ * context reaches every job that reads the plan status (the note job's
4
+ * `pr-post --context`, the stale job, the apply before merge), and `pr-post`
5
+ * posts and marks under it; on GitLab `pr-post --open --plan-job` finds a
6
+ * plan job of the product's name. The forge renders are in each lexicon's
7
+ * `product-plan-pipeline.names.test.ts`.
8
+ */
9
+ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
10
+ import { tmpdir } from "node:os";
11
+ import { join } from "node:path";
12
+ import { afterAll, describe, expect, test } from "vitest";
13
+ import type { OpWavesSpec } from "../op/op-waves";
14
+ import { parseArgs } from "../cli/parse-args";
15
+ import { markStaleNotes, postOpenPlanReports, postPlanReport, prNoteTipMarker } from "../pr-post";
16
+ import { prNoteMarker } from "../pr-loop";
17
+ import { planNoteHandoff, PR_PLAN_NOTE_FILE, type PrPlanNote } from "../pr-plan-note";
18
+ import { withProductWords } from "../ci-product-words";
19
+ import type { ForgeStatus, OpenPullRequest, PrForge } from "../pr-forge";
20
+ import { TERRAGUCCI, TERRAGUCCI_NOTE } from "../__fixtures__/product-words";
21
+ import { productPipelineJobs } from "./product-pipeline";
22
+ import { productPlanJobs, productPlanWorkflowFile } from "./product-plan";
23
+
24
+ const NOTE = JSON.parse(readFileSync(join(import.meta.dirname, "..", "__fixtures__", "pr-loop", "terragucci-plan.note.json"), "utf-8")) as PrPlanNote;
25
+ const HEAD = NOTE.head;
26
+ const dirs: string[] = [];
27
+ afterAll(() => {
28
+ for (const d of dirs) rmSync(d, { recursive: true, force: true });
29
+ });
30
+
31
+ function fakeForge(open: OpenPullRequest[] = []): { forge: PrForge; statuses: Array<{ sha: string; status: ForgeStatus }>; notes: Map<string, string> } {
32
+ const statuses: Array<{ sha: string; status: ForgeStatus }> = [];
33
+ const notes = new Map<string, string>();
34
+ const forge = {
35
+ kind: "github",
36
+ host: "github.com",
37
+ async setStatus(sha: string, status: ForgeStatus) {
38
+ statuses.push({ sha, status });
39
+ },
40
+ async upsertNote(pr: number, marker: string, body: string) {
41
+ notes.set(`${pr} ${marker}`, body);
42
+ return "1";
43
+ },
44
+ async findComment(pr: number, marker: string) {
45
+ const body = notes.get(`${pr} ${marker}`);
46
+ return body === undefined ? undefined : { id: 1, body };
47
+ },
48
+ async openPullRequests(base: string) {
49
+ return open.filter((p) => p.base === base);
50
+ },
51
+ } as unknown as PrForge;
52
+ return { forge, statuses, notes };
53
+ }
54
+
55
+ const at = { pr: 7, env: "default", state: "success" as const, description: "2 roots planned" };
56
+
57
+ describe("pr-post under a product plan's own status context (#5003)", () => {
58
+ test("the note job posts the status under the context it is given", async () => {
59
+ const { forge, statuses } = fakeForge();
60
+ const dir = mkdtempSync(join(tmpdir(), "chant-pr-post-names-"));
61
+ dirs.push(dir);
62
+ writeFileSync(join(dir, PR_PLAN_NOTE_FILE), JSON.stringify(planNoteHandoff(NOTE, at)));
63
+ await withProductWords(TERRAGUCCI, () => postPlanReport({ forge, dir, pr: 7, head: HEAD, env: "default", result: "success", noteWords: TERRAGUCCI_NOTE, context: "tg/plan-roots" }));
64
+ expect(statuses.map((s) => s.status.context)).toEqual(["tg/plan-roots"]);
65
+ });
66
+
67
+ test("pr-post --open asks for the plan job it is named and posts under the context", async () => {
68
+ const { forge: base, statuses } = fakeForge();
69
+ const asked: string[] = [];
70
+ const forge = {
71
+ ...base,
72
+ kind: "gitlab",
73
+ async mergeRequestJobs(_branch: string, job: string) {
74
+ asked.push(job);
75
+ return [{ pr: 7, head: HEAD, id: 11, status: "success", url: "https://gitlab.example/job/11" }];
76
+ },
77
+ async jobArtifact(_id: number, path: string) {
78
+ return path === "terragucci-report/pr-plan-note.json" ? JSON.stringify(planNoteHandoff(NOTE, at)) : undefined;
79
+ },
80
+ async statusUrl() {
81
+ return undefined;
82
+ },
83
+ setStatus: base.setStatus,
84
+ upsertNote: base.upsertNote,
85
+ findComment: base.findComment,
86
+ } as unknown as PrForge;
87
+ const done = await withProductWords(TERRAGUCCI, () => postOpenPlanReports({ forge, branch: "main", job: "tf-plan", artifactDir: "terragucci-report", env: "default", context: "tg/plan-roots" }));
88
+ expect(asked).toEqual(["tf-plan"]);
89
+ expect(done.posts[0]!.posted).toMatchObject({ noted: true });
90
+ expect(statuses.map((s) => s.status.context)).toEqual(["tg/plan-roots"]);
91
+ });
92
+
93
+ test("the stale job sets the named status back to pending", async () => {
94
+ const head = "d".repeat(40);
95
+ const { forge, statuses, notes } = fakeForge([{ number: 7, head: "feature", headSha: head, base: "main", fork: false }]);
96
+ notes.set(`7 ${prNoteMarker("default")}`, [prNoteMarker("default"), "body", prNoteTipMarker("a".repeat(40)), ""].join("\n"));
97
+ await withProductWords(TERRAGUCCI, () => markStaleNotes({ forge, branch: "main", tip: "b".repeat(40), env: "default", context: "tg/plan-roots" }));
98
+ expect(statuses).toEqual([{ sha: head, status: expect.objectContaining({ context: "tg/plan-roots", state: "pending" }) }]);
99
+ });
100
+
101
+ test("the command line takes --context (once a --member with --stale) and --plan-job", () => {
102
+ expect(parseArgs(["components", "pr-post", "--stale", "--member", "dev", "--context", "tg/dev/plan", "--member", "prod", "--context", "tg/prod/plan"]).statusContexts).toEqual(["tg/dev/plan", "tg/prod/plan"]);
103
+ expect(parseArgs(["components", "pr-post", "--open", "--plan-job", "tf-plan"]).planJob).toBe("tf-plan");
104
+ expect(() => parseArgs(["components", "pr-post", "--context", "tg plan"])).toThrow(/--context needs the plan status's context/);
105
+ expect(() => parseArgs(["components", "pr-post", "--plan-job", "--open"])).toThrow(/--plan-job needs the plan job's name/);
106
+ });
107
+ });
108
+
109
+ 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" };
110
+ const waves: OpWavesSpec = { name: "tf-apply", op: "tf-apply", step: { kind: "terraform-apply", root: "{target}" }, waves: [{ name: "dev", runs: [{ target: "envs/dev" }] }] } as OpWavesSpec;
111
+
112
+ describe("the product plan's status context in the pipeline (#5003)", () => {
113
+ const productPlan = { command: "terragucci plan {target} --out {output}", targets: [{ name: "dev" }, { name: "prod" }], statusContext: "tg/{target}/plan" };
114
+
115
+ test.each(["github", "forgejo", "gitlab"] as const)("on %s, the stale job sets each target's own status back", (forge) => {
116
+ const jobs = productPipelineJobs(forge, "default", { words, waves, productPlan, staleNotes: true });
117
+ expect(jobs.waves!.pipeline.staleNotes!.command).toBe(`npx --no-install terragucci components pr-post --stale --tip "$TIP_SHA" --env default --forge ${forge} --member dev --member prod --context tg/dev/plan --context tg/prod/plan`);
118
+ });
119
+
120
+ test("the apply before merge asks for the product's plan statuses", () => {
121
+ const jobs = productPipelineJobs("github", "default", { words, waves, productPlan, commentJob: true, wavesBeforeMerge: {} });
122
+ expect(jobs.comment!.jobs.wavesBeforeMerge!.plan).toEqual(["tg/dev/plan", "tg/prod/plan"]);
123
+ const gitlab = productPipelineJobs("gitlab", "default", { words, waves, productPlan: { ...productPlan, replan: true }, noteCommands: true, wavesBeforeMerge: {} });
124
+ expect(JSON.stringify(gitlab.noteCommands!.env)).toContain('\\"plan\\":[\\"tg/dev/plan\\",\\"tg/prod/plan\\"]');
125
+ });
126
+
127
+ test("without the options the jobs carry no names of their own", () => {
128
+ const [p] = productPlanJobs("github", "default", { plan: { command: "terragucci plan --out {output}" } }, { ...words, aliases: [] } as never);
129
+ expect(p!.context).toBeUndefined();
130
+ expect(p!.reportDir).toBeUndefined();
131
+ expect(productPlanWorkflowFile("gitlab", "default", { workflow: "terragucci" })).toBe(".gitlab/terragucci.gitlab-ci.yml");
132
+ expect(productPlanWorkflowFile("gitlab", "default", { workflowFile: ".gitlab/terragucci.yml" })).toBe(".gitlab/terragucci.yml");
133
+ expect(() => productPlanWorkflowFile("gitlab", "default", { workflowFile: "../ci.yml" })).toThrow(/inside it/);
134
+ });
135
+ });
@@ -51,6 +51,7 @@ import { PLAN_RUN_OP, PLAN_RUN_RECORD_FILE } from "../pr-plan-record";
51
51
  import { idTokenVar, tradedClouds, type CloudTradeSpec } from "../ci-identity";
52
52
  import { prNoteMarker } from "../pr-loop";
53
53
  import { PRODUCT_MARKER_NAME } from "../pr-plan-note";
54
+ import { gitlabJobArtifacts, type PrCheckArtifacts } from "./pr-checks";
54
55
 
55
56
  /** The variable the plan-note job reads the product's note words from (#4799), as JSON. Set from the pipeline, never from the report. */
56
57
  export const PR_PLAN_NOTE_WORDS_ENV = "CHANT_PLAN_NOTE_WORDS";
@@ -371,6 +372,60 @@ export interface ProductPlanOptions {
371
372
  * answer `/<product> lock` and `/<product> unlock` there too.
372
373
  */
373
374
  reach?: { command: string; gate?: string };
375
+ /**
376
+ * The file the product writes the workflow to (#5003), from the
377
+ * repository root: on GitHub a file directly under `.github/workflows/`,
378
+ * on Forgejo under `.forgejo/workflows/`, on GitLab a `.yml` file, such
379
+ * as one the project's `.gitlab-ci.yml` includes. The generators return it as
380
+ * `path`. Default `<forge's workflow directory>/<workflow>.yml`, and on
381
+ * GitLab `.gitlab/<workflow>.gitlab-ci.yml`, with `workflow` the
382
+ * workflow's name.
383
+ */
384
+ workflowFile?: string;
385
+ /**
386
+ * The plan jobs' names (#5003), so a product's required checks keep
387
+ * matching: `plan`, the plan job; `note`, its note job; `replan` and
388
+ * `replanNote`, the comment re-plan's. With `targets` each name holds
389
+ * `{target}`, filled with the target's name. Left out, a name is chant's:
390
+ * `plan`, `plan-note`, `replan`, `replan-note`, with targets
391
+ * `plan-{target}`, `plan-note-{target}`, `replan-{target}` and
392
+ * `replan-note-{target}` on GitHub and Forgejo and `{target}-plan`,
393
+ * `{target}-plan-note`, `{target}-replan` and `{target}-replan-note` on
394
+ * GitLab. A name is letters, digits, `_` and `-`, starting with a letter
395
+ * or `_` (on GitLab a digit too, and no top-level keyword such as
396
+ * `stages`), and no two jobs share one.
397
+ */
398
+ jobNames?: { plan?: string; note?: string; replan?: string; replanNote?: string };
399
+ /**
400
+ * The plan status's context (#5003), which the note job posts
401
+ * (`pr-post --context`), the pending step says is pending, the stale job
402
+ * sets back to pending, and the apply before merge asks has passed. With
403
+ * `targets` it holds `{target}`. Default the words' `<product>/<plan
404
+ * stage>`, with targets `<product>/<plan stage>/<target>`. Letters,
405
+ * digits and `_./:-`.
406
+ */
407
+ statusContext?: string;
408
+ /**
409
+ * The directory the plan verb writes into and the jobs hand on, keep as
410
+ * the artifact's path and post from (#5003): `{output}` in `command`
411
+ * and `report`, and `pr-post --output`. A path from the checkout's root
412
+ * that stays inside it, such as terragucci's `terragucci-report`.
413
+ * Default {@link PR_LOOP_REPORT_DIR}.
414
+ */
415
+ reportDir?: string;
416
+ /**
417
+ * GitLab only (#5004): what each plan job keeps beside the report
418
+ * directory, as the check job's `artifacts` (#4988, {@link PrCheckArtifacts}):
419
+ * `paths` after it in `artifacts:paths`, and `reports` as
420
+ * `artifacts:reports`, such as terragucci's `{ terraform:
421
+ * "{output}/gitlab-terraform.json" }` for the merge request's widget.
422
+ * `{target}` and `{output}` are filled as in `command`. Kept when the plan
423
+ * fails too, as the report is. The re-plan jobs keep only the report
424
+ * directory: they run in a pipeline of the target branch, whose reports
425
+ * GitLab would read as the target branch's own. GitHub and Forgejo refuse
426
+ * it, since the plan verb is the job's last step there.
427
+ */
428
+ artifacts?: PrCheckArtifacts;
374
429
  }
375
430
 
376
431
  /** The lock job a product plan with {@link ProductPlanOptions.reach} writes (#4979): its command and the values the command reads. */
@@ -475,6 +530,46 @@ export interface ProductPlanJob {
475
530
  previous?: { marker: string; name: string };
476
531
  /** With `record` (#4899): the plan step writes the run record, `env` its op, environment and labels as {@link PLAN_RUN_RECORD_ENV}; the note job's command records it. */
477
532
  record?: { env: Record<string, string> };
533
+ /** With `statusContext` (#5003): the plan status's context, filled for the target. Absent: the words' {@link productStatusContext}. */
534
+ context?: string;
535
+ /** With `reportDir` (#5003): the directory the plan verb writes into and the jobs hand on. Absent: {@link PR_LOOP_REPORT_DIR}. */
536
+ reportDir?: string;
537
+ /** With `artifacts` (#5004), GitLab: the plan job's own paths and reports beside the report directory, `{target}` and `{output}` filled. */
538
+ artifacts?: PrCheckArtifacts;
539
+ }
540
+
541
+ /** The plan status's context of one plan job (#5003): its own, else the words'. */
542
+ export function productPlanContext(p: Pick<ProductPlanJob, "context" | "target">, words: CiProductWords): string {
543
+ return p.context ?? productStatusContext(words, "plan", p.target);
544
+ }
545
+
546
+ /** The directory one plan job hands on (#5003): its own, else {@link PR_LOOP_REPORT_DIR}. */
547
+ export function productPlanReportDir(p: Pick<ProductPlanJob, "reportDir">): string {
548
+ return p.reportDir ?? PR_LOOP_REPORT_DIR;
549
+ }
550
+
551
+ /** The workflow's default name (#4799): `chant-pr-<env>`. */
552
+ function defaultWorkflowName(env: string): string {
553
+ return `chant-pr-${env}`;
554
+ }
555
+
556
+ /**
557
+ * The file a product plan's workflow is written to (#5003),
558
+ * {@link ProductPlanOptions.workflowFile}: the product's, checked for the
559
+ * forge, else the workflow's name in the forge's workflow directory
560
+ * (`.gitlab/<name>.gitlab-ci.yml` on GitLab).
561
+ */
562
+ export function productPlanWorkflowFile(forge: ForgeKind, env: string, plan: Pick<ProductPlanOptions, "workflow" | "workflowFile">): string {
563
+ const name = plan.workflow ?? defaultWorkflowName(env);
564
+ const dir = forge === "github" ? ".github/workflows" : forge === "forgejo" ? ".forgejo/workflows" : ".gitlab";
565
+ const file = plan.workflowFile;
566
+ if (file === undefined) return forge === "gitlab" ? `${dir}/${name}.gitlab-ci.yml` : `${dir}/${name}.yml`;
567
+ if (!/\.ya?ml$/.test(file)) throw new Error(`the product plan's workflowFile ${JSON.stringify(file)} is not a .yml or .yaml file`);
568
+ if (file.startsWith("/") || file.split("/").some((part) => part === "" || part === "." || part === "..") || !/^[A-Za-z0-9_.\/-]+$/.test(file)) {
569
+ throw new Error(`the product plan's workflowFile ${JSON.stringify(file)} is not a path from the repository root of letters, digits and _.-, inside it`);
570
+ }
571
+ if (forge !== "gitlab" && (!file.startsWith(`${dir}/`) || file.slice(dir.length + 1).includes("/"))) throw new Error(`the product plan's workflowFile ${JSON.stringify(file)} is not directly under ${dir}/, where ${forge === "github" ? "GitHub" : "Forgejo"} reads workflows`);
572
+ return file;
478
573
  }
479
574
 
480
575
  const TARGET_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
@@ -526,6 +621,17 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
526
621
  seen.add(t.name);
527
622
  }
528
623
  const github = forge !== "gitlab";
624
+ // #5003: the product's own names, checked before any job is written.
625
+ if (plan.workflowFile !== undefined) productPlanWorkflowFile(forge, env, plan);
626
+ const reportDir = plan.reportDir;
627
+ if (reportDir !== undefined && !isReportDir(reportDir)) throw new Error(`the product plan's reportDir ${JSON.stringify(reportDir)} is not a directory from the checkout's root that stays inside it: letters, digits and _.-, parts joined by /, with no . or .. part and no / at either end`);
628
+ const outputDir = reportDir ?? PR_LOOP_REPORT_DIR;
629
+ const statusContext = plan.statusContext;
630
+ if (statusContext !== undefined) {
631
+ if (!/^[A-Za-z0-9][A-Za-z0-9_.\/:{}-]*$/.test(statusContext) || /[{}]/.test(statusContext.replaceAll("{target}", ""))) throw new Error(`the product plan's statusContext ${JSON.stringify(statusContext)} is not a status context of letters, digits and _./:-${targets ? ", with {target}" : ""}`);
632
+ if (Boolean(targets) !== statusContext.includes("{target}")) throw new Error(targets ? `the product plan's statusContext ${JSON.stringify(statusContext)} is every target's, so it holds {target}` : `the product plan's statusContext ${JSON.stringify(statusContext)} holds {target}, and the plan has no targets`);
633
+ }
634
+ const namesOf = productPlanJobNames(forge, plan, targets?.map((t) => t.name));
529
635
  const shared = prLoopPassedEnv(forge, loop);
530
636
  const jobEnv = plan.env ? prLoopPassedEnv(forge, { variables: plan.env }) : {};
531
637
  for (const key of Object.keys(jobEnv)) {
@@ -571,19 +677,24 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
571
677
  ...(plan.noteWords ? { [PR_PLAN_NOTE_WORDS_ENV]: JSON.stringify(plan.noteWords) } : {}),
572
678
  ...(plan.watches?.length ? { [PLAN_WATCHES_ENV]: JSON.stringify(plan.watches) } : {}),
573
679
  };
574
- const fill = (line: string, name: string | undefined): string => line.replaceAll("{target}", name ?? env).replaceAll("{output}", PR_LOOP_REPORT_DIR);
680
+ const fill = (line: string, name: string | undefined): string => line.replaceAll("{target}", name ?? env).replaceAll("{output}", outputDir);
575
681
  const control = plan.controlRead ? controlNoteCheckout(forge, plan.controlRead, words) : undefined;
576
682
  const one = (target?: ProductPlanTarget): ProductPlanJob => {
577
683
  const name = target?.name;
578
- const jobName = github ? (name ? `plan-${name}` : "plan") : gitlabPlanJobName(name);
579
- const noteJobName = github ? (name ? `${PR_PLAN_NOTE_JOB}-${name}` : PR_PLAN_NOTE_JOB) : name ? `${name}-${PR_PLAN_NOTE_JOB}` : PR_PLAN_NOTE_JOB;
684
+ const names = namesOf(name);
685
+ const jobName = names.plan;
686
+ const noteJobName = names.note;
687
+ // #5003: the product's status context, and on GitLab its plan job's name for `pr-post --open` to find.
688
+ const context = statusContext?.replaceAll("{target}", name ?? "");
689
+ const named = [...(context !== undefined ? ["--context", context] : []), ...(!github && jobName !== gitlabPlanJobName(name) ? ["--plan-job", jobName] : [])];
690
+ const withNames = <T extends { command: string }>(p: T): T => (named.length > 0 ? { ...p, command: `${p.command} ${named.join(" ")}` } : p);
580
691
  const own = target ? prLoopPassedEnv(forge, { ...(target.variables ? { variables: target.variables } : {}), ...(target.secrets ? { secrets: target.secrets } : {}) }) : {};
581
692
  for (const key of Object.keys(own)) {
582
693
  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`);
583
694
  if (key in jobEnv) throw new Error(`target ${name}'s ${key} is the product plan's env too; give it once`);
584
695
  }
585
696
  // #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 } : {});
697
+ const post0 = withNames(prLoopPostJob(forge, env, name, words, { ...(loop.staleNotes ? { staleNotes: true } : {}), ...(reportDir !== undefined ? { output: reportDir } : {}) }));
587
698
  // #4899: the note job records the plan job's run, named by that job.
588
699
  const post1 = plan.record ? { ...post0, command: `${post0.command} --record-run ${jobName}` } : post0;
589
700
  // #4914: on GitLab the signing job of the same pipeline keeps each merge request's evidence, which the note's checks line reads.
@@ -608,11 +719,30 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
608
719
  }
609
720
  const idTokens = { ...(login?.idTokens ?? {}), ...tradeTokens, ...(ownTokens ?? {}) };
610
721
  const artifact = plan.artifact ? (name ? `${plan.artifact}-${name}` : plan.artifact) : name ? `chant-pr-plan-${name}` : "chant-pr-plan";
722
+ // #5004: on GitLab the plan job's own paths and reports beside the report directory, such as terragucci's terraform report.
723
+ const given = plan.artifacts;
724
+ const artifacts = given
725
+ ? gitlabJobArtifacts(
726
+ forge,
727
+ {
728
+ ...(given.paths ? { paths: given.paths.map((p) => fill(p, name)) } : {}),
729
+ ...(given.reports ? { reports: Object.fromEntries(Object.entries(given.reports).map(([type, p]) => [type, Array.isArray(p) ? p.map((q) => fill(q, name)) : fill(p, name)])) } : {}),
730
+ },
731
+ { job: "the product plan", last: "the plan verb is the plan job's last step" },
732
+ )
733
+ : undefined;
611
734
  // #4963: on GitHub and Forgejo the first re-plan job replies to the comments no other job takes.
612
735
  const replies = github && Boolean(replanOpts.reply) && (targets === undefined || target === targets[0]);
613
736
  const replan0 = replanComments
614
737
  ? {
615
- ...replanJobOf(forge, env, words, name, artifact, noteWords, { notAffected: replanOpts.notAffected === true, ...(loop.staleNotes ? { staleNotes: true } : {}) }),
738
+ ...replanJobOf(forge, env, words, name, artifact, noteWords, {
739
+ notAffected: replanOpts.notAffected === true,
740
+ ...(loop.staleNotes ? { staleNotes: true } : {}),
741
+ jobName: names.replan,
742
+ noteJobName: names.replanNote,
743
+ ...(reportDir !== undefined ? { output: reportDir } : {}),
744
+ ...(context !== undefined ? { context } : {}),
745
+ }),
616
746
  ...replanComments,
617
747
  ...(github && dispatchArg !== undefined ? { dispatch: { argument: dispatchArg } } : {}),
618
748
  ...(replies ? { reply: { prefix: `/${words.product}`, others } } : {}),
@@ -635,11 +765,11 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
635
765
  ...(planRunner !== undefined ? { runner: planRunner } : {}),
636
766
  ...(noteRunner !== undefined ? { noteRunner } : {}),
637
767
  // #4978: a target's plan job plans that target alone, so its checks are `plan:<target>` and `policy:<target>`.
638
- ...(evidence ? { evidence: planEvidenceOf(forge, evidence, words, jobName, { ...(plan.forks === "skip" ? { noForks: true } : {}), ...(name ? { member: { name, reportPath: PR_LOOP_REPORT_DIR } } : {}) }) } : {}),
768
+ ...(evidence ? { evidence: planEvidenceOf(forge, evidence, words, jobName, { ...(plan.forks === "skip" ? { noForks: true } : {}), ...(name ? { member: { name, reportPath: outputDir } } : {}), ...(reportDir !== undefined ? { dir: reportDir } : {}) }) } : {}),
639
769
  ...(Object.keys(jobEnv).length > 0 ? { jobEnv } : {}),
640
770
  ...(login && login.steps.length > 0 ? { login: login.steps } : {}),
641
771
  ...(Object.keys(idTokens).length > 0 ? { idTokens } : {}),
642
- ...(plan.pending && github ? { pending: { context: productStatusContext(words, "plan", name), description: "planning" } } : {}),
772
+ ...(plan.pending && github ? { pending: { context: context ?? productStatusContext(words, "plan", name), description: "planning" } } : {}),
643
773
  ...(control ? { control } : {}),
644
774
  ...(plan.setup?.length ? { setup: plan.setup } : {}),
645
775
  ...(plan.report ? { report: fill(plan.report, name) } : {}),
@@ -648,11 +778,62 @@ export function productPlanJobs(forge: ForgeKind, env: string, loop: PrLoopPipel
648
778
  ...(record ? { record } : {}),
649
779
  ...(tradeSpec ? { trade: tradeSpec } : {}),
650
780
  ...(plan.previousMarker && productMarker ? { previous: { marker: prNoteMarker(env, name), name: productMarker } } : {}),
781
+ ...(context !== undefined ? { context } : {}),
782
+ ...(reportDir !== undefined ? { reportDir } : {}),
783
+ ...(artifacts ? { artifacts } : {}),
651
784
  };
652
785
  };
653
786
  return targets ? targets.map(one) : [one()];
654
787
  }
655
788
 
789
+ /** Whether `dir` is a report directory a product plan takes (#5003): a relative path that stays in the checkout. */
790
+ function isReportDir(dir: string): boolean {
791
+ return /^[A-Za-z0-9_.\/-]+$/.test(dir) && !dir.startsWith("-") && dir.split("/").every((part) => part !== "" && part !== "." && part !== "..");
792
+ }
793
+
794
+ /** GitLab's top-level keywords, which no job may be named (#5003). */
795
+ const GITLAB_KEYWORDS = new Set(["default", "include", "stages", "variables", "workflow", "image", "services", "cache", "before_script", "after_script", "spec", "pages"]);
796
+
797
+ /**
798
+ * The plan jobs' names for each target (#5003), from
799
+ * {@link ProductPlanOptions.jobNames}, else chant's. Throws on a name that
800
+ * is not one, a `{target}` given without targets or left out with them, and
801
+ * two jobs of the plan that share a name.
802
+ */
803
+ function productPlanJobNames(forge: ForgeKind, plan: Pick<ProductPlanOptions, "jobNames" | "replan">, targets: string[] | undefined): (target?: string) => { plan: string; note: string; replan: string; replanNote: string } {
804
+ const github = forge !== "gitlab";
805
+ const given = plan.jobNames ?? {};
806
+ const chant = { plan: "plan", note: PR_PLAN_NOTE_JOB, replan: REPLAN_JOB, replanNote: REPLAN_NOTE_JOB };
807
+ const keys = ["plan", "note", "replan", "replanNote"] as const;
808
+ for (const key of keys) {
809
+ const t = given[key];
810
+ if (t === undefined) continue;
811
+ if (Boolean(targets) !== t.includes("{target}")) throw new Error(targets ? `the product plan's jobNames.${key} ${JSON.stringify(t)} names every target's job, so it holds {target}` : `the product plan's jobNames.${key} ${JSON.stringify(t)} holds {target}, and the plan has no targets`);
812
+ }
813
+ const namesOf = (target?: string) => {
814
+ const out = {} as Record<(typeof keys)[number], string>;
815
+ for (const key of keys) {
816
+ const t = given[key];
817
+ // chant's: `plan-<target>` on GitHub and Forgejo, `<target>-plan` on GitLab.
818
+ out[key] = t !== undefined ? t.replaceAll("{target}", target ?? "") : target ? (github ? `${chant[key]}-${target}` : `${target}-${chant[key]}`) : chant[key];
819
+ }
820
+ return out;
821
+ };
822
+ const seen = new Map<string, string>();
823
+ for (const target of targets ?? [undefined]) {
824
+ const names = namesOf(target);
825
+ for (const key of plan.replan ? keys : (["plan", "note"] as const)) {
826
+ const n = names[key];
827
+ const ok = github ? /^[A-Za-z_][A-Za-z0-9_-]*$/.test(n) : /^[A-Za-z0-9_][A-Za-z0-9_-]*$/.test(n) && !GITLAB_KEYWORDS.has(n);
828
+ if (!ok) throw new Error(`the product plan's ${given[key] !== undefined ? `jobNames.${key}` : `${key} job`} ${JSON.stringify(n)} is not a job name of letters, digits, _ and -, starting with a letter or _${github ? "" : " or a digit, and no GitLab keyword"}`);
829
+ const other = seen.get(n);
830
+ if (other !== undefined) throw new Error(`the product plan names two jobs ${n}: ${other} and ${key}${target ? ` of ${target}` : ""}`);
831
+ seen.set(n, `${key}${target ? ` of ${target}` : ""}`);
832
+ }
833
+ }
834
+ return namesOf;
835
+ }
836
+
656
837
  /** The comments the re-plan answers (#4899): the plan command, then the words' aliases for it. Refused when the words name no plan command. */
657
838
  function replanCommentsOf(words: CiProductWords): { comments: string[]; gated: Array<{ comment: string; when: string }> } {
658
839
  const command = commentLine(words, "plan");
@@ -662,16 +843,25 @@ function replanCommentsOf(words: CiProductWords): { comments: string[]; gated: A
662
843
  }
663
844
 
664
845
  /** The re-plan's jobs for one target (#4899), its comments filled in by the caller. */
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"> {
846
+ function replanJobOf(
847
+ forge: ForgeKind,
848
+ env: string,
849
+ words: CiProductWords,
850
+ name: string | undefined,
851
+ artifact: string,
852
+ noteWords0: Record<string, string>,
853
+ opts: { notAffected?: boolean; staleNotes?: boolean; jobName: string; noteJobName: string; output?: string; context?: string },
854
+ ): Omit<ProductPlanReplanJob, "comments" | "gated"> {
666
855
  const github = forge !== "gitlab";
667
- const jobName = github ? (name ? `${REPLAN_JOB}-${name}` : REPLAN_JOB) : name ? `${name}-${REPLAN_JOB}` : REPLAN_JOB;
668
- const noteJobName = github ? (name ? `${REPLAN_NOTE_JOB}-${name}` : REPLAN_NOTE_JOB) : name ? `${name}-${REPLAN_NOTE_JOB}` : REPLAN_NOTE_JOB;
856
+ const { jobName, noteJobName } = opts;
669
857
  // 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.
670
858
  // #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 ");
859
+ // #5003: the product's report directory and status context.
860
+ const post0 = { ...(opts.staleNotes ? { staleNotes: true } : {}), ...(opts.output !== undefined ? { output: opts.output } : {}) };
861
+ const command0 = github ? prLoopPostJob(forge, env, name, words, post0).command : prLoopPostJob("github", env, name, words, post0).command.replace(" --forge github ", " --forge gitlab ");
862
+ const command1 = opts.context !== undefined ? `${command0} --context ${opts.context}` : command0;
673
863
  // #4963: the argument the re-plan was narrowed to, which pr-post answers "not affected" for when the change does not reach it.
674
- const command = opts.notAffected ? `${command0} --not-affected "$${PLAN_ARGUMENT_ENV}"` : command0;
864
+ const command = opts.notAffected ? `${command1} --not-affected "$${PLAN_ARGUMENT_ENV}"` : command1;
675
865
  const noteWords1 = opts.notAffected && github ? { ...noteWords0, [PLAN_ARGUMENT_ENV]: `\${{ needs.${jobName}.outputs.argument }}` } : noteWords0;
676
866
  const noteWords = opts.staleNotes ? { ...noteWords1, TIP_SHA: github ? "${{ github.sha }}" : "$CI_COMMIT_SHA" } : noteWords1;
677
867
  const post = github
@@ -877,7 +1067,7 @@ export const PENDING_JS = [
877
1067
  * report line whatever the verb's exit, then the step exits with the verb's
878
1068
  * status. Without a report line, the verb alone.
879
1069
  */
880
- export function planVerbLines(p: Pick<ProductPlanJob, "command" | "report" | "record">): string[] {
1070
+ export function planVerbLines(p: Pick<ProductPlanJob, "command" | "report" | "record" | "reportDir">): string[] {
881
1071
  if (!p.report && !p.record) return [p.command];
882
1072
  return [
883
1073
  ...(p.record ? ['chant_plan_started="$(date -u +%Y-%m-%dT%H:%M:%SZ)"'] : []),
@@ -885,7 +1075,7 @@ export function planVerbLines(p: Pick<ProductPlanJob, "command" | "report" | "re
885
1075
  `${p.command} || chant_plan_exit=$?`,
886
1076
  ...(p.report ? [`${p.report} || echo "chant: the report line exited $?" >&2`] : []),
887
1077
  // #4899: the run record goes into the hand-off, for the note job to keep on chant/lifecycle.
888
- ...(p.record ? [`CHANT_PLAN_EXIT="$chant_plan_exit" CHANT_PLAN_STARTED="$chant_plan_started" node -e '${PLAN_RECORD_JS}' ${PR_LOOP_REPORT_DIR} || echo "chant: the plan's run record was not written" >&2`] : []),
1078
+ ...(p.record ? [`CHANT_PLAN_EXIT="$chant_plan_exit" CHANT_PLAN_STARTED="$chant_plan_started" node -e '${PLAN_RECORD_JS}' ${productPlanReportDir(p)} || echo "chant: the plan's run record was not written" >&2`] : []),
889
1079
  '[ "$chant_plan_exit" -eq 0 ] || exit "$chant_plan_exit"',
890
1080
  ];
891
1081
  }
@@ -917,25 +1107,27 @@ export const PLAN_RECORD_JS = [
917
1107
  * #4978: a product plan target's plan job is signed the same way, under the
918
1108
  * target's name.
919
1109
  */
920
- export function planEvidenceOf(forge: ForgeKind, evidence: PipelineEvidence, words: CiProductWords, planJob: string, opts: { noForks?: boolean; member?: { name: string; reportPath: string } } = {}): NonNullable<ProductPlanJob["evidence"]> {
1110
+ export function planEvidenceOf(forge: ForgeKind, evidence: PipelineEvidence, words: CiProductWords, planJob: string, opts: { noForks?: boolean; member?: { name: string; reportPath: string }; dir?: string } = {}): NonNullable<ProductPlanJob["evidence"]> {
921
1111
  assertPipelineEvidence(evidence);
922
1112
  const key = evidenceKeyEnv(forge, evidence);
923
1113
  const bin = words.bin;
924
1114
  const member = opts.member ? { member: opts.member.name } : {};
1115
+ // #5003: the product plan's report directory, which the plan job handed on.
1116
+ const reportDir = opts.dir ?? PR_LOOP_REPORT_DIR;
925
1117
  if (forge === "gitlab") {
926
1118
  // #4914: the job runs in the target branch's plan notes pipeline, before the note job, and signs every open
927
1119
  // merge request's settled plan job from its artifact; no job of a merge request pipeline holds the key.
928
1120
  const dir = gitlabOpenEvidenceDir(planJob);
929
1121
  return {
930
1122
  jobName: `${planJob}-evidence`,
931
- lines: openEvidenceLines({ job: planJob, dir: opts.member?.reportPath ?? PR_LOOP_REPORT_DIR, out: dir, ...(bin ? { bin } : {}), ...(opts.noForks ? { noForks: true } : {}), ...member }),
1123
+ lines: openEvidenceLines({ job: planJob, dir: opts.member?.reportPath ?? reportDir, out: dir, ...(bin ? { bin } : {}), ...(opts.noForks ? { noForks: true } : {}), ...member }),
932
1124
  env: key,
933
1125
  dir,
934
1126
  ...(evidenceKeyless(evidence) ? { idTokens: evidenceIdTokens(evidence) } : {}),
935
1127
  };
936
1128
  }
937
1129
  return {
938
- lines: planEvidenceLines({ dir: PR_LOOP_REPORT_DIR, at: '"$HEAD_SHA"', base: '"$BASE_SHA"', result: '"$PLAN_RESULT"', ...(bin ? { bin } : {}), ...member }),
1130
+ lines: planEvidenceLines({ dir: reportDir, at: '"$HEAD_SHA"', base: '"$BASE_SHA"', result: '"$PLAN_RESULT"', ...(bin ? { bin } : {}), ...member }),
939
1131
  env: { HEAD_SHA: "${{ github.sha }}", BASE_SHA: "${{ github.event.pull_request.base.sha }}", PLAN_RESULT: `\${{ needs.${planJob}.result }}`, ...key },
940
1132
  ...(evidenceKeyless(evidence) ? { idToken: true as const } : {}),
941
1133
  };
@@ -38,18 +38,20 @@ export const FLOOR_ROWS: readonly FloorRow[] = [
38
38
  { name: "COMMENT_COMMANDS_FLOOR", version: "0.124.89", gates: "The first chant with the comment job on GitHub and Forgejo and the replies to commands no job runs (#4946): `commentJob` in the product pipeline (`chant components pr-comment`, `answerProductComment` in `@intentius/chant/ci-comment-commands`), which replies to a refusal and to a command the pipeline runs no job for, and with waves on merge starts a merged pull request's apply again; the words' `replies` and an alias's `refuse`, which the GitLab note poll reads too, as `chantNoteRuns`' `members`; `retryApply`; and `locks: \"plan\"` in GitHub's and Forgejo's product plan, with the lock, unlock and comment lock jobs.", issue: "#4946", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
39
39
  { name: "PRODUCT_PLAN_REACH_LOCKS_FLOOR", version: "0.124.89", gates: "The first chant whose product plan locks what a change reaches (#4979): `productPlan.reach`, a reach line the lock job runs at the target branch's commit with `chant lock --reach` (`@intentius/chant/lifecycle/reach-locks`), on GitHub, Forgejo and GitLab, where the lock job runs in the plan notes pipeline with `--open` beside the comment lock and unlock jobs; and whose comment job answers a re-plan comment with flags the product plan's re-plan cannot take (`noPlanFlags`).", issue: "#4979", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
40
40
  { name: "WAVE_STOP_FLOOR", version: "0.124.89", gates: "The first chant whose comment job stops a merged pull request's re-run at a wave (#4979): `/<product> apply wave-<n>` writes a stop for the merge commit on `chant/lifecycle` (`_waves/<op>.stops.json`, `@intentius/chant/op/wave-stop`) before GitHub's re-run or Forgejo's dispatch, and `chant run wave` leaves each wave after n waiting (exit 3).", issue: "#4979", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
41
- { name: "WAVES_BEFORE_MERGE_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves run before merge (#4984): `wavesBeforeMerge` in the product pipeline, where the comment job (GitHub, Forgejo) or the note poll (GitLab) decides `/<product> apply [wave-<n>]` on an open pull request (`decideWavesBeforeMerge`, `@intentius/chant/op/before-merge-decide`), records the head and its digest on `chant/lifecycle` (`_waves/<op>.before-merge.json`) and starts the waves for it; the generators' `beforeMerge`, whose guard admits that head alone, whose jobs check it out and read the base from the default branch, and whose `before-merge-done` job merges and releases the locks (`chant run wave --merge`); `waveJobs.<wave>.prelude`; the GitLab note poll's wave stop (`chantNoteRuns`' `waves`); a re-plan word that never starts with `-`; and the terraform lexicon's reach helpers (`@intentius/chant-lexicon-terraform/reach`).", issue: "#4984", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
42
- { name: "WAVES_APPLY_STATUS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves post the apply statuses (#4987): the generators' `applyStatus`, a job `apply-status-<n>` after each wave at the default branch's commit that posts `<product>/apply` on the commit the waves applied (a before-merge run's decided head) with `chant run wave --apply-status` (`@intentius/chant/op/apply-status`), and the product pipeline's `applyStatus`; whose product plan takes `staleNotes`, each target's note carrying the target branch's commit and a `stale-notes` job beside wave 1 on a push marking each target's note (`pr-post --stale` with one `--member` per target); whose `productPipelineJobs` returns `waves.pipeline` for the generators; and whose GitLab reach line reaches the lock and note-commands jobs unexpanded (`expand: false`).", issue: "#4987", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
43
- { name: "WAVES_BEFORE_MERGE_SPLIT_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose before-merge waves never run the change's code beside a write token (#4987): with `beforeMerge` each wave is a plan job (the change's code, a checkout with no credentials kept, a read-only token; GitLab drops `CHANT_FORGE_TOKEN` and the job token), a gate job at the default branch with the token, an applying job on the saved plan with no write token, and a record job at the default branch that writes the run records (`chant run wave --phase plan|gate|apply|record`, `@intentius/chant/op/op-waves-split`).", issue: "#4987", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
44
- { name: "WAVES_BEFORE_MERGE_STEP_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose split before-merge waves take a `step` spec, Forgejo's hand-off, holds on other gates and one approval per wave (#4992): the plan job saves each run's step plan, the gate job leases the rows they change (no heartbeat; the decision names the lease) before it spends the approval, the applying job plans its runs again through the step and applies each whose digest the decision holds, and the record job writes the release records and lets go of the rows; a hook in the plan or apply job that holds the wave on another gate reads it with no write token and leaves its pending fact to the gate or record job; on Forgejo the plan and applying jobs hand their files on as job outputs (`packJs`), never through the artifact upload, and the gate and record jobs keep them as the artifacts; the plan job names no environment on GitHub (a wave's `planEnvironment` when set; on GitLab it prepares it), so the environment's reviewers are asked once.", issue: "#4992", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
45
- { name: "WAVES_PRODUCT_HOOKS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose split waves run a product's own process in every job (#4994): the product wave hook's `hooks` (`runChantInProcess([\"run\", \"wave\", ..., \"--phase\", <phase>], words, { wave: { afterPlan, capabilities, hookExec, runHooks, hooks } })`, `RunOpWaveOptions.inProcessHooks`) serves a spec hook by its name in the process of whichever job runs it, plan, gate or applying job or the one-job shape, in place of a command that called back over a socket; `opWaveProductStateDir` is where the plan job's code keeps what the later jobs read; a `record: true` hold in the plan job is spent by the gate job for a re-run of the hook at the wave's commit (an applied line with `rerun.head`), which the next run's plan job runs and its gate job finishes (`holdsFinished`); and `waveJobs.<wave>.artifact.path` takes a list and `waveJobs.<wave>.gate` gives the gate job a report and an artifact, so a product's own upload steps go through chant's Forgejo hand-off.", issue: "#4994", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
46
- { name: "WAVES_BEFORE_MERGE_REST_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose split before-merge waves take a `rest` wave (#4992): its four jobs run one wave per run, the wave `CHANT_WAVES_WAVE` names (their own by default), and its record job, once the run applied and the plan found another wave, starts the waves workflow again for it (GitHub and Forgejo: a dispatch with the inputs `wave` and the decision's `pr`, `head` and `digest`, or a push's `commit`; GitLab: a pipeline with the same variables, with `CHANT_FORGE_TOKEN`), whose guard admits it as the same decided head; the jobs of the waves before it do not run in that follow-on; the record job's note (`rest-wave.json` beside the outcomes, `@intentius/chant/op/op-waves-follow-on`) tells `before-merge-done`, the control dispatch and the apply status that a run which started a follow-on is not the last.", issue: "#4992", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
47
- { name: "WAVES_FOLLOW_ON_RECORD_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose rest wave's record job records each follow-on it starts on `chant/lifecycle` before it starts it (#4998): `_waves/<op>.follow-on.json` keeps, per decided head or pushed commit, the wave started, the run that started it, the decision (`pr`, `digest`) or the `commit`, and the outcomes of every run of the chain so far; the guard admits a follow-on only for the wave that record names, so a wave started by hand past it is refused; and the last run's control dispatch, apply status and `before-merge-done` add up the outcomes of every run of the chain (the note's `chain`), so a chain whose last wave changed nothing reports `applied`.", issue: "#4998", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
41
+ { name: "WAVES_BEFORE_MERGE_FLOOR", version: "0.124.90", gates: "The first chant whose Op waves run before merge (#4984): `wavesBeforeMerge` in the product pipeline, where the comment job (GitHub, Forgejo) or the note poll (GitLab) decides `/<product> apply [wave-<n>]` on an open pull request (`decideWavesBeforeMerge`, `@intentius/chant/op/before-merge-decide`), records the head and its digest on `chant/lifecycle` (`_waves/<op>.before-merge.json`) and starts the waves for it; the generators' `beforeMerge`, whose guard admits that head alone, whose jobs check it out and read the base from the default branch, and whose `before-merge-done` job merges and releases the locks (`chant run wave --merge`); `waveJobs.<wave>.prelude`; the GitLab note poll's wave stop (`chantNoteRuns`' `waves`); a re-plan word that never starts with `-`; and the terraform lexicon's reach helpers (`@intentius/chant-lexicon-terraform/reach`).", issue: "#4984", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
42
+ { name: "WAVES_APPLY_STATUS_FLOOR", version: "0.124.90", gates: "The first chant whose Op waves post the apply statuses (#4987): the generators' `applyStatus`, a job `apply-status-<n>` after each wave at the default branch's commit that posts `<product>/apply` on the commit the waves applied (a before-merge run's decided head) with `chant run wave --apply-status` (`@intentius/chant/op/apply-status`), and the product pipeline's `applyStatus`; whose product plan takes `staleNotes`, each target's note carrying the target branch's commit and a `stale-notes` job beside wave 1 on a push marking each target's note (`pr-post --stale` with one `--member` per target); whose `productPipelineJobs` returns `waves.pipeline` for the generators; and whose GitLab reach line reaches the lock and note-commands jobs unexpanded (`expand: false`).", issue: "#4987", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
43
+ { name: "WAVES_BEFORE_MERGE_SPLIT_FLOOR", version: "0.124.90", gates: "The first chant whose before-merge waves never run the change's code beside a write token (#4987): with `beforeMerge` each wave is a plan job (the change's code, a checkout with no credentials kept, a read-only token; GitLab drops `CHANT_FORGE_TOKEN` and the job token), a gate job at the default branch with the token, an applying job on the saved plan with no write token, and a record job at the default branch that writes the run records (`chant run wave --phase plan|gate|apply|record`, `@intentius/chant/op/op-waves-split`).", issue: "#4987", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
44
+ { name: "WAVES_BEFORE_MERGE_STEP_FLOOR", version: "0.124.90", gates: "The first chant whose split before-merge waves take a `step` spec, Forgejo's hand-off, holds on other gates and one approval per wave (#4992): the plan job saves each run's step plan, the gate job leases the rows they change (no heartbeat; the decision names the lease) before it spends the approval, the applying job plans its runs again through the step and applies each whose digest the decision holds, and the record job writes the release records and lets go of the rows; a hook in the plan or apply job that holds the wave on another gate reads it with no write token and leaves its pending fact to the gate or record job; on Forgejo the plan and applying jobs hand their files on as job outputs (`packJs`), never through the artifact upload, and the gate and record jobs keep them as the artifacts; the plan job names no environment on GitHub (a wave's `planEnvironment` when set; on GitLab it prepares it), so the environment's reviewers are asked once.", issue: "#4992", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
45
+ { name: "WAVES_PRODUCT_HOOKS_FLOOR", version: "0.124.90", gates: "The first chant whose split waves run a product's own process in every job (#4994): the product wave hook's `hooks` (`runChantInProcess([\"run\", \"wave\", ..., \"--phase\", <phase>], words, { wave: { afterPlan, capabilities, hookExec, runHooks, hooks } })`, `RunOpWaveOptions.inProcessHooks`) serves a spec hook by its name in the process of whichever job runs it, plan, gate or applying job or the one-job shape, in place of a command that called back over a socket; `opWaveProductStateDir` is where the plan job's code keeps what the later jobs read; a `record: true` hold in the plan job is spent by the gate job for a re-run of the hook at the wave's commit (an applied line with `rerun.head`), which the next run's plan job runs and its gate job finishes (`holdsFinished`); and `waveJobs.<wave>.artifact.path` takes a list and `waveJobs.<wave>.gate` gives the gate job a report and an artifact, so a product's own upload steps go through chant's Forgejo hand-off.", issue: "#4994", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
46
+ { name: "WAVES_BEFORE_MERGE_REST_FLOOR", version: "0.124.90", gates: "The first chant whose split before-merge waves take a `rest` wave (#4992): its four jobs run one wave per run, the wave `CHANT_WAVES_WAVE` names (their own by default), and its record job, once the run applied and the plan found another wave, starts the waves workflow again for it (GitHub and Forgejo: a dispatch with the inputs `wave` and the decision's `pr`, `head` and `digest`, or a push's `commit`; GitLab: a pipeline with the same variables, with `CHANT_FORGE_TOKEN`), whose guard admits it as the same decided head; the jobs of the waves before it do not run in that follow-on; the record job's note (`rest-wave.json` beside the outcomes, `@intentius/chant/op/op-waves-follow-on`) tells `before-merge-done`, the control dispatch and the apply status that a run which started a follow-on is not the last.", issue: "#4992", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
47
+ { name: "WAVES_FOLLOW_ON_RECORD_FLOOR", version: "0.124.90", gates: "The first chant whose rest wave's record job records each follow-on it starts on `chant/lifecycle` before it starts it (#4998): `_waves/<op>.follow-on.json` keeps, per decided head or pushed commit, the wave started, the run that started it, the decision (`pr`, `digest`) or the `commit`, and the outcomes of every run of the chain so far; the guard admits a follow-on only for the wave that record names, so a wave started by hand past it is refused; and the last run's control dispatch, apply status and `before-merge-done` add up the outcomes of every run of the chain (the note's `chain`), so a chain whose last wave changed nothing reports `applied`.", issue: "#4998", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
48
48
  { name: "PRODUCT_PLAN_WATCHES_FLOOR", version: "0.124.88", gates: "The first chant whose product plan takes `watches`, the product's own scheduled jobs the note job's `pr-post` checks for having stopped with the job's token (#4888), and whose `checkOverdueOps` and `overdueOpsAt` take a product's `logPrefix` and `label`.", issue: "#4888", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
49
- { name: "PRODUCT_PLAN_WATCH_TARGETS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose product plan's `watches` take `targets` (#4988): a watch scoped to those targets is checked by their notes alone, and the note of another target checks neither it nor the discovered Op of its name (`watchesForTarget`).", issue: "#4988", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
49
+ { name: "PRODUCT_PLAN_WATCH_TARGETS_FLOOR", version: "0.124.90", gates: "The first chant whose product plan's `watches` take `targets` (#4988): a watch scoped to those targets is checked by their notes alone, and the note of another target checks neither it nor the discovered Op of its name (`watchesForTarget`).", issue: "#4988", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
50
50
  { name: "PRODUCT_PLAN_RECORD_FLOOR", version: "0.124.88", gates: "The first chant whose product plan takes `record` (#4899): the plan step writes the plan job's run record into the hand-off, and the note job keeps it as Op `pr-plan` on `chant/lifecycle` with `pr-post --record-run <plan job>` (`--open` on GitLab), as `chant ci run plan --in-place` records `pr-plan`'s.", issue: "#4899", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
51
51
  { name: "PRODUCT_PLAN_REPLAN_FLOOR", version: "0.124.89", gates: "The first chant whose product plan carries what terragucci's and sql-yodeler's plan jobs did themselves (#4963, #4951): `trade` (a plan's or a target's) before the checkout, `replan: { dispatch, reply, notAffected }` (a re-plan from `workflow_dispatch`, a reply to a comment no other job takes, `pr-post --not-affected`), `previousMarker` (`CHANT_PLAN_PREVIOUS_MARKER`), `noteSteps.pullRequest`, a `PrReport`'s `marker`, and a hand-off of the product's own note text (`planBodyHandoff`).", issue: "#4963", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
52
52
  { name: "PRODUCT_PLAN_SUBJECT_FLOOR", version: "0.124.89", gates: "The first chant whose note job compares the plan's subject with the previous note's (#4972), on GitHub, Forgejo and GitLab: a plan note hand-off's `subject` (`PrPlanSubject`, an id and named parts) is kept in the note, and `pr-post` adds the note words' `sinceLast` line, naming the parts added, gone and changed (`subjectParts`), when the previous note kept another id.", issue: "#4972", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
53
+ { name: "PRODUCT_PLAN_NAMES_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose product plan keeps a product's own names (#5003): `workflowFile` (the generators' `path`), `jobNames` (the plan, note, re-plan and re-plan note jobs, with `{target}`), `statusContext` (which `pr-post --context`, the pending step, the stale job and the apply before merge use) and `reportDir` (`{output}`, the hand-off, the artifact's path and `pr-post --output`), and whose `pr-post --open` finds a plan job of the product's name (`--plan-job`).", issue: "#5003", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
54
+ { name: "PRODUCT_PLAN_ARTIFACTS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose GitLab product plan job keeps a product's own artifacts beside the report directory (#5004): `productPlan.artifacts: { paths, reports }`, as `artifacts:paths` and `artifacts:reports`, such as terragucci's `terraform` report for the merge request's widget, with `{target}` and `{output}` filled.", issue: "#5004", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
53
55
  { name: "PRODUCT_ACTIONS_FLOOR", version: "0.124.58", gates: "Day-2 actions in the product pipeline (#4654): the `action` comment command counted as answered by the product's own workflow (`productPipelineJobs(forge, env, { words, actions: true })`), or the pipeline's own action job (`actionJob`, `build --pr-loop --action-job`), which answers the comment and a dispatch with a member and an action input, and runs the product's action verb with `--from-event`.", issue: "#4654", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
54
56
  { name: "APPROVAL_STATUS_FLOOR", version: "0.124.56", gates: "The approval status before merge (#4630): under a `pr-review` wave, the op waves generators add a job that posts `<product>/approval` on each open pull request's head.", issue: "#4630", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
55
57
  { name: "APPROVAL_STATUS_PULL_REQUEST_FLOOR", version: "0.124.56", gates: "The approval status for `pull-request` waves too (#4630, 2026-10-28 ruling): the generators add the record-plans and approval-status jobs for a spec whose waves take the pull request's own approval, and the status reads that approval's coverage of each wave's change set.", issue: "#4630", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
@@ -211,16 +213,19 @@ export const FLOOR_ROWS: readonly FloorRow[] = [
211
213
  { name: "DRIFT_NOTIFY_STACKS_FLOOR", version: "0.124.89", gates: "The first chant whose `driftNotifyFields` takes `stacks`, each member's drift records, and from them names the drifted members and computes the run's fingerprint (#4944).", issue: "#4944", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
212
214
  { name: "MEMBER_SIGNED_CHECKS_FLOOR", version: "0.124.89", gates: "The first chant whose workspace member's pull request pipeline takes `evidence`, `checkJob` and `refGateStatus` (`chant build --pr-loop` in a member), signing the member's plan job as `plan:<member>` and `policy:<member>` (`ci evidence sign --member`, `memberEvidenceCheck`) and running the check job in the member's directory (#4964).", issue: "#4964", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/components/pr-checks","@intentius/chant/release-floors"] },
213
215
  { name: "PRODUCT_CHECK_JOBS_FLOOR", version: "0.124.89", gates: "The first chant whose `checkJob` takes `{ services, env, before, dir, args }` (`PrCheckJobOptions`: service containers, the check step's variables and lines, the report directory, the arguments after `--base`) and whose github, forgejo and gitlab lexicons render the check, check evidence and ref gate jobs for a product's own workflow (`productCheckJobs`, `forgejoProductCheckJobs`, `gitlabProductCheckJobs`) (#4964).", issue: "#4964", file: "release-floors.ts", modules: ["@intentius/chant/components/pr-checks","@intentius/chant/release-floors"] },
214
- { name: "CHECK_JOB_ARTIFACTS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `checkJob` takes `artifacts: { paths, reports }` (`PrCheckArtifacts`), which GitLab's check job keeps beside its report as `artifacts:paths` and `artifacts:reports`, such as a lint hook's `codequality` report (#4988).", issue: "#4988", file: "release-floors.ts", modules: ["@intentius/chant/components/pr-checks","@intentius/chant/release-floors"] },
216
+ { name: "CHECK_JOB_ARTIFACTS_FLOOR", version: "0.124.90", gates: "The first chant whose `checkJob` takes `artifacts: { paths, reports }` (`PrCheckArtifacts`), which GitLab's check job keeps beside its report as `artifacts:paths` and `artifacts:reports`, such as a lint hook's `codequality` report (#4988).", issue: "#4988", file: "release-floors.ts", modules: ["@intentius/chant/components/pr-checks","@intentius/chant/release-floors"] },
215
217
  { name: "GITLAB_WAVE_KEY_SCOPE_FLOOR", version: "0.124.89", gates: "The first chant whose GitLab Op waves pipeline with a runner key hands it to no wave job: each deciding wave's `<wave job>-evidence` job names the `chant-evidence` environment and signs `plan:<wave>` from the wave job (#4964).", issue: "#4964", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/release-floors"] },
216
218
  { name: "ACTOR_ORDER_FLOOR", version: "0.124.89", gates: "The first chant with `actorOf` and `actorOrder` in `@intentius/chant/actor`: the actor fallback with `GITHUB_TRIGGERING_ACTOR` ahead of the forge's actor and git's `user.name` before the login, each place switched on or off by the caller (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/actor","@intentius/chant/release-floors"] },
219
+ { name: "ACTOR_GIT_ENV_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `actorOf({ env, repo })` runs `git config` in `repo` with the `env` it is given rather than the process's, so a job's `GIT_CONFIG_GLOBAL` or `HOME` picks the `user.name` it reads (#5005).", issue: "#5005", file: "release-floors.ts", modules: ["@intentius/chant/actor","@intentius/chant/release-floors"] },
217
220
  { name: "CI_BASE_REF_FLOOR", version: "0.124.89", gates: "The first chant with `@intentius/chant/ci-base` (`ciBaseRef`), the base a CI job measures a change from (the pull request's target branch, else the default branch for a push to another branch), and whose `chant ci check` defaults `--base` to it (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/ci-base","@intentius/chant/release-floors"] },
218
221
  { name: "PLANNED_FILES_FLOOR", version: "0.124.89", gates: "The first chant with `@intentius/chant/planned-files` (`planFile`, `planRemoval`, `writePlannedFiles`, `staleGeneratedFiles`): an init's planned files with their modes, written or removed in one call, and the generated files a product no longer renders, found by their header (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/planned-files","@intentius/chant/release-floors"] },
222
+ { name: "PLANNED_BYTES_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `planFile` in `@intentius/chant/planned-files` takes bytes (`Uint8Array` or `Buffer`) as well as text: `writePlannedFiles` writes them unchanged and the plan compares them with the file byte for byte (#5006).", issue: "#5006", file: "release-floors.ts", modules: ["@intentius/chant/planned-files","@intentius/chant/release-floors"] },
219
223
  { name: "FORGE_CHECK_OWN_JOBS_FLOOR", version: "0.124.89", gates: "The first chant whose `pipelineContract` takes `jobs`, the jobs a product builds from its own config, beside or in place of `pipelines`, so a product's forge check gets the required statuses and `refGateStatus` from chant (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/forge-check","@intentius/chant/forge-check/index","@intentius/chant/release-floors"] },
220
224
  { name: "BEFORE_MERGE_REF_GATE_FLOOR", version: "0.124.89", gates: "The first chant whose `chant components pr-apply --before-merge` waits for the ref gate's status: the status the policy at base sets for the target branch is passed as `require` to the `checks` require (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
221
225
  { name: "TARGET_SIGNED_CHECKS_FLOOR", version: "0.124.89", gates: "The first chant whose product plan with `targets` and `evidence` signs each target's plan job as `plan:<target>` and `policy:<target>` (`ci evidence sign --member <target>`, `targetEvidenceCheck`, `productPlanEvidenceChecks`), and whose `refGateInitPlan` takes `targets` and names those checks in the `refs` rule (#4978).", issue: "#4978", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/ref-gate-init","@intentius/chant/release-floors"] },
222
226
  { name: "RUNTIME_WAVES_SPEC_FLOOR", version: "0.124.89", gates: "The first chant whose Op waves generators take `renderSpec` (the wave jobs run `chant run wave --render-spec`, and `CHANT_WAVES_SPEC_COMMAND` names the product command that prints the spec at the commit in `CHANT_WAVES_SPEC_AT`), so a product whose spec is built from its config at base renders its wave jobs, policy step, evidence job and cloud trade through chant (#4982).", issue: "#4982", file: "release-floors.ts", modules: ["@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-render-spec","@intentius/chant/release-floors"] },
223
227
  { name: "GITLAB_WAVE_EVIDENCE_RETRY_FLOOR", version: "0.124.89", gates: "The first chant whose `chant run resume` (`resumeGateRun`) on GitLab retries a wave job's `<wave job>-evidence` with the wave job when the evidence job already ran, and whose `ci evidence sign --from-job` waits for a job it reads to finish, so a resumed wave's evidence job signs from the new try (#4978).", issue: "#4978", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/release-floors"] },
228
+ { name: "TERRAFORM_COMMAND_TRACE_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose terraform lexicon's engine runs carry what a product's own command tracing read: `runBinary` and the engine runner's `exec` and `execSync` answer stderr apart (`Ran.stderr`) and a spawn failure's message (`Ran.error`), a hook's `after` gets a binary that could not be started as a null code with `error`, `commandTrace` ends that span with the message, and `composeCommandHooks` runs a product's own hook and `commandTrace` as one `onCommand` (#5007).", issue: "#5007", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
224
229
  { name: "RUN_EVENT_FLOOR", version: "0.124.28", gates: "The first chant that writes contract version 1 of the run-event stream.", file: "run-event.ts", modules: ["@intentius/chant","@intentius/chant/index","@intentius/chant/run-event"] },
225
230
  { name: "RUN_EVENT_FAILURE_FLOOR", version: "0.124.30", gates: "The first chant that writes `failure` on `run-settle` (#4094).", issue: "#4094", file: "run-event.ts", modules: ["@intentius/chant","@intentius/chant/index","@intentius/chant/run-event"] },
226
231
  { name: "RUN_EVENT_COMPONENT_SKIP_FLOOR", version: "0.124.29", gates: "The first chant that writes `blocked`, `already-applied` and `blockedBy` on `component-settle` (#4007).", issue: "#4007", file: "run-event.ts", modules: ["@intentius/chant","@intentius/chant/index","@intentius/chant/run-event"] },
@@ -243,11 +243,15 @@ export function packageNameOf(spec: string): string | undefined {
243
243
  }
244
244
 
245
245
  /** True when `err` says the package `pkg` itself could not be found, not something it imports. */
246
- function isPackageNotFound(err: unknown, pkg: string): boolean {
246
+ export function isPackageNotFound(err: unknown, pkg: string): boolean {
247
247
  const code = (err as { code?: unknown } | null)?.code;
248
248
  if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") return false;
249
249
  const message = err instanceof Error ? err.message : String(err);
250
- return message.includes(`'${pkg}'`) || message.includes(`"${pkg}"`) || message.includes(`${pkg}/`);
250
+ // The specifier itself is quoted: `'pkg'`, or `'pkg/sub'` for a subpath.
251
+ // chant#4881 — a file missing inside an installed package is named by its
252
+ // path (`'/…/node_modules/pkg/generated/index.js'`), which is not quoted at
253
+ // the package name, so it doesn't count as the package being missing.
254
+ return [`'${pkg}'`, `"${pkg}"`, `'${pkg}/`, `"${pkg}/`].some((quoted) => message.includes(quoted));
251
255
  }
252
256
 
253
257
  /**