@intentius/chant-lexicon-forgejo 0.58.0 → 0.60.0

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

@@ -16,13 +16,55 @@
  * needs still rides the trigger step's `env:` (`GH_TOKEN`/`GITHUB_TOKEN`,
  * built by github's generator); actual write access on Forgejo is a property
  * of the runner/token configuration, not the workflow YAML.
+ *
+ * That covers a spec's additive `permissions` too (#2242): an `id-token:
+ * write` added for OIDC is dropped here along with the mode's own scopes,
+ * because the Forgejo runner reads none of them and issues no OIDC token off
+ * a workflow permission. A Forgejo job authenticates to a cloud provider
+ * through whatever the runner already holds. A spec's `setup` steps do cross
+ * over unchanged: Forgejo runs `uses:` steps, so they are emitted in the
+ * position github puts them (after the checkout, ahead of the `beforeScript`
+ * lines) with the dialect's own action-ref rewrite applied — an action with
+ * no mapping in ../actions.ts passes through verbatim and resolves only if
+ * the runner can fetch it.
+ *
+ * One finding-mode does not cross over: `comment` (#2231) posts onto the
+ * triggering pull request by shelling to `gh` against the GitHub API and
+ * reading the GitHub Actions event payload. Forgejo's API is
+ * GitHub-compatible in shape, but chant has no Forgejo client and no host
+ * configuration to point `gh` at a Forgejo instance, so this refuses the mode
+ * by name rather than generating a job whose finding step fails on every run.
+ *
+ * A spec's `environment` (#2257) is dropped on the same terms as
+ * `permissions:`, and for a stronger reason: Forgejo Actions has no
+ * environments at all — no protection rules, no required reviewers, no
+ * per-environment secrets — so the key names an object that does not exist on
+ * the instance. Dropping it silently would be the worst outcome available,
+ * because the whole point of the option is a human holding an apply, so this
+ * also writes a comment into the generated file's header saying which
+ * environment was asked for and that nothing on Forgejo enforces it. What
+ * still holds the apply here is chant's own gate (#2119), which is a fact on
+ * the `chant/lifecycle` branch and needs nothing from the forge.
+ *
+ * The gated-apply notice job (#2243) does not cross over either, for the same
+ * reason and by the same mechanism as `permissions:`: it shells to `gh`, which
+ * a Forgejo `act_runner` neither ships nor can point at its own instance, and
+ * it runs outside the Op's container image, where a hosted GitHub runner's
+ * preinstalled tools would be. So the doc rebuilt below simply does not carry
+ * `gatedNoticeDoc`, and the job is dropped. What does cross over is the half
+ * that needs no forge API: a `push` job still runs with `--gated-exit 0`, so a
+ * Forgejo apply that stops at its gate is a green run rather than a red one,
+ * and `chant run` still writes the gate and the approve command to
+ * `GITHUB_STEP_SUMMARY`, which Forgejo Actions sets like GitHub does.
  */
 import type { ComponentPipelineOptions, OpPipelineResult, ScheduledOpSpec } from "@intentius/chant/lexicon";
 import { type ForgejoDialectOptions } from "../dialect.js";
 /**
  * Synthesize one `.forgejo/workflows/*.yml` per scheduled Op. Reuses github's
- * trigger/job structure ({@link buildGithubOpPipelineDocs}), then applies the
- * Forgejo dialect and drops `permissions:` (ignored by the Forgejo runner).
+ * trigger/job structure ({@link buildGithubOpPipelineDocs}) — its `setup`-step
+ * and additive-permission validation included, so an unpinned action ref is
+ * refused here on the same terms — then applies the Forgejo dialect and drops
+ * `permissions:` (ignored by the Forgejo runner).
  * Wired into core's Op generate mode via the forgejo lexicon plugin's
  * `generateOpPipeline` (../plugin.ts).
  */

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

@@ -1 +1 @@
-{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAOjF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,wBAA6B,EACtC,cAAc,GAAE,qBAA0B,GACzC,gBAAgB,CAgBlB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAOH,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAmCjF;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,wBAA6B,EACtC,cAAc,GAAE,qBAA0B,GACzC,gBAAgB,CA+BlB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "680e6414892aa4dcb70e374a8a17761020aed986ed03d988ca82ad685654f632",
+    "manifest.json": "56a899fd87d95111c56cb551f5a4961c91af788fb0a11c3ef4f9fb207f5abd3f",
     "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": "a1a560429db736c187e0b34cf8dd9efc6ad771afefcbf6f802d160d3d5274257"
   },
-  "composite": "c2da4b8dc0e9d2cc2f1f2d6d0e800fddfe16e1eccf2e23b196883b937b8f56bc"
+  "composite": "390ec307dcfc42c1e376d49ee30e4f78429b316ded7bce20355efded9327d04e"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-forgejo",
-  "version": "0.58.0",
+  "version": "0.60.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.58.0",
-    "@intentius/chant-lexicon-github": "^0.58.0"
+    "@intentius/chant": "^0.60.0",
+    "@intentius/chant-lexicon-github": "^0.60.0"
   },
   "scripts": {
     "generate": "tsx src/codegen/generate-cli.ts",

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

@@ -14,7 +14,9 @@ import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
 
 interface ParsedJob {
   "runs-on"?: string;
-  steps: Array<{ uses?: string; run?: string }>;
+  environment?: Record<string, string>;
+  outputs?: Record<string, string>;
+  steps: Array<{ id?: string; uses?: string; run?: string }>;
 }
 interface ParsedDoc {
   on?: Record<string, unknown>;
@@ -102,3 +104,176 @@ describe("generateForgejoOpPipeline: non-cron trigger survives the dialect trans
     expect(fj.files[0].yaml).not.toMatch(/^permissions:/m);
   });
 });
+
+describe("generateForgejoOpPipeline: no comment finding mode (#2231)", () => {
+  test("findingMode comment is refused by name, on the pull_request trigger it would otherwise fit", () => {
+    // Forgejo Actions runs the same workflow shape and Forgejo's API is
+    // GitHub-compatible, but the activity behind the mode shells to `gh`
+    // against github.com and reads the GitHub Actions event payload. Nothing
+    // in chant points either at a Forgejo instance, so the mode is refused
+    // here rather than generating a job that fails at its Report step.
+    const specs: ScheduledOpSpec[] = [
+      { name: "app-plan", trigger: { kind: "pull_request", branches: ["main"] }, findingMode: "comment" },
+    ];
+    expect(() => generateForgejoOpPipeline(specs)).toThrow(
+      /Scheduled Op "app-plan".*findingMode "comment".*no Forgejo API client/s,
+    );
+  });
+
+  test("github generates the same spec, so the refusal is forgejo's and not the shared builder's", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "app-plan", trigger: { kind: "pull_request", branches: ["main"] }, findingMode: "comment" },
+    ];
+    const gh = parseFile(generateGithubOpPipeline(specs).files[0].yaml);
+    expect(gh.permissions).toEqual({ contents: "read", "pull-requests": "write" });
+  });
+});
+
+/**
+ * #2242 crosses the dialect asymmetrically: Forgejo runs `uses:` steps, so a
+ * spec's `setup` list is emitted; it ignores `permissions:`, so an additive
+ * scope is dropped with the rest of the section rather than emitted as a
+ * control the runner never reads.
+ */
+describe("generateForgejoOpPipeline: setup steps and additive permissions (#2242)", () => {
+  const OIDC_SPEC: ScheduledOpSpec = {
+    name: "app-apply",
+    trigger: { kind: "push", branches: ["main"] },
+    setup: [
+      {
+        uses: "aws-actions/configure-aws-credentials@v6",
+        with: { "role-to-assume": "${{ vars.AWS_ROLE_ARN }}", "aws-region": "eu-west-1" },
+      },
+    ],
+    permissions: { "id-token": "write" },
+  };
+
+  test("emits the setup step after the checkout, with its `with:` intact", () => {
+    const doc = parseFile(generateForgejoOpPipeline([OIDC_SPEC]).files[0].yaml);
+    const steps = doc.jobs!["app-apply"].steps;
+    // The checkout is rewritten to the Forgejo mirror; an action with no
+    // mapping in ../actions.ts passes through verbatim.
+    expect(steps[0].uses).toContain("actions/checkout@v4");
+    expect(steps[1].uses).toBe("aws-actions/configure-aws-credentials@v6");
+    expect((steps[1] as { with?: Record<string, string> }).with).toEqual({
+      "role-to-assume": "${{ vars.AWS_ROLE_ARN }}",
+      "aws-region": "eu-west-1",
+    });
+  });
+
+  test("drops the additive permission along with the mode's own scopes", () => {
+    const yaml = generateForgejoOpPipeline([OIDC_SPEC]).files[0].yaml;
+    expect(yaml).not.toContain("permissions:");
+    expect(yaml).not.toContain("id-token");
+    // The same spec on github does carry it — this is a dialect drop, not a
+    // generator that never computed the scope.
+    expect(generateGithubOpPipeline([OIDC_SPEC]).files[0].yaml).toContain("id-token: write");
+  });
+
+  test("refuses an unpinned action ref on the same terms as github", () => {
+    expect(() =>
+      generateForgejoOpPipeline([{ ...OIDC_SPEC, setup: [{ uses: "aws-actions/configure-aws-credentials@main" }] }]),
+    ).toThrow(/the action repository's own default branch/);
+  });
+});
+
+describe("generateForgejoOpPipeline: the gated apply on push (#2243)", () => {
+  const pushSpec: ScheduledOpSpec = { name: "app-apply", trigger: { kind: "push", branches: ["main"] } };
+
+  test("the exit mapping crosses over: a gated apply is a green Forgejo run too", () => {
+    // `--gated-exit 0` is `chant run`'s own, so it needs nothing from the
+    // runner. `GITHUB_STEP_SUMMARY`, which the gate block goes to, is set by
+    // Forgejo's act_runner the same way GitHub sets it.
+    const doc = parseFile(generateForgejoOpPipeline([pushSpec]).files[0].yaml);
+    const step = doc.jobs!["app-apply"].steps.find((s) => s.id === "chant-run");
+    expect(step?.run).toContain("chant run app-apply --gated-exit 0 --json");
+  });
+
+  test("the notice job does not: it shells to `gh`, which no Forgejo runner points at its own instance", () => {
+    const fj = parseFile(generateForgejoOpPipeline([pushSpec]).files[0].yaml);
+    const gh = parseFile(generateGithubOpPipeline([pushSpec]).files[0].yaml);
+    // Dropped the same way `permissions:` is dropped — by not being carried
+    // onto the rebuilt doc — and github still has it, so the omission is
+    // forgejo's rather than the shared builder's.
+    expect(Object.keys(fj.jobs ?? {})).toEqual(["app-apply"]);
+    expect(gh.jobs).toHaveProperty("app-apply-gate-notice");
+  });
+});
+
+/**
+ * chant #2257 — the option Forgejo has no concept for at all. Unlike
+ * `permissions:`, which the runner reads and ignores, an environment is an
+ * object that does not exist on a Forgejo instance: no protection rules, no
+ * required reviewers, no wait timers. Emitting the key would read as a
+ * deployment gate and hold nothing back, so it is dropped — and, because the
+ * whole point of the option is a human holding an apply, the drop is said out
+ * loud in the file rather than only in a build warning.
+ */
+describe("generateForgejoOpPipeline: a dropped deployment environment (#2257)", () => {
+  const APPLY: ScheduledOpSpec = { name: "app-apply", trigger: { kind: "push", branches: ["main"] } };
+  const GATED: ScheduledOpSpec = { ...APPLY, environment: { name: "production" } };
+
+  /** The document a spec with no `environment` emitted before the option existed. */
+  const AUDIT_YAML_BEFORE_2257 =
+    [
+      "on:",
+      "  schedule:",
+      "    - cron: '0 6 * * *'",
+      "  workflow_dispatch: {}",
+      "",
+      "concurrency:",
+      "  group: actions-audit",
+      "  cancel-in-progress: false",
+      "",
+      "jobs:",
+      "  actions-audit:",
+      "    runs-on: docker",
+      "    container: node:22-slim",
+      "    steps:",
+      "      - uses: https://code.forgejo.org/actions/checkout@v4",
+      "      - run: chant run actions-audit",
+      "        env:",
+      "          GITHUB_TOKEN: '${{ github.token }}'",
+      "          GH_TOKEN: '${{ github.token }}'",
+    ].join("\n") + "\n";
+
+  test("a spec with no environment emits the bytes it emitted before the option existed", () => {
+    const yaml = generateForgejoOpPipeline([
+      { name: "actions-audit", schedule: "0 6 * * *", findingMode: "issue" },
+    ]).files[0].yaml;
+    expect(yaml).toBe(AUDIT_YAML_BEFORE_2257);
+  });
+
+  test("drops the key, and github with the same spec keeps it", () => {
+    const fj = parseFile(generateForgejoOpPipeline([GATED]).files[0].yaml);
+    expect(fj.jobs!["app-apply"].environment).toBeUndefined();
+    // A dialect drop, not a builder that never computed it.
+    expect(generateGithubOpPipeline([GATED]).files[0].yaml).toContain("environment:");
+  });
+
+  test("says in the generated header which environment did not survive, and what still gates", () => {
+    const yaml = generateForgejoOpPipeline([GATED]).files[0].yaml;
+    expect(yaml.startsWith("# chant dropped `environment: production`")).toBe(true);
+    expect(yaml).toContain("Forgejo Actions has no");
+    expect(yaml).toContain("not held back by anything on the forge");
+    // The gate that does survive is chant's own, which needs nothing from the forge.
+    expect(yaml).toContain("chant/lifecycle");
+    expect(yaml).toContain("approve <op> <gate>");
+  });
+
+  test("the header only appears for the Op that asked for an environment", () => {
+    const files = generateForgejoOpPipeline([
+      { ...GATED, name: "app-apply" },
+      { name: "app-watch", schedule: "0 6 * * *" },
+    ]).files;
+    expect(files[0].yaml).toContain("# chant dropped `environment: production`");
+    expect(files[1].yaml).not.toContain("# chant dropped");
+    expect(files[1].yaml.startsWith("on:")).toBe(true);
+  });
+
+  test("refuses the same malformed environment github refuses, through the shared builder", () => {
+    expect(() =>
+      generateForgejoOpPipeline([{ ...APPLY, environment: { name: "production", url: "/deploys" } }]),
+    ).toThrow(/neither an absolute http\(s\) URL nor a/);
+  });
+});

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

@@ -16,6 +16,46 @@
  * needs still rides the trigger step's `env:` (`GH_TOKEN`/`GITHUB_TOKEN`,
  * built by github's generator); actual write access on Forgejo is a property
  * of the runner/token configuration, not the workflow YAML.
+ *
+ * That covers a spec's additive `permissions` too (#2242): an `id-token:
+ * write` added for OIDC is dropped here along with the mode's own scopes,
+ * because the Forgejo runner reads none of them and issues no OIDC token off
+ * a workflow permission. A Forgejo job authenticates to a cloud provider
+ * through whatever the runner already holds. A spec's `setup` steps do cross
+ * over unchanged: Forgejo runs `uses:` steps, so they are emitted in the
+ * position github puts them (after the checkout, ahead of the `beforeScript`
+ * lines) with the dialect's own action-ref rewrite applied — an action with
+ * no mapping in ../actions.ts passes through verbatim and resolves only if
+ * the runner can fetch it.
+ *
+ * One finding-mode does not cross over: `comment` (#2231) posts onto the
+ * triggering pull request by shelling to `gh` against the GitHub API and
+ * reading the GitHub Actions event payload. Forgejo's API is
+ * GitHub-compatible in shape, but chant has no Forgejo client and no host
+ * configuration to point `gh` at a Forgejo instance, so this refuses the mode
+ * by name rather than generating a job whose finding step fails on every run.
+ *
+ * A spec's `environment` (#2257) is dropped on the same terms as
+ * `permissions:`, and for a stronger reason: Forgejo Actions has no
+ * environments at all — no protection rules, no required reviewers, no
+ * per-environment secrets — so the key names an object that does not exist on
+ * the instance. Dropping it silently would be the worst outcome available,
+ * because the whole point of the option is a human holding an apply, so this
+ * also writes a comment into the generated file's header saying which
+ * environment was asked for and that nothing on Forgejo enforces it. What
+ * still holds the apply here is chant's own gate (#2119), which is a fact on
+ * the `chant/lifecycle` branch and needs nothing from the forge.
+ *
+ * The gated-apply notice job (#2243) does not cross over either, for the same
+ * reason and by the same mechanism as `permissions:`: it shells to `gh`, which
+ * a Forgejo `act_runner` neither ships nor can point at its own instance, and
+ * it runs outside the Op's container image, where a hosted GitHub runner's
+ * preinstalled tools would be. So the doc rebuilt below simply does not carry
+ * `gatedNoticeDoc`, and the job is dropped. What does cross over is the half
+ * that needs no forge API: a `push` job still runs with `--gated-exit 0`, so a
+ * Forgejo apply that stops at its gate is a green run rather than a red one,
+ * and `chant run` still writes the gate and the approve command to
+ * `GITHUB_STEP_SUMMARY`, which Forgejo Actions sets like GitHub does.
  */
 
 import {
@@ -35,10 +75,40 @@ function forgejoize(value: Record<string, unknown>, dialect: ForgejoDialectOptio
   return transformWorkflowObject(value, dialect).value as Record<string, unknown>;
 }
 
+/**
+ * Strip the job-level `environment:` github emitted (#2257). Forgejo Actions
+ * has no environments, so the key would read as a deployment gate and hold
+ * nothing back. Dropped from the rebuilt doc rather than from the dialect's
+ * own `DROPPED_KEYS`, so this touches the Op generator alone and leaves every
+ * other document the dialect transforms exactly as it emits today.
+ */
+function withoutEnvironment(jobsDoc: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(jobsDoc).map(([jobName, job]) => {
+      if (typeof job !== "object" || job === null || !("environment" in job)) return [jobName, job];
+      const { environment: _dropped, ...rest } = job as Record<string, unknown>;
+      return [jobName, rest];
+    }),
+  );
+}
+
+/** Say in the generated file which environment gate did not survive the crossing. */
+function droppedEnvironmentHeader(environmentName: string): string[] {
+  return [
+    `# chant dropped \`environment: ${environmentName}\` from this workflow: Forgejo Actions has no`,
+    "# environments, so there is no protection rule, required reviewer or wait timer for the key to",
+    "# name. This job is not held back by anything on the forge. What still stops the apply is chant's",
+    "# own gate: the run records a pending fact on the chant/lifecycle branch and ends, and `chant",
+    "# approve <op> <gate>` is what lets the next run through.",
+  ];
+}
+
 /**
  * Synthesize one `.forgejo/workflows/*.yml` per scheduled Op. Reuses github's
- * trigger/job structure ({@link buildGithubOpPipelineDocs}), then applies the
- * Forgejo dialect and drops `permissions:` (ignored by the Forgejo runner).
+ * trigger/job structure ({@link buildGithubOpPipelineDocs}) — its `setup`-step
+ * and additive-permission validation included, so an unpinned action ref is
+ * refused here on the same terms — then applies the Forgejo dialect and drops
+ * `permissions:` (ignored by the Forgejo runner).
  * Wired into core's Op generate mode via the forgejo lexicon plugin's
  * `generateOpPipeline` (../plugin.ts).
  */
@@ -47,16 +117,31 @@ export function generateForgejoOpPipeline(
   options: ComponentPipelineOptions = {},
   dialectOptions: ForgejoDialectOptions = {},
 ): OpPipelineResult {
+  for (const spec of ops) {
+    if (spec.findingMode === "comment") {
+      throw new Error(
+        `Scheduled Op "${spec.name}" has findingMode "comment", which posts its finding on the pull request ` +
+          `that triggered the run. That activity shells to \`gh\` against the GitHub API and reads the ` +
+          `GitHub Actions event payload; chant carries no Forgejo API client to post the equivalent comment ` +
+          `(#2231). Use findingMode "issue" here, or generate this Op for github.`,
+      );
+    }
+  }
+
   const { files, jobs } = buildGithubOpPipelineDocs(ops, options);
 
   return {
-    files: files.map(({ name, doc }) => {
+    // One file per spec, in spec order, which is what lets the header below
+    // read its Op's own `environment` off the input by position.
+    files: files.map(({ name, doc }, index) => {
+      const environment = ops[index].environment;
       const forgejoDoc: GithubOpPipelineDoc = {
+        ...(environment ? { header: droppedEnvironmentHeader(environment.name) } : {}),
         on: forgejoize(doc.on, dialectOptions),
         ...(doc.env ? { env: forgejoize(doc.env, dialectOptions) } : {}),
         concurrency: forgejoize(doc.concurrency, dialectOptions),
         permissions: {},
-        jobsDoc: forgejoize(doc.jobsDoc, dialectOptions),
+        jobsDoc: forgejoize(withoutEnvironment(doc.jobsDoc), dialectOptions),
       };
       return { name, yaml: emitOpPipelineYAML(forgejoDoc) };
     }),

package/src/serializer.test.ts

@@ -151,5 +151,9 @@ describe("forgejoSerializer — inherits PrPlanReport from github (#1983)", () =
     // The sticky-comment mechanism is a raw script, nothing to remap or drop.
     expect(result.primary).toContain("Post or update PR comment");
     expect(result.primary).toContain("gh api");
+    // Including the `-F` that reads the body from plan.md — forgejo renders
+    // the same script, so the #2236 regression would show up here as well.
+    expect(result.primary).toContain("-F body=@plan.md");
+    expect(result.primary).not.toContain("-f body=@");
   });
 });