@intentius/chant-lexicon-gitlab 0.1.11 → 0.1.14

package/README.md

@@ -27,6 +27,10 @@ npm install --save-dev @intentius/chant @intentius/chant-lexicon-gitlab
 
 If a concrete observation use case surfaces, file a focused issue rather than retrofitting `listArtifacts()` to fit.
 
+## GitHub Actions migration
+
+`chant migrate` translates `.github/workflows/*.yml` into `.gitlab-ci.yml` or typed chant TypeScript. The transformer, action-mapping registry, and provenance model are ported from `gitlab-org/ci-cd/github-actions-to-gitlab-ci` (MIT). See [Migration](https://intentius.io/chant/lexicons/gitlab/migration/) and [`ATTRIBUTIONS.md`](./ATTRIBUTIONS.md).
+
 ## License
 
 See the main project LICENSE file.

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "bf526b6f9f73e10cebc3f09f09a5f47a4209f0f227b2cdab8a937fadb490441a",
+    "manifest.json": "1121cc5d536544ee7de9b5326c5aa47929f4ac40591d4269e1e50e428f7c32dc",
     "meta.json": "931fc3246a55645b1493080bbeb160e5d205e42349e8bdca96ca243adb5f0da3",
     "types/index.d.ts": "5cd2e99f135a929b72bdd822d00d780d39b1cd407ba0cfb3d511c7ac9d667b58",
     "rules/artifact-no-expiry.ts": "3f3cabf9792cbf8207e53a25f506715466b19ec25e9c3b4d0d77fed6b2eb4542",
@@ -29,7 +29,8 @@
     "rules/wgl028.ts": "f1c64eda25e2ad8da634d64a397f877a46ae8327713db5cf3193882bb9b96453",
     "rules/yaml-helpers.ts": "f2322530a7fd812e482c5a7df05d0d05787b207574b67b811776786e00fd3e18",
     "skills/chant-gitlab.md": "1e26a0c50ea891423479bd7fec3bc133f9185727c4a3eaadd525d7e7436056b6",
+    "skills/chant-gitlab-migrate.md": "9402ed4fcfd25971cf72f8f02a93c43aadfed3b83876081b92711562ce1bdc34",
     "skills/chant-gitlab-patterns.md": "cefda1b656f222293d16381dfbf452b2b376b545a69f62e55dc38907fe8aa7fa"
   },
-  "composite": "9e350e4b9ef3118fd4eec7e9b3eaef2c5477f825cbffbae60aecf24ca7fd731a"
+  "composite": "95153640312955ba3ebf46f26199a5c749cf81ae007ffdaa1b38f23148ca6464"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gitlab",
-  "version": "0.1.11",
+  "version": "0.1.14",
   "chantVersion": ">=0.1.0",
   "namespace": "GitLab",
   "intrinsics": [

package/dist/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.

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.1.11",
+  "version": "0.1.14",
   "description": "GitLab CI lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
   "repository": {
     "type": "git",
-    "url": "https://github.com/intentius/chant.git",
+    "url": "https://github.com/INTENTIUS/chant.git",
     "directory": "lexicons/gitlab"
   },
   "bugs": {
-    "url": "https://github.com/intentius/chant/issues"
+    "url": "https://github.com/INTENTIUS/chant/issues"
   },
   "keywords": [
     "infrastructure-as-code",
@@ -44,9 +44,16 @@
   },
   "devDependencies": {
     "@intentius/chant": "*",
+    "@intentius/chant-lexicon-github": "*",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.1.0"
+    "@intentius/chant": "^0.1.0",
+    "@intentius/chant-lexicon-github": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@intentius/chant-lexicon-github": {
+      "optional": true
+    }
   }
 }

package/src/import/generator.ts

@@ -17,6 +17,17 @@ const TYPE_TO_CLASS: Record<string, string> = {
   "GitLab::CI::Workflow": "Workflow",
 };
 
+/**
+ * Composite IR types emit as `FunctionName({...})` factory calls rather
+ * than `new ClassName({...})` constructors. The `chant migrate --use-
+ * composites` rewriter rewrites recognised IR shapes into these sentinel
+ * types (see `lexicons/gitlab/src/migrate/from-github/composites/`).
+ */
+const COMPOSITE_TYPE_TO_FN: Record<string, string> = {
+  "GitLab::Composite::NodePipeline": "NodePipeline",
+  "GitLab::Composite::NodeCI": "NodeCI",
+};
+
 /**
  * Properties that reference known property entities.
  */
