@intentius/chant-lexicon-github 0.124.31 → 0.124.33

package/src/components/generate-pipeline.ts

@@ -60,7 +60,18 @@ import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/co
 import { hasPublishStep, promoteArchivePaths } from "@intentius/chant/components/promote";
 import { GATED_WAVE_RECORD, gatedWaveJobs } from "@intentius/chant/components/gated-wave-pipeline";
 import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
-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 { memberRepoPath } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineJob as GeneratedJob,
@@ -161,7 +172,10 @@ function gatedWaveGithubDoc(
 
 /**
  * The pull-request workflow (#3183): `plan` on each pull request into the
- * target branch, `apply` on each push to it. The plan job can comment and set
+ * target branch, and on each push to it `record` (#4168), or `apply` with
+ * `applyOnMerge`. The record job plans on the merged commit and writes the
+ * merge record, applying nothing, so it pushes to `chant/lifecycle` and runs
+ * one at a time per environment as the apply does. The plan job can comment and set
  * statuses but cannot push, since it runs the pull request's code; the apply
  * job can push, to record a pending fact on `chant/lifecycle`, and runs one
  * at a time per environment. Both keep their report as an artifact, and both
@@ -175,8 +189,17 @@ function gatedWaveGithubDoc(
  * path filter, since a change outside the member can reach it; the plan
  * selects from the whole change and passes `--member`, which keeps the
  * member's gate, note and statuses apart from the other members'.
+ *
+ * With a gate per wave (`waveGate`, #4003) the one apply job becomes
+ * `apply-wave-1` to `apply-wave-<n>`, one per wave of the component graph,
+ * each needing the one before. Each saves the record under its own cache key
+ * (the run, the attempt and the wave), and each restores the newest record
+ * for the pushed commit, so wave k reads what wave k-1 left, and a re-run of
+ * a wave that stopped at its gate reads what it left itself. Each keeps its
+ * report as `chant-pr-apply-wave-<k>`.
  */
 function prLoopGithubDoc(
+  components: DriverComponent[],
   env: string,
   image: string,
   beforeScript: string[],
@@ -187,41 +210,62 @@ function prLoopGithubDoc(
   const branch = loop.branch ?? "main";
   const member = options.member;
   const rooted = !member || member.dir === "." || member.dir === "";
-  const [plan, apply] = prLoopJobs(loop.forge ?? "github", env, loop, member?.name);
+  const [plan, apply, record] = prLoopJobs(loop.forge ?? "github", env, loop, member?.name);
   const reportPath = member ? memberRepoPath(member, PR_LOOP_REPORT_DIR) : PR_LOOP_REPORT_DIR;
   // The apply's attempt record (#3543) lives in the cache under the pushed
   // commit. Cache keys cannot be overwritten, so each attempt saves under
   // its run and attempt, and a re-run restores the newest for the commit.
   const recordPath = member ? memberRepoPath(member, PR_APPLY_RECORD) : PR_APPLY_RECORD;
   const recordPrefix = `${prApplyRecordKey(env, "${{ github.sha }}", member?.name)}-`;
-  const recordKey = `${recordPrefix}\${{ github.run_id }}-\${{ github.run_attempt }}`;
-  const restoreRecord = {
-    name: "Restore the record of an earlier attempt at this commit",
+  const recordKey = (wave?: number) => `${recordPrefix}\${{ github.run_id }}-\${{ github.run_attempt }}${wave ? `-wave-${wave}` : ""}`;
+  const restoreRecord = (wave?: number) => ({
+    name: wave ? "Restore the newest record of this commit's apply" : "Restore the record of an earlier attempt at this commit",
     uses: "actions/cache/restore@v4",
-    with: { path: recordPath, key: recordKey, "restore-keys": recordPrefix },
-  };
-  const saveRecord = {
-    name: "Keep the record for a re-run",
+    with: { path: recordPath, key: recordKey(wave), "restore-keys": recordPrefix },
+  });
+  const saveRecord = (wave?: number) => ({
+    name: wave ? "Keep the record for the next wave and a re-run" : "Keep the record for a re-run",
     if: "always()",
     uses: "actions/cache/save@v4",
-    with: { path: recordPath, key: recordKey },
-  };
+    with: { path: recordPath, key: recordKey(wave) },
+  });
+  const reportName = (job: typeof plan) => `chant-pr-${job.wave ? prApplyWaveJobName(job.wave) : job.jobName}`;
   const steps = (job: typeof plan, name: string): Array<Record<string, unknown>> => [
     checkoutStep(true),
     ...runSteps(prLoopSetup(image)),
     ...runSteps(beforeScript),
     ...(job.build ? [{ name: "Build the templates", run: job.build[0] }, { name: "Lint the project", run: job.build[1] }] : []),
-    ...(job.jobName === "apply" ? [restoreRecord] : []),
-    { name, env: job.env, run: job.command },
+    ...(job.jobName === "apply" ? [restoreRecord(job.wave)] : []),
+    // The job's setup lines (#4004) run in the command's shell, so a value they settle reaches it.
+    // The command runs through chant ci run (#4156), which writes the job's run record, signed when the CHANT_RUNNER_KEY secret is set.
+    { name, env: job.run.env, run: [...(job.setup ?? []), job.run.command].join("\n") },
     ...runSteps(extraScript),
-    ...(job.jobName === "apply" ? [saveRecord] : []),
+    ...(job.jobName === "apply" ? [saveRecord(job.wave)] : []),
     {
-      name: `Keep the ${job.jobName} report`,
+      name: `Keep the ${job.wave ? `wave ${job.wave} ` : ""}${job.jobName} report`,
       if: "always()",
       uses: UPLOAD_ARTIFACT,
-      with: { name: `chant-pr-${job.jobName}`, path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true },
+      with: { name: reportName(job), path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true },
     },
   ];
+  const applyJob = (job: typeof plan, needs: string[], name: string) => ({
+    if: "github.event_name == 'push'",
+    "runs-on": GITHUB_RUNNER,
+    ...(needs.length > 0 ? { needs } : {}),
+    container: image,
+    concurrency: concurrency(prApplyGroup(env, member?.name)),
+    permissions: { contents: "write", "pull-requests": "write", statuses: "write" },
+    steps: steps(job, name),
+  });
+  const waveJobs = loop.waveGate ? prLoopWaveJobs(components, apply) : [];
+  const applyJobs: Array<[string, Record<string, unknown>]> = loop.waveGate
+    ? waveJobs.map((job) => [
+        prApplyWaveJobName(job.wave!),
+        applyJob(job, job.wave! > 1 ? [prApplyWaveJobName(job.wave! - 1)] : [], `Apply wave ${job.wave}, under the approval its plan has`),
+      ])
+    : loop.applyOnMerge
+      ? [["apply", applyJob(apply, [], "Apply the plan a reviewer approved")]]
+      : [["record", { ...applyJob(record, [], "Record the plan on the merged commit; nothing applies"), concurrency: concurrency(prRecordGroup(env, member?.name)) }]];
   const jobsDoc: Record<string, unknown> = {
     plan: {
       if: "github.event_name == 'pull_request'",
@@ -230,15 +274,9 @@ function prLoopGithubDoc(
       permissions: { contents: "read", "pull-requests": "write", statuses: "write" },
       steps: steps(plan, "Plan the members this pull request reaches"),
     },
-    apply: {
-      if: "github.event_name == 'push'",
-      "runs-on": GITHUB_RUNNER,
-      container: image,
-      concurrency: concurrency(prApplyGroup(env, member?.name)),
-      permissions: { contents: "write", "pull-requests": "write", statuses: "write" },
-      steps: steps(apply, "Apply the plan a reviewer approved"),
-    },
+    ...Object.fromEntries(applyJobs),
   };
+  const applyNames = applyJobs.map(([name]) => name);
   return {
     name: member ? `chant-pr.${member.name}.${env}` : `chant-pr-${env}`,
     environment: env,
@@ -246,10 +284,15 @@ function prLoopGithubDoc(
     ...(rooted ? {} : { defaults: { run: { "working-directory": member!.dir } } }),
     env: { ...options.variables, CHANT_ENV: env },
     jobsDoc,
-    stages: ["plan", "apply"],
+    stages: ["plan", ...applyNames],
     jobs: [
       { jobName: "plan", component: "pull request plan", stage: "plan", needs: [] },
-      { jobName: "apply", component: "pull request apply", stage: "apply", needs: [] },
+      ...applyNames.map((name, i) => ({
+        jobName: name,
+        component: loop.waveGate ? `pull request apply, wave ${i + 1}` : loop.applyOnMerge ? "pull request apply" : "merge record",
+        stage: name,
+        needs: i > 0 ? [applyNames[i - 1]] : [],
+      })),
     ],
   };
 }
@@ -315,10 +358,10 @@ export function buildGithubPipelineDoc(
   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 prLoopGithubDoc(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 prLoopGithubDoc(components, env, image, beforeScript, extraScript, { ...options, prLoop });
   }
 
   if (options.gatedWaves) {

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

@@ -11,7 +11,7 @@ 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 { prApplyGroup, prApplyRecordKey } from "@intentius/chant/components/pr-pipeline";
+import { githubBaseFallback, prApplyGroup, prApplyRecordKey, prLoopJobs } from "@intentius/chant/components/pr-pipeline";
 import { generateGithubPipeline } from "./generate-pipeline";
 
 const ESTATE: DriverComponent[] = [
@@ -46,7 +46,7 @@ interface Job {
 }
 
 describe("the GitHub pull-request workflow", () => {
-  const result = generateGithubPipeline(ESTATE, { env: "prod", prLoop: {} });
+  const result = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true } });
   const doc = parseYAML(result.yaml) as { name: string; on: Record<string, unknown>; jobs: Record<string, Job> };
 
   test("matches its golden", () => {
@@ -63,28 +63,49 @@ describe("the GitHub pull-request workflow", () => {
   });
 
   test("the plan job measures from the pull request's base and cannot push; the apply job can, one at a time", () => {
-    const plan = doc.jobs.plan.steps.find((s) => s.run?.includes("pr-plan"))!;
-    expect(plan.run).toBe('chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge github');
+    const plan = doc.jobs.plan.steps.find((s) => s.run?.includes("ci run plan"))!;
+    // #4156: the job runs pr-plan through chant ci run, in its own checkout, and pushes no record from the pull request's code.
+    expect(plan.run).toBe('chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github');
     expect(plan.env).toMatchObject({ BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}" });
+    // The runner key is an optional secret: unset, the expression is empty and the record is unsigned.
+    expect(plan.env?.CHANT_RUNNER_KEY).toBe("${{ secrets.CHANT_RUNNER_KEY }}");
     expect(doc.jobs.plan.permissions).toEqual({ contents: "read", "pull-requests": "write", statuses: "write" });
 
-    const apply = doc.jobs.apply.steps.find((s) => s.run?.includes("pr-apply"))!;
-    expect(apply.run).toContain("--require-review");
-    expect(apply.env).toMatchObject({ BASE_SHA: "${{ github.event.before }}" });
+    const apply = doc.jobs.apply.steps.find((s) => s.run?.includes("ci run apply"))!;
+    // #4168: ci run builds pr-apply without --require-review unless the pipeline asks for it.
+    expect(apply.run).not.toContain("--require-review");
+    expect(apply.run).not.toContain("--no-push");
+    expect(apply.env).toMatchObject({ BASE_SHA: "${{ github.event.before }}", CHANT_RUNNER_KEY: "${{ secrets.CHANT_RUNNER_KEY }}" });
     expect(doc.jobs.apply.permissions.contents).toBe("write");
     expect(doc.jobs.apply.concurrency).toEqual({ group: "chant-apply-prod", "cancel-in-progress": false });
     for (const job of Object.values(doc.jobs)) expect(job.steps[0].with).toEqual({ "fetch-depth": 0 });
   });
 
+  test("a first push's all-zero github.event.before is settled in the apply's own shell, before pr-apply reads it (#4004)", () => {
+    const apply = doc.jobs.apply.steps.find((s) => s.run?.includes("ci run apply"))!;
+    const lines = apply.run!.trimEnd().split("\n");
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toBe(githubBaseFallback());
+    expect(lines[0]).toContain('[ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]');
+    expect(lines[0]).toContain('git merge-base FETCH_HEAD "$GITHUB_SHA"');
+    expect(lines[1]).toMatch(/^chant ci run apply --in-place --base "\$BASE_SHA"/);
+    const trunk = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, branch: "trunk" } }).yaml) as { jobs: Record<string, Job> };
+    expect(trunk.jobs.apply.steps.find((s) => s.run?.includes("ci run apply"))!.run).toContain('git fetch origin "trunk"');
+    const plan = doc.jobs.plan.steps.find((s) => s.run?.includes("ci run plan"))!;
+    expect(plan.run).not.toContain("0000000000000000000000000000000000000000");
+  });
+
   test("the apply resumes from a record the cache keeps for the pushed commit across a re-run (#3543)", () => {
     const steps = doc.jobs.apply.steps;
     const restore = steps.findIndex((s) => s.uses === "actions/cache/restore@v4");
-    const run = steps.findIndex((s) => s.run?.includes("pr-apply"));
+    const run = steps.findIndex((s) => s.run?.includes("ci run apply"));
     const save = steps.findIndex((s) => s.uses === "actions/cache/save@v4");
     expect(restore).toBeGreaterThan(-1);
     expect(restore).toBeLessThan(run);
     expect(save).toBeGreaterThan(run);
-    expect(steps[run].run).toContain("--resume .chant/pr-resume/pr-apply.json");
+    // ci run runs the inner pr-apply in the checkout, where the cache restored the record.
+    expect(steps[run].run).toContain("--in-place");
+    expect(prLoopJobs("github", "prod")[1]!.command).toContain("--resume .chant/pr-resume/pr-apply.json");
     const key = "chant-apply-prod-${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}";
     expect(steps[restore].with).toEqual({ path: ".chant/pr-resume/pr-apply.json", key, "restore-keys": "chant-apply-prod-${{ github.sha }}-" });
     // Saved even when the apply failed, which is when a re-run needs it.
@@ -92,7 +113,7 @@ describe("the GitHub pull-request workflow", () => {
     expect(steps[save].with).toEqual({ path: ".chant/pr-resume/pr-apply.json", key });
     // The plan job runs the pull request's code: it neither reads nor writes the record.
     expect(doc.jobs.plan.steps.some((s) => s.uses?.startsWith("actions/cache"))).toBe(false);
-    expect(doc.jobs.plan.steps.find((s) => s.run?.includes("pr-plan"))!.run).not.toContain("--resume");
+    expect(doc.jobs.plan.steps.find((s) => s.run?.includes("ci run plan"))!.run).not.toContain("--resume");
     // The report artifact does not carry the record, which holds the members' outputs.
     const keep = steps.find((s) => s.uses?.startsWith("actions/upload-artifact"))!;
     expect(keep.with?.path).toBe(".chant/pr");
@@ -100,27 +121,29 @@ describe("the GitHub pull-request workflow", () => {
 
   test("runs in an image with git and installs OpenTofu, unless the caller names an image", () => {
     expect(doc.jobs.plan.steps[1].run).toContain("install-opentofu");
-    const own = generateGithubPipeline(ESTATE, { env: "prod", image: "example/ci:1", prLoop: {} }).yaml;
+    const own = generateGithubPipeline(ESTATE, { env: "prod", image: "example/ci:1", prLoop: { applyOnMerge: true } }).yaml;
     expect(own).toContain("container: example/ci:1");
     expect(own).not.toContain("install-opentofu");
   });
 
   test("the gate, branch and review requirement are options", () => {
-    const yaml = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { gate: "infra-apply", branch: "trunk", requireReview: false } }).yaml;
+    const yaml = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, gate: "infra-apply", branch: "trunk", requireReview: true } }).yaml;
     expect(yaml).toContain("--gate infra-apply");
     expect(yaml).toContain("- trunk");
-    expect(yaml).not.toContain("--require-review");
+    expect(yaml).toContain("ci run apply --in-place --base \"$BASE_SHA\" --env prod --gate infra-apply --forge github --branch \"trunk\" --require-review");
+    expect(yaml).toContain('--branch "trunk"');
   });
 
-  test("refuses a wave or promote job beside it", () => {
-    expect(() => generateGithubPipeline(ESTATE, { prLoop: {}, gatedWaves: { gate: "g" } })).toThrow(/pull-request pipeline has no wave or promote jobs/);
-    expect(() => generateGithubPipeline(ESTATE, { prLoop: {}, promoteTo: "prod" })).toThrow(/pull-request pipeline has no wave or promote jobs/);
+  test("refuses a promote job beside it, and a canary or a fixed base beside --wave-gate (#4003)", () => {
+    expect(() => generateGithubPipeline(ESTATE, { prLoop: { applyOnMerge: true }, promoteTo: "prod" })).toThrow(/pull-request pipeline has no promote job/);
+    expect(() => generateGithubPipeline(ESTATE, { prLoop: { applyOnMerge: true }, gatedWaves: { gate: "g", canary: ["net"] } })).toThrow(/takes no --canary/);
+    expect(() => generateGithubPipeline(ESTATE, { prLoop: { applyOnMerge: true }, gatedWaves: { gate: "g", base: "HEAD~1" } })).toThrow(/takes no --base/);
   });
 
   test("events and reportUrl stream the run's events into the report artifact and copy the reports out (#4007)", () => {
-    const loud = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { events: true, reportUrl: "s3://chant-reports/acme" } }).yaml) as { jobs: Record<string, Job> };
+    const loud = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, events: true, reportUrl: "s3://chant-reports/acme" } }).yaml) as { jobs: Record<string, Job> };
     for (const job of ["plan", "apply"]) {
-      const run = loud.jobs[job].steps.find((s) => s.run?.startsWith("chant components"))!;
+      const run = loud.jobs[job].steps.find((s) => s.run?.includes("chant ci run"))!;
       expect(run.run).toContain('--events-json --report-url "s3://chant-reports/acme"');
       expect(run.env?.CHANT_RUN_EVENTS_DIR).toBe(".chant/pr/run-events");
     }
@@ -131,7 +154,7 @@ describe("the GitHub pull-request workflow", () => {
 
   test("inside a workspace member: runs in the member's directory and keeps its own gate, note and apply group (#3465)", () => {
     const member = { name: "network", dir: "infra/network", file: ".github/workflows/chant-pr.network.prod.yml" };
-    const scoped = generateGithubPipeline(ESTATE, { env: "prod", prLoop: {}, member });
+    const scoped = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true }, member });
     const mdoc = parseYAML(scoped.yaml) as {
       name: string;
       on: Record<string, unknown>;
@@ -142,13 +165,14 @@ describe("the GitHub pull-request workflow", () => {
     // No path filter: a change outside the member can reach it.
     expect(mdoc.on).toEqual({ pull_request: { branches: ["main"] }, push: { branches: ["main"] } });
     expect(mdoc.defaults).toEqual({ run: { "working-directory": "infra/network" } });
-    const plan = mdoc.jobs.plan.steps.find((s) => s.run?.includes("pr-plan"))!;
-    expect(plan.run).toBe('chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge github --member network');
-    const apply = mdoc.jobs.apply.steps.find((s) => s.run?.includes("pr-apply"))!;
-    expect(apply.run).toContain("--member network");
+    const plan = mdoc.jobs.plan.steps.find((s) => s.run?.includes("ci run plan"))!;
+    // ci run finds the member from the directory it runs in and passes --member to pr-plan and pr-apply.
+    expect(plan.run).toBe('chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github');
+    expect(prLoopJobs("github", "prod", {}, "network")[0]!.command).toContain("--member network");
+    const apply = mdoc.jobs.apply.steps.find((s) => s.run?.includes("ci run apply"))!;
     expect(mdoc.jobs.apply.concurrency).toEqual({ group: "chant-apply.network.prod", "cancel-in-progress": false });
     // The record path is relative to the member for --resume and to the repository for the cache.
-    expect(apply.run).toContain("--resume .chant/pr-resume/pr-apply.json");
+    expect(apply.run).toContain("--in-place");
     const restore = mdoc.jobs.apply.steps.find((s) => s.uses === "actions/cache/restore@v4")!;
     expect(restore.with).toMatchObject({ path: "infra/network/.chant/pr-resume/pr-apply.json", "restore-keys": "chant-apply.network.prod-${{ github.sha }}-" });
     for (const job of Object.values(mdoc.jobs)) {
@@ -168,11 +192,11 @@ describe("the GitHub pull-request workflow", () => {
   });
 
   test("a member at the workspace root keeps the root's paths but its own names", () => {
-    const yaml = generateGithubPipeline(ESTATE, { env: "prod", prLoop: {}, member: { name: "root", dir: "." } }).yaml;
+    const yaml = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true }, member: { name: "root", dir: "." } }).yaml;
     const mdoc = parseYAML(yaml) as { name: string; defaults?: unknown; jobs: Record<string, Job> };
     expect(mdoc.name).toBe("chant-pr.root.prod");
     expect(mdoc.defaults).toBeUndefined();
-    expect(yaml).toContain("--member root");
+    expect(yaml).toContain("chant ci run plan --in-place");
     expect(yaml).toContain("path: .chant/pr");
   });
 
@@ -189,7 +213,7 @@ describe("the GitHub pull-request workflow", () => {
 });
 
 describe("the github pull-request pipeline with build (#4088)", () => {
-  const result = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { build: true } });
+  const result = generateGithubPipeline(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.github.golden.yml");
 
@@ -207,14 +231,60 @@ describe("the github pull-request pipeline with build (#4088)", () => {
   });
 
   test("buildCommand replaces the build line and turns the option on", () => {
-    const yaml = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { buildCommand: "npm run build" } }).yaml;
+    const yaml = generateGithubPipeline(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 = generateGithubPipeline(ESTATE, { env: "prod", prLoop: {} }).yaml;
+    const plain = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true } }).yaml;
     expect(plain).not.toContain("chant lint");
   });
 });
