@intentius/chant-lexicon-github 0.116.0 → 0.118.0

package/dist/components/generate-op-waves-pipeline.d.ts

@@ -13,6 +13,16 @@
  * deciding job uploads its decision, even when it waits, and each share job
  * downloads it. The forgejo generator reuses {@link buildGithubOpWavesDoc}
  * and applies its dialect.
+ *
+ * With `resume` on the spec (#3683), a second workflow, `<name>-resume.yml`,
+ * runs `chant run resume --op <name>` on that schedule: it re-runs the failed
+ * jobs of a run whose waiting wave has been approved since, with the job's
+ * token and `actions: write`.
+ *
+ * When a wave's approval is `pr-review` (#3684), the workflow also asks for
+ * `pull-requests: read`, so a wave can read the merged pull request's
+ * reviews, and a second workflow, `<name>-plans.yml`, runs `chant run wave
+ * --record-plans` on each pull request to record the digests its head plans.
  */
 import { type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
@@ -25,6 +35,8 @@ export declare function opWaveRecordArtifact(spec: Pick<OpWavesSpec, "name">, wa
 export declare function buildGithubOpWavesDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): {
     doc: GithubOpPipelineDoc;
     jobs: OpWavesPipelineResult["jobs"];
+    resumeDoc?: GithubOpPipelineDoc;
+    plansDoc?: GithubOpPipelineDoc;
 };
 /** Render an Op waves spec as one GitHub Actions workflow, `<name>.yml`. */
 export declare function generateGithubOpWavesPipeline(spec: OpWavesSpec, options: OpWavesPipelineOptions): OpWavesPipelineResult;

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

@@ -1 +1 @@
-{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAE9F,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,wBAAwB,CAAC;AAEhC,yFAAyF;AACzF,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAOD,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,GAC9B;IAAE,GAAG,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAA;CAAE,CA0DnE;AAQD,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAGvH"}
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAoC,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAClG,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAE9F,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,wBAAwB,CAAC;AAEhC,yFAAyF;AACzF,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAOD,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,GAC9B;IAAE,GAAG,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAgEpI;AA4CD,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAMvH"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "f949c0f2abdd7cdae723d3c5e0b478955312e5519455f20f466f85267a324ebd",
+    "manifest.json": "a0a217bf875f2999a78da91e06dd0fe33165e52b6077800a76654f75c9e8354d",
     "meta.json": "c50e0ef3845c370c3ad2210b8bba455980417c0f818aa6ed46e06d4fb8b1b9f9",
     "types/index.d.ts": "bdd54a4145a39a9dd4f7bbc8c500191acb6bc9057a87da0040475afac84db397",
     "rules/deprecated-action-version.ts": "d41e6e532ab7f623af1bee4ac5279fcb2baada7defa1c5d022a5bc71983e8797",
@@ -78,5 +78,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "2903da07a25bb2dc474145fdbefc01607599f0f8e64039b5c6428964a8c15b45"
+  "composite": "db3b08fa2fb816149260d6ea9f821c842bbd6317bcb181114380fbb14fd7a734"
 }

package/dist/manifest.json

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

package/package.json

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

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

@@ -30,4 +30,23 @@ describe("generateGithubOpWavesPipeline", () => {
     expect(yaml).toContain("name: migrations-wave-2-decision");
     expect(yaml).toContain("environment:\n      name: production");
   });
+
+  test("resume renders a scheduled workflow that re-runs approved waves with actions: write (#3683)", () => {
+    const { files } = generateGithubOpWavesPipeline({ ...spec, resume: { schedule: "*/10 * * * *" } }, { specFile: "waves.json" });
+    expect(files.map((f) => f.name)).toEqual([`${spec.name}.yml`, `${spec.name}-resume.yml`]);
+    const yaml = files[1]!.yaml;
+    expect(yaml).toContain("- cron: '*/10 * * * *'");
+    expect(yaml).toMatch(/permissions:\n\s+contents: read\n\s+actions: write/);
+    expect(yaml).toContain(`run: chant run resume --op ${spec.name}`);
+    expect(yaml).toContain("GITHUB_TOKEN: '${{ github.token }}'");
+    expect(generateGithubOpWavesPipeline(spec, { specFile: "waves.json" }).files).toHaveLength(1);
+  });
+
+  test("a pr-review wave adds a pull request workflow that records the head's plans (#3684)", () => {
+    const { files } = generateGithubOpWavesPipeline({ ...spec, waves: spec.waves.map((w, i) => (i === spec.waves.length - 1 ? { ...w, approval: "pr-review" as const } : w)) }, { specFile: "waves.json" });
+    expect(files.map((f) => f.name)).toEqual([`${spec.name}.yml`, `${spec.name}-plans.yml`]);
+    expect(files[1]!.yaml).toContain("pull_request:");
+    expect(files[1]!.yaml).toContain("run: chant run wave --spec waves.json --record-plans");
+    expect(files[0]!.yaml).toMatch(/permissions:\n\s+contents: write\n\s+pull-requests: read/);
+  });
 });

package/src/components/generate-op-waves-pipeline.ts

@@ -13,9 +13,19 @@
  * deciding job uploads its decision, even when it waits, and each share job
  * downloads it. The forgejo generator reuses {@link buildGithubOpWavesDoc}
  * and applies its dialect.