@@ -45,6 +56,8 @@ export class GitLabGenerator implements TypeScriptGenerator {
     for (const resource of ir.resources) {
       const cls = TYPE_TO_CLASS[resource.type];
       if (cls) usedConstructors.add(cls);
+      const fn = COMPOSITE_TYPE_TO_FN[resource.type];
+      if (fn) usedConstructors.add(fn);
 
       // Check properties for nested constructors
       this.collectNestedConstructors(resource.properties, usedConstructors);
@@ -78,12 +91,17 @@ export class GitLabGenerator implements TypeScriptGenerator {
     // Emit resources
     for (const resource of ir.resources) {
       const cls = TYPE_TO_CLASS[resource.type];
-      if (!cls) continue;
+      const fn = COMPOSITE_TYPE_TO_FN[resource.type];
+      if (!cls && !fn) continue;
 
       const varName = resource.logicalId;
       const propsStr = this.emitProps(resource.properties, 1);
 
-      lines.push(`export const ${varName} = new ${cls}(${propsStr});`);
+      if (fn) {
+        lines.push(`export const ${varName} = ${fn}(${propsStr});`);
+      } else {
+        lines.push(`export const ${varName} = new ${cls}(${propsStr});`);
+      }
       lines.push("");
     }
 

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

@@ -0,0 +1,27 @@
+/**
+ * Action mapping registry — public surface.
+ *
+ * Tier 1 mappings auto-register into the default registry on import of
+ * this module. Tier 2 and Tier 3 are added in #88.
+ */
+
+export type {
+  ActionMapping,
+  ActionMapCtx,
+  ActionMappedResult,
+  ActionMappingRegistry,
+} from "./registry";
+export { createRegistry, getDefaultRegistry, lookupAction, setDefaultRegistry } from "./registry";
+
+import { registerTier1 } from "./tier-1";
+import { registerTier2 } from "./tier-2";
+import { registerTier3 } from "./tier-3";
+import { getDefaultRegistry } from "./registry";
+
+// Auto-register Tiers 1/2/3 into the default registry the first time
+// this module is imported.
+registerTier1(getDefaultRegistry());
+registerTier2(getDefaultRegistry());
+registerTier3(getDefaultRegistry());
+
+export { registerTier1, registerTier2, registerTier3 };

package/src/migrate/from-github/actions/registry.ts

@@ -0,0 +1,112 @@
+/**
+ * ActionMapping registry for GitHub Actions → GitLab CI translation.
+ *
+ * Each marketplace action gets a typed mapping that returns the GitLab-side
+ * effects (script lines, image substitution, services, cache, artifacts,
+ * job-level variables) plus provenance records.
+ *
+ * v1 ships a built-in registry covering 33 actions (Tier 1/2/3, see
+ * `tier-1.ts`/`tier-2.ts`/`tier-3.ts`). Users can inject their own
+ * mappings via `MigrateOptions.registry`.
+ */
+
+import type { ProvenanceRecord } from "../provenance";
+
+export interface ActionMapCtx {
+  /** GitLab IR job logicalId */
+  logicalId: string;
+  /** Original GitHub job name (kebab-case) */
+  jobName: string;
+  /** Source file (for provenance) */
+  sourceFile?: string;
+  /** 0-based step index within the job */
+  stepIndex: number;
+}
+
+export interface ActionMappedResult {
+  /** Lines appended to the GitLab job `script:` */
+  scriptLines: string[];
+  /** Lines prepended to the GitLab job `before_script:` */
+  beforeScript?: string[];
+  /** Job-level image override (last write wins) */
+  image?: string;
+  /** Job-level services to add */
+  services?: unknown[];
+  /** Job-level cache config */
+  cache?: Record<string, unknown>;
+  /** Job-level artifacts config */
+  artifacts?: Record<string, unknown>;
+  /** Job-level variables to merge */
+  variables?: Record<string, unknown>;
+  /** Provenance records for this mapping firing */
+  provenance: ProvenanceRecord[];
+}
+
+export interface ActionMapping {
+  /** Action name without version, e.g. "actions/checkout" */
+  actionName: string;
+  /** Optional version filter (matches against major version) */
+  majorVersions?: string[];
+  /** Tier (1: must-have, 2: common, 3: niche) */
+  tier: 1 | 2 | 3;
+  /** Apply the mapping to a step */
+  translate(step: Record<string, unknown>, ctx: ActionMapCtx): ActionMappedResult;
+}
+
+export interface ActionMappingRegistry {
+  register(mapping: ActionMapping): void;
+  lookup(actionRef: string): ActionMapping | undefined;
+}
+
+class DefaultRegistry implements ActionMappingRegistry {
+  private byName = new Map<string, ActionMapping[]>();
+
+  register(mapping: ActionMapping): void {
+    const arr = this.byName.get(mapping.actionName) ?? [];
+    arr.push(mapping);
+    this.byName.set(mapping.actionName, arr);
+  }
+
+  lookup(actionRef: string): ActionMapping | undefined {
+    // actionRef is e.g. "actions/checkout@v4" or "docker/build-push-action@v5"
+    const [name, version] = actionRef.split("@");
+    const candidates = this.byName.get(name);
+    if (!candidates || candidates.length === 0) return undefined;
+    if (!version) return candidates[0];
+    // Find a mapping whose majorVersions includes this version (best effort)
+    const major = version.replace(/^v/, "").split(".")[0];
+    for (const c of candidates) {
+      if (!c.majorVersions || c.majorVersions.length === 0) return c;
+      if (c.majorVersions.includes(`v${major}`) || c.majorVersions.includes(major)) {
+        return c;
+      }
+    }
+    // No version match — fall back to first registered
+    return candidates[0];
+  }
+}
+
+let defaultRegistryInstance: ActionMappingRegistry | undefined;
+
+export function getDefaultRegistry(): ActionMappingRegistry {
+  if (!defaultRegistryInstance) {
+    defaultRegistryInstance = new DefaultRegistry();
+  }
+  return defaultRegistryInstance;
+}
+
+/**
+ * Test-only: replace the default registry. Used by `lookupAction` callers
+ * that pass `opts.registry` to inject a stub. Reset to undefined to restore.
+ */
+export function setDefaultRegistry(registry: ActionMappingRegistry | undefined): void {
+  defaultRegistryInstance = registry;
+}
+
+export function createRegistry(): ActionMappingRegistry {
+  return new DefaultRegistry();
+}
+
+export function lookupAction(actionRef: string, registry?: ActionMappingRegistry): ActionMapping | undefined {
+  return (registry ?? getDefaultRegistry()).lookup(actionRef);
+}

package/src/migrate/from-github/actions/tier-1.test.ts

@@ -0,0 +1,128 @@
+import { describe, test, expect, beforeAll } from "vitest";
+import { createRegistry, lookupAction } from "./registry";
+import { registerTier1 } from "./tier-1";
+import type { ActionMapCtx } from "./registry";
+
+const ctx: ActionMapCtx = { logicalId: "build", jobName: "build", stepIndex: 0 };
+
+const reg = createRegistry();
+beforeAll(() => registerTier1(reg));
+
+function callAction(uses: string, withProps: Record<string, unknown> = {}) {
+  const m = lookupAction(uses, reg);
+  if (!m) throw new Error(`No mapping for ${uses}`);
+  return m.translate({ uses, with: withProps }, ctx);
+}
+
+describe("Tier 1 mappings", () => {
+  test("actions/checkout removes step + may set GIT_DEPTH", () => {
+    const r = callAction("actions/checkout@v4");
+    expect(r.scriptLines).toEqual([]);
+    expect(r.provenance[0].category).toBe("skipped");
+  });
+
+  test("actions/checkout with fetch-depth sets GIT_DEPTH", () => {
+    const r = callAction("actions/checkout@v4", { "fetch-depth": 0 });
+    expect(r.variables?.GIT_DEPTH).toBe(0);
+  });
+
+  test("actions/setup-node sets image: node:<v>", () => {
+    const r = callAction("actions/setup-node@v4", { "node-version": "20" });
+    expect(r.image).toBe("node:20");
+  });
+
+  test("actions/setup-node with cache: npm sets cache paths", () => {
+    const r = callAction("actions/setup-node@v4", { "node-version": "20", cache: "npm" });
+    expect(r.cache?.paths).toEqual([".npm/"]);
+  });
+
+  test("actions/setup-python sets image: python:<v>", () => {
+    const r = callAction("actions/setup-python@v5", { "python-version": "3.11" });
+    expect(r.image).toBe("python:3.11");
+  });
+
+  test("actions/setup-java sets eclipse-temurin", () => {
+    const r = callAction("actions/setup-java@v3", { "java-version": "17" });
+    expect(r.image).toBe("eclipse-temurin:17");
+  });
+
+  test("actions/setup-go sets image: golang:<v>", () => {
+    const r = callAction("actions/setup-go@v5", { "go-version": "1.21" });
+    expect(r.image).toBe("golang:1.21");
+  });
+
+  test("actions/setup-ruby sets image: ruby:<v>", () => {
+    const r = callAction("actions/setup-ruby@v1", { "ruby-version": "3.3" });
+    expect(r.image).toBe("ruby:3.3");
+  });
+
+  test("actions/cache → cache: keyword", () => {
+    const r = callAction("actions/cache@v3", { path: "node_modules\n.npm", key: "v1-${{ runner.os }}" });
+    expect(r.cache?.paths).toEqual(["node_modules", ".npm"]);
+    expect(r.cache?.key).toContain("v1-");
+  });
+
+  test("actions/upload-artifact → artifacts: keyword", () => {
+    const r = callAction("actions/upload-artifact@v4", { name: "out", path: "dist", "retention-days": 7 });
+    expect(r.artifacts?.paths).toEqual(["dist"]);
+    expect(r.artifacts?.name).toBe("out");
+    expect(r.artifacts?.expire_in).toBe("7 days");
+  });
+
+  test("actions/download-artifact → no-op (GitLab auto-passes)", () => {
+    const r = callAction("actions/download-artifact@v4");
+    expect(r.scriptLines).toEqual([]);
+  });
+
+  test("docker/login-action emits docker login", () => {
+    const r = callAction("docker/login-action@v3", {
+      registry: "ghcr.io",
+      username: "${{ github.actor }}",
+      password: "${{ secrets.GH_TOKEN }}",
+    });
+    expect(r.scriptLines.join("\n")).toContain("docker login");
+    expect(r.scriptLines.join("\n")).toContain("ghcr.io");
+  });
+
+  test("docker/build-push-action emits docker build/push + dind", () => {
+    const r = callAction("docker/build-push-action@v5", {
+      tags: "ghcr.io/me/img:latest",
+      push: true,
+    });
+    expect(r.image).toBe("docker:latest");
+    expect(r.services?.[0]).toMatchObject({ name: "docker:dind" });
+    expect(r.scriptLines.some((l) => l.startsWith("docker build"))).toBe(true);
+    expect(r.scriptLines.some((l) => l.startsWith("docker push"))).toBe(true);
+  });
+
+  test("docker/setup-buildx-action emits buildx create", () => {
+    const r = callAction("docker/setup-buildx-action@v3");
+    expect(r.scriptLines.some((l) => l.includes("buildx create"))).toBe(true);
+    expect(r.image).toBe("docker:latest");
+  });
+
+  test("docker/setup-qemu-action emits binfmt", () => {
+    const r = callAction("docker/setup-qemu-action@v3", { platforms: "linux/arm64" });
+    expect(r.scriptLines.some((l) => l.includes("tonistiigi/binfmt"))).toBe(true);
+  });
+
+  test("actions/github-script → needs-review with TODO comment", () => {
+    const r = callAction("actions/github-script@v7");
+    expect(r.scriptLines.some((l) => l.startsWith("# TODO"))).toBe(true);
+    expect(r.provenance[0].category).toBe("needs-review");
+  });
+
+  test("registry contains all 14 Tier 1 actions", () => {
+    const names = [
+      "actions/checkout", "actions/setup-node", "actions/setup-python",
+      "actions/setup-java", "actions/setup-go", "actions/setup-ruby",
+      "actions/cache", "actions/upload-artifact", "actions/download-artifact",
+      "docker/login-action", "docker/build-push-action",
+      "docker/setup-buildx-action", "docker/setup-qemu-action",
+      "actions/github-script",
+    ];
+    for (const n of names) {
+      expect(lookupAction(`${n}@v1`, reg)).toBeDefined();
+    }
+  });
+});