@intentius/chant-lexicon-forgejo 0.4.0

package/src/migrate/from-github/security.test.ts

@@ -0,0 +1,120 @@
+import { describe, test, expect } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import { analyzeForgejoSecurity, renderSecurityPosture, provenanceToDiagnostics } from "./security";
+
+function analyze(yaml: string) {
+  return analyzeForgejoSecurity(parseYAML(yaml), { sourceFile: "ci.yml" });
+}
+
+describe("analyzeForgejoSecurity — fate classes", () => {
+  test("workflow-level permissions is lost", () => {
+    const records = analyze(`on: push
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hi
+`);
+    const perm = records.filter((r) => r.rule === "MIG-FJ-PERMISSIONS");
+    expect(perm).toHaveLength(1);
+    expect(perm[0].security.fate).toBe("lost");
+  });
+
+  test("continue-on-error is lost (job and step)", () => {
+    const records = analyze(`on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - run: echo a
+        continue-on-error: true
+`);
+    const coe = records.filter((r) => r.rule === "MIG-FJ-CONTINUE-ON-ERROR");
+    expect(coe).toHaveLength(2);
+    expect(coe.every((r) => r.security.fate === "lost")).toBe(true);
+  });
+
+  test("an unmapped action ref needs review", () => {
+    const records = analyze(`on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: some-org/custom-action@v1
+`);
+    const act = records.filter((r) => r.rule === "MIG-FJ-ACTION-UNRESOLVED");
+    expect(act).toHaveLength(1);
+    expect(act[0].security.fate).toBe("needs-review");
+  });
+
+  test("a mapped action ref produces no finding", () => {
+    const records = analyze(`on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+`);
+    expect(records.filter((r) => r.rule === "MIG-FJ-ACTION-UNRESOLVED")).toHaveLength(0);
+  });
+
+  test("an unmapped runner label needs review; a mapped one does not", () => {
+    const records = analyze(`on: push
+jobs:
+  a:
+    runs-on: macos-latest
+    steps:
+      - run: echo a
+  b:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo b
+`);
+    const labels = records.filter((r) => r.rule === "MIG-FJ-RUNNER-LABEL");
+    expect(labels).toHaveLength(1);
+    expect(labels[0].note).toContain("macos-latest");
+  });
+});
+
+describe("renderSecurityPosture", () => {
+  test("renders a table with fate rows", () => {
+    const records = analyze(`on: push
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+`);
+    const md = renderSecurityPosture(records);
+    expect(md).toContain("## Security posture");
+    expect(md).toContain("MIG-FJ-PERMISSIONS");
+    expect(md).toContain("lost");
+  });
+
+  test("clean workflow reports no weakening", () => {
+    const md = renderSecurityPosture([]);
+    expect(md).toContain("No security-relevant properties weaken or drop");
+  });
+});
+
+describe("provenanceToDiagnostics", () => {
+  test("emits one diagnostic per record; --strict escalates to error", () => {
+    const records = analyze(`on: push
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hi
+`);
+    expect(provenanceToDiagnostics(records)).toHaveLength(1);
+    expect(provenanceToDiagnostics(records)[0].severity).toBe("warning");
+    expect(provenanceToDiagnostics(records, { strict: true })[0].severity).toBe("error");
+  });
+});

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

