@intentius/chant-lexicon-forgejo 0.4.0

package/src/index.ts

@@ -0,0 +1,50 @@
+// Forgejo Actions lexicon — a thin dialect of the github lexicon.
+//
+// Serializer + plugin override only the dialect; everything a user writes
+// (entities, expression helpers, context variables, composites) is reused
+// directly from the github lexicon and re-exported here so a forgejo project
+// imports solely from "@intentius/chant-lexicon-forgejo".
+
+// Serializer
+export { forgejoSerializer } from "./serializer";
+
+// Plugin
+export { forgejoPlugin } from "./plugin";
+
+// Dialect (exposed for tooling/tests)
+export {
+  applyForgejoDialect,
+  transformWorkflowObject,
+  DEFAULT_RUNNER_LABELS,
+  type ForgejoDialectOptions,
+  type ForgejoDialectResult,
+  type TransformObjectResult,
+} from "./dialect";
+
+// github → forgejo migration
+export {
+  transform,
+  detectGitHubWorkflow,
+  type MigrateOptions,
+  type MigrationResult,
+} from "./migrate/from-github";
+export {
+  analyzeForgejoSecurity,
+  renderSecurityPosture,
+  type SecurityFate,
+  type SecurityRecord,
+} from "./migrate/from-github/security";
+
+// Action-reference resolver (exposed for tooling/tests)
+export {
+  resolveActionRef,
+  DEFAULT_ACTIONS_ROOT,
+  KNOWN_ACTIONS,
+  type ActionTarget,
+  type ActionResolveOptions,
+  type ActionResolveResult,
+} from "./actions";
+
+// Reuse the entire github authoring surface: generated entities, expression
+// system, context variables, and composites.
+export * from "@intentius/chant-lexicon-github";

package/src/lint/post-synth/wfj.test.ts

