@intentius/chant-lexicon-gitlab 0.124.31 → 0.124.33

package/src/components/generate-pipeline.ts

@@ -44,7 +44,18 @@ import {
 import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/components/driver";
 import { hasPublishStep, promoteArchivePaths } from "@intentius/chant/components/promote";
 import { GATED_WAVE_RECORD, gatedWaveJobs } from "@intentius/chant/components/gated-wave-pipeline";
-import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prApplyRecordKey, prLoopJobs, prLoopSetup } from "@intentius/chant/components/pr-pipeline";
+import {
+  PR_APPLY_RECORD,
+  PR_LOOP_REPORT_DIR,
+  prApplyGroup,
+  prRecordGroup,
+  prApplyRecordKey,
+  prApplyWaveJobName,
+  prLoopJobs,
+  prLoopSetup,
+  prLoopWaveJobs,
+  prLoopWithWaves,
+} from "@intentius/chant/components/pr-pipeline";
 import { memberGitlabChanges, memberRepoPath, memberShellDir } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineJob as GeneratedJob,
@@ -79,10 +90,10 @@ export function generateGitlabPipeline(
   const byName = new Map(components.map((c) => [c.name, c]));
 
   if (options.prLoop) {
-    if (options.gatedWaves || options.promoteTo !== undefined) {
-      throw new Error("a pull-request pipeline has no wave or promote jobs; drop --wave-gate and --promote-to, or --pr-loop");
-    }
-    return prLoopGitlabPipeline(env, image, beforeScript, extraScript, options);
+    if (options.promoteTo !== undefined) throw new Error("a pull-request pipeline has no promote job; drop --promote-to or --pr-loop");
+    // #4003: --wave-gate beside --pr-loop gives the apply a gate per wave.
+    const prLoop = prLoopWithWaves(options.prLoop, options.gatedWaves);
+    return prLoopGitlabPipeline(components, env, image, beforeScript, extraScript, { ...options, prLoop });
   }
 
   if (options.gatedWaves) {
@@ -262,8 +273,8 @@ function gatedWaveGitlabPipeline(
 
 /**
  * The merge-request pipeline (#3183): `plan` in each merge request pipeline,
- * `apply` on each push to the target branch, one apply at a time per
- * environment (`resource_group`). `GIT_DEPTH: "0"` gives both the history
+ * and on each push to the target branch `record` (#4168), or `apply` with
+ * `applyOnMerge`, one at a time per environment (`resource_group`). `GIT_DEPTH: "0"` gives both the history
  * they measure the change with. The jobs talk to GitLab with
  * `CHANT_FORGE_TOKEN`, a project or group access token with the `api` scope
  * set as a masked CI/CD variable, since a job token cannot write notes.
@@ -282,8 +293,15 @@ function gatedWaveGitlabPipeline(
  * apply passes it to `pr-apply --resume` (#3543). GitLab keeps protected
  * branches' caches apart from other branches' by default, so a merge request
  * pipeline cannot write the record the target branch's apply reads.
+ *
+ * With a gate per wave (`waveGate`, #4003) the apply job becomes
+ * `apply-wave-1` to `apply-wave-<n>`, one stage each, each needing the one
+ * before. They share the commit's cache key, so wave k pulls the record wave
+ * k-1 pushed, and a retry of a wave that stopped at its gate pulls the one it
+ * pushed itself.
  */
 function prLoopGitlabPipeline(
+  components: DriverComponent[],
   env: string,
   image: string,
   beforeScript: string[],
@@ -293,17 +311,24 @@ function prLoopGitlabPipeline(
   const loop = options.prLoop!;
   const member = options.member;
   const rooted = !member || member.dir === "." || member.dir === "";
-  const [plan, apply] = prLoopJobs("gitlab", env, loop, member?.name);
+  const [plan, apply, record] = prLoopJobs("gitlab", env, loop, member?.name);
   const reportPath = member ? memberRepoPath(member, PR_LOOP_REPORT_DIR) : PR_LOOP_REPORT_DIR;
   const planJob = member ? `${member.name}-plan` : "plan";
-  const applyJob = member ? `${member.name}-apply` : "apply";
+  const named = (job: string) => (member ? `${member.name}-${job}` : job);
+  const waveJobs = loop.waveGate ? prLoopWaveJobs(components, apply) : [];
+  const applies = loop.waveGate
+    ? waveJobs.map((job) => ({ job, name: named(prApplyWaveJobName(job.wave!)), stage: prApplyWaveJobName(job.wave!) }))
+    : loop.applyOnMerge
+      ? [{ job: apply, name: named("apply"), stage: "apply" }]
+      : [{ job: record, name: named("record"), stage: "record" }];
   const onMergeRequest = GITLAB_MERGE_REQUEST_SOURCE;
   if (loop.branch !== undefined) assertGitlabBranch("The merge-request pipeline", loop.branch);
   const onMerge = gitlabPushRule(loop.branch ? JSON.stringify(loop.branch) : "$CI_DEFAULT_BRANCH");
   // A member's jobs start in its directory, after the image's install lines.
   const enter = rooted ? [] : [`cd ${memberShellDir(member!)}`];
-  const script = (job: typeof plan): string[] => [...prLoopSetup(image), ...enter, ...beforeScript, ...(job.setup ?? []), ...(job.build ?? []), job.command, ...extraScript];
-  const stages = ["plan", "apply"];
+  // The command runs through chant ci run (#4156), which writes the job's run record, signed when the CHANT_RUNNER_KEY variable is set.
+  const script = (job: typeof plan): string[] => [...prLoopSetup(image), ...enter, ...beforeScript, ...(job.setup ?? []), ...(job.build ?? []), job.run.command, ...extraScript];
+  const stages = ["plan", ...applies.map((a) => a.stage)];
   const doc: Record<string, unknown> = {
     // Included files merge their top-level keys, so a member's file carries
     // the rules every member shares and no name: two names would collide.
@@ -314,32 +339,48 @@ function prLoopGitlabPipeline(
       stage: "plan",
       image,
       rules: [{ if: onMergeRequest }],
-      variables: plan.env,
+      variables: plan.run.env,
       script: script(plan),
       artifacts: { when: "always", paths: [reportPath] },
     },
-    [applyJob]: {
-      stage: "apply",
-      image,
-      resource_group: prApplyGroup(env, member?.name),
-      rules: [{ if: onMerge }],
-      variables: apply.env,
-      script: script(apply),
-      // The attempt record (#3543), kept under the pushed commit even when
-      // the job fails, so a retry finishes the apply under the same approval.
-      cache: {
-        key: prApplyRecordKey(env, "$CI_COMMIT_SHA", member?.name),
-        paths: [member ? memberRepoPath(member, PR_APPLY_RECORD) : PR_APPLY_RECORD],
-        when: "always",
-      },
-      artifacts: { when: "always", paths: [reportPath] },
-    },
+    ...Object.fromEntries(
+      applies.map(({ job, name, stage }, i) => [
+        name,
+        {
+          stage,
+          image,
+          ...(i > 0 ? { needs: [applies[i - 1]!.name] } : {}),
+          resource_group: job.jobName === "record" ? prRecordGroup(env, member?.name) : prApplyGroup(env, member?.name),
+          rules: [{ if: onMerge }],
+          variables: job.run.env,
+          script: script(job),
+          // The attempt record (#3543), kept under the pushed commit even when
+          // the job fails, so a retry finishes the apply under the same approval.
+          // The record job (#4168) applies nothing and keeps none.
+          ...(job.jobName === "record"
+            ? {}
+            : {
+                cache: {
+                  key: prApplyRecordKey(env, "$CI_COMMIT_SHA", member?.name),
+                  paths: [member ? memberRepoPath(member, PR_APPLY_RECORD) : PR_APPLY_RECORD],
+                  when: "always",
+                },
+              }),
+          artifacts: { when: "always", paths: [reportPath] },
+        },
+      ]),
+    ),
   };
   const jobs: GeneratedJob[] = [
     { jobName: planJob, component: "merge request plan", stage: "plan", needs: [] },
-    { jobName: applyJob, component: "merge request apply", stage: "apply", needs: [] },
+    ...applies.map(({ job, name, stage }, i) => ({
+      jobName: name,
+      component: job.wave ? `merge request apply, wave ${job.wave}` : job.jobName === "record" ? "merge record" : "merge request apply",
+      stage,
+      needs: i > 0 ? [applies[i - 1]!.name] : [],
+    })),
   ];
-  const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, applyJob].map((key) => [key, doc[key]] as const));
+  const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, ...applies.map((a) => a.name)].map((key) => [key, doc[key]] as const));
   return { yaml, stages, jobs, env };
 }
 

