@intentius/chant-lexicon-forgejo 0.4.0

package/README.md

@@ -0,0 +1,116 @@
+# @intentius/chant-lexicon-forgejo
+
+Forgejo Actions lexicon for [chant](https://intentius.io/chant) — a **thin
+dialect of the github lexicon**. Forgejo (the forge behind Codeberg,
+self-hosted Forgejo, and Gitea) runs GitHub-Actions-compatible workflows, so
+this package reuses the github lexicon's entities and composites wholesale and
+overrides only what the dialect changes.
+
+## What it does
+
+You author exactly as you would for GitHub Actions — same `Workflow`, `Job`,
+`Step`, and composites, imported from `@intentius/chant-lexicon-forgejo`:
+
+```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" }),
+  ],
+});
+```
+
+On build, the Forgejo dialect:
+
+- **Drops keys Forgejo ignores** — `permissions` and `continue-on-error` are
+  silently ignored by the Forgejo runner, so they are removed from the output
+  and reported as build warnings (emitting them is misleading).
+- **Maps runner labels** — GitHub-hosted labels like `ubuntu-latest` have no
+  fixed meaning on Forgejo. They are mapped to a default Forgejo label
+  (`docker`), overridable per project. Unmapped labels pass through with a
+  warning.
+- **Resolves `uses:` action refs** — Forgejo has no GitHub Marketplace, so a
+  bare `uses: actions/checkout@v4` is rewritten to a resolvable form. Common
+  `actions/*` are mapped under an actions root (`https://code.forgejo.org` by
+  default, overridable via `forgejo.actionsRoot`); `docker/*` are pinned to
+  their full GitHub URL. Local (`./…`), `docker://`, and full-URL refs pass
+  through untouched. Anything else passes through **and is reported** as a
+  warning so it's never silently unresolvable.
+
+Everything else is emitted by the github serializer, which already produces the
+exact YAML shape Forgejo executes.
+
+## Building
+
+Forgejo reads workflows from `.forgejo/workflows/` (and `.gitea/workflows/` for
+Gitea), so point the build output there:
+
+```sh
+chant build src -o .forgejo/workflows/ci.yml
+```
+
+## Migrating from GitHub Actions
+
+Because github → forgejo YAML is near-identical, the migration is thin — it
+applies the same dialect as a build. Its real value is the **compare**: what the
+move costs.
+
+```sh
+chant migrate .github/workflows/ci.yml --to forgejo -o .forgejo/workflows/ci.yml --validate
+```
+
+`--validate` prints a **Security posture** report classifying each property's
+fate across the edge:
+
+| Fate | Meaning |
+|---|---|
+| `translated` | carried across as-is |
+| `approximated` | carried with a close equivalent |
+| `needs-review` | confirm/adjust on Forgejo (unresolved `uses:`, unmapped runner label) |
+| `lost` | the Forgejo runner ignores it (`permissions`, `continue-on-error`) |
+
+The same view is available to agents as the `forgejo:compare` MCP tool, which
+takes a workflow file and returns per-property fates plus summary counts —
+read-only.
+
+> Note: flow-style YAML (`branches: [main]`) is parsed by chant's lightweight
+> core parser, which keeps it as a scalar; prefer block style in sources you
+> intend to migrate. This is shared with the github import path.
+
+## Configuration
+
+Override runner-label mapping in `chant.config.ts`:
+
+```ts
+import type { ChantConfig } from "@intentius/chant";
+
+export default {
+  lexicons: ["forgejo"],
+  forgejo: {
+    runnerLabels: {
+      "ubuntu-latest": "docker",
+      "ubuntu-22.04": "ubuntu-lts",
+    },
+    // Base for resolving mirrored `uses:` action refs.
+    actionsRoot: "https://code.forgejo.org",
+  },
+} satisfies ChantConfig;
+```
+
+## Notes
+
+- The serializer's lexicon `name` is `"github"` on purpose: it serializes the
+  reused github-lexicon entities (which are tagged `lexicon: "github"`). Its
+  rule prefix is `WFJ` to keep Forgejo diagnostics namespaced apart from
+  github's `GHA`.
+- No codegen: this lexicon has no spec of its own. Run `chant generate` in the
+  github lexicon if you need to refresh entities.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@intentius/chant-lexicon-forgejo",
+  "version": "0.4.0",
+  "description": "Forgejo / Codeberg / Gitea Actions lexicon for chant — a thin GitHub Actions dialect",
+  "license": "Apache-2.0",
+  "homepage": "https://intentius.io/chant",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/INTENTIUS/chant.git",
+    "directory": "lexicons/forgejo"
+  },
+  "bugs": {
+    "url": "https://github.com/INTENTIUS/chant/issues"
+  },
+  "keywords": [
+    "infrastructure-as-code",
+    "iac",
+    "typescript",
+    "forgejo",
+    "codeberg",
+    "gitea",
+    "actions",
+    "chant"
+  ],
+  "type": "module",
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "devDependencies": {
+    "@intentius/chant": "*",
+    "@intentius/chant-lexicon-github": "*",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@intentius/chant": "^0.1.0",
+    "@intentius/chant-lexicon-github": "^0.1.0"
+  }
+}

