@intentius/chant-lexicon-github 0.115.0 → 0.117.0

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

@@ -0,0 +1,37 @@
+/**
+ * Op waves → GitHub Actions workflow (#3679).
+ *
+ * One workflow for the whole spec, on a push to its branches (and by hand),
+ * one run at a time. Each job is one of core's `opWaveJobs`: a wave, or a wide
+ * wave's deciding job and share jobs, chained by `needs:` so a wave that waits
+ * at its gate (exit 3) or fails stops every later wave. Re-running the failed
+ * jobs after `chant approve` carries on from that wave.
+ *
+ * Every job checks out the full history, because the runner reads the gate
+ * policy from the spec file at the base commit and records pending gates on
+ * `chant/lifecycle`, which is why the workflow asks for `contents: write`. A
+ * 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`.
+ */
+import { type OpWavesSpec } from "@intentius/chant/op/op-waves";
+import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
+import { type GithubOpPipelineDoc } from "./generate-op-pipeline.js";
+/** The default image: it carries git, which the runner needs to read the base commit. */
+export declare const OP_WAVES_IMAGE = "node:22";
+/** The artifact a wide wave's deciding job hands its share jobs. */
+export declare function opWaveRecordArtifact(spec: Pick<OpWavesSpec, "name">, wave: number): string;
+/** The workflow document, before emission, and the jobs it holds. */
+export declare function buildGithubOpWavesDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): {
+    doc: GithubOpPipelineDoc;
+    jobs: OpWavesPipelineResult["jobs"];
+    resumeDoc?: GithubOpPipelineDoc;
+};
+/** Render an Op waves spec as one GitHub Actions workflow, `<name>.yml`. */
+export declare function generateGithubOpWavesPipeline(spec: OpWavesSpec, options: OpWavesPipelineOptions): OpWavesPipelineResult;
+//# sourceMappingURL=generate-op-waves-pipeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;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,CAAA;CAAE,CA0DpG;AA2BD,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAKvH"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "54bbeec529a529e3ddf864c759cc27e02ebc975452e5f12f6e379a0f9527da72",
+    "manifest.json": "80cd8fc60162a6b30fc79202a8992ab61d34b4d245c93553194e489340c32abd",
     "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": "cd58401e7371b5b3af04db5f6d0b5025c96bb3ed91f5ec7c26eb15949eaf9208"
+  "composite": "56d98c73201dd7cf4c5a2ca9153dfd1324ae6cc21adf35f9a956e389f98f51b8"
 }

package/dist/manifest.json

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

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AA6B7F,eAAO,MAAM,YAAY,EAAE,aA8U1B,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AA8B7F,eAAO,MAAM,YAAY,EAAE,aAgV1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.115.0",
+  "version": "0.117.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.115.0",
+    "@intentius/chant": "^0.117.0",
     "typescript": "^5.9.3"
   }
 }

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

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateGithubOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "migrations",
+  op: "migrate",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "never" },
+    { name: "prod", runs: [{ target: "a" }, { target: "b" }], gate: "on-destructive", shares: 2, environment: { name: "production" } },
+  ],
+};
+
+describe("generateGithubOpWavesPipeline", () => {
+  test("one workflow; each wave needs the one before, and a wide wave hands its decision to its shares", () => {
+    const { files, jobs } = generateGithubOpWavesPipeline(spec, { specFile: "waves.json" });
+    expect(files.map((f) => f.name)).toEqual(["migrations.yml"]);
+    expect(jobs.map((j) => j.jobName)).toEqual(["wave-1-dev", "wave-2-prod-decide", "wave-2-prod-share-1", "wave-2-prod-share-2"]);
+    const yaml = files[0]!.yaml;
+    expect(yaml).toContain("push:\n    branches:\n      - main");
+    expect(yaml).toContain("permissions:\n  contents: write");
+    expect(yaml).toContain("fetch-depth: 0");
+    expect(yaml).toContain("run: chant run wave --spec waves.json --wave 1\n");
+    expect(yaml).toMatch(/wave-2-prod-decide:\n\s+runs-on: ubuntu-latest\n\s+needs:\n\s+- wave-1-dev/);
+    expect(yaml).toContain("run: chant run wave --spec waves.json --wave 2 --decide");
+    expect(yaml).toMatch(/wave-2-prod-share-2:\n\s+runs-on: ubuntu-latest\n\s+needs:\n\s+- wave-2-prod-decide/);
+    expect(yaml).toContain("run: chant run wave --spec waves.json --wave 2 --share 2");
+    expect(yaml).toContain("uses: actions/upload-artifact@v4");
+    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);
+  });
+});

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