@@ -0,0 +1,80 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wfj010 } from "./wfj010";
+import { wfj011 } from "./wfj011";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["github", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["github", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WFJ010: unresolved action reference", () => {
+  test("flags a bare owner/repo ref", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: docker
+    steps:
+      - uses: some-org/custom-action@v1
+`;
+    const diags = wfj010.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WFJ010");
+    expect(diags[0].message).toContain("some-org/custom-action@v1");
+  });
+
+  test("does not flag a resolved full-URL ref", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: docker
+    steps:
+      - uses: https://code.forgejo.org/actions/checkout@v4
+`;
+    expect(wfj010.check(makeCtx(yaml))).toHaveLength(0);
+  });
+});
+
+describe("WFJ011: GitHub-hosted runner label", () => {
+  test("flags a macos-latest label", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: macos-latest
+    steps:
+      - run: echo hi
+`;
+    const diags = wfj011.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WFJ011");
+    expect(diags[0].message).toContain("macos-latest");
+  });
+
+  test("does not flag a mapped Forgejo label", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: docker
+    steps:
+      - run: echo hi
+`;
+    expect(wfj011.check(makeCtx(yaml))).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/wfj010.ts

@@ -0,0 +1,38 @@
+/**
+ * WFJ010: Unresolved action reference.
+ *
+ * After the forgejo dialect runs, every `uses:` should be a Forgejo-resolvable
+ * form (a full URL, a local `./` action, or `docker://`). A bare `owner/repo@ref`
+ * that survives into the output won't resolve — Forgejo has no GitHub
+ * Marketplace. Flags it so it's caught in `chant lint` / `forgejo:checks`, not
+ * only as a build-time warning.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { extractActionRefs } from "@intentius/chant-lexicon-github/lint/post-synth/yaml-helpers";
+import { resolveActionRef } from "../../actions";
+
+export const wfj010: PostSynthCheck = {
+  id: "WFJ010",
+  description: "Unresolved action reference (won't resolve on Forgejo)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const ref of extractActionRefs(yaml)) {
+        if (resolveActionRef(ref.ref).warning) {
+          diagnostics.push({
+            checkId: "WFJ010",
+            severity: "warning",
+            message: `Job "${ref.job}" references '${ref.ref}', which has no Forgejo-resolvable form. Use a full repository URL or map it under forgejo.actionsRoot.`,
+            entity: ref.job,
+            lexicon: "forgejo",
+          });
+        }
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/wfj011.ts

@@ -0,0 +1,41 @@
+/**
+ * WFJ011: GitHub-hosted runner label.
+ *
+ * `runs-on` labels like `macos-latest` / `windows-latest` name GitHub-hosted
+ * runners that don't exist on Forgejo, and `ubuntu-*` labels that the dialect
+ * didn't map (e.g. when mapping is overridden away) won't be advertised by a
+ * default Forgejo runner. Flags any such label that survives into the output.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { extractRunsOnByJob } from "@intentius/chant-lexicon-github/lint/post-synth/yaml-helpers";
+
+/** Labels that name a GitHub-hosted runner image (no fixed Forgejo equivalent). */
+const GITHUB_HOSTED = /^(ubuntu|macos|windows)-/;
+
+export const wfj011: PostSynthCheck = {
+  id: "WFJ011",
+  description: "GitHub-hosted runner label with no Forgejo equivalent",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const [job, labels] of extractRunsOnByJob(yaml)) {
+        for (const label of labels) {
+          if (GITHUB_HOSTED.test(label)) {
+            diagnostics.push({
+              checkId: "WFJ011",
+              severity: "warning",
+              message: `Job "${job}" runs on '${label}', a GitHub-hosted runner label with no Forgejo equivalent. Map it via forgejo.runnerLabels or target a label your Forgejo runners advertise.`,
+              entity: job,
+              lexicon: "forgejo",
+            });
+          }
+        }
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/mcp/context-tools.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Smoke tests for the forgejo read-only context tools. Each builds a small
+ * temp project from source and exercises the tool handler directly.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { forgejoContextTools } from "./context-tools";
+
+const SOURCE = `import { Workflow, Job, Step, Checkout } 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,
+    new Step({ name: "Custom", uses: "some-org/custom-action@v1" }),
+    new Step({ name: "Test", run: "npm test" }),
+  ],
+});
+
+export const deploy = new Job({
+  "runs-on": "ubuntu-latest",
+  needs: ["build"],
+  steps: [new Step({ name: "Deploy", run: "./deploy.sh" })],
+});
+`;
+
+let dir: string;
+const tools = forgejoContextTools();
+const tool = (name: string) => tools.find((t) => t.name === name)!;
+
+beforeAll(() => {
+  dir = mkdtempSync(join(tmpdir(), "fj-ctx-"));
+  mkdirSync(join(dir, "src"));
+  writeFileSync(join(dir, "src", "pipeline.ts"), SOURCE);
+});
+
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("forgejo context tools", () => {
+  test("all expected tools are registered", () => {
+    expect(tools.map((t) => t.name)).toEqual([
+      "forgejo:checks",
+      "forgejo:workflow",
+      "forgejo:references",
+      "forgejo:affected",
+      "forgejo:workflow-yaml",
+      "forgejo:source",
+      "forgejo:owns",
+      "forgejo:compare",
+    ]);
+  });
+
+  test("forgejo:workflow returns triggers and jobs", async () => {
+    const result = (await tool("forgejo:workflow").handler({ path: join(dir, "src") })) as {
+      workflow: string;
+      triggers: string[];
+      jobs: Array<{ name: string; runsAfter: string[] }>;
+    };
+    expect(result.workflow).toBe("CI");
+    expect(result.triggers).toContain("push");
+    expect(result.jobs.map((j) => j.name).sort()).toEqual(["build", "deploy"]);
+  });
+
+  test("forgejo:references reports the rewritten + unmapped refs", async () => {
+    const refs = (await tool("forgejo:references").handler({ path: join(dir, "src") })) as Array<{ source: string }>;
+    const sources = refs.map((r) => r.source);
+    expect(sources).toContain("https://code.forgejo.org/actions/checkout@v4");
+    expect(sources).toContain("some-org/custom-action@v1");
+  });
+
+  test("forgejo:checks surfaces the unresolved ref (WFJ010)", async () => {
+    const result = (await tool("forgejo:checks").handler({ path: join(dir, "src") })) as {
+      findings: Array<{ id: string }>;
+    };
+    expect(result.findings.some((f) => f.id === "WFJ010")).toBe(true);
+  });
+
+  test("forgejo:affected traces the needs chain", async () => {
+    const result = (await tool("forgejo:affected").handler({ path: join(dir, "src"), job: "build" })) as {
+      wouldRerun: string[];
+    };
+    expect(result.wouldRerun).toContain("deploy");
+  });
+
+  test("forgejo:owns reports a declared job as owned", async () => {
+    const result = (await tool("forgejo:owns").handler({ path: join(dir, "src"), job: "build" })) as { owned: boolean };
+    expect(result.owned).toBe(true);
+  });
+});

package/src/mcp/context-tools.ts

@@ -0,0 +1,263 @@
+/**
+ * Read-only MCP tools for the forgejo lexicon.
+ *
+ * The forgejo counterpart to the github/gitlab context tools (#327): expose
+ * what `chant build` already computes about a Forgejo workflow — its triggers
+ * and jobs, what it pulls in from outside, its findings, where each job came
+ * from in source — plus `forgejo:compare`, the migration safety view. Because
+ * Forgejo emits GitHub-style YAML, the parsing reuses the github lexicon's
+ * yaml-helpers.
+ *
+ * Every tool builds from source and returns data. None touch a live forge,
+ * read run history, or write anything.
+ */
+
+import { build, type BuildResult } from "@intentius/chant/build";
+import { runPostSynthChecks, getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { discoverPostSynthChecks } from "@intentius/chant/lint/discover";
+import { getProvenance } from "@intentius/chant/provenance";
+import type { McpToolContribution } from "@intentius/chant/mcp/types";
+import { dirname, join, relative, isAbsolute, resolve } from "path";
+import { readFile } from "fs/promises";
+import { fileURLToPath } from "url";
+import {
+  extractJobs,
+  extractActionRefs,
+  extractImageRefs,
+  extractTriggers,
+  extractWorkflowName,
+} from "@intentius/chant-lexicon-github/lint/post-synth/yaml-helpers";
+import { forgejoSerializer } from "../serializer";
+import { transform, detectGitHubWorkflow } from "../migrate/from-github";
+
+/**
+ * Build the project with the forgejo serializer and return the emitted YAML.
+ * The serializer is registered under the "github" lexicon (it serializes the
+ * reused github entities), so the output is keyed "github".
+ */
+async function buildForgejo(path: string): Promise<{ yaml: string; result: BuildResult }> {
+  const result = await build(path, [forgejoSerializer]);
+  const out = result.outputs.get("github");
+  return { yaml: out ? getPrimaryOutput(out) : "", result };
+}
+
+/** Discover the forgejo post-synth checks without depending on the plugin. */
+function forgejoPostSynthChecks() {
+  const dir = join(dirname(fileURLToPath(import.meta.url)), "..", "lint", "post-synth");
+  return discoverPostSynthChecks(dir, import.meta.url);
+}
+
+/** Is a `uses:` ref pinned to a full commit SHA (the only immutable form)? */
+export function actionPinned(ref: string): boolean {
+  const at = ref.lastIndexOf("@");
+  return at !== -1 && /^[0-9a-f]{40}$/.test(ref.slice(at + 1));
+}
+
+/** The YAML job name a build entity serializes to (camelCase → kebab-case). */
+export function jobNameOf(entityName: string): string {
+  return entityName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/** Find the build entity whose serialized job name matches `job`. */
+function entityForJob(result: BuildResult, job: string): { name: string; entity: object } | undefined {
+  for (const [name, entity] of result.entities) {
+    if (name === job || jobNameOf(name) === job) return { name, entity };
+  }
+  return undefined;
+}
+
+/** Render a source-file path relative to the project root, when possible. */
+function relSource(root: string, file: string | undefined): string | undefined {
+  if (!file) return undefined;
+  if (!isAbsolute(file)) return file;
+  const rel = relative(root, file);
+  return rel.startsWith("..") ? file : rel;
+}
+
+/** Jobs that would re-run because they depend (transitively) on `job`. */
+export function downstreamJobs(yaml: string, job: string): string[] {
+  const jobs = extractJobs(yaml);
+  const downstreamOf = new Map<string, string[]>();
+  for (const [name, j] of jobs) {
+    for (const dep of j.needs ?? []) {
+      const arr = downstreamOf.get(dep) ?? [];
+      arr.push(name);
+      downstreamOf.set(dep, arr);
+    }
+  }
+  const out = new Set<string>();
+  const queue = [job];
+  while (queue.length) {
+    const cur = queue.shift()!;
+    for (const next of downstreamOf.get(cur) ?? []) {
+      if (!out.has(next)) {
+        out.add(next);
+        queue.push(next);
+      }
+    }
+  }
+  return [...out];
+}
+
+const PATH_INPUT = {
+  type: "object" as const,
+  properties: {
+    path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+  },
+};
+
+const JOB_INPUT = {
+  type: "object" as const,
+  properties: {
+    path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+    job: { type: "string", description: "Job name (as it appears in the generated YAML)" },
+  },
+  required: ["job"],
+};
+
+/** The read-only context tools for the forgejo lexicon. */
+export function forgejoContextTools(): McpToolContribution[] {
+  return [
+    {
+      name: "forgejo:checks",
+      description:
+        "Build the workflow and return its Forgejo-specific findings (the WFJ checks: unresolved action refs, GitHub-hosted runner labels) as JSON. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml, result } = await buildForgejo((params.path as string) ?? ".");
+        if (!yaml) return { findings: [], note: "no Forgejo workflow produced from this project" };
+        const scoped = { ...result, outputs: new Map([["github", result.outputs.get("github")!]]) };
+        const diags = runPostSynthChecks(forgejoPostSynthChecks(), scoped);
+        return {
+          findings: diags.map((d) => ({ id: d.checkId, severity: d.severity, job: d.entity ?? null, message: d.message })),
+        };
+      },
+    },
+    {
+      name: "forgejo:workflow",
+      description:
+        "Build the workflow and return its triggers and jobs as written (name, what each job runs after, step count) — before anything runs. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildForgejo((params.path as string) ?? ".");
+        const jobs = [...extractJobs(yaml).values()].map((j) => ({
+          name: j.name,
+          runsAfter: j.needs ?? [],
+          steps: j.steps?.length ?? 0,
+        }));
+        return { workflow: extractWorkflowName(yaml) ?? null, triggers: Object.keys(extractTriggers(yaml)), jobs };
+      },
+    },
+    {
+      name: "forgejo:references",
+      description:
+        "Build the workflow and list everything it pulls in from outside (actions via uses:, container/service images) and whether each is pinned to an immutable commit SHA. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildForgejo((params.path as string) ?? ".");
+        const actions = extractActionRefs(yaml).map((a) => ({
+          kind: a.level === "job" ? ("reusable-workflow" as const) : ("action" as const),
+          job: a.job,
+          source: a.ref,
+          pinned: actionPinned(a.ref),
+        }));
+        const images = extractImageRefs(yaml).map((i) => ({
+          kind: "image" as const,
+          job: i.job,
+          source: i.image,
+          pinned: i.image.includes("@sha256:"),
+        }));
+        return [...actions, ...images];
+      },
+    },
+    {
+      name: "forgejo:affected",
+      description:
+        "Build the workflow and, given a job name, list the jobs that would re-run because they depend on it (the needs chain). Read-only.",
+      inputSchema: JOB_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildForgejo((params.path as string) ?? ".");
+        const job = params.job as string;
+        return { job, wouldRerun: downstreamJobs(yaml, job) };
+      },
+    },
+    {
+      name: "forgejo:workflow-yaml",
+      description: "Build the project and return the generated Forgejo Actions workflow YAML as a string. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildForgejo((params.path as string) ?? ".");
+        return { yaml };
+      },
+    },
+    {
+      name: "forgejo:source",
+      description:
+        "Build the project and, given a job name, say where it came from in the TypeScript source — the file that declared it and the composite that expanded it, if any. Entity-level provenance, not a YAML-line source map. Read-only.",
+      inputSchema: JOB_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const root = (params.path as string) ?? ".";
+        const { result } = await buildForgejo(root);
+        const job = params.job as string;
+        const found = entityForJob(result, job);
+        if (!found) return { job, found: false, note: "no build entity serializes to that job name" };
+        const prov = getProvenance(found.entity);
+        return { job, found: true, entity: found.name, from: relSource(root, prov?.sourceFile) ?? null, via: prov?.composite ?? null };
+      },
+    },
+    {
+      name: "forgejo:owns",
+      description:
+        "Build the project and report whether a job is declared (owned) by chant in this project's source. For workflow config, ownership means \"declared here\" — Forgejo Actions jobs are not taggable cloud resources, so there is no live ownership marker as there is for cloud lexicons. Read-only.",
+      inputSchema: JOB_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const root = (params.path as string) ?? ".";
+        const { result } = await buildForgejo(root);
+        const job = params.job as string;
+        const found = entityForJob(result, job);
+        return {
+          job,
+          owned: Boolean(found),
+          basis: "declared-in-source",
+          note: "Forgejo Actions jobs are not taggable cloud resources; ownership here means the job is declared by chant in this project. Live ownership markers apply to cloud lexicons (aws/azure/k8s).",
+        };
+      },
+    },
+    {
+      name: "forgejo:compare",
+      description:
+        "Given a GitHub Actions workflow file, migrate it to Forgejo and report which properties survive the move and which weaken or are lost (the migration safety view). Returns a per-property fate (translated/approximated/needs-review/lost) plus summary counts. Read-only — analyzes, never writes.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          file: { type: "string", description: "Path to a .github/workflows/*.yml workflow file to migrate and compare" },
+        },
+        required: ["file"],
+      },
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const file = resolve((params.file as string) ?? "");
+        let content: string;
+        try {
+          content = await readFile(file, "utf8");
+        } catch {
+          return { file: params.file ?? null, found: false, note: "could not read the workflow file" };
+        }
+        if (!detectGitHubWorkflow(content)) {
+          return { file: params.file ?? null, found: false, note: "file does not look like a GitHub Actions workflow" };
+        }
+        const migration = await transform(content, { security: true, sourceFile: file });
+        const properties = migration.provenance.map((r) => ({
+          property: r.security.property,
+          fate: r.security.fate,
+          severity: r.security.severity,
+          sourceKey: r.sourceKey,
+          reestablish: r.security.reestablish ?? null,
+          note: r.note ?? null,
+        }));
+        const summary: Record<string, number> = { translated: 0, approximated: 0, "needs-review": 0, lost: 0 };
+        for (const p of properties) summary[p.fate] = (summary[p.fate] ?? 0) + 1;
+        return { found: true, properties, summary };
+      },
+    },
+  ];
+}

package/src/migrate/from-github/index.ts

@@ -0,0 +1,103 @@
+/**
+ * github → forgejo migration entry point.
+ *
+ * Thin by design: Forgejo Actions YAML *is* GitHub Actions YAML, so the
+ * migration applies the same dialect as a `chant build` (drop ignored keys,
+ * resolve `uses:` refs, map runner labels) and emits the result. No stage
+ * inference, job→script rewrite, or `!reference` intrinsic like the gitlab
+ * migration needs. The differentiated value is the security-fate **compare**
+ * (see ./security).
+ */
+
+import type { LintDiagnostic } from "@intentius/chant/lint/rule";
+import { parseYAML, emitYAML } from "@intentius/chant/yaml";
+import { transformWorkflowObject } from "../../dialect";
+import {
+  analyzeForgejoSecurity,
+  provenanceToDiagnostics,
+  renderSecurityPosture,
+  type SecurityRecord,
+} from "./security";
+
+export interface MigrateOptions {
+  /** Output format. Defaults to "yaml". */
+  emit?: "yaml" | "ts";
+  /** Source file path (display only). */
+  sourceFile?: string;
+  /** Escalate needs-review/lost findings to errors. */
+  strict?: boolean;
+  /** Accepted for parity with the core MigrationSource contract; forgejo
+   *  always runs the (cheap) security analysis. */
+  security?: boolean;
+  /** Accepted for parity; forgejo has no composite rewriter. */
+  useComposites?: boolean;
+}
+
+export interface MigrationResult {
+  /** Rendered output (forgejo YAML by default, chant TS when emit: "ts"). */
+  output: string;
+  /** Per-property security-fate records. */
+  provenance: SecurityRecord[];
+  /** SARIF-shaped diagnostics derived from the records. */
+  diagnostics: LintDiagnostic[];
+  /** Markdown "Security posture" section. */
+  securityPosture: string;
+}
+
+/** Emit a parsed/transformed workflow object back to YAML. */
+function emitForgejoYaml(value: unknown): string {
+  const body = emitYAML(value, 0);
+  return (body.startsWith("\n") ? body.slice(1) : body) + "\n";
+}
+
+/** Emit a chant TypeScript pipeline (authored github-style, imported from forgejo). */
+async function emitTs(content: string, opts: MigrateOptions): Promise<string> {
+  const { GitHubActionsParser } = await import("@intentius/chant-lexicon-github/import/parser");
+  const { GitHubActionsGenerator } = await import("@intentius/chant-lexicon-github/import/generator");
+  const ir = new GitHubActionsParser().parse(content);
+  const files = new GitHubActionsGenerator().generate(ir);
+  const banner =
+    `// Migrated from ${opts.sourceFile ?? "(stdin)"} by chant migrate (github → forgejo).\n` +
+    `// Authored github-style; the forgejo lexicon applies its dialect on build.\n\n`;
+  return (
+    banner +
+    files
+      .map((f) => f.content.replace(/@intentius\/chant-lexicon-github/g, "@intentius/chant-lexicon-forgejo"))
+      .join("\n")
+  );
+}
+
+/**
+ * Migrate a GitHub Actions workflow into a Forgejo workflow.
+ *
+ * @param content raw .github/workflows/*.yml content
+ * @param opts    migration options
+ */
+export async function transform(content: string, opts: MigrateOptions = {}): Promise<MigrationResult> {
+  const source = parseYAML(content);
+
+  let output: string;
+  if (opts.emit === "ts") {
+    output = await emitTs(content, opts);
+  } else {
+    const { value } = transformWorkflowObject(source);
+    output = emitForgejoYaml(value);
+  }
+
+  // The compare is computed against the *source* — that's where the dropped
+  // keys still exist — so it reports what the move costs.
+  const provenance = analyzeForgejoSecurity(source, { sourceFile: opts.sourceFile });
+  const diagnostics = provenanceToDiagnostics(provenance, { strict: opts.strict });
+  const securityPosture = renderSecurityPosture(provenance);
+
+  return { output, provenance, diagnostics, securityPosture };
+}
+
+/**
+ * Lightweight detector: does this content look like a GitHub Actions workflow?
+ * Used by the plugin's `migrationSource("github")`.
+ */
+export function detectGitHubWorkflow(content: string): boolean {
+  if (!/^\s*jobs\s*:/m.test(content)) return false;
+  return /^\s*on\s*:/m.test(content) || /^\s*runs-on\s*:/m.test(content);
+}