package/src/components/generate-pr-pipeline.test.ts

@@ -12,7 +12,7 @@ import { describe, expect, test } from "vitest";
 import { parseYAML } from "@intentius/chant/yaml";
 import type { DriverComponent } from "@intentius/chant/components/driver";
 import { generateGitlabPipeline } from "./generate-pipeline";
-import { PR_LOOP_SETUP } from "@intentius/chant/components/pr-pipeline";
+import { PR_LOOP_SETUP, prLoopJobs } from "@intentius/chant/components/pr-pipeline";
 
 const ESTATE: DriverComponent[] = [
   { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
@@ -33,7 +33,7 @@ interface Job {
 }
 
 describe("the GitLab merge-request pipeline", () => {
-  const result = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: {} });
+  const result = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true } });
   const doc = parseYAML(result.yaml) as { workflow: { rules: unknown[] }; variables: Record<string, string>; plan: Job; apply: Job };
 
   test("matches its golden", () => {
@@ -54,17 +54,19 @@ describe("the GitLab merge-request pipeline", () => {
     expect(doc.plan.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' }]);
     expect(doc.plan.variables).toEqual({ BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID" });
     expect(doc.plan.script).toEqual([
-      ...PR_LOOP_SETUP,'chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge gitlab']);
+      ...PR_LOOP_SETUP,'chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge gitlab']);
     expect(doc.apply.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' }]);
     expect(doc.apply.variables).toEqual({ BASE_SHA: "$CI_COMMIT_BEFORE_SHA" });
-    expect(doc.apply.script.at(-1)).toContain("--require-review");
+    // #4156: ci run builds pr-apply (with no --require-review since #4168), and GitLab hands CHANT_RUNNER_KEY to the job as a CI/CD variable when it has one.
+    expect(doc.apply.script.at(-1)).toBe('chant ci run apply --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge gitlab');
+    expect(result.yaml).not.toContain("CHANT_RUNNER_KEY");
     expect(doc.apply.resource_group).toBe("chant-apply-prod");
     expect(doc.variables.GIT_DEPTH).toBe("0");
     expect(doc.apply.artifacts).toEqual({ when: "always", paths: [".chant/pr"] });
   });
 
   test("events and reportUrl stream the run's events into the report artifact and copy the reports out (#4007)", () => {
-    const loud = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { events: true, reportUrl: "$CHANT_REPORT_URL" } }).yaml) as { plan: Job; apply: Job };
+    const loud = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, events: true, reportUrl: "$CHANT_REPORT_URL" } }).yaml) as { plan: Job; apply: Job };
     for (const job of [loud.plan, loud.apply]) {
       expect(job.script.at(-1)).toContain('--events-json --report-url "$CHANT_REPORT_URL"');
       expect(job.variables.CHANT_RUN_EVENTS_DIR).toBe(".chant/pr/run-events");
@@ -76,7 +78,7 @@ describe("the GitLab merge-request pipeline", () => {
   test("runs in an image with git and installs OpenTofu, unless the caller names an image", () => {
     expect(doc.plan.image).toBe("node:22");
     expect(doc.apply.script[0]).toBe(PR_LOOP_SETUP[0]);
-    const own = generateGitlabPipeline(ESTATE, { env: "prod", image: "example/ci:1", prLoop: {} }).yaml;
+    const own = generateGitlabPipeline(ESTATE, { env: "prod", image: "example/ci:1", prLoop: { applyOnMerge: true } }).yaml;
     expect(own).toContain("image: example/ci:1");
     expect(own).not.toContain("install-opentofu");
   });
@@ -90,25 +92,27 @@ describe("the GitLab merge-request pipeline", () => {
   });
 
   test("a named branch replaces the default branch in the apply rule", () => {
-    const yaml = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { branch: "trunk" } }).yaml;
+    const yaml = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, branch: "trunk" } }).yaml;
     expect(yaml).toContain('$CI_COMMIT_BRANCH == "trunk"');
   });
 
   test("the apply resumes from a record the job cache keeps for the pushed commit, failed or not (#3543)", () => {
-    expect(doc.apply.script.at(-1)).toContain("--resume .chant/pr-resume/pr-apply.json");
+    expect(doc.apply.script.at(-1)).toContain("--in-place");
+    expect(prLoopJobs("gitlab", "prod")[1]!.command).toContain("--resume .chant/pr-resume/pr-apply.json");
     expect(doc.apply.cache).toEqual({ key: "chant-apply-prod-$CI_COMMIT_SHA", paths: [".chant/pr-resume/pr-apply.json"], when: "always" });
     // The plan runs the merge request's code: no cache, no record.
     expect(doc.plan.cache).toBeUndefined();
     expect(doc.plan.script.at(-1)).not.toContain("--resume");
   });
 
