@intentius/chant-lexicon-forgejo 0.117.0 → 0.118.0

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

@@ -11,6 +11,9 @@
  * resume --op <name>` on that schedule. Forgejo has no API to re-run a run,
  * so it dispatches the waves workflow again on its branch, with the
  * `CHANT_FORGE_TOKEN` secret (a token with the `write:repository` scope).
+ *
+ * A `pr-review` wave (#3684) gets `<name>-plans.yml` on pull requests, as on
+ * GitHub. Forgejo's job token reads reviews with no permission to ask for.
  */
 import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";

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;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAMjF,6EAA6E;AAC7E,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,EAC/B,cAAc,GAAE,qBAA0B,GACzC,qBAAqB,CA6CvB"}
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAMjF,6EAA6E;AAC7E,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,EAC/B,cAAc,GAAE,qBAA0B,GACzC,qBAAqB,CA0DvB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "bd0b5cbea165a77cb8a066acbf0d382f8dd45d8d767a4d88ae874e60bac02d0d",
+    "manifest.json": "ba516f57c3a548ed384d4bfcc35134a752f9b9e61a6a3d4ca167ee028f61a005",
     "meta.json": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
     "types/index.d.ts": "66204549b2a864ab5489e3f02c1878e73ab4b3c9d938cfb480b66f71543a43de",
     "rules/delegate-to-github.ts": "1060cda40f4b73d6cca3ba3fa13b80b4886147d4034c88584c2d80c5510dbe5e",
@@ -9,5 +9,5 @@
     "rules/wfj011.ts": "fcb8bf6685d744af20ad804ce929488257995c74b9a3353b2eacae3768d1c83e",
     "skills/chant-forgejo.md": "f28d7fb69fb1cfd992496ef41fda0ea5ccd54a29b84ea1c501a44f6a3992c4d5"
   },
-  "composite": "73b7f0b11a0b2392b370713f429927c565a53e71742ae5a10f2d3be661e9fc4c"
+  "composite": "55b4cd03f51850c9887c8af5d74b7101952ff326184355ac96c1f1ef004662ff"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "forgejo",
-  "version": "0.117.0",
+  "version": "0.118.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Forgejo",
   "intrinsics": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-forgejo",
-  "version": "0.117.0",
+  "version": "0.118.0",
   "description": "Forgejo / Codeberg / Gitea Actions lexicon for chant — a thin GitHub Actions dialect",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -54,8 +54,8 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.117.0",
-    "@intentius/chant-lexicon-github": "^0.117.0"
+    "@intentius/chant": "^0.118.0",
+    "@intentius/chant-lexicon-github": "^0.118.0"
   },
   "scripts": {
     "generate": "tsx src/codegen/generate-cli.ts",

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

@@ -40,4 +40,11 @@ describe("generateForgejoOpWavesPipeline", () => {
     expect(yaml).not.toContain("github.token");
     expect(yaml).not.toMatch(/^permissions:/m);
   });
+
+  test("a pr-review wave adds a pull request workflow that records the head's plans (#3684)", () => {
+    const { files } = generateForgejoOpWavesPipeline({ ...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");
+  });
 });

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

@@ -11,6 +11,9 @@
  * resume --op <name>` on that schedule. Forgejo has no API to re-run a run,
  * so it dispatches the waves workflow again on its branch, with the
  * `CHANT_FORGE_TOKEN` secret (a token with the `write:repository` scope).