package/src/actions.test.ts

@@ -0,0 +1,82 @@
+import { describe, test, expect } from "vitest";
+import { resolveActionRef, DEFAULT_ACTIONS_ROOT } from "./actions";
+
+describe("resolveActionRef — mapped actions", () => {
+  test("rewrites actions/checkout@v4 under the default actions root", () => {
+    const { rewritten, warning } = resolveActionRef("actions/checkout@v4");
+    expect(rewritten).toBe(`${DEFAULT_ACTIONS_ROOT}/actions/checkout@v4`);
+    expect(warning).toBeUndefined();
+  });
+
+  test("rewrites the common actions/* set", () => {
+    for (const name of [
+      "actions/setup-node",
+      "actions/setup-go",
+      "actions/setup-python",
+      "actions/cache",
+      "actions/upload-artifact",
+      "actions/download-artifact",
+    ]) {
+      const { rewritten, warning } = resolveActionRef(`${name}@v4`);
+      expect(rewritten).toBe(`${DEFAULT_ACTIONS_ROOT}/${name}@v4`);
+      expect(warning).toBeUndefined();
+    }
+  });
+
+  test("pins docker/* to a full GitHub URL, independent of the actions root", () => {
+    const { rewritten, warning } = resolveActionRef("docker/build-push-action@v5", {
+      actionsRoot: "https://example.test",
+    });
+    expect(rewritten).toBe("https://github.com/docker/build-push-action@v5");
+    expect(warning).toBeUndefined();
+  });
+
+  test("preserves a subpath", () => {
+    const { rewritten } = resolveActionRef("actions/cache/restore@v4");
+    expect(rewritten).toBe(`${DEFAULT_ACTIONS_ROOT}/actions/cache/restore@v4`);
+  });
+
+  test("handles a ref with no version", () => {
+    const { rewritten } = resolveActionRef("actions/checkout");
+    expect(rewritten).toBe(`${DEFAULT_ACTIONS_ROOT}/actions/checkout`);
+  });
+});
+
+describe("resolveActionRef — actionsRoot override", () => {
+  test("override changes the base for mirrored actions", () => {
+    const { rewritten } = resolveActionRef("actions/checkout@v4", {
+      actionsRoot: "https://codeberg.org",
+    });
+    expect(rewritten).toBe("https://codeberg.org/actions/checkout@v4");
+  });
+
+  test("a trailing slash on the root is normalized", () => {
+    const { rewritten } = resolveActionRef("actions/checkout@v4", {
+      actionsRoot: "https://codeberg.org/",
+    });
+    expect(rewritten).toBe("https://codeberg.org/actions/checkout@v4");
+  });
+});
+
+describe("resolveActionRef — unmapped refs", () => {
+  test("passes an unmapped owner/repo through and reports it", () => {
+    const { rewritten, warning } = resolveActionRef("some-org/custom-action@v1");
+    expect(rewritten).toBe("some-org/custom-action@v1");
+    expect(warning).toBeDefined();
+    expect(warning).toContain("some-org/custom-action@v1");
+  });
+});
+
+describe("resolveActionRef — already-resolvable refs", () => {
+  test.each([
+    "./.forgejo/actions/local",
+    "../shared/action",
+    "docker://alpine:3.20",
+    "https://codeberg.org/actions/checkout@v4",
+    "http://example.test/x@v1",
+  ])("leaves %s untouched without warning", (ref) => {
+    const { rewritten, warning } = resolveActionRef(ref);
+    expect(rewritten).toBe(ref);
+    expect(warning).toBeUndefined();
+  });
+});