-  test("refuses a wave or promote job beside it", () => {
-    expect(() => generateGitlabPipeline(ESTATE, { prLoop: {}, gatedWaves: { gate: "g" } })).toThrow(/pull-request pipeline has no wave or promote jobs/);
+  test("refuses a promote job beside it, and a canary beside --wave-gate (#4003)", () => {
+    expect(() => generateGitlabPipeline(ESTATE, { prLoop: { applyOnMerge: true }, promoteTo: "prod" })).toThrow(/pull-request pipeline has no promote job/);
+    expect(() => generateGitlabPipeline(ESTATE, { prLoop: { applyOnMerge: true }, gatedWaves: { gate: "g", canary: ["net"] } })).toThrow(/takes no --canary/);
   });
 
   test("inside a workspace member: member-named jobs that cd into the member, with no changes rule (#3465)", () => {
     const member = { name: "network", dir: "infra/network", file: ".gitlab/ci/chant-pr.network.prod.gitlab-ci.yml" };
-    const scoped = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: {}, member });
+    const scoped = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true }, member });
     const mdoc = parseYAML(scoped.yaml) as Record<string, unknown> & { workflow: { name?: string; rules: unknown[] } };
     expect(scoped.jobs.map((j) => j.jobName)).toEqual(["network-plan", "network-apply"]);
     expect(mdoc.plan).toBeUndefined();