@@ -0,0 +1,195 @@
+/**
+ * Security-fate model for the github → forgejo migration edge.
+ *
+ * github → forgejo YAML is near-identical, so the migration itself is thin. The
+ * differentiated value is the **compare**: classifying what survives the move
+ * and what Forgejo silently drops. Most properties translate verbatim; the
+ * useful findings are the keys the Forgejo runner ignores (`permissions`,
+ * `continue-on-error` → `lost`) plus refs/labels that need attention
+ * (unresolved `uses:`, unmapped runner labels → `needs-review`).
+ *
+ * Mirrors the gitlab lexicon's fate model (translated / approximated /
+ * needs-review / lost) but for the Forgejo edge — kept local so the forgejo
+ * lexicon does not depend on the gitlab one.
+ */
+
+import type { LintDiagnostic } from "@intentius/chant/lint/rule";
+import { DEFAULT_RUNNER_LABELS } from "../../dialect";
+import { resolveActionRef } from "../../actions";
+
+export type SecurityFate = "translated" | "approximated" | "needs-review" | "lost";
+
+export interface SecurityProvenance {
+  /** Human label for the property (e.g. "Least-privilege permissions"). */
+  property: string;
+  /** What happened to the property as it crossed the github → forgejo edge. */
+  fate: SecurityFate;
+  /** Diagnostic severity for this finding. */
+  severity: "error" | "warning" | "info";
+  /** How to re-establish the property on Forgejo, when it doesn't carry. */
+  reestablish?: string;
+}
+
+/** A migration provenance record carrying a security classification. */
+export interface SecurityRecord {
+  /** YAML-ish path in the source (e.g. "jobs.build.steps[1].uses"). */
+  sourceKey: string;
+  /** Source file name (for diagnostics). */
+  sourceFile?: string;
+  /** Functional category (forgejo migration only emits security records). */
+  category: "needs-review" | "skipped" | "synthesis";
+  /** Rule ID (MIG-FJ-*). */
+  rule: string;
+  /** Human-readable explanation. */
+  note?: string;
+  /** Security classification. */
+  security: SecurityProvenance;
+}
+
+function toKebabCase(name: string): string {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/**
+ * Classify the fate of security-relevant properties in a parsed GitHub Actions
+ * workflow as it migrates to Forgejo. Walks the source object so occurrence
+ * counts (and paths) are precise.
+ */
+export function analyzeForgejoSecurity(
+  workflow: unknown,
+  opts: { sourceFile?: string } = {},
+): SecurityRecord[] {
+  const records: SecurityRecord[] = [];
+  const file = opts.sourceFile;
+
+  function visit(value: unknown, path: string): void {
+    if (value === null || typeof value !== "object") return;
+
+    if (Array.isArray(value)) {
+      value.forEach((v, i) => visit(v, `${path}[${i}]`));
+      return;
+    }
+
+    for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+      const kebab = toKebabCase(key);
+      const childPath = path ? `${path}.${key}` : key;
+
+      if (kebab === "permissions") {
+        records.push({
+          sourceKey: childPath,
+          sourceFile: file,
+          category: "skipped",
+          rule: "MIG-FJ-PERMISSIONS",
+          note: `permissions: is ignored by the Forgejo runner — the least-privilege control is lost. Re-establish it through your Forgejo/runner and repository token settings.`,
+          security: { property: "Least-privilege permissions", fate: "lost", severity: "warning", reestablish: "Forgejo runner/token settings" },
+        });
+        continue; // don't descend into a dropped subtree
+      }
+
+      if (kebab === "continue-on-error") {
+        records.push({
+          sourceKey: childPath,
+          sourceFile: file,
+          category: "skipped",
+          rule: "MIG-FJ-CONTINUE-ON-ERROR",
+          note: `continue-on-error is ignored by the Forgejo runner — the failure-tolerance control is lost. A failing step/job will fail the run.`,
+          security: { property: "continue-on-error tolerance", fate: "lost", severity: "warning" },
+        });
+        continue;
+      }
+
+      if (kebab === "uses" && typeof v === "string") {
+        const { warning } = resolveActionRef(v);
+        if (warning) {
+          records.push({
+            sourceKey: childPath,
+            sourceFile: file,
+            category: "needs-review",
+            rule: "MIG-FJ-ACTION-UNRESOLVED",
+            note: `Action ref '${v}' has no built-in Forgejo mapping and won't resolve from a GitHub Marketplace. Use a full repository URL or mirror it under forgejo.actionsRoot.`,
+            security: { property: "Action reference", fate: "needs-review", severity: "warning" },
+          });
+        }
+        continue;
+      }
+
+      if (kebab === "runs-on") {
+        for (const label of runnerLabels(v)) {
+          if (DEFAULT_RUNNER_LABELS[label] === undefined) {
+            records.push({
+              sourceKey: childPath,
+              sourceFile: file,
+              category: "needs-review",
+              rule: "MIG-FJ-RUNNER-LABEL",
+              note: `Runner label '${label}' has no built-in Forgejo mapping. Confirm a Forgejo runner advertises it, or map it via forgejo.runnerLabels.`,
+              security: { property: "Runner label", fate: "needs-review", severity: "warning" },
+            });
+          }
+        }
+        continue;
+      }
+
+      visit(v, childPath);
+    }
+  }
+
+  visit(workflow, "");
+  return records;
+}
+
+function runnerLabels(value: unknown): string[] {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.filter((v): v is string => typeof v === "string");
+  return [];
+}
+
+/**
+ * Convert security records into SARIF-shaped diagnostics. Security findings
+ * always emit a diagnostic at their severity, escalated to `error` under
+ * `--strict` when the property was lost or needs review.
+ */
+export function provenanceToDiagnostics(
+  records: SecurityRecord[],
+  opts: { strict?: boolean } = {},
+): LintDiagnostic[] {
+  return records.map((r) => {
+    const escalate = opts.strict && (r.security.fate === "lost" || r.security.fate === "needs-review");
+    return {
+      file: r.sourceFile ?? "<input>",
+      line: 1,
+      column: 1,
+      ruleId: r.rule,
+      severity: escalate ? "error" : r.security.severity,
+      message: r.note ?? r.rule,
+    };
+  });
+}
+
+interface PostureLine {
+  property: string;
+  fate: SecurityFate;
+  rule: string;
+  count: number;
+}
+
+/** Render a "Security posture" Markdown section from the security records. */
+export function renderSecurityPosture(records: SecurityRecord[]): string {
+  if (records.length === 0) {
+    return "## Security posture\n\nNo security-relevant properties weaken or drop at the Forgejo migration edge.\n";
+  }
+
+  const byRule = new Map<string, PostureLine>();
+  for (const r of records) {
+    const existing = byRule.get(r.rule);
+    if (existing) existing.count += 1;
+    else byRule.set(r.rule, { property: r.security.property, fate: r.security.fate, rule: r.rule, count: 1 });
+  }
+
+  let out = "## Security posture\n\n";
+  out += "| Property | Fate | Rule | Count |\n|---|---|---|---|\n";
+  for (const line of byRule.values()) {
+    out += `| ${line.property} | ${line.fate} | ${line.rule} | ${line.count} |\n`;
+  }
+  out += "\nFates: **translated** (carried as-is) · **approximated** · **needs-review** (confirm/adjust on Forgejo) · **lost** (the Forgejo runner ignores the property).\n";
+  return out;
+}

