@intentius/chant-lexicon-github 0.124.41 → 0.124.42

package/dist/components/generate-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AA2BjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,mIAAmI;IACnI,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uEAAuE;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAsaD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CA+JnB;AA4CD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAGtB"}
+{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AA4BjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,mIAAmI;IACnI,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uEAAuE;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AA2bD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CA+JnB;AA4CD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAGtB"}

package/dist/components/generate-pipeline.js

@@ -61,7 +61,7 @@ import { GATED_WAVE_RECORD, gatedWaveJobs } from "@intentius/chant/components/ga
 import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_JOB_TOKEN, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
 import { CHECKOUT_TOKEN_ENV, checkoutScript, dropForgeTokens, handoverOutputs, handoverTrap, takeOverScript } from "@intentius/chant/ci-handover";
 import { OIDC_REQUEST_VARS, TRADE_SPEC_ENV, tradeLine } from "@intentius/chant/ci-identity";
-import { GREEN_TAG_PATTERN, GREEN_TICK_WORKFLOW, PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, prLoopWaveJobs, prLoopWithWaves, prEnvJobs, PR_ENV_REPORT_DIR, PR_ENV_SWEEP_CRON, PR_ENV_POST_JOB, } from "@intentius/chant/components/pr-pipeline";
+import { APPLY_COMMENT, GREEN_TAG_PATTERN, GREEN_TICK_WORKFLOW, PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, prLoopWaveJobs, prLoopWithWaves, prEnvJobs, PR_ENV_REPORT_DIR, PR_ENV_SWEEP_CRON, PR_ENV_POST_JOB, } from "@intentius/chant/components/pr-pipeline";
 import { memberRepoPath } from "@intentius/chant/lexicon";
 import { afterEarlierWave, checkoutStep, concurrency, downloadArtifactStep, emitWorkflowYAML, keepRecordStep, runSteps, UPLOAD_ARTIFACT } from "./ci-jobs.js";
 import { actionRef } from "../action-pins.js";
@@ -160,6 +160,15 @@ function gatedWaveGithubDoc(components, env, image, beforeScript, extraScript, o
  * variables a token is requested with, so the pull request's code holds no
  * OIDC token and cannot request one, and the plan job names no apply
  * identity.
+ *
+ * With `applyBeforeMerge` (#4301, ws-106) the apply job runs on a
+ * `/chant apply` comment on a pull request (`issue_comment`), from the
+ * default branch's workflow file, so a pull request cannot change the job
+ * that applies it. It checks out the pull request's head after the setup
+ * and `beforeScript` ran at the default branch's commit, and runs `pr-apply
+ * --before-merge`, which asks the forge the requires checks before any of
+ * the head's code loads. On GitHub the commenter must be an owner, member
+ * or collaborator. A push still records.
  */
 function prLoopGithubDoc(components, env, image, beforeScript, extraScript, options) {
     const loop = options.prLoop;
@@ -226,6 +235,14 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
     const forgejo = loop.forge === "forgejo";
     const onGreen = forgejo ? "startsWith(github.ref, 'refs/tags/ci/green/')" : "github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'";
     const onPush = loop.applyOnMerge && forgejo ? "github.event_name == 'push' && startsWith(github.ref, 'refs/heads/')" : "github.event_name == 'push'";
+    // #4301: a `/chant apply` comment on a pull request starts the apply before merge. GitHub also asks for a commenter who can write.
+    const onComment = [
+        "github.event_name == 'issue_comment'",
+        // Forgejo's payload says so with is_pull (terragucci comment-apply.ts:129 at e6cb431).
+        forgejo ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
+        `startsWith(github.event.comment.body, '${APPLY_COMMENT}')`,
+        ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+    ].join(" && ");
     const applyJob = (job, needs, name) => ({
         // #4291: a wave after the first runs after one that failed, and blocks only what depends on the failure.
         if: job.jobName === "record" ? onPush : needs.length > 0 && job.wave ? afterEarlierWave(needs[0], onGreen) : onGreen,
@@ -246,7 +263,9 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
         ])
         : loop.applyOnMerge
             ? [["apply", applyJob(apply, [], "Apply the newest green commit under the merged changes' approvals")]]
-            : [];
+            : loop.applyBeforeMerge
+                ? [["apply", { ...applyJob(apply, [], "Apply the pull request's head under its gate, once it is approved, mergeable, undiverged and green"), if: onComment }]]
+                : [];
     const applyJobs = [recordJob, ...greenJobs];
     // #4295: the plan job runs the pull request's code and holds no forge token while it does.
     const forgeName = loop.forge ?? "github";
@@ -315,6 +334,9 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
         on.pull_request = { branches: [branch], types: ["opened", "synchronize", "reopened", "closed"] };
         on.schedule = [{ cron: PR_ENV_SWEEP_CRON }];
     }
+    // #4301: a /chant apply comment starts the apply before merge.
+    if (loop.applyBeforeMerge)
+        on.issue_comment = { types: ["created"] };
     return {
         name: member ? `chant-pr.${member.name}.${env}` : `chant-pr-${env}`,
         environment: env,
@@ -328,7 +350,7 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
             { jobName: PR_PLAN_NOTE_JOB, component: "pull request plan note", stage: PR_PLAN_NOTE_JOB, needs: ["plan"] },
             ...applyNames.map((name, i) => ({
                 jobName: name,
-                component: name === "record" ? "merge record" : loop.waveGate ? `green apply, wave ${i}` : "green apply",
+                component: name === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : loop.waveGate ? `green apply, wave ${i}` : "green apply",
                 stage: name,
                 // The record runs on a push and the apply on a green commit, so only the waves need each other.
                 needs: i > 1 ? [applyNames[i - 1]] : [],

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "91be5cd758d335f713fe5eee9fdde779edfb2baf9ed1d38bc248487dfeb4301d",
+    "manifest.json": "f43fcee2c55ab1b71df96a4010da7ae13b50257d1f5f287ae9eaf4582a4403b9",
     "meta.json": "c50e0ef3845c370c3ad2210b8bba455980417c0f818aa6ed46e06d4fb8b1b9f9",
     "types/index.d.ts": "0ead95536e947ddfb98a5acf0ddb88547913b5a53a342df67711c59266f84b3e",
     "rules/deprecated-action-version.ts": "a9ba7cc924ff1c7055110416d8989273690415bfb5e8dcc32dc9431b9351f5ca",
@@ -78,5 +78,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "5c0703f8385fcd34f6d37731e92126fa3390127f40f3f829cb1eb2d33c011bee"
+  "composite": "20903f358de58d2aa87ad426ed158a792c906737d6064d904af4ff0da466c121"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.124.41",
+  "version": "0.124.42",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.124.41",
+  "version": "0.124.42",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -61,6 +61,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.41"
+    "@intentius/chant": "^0.124.42"
   }
 }

package/src/components/generate-pipeline.ts

@@ -63,6 +63,7 @@ import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_JOB_TOKEN, GITHUB_R
 import { CHECKOUT_TOKEN_ENV, checkoutScript, dropForgeTokens, handoverOutputs, handoverTrap, takeOverScript } from "@intentius/chant/ci-handover";
 import { OIDC_REQUEST_VARS, TRADE_SPEC_ENV, tradeLine, type CloudTradeSpec } from "@intentius/chant/ci-identity";
 import {
+  APPLY_COMMENT,
   GREEN_TAG_PATTERN,
   GREEN_TICK_WORKFLOW,
   PR_APPLY_RECORD,
@@ -237,6 +238,15 @@ function gatedWaveGithubDoc(
  * variables a token is requested with, so the pull request's code holds no
  * OIDC token and cannot request one, and the plan job names no apply
  * identity.
+ *
+ * With `applyBeforeMerge` (#4301, ws-106) the apply job runs on a
+ * `/chant apply` comment on a pull request (`issue_comment`), from the
+ * default branch's workflow file, so a pull request cannot change the job
+ * that applies it. It checks out the pull request's head after the setup
+ * and `beforeScript` ran at the default branch's commit, and runs `pr-apply
+ * --before-merge`, which asks the forge the requires checks before any of
+ * the head's code loads. On GitHub the commenter must be an owner, member
+ * or collaborator. A push still records.
  */
 function prLoopGithubDoc(
   components: DriverComponent[],
@@ -310,6 +320,14 @@ function prLoopGithubDoc(
   const forgejo = loop.forge === "forgejo";
   const onGreen = forgejo ? "startsWith(github.ref, 'refs/tags/ci/green/')" : "github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'";
   const onPush = loop.applyOnMerge && forgejo ? "github.event_name == 'push' && startsWith(github.ref, 'refs/heads/')" : "github.event_name == 'push'";
+  // #4301: a `/chant apply` comment on a pull request starts the apply before merge. GitHub also asks for a commenter who can write.
+  const onComment = [
+    "github.event_name == 'issue_comment'",
+    // Forgejo's payload says so with is_pull (terragucci comment-apply.ts:129 at e6cb431).
+    forgejo ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
+    `startsWith(github.event.comment.body, '${APPLY_COMMENT}')`,
+    ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+  ].join(" && ");
   const applyJob = (job: typeof plan, needs: string[], name: string) => ({
     // #4291: a wave after the first runs after one that failed, and blocks only what depends on the failure.
     if: job.jobName === "record" ? onPush : needs.length > 0 && job.wave ? afterEarlierWave(needs[0]!, onGreen) : onGreen,
@@ -330,7 +348,9 @@ function prLoopGithubDoc(
       ])
     : loop.applyOnMerge
       ? [["apply", applyJob(apply, [], "Apply the newest green commit under the merged changes' approvals")]]
-      : [];
+      : loop.applyBeforeMerge
+        ? [["apply", { ...applyJob(apply, [], "Apply the pull request's head under its gate, once it is approved, mergeable, undiverged and green"), if: onComment }]]
+        : [];
   const applyJobs: Array<[string, Record<string, unknown>]> = [recordJob, ...greenJobs];
   // #4295: the plan job runs the pull request's code and holds no forge token while it does.
   const forgeName = loop.forge ?? "github";
@@ -399,6 +419,8 @@ function prLoopGithubDoc(
     on.pull_request = { branches: [branch], types: ["opened", "synchronize", "reopened", "closed"] };
     on.schedule = [{ cron: PR_ENV_SWEEP_CRON }];
   }
+  // #4301: a /chant apply comment starts the apply before merge.
+  if (loop.applyBeforeMerge) on.issue_comment = { types: ["created"] };
   return {
     name: member ? `chant-pr.${member.name}.${env}` : `chant-pr-${env}`,
     environment: env,
@@ -412,7 +434,7 @@ function prLoopGithubDoc(
       { jobName: PR_PLAN_NOTE_JOB, component: "pull request plan note", stage: PR_PLAN_NOTE_JOB, needs: ["plan"] },
       ...applyNames.map((name, i) => ({
         jobName: name,
-        component: name === "record" ? "merge record" : loop.waveGate ? `green apply, wave ${i}` : "green apply",
+        component: name === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : loop.waveGate ? `green apply, wave ${i}` : "green apply",
         stage: name,
         // The record runs on a push and the apply on a green commit, so only the waves need each other.
         needs: i > 1 ? [applyNames[i - 1]] : [],

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

@@ -0,0 +1,67 @@
+/**
+ * The pull-request workflow with an apply before merge (#4301, ws-106): a
+ * `/chant apply` comment starts the apply job from the default branch's
+ * workflow, which checks out the pull request's head and runs `pr-apply
+ * --before-merge` through `chant ci run`. A push still records.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { prLoopJobs, pullRequestCheckout } from "@intentius/chant/components/pr-pipeline";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+];
+
+interface Step { name?: string; run?: string; env?: Record<string, string> }
+interface Job { if: string; permissions: Record<string, string>; steps: Step[] }
+
+describe("the GitHub workflow with --apply-before-merge", () => {
+  const doc = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyBeforeMerge: true } }).yaml) as { on: Record<string, unknown>; jobs: Record<string, Job> };
+
+  test("listens to new comments beside pull requests and pushes, and keeps the record job on a push", () => {
+    expect(doc.on).toEqual({ pull_request: { branches: ["main"] }, push: { branches: ["main"] }, issue_comment: { types: ["created"] } });
+    expect(Object.keys(doc.jobs)).toEqual(["plan", "plan-note", "record", "apply"]);
+    expect(doc.jobs.record!.if).toBe("github.event_name == 'push'");
+  });
+
+  test("the apply runs on a /chant apply comment on a pull request from someone who can write", () => {
+    const cond = doc.jobs.apply!.if;
+    expect(cond).toContain("github.event_name == 'issue_comment'");
+    expect(cond).toContain("github.event.issue.pull_request");
+    expect(cond).toContain("startsWith(github.event.comment.body, '/chant apply')");
+    expect(cond).toContain("github.event.comment.author_association");
+  });
+
+  test("it checks out the pull request's head in its run step and applies before merge with the target branch's commit as the base", () => {
+    const step = doc.jobs.apply!.steps.find((s) => s.run?.includes("chant ci run apply"))!;
+    const lines = step.run!.trimEnd().split("\n");
+    expect(lines[0]).toBe(pullRequestCheckout("github"));
+    expect(lines.at(-1)).toBe('chant ci run apply --in-place --base "$BASE_SHA" --pr "$PR_NUMBER" --apply-before-merge --env prod --gate pr-apply --forge github');
+    expect(step.env).toMatchObject({ BASE_SHA: "${{ github.sha }}", PR_NUMBER: "${{ github.event.issue.number }}" });
+  });
+
+  test("the command chant ci run rebuilds asks pr-apply for the apply before merge", () => {
+    const apply = prLoopJobs("github", "prod", { applyBeforeMerge: true }).find((j) => j.jobName === "apply")!;
+    expect(apply.command).toBe('chant components pr-apply --before-merge --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge github --resume .chant/pr-resume/pr-apply.json');
+  });
+
+  test("it takes no apply on merge, no wave gate and no build", () => {
+    expect(() => prLoopJobs("github", "prod", { applyBeforeMerge: true, applyOnMerge: true })).toThrow(/--apply-on-merge/);
+    expect(() => prLoopJobs("github", "prod", { applyBeforeMerge: true, waveGate: "w" })).toThrow(/--wave-gate/);
+    expect(() => prLoopJobs("github", "prod", { applyBeforeMerge: true, build: true })).toThrow(/--pr-build/);
+  });
+
+  test("the pull request checkout refuses a number that is not one", () => {
+    expect(pullRequestCheckout("github")).toMatch(/^echo "\$PR_NUMBER" \| grep -Eq '\^\[0-9\]\+\$' && git fetch --quiet origin "\+refs\/pull\/\$PR_NUMBER\/head:/);
+    expect(pullRequestCheckout("gitlab")).toContain("refs/merge-requests/$PR_NUMBER/head");
+  });
+
+  test("on Forgejo the comment may also say so with is_pull, and there is no author association", () => {
+    const forgejo = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyBeforeMerge: true, forge: "forgejo" } }).yaml) as { jobs: Record<string, Job> };
+    expect(forgejo.jobs.apply!.if).toContain("(github.event.issue.pull_request || github.event.is_pull)");
+    expect(forgejo.jobs.apply!.if).not.toContain("author_association");
+  });
+});