@@ -118,9 +122,10 @@ describe("the GitLab merge-request pipeline", () => {
     const plan = mdoc["network-plan"] as Job;
     const apply = mdoc["network-apply"] as Job;
     expect(plan.script).toContain("cd infra/network");
-    expect(plan.script.indexOf("cd infra/network")).toBeLessThan(plan.script.findIndex((l) => l.includes("pr-plan")));
-    expect(plan.script.find((l) => l.includes("pr-plan"))).toContain("--member network");
-    expect(apply.script.find((l) => l.includes("pr-apply"))).toContain("--member network");
+    // ci run, started in the member's directory, finds the member and passes --member to pr-plan and pr-apply.
+    expect(plan.script.indexOf("cd infra/network")).toBeLessThan(plan.script.findIndex((l) => l.includes("ci run plan")));
+    expect(apply.script.indexOf("cd infra/network")).toBeLessThan(apply.script.findIndex((l) => l.includes("ci run apply")));
+    expect(prLoopJobs("gitlab", "prod", {}, "network")[0]!.command).toContain("--member network");
     // A change outside the member can reach it, so the jobs keep only their pipeline-source rules.
     expect(plan.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' }]);
     expect(apply.resource_group).toBe("chant-apply.network.prod");
@@ -132,12 +137,12 @@ describe("the GitLab merge-request pipeline", () => {
 
 describe("the merge-request pipeline's branch (#3765)", () => {
   test("a branch that would break the rules: expression is refused, as an Op's is", () => {
-    expect(() => generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { branch: "re$lease" } })).toThrow(/filters on branch "re\$lease"/);
+    expect(() => generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, branch: "re$lease" } })).toThrow(/filters on branch "re\$lease"/);
   });
 });
 
 describe("the gitlab pull-request pipeline with build (#4088)", () => {
-  const result = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { build: true } });
+  const result = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, build: true } });
   const doc = parseYAML(result.yaml) as Record<string, any>;
   const golden = join(import.meta.dirname, "__fixtures__", "pr-loop-build.gitlab.golden.yml");
 