package/src/migrate.mcp.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Smoke test for the forgejo MCP `forgejo:compare` tool. Exercises the
+ * handler directly (the tool contract is a plain async function from
+ * inputSchema params to a result object).
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { forgejoPlugin } from "./plugin";
+
+const GHA_WORKFLOW = `name: CI
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: some-org/custom-action@v1
+      - run: npm test
+`;
+
+let dir: string;
+let file: string;
+
+beforeAll(() => {
+  dir = mkdtempSync(join(tmpdir(), "fj-compare-"));
+  file = join(dir, "ci.yml");
+  writeFileSync(file, GHA_WORKFLOW);
+});
+
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("forgejo MCP compare tool", () => {
+  test("registered in mcpTools", () => {
+    const tools = forgejoPlugin.mcpTools?.() ?? [];
+    expect(tools.map((t) => t.name)).toContain("forgejo:compare");
+  });
+
+  test("reports per-property fates and summary counts", async () => {
+    const tools = forgejoPlugin.mcpTools?.() ?? [];
+    const compare = tools.find((t) => t.name === "forgejo:compare");
+    expect(compare).toBeDefined();
+
+    const result = (await compare!.handler({ file })) as {
+      found: boolean;
+      properties: Array<{ property: string; fate: string }>;
+      summary: Record<string, number>;
+    };
+
+    expect(result.found).toBe(true);
+    const fates = result.properties.map((p) => p.fate);
+    expect(fates).toContain("lost"); // permissions
+    expect(fates).toContain("needs-review"); // unmapped action ref
+    expect(result.summary.lost).toBeGreaterThanOrEqual(1);
+    expect(result.summary["needs-review"]).toBeGreaterThanOrEqual(1);
+  });
+
+  test("returns found:false for a non-workflow file", async () => {
+    const tools = forgejoPlugin.mcpTools?.() ?? [];
+    const compare = tools.find((t) => t.name === "forgejo:compare");
+    const other = join(dir, "not-a-workflow.yml");
+    writeFileSync(other, "foo: bar\n");
+    const result = (await compare!.handler({ file: other })) as { found: boolean };
+    expect(result.found).toBe(false);
+  });
+});

package/src/migrate.test.ts