package/src/actions.ts

@@ -0,0 +1,112 @@
+/**
+ * Forgejo `uses:` action-reference resolver.
+ *
+ * GitHub Actions resolves a bare `uses: actions/checkout@v4` against the GitHub
+ * Marketplace. Forgejo / Codeberg / Gitea runners have no Marketplace, so such a
+ * ref must be rewritten to a form their runner can fetch — a full repository URL,
+ * or a path under a configured actions root that mirrors the action.
+ *
+ * The resolver rewrites a built-in set of common actions and reports anything it
+ * can't place as a diagnostic (never dropping or silently passing it through).
+ */
+
+/**
+ * Default actions root. `code.forgejo.org` hosts the Forgejo `actions/*` mirror
+ * (checkout, setup-*, cache, upload/download-artifact, …). Override per project
+ * via `forgejo.actionsRoot` in `chant.config.ts`.
+ */
+export const DEFAULT_ACTIONS_ROOT = "https://code.forgejo.org";
+
+/**
+ * Where a known action resolves:
+ *  - `mirror`: `<actionsRoot>/<repo>` — follows the configured actions root.
+ *  - `url`:    an absolute base URL — independent of the actions root (used for
+ *              actions not carried by the Forgejo mirror, e.g. `docker/*`).
+ */
+export type ActionTarget = { kind: "mirror"; repo: string } | { kind: "url"; url: string };
+
+/** Built-in mapping of GitHub action `owner/repo` → Forgejo-resolvable target. */
+export const KNOWN_ACTIONS: Record<string, ActionTarget> = {
+  // actions/* — mirrored on the Forgejo actions root.
+  "actions/checkout": { kind: "mirror", repo: "actions/checkout" },
+  "actions/setup-node": { kind: "mirror", repo: "actions/setup-node" },
+  "actions/setup-go": { kind: "mirror", repo: "actions/setup-go" },
+  "actions/setup-python": { kind: "mirror", repo: "actions/setup-python" },
+  "actions/setup-java": { kind: "mirror", repo: "actions/setup-java" },
+  "actions/setup-dotnet": { kind: "mirror", repo: "actions/setup-dotnet" },
+  "actions/cache": { kind: "mirror", repo: "actions/cache" },
+  "actions/upload-artifact": { kind: "mirror", repo: "actions/upload-artifact" },
+  "actions/download-artifact": { kind: "mirror", repo: "actions/download-artifact" },
+  // docker/* — not on the Forgejo mirror; pin to the full GitHub URL, which
+  // Forgejo runners can fetch directly.
+  "docker/build-push-action": { kind: "url", url: "https://github.com/docker/build-push-action" },
+  "docker/login-action": { kind: "url", url: "https://github.com/docker/login-action" },
+  "docker/setup-buildx-action": { kind: "url", url: "https://github.com/docker/setup-buildx-action" },
+  "docker/setup-qemu-action": { kind: "url", url: "https://github.com/docker/setup-qemu-action" },
+  "docker/metadata-action": { kind: "url", url: "https://github.com/docker/metadata-action" },
+};
+
+export interface ActionResolveOptions {
+  /** Base for `mirror` targets; defaults to {@link DEFAULT_ACTIONS_ROOT}. */
+  actionsRoot?: string;
+  /** Mapping table to use; defaults to {@link KNOWN_ACTIONS}. */
+  known?: Record<string, ActionTarget>;
+}
+
+export interface ActionResolveResult {
+  /** The rewritten (or unchanged) `uses:` ref. */
+  rewritten: string;
+  /** Set when the ref could not be resolved — surfaced as a build warning. */
+  warning?: string;
+}
+
+/** A ref that already resolves on Forgejo as-is needs no rewrite and no warning. */
+function isAlreadyResolvable(ref: string): boolean {
+  return (
+    ref.startsWith("./") ||
+    ref.startsWith("../") ||
+    ref.startsWith(".\\") ||
+    ref.startsWith("docker://") ||
+    /^https?:\/\//.test(ref)
+  );
+}
+
+/**
+ * Resolve a single `uses:` action ref to a Forgejo-resolvable form.
+ */
+export function resolveActionRef(ref: string, options: ActionResolveOptions = {}): ActionResolveResult {
+  const trimmed = ref.trim();
+  if (trimmed === "" || isAlreadyResolvable(trimmed)) return { rewritten: ref };
+
+  const root = (options.actionsRoot ?? DEFAULT_ACTIONS_ROOT).replace(/\/+$/, "");
+  const known = options.known ?? KNOWN_ACTIONS;
+
+  const atIndex = trimmed.lastIndexOf("@");
+  const path = atIndex >= 0 ? trimmed.slice(0, atIndex) : trimmed;
+  const version = atIndex >= 0 ? trimmed.slice(atIndex + 1) : "";
+
+  const segments = path.split("/");
+  if (segments.length < 2) {
+    return { rewritten: ref, warning: unresolvedWarning(trimmed) };
+  }
+
+  const actionName = `${segments[0]}/${segments[1]}`;
+  const subpath = segments.slice(2).join("/");
+  const target = known[actionName];
+  if (!target) {
+    return { rewritten: ref, warning: unresolvedWarning(trimmed) };
+  }
+
+  const base = target.kind === "mirror" ? `${root}/${target.repo}` : target.url;
+  const withSubpath = subpath ? `${base}/${subpath}` : base;
+  const rewritten = version ? `${withSubpath}@${version}` : withSubpath;
+  return { rewritten };
+}
+
+function unresolvedWarning(ref: string): string {
+  return (
+    `forgejo: unresolved action ref '${ref}' — it has no built-in mapping and won't ` +
+    `resolve from a GitHub Marketplace on Forgejo. Use a full repository URL, or mirror ` +
+    `it under forgejo.actionsRoot in chant.config.ts.`
+  );
+}