@@ -156,14 +161,52 @@ describe("the gitlab pull-request pipeline with build (#4088)", () => {
   });
 
   test("buildCommand replaces the build line and turns the option on", () => {
-    const yaml = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { buildCommand: "npm run build" } }).yaml;
+    const yaml = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, buildCommand: "npm run build" } }).yaml;
     expect(yaml).toContain("npm run build");
     expect(yaml).not.toContain("chant build --env");
     expect(yaml).toContain("chant lint");
   });
 
   test("the default output carries neither line", () => {
-    const plain = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: {} }).yaml;
+    const plain = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true } }).yaml;
     expect(plain).not.toContain("chant lint");
   });
 });
+
+describe("the GitLab merge-request pipeline records on merge by default (#4168)", () => {
+  const result = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: {} });
+  const doc = parseYAML(result.yaml) as Record<string, unknown> & { stages: string[]; record: Job };
+  const golden = join(import.meta.dirname, "__fixtures__", "pr-loop-record.gitlab.golden.yml");
+
+  test("matches its golden", () => {
+    if (process.env.UPDATE_GOLDEN) writeFileSync(golden, result.yaml);
+    expect(result.yaml).toBe(readFileSync(golden, "utf-8"));
+  });
+
+  test("validates against the vendored GitLab CI schema", () => {
+    const req = createRequire(import.meta.url);
+    const mod = req("ajv") as { default?: unknown };
+    const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): ((d: unknown) => boolean) & { errors?: unknown } };
+    const validate = new Ajv({ strict: false, allErrors: true }).compile(JSON.parse(readFileSync(SCHEMA, "utf-8")));
+    expect(validate(doc), JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+
+  test("a push to the default branch runs the record job, which applies nothing and keeps no cache", () => {
+    expect(doc.stages).toEqual(["plan", "record"]);
+    expect(doc.apply).toBeUndefined();
+    expect(doc.record.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' }]);
+    expect(doc.record.script.at(-1)).toBe('chant ci run record --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge gitlab');
+    expect(doc.record.resource_group).toBe("chant-record-prod");
+    expect(doc.record.cache).toBeUndefined();
+  });
+
+  test("a gate per wave gates the apply, so it needs applyOnMerge", () => {
+    expect(() => generateGitlabPipeline(ESTATE, { env: "prod", prLoop: {}, gatedWaves: { gate: "release" } })).toThrow(/needs --apply-on-merge/);
+  });
+
+  test("inside a workspace member the record job takes the member's name and group", () => {
+    const scoped = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: {}, member: { name: "network", dir: "infra/network" } }).yaml) as Record<string, Job>;
+    expect(scoped["network-record"].resource_group).toBe("chant-record.network.prod");
+    expect(scoped["network-record"].script.at(-1)).toContain("chant ci run record");
+  });
+});

package/src/components/generate-pr-waves-pipeline.test.ts