@@ -0,0 +1,71 @@
+import { describe, test, expect } from "vitest";
+import { transform, detectGitHubWorkflow } from "./migrate/from-github";
+import { forgejoPlugin } from "./plugin";
+
+const GHA_WORKFLOW = `name: CI
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: some-org/custom-action@v1
+      - run: npm test
+`;
+
+describe("github → forgejo transform", () => {
+  test("emits forgejo YAML with the dialect applied", async () => {
+    const { output } = await transform(GHA_WORKFLOW, { sourceFile: "ci.yml" });
+    expect(output).toContain("runs-on: docker");
+    expect(output).not.toContain("permissions");
+    expect(output).not.toContain("continue-on-error");
+    expect(output).toContain("https://code.forgejo.org/actions/checkout@v4");
+    // unmapped ref still present (passed through), surfaced in the compare
+    expect(output).toContain("some-org/custom-action@v1");
+  });
+
+  test("classifies property fates (provenance + posture)", async () => {
+    const { provenance, securityPosture, diagnostics } = await transform(GHA_WORKFLOW, { sourceFile: "ci.yml" });
+    const rules = provenance.map((r) => r.rule);
+    expect(rules).toContain("MIG-FJ-PERMISSIONS");
+    expect(rules).toContain("MIG-FJ-CONTINUE-ON-ERROR");
+    expect(rules).toContain("MIG-FJ-ACTION-UNRESOLVED");
+    expect(provenance.find((r) => r.rule === "MIG-FJ-PERMISSIONS")?.security.fate).toBe("lost");
+    expect(securityPosture).toContain("## Security posture");
+    expect(diagnostics.length).toBe(provenance.length);
+  });
+
+  test("emit: ts produces a chant pipeline importing from forgejo", async () => {
+    const { output } = await transform(GHA_WORKFLOW, { emit: "ts", sourceFile: "ci.yml" });
+    expect(output).toContain("@intentius/chant-lexicon-forgejo");
+    expect(output).not.toContain("@intentius/chant-lexicon-github");
+  });
+
+  test("detectGitHubWorkflow recognizes a workflow", () => {
+    expect(detectGitHubWorkflow(GHA_WORKFLOW)).toBe(true);
+    expect(detectGitHubWorkflow("foo: bar\n")).toBe(false);
+  });
+});
+
+describe("forgejoPlugin.migrationSource", () => {
+  test("supports github only", () => {
+    expect(forgejoPlugin.migrationSource?.("github")).toBeDefined();
+    expect(forgejoPlugin.migrationSource?.("gitlab")).toBeUndefined();
+  });
+
+  test("transform mirrors the gitlab MigrationResult shape", async () => {
+    const source = forgejoPlugin.migrationSource?.("github");
+    expect(source?.detect(GHA_WORKFLOW)).toBe(true);
+    const result = await source!.transform(GHA_WORKFLOW, { emit: "yaml", sourceFile: "ci.yml" });
+    expect(result.output).toContain("runs-on: docker");
+    expect(Array.isArray(result.provenance)).toBe(true);
+    expect(Array.isArray(result.diagnostics)).toBe(true);
+    expect(result.securityPosture).toContain("Security posture");
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,173 @@
+/**
+ * Forgejo Actions lexicon plugin.
+ *
+ * Forgejo runs GitHub-Actions-compatible workflows, so this lexicon is a thin
+ * dialect of the github lexicon: it reuses github's generated entities and
+ * composites wholesale (re-exported from ./index) and overrides only the
+ * serializer. There is no own spec, so the codegen lifecycle methods are
+ * intentionally no-ops — they delegate the real work to the github lexicon.
+ */
+
+import type { LexiconPlugin, InitTemplateSet, MigrationSource } from "@intentius/chant/lexicon";
+import { discoverPostSynthChecks } from "@intentius/chant/lint/discover";
+import { createSkillsLoader, createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { forgejoSerializer } from "./serializer";
+import { forgejoContextTools } from "./mcp/context-tools";
+
+const reuseNote =
+  "forgejo reuses the github lexicon's entities — run `chant generate` in the github lexicon instead.";
+
+export const forgejoPlugin: LexiconPlugin = {
+  name: "forgejo",
+  serializer: forgejoSerializer,
+
+  initTemplates(template?: string): InitTemplateSet {
+    if (template === "docker-build") {
+      return {
+        src: {
+          "pipeline.ts": `import { Workflow, Job, Step, Checkout } from "@intentius/chant-lexicon-forgejo";
+
+export const workflow = new Workflow({
+  name: "Docker Build",
+  on: { push: { branches: ["main"] } },
+});
+
+export const build = new Job({
+  "runs-on": "ubuntu-latest",
+  steps: [
+    Checkout({}).step,
+    new Step({ name: "Build", run: "docker build -t myapp ." }),
+  ],
+});
+`,
+        },
+      };
+    }
+
+    // Default template: a Node CI workflow. Reuses github entities; the forgejo
+    // serializer maps "ubuntu-latest" to a Forgejo runner label on build.
+    return {
+      src: {
+        "pipeline.ts": `import { Workflow, Job, Step, Checkout, SetupNode } from "@intentius/chant-lexicon-forgejo";
+
+export const workflow = new Workflow({
+  name: "CI",
+  on: {
+    push: { branches: ["main"] },
+    pull_request: { branches: ["main"] },
+  },
+});
+
+export const build = new Job({
+  "runs-on": "ubuntu-latest",
+  steps: [
+    Checkout({}).step,
+    SetupNode({ nodeVersion: "22", cache: "npm" }).step,
+    new Step({ name: "Install", run: "npm ci" }),
+    new Step({ name: "Build", run: "npm run build" }),
+    new Step({ name: "Test", run: "npm test" }),
+  ],
+});
+`,
+      },
+    };
+  },
+
+  detectTemplate(data: unknown): boolean {
+    if (typeof data !== "object" || data === null) return false;
+    const obj = data as Record<string, unknown>;
+
+    // Forgejo Actions workflows are GitHub-Actions-shaped: `on:` + `jobs:`.
+    if (obj.on !== undefined && obj.jobs !== undefined) return true;
+
+    for (const value of Object.values(obj)) {
+      if (typeof value === "object" && value !== null) {
+        const entry = value as Record<string, unknown>;
+        if (entry["runs-on"] !== undefined || entry.steps !== undefined) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  },
+
+  migrationSource(from: string): MigrationSource | undefined {
+    if (from !== "github") return undefined;
+    return {
+      detect(content: string): boolean {
+        // Inline heuristic — keeps the migrate code out of the import graph
+        // until a transform actually runs.
+        if (!/^\s*jobs\s*:/m.test(content)) return false;
+        return /^\s*on\s*:/m.test(content) || /^\s*runs-on\s*:/m.test(content);
+      },
+      async transform(content: string, opts) {
+        const { transform } = await import("./migrate/from-github");
+        const result = await transform(content, {
+          emit: opts.emit,
+          sourceFile: opts.sourceFile,
+          strict: opts.strict,
+          security: opts.security,
+        });
+        return {
+          output: result.output,
+          provenance: result.provenance as unknown as Array<Record<string, unknown>>,
+          diagnostics: result.diagnostics as unknown as Array<Record<string, unknown>>,
+          securityPosture: result.securityPosture,
+        };
+      },
+    };
+  },
+
+  postSynthChecks() {
+    const dir = join(dirname(fileURLToPath(import.meta.url)), "lint", "post-synth");
+    return discoverPostSynthChecks(dir, import.meta.url);
+  },
+
+  mcpTools() {
+    return [
+      createDiffTool(forgejoSerializer, "Compare current build output against previous output for Forgejo Actions", "forgejo"),
+      ...forgejoContextTools(),
+    ];
+  },
+
+  skills: createSkillsLoader(import.meta.url, [
+    {
+      file: "chant-forgejo.md",
+      name: "chant-forgejo",
+      description: "Forgejo / Codeberg / Gitea Actions with chant — build, the dialect (dropped keys, runner labels, uses: resolution), and github→forgejo migration",
+      triggers: [
+        { type: "file-pattern", value: "**/.forgejo/workflows/*.yml" },
+        { type: "file-pattern", value: "**/.gitea/workflows/*.yml" },
+        { type: "context", value: "forgejo" },
+        { type: "context", value: "codeberg" },
+        { type: "context", value: "gitea" },
+      ],
+      parameters: [],
+      examples: [
+        {
+          title: "Build a Forgejo workflow",
+          description: "Author github-style; the forgejo dialect applies on build",
+          input: "Create a CI workflow for Codeberg",
+          output: `chant build src -o .forgejo/workflows/ci.yml`,
+        },
+      ],
+    },
+  ]),
+
+  // ── Codegen lifecycle — delegated to github (no own spec) ──────────
+  async generate(): Promise<void> {
+    console.error(reuseNote);
+  },
+  async validate(): Promise<void> {
+    console.error("All checks passed.");
+  },
+  async coverage(): Promise<void> {
+    console.error(reuseNote);
+  },
+  async package(): Promise<void> {
+    console.error(reuseNote);
+  },
+};