@@ -0,0 +1,141 @@
+/**
+ * Op waves → GitHub Actions workflow (#3679).
+ *
+ * One workflow for the whole spec, on a push to its branches (and by hand),
+ * one run at a time. Each job is one of core's `opWaveJobs`: a wave, or a wide
+ * wave's deciding job and share jobs, chained by `needs:` so a wave that waits
+ * at its gate (exit 3) or fails stops every later wave. Re-running the failed
+ * jobs after `chant approve` carries on from that wave.
+ *
+ * Every job checks out the full history, because the runner reads the gate
+ * policy from the spec file at the base commit and records pending gates on
+ * `chant/lifecycle`, which is why the workflow asks for `contents: write`. A
+ * 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`.
+ */
+
+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 {
+  assertEnvironment,
+  assertSetupSteps,
+  emitOpPipelineYAML,
+  type GithubOpPipelineDoc,
+} from "./generate-op-pipeline";
+
+/** The default image: it carries git, which the runner needs to read the base commit. */
+export const OP_WAVES_IMAGE = "node:22";
+
+/** The artifact a wide wave's deciding job hands its share jobs. */
+export function opWaveRecordArtifact(spec: Pick<OpWavesSpec, "name">, wave: number): string {
+  return `${spec.name}-wave-${wave}-decision`;
+}
+
+function dirOf(path: string): string {
+  const i = path.lastIndexOf("/");
+  return i < 0 ? "." : path.slice(0, i);
+}
+
+/** The workflow document, before emission, and the jobs it holds. */
+export function buildGithubOpWavesDoc(
+  spec: OpWavesSpec,
+  options: OpWavesPipelineOptions,
+): { doc: GithubOpPipelineDoc; jobs: OpWavesPipelineResult["jobs"]; resumeDoc?: GithubOpPipelineDoc } {
+  const jobs = opWaveJobs(spec, options.specFile);
+  const image = options.image ?? OP_WAVES_IMAGE;
+  for (const wave of spec.waves) {
+    assertSetupSteps(`${spec.name}/${wave.name}`, wave.setup ?? []);
+    if (wave.environment) assertEnvironment(`${spec.name}/${wave.name}`, wave.environment);
+  }
+
+  const jobsDoc: Record<string, unknown> = {};
+  for (const job of jobs) {
+    const wave = spec.waves[job.wave - 1]!;
+    const steps: Array<Record<string, unknown>> = [{ uses: actionRef("actions/checkout"), with: { "fetch-depth": 0 } }];
+    if (job.kind === "share") {
+      steps.push({
+        name: `Download wave ${job.wave}'s decision`,
+        uses: "actions/download-artifact@v4",
+        with: { name: opWaveRecordArtifact(spec, job.wave), path: dirOf(job.record!) },
+      });
+    }
+    for (const step of wave.setup ?? []) steps.push({ ...step });
+    for (const line of options.beforeScript ?? []) steps.push({ run: line });
+    steps.push({ name: describeJob(job.kind, job.wave, wave.name, job.share), run: job.command.join(" ") });
+    for (const line of options.extraScript ?? []) steps.push({ run: line });
+    if (job.kind === "decide") {
+      steps.push({
+        name: `Keep wave ${job.wave}'s decision`,
+        if: "always()",
+        uses: "actions/upload-artifact@v4",
+        with: {
+          name: opWaveRecordArtifact(spec, job.wave),
+          path: job.record!,
+          "if-no-files-found": "ignore",
+          "include-hidden-files": true,
+          overwrite: true,
+        },
+      });
+    }
+    jobsDoc[job.jobName] = {
+      "runs-on": "ubuntu-latest",
+      ...(job.needs.length > 0 ? { needs: job.needs } : {}),
+      container: image,
+      ...(wave.environment
+        ? { environment: { name: wave.environment.name, ...(wave.environment.url ? { url: wave.environment.url } : {}) } }
+        : {}),
+      ...(wave.variables && Object.keys(wave.variables).length > 0 ? { env: wave.variables } : {}),
+      steps,
+    };
+  }
+
+  const doc: GithubOpPipelineDoc = {
+    name: spec.name,
+    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" },
+    jobsDoc,
+  };
+  return { doc, jobs, ...(spec.resume ? { resumeDoc: buildResumeDoc(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 } },
+  };
+}
+
+function describeJob(kind: "wave" | "decide" | "share", wave: number, name: string, share?: number): string {
+  if (kind === "decide") return `Plan wave ${wave} (${name}) and decide its gate`;
+  if (kind === "share") return `Apply share ${share} of wave ${wave} (${name})`;
+  return `Plan, gate and apply wave ${wave} (${name})`;
+}
+
+/** Render an Op waves spec as one GitHub Actions workflow, `<name>.yml`. */
+export function generateGithubOpWavesPipeline(spec: OpWavesSpec, options: OpWavesPipelineOptions): OpWavesPipelineResult {
+  const { doc, jobs, resumeDoc } = buildGithubOpWavesDoc(spec, options);
+  const files = [{ name: `${spec.name}.yml`, yaml: emitOpPipelineYAML(doc) }];
+  if (resumeDoc) files.push({ name: `${spec.name}-resume.yml`, yaml: emitOpPipelineYAML(resumeDoc) });
+  return { files, jobs };
+}

package/src/plugin.ts

@@ -34,6 +34,7 @@ import { GitHubActionsGenerator } from "./import/generator";
 import { githubContextTools } from "./mcp/context-tools";
 import { generateGithubPipeline } from "./components/generate-pipeline";
 import { generateGithubOpPipeline } from "./components/generate-op-pipeline";
+import { generateGithubOpWavesPipeline } from "./components/generate-op-waves-pipeline";
 
 export const githubPlugin: LexiconPlugin = {
   name: "github",
@@ -42,6 +43,8 @@ export const githubPlugin: LexiconPlugin = {
   generateComponentPipeline: (components, options) => generateGithubPipeline(components, options),
   // Generate mode, Op counterpart (#927): synthesize one cron-triggered workflow per scheduled Op.
   generateOpPipeline: (ops, options) => generateGithubOpPipeline(ops, options),
+  // Ordered waves of Op runs, each behind one gate (#3679).
+  generateOpWavesPipeline: (spec, options) => generateGithubOpWavesPipeline(spec, options),
   serializer: githubSerializer,
 
   lintRules(): LintRule[] {