@@ -0,0 +1,88 @@
+/**
+ * The GitLab merge-request pipeline with a gate per wave on merge (#4003):
+ * the plan job in each merge request pipeline, and one apply job per wave of
+ * the component graph, one stage each, sharing the commit's record in the
+ * job cache. The whole file has a golden, and it validates against the GitLab
+ * CI schema this lexicon vendors.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGitlabPipeline } from "./generate-pipeline";
+
+const root = (name: string, dependsOn: string[] = []): DriverComponent => ({
+  name,
+  dependsOn,
+  deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: name }] }],
+});
+const ESTATE: DriverComponent[] = [root("net"), root("app", ["net"]), root("web", ["app"])];
+
+const GOLDEN = join(import.meta.dirname, "__fixtures__", "pr-loop-waves.gitlab.golden.yml");
+const SCHEMA = join(import.meta.dirname, "..", "codegen", "vendored", "gitlab-ci-schema.json");
+
+interface Job {
+  stage: string;
+  needs?: string[];
+  rules: Array<{ if: string }>;
+  script: string[];
+  resource_group?: string;
+  cache?: Record<string, unknown>;
+}
+
+describe("the GitLab merge-request pipeline with a gate per wave (#4003)", () => {
+  const result = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true }, gatedWaves: { gate: "release" } });
+  const doc = parseYAML(result.yaml) as Record<string, unknown> & { stages: string[] };
+
+  test("matches its golden", () => {
+    if (process.env.UPDATE_GOLDEN) writeFileSync(GOLDEN, result.yaml);
+    expect(result.yaml).toBe(readFileSync(GOLDEN, "utf-8"));
+  });
+
+  test("validates against the vendored GitLab CI schema", () => {
+    const req = createRequire(import.meta.url);
+    const mod = req("ajv") as { default?: unknown };
+    const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): ((d: unknown) => boolean) & { errors?: unknown } };
+    const validate = new Ajv({ strict: false, allErrors: true }).compile(JSON.parse(readFileSync(SCHEMA, "utf-8")));
+    expect(validate(doc), JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+
+  test("one apply job and stage per wave, each needing the one before, on the merge, one at a time", () => {
+    expect(doc.stages).toEqual(["plan", "apply-wave-1", "apply-wave-2", "apply-wave-3"]);
+    expect(result.jobs.map((j) => [j.jobName, j.needs])).toEqual([
+      ["plan", []],
+      ["apply-wave-1", []],
+      ["apply-wave-2", ["apply-wave-1"]],
+      ["apply-wave-3", ["apply-wave-2"]],
+    ]);
+    for (const k of [1, 2, 3]) {
+      const job = doc[`apply-wave-${k}`] as Job;
+      expect(job.stage).toBe(`apply-wave-${k}`);
+      expect(job.needs).toEqual(k > 1 ? [`apply-wave-${k - 1}`] : undefined);
+      expect(job.resource_group).toBe("chant-apply-prod");
+      // #4156: through chant ci run, which runs pr-apply --wave-gate release (no --require-review since #4168) --resume ... --wave <k>.
+      expect(job.script.at(-1)).toBe(`chant ci run apply --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge gitlab --wave-gate release --wave ${k}`);
+      // Every wave shares the commit's record, so wave k pulls what wave k-1 pushed.
+      expect(job.cache).toEqual({ key: "chant-apply-prod-$CI_COMMIT_SHA", paths: [".chant/pr-resume/pr-apply.json"], when: "always" });
+    }
+    expect((doc.plan as Job).script.at(-1)).toContain("--forge gitlab --wave-gate release");
+    expect((doc.plan as Job).script.at(-1)).not.toContain("--wave ");
+  });
+
+  test("inside a workspace member the wave jobs carry the member's name", () => {
+    const member = { name: "network", dir: "infra/network", file: ".gitlab/ci/chant-pr.network.prod.gitlab-ci.yml" };
+    const scoped = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true }, gatedWaves: { gate: "release" }, member });
+    expect(scoped.jobs.map((j) => [j.jobName, j.needs])).toEqual([
+      ["network-plan", []],
+      ["network-apply-wave-1", []],
+      ["network-apply-wave-2", ["network-apply-wave-1"]],
+      ["network-apply-wave-3", ["network-apply-wave-2"]],
+    ]);
+    // ci run, started in the member's directory, passes --member network to pr-apply.
+    expect(scoped.yaml).toContain("cd infra/network");
+    expect(scoped.yaml).toContain("chant ci run apply --in-place --base \"$BASE_SHA\" --env prod --gate pr-apply --forge gitlab --wave-gate release --wave 3");
+  });
+});

package/src/lint/post-synth/wgl012.ts

@@ -7,6 +7,7 @@
 
 import { readFileSync } from "fs";
 import { join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import { isPropertyDeclarable } from "@intentius/chant/declarable";
 
@@ -23,8 +24,7 @@ interface LexiconEntry {
 function loadDeprecatedProperties(): Map<string, Set<string>> {
   const map = new Map<string, Set<string>>();
   try {
-    const pkgDir = join(__dirname, "..", "..", "..");
-    const lexiconPath = join(pkgDir, "src", "generated", "lexicon-gitlab.json");
+    const lexiconPath = join(moduleSourceDir(import.meta.url), "..", "..", "generated", "lexicon-gitlab.json");
     const content = readFileSync(lexiconPath, "utf-8");
     const data = JSON.parse(content) as Record<string, LexiconEntry>;
 

package/src/lsp/completions.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
 import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
-const require = createRequire(import.meta.url);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 let cachedIndex: LexiconIndex | null = null;
 

package/src/lsp/hover.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
 import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
-const require = createRequire(import.meta.url);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 let cachedIndex: LexiconIndex | null = null;