+
+describe("the GitHub pull-request workflow records on merge by default (#4168)", () => {
+  const result = generateGithubPipeline(ESTATE, { env: "prod", prLoop: {} });
+  const doc = parseYAML(result.yaml) as { jobs: Record<string, Job> };
+  const golden = join(import.meta.dirname, "__fixtures__", "pr-loop-record.github.golden.yml");
+
+  test("matches its golden", () => {
+    if (process.env.UPDATE_GOLDEN) writeFileSync(golden, result.yaml);
+    expect(result.yaml).toBe(readFileSync(golden, "utf-8"));
+  });
+
+  test("a push runs the record job, which applies nothing and keeps no resume record", () => {
+    expect(result.jobs.map((j) => j.jobName)).toEqual(["plan", "record"]);
+    expect(doc.jobs.apply).toBeUndefined();
+    expect(doc.jobs.record.if).toBe("github.event_name == 'push'");
+    const run = doc.jobs.record.steps.find((s) => s.run?.includes("ci run record"))!;
+    expect(run.run!.trimEnd().split("\n")).toEqual([githubBaseFallback(), 'chant ci run record --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge github']);
+    expect(doc.jobs.record.steps.some((s) => s.uses?.startsWith("actions/cache"))).toBe(false);
+    // It writes the merge record and the change set to chant/lifecycle, one at a time per environment.
+    expect(doc.jobs.record.permissions.contents).toBe("write");
+    expect(doc.jobs.record.concurrency).toEqual({ group: "chant-record-prod", "cancel-in-progress": false });
+    expect(result.yaml).not.toContain("ci run apply");
+  });
+
+  test("a gate per wave gates the apply, so it needs applyOnMerge", () => {
+    expect(() => generateGithubPipeline(ESTATE, { env: "prod", prLoop: {}, gatedWaves: { gate: "release" } })).toThrow(/needs --apply-on-merge/);
+  });
+
+  test("the record job runs pr-record with the apply's flags", () => {
+    const [, , record] = prLoopJobs("github", "prod", { events: true, reportUrl: "s3://r/acme", waveGate: "w", requireReview: true, branch: "trunk" });
+    expect(record.jobName).toBe("record");
+    expect(record.command).toBe('chant components pr-record --base "$BASE_SHA" --env prod --gate pr-apply --output .chant/pr --forge github --events-json --report-url "s3://r/acme"');
+    expect(record.run.command).toBe('chant ci run record --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge github --branch "trunk" --events-json --report-url "s3://r/acme"');
+  });
+
+  test.skipIf(!hasActionlint())("passes actionlint", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-pr-record-"));
+    try {
+      mkdirSync(join(dir, ".github", "workflows"), { recursive: true });
+      writeFileSync(join(dir, ".github", "workflows", "chant-pr.yml"), result.yaml);
+      execFileSync("actionlint", [join(dir, ".github", "workflows", "chant-pr.yml")], { cwd: dir, stdio: "pipe" });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -0,0 +1,117 @@
+/**
+ * The GitHub pull-request workflow with a gate per wave on merge (#4003):
+ * `--pr-loop --wave-gate <gate>` keeps the plan job on the pull request and
+ * writes one apply job per wave of the component graph, each running
+ * `pr-apply --wave-gate <gate> --wave <k>` after the one before it. The whole
+ * file has a golden, and actionlint checks it when it is installed.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+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 { generateGithubPipeline } from "./generate-pipeline";
+
+const root = (name: string, dependsOn: string[] = []): DriverComponent => ({
+  name,
+  dependsOn,
+  deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: name }] }],
+});
+/** Three waves: net, then app, then web. */
+const ESTATE: DriverComponent[] = [root("net"), root("app", ["net"]), root("web", ["app"])];
+
+const GOLDEN = join(import.meta.dirname, "__fixtures__", "pr-loop-waves.github.golden.yml");
+
+interface Step {
+  name?: string;
+  if?: string;
+  uses?: string;
+  run?: string;
+  env?: Record<string, string>;
+  with?: Record<string, unknown>;
+}
+interface Job {
+  if: string;
+  needs?: string[];
+  concurrency?: Record<string, unknown>;
+  permissions: Record<string, string>;
+  steps: Step[];
+}
+
+function hasActionlint(): boolean {
+  try {
+    execFileSync("actionlint", ["-version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe("the GitHub pull-request workflow with a gate per wave (#4003)", () => {
+  const result = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true }, gatedWaves: { gate: "release" } });
+  const doc = parseYAML(result.yaml) as { jobs: Record<string, Job> };
+
+  test("matches its golden", () => {
+    if (process.env.UPDATE_GOLDEN) writeFileSync(GOLDEN, result.yaml);
+    expect(result.yaml).toBe(readFileSync(GOLDEN, "utf-8"));
+  });
+
+  test("keeps the plan job, and writes one apply job per wave, each needing the one before", () => {
+    expect(Object.keys(doc.jobs)).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"]],
+    ]);
+    expect(doc.jobs["apply-wave-2"]!.needs).toEqual(["apply-wave-1"]);
+    const plan = doc.jobs.plan!.steps.find((s) => s.run?.includes("ci run plan"))!;
+    // The plan passes the wave gate for its note (#4003), and runs no wave.
+    expect(plan.run).toContain("--forge github --wave-gate release");
+    expect(plan.run).not.toContain("--wave ");
+    for (const k of [1, 2, 3]) {
+      const job = doc.jobs[`apply-wave-${k}`]!;
+      expect(job.if).toBe("github.event_name == 'push'");
+      expect(job.concurrency).toEqual({ group: "chant-apply-prod", "cancel-in-progress": false });
+      expect(job.permissions.contents).toBe("write");
+      const run = job.steps.find((s) => s.run?.includes("ci run apply"))!.run!;
+      // #4156: through chant ci run, which runs pr-apply --wave-gate release (no --require-review since #4168) --resume ... --wave <k>.
+      expect(run).toContain(`chant ci run apply --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge github --wave-gate release --wave ${k}`);
+      expect(job.steps.find((s) => s.run?.includes("ci run apply"))!.env?.CHANT_RUNNER_KEY).toBe("${{ secrets.CHANT_RUNNER_KEY }}");
+    }
+  });
+
+  test("each wave restores the commit's newest record and saves its own, so wave k reads what wave k-1 left", () => {
+    for (const k of [1, 2, 3]) {
+      const steps = doc.jobs[`apply-wave-${k}`]!.steps;
+      const restore = steps.find((s) => s.uses === "actions/cache/restore@v4")!;
+      const save = steps.find((s) => s.uses === "actions/cache/save@v4")!;
+      const key = `chant-apply-prod-\${{ github.sha }}-\${{ github.run_id }}-\${{ github.run_attempt }}-wave-${k}`;
+      expect(restore.with).toEqual({ path: ".chant/pr-resume/pr-apply.json", key, "restore-keys": "chant-apply-prod-${{ github.sha }}-" });
+      expect(save).toMatchObject({ if: "always()", with: { path: ".chant/pr-resume/pr-apply.json", key } });
+      const keep = steps.find((s) => s.uses?.startsWith("actions/upload-artifact"))!;
+      expect(keep.with?.name).toBe(`chant-pr-apply-wave-${k}`);
+    }
+  });
+
+  test("without --wave-gate the workflow is the one apply job it was", () => {
+    const plain = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true } });
+    expect(plain.jobs.map((j) => j.jobName)).toEqual(["plan", "apply"]);
+    expect(plain.yaml).not.toContain("--wave");
+  });
+
+  test.skipIf(!hasActionlint())("actionlint passes it", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "pr-waves-actionlint-"));
+    try {
+      mkdirSync(join(tmp, ".github", "workflows"), { recursive: true });
+      const file = join(tmp, ".github", "workflows", "chant-pr.yml");
+      writeFileSync(file, result.yaml);
+      execFileSync("actionlint", [file], { cwd: tmp, stdio: "pipe" });
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

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;