+ *
+ * A `pr-review` wave (#3684) gets `<name>-plans.yml` on pull requests, as on
+ * GitHub. Forgejo's job token reads reviews with no permission to ask for.
  */
 
 import { buildGithubOpWavesDoc } from "@intentius/chant-lexicon-github/components/generate-op-waves-pipeline";
@@ -29,7 +32,7 @@ export function generateForgejoOpWavesPipeline(
   options: OpWavesPipelineOptions,
   dialectOptions: ForgejoDialectOptions = {},
 ): OpWavesPipelineResult {
-  const { doc, jobs, resumeDoc } = buildGithubOpWavesDoc(spec, options);
+  const { doc, jobs, resumeDoc, plansDoc } = buildGithubOpWavesDoc(spec, options);
   const jobsDoc = Object.fromEntries(
     Object.entries(doc.jobsDoc).map(([name, job]) => {
       const { environment: _dropped, ...rest } = job as Record<string, unknown>;
@@ -72,5 +75,18 @@ export function generateForgejoOpWavesPipeline(
       }),
     });
   }
+  if (plansDoc) {
+    files.push({
+      name: `${spec.name}-plans.yml`,
+      yaml: emitOpPipelineYAML({
+        name: plansDoc.name!,
+        on: forgejoize(plansDoc.on, dialectOptions),
+        ...(plansDoc.env ? { env: forgejoize(plansDoc.env, dialectOptions) } : {}),
+        concurrency: forgejoize(plansDoc.concurrency, dialectOptions),
+        permissions: {},
+        jobsDoc: forgejoize(plansDoc.jobsDoc, dialectOptions),
+      }),
+    });
+  }
   return { files, jobs };
 }

package/src/components/op-waves.e2e.test.ts