+ *
+ * With `resume` on the spec (#3683), a second workflow, `<name>-resume.yml`,
+ * runs `chant run resume --op <name>` on that schedule: it re-runs the failed
+ * jobs of a run whose waiting wave has been approved since, with the job's
+ * token and `actions: write`.
+ *
+ * When a wave's approval is `pr-review` (#3684), the workflow also asks for
+ * `pull-requests: read`, so a wave can read the merged pull request's
+ * reviews, and a second workflow, `<name>-plans.yml`, runs `chant run wave
+ * --record-plans` on each pull request to record the digests its head plans.
  */
 
-import { opWaveJobs, type OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { opWaveJobs, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
 import { actionRef } from "../action-pins";
 import {
@@ -42,9 +52,10 @@ function dirOf(path: string): string {
 export function buildGithubOpWavesDoc(
   spec: OpWavesSpec,
   options: OpWavesPipelineOptions,
-): { doc: GithubOpPipelineDoc; jobs: OpWavesPipelineResult["jobs"] } {
+): { doc: GithubOpPipelineDoc; jobs: OpWavesPipelineResult["jobs"]; resumeDoc?: GithubOpPipelineDoc; plansDoc?: GithubOpPipelineDoc } {
   const jobs = opWaveJobs(spec, options.specFile);
   const image = options.image ?? OP_WAVES_IMAGE;
+  const byReview = spec.waves.some((w) => w.approval === "pr-review");
   for (const wave of spec.waves) {
     assertSetupSteps(`${spec.name}/${wave.name}`, wave.setup ?? []);
     if (wave.environment) assertEnvironment(`${spec.name}/${wave.name}`, wave.environment);
@@ -96,10 +107,51 @@ export function buildGithubOpWavesDoc(
     on: { push: { branches: spec.branches?.length ? spec.branches : ["main"] }, workflow_dispatch: {} },
     ...(options.variables && Object.keys(options.variables).length > 0 ? { env: options.variables } : {}),
     concurrency: { group: spec.name, "cancel-in-progress": false },
-    permissions: { contents: "write" },
+    permissions: { contents: "write", ...(byReview ? { "pull-requests": "read" } : {}) },
     jobsDoc,
   };
-  return { doc, jobs };
+  return {
+    doc,
+    jobs,
+    ...(spec.resume ? { resumeDoc: buildResumeDoc(spec, options) } : {}),
+    ...(byReview ? { plansDoc: buildPlansDoc(spec, options) } : {}),
+  };
+}
+
+/** The scheduled resume workflow (#3683). */
+function buildResumeDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): GithubOpPipelineDoc {
+  const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout") }];
+  for (const line of options.beforeScript ?? []) steps.push({ run: line });
+  steps.push({
+    name: `Resume the waves of ${spec.name} whose approval arrived`,
+    run: opWavesResumeCommand(spec).join(" "),
+    env: { GITHUB_TOKEN: "${{ github.token }}" },
+  });
+  return {
+    name: `${spec.name}-resume`,
+    on: { schedule: [{ cron: spec.resume!.schedule }], workflow_dispatch: {} },
+    concurrency: { group: `${spec.name}-resume`, "cancel-in-progress": true },
+    // contents: read fetches chant/lifecycle; actions: write re-runs a waiting run.
+    permissions: { contents: "read", actions: "write" },
+    jobsDoc: { resume: { "runs-on": "ubuntu-latest", container: options.image ?? OP_WAVES_IMAGE, steps } },
+  };
+}
+
+/** The pull request workflow a `pr-review` wave needs (#3684): record the digests each head plans. */
+function buildPlansDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): GithubOpPipelineDoc {
+  const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout"), with: { "fetch-depth": 0 } }];
+  for (const step of spec.waves[0]?.setup ?? []) steps.push({ ...step });
+  for (const line of options.beforeScript ?? []) steps.push({ run: line });
+  steps.push({ name: "Plan every wave at the head and record its digests", run: ["chant", "run", "wave", "--spec", options.specFile, "--record-plans"].join(" ") });
+  return {
+    name: `${spec.name}-plans`,
+    on: { pull_request: { branches: spec.branches?.length ? spec.branches : ["main"] } },
+    ...(options.variables && Object.keys(options.variables).length > 0 ? { env: options.variables } : {}),
+    concurrency: { group: spec.name + "-plans-${{ github.event.number }}", "cancel-in-progress": true },
+    // contents: write pushes the record to chant/lifecycle.
+    permissions: { contents: "write" },
+    jobsDoc: { "record-plans": { "runs-on": "ubuntu-latest", container: options.image ?? OP_WAVES_IMAGE, steps } },
+  };
 }
 
 function describeJob(kind: "wave" | "decide" | "share", wave: number, name: string, share?: number): string {
@@ -110,6 +162,9 @@ function describeJob(kind: "wave" | "decide" | "share", wave: number, name: stri
 
 /** Render an Op waves spec as one GitHub Actions workflow, `<name>.yml`. */
 export function generateGithubOpWavesPipeline(spec: OpWavesSpec, options: OpWavesPipelineOptions): OpWavesPipelineResult {
-  const { doc, jobs } = buildGithubOpWavesDoc(spec, options);
-  return { files: [{ name: `${spec.name}.yml`, yaml: emitOpPipelineYAML(doc) }], jobs };
+  const { doc, jobs, resumeDoc, plansDoc } = buildGithubOpWavesDoc(spec, options);
+  const files = [{ name: `${spec.name}.yml`, yaml: emitOpPipelineYAML(doc) }];
+  if (resumeDoc) files.push({ name: `${spec.name}-resume.yml`, yaml: emitOpPipelineYAML(resumeDoc) });
+  if (plansDoc) files.push({ name: `${spec.name}-plans.yml`, yaml: emitOpPipelineYAML(plansDoc) });
+  return { files, jobs };
 }