@intentius/chant-lexicon-gitlab 0.1.12 → 0.1.14

package/src/migrate.mcp.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Smoke test for the gitlab MCP `migrate` tool. Exercises the tool's
+ * handler directly (no JSON-RPC harness needed — the tool contract is
+ * a plain async function from inputSchema params to a result object).
+ */
+
+import { describe, test, expect } from "vitest";
+import { gitlabPlugin } from "./plugin";
+
+describe("gitlab MCP migrate tool", () => {
+  test("registered alongside the diff tool", () => {
+    const tools = gitlabPlugin.mcpTools?.() ?? [];
+    const names = tools.map((t) => t.name);
+    // The MCP server applies ${plugin.name}: namespacing at registration
+    // time. Diff is pre-prefixed by createDiffTool; migrate is plain.
+    expect(names).toContain("gitlab:diff");
+    expect(names).toContain("migrate");
+  });
+
+  test("handler translates a trivial workflow", async () => {
+    const tools = gitlabPlugin.mcpTools?.() ?? [];
+    const migrate = tools.find((t) => t.name === "migrate");
+    expect(migrate).toBeDefined();
+    const result = await migrate!.handler({
+      content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hello
+`,
+    }) as { output: string; diagnostics: unknown[]; provenance: unknown[]; stages: string[] };
+
+    expect(result.output).toContain("stages:");
+    expect(result.output).toContain("build:");
+    expect(Array.isArray(result.diagnostics)).toBe(true);
+    expect(Array.isArray(result.provenance)).toBe(true);
+    expect(result.stages).toContain("build");
+  });
+
+  test("respects useComposites toggle", async () => {
+    const tools = gitlabPlugin.mcpTools?.() ?? [];
+    const migrate = tools.find((t) => t.name === "migrate")!;
+    const nodePipelineWorkflow = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npm ci
+      - run: npm run build
+  test:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npm ci
+      - run: npm test
+`;
+    const without = await migrate.handler({ content: nodePipelineWorkflow, emit: "ts" }) as { output: string };
+    const withC = await migrate.handler({ content: nodePipelineWorkflow, emit: "ts", useComposites: true }) as { output: string };
+    expect(without.output).not.toContain("NodePipeline(");
+    expect(withC.output).toContain("NodePipeline(");
+  });
+});

package/src/plugin.test.ts

@@ -214,9 +214,13 @@ describe("gitlabPlugin", () => {
 
   test("returns MCP tools", () => {
     const tools = gitlabPlugin.mcpTools!();
-    expect(tools).toHaveLength(1);
-    expect(tools[0].name).toBe("gitlab:diff");
-    expect(typeof tools[0].handler).toBe("function");
+    expect(tools.length).toBeGreaterThanOrEqual(2);
+    const names = tools.map((t) => t.name);
+    expect(names).toContain("gitlab:diff");
+    expect(names).toContain("migrate");
+    for (const t of tools) {
+      expect(typeof t.handler).toBe("function");
+    }
   });
 
   test("returns MCP resources", () => {

package/src/plugin.ts

@@ -252,7 +252,68 @@ export const test = new Job({
   },
 
   mcpTools() {
-    return [createDiffTool(gitlabSerializer, "Compare current build output against previous output for GitLab CI", "gitlab")];
+    return [
+      createDiffTool(gitlabSerializer, "Compare current build output against previous output for GitLab CI", "gitlab"),
+      {
+        name: "migrate",
+        description: "Translate a GitHub Actions workflow YAML into a GitLab CI/CD pipeline. Returns the rendered output plus diagnostic + provenance arrays.",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            content: { type: "string", description: "Raw .github/workflows/*.yml content" },
+            emit: { type: "string", enum: ["yaml", "ts"], description: "Output format (default: yaml)" },
+            useComposites: { type: "boolean", description: "Recognise composite patterns and emit NodePipeline/NodeCI calls" },
+            strict: { type: "boolean", description: "Escalate needs-review diagnostics to errors" },
+          },
+          required: ["content"],
+        },
+        async handler(params: Record<string, unknown>): Promise<unknown> {
+          const { transform } = await import("./migrate/from-github/index");
+          const result = await transform(params.content as string, {
+            emit: (params.emit as "yaml" | "ts" | undefined) ?? "yaml",
+            useComposites: !!params.useComposites,
+            strict: !!params.strict,
+            sourceFile: "<mcp-input>",
+          });
+          return {
+            output: result.output,
+            diagnostics: result.diagnostics,
+            provenance: result.provenance,
+            stages: result.stages,
+          };
+        },
+      },
+    ];
+  },
+
+  migrationSource(from: string) {
+    if (from !== "github") return undefined;
+    return {
+      detect(content: string): boolean {
+        // Avoid bringing the migrate code into the import graph until needed
+        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/index");
+        const result = await transform(content, {
+          emit: opts.emit,
+          useComposites: opts.useComposites,
+          sourceFile: opts.sourceFile,
+          strict: opts.strict,
+        });
+        // The composites rewriter (when enabled) replaces several Job
+        // resources with a single Composite resource — stages: in the
+        // top-level YAML output is now stale for that path. The yaml
+        // emitter reads metadata.stages directly; no special handling
+        // needed at the call site.
+        return {
+          output: result.output,
+          provenance: result.provenance as unknown as Array<Record<string, unknown>>,
+          diagnostics: result.diagnostics as unknown as Array<Record<string, unknown>>,
+        };
+      },
+    };
   },
 
   mcpResources() {
@@ -400,6 +461,49 @@ curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \\
         },
       ],
     },
+    {
+      file: "chant-gitlab-migrate.md",
+      name: "chant-gitlab-migrate",
+      description: "Translate GitHub Actions workflows into GitLab CI/CD pipelines via chant migrate",
+      triggers: [
+        { type: "file-pattern", value: "**/.github/workflows/*.yml" },
+        { type: "file-pattern", value: "**/.github/workflows/*.yaml" },
+        { type: "context", value: "migrate from github actions" },
+        { type: "context", value: "github actions to gitlab" },
+        { type: "context", value: "convert workflow" },
+      ],
+      preConditions: [
+        "chant CLI is installed (chant --version succeeds)",
+        "@intentius/chant-lexicon-gitlab is installed",
+      ],
+      postConditions: [
+        "Translated .gitlab-ci.yml or .ts source on disk",
+        "Migration report visible to the user (Markdown + SARIF if --report)",
+      ],
+      parameters: [],
+      examples: [
+        {
+          title: "Translate a single workflow file",
+          description: "Migrate .github/workflows/ci.yml into .gitlab-ci.yml with a SARIF report",
+          input: "Migrate this GitHub workflow to GitLab CI",
+          output: `npx chant migrate .github/workflows/ci.yml \\
+  --output .gitlab-ci.yml \\
+  --report migration.sarif`,
+        },
+        {
+          title: "Translate to chant TypeScript",
+          description: "Produce typed chant source instead of YAML so the user can maintain the pipeline in chant going forward",
+          input: "I want to maintain this in chant — produce TypeScript",
+          output: `npx chant migrate .github/workflows/ci.yml --emit ts --output src/pipeline.ts`,
+        },
+        {
+          title: "Recognise and emit composites",
+          description: "Collapse a 2-job NodePipeline-shaped workflow into a single NodePipeline() call",
+          input: "Use composites for the upgrade",
+          output: `npx chant migrate .github/workflows/ci.yml --emit ts --use-composites --output src/pipeline.ts`,
+        },
+      ],
+    },
     {
       file: "chant-gitlab-patterns.md",
       name: "chant-gitlab-patterns",

package/src/skills/chant-gitlab-migrate.md

@@ -0,0 +1,117 @@
+---
+skill: chant-gitlab-migrate
+description: Translate GitHub Actions workflows into GitLab CI/CD pipelines via chant migrate
+user-invocable: true
+---
+
+# Chant GitHub Actions → GitLab CI/CD Migration
+
+## When to invoke this skill
+
+The user wants to translate a `.github/workflows/*.yml` workflow into a `.gitlab-ci.yml` pipeline. Trigger phrases include:
+
+- "migrate this GitHub workflow to GitLab"
+- "convert .github/workflows/ci.yml to GitLab CI"
+- pasting a GitHub workflow and asking "how would this look in GitLab"
+- evaluating GitLab CI/CD from a GitHub Actions background
+- "what's the GitLab equivalent of <action>"
+
+This skill is the operational glue around `chant migrate`. The translation logic lives in `@intentius/chant-lexicon-gitlab`; this skill knows how to invoke it, surface the report, and suggest GitLab-only upgrade moments.
+
+## Distinction from the upstream GitLab skill
+
+The upstream `gitlab-org/ci-cd/github-actions-to-gitlab-ci` Agent Skill (MIT) translates workflows by direct LLM prompting — stateless, freehand each run. `chant migrate` ports the same translation rules into a typed compiler so the output is reproducible, testable, and re-runnable. The skills are complementary:
+
+- Use the upstream skill for one-shot read-and-respond ("here's my YAML, paste the answer").
+- Use `chant migrate` when the translation has to survive evolution of the source workflow.
+
+## Step 1: Detect
+
+Confirm the input is a GitHub Actions workflow. Heuristic: top-level `jobs:` plus either `on:` or per-job `runs-on:`. If you're given a path, read the file. If pasted inline, work from the paste.
+
+## Step 2: Dry-run migrate
+
+Run with no `--strict`, no `--validate` first so the user sees the full translation including any NeedsReview items:
+
+```bash
+npx chant migrate path/to/workflow.yml --output /tmp/proposed.gitlab-ci.yml --report /tmp/migration.sarif
+```
+
+Or for inline content, pipe via a temp file:
+
+```bash
+TMPF=$(mktemp --suffix=.yml) && cat > "$TMPF" <<'EOF'
+<paste workflow here>
+EOF
+npx chant migrate "$TMPF" --output /tmp/proposed.gitlab-ci.yml --report /tmp/migration.sarif
+```
+
+The Markdown summary always prints to stderr. The SARIF v2.1.0 report goes to `--report`.
+
+## Step 3: Review NeedsReview items
+
+The transformer surfaces categorised provenance. The categories are:
+
+| Category | Severity (default) | Meaning |
+|---|---|---|
+| literal | (none, no diagnostic) | Direct key rename (env → variables) |
+| rewrite | (none, no diagnostic) | Expression substitution (github.ref → $CI_COMMIT_REF_NAME) |
+| synthesis | (none, no diagnostic) | Emitted construct with no GH original (inferred stage) |
+| action-map tier 3 | warning | Marketplace action mapping that requires manual review |
+| skipped | info | Intentionally dropped (actions/checkout) |
+| needs-review | warning | No clean translation — user must decide |
+
+Common needs-review rules and the right response:
+
+- **MIG-PERMISSIONS-001**: GitHub `permissions:` has no per-job equivalent. Configure CI/CD token access at project level (Settings > CI/CD > Token Access).
+- **MIG-ON-SCHEDULE**: GitLab cron schedules live in the UI under CI/CD > Schedules, not in YAML. The workflow rule (`$CI_PIPELINE_SOURCE == "schedule"`) is emitted; the schedule itself needs UI setup.
+- **MIG-ON-DISPATCH**: `workflow_dispatch` inputs require `spec:inputs` (GitLab 17+) with defaults on every input (auto-triggered pipelines can't prompt).
+- **MIG-NEEDS-OUTPUTS-001**: GitHub job outputs require the `artifacts:reports:dotenv` pattern in GitLab. Manual rewire needed.
+- **MIG-ACTION-UNKNOWN**: A marketplace action has no registered mapping. Either replace with an inline script, or add an `--action-mapping <file>` extension (future flag).
+
+## Step 4: Validate (optional)
+
+If the user has `glci` or `glab` installed locally, run validation:
+
+```bash
+npx chant migrate path/to/workflow.yml --output .gitlab-ci.yml --validate
+```
+
+The CLI picks `glci` (offline, no auth) first; `glab ci lint` second. If neither is on PATH, `--validate` warns and skips. Pair with `--strict` to make validation failures hard.
+
+## Step 5: Decide the emit mode
+
+Two modes serve different intents:
+
+- `--emit yaml` (default): produces `.gitlab-ci.yml` directly. Right when the user wants the YAML and is done with chant going forward.
+- `--emit ts`: produces chant TypeScript source the user owns. Right when the user wants to maintain the pipeline in chant — they can edit the typed source and rebuild via `chant build` to refresh the YAML.
+
+When in doubt, do `--emit yaml` first to validate the translation, then offer `--emit ts` as the long-term ownership option.
+
+## Step 6: Suggest the upgrade moments
+
+After surfacing the literal translation, opportunistically suggest GitLab-native features that improve on the GitHub original. Only suggest when they actually apply:
+
+- `--use-composites` recognises Node-shaped pipelines and emits `NodePipeline({...})` or `NodeCI({...})` instead of raw `Job` constructors. The output is 5-10x shorter and easier to maintain.
+- DAG `needs:` removes stage barriers — jobs run as soon as deps complete (already handled by the transformer for explicit `needs:`).
+- `rules:changes:` enables monorepo path-based job filtering — no GitHub equivalent.
+- `resource_group:` serialises deploys to the same environment (covered when GH `concurrency.group:` is translated).
+- `include:` shares config across projects and workflows.
+- GitLab CI templates (`Auto-DevOps`, `Security/SAST`, `Terraform/Base`) — no GitHub Actions equivalent.
+
+## Self-check rubric
+
+Before reporting "done" to the user, verify:
+
+- [ ] Was `actions/checkout` removed (GitLab clones automatically)?
+- [ ] Was `runs-on:` translated to `image:` (Linux runners) or `tags:` (self-hosted)?
+- [ ] Did every `uses:` step either map cleanly or get flagged with NeedsReview?
+- [ ] Did `if:` conditions translate to `rules:if:` (NOT a string substitution; semantics differ)?
+- [ ] Were `permissions:` items documented as manual project-level setup?
+- [ ] Was the migration report (Markdown + SARIF) surfaced to the user?
+- [ ] Were `NeedsReview` items called out explicitly?
+- [ ] Did I suggest `--use-composites` if Node patterns were detected?
+
+## Inspired by
+
+`gitlab-org/ci-cd/github-actions-to-gitlab-ci` — MIT. The trigger-phrase patterns, the four-category report shape, and the "suggest GitLab improvements" step are direct ports. The difference: this skill *calls* a compiler instead of *being* one.