package/src/dialect.test.ts

@@ -0,0 +1,104 @@
+import { describe, test, expect } from "vitest";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { applyForgejoDialect, DEFAULT_RUNNER_LABELS } from "./dialect";
+
+// ── Mock entities (github-tagged, as the dialect reuses github entities) ──
+
+class MockJob implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "github";
+  readonly entityType = "GitHub::Actions::Job";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+class MockWorkflow implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "github";
+  readonly entityType = "GitHub::Actions::Workflow";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+function entityMap(...pairs: Array<[string, Declarable]>): Map<string, Declarable> {
+  return new Map(pairs);
+}
+
+describe("applyForgejoDialect — dropped keys", () => {
+  test("drops workflow-level permissions and warns", () => {
+    const wf = new MockWorkflow({ name: "CI", permissions: { contents: "read" } });
+    const { entities, warnings } = applyForgejoDialect(entityMap(["workflow", wf]));
+    const props = (entities.get("workflow") as MockWorkflow).props;
+    expect(props.permissions).toBeUndefined();
+    expect(props.name).toBe("CI");
+    expect(warnings.filter((w) => w.includes("permissions"))).toHaveLength(1);
+  });
+
+  test("drops job and step continue-on-error, one warning each", () => {
+    const job = new MockJob({
+      "runs-on": "ubuntu-latest",
+      "continue-on-error": true,
+      steps: [
+        { name: "a", run: "echo a", "continue-on-error": true },
+        { name: "b", run: "echo b" },
+      ],
+    });
+    const { entities, warnings } = applyForgejoDialect(entityMap(["build", job]));
+    const props = (entities.get("build") as MockJob).props;
+    expect(props["continue-on-error"]).toBeUndefined();
+    const steps = props.steps as Array<Record<string, unknown>>;
+    expect(steps[0]["continue-on-error"]).toBeUndefined();
+    expect(steps[0].name).toBe("a");
+    expect(warnings.filter((w) => w.includes("continue-on-error"))).toHaveLength(2);
+  });
+
+  test("also catches the camelCase spelling (continueOnError)", () => {
+    const job = new MockJob({ continueOnError: true, "runs-on": "ubuntu-latest" });
+    const { entities, warnings } = applyForgejoDialect(entityMap(["build", job]));
+    const props = (entities.get("build") as MockJob).props;
+    expect(props.continueOnError).toBeUndefined();
+    expect(warnings.filter((w) => w.includes("continue-on-error"))).toHaveLength(1);
+  });
+
+  test("does not mutate the original entity", () => {
+    const wf = new MockWorkflow({ name: "CI", permissions: { contents: "read" } });
+    applyForgejoDialect(entityMap(["workflow", wf]));
+    expect(wf.props.permissions).toEqual({ contents: "read" });
+  });
+});
+
+describe("applyForgejoDialect — runner labels", () => {
+  test("maps ubuntu-latest to the default Forgejo label", () => {
+    const job = new MockJob({ "runs-on": "ubuntu-latest" });
+    const { entities, warnings } = applyForgejoDialect(entityMap(["build", job]));
+    expect((entities.get("build") as MockJob).props["runs-on"]).toBe(DEFAULT_RUNNER_LABELS["ubuntu-latest"]);
+    expect(warnings).toHaveLength(0);
+  });
+
+  test("a project override changes the emitted label", () => {
+    const job = new MockJob({ "runs-on": "ubuntu-latest" });
+    const { entities } = applyForgejoDialect(entityMap(["build", job]), {
+      runnerLabels: { "ubuntu-latest": "big-runner" },
+    });
+    expect((entities.get("build") as MockJob).props["runs-on"]).toBe("big-runner");
+  });
+
+  test("an unmapped label passes through unchanged (reported by WFJ011, not here)", () => {
+    const job = new MockJob({ "runs-on": "macos-latest" });
+    const { entities, warnings } = applyForgejoDialect(entityMap(["build", job]));
+    expect((entities.get("build") as MockJob).props["runs-on"]).toBe("macos-latest");
+    expect(warnings.filter((w) => w.includes("macos-latest"))).toHaveLength(0);
+  });
+
+  test("remaps every label in an array form, leaving unmapped ones untouched", () => {
+    const job = new MockJob({ "runs-on": ["ubuntu-latest", "self-hosted"] });
+    const { entities } = applyForgejoDialect(entityMap(["build", job]));
+    expect((entities.get("build") as MockJob).props["runs-on"]).toEqual(["docker", "self-hosted"]);
+  });
+});