@@ -0,0 +1,222 @@
+/**
+ * #3690 end to end on a real Forgejo with a runner: a two-wave Op pipeline,
+ * rendered by {@link generateForgejoOpWavesPipeline}, whose jobs run this
+ * checkout's `chant run wave`.
+ *
+ * - Wave 1 (`dev`, gate `on-destructive`) plans a destructive run and waits
+ *   at its gate (exit 3). Wave 2 (`prod`, gate `never`) needs it, so it never
+ *   starts and applies nothing.
+ * - `chant approve` of the digest wave 1 printed, then a dispatch of the
+ *   workflow: wave 1 applies and wave 2 runs and applies.
+ * - A broken copy of the workflow with wave 2's `needs` edge removed: wave 1
+ *   still waits, wave 2 runs and applies, and the check the first run passed
+ *   ({@link waitingWaveStoppedNext}) catches it.
+ *
+ * The plan and apply commands are shell scripts in the repository: plan
+ * writes a fixed digest with `destructive: true`, apply prints a marker line.
+ * This checkout's `@intentius/chant` is packed into the repository and each
+ * job installs it, so the jobs run the code under test, not a release.
+ *
+ * Runs only with CHANT_E2E_FORGEJO_URL and CHANT_E2E_FORGEJO_TOKEN (a token
+ * that creates and deletes repositories and pushes to them), against a
+ * Forgejo whose runner takes `docker` jobs and reaches the npm registry.
+ * chant's CI has no Forgejo, so its e2e job skips this file, as it skips the
+ * other Forgejo e2e (`packages/core/src/op/gate-resume.e2e.test.ts`).
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateForgejoOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const URL_ = process.env.CHANT_E2E_FORGEJO_URL?.replace(/\/+$/, "");
+const TOKEN = process.env.CHANT_E2E_FORGEJO_TOKEN;
+const api = `${URL_}/api/v1`;
+
+const CORE = resolve(dirname(fileURLToPath(import.meta.url)), "../../../../packages/core");
+const CHANT = join(CORE, "bin/chant");
+
+const SPEC: OpWavesSpec = {
+  name: "demo",
+  op: "demo",
+  plan: ["sh", "plan.sh", "{target}", "{plan}"],
+  apply: ["sh", "apply.sh", "{target}"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "on-destructive" },
+    { name: "prod", runs: [{ target: "prod" }], gate: "never" },
+  ],
+};
+
+const PLAN_SH = `# Every run's plan is destructive, with a digest fixed by its target.
+printf '{"planDigest":"sha256:%s","destructive":true}' "$(printf '%s' "$1" | sha256sum | cut -d' ' -f1)" > "$2"
+`;
+const APPLY_SH = `echo "CHANT_E2E_APPLIED $1"\n`;
+
+async function call(method: string, path: string, body?: unknown): Promise<any> { // eslint-disable-line @typescript-eslint/no-explicit-any -- untyped forge JSON
+  const res = await fetch(`${api}${path}`, {
+    method,
+    headers: { Authorization: `token ${TOKEN}`, "Content-Type": "application/json" },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${text.slice(0, 300)}`);
+  try {
+    return text ? JSON.parse(text) : null;
+  } catch {
+    return text;
+  }
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+const git = (cwd: string, ...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+
+interface Run {
+  id: number;
+  status: string;
+}
+
+/** One job of a finished run: its name, how it ended and its log. */
+interface JobOutcome {
+  name: string;
+  status: string;
+  log: string;
+}
+
+async function finishedRun(repo: string, after: number, timeoutMs = 600_000): Promise<Run> {
+  const end = Date.now() + timeoutMs;
+  while (Date.now() < end) {
+    const listed = await call("GET", `/repos/${repo}/actions/runs?limit=50`);
+    const run = ((listed.workflow_runs ?? listed) as Run[]).find((r) => r.id > after);
+    if (run && !["waiting", "running", "blocked", "unknown"].includes(run.status)) return run;
+    await sleep(3000);
+  }
+  throw new Error(`no finished run in ${repo} within ${timeoutMs}ms`);
+}
+
+async function jobsOf(repo: string, run: number): Promise<Record<string, JobOutcome>> {
+  const listed = await call("GET", `/repos/${repo}/actions/runs/${run}/jobs`);
+  const out: Record<string, JobOutcome> = {};
+  for (const job of (listed.jobs ?? listed) as Array<{ id: number; name: string; status: string; conclusion?: string }>) {
+    const log = await call("GET", `/repos/${repo}/actions/jobs/${job.id}/logs`).catch(() => "");
+    out[job.name] = { name: job.name, status: job.conclusion || job.status, log: String(log ?? "") };
+  }
+  return out;
+}
+
+const applied = (job: JobOutcome | undefined, target: string) => !!job && job.log.includes(`CHANT_E2E_APPLIED ${target}`);
+
+/**
+ * What the issue asks of a waiting wave: wave 1 waited at its gate, and wave
+ * 2 neither succeeded nor applied anything. Returns why not, or null.
+ */
+function waitingWaveStoppedNext(jobs: Record<string, JobOutcome>): string | null {
+  const first = jobs["wave-1-dev"];
+  const second = jobs["wave-2-prod"];
+  if (!first || first.status !== "failure" || !first.log.includes("Nothing in wave 1 or after it ran")) {
+    return `wave 1 did not wait at its gate (${first?.status ?? "missing"})`;
+  }
+  if (applied(first, "dev")) return "wave 1 applied while waiting";
+  if (second && (second.status === "success" || applied(second, "prod"))) return `wave 2 ran (${second.status}) while wave 1 waited`;
+  return null;
+}
+
+describe.skipIf(!URL_ || !TOKEN)("a waiting Op wave stops the next on Forgejo (#3690)", () => {
+  const stamp = Date.now().toString(36);
+  const work = mkdtempSync(join(tmpdir(), "chant-e2e-waves-"));
+  const created: string[] = [];
+  let owner = "";
+  let tarball = "";
+
+  beforeAll(() => {
+    // This checkout's chant, for the jobs to install. Its declaration build
+    // is skipped: the bin runs the TypeScript sources through tsx.
+    const out = execFileSync("npm", ["pack", "--ignore-scripts", "--silent", "--pack-destination", work], { cwd: CORE, encoding: "utf-8" });
+    tarball = join(work, out.trim().split("\n").pop()!);
+  }, 300_000);
+
+  afterAll(async () => {
+    for (const repo of created) await call("DELETE", `/repos/${repo}`).catch(() => undefined);
+    rmSync(work, { recursive: true, force: true });
+  });
+
+  /**
+   * A repository whose `main` holds two commits: the spec, scripts and chant
+   * first (the base the gate policy is read at), then the workflow. One push
+   * of both runs the workflow once, at the second.
+   */
+  async function pushRepo(name: string, workflow: string): Promise<{ repo: string; dir: string }> {
+    owner ||= (await call("GET", "/user")).login;
+    await call("POST", "/user/repos", { name, auto_init: false, default_branch: "main", private: false });
+    const repo = `${owner}/${name}`;
+    created.push(repo);
+    const dir = join(work, name);
+    mkdirSync(dir);
+    git(dir, "init", "-q", "-b", "main");
+    git(dir, "config", "user.name", "chant e2e");
+    git(dir, "config", "user.email", "chant-e2e@example.invalid");
+    writeFileSync(join(dir, "waves.json"), JSON.stringify(SPEC, null, 2) + "\n");
+    writeFileSync(join(dir, "plan.sh"), PLAN_SH);
+    writeFileSync(join(dir, "apply.sh"), APPLY_SH);
+    writeFileSync(join(dir, ".gitignore"), ".chant/\n");
+    execFileSync("cp", [tarball, join(dir, "chant.tgz")]);
+    git(dir, "add", ".");
+    git(dir, "commit", "-q", "-m", "waves spec, plan and apply");
+    mkdirSync(join(dir, ".forgejo/workflows"), { recursive: true });
+    writeFileSync(join(dir, ".forgejo/workflows/demo.yml"), workflow);
+    git(dir, "add", ".");
+    git(dir, "commit", "-q", "-m", "waves workflow");
+    const remote = new URL(`${URL_}/${repo}.git`);
+    remote.username = owner;
+    remote.password = TOKEN!;
+    git(dir, "remote", "add", "origin", remote.toString());
+    git(dir, "push", "-q", "origin", "main");
+    return { repo, dir };
+  }
+
+  const { files } = generateForgejoOpWavesPipeline(SPEC, { specFile: "waves.json", beforeScript: ["npm install --global --no-audit --no-fund ./chant.tgz"] });
+  const workflow = files[0]!.yaml;
+  const needsEdge = /\n\s+needs:\n\s+- wave-1-dev/;
+
+  test("the rendered workflow chains wave 2 to wave 1", () => {
+    expect(workflow).toMatch(needsEdge);
+  });
+
+  test("wave 1 waits and wave 2 never starts; after chant approve a rerun applies both; without the needs edge the check fails", async () => {
+    const [good, broken] = await Promise.all([
+      pushRepo(`chant-e2e-waves-${stamp}`, workflow),
+      pushRepo(`chant-e2e-waves-broken-${stamp}`, workflow.replace(needsEdge, "")),
+    ]);
+    const [waited, brokenRun] = await Promise.all([finishedRun(good.repo, 0), finishedRun(broken.repo, 0)]);
+
+    // Wave 1 waits at its gate; wave 2 never starts.
+    const first = await jobsOf(good.repo, waited.id);
+    expect(waitingWaveStoppedNext(first)).toBeNull();
+    expect(first["wave-2-prod"]?.status).not.toBe("success");
+
+    // Without the needs edge, wave 2 runs and applies while wave 1 waits, and the check says so.
+    const unchained = await jobsOf(broken.repo, brokenRun.id);
+    expect(unchained["wave-1-dev"]?.status).toBe("failure");
+    expect(applied(unchained["wave-2-prod"], "prod")).toBe(true);
+    expect(waitingWaveStoppedNext(unchained)).toMatch(/wave 2 ran/);
+
+    // Approve the digest wave 1 printed, from a checkout of the repository.
+    const approve = first["wave-1-dev"]!.log.match(/then approve: (chant approve \S+ \S+ --plan \S+)/)?.[1];
+    expect(approve, "wave 1 printed the approve command").toBeDefined();
+    const argv = approve!.split(" ").slice(1);
+    execFileSync(CHANT, argv, { cwd: good.dir, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+    expect(git(good.dir, "ls-remote", "origin", "refs/heads/chant/lifecycle")).toContain("chant/lifecycle");
+
+    // A rerun applies wave 1, then wave 2 runs and applies.
+    await call("POST", `/repos/${good.repo}/actions/workflows/demo.yml/dispatches`, { ref: "main" });
+    const rerun = await finishedRun(good.repo, waited.id);
+    const second = await jobsOf(good.repo, rerun.id);
+    expect(second["wave-1-dev"]?.status).toBe("success");
+    expect(applied(second["wave-1-dev"], "dev")).toBe(true);
+    expect(second["wave-2-prod"]?.status).toBe("success");
+    expect(applied(second["wave-2-prod"], "prod")).toBe(true);
+  }, 1_500_000);
+});