@intentius/chant-lexicon-forgejo 0.4.0

package/src/serializer.test.ts

@@ -0,0 +1,124 @@
+import { describe, test, expect } from "vitest";
+import { Workflow, Job, Step, Checkout, SetupNode } from "@intentius/chant-lexicon-github";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { forgejoSerializer } from "./serializer";
+import { DEFAULT_ACTIONS_ROOT } from "./actions";
+
+function asResult(out: string | SerializerResult): SerializerResult {
+  return typeof out === "string" ? { primary: out } : out;
+}
+
+describe("forgejoSerializer identity", () => {
+  test("claims the github partition with a distinct rule prefix", () => {
+    // name is "github" on purpose — it serializes github-lexicon entities.
+    expect(forgejoSerializer.name).toBe("github");
+    expect(forgejoSerializer.rulePrefix).toBe("WFJ");
+  });
+});
+
+describe("forgejoSerializer — github-style source roundtrip", () => {
+  function buildSource(): Map<string, Declarable> {
+    const workflow = new Workflow({
+      name: "CI",
+      on: { push: { branches: ["main"] } },
+      permissions: { contents: "read" },
+    }) as unknown as Declarable;
+    const build = new Job({
+      "runs-on": "ubuntu-latest",
+      "continue-on-error": true,
+      steps: [
+        new Step({ name: "Build", run: "npm run build", "continue-on-error": true }),
+        new Step({ name: "Test", run: "npm test" }),
+      ],
+    }) as unknown as Declarable;
+    return new Map<string, Declarable>([
+      ["workflow", workflow],
+      ["build", build],
+    ]);
+  }
+
+  test("emits on/jobs/steps from reused github entities", () => {
+    const { primary } = asResult(forgejoSerializer.serialize(buildSource()));
+    expect(primary).toContain("on:");
+    expect(primary).toContain("jobs:");
+    expect(primary).toContain("push:");
+    expect(primary).toContain("Build");
+    expect(primary).toContain("npm run build");
+  });
+
+  test("drops permissions and continue-on-error, warning on each", () => {
+    const result = asResult(forgejoSerializer.serialize(buildSource()));
+    expect(result.primary).not.toContain("permissions");
+    expect(result.primary).not.toContain("continue-on-error");
+    // workflow permissions + job continue-on-error + step continue-on-error
+    expect((result.warnings ?? []).filter((w) => w.includes("permissions"))).toHaveLength(1);
+    expect((result.warnings ?? []).filter((w) => w.includes("continue-on-error"))).toHaveLength(2);
+  });
+
+  test("maps ubuntu-latest to the default Forgejo runner label", () => {
+    const { primary } = asResult(forgejoSerializer.serialize(buildSource()));
+    expect(primary).toContain("runs-on: docker");
+    expect(primary).not.toContain("ubuntu-latest");
+  });
+
+  test("a chant.config forgejo.runnerLabels override changes the label", () => {
+    const out = forgejoSerializer.serialize(buildSource(), undefined, {
+      config: { forgejo: { runnerLabels: { "ubuntu-latest": "big-runner" } } },
+    });
+    expect(asResult(out).primary).toContain("runs-on: big-runner");
+  });
+
+  test("an unmapped label passes through (WFJ011 reports it post-synth, not the serializer)", () => {
+    const job = new Job({ "runs-on": "windows-latest", steps: [new Step({ run: "echo hi" })] }) as unknown as Declarable;
+    const out = forgejoSerializer.serialize(new Map([["build", job]]));
+    const result = asResult(out);
+    expect(result.primary).toContain("runs-on: windows-latest");
+    expect((result.warnings ?? []).filter((w) => w.includes("windows-latest"))).toHaveLength(0);
+  });
+});
+
+describe("forgejoSerializer — uses: action resolution", () => {
+  function withSteps(...steps: unknown[]): Map<string, Declarable> {
+    const job = new Job({ "runs-on": "ubuntu-latest", steps }) as unknown as Declarable;
+    return new Map<string, Declarable>([["build", job]]);
+  }
+
+  test("rewrites composite-emitted action refs under the actions root", () => {
+    const { primary } = asResult(
+      forgejoSerializer.serialize(withSteps(Checkout({}).step, SetupNode({ nodeVersion: "22" }).step)),
+    );
+    expect(primary).toContain(`uses: ${DEFAULT_ACTIONS_ROOT}/actions/checkout@v4`);
+    expect(primary).toContain(`uses: ${DEFAULT_ACTIONS_ROOT}/actions/setup-node@v4`);
+  });
+
+  test("forgejo.actionsRoot override changes the rewritten base", () => {
+    const out = forgejoSerializer.serialize(withSteps(Checkout({}).step), undefined, {
+      config: { forgejo: { actionsRoot: "https://codeberg.org" } },
+    });
+    expect(asResult(out).primary).toContain("uses: https://codeberg.org/actions/checkout@v4");
+  });
+
+  test("an unmapped action ref is passed through (WFJ010 reports it post-synth)", () => {
+    const step = new Step({ name: "Custom", uses: "some-org/custom-action@v1" });
+    const result = asResult(forgejoSerializer.serialize(withSteps(step)));
+    expect(result.primary).toContain("uses: some-org/custom-action@v1");
+    expect((result.warnings ?? []).filter((w) => w.includes("some-org/custom-action@v1"))).toHaveLength(0);
+  });
+});
+
+describe("forgejoSerializer — multi-workflow output", () => {
+  test("additional workflows become separate files", () => {
+    const a = new Workflow({ name: "A", on: { push: {} } }) as unknown as Declarable;
+    const b = new Workflow({ name: "B", on: { push: {} } }) as unknown as Declarable;
+    const out = forgejoSerializer.serialize(
+      new Map<string, Declarable>([
+        ["ci", a],
+        ["release", b],
+      ]),
+    );
+    const result = asResult(out);
+    expect(result.primary).toContain("name: A");
+    expect(Object.keys(result.files ?? {})).toContain("release.yml");
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,62 @@
+/**
+ * Forgejo Actions YAML serializer.
+ *
+ * A thin dialect of the github serializer: it applies the Forgejo dialect
+ * (see ./dialect) to the entity graph, then delegates emission to the github
+ * serializer, which already produces GitHub-Actions-compatible YAML — exactly
+ * what Forgejo / Codeberg / Gitea runners execute.
+ *
+ * The serializer's `name` is "github" on purpose: github-lexicon entities are
+ * tagged `lexicon: "github"`, and the build pipeline partitions and looks up
+ * serializers by that tag. A forgejo project loads only this serializer, so it
+ * claims that partition. The distinct `rulePrefix` ("WFJ") keeps Forgejo lint
+ * diagnostics namespaced apart from github's "GHA".
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializerResult, SerializeContext } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { githubSerializer } from "@intentius/chant-lexicon-github";
+import { applyForgejoDialect, type ForgejoDialectOptions } from "./dialect";
+
+/** Extract forgejo dialect options from the resolved project config, if any. */
+function readForgejoOptions(config: Record<string, unknown> | undefined): ForgejoDialectOptions {
+  const forgejo = config?.forgejo;
+  if (!forgejo || typeof forgejo !== "object") return {};
+  const obj = forgejo as Record<string, unknown>;
+  const options: ForgejoDialectOptions = {};
+  if (obj.runnerLabels && typeof obj.runnerLabels === "object") {
+    options.runnerLabels = obj.runnerLabels as Record<string, string>;
+  }
+  if (typeof obj.actionsRoot === "string") {
+    options.actionsRoot = obj.actionsRoot;
+  }
+  return options;
+}
+
+/**
+ * Forgejo Actions YAML serializer implementation.
+ */
+export const forgejoSerializer: Serializer = {
+  name: "github",
+  rulePrefix: "WFJ",
+
+  serialize(
+    entities: Map<string, Declarable>,
+    outputs?: LexiconOutput[],
+    context?: SerializeContext,
+  ): string | SerializerResult {
+    const options = readForgejoOptions(context?.config);
+    const { entities: transformed, warnings } = applyForgejoDialect(entities, options);
+
+    const result = githubSerializer.serialize(transformed, outputs, context);
+
+    if (typeof result === "string") {
+      return warnings.length > 0 ? { primary: result, warnings } : result;
+    }
+    return {
+      ...result,
+      warnings: [...(result.warnings ?? []), ...warnings],
+    };
+  },
+};

package/src/skills/chant-forgejo.md

@@ -0,0 +1,68 @@
+# chant-forgejo
+
+Forgejo / Codeberg / Gitea Actions with chant.
+
+Forgejo runs **GitHub-Actions-compatible** workflows, so the forgejo lexicon is
+a thin dialect of the github lexicon. You author exactly as you would for GitHub
+Actions — same `Workflow`, `Job`, `Step`, and composites — but import from
+`@intentius/chant-lexicon-forgejo`. The dialect applies on build.
+
+## Authoring
+
+```ts
+import { Workflow, Job, Step, Checkout, SetupNode } from "@intentius/chant-lexicon-forgejo";
+
+export const workflow = new Workflow({
+  name: "CI",
+  on: { push: { branches: ["main"] } },
+});
+
+export const build = new Job({
+  "runs-on": "ubuntu-latest",
+  steps: [
+    Checkout({}).step,
+    SetupNode({ nodeVersion: "22", cache: "npm" }).step,
+    new Step({ name: "Test", run: "npm test" }),
+  ],
+});
+```
+
+## Build
+
+Forgejo reads workflows from `.forgejo/workflows/` (or `.gitea/workflows/` for
+Gitea):
+
+```sh
+chant build src -o .forgejo/workflows/ci.yml
+```
+
+## What the dialect does on build
+
+- **Drops keys the Forgejo runner ignores** — `permissions` and
+  `continue-on-error` are removed (each emits a build warning).
+- **Maps runner labels** — `ubuntu-latest` → `docker` by default; override via
+  `forgejo.runnerLabels` in `chant.config.ts`. Unmapped labels warn.
+- **Resolves `uses:` refs** — common `actions/*` rewrite under
+  `forgejo.actionsRoot` (default `https://code.forgejo.org`); `docker/*` pin to
+  their GitHub URL; unmapped refs warn.
+
+## Migrating from GitHub Actions
+
+```sh
+chant migrate .github/workflows/ci.yml --to forgejo -o .forgejo/workflows/ci.yml --validate
+```
+
+`--validate` prints a **Security posture** report: what survives the move and
+what Forgejo silently drops (`permissions`/`continue-on-error` → lost,
+unresolved `uses:` / unmapped runner labels → needs-review). The same view is
+the `forgejo:compare` MCP tool.
+
+## Read-only context tools (MCP)
+
+- `forgejo:workflow` — triggers and jobs as written
+- `forgejo:references` — external actions/images and whether each is SHA-pinned
+- `forgejo:affected` — jobs that re-run downstream of a given job
+- `forgejo:checks` — Forgejo-specific findings (WFJ010/011)
+- `forgejo:source` / `forgejo:owns` — where a job came from / whether it's declared here
+- `forgejo:workflow-yaml` — the generated YAML
+- `forgejo:compare` — the github→forgejo migration safety view