package/src/dialect.ts

@@ -0,0 +1,189 @@
+/**
+ * Forgejo dialect transform.
+ *
+ * Forgejo Actions (the engine behind Codeberg, self-hosted Forgejo, and Gitea)
+ * runs GitHub-Actions-compatible YAML, so the github lexicon's serializer emits
+ * the right shape. The dialect differs in three small ways, all handled here as
+ * a pre-pass over the resolved entity graph before the github serializer runs:
+ *
+ *  1. `permissions` and `continue-on-error` are silently ignored by the Forgejo
+ *     runner — we drop them from the output and warn per occurrence.
+ *  2. GitHub-hosted runner labels (`ubuntu-latest`, …) have no fixed meaning on
+ *     Forgejo — we map them to a default Forgejo label, overridable per project.
+ *  3. Anything we can't place (an unmapped runner label) passes through with a
+ *     warning rather than being dropped.
+ *
+ * Operating on the entity graph (rather than string-munging YAML) keeps the
+ * transform faithful: the github serializer still does the actual emission.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { resolveActionRef } from "./actions";
+
+/**
+ * Keys the Forgejo runner ignores. Emitting them is misleading (they look
+ * enforced but aren't), so the dialect drops them. Compared in kebab-case so
+ * both `continueOnError` and `continue-on-error` spellings are caught.
+ */
+const DROPPED_KEYS = new Set(["permissions", "continue-on-error"]);
+
+/** Property key whose value is a runner-label selector. */
+const RUNS_ON_KEY = "runs-on";
+
+/** Property key whose value is an action/workflow reference. */
+const USES_KEY = "uses";
+
+/**
+ * Default GitHub-hosted runner label → Forgejo label mapping. `docker` is the
+ * label a freshly-registered Forgejo `act_runner` exposes, and the one used
+ * throughout the Forgejo Actions docs, so it is the safest default target.
+ * Override per project via `forgejo.runnerLabels` in `chant.config.ts`.
+ */
+export const DEFAULT_RUNNER_LABELS: Record<string, string> = {
+  "ubuntu-latest": "docker",
+  "ubuntu-24.04": "docker",
+  "ubuntu-22.04": "docker",
+  "ubuntu-20.04": "docker",
+};
+
+export interface ForgejoDialectOptions {
+  /** Project-supplied label overrides, merged over {@link DEFAULT_RUNNER_LABELS}. */
+  runnerLabels?: Record<string, string>;
+  /** Base for resolving mirrored `uses:` action refs (see ./actions). */
+  actionsRoot?: string;
+}
+
+export interface ForgejoDialectResult {
+  /** The transformed entity map (clones; originals are not mutated). */
+  entities: Map<string, Declarable>;
+  /** One warning per dropped key and per unmapped runner label. */
+  warnings: string[];
+}
+
+/** Convert a camelCase or kebab-case key to a canonical kebab-case form. */
+function toKebabCase(name: string): string {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+function isDeclarable(value: unknown): value is Declarable {
+  return typeof value === "object" && value !== null && DECLARABLE_MARKER in value;
+}
+
+interface TransformCtx {
+  labels: Record<string, string>;
+  actionsRoot?: string;
+  warnings: string[];
+  /** Human-readable location used in warning messages. */
+  where: string;
+}
+
+/**
+ * Map a single runner label, passing it through unchanged when unmapped. An
+ * unmapped label that survives into the output is reported by the WFJ011
+ * post-synth check (which surfaces in both `chant build` and `chant lint`),
+ * so the dialect doesn't also warn here — that would double-report.
+ */
+function mapLabel(label: string, ctx: TransformCtx): string {
+  return ctx.labels[label] ?? label;
+}
+
+/** Remap a `runs-on` value (string or string[]); leave other shapes untouched. */
+function remapRunsOn(value: unknown, ctx: TransformCtx): unknown {
+  if (typeof value === "string") return mapLabel(value, ctx);
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+    return (value as string[]).map((v) => mapLabel(v, ctx));
+  }
+  return value;
+}
+
+function transformValue(value: unknown, ctx: TransformCtx): unknown {
+  if (value === null || typeof value !== "object") return value;
+
+  if (isDeclarable(value)) return cloneDeclarable(value, ctx);
+
+  if (Array.isArray(value)) return value.map((v) => transformValue(v, ctx));
+
+  // Plain object: drop ignored keys, remap runs-on, recurse into the rest.
+  const result: Record<string, unknown> = {};
+  for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+    const kebab = toKebabCase(key);
+    if (DROPPED_KEYS.has(kebab)) {
+      ctx.warnings.push(
+        `forgejo: dropped '${kebab}' in ${ctx.where} — the Forgejo runner ignores it. ` +
+          `Re-establish this control through your Forgejo/runner configuration.`,
+      );
+      continue;
+    }
+    if (kebab === RUNS_ON_KEY) {
+      result[key] = remapRunsOn(v, ctx);
+      continue;
+    }
+    if (kebab === USES_KEY && typeof v === "string") {
+      // Rewrite to a Forgejo-resolvable form. An unresolved ref that survives
+      // is reported by the WFJ010 post-synth check (build + lint), so the
+      // dialect doesn't also warn here — that would double-report.
+      result[key] = resolveActionRef(v, { actionsRoot: ctx.actionsRoot }).rewritten;
+      continue;
+    }
+    result[key] = transformValue(v, ctx);
+  }
+  return result;
+}
+
+/** Shallow-clone a Declarable, replacing its `props` with a transformed copy. */
+function cloneDeclarable(entity: Declarable, ctx: TransformCtx): Declarable {
+  const descriptors = Object.getOwnPropertyDescriptors(entity);
+  const clone = Object.create(Object.getPrototypeOf(entity), descriptors) as Declarable;
+  const rawProps = (entity as unknown as { props?: unknown }).props;
+  const newProps = transformValue(rawProps, ctx);
+  Object.defineProperty(clone, "props", {
+    value: newProps,
+    enumerable: descriptors.props?.enumerable ?? false,
+    configurable: true,
+    writable: descriptors.props?.writable ?? true,
+  });
+  return clone;
+}
+
+export interface TransformObjectResult {
+  /** The transformed plain value (clone; the input is not mutated). */
+  value: unknown;
+  /** One warning per dropped key, unmapped label, and unresolved action ref. */
+  warnings: string[];
+}
+
+/**
+ * Apply the Forgejo dialect to a plain object — e.g. a parsed GitHub Actions
+ * workflow during migration, rather than the resolved entity graph. Same
+ * rules as {@link applyForgejoDialect}: drop ignored keys, remap runner
+ * labels, resolve `uses:` refs.
+ */
+export function transformWorkflowObject(
+  obj: unknown,
+  options: ForgejoDialectOptions = {},
+): TransformObjectResult {
+  const labels = { ...DEFAULT_RUNNER_LABELS, ...(options.runnerLabels ?? {}) };
+  const warnings: string[] = [];
+  const ctx: TransformCtx = { labels, actionsRoot: options.actionsRoot, warnings, where: "workflow" };
+  return { value: transformValue(obj, ctx), warnings };
+}
+
+/**
+ * Apply the Forgejo dialect to a resolved entity map. Returns transformed
+ * clones plus the diagnostics produced (dropped keys, unmapped labels).
+ */
+export function applyForgejoDialect(
+  entities: Map<string, Declarable>,
+  options: ForgejoDialectOptions = {},
+): ForgejoDialectResult {
+  const labels = { ...DEFAULT_RUNNER_LABELS, ...(options.runnerLabels ?? {}) };
+  const warnings: string[] = [];
+  const out = new Map<string, Declarable>();
+
+  for (const [name, entity] of entities) {
+    const ctx: TransformCtx = { labels, actionsRoot: options.actionsRoot, warnings, where: name };
+    out.set(name, cloneDeclarable(entity, ctx));
+  }
+
+  return { entities: out, warnings };
+}