@intentius/chant-lexicon-gitlab 0.1.11 → 0.1.14

package/src/migrate/from-github/fixtures/syntax-mapping/04-env-secrets/input.yml

@@ -0,0 +1,11 @@
+on: push
+env:
+  GREETING: Hello
+jobs:
+  greet:
+    runs-on: ubuntu-latest
+    env:
+      NAME: World
+    steps:
+      - run: echo "$GREETING $NAME"
+      - run: echo "Token is ${{ secrets.API_TOKEN }}"

package/src/migrate/from-github/fixtures/syntax-mapping/05-conditional/expected-report.json

@@ -0,0 +1,13 @@
+{
+  "totals": {
+    "error": 0,
+    "warning": 0,
+    "info": 0
+  },
+  "ruleIds": [],
+  "needsReview": [],
+  "provenance": {
+    "literalRewrites": 6,
+    "actionMappings": []
+  }
+}

package/src/migrate/from-github/fixtures/syntax-mapping/05-conditional/expected.gitlab-ci.yml

@@ -0,0 +1,24 @@
+# Generated by chant migrate from input.yml
+
+stages:
+  - build
+  - deploy
+workflow:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push"'
+
+deploy:
+  image: ubuntu:24.04
+  rules:
+    - if: '$CI_COMMIT_REF_NAME == ''refs/heads/main'' && $CI_PIPELINE_SOURCE == ''push'''
+  script:
+    - make deploy
+  stage: deploy
+
+notify:
+  image: ubuntu:24.04
+  rules:
+    - when: on_failure
+  script:
+    - ./notify-slack.sh
+  stage: build

package/src/migrate/from-github/fixtures/syntax-mapping/05-conditional/input.yml

@@ -0,0 +1,12 @@
+on: push
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - run: make deploy
+  notify:
+    runs-on: ubuntu-latest
+    if: failure()
+    steps:
+      - run: ./notify-slack.sh

package/src/migrate/from-github/fixtures/syntax-mapping/06-services/expected-report.json

@@ -0,0 +1,13 @@
+{
+  "totals": {
+    "error": 0,
+    "warning": 0,
+    "info": 0
+  },
+  "ruleIds": [],
+  "needsReview": [],
+  "provenance": {
+    "literalRewrites": 4,
+    "actionMappings": []
+  }
+}

package/src/migrate/from-github/fixtures/syntax-mapping/06-services/expected.gitlab-ci.yml

@@ -0,0 +1,18 @@
+# Generated by chant migrate from input.yml
+
+stages:
+  - test
+workflow:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push"'
+
+test:
+  image: node:20-alpine
+  services:
+    - name: postgres:15
+      alias: postgres
+      variables:
+        POSTGRES_PASSWORD: secret
+  script:
+    - npm test
+  stage: test

package/src/migrate/from-github/fixtures/syntax-mapping/06-services/input.yml

@@ -0,0 +1,13 @@
+on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    container:
+      image: node:20-alpine
+    services:
+      - name: postgres:15
+        alias: postgres
+        variables:
+          POSTGRES_PASSWORD: secret
+    steps:
+      - run: npm test

package/src/migrate/from-github/fixtures/syntax-mapping/07-job-control/expected-report.json

@@ -0,0 +1,20 @@
+{
+  "totals": {
+    "error": 0,
+    "warning": 1,
+    "info": 0
+  },
+  "ruleIds": [
+    "MIG-PERMISSIONS-001"
+  ],
+  "needsReview": [
+    {
+      "line": 1,
+      "ruleId": "MIG-PERMISSIONS-001"
+    }
+  ],
+  "provenance": {
+    "literalRewrites": 6,
+    "actionMappings": []
+  }
+}

package/src/migrate/from-github/fixtures/syntax-mapping/07-job-control/expected.gitlab-ci.yml

@@ -0,0 +1,17 @@
+# Generated by chant migrate from input.yml
+
+stages:
+  - build
+workflow:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push"'
+
+flaky-test:
+  image: ubuntu:24.04
+  timeout: '10 minutes'
+  allow_failure: true
+  resource_group: deploy-$CI_COMMIT_REF_NAME
+  interruptible: true
+  script:
+    - make test
+  stage: build

package/src/migrate/from-github/fixtures/syntax-mapping/07-job-control/input.yml

@@ -0,0 +1,13 @@
+on: push
+jobs:
+  flaky-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    continue-on-error: true
+    concurrency:
+      group: deploy-${{ github.ref }}
+      cancel-in-progress: true
+    permissions:
+      contents: read
+    steps:
+      - run: make test

package/src/migrate/from-github/fixtures/syntax-mapping/08-workflow-name/expected-report.json

@@ -0,0 +1,13 @@
+{
+  "totals": {
+    "error": 0,
+    "warning": 0,
+    "info": 0
+  },
+  "ruleIds": [],
+  "needsReview": [],
+  "provenance": {
+    "literalRewrites": 3,
+    "actionMappings": []
+  }
+}

package/src/migrate/from-github/fixtures/syntax-mapping/08-workflow-name/expected.gitlab-ci.yml

@@ -0,0 +1,14 @@
+# Generated by chant migrate from input.yml
+
+stages:
+  - build
+workflow:
+  name: CI Pipeline
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push"'
+
+build:
+  image: ubuntu:24.04
+  script:
+    - make
+  stage: build

package/src/migrate/from-github/fixtures/syntax-mapping/08-workflow-name/input.yml

@@ -0,0 +1,7 @@
+name: CI Pipeline
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: make

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

@@ -0,0 +1,92 @@
+/**
+ * Fixture-driven migration tests.
+ *
+ * Each fixture directory under `fixtures/` contains:
+ *   - input.yml             (GitHub Actions workflow)
+ *   - expected.gitlab-ci.yml (expected GitLab CI output)
+ *   - expected-report.json  (expected diagnostic + provenance shape)
+ *
+ * The test asserts canonical-YAML equality on the output and shape
+ * equality on the report. Adding a new fixture requires no manifest
+ * edit — just drop the three files into a new directory.
+ */
+
+import { describe, test, expect } from "vitest";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parseYAML } from "@intentius/chant/yaml";
+import { transform } from "./index";
+
+const FIXTURE_ROOT = join(__dirname, "fixtures");
+
+interface Fixture { name: string; dir: string }
+
+function* walkFixtures(root: string, prefix = ""): Generator<Fixture> {
+  for (const entry of readdirSync(root)) {
+    const p = join(root, entry);
+    if (!statSync(p).isDirectory()) continue;
+    const name = prefix ? `${prefix}/${entry}` : entry;
+    const files = readdirSync(p);
+    if (files.includes("input.yml") && files.includes("expected.gitlab-ci.yml")) {
+      yield { name, dir: p };
+    } else {
+      yield* walkFixtures(p, name);
+    }
+  }
+}
+
+function canonicalYaml(text: string): unknown {
+  // Strip leading comments so the "Generated by chant migrate from ..."
+  // banner doesn't have to match byte-for-byte when sourceFile differs.
+  const stripped = text.replace(/^#[^\n]*\n+/g, "");
+  if (!stripped.trim()) return {};
+  return parseYAML(stripped);
+}
+
+interface ReportShape {
+  totals: { error: number; warning: number; info: number };
+  ruleIds: string[];
+  needsReview: Array<{ line: number; ruleId: string }>;
+  provenance: { literalRewrites: number; actionMappings: Array<{ action: string; tier: number | undefined }> };
+}
+
+function reportShape(diagnostics: Array<Record<string, unknown>>, provenance: Array<Record<string, unknown>>): ReportShape {
+  const totals = { error: 0, warning: 0, info: 0 };
+  for (const d of diagnostics) {
+    const sev = d.severity as string;
+    if (sev in totals) totals[sev as "error" | "warning" | "info"]++;
+  }
+  const ruleIds = Array.from(new Set(diagnostics.map((d) => d.ruleId as string))).sort();
+  const needsReview = diagnostics
+    .filter((d) => d.severity === "warning" || d.severity === "error")
+    .map((d) => ({ line: d.line as number, ruleId: d.ruleId as string }));
+  const literalRewrites = provenance.filter((p) => p.category === "literal" || p.category === "rewrite").length;
+  const actionMappings = provenance
+    .filter((p) => p.category === "action-map")
+    .map((p) => ({ action: p.actionRef as string, tier: p.mappingTier as number | undefined }));
+  return { totals, ruleIds, needsReview, provenance: { literalRewrites, actionMappings } };
+}
+
+describe("github → gitlab fixtures", () => {
+  for (const f of walkFixtures(FIXTURE_ROOT)) {
+    test(f.name, async () => {
+      const input = readFileSync(join(f.dir, "input.yml"), "utf-8");
+      const expectedYaml = readFileSync(join(f.dir, "expected.gitlab-ci.yml"), "utf-8");
+      const expectedReport: ReportShape = JSON.parse(
+        readFileSync(join(f.dir, "expected-report.json"), "utf-8"),
+      );
+
+      const result = await transform(input, { sourceFile: "input.yml" });
+
+      // Canonical YAML compare (parse + re-stringify absorbs whitespace/key order)
+      expect(canonicalYaml(result.output)).toEqual(canonicalYaml(expectedYaml));
+
+      // Shape compare
+      const actualShape = reportShape(
+        result.diagnostics as unknown as Array<Record<string, unknown>>,
+        result.provenance as unknown as Array<Record<string, unknown>>,
+      );
+      expect(actualShape).toEqual(expectedReport);
+    });
+  }
+});

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

@@ -0,0 +1,128 @@
+/**
+ * Public entry point for the GitHub Actions → GitLab CI migration tool.
+ *
+ * Lazy-imports `@intentius/chant-lexicon-github` so users who don't need
+ * migration don't pay the install cost (the github lexicon is an optional
+ * peer dependency of `@intentius/chant-lexicon-gitlab`).
+ */
+
+import type { TemplateIR } from "@intentius/chant/import/parser";
+import type { LintDiagnostic } from "@intentius/chant/lint/rule";
+import { ProvenanceAccumulator, type ProvenanceRecord } from "./provenance";
+import { transformIR } from "./transformer";
+import { emitGitlabYaml } from "./emit-yaml";
+import { provenanceToDiagnostics } from "./diagnostics";
+import { GitLabGenerator } from "../../import/generator";
+import { applyComposites } from "./composites/rewriter";
+import type { ActionMappingRegistry } from "./actions/registry";
+// Importing `./actions/index` triggers auto-registration of Tier 1
+// marketplace action mappings into the default registry. This is the
+// single chokepoint where the registry is wired up.
+import "./actions/index";
+
+export interface MigrateOptions {
+  /** Output format. */
+  emit?: "yaml" | "ts";
+  /** Enable composite-pattern recognition (Node patterns in v1). */
+  useComposites?: boolean;
+  /** Source file path for provenance (display only). */
+  sourceFile?: string;
+  /** Inject a custom action mapping registry for testing. */
+  registry?: ActionMappingRegistry;
+  /** Escalate needs-review diagnostics to errors. */
+  strict?: boolean;
+}
+
+export interface MigrationResult {
+  /** GitLab IR (consumed by `chant import`-style tools downstream). */
+  ir: TemplateIR;
+  /** Rendered output (YAML by default, TS when emit: "ts"). */
+  output: string;
+  /** Per-key provenance records. */
+  provenance: ProvenanceRecord[];
+  /** SARIF-shaped diagnostics derived from provenance. */
+  diagnostics: LintDiagnostic[];
+  /** Inferred stage list. */
+  stages: string[];
+}
+
+/**
+ * Migrate a GitHub Actions workflow YAML into GitLab CI.
+ *
+ * @param yamlContent raw .github/workflows/*.yml content
+ * @param opts        migration options
+ */
+export async function transform(
+  yamlContent: string,
+  opts: MigrateOptions = {},
+): Promise<MigrationResult> {
+  // Lazy-import the GitHub parser to keep the github lexicon dep optional.
+  let GitHubActionsParser: typeof import("@intentius/chant-lexicon-github/import/parser").GitHubActionsParser;
+  try {
+    ({ GitHubActionsParser } = await import("@intentius/chant-lexicon-github/import/parser"));
+  } catch {
+    throw new Error(
+      "chant migrate from github requires @intentius/chant-lexicon-github. " +
+        "Install it: npm install --save-dev @intentius/chant-lexicon-github",
+    );
+  }
+
+  const ghIR = new GitHubActionsParser().parse(yamlContent);
+  const provAcc = new ProvenanceAccumulator();
+  const transformed = await transformIR(ghIR, {
+    sourceFile: opts.sourceFile,
+    registry: opts.registry,
+    provenance: provAcc,
+  });
+  let { ir } = transformed;
+  const stages = transformed.stages;
+
+  // --use-composites: opt-in IR rewrite that turns recognised shapes
+  // (NodePipeline / NodeCI) into composite calls.
+  if (opts.useComposites) {
+    const r = applyComposites(ir);
+    ir = r.ir;
+    provAcc.pushAll(r.provenance);
+  }
+
+  let output: string;
+  if (opts.emit === "ts") {
+    const generator = new GitLabGenerator();
+    const files = generator.generate(ir);
+    // For single-file emit (default), concatenate. The migration banner
+    // + per-resource provenance comments are interleaved.
+    const banner = `// Migrated from ${opts.sourceFile ?? "(stdin)"} by chant migrate.
+// Source tool: github-actions. Edit freely — chant build will pick this up.\n\n`;
+    output = banner + files.map((f) => f.content).join("\n");
+    // Append NeedsReview TODOs at the bottom for visibility.
+    const todos = provAcc.byCategory("needs-review");
+    if (todos.length > 0) {
+      output += "\n// TODO(migration): items needing manual review:\n";
+      for (const t of todos) {
+        output += `//   - ${t.rule}: ${t.note ?? ""}\n`;
+      }
+    }
+  } else {
+    output = emitGitlabYaml(ir);
+  }
+
+  const provenance = provAcc.all();
+  const diagnostics = provenanceToDiagnostics(provenance, { strict: opts.strict });
+
+  return { ir, output, provenance, diagnostics, stages };
+}
+
+/**
+ * Lightweight detector: does this YAML look like a GitHub Actions workflow?
+ * Used by the plugin's `migrationSource("github")` extension.
+ */
+export function detectGitHubWorkflow(content: string): boolean {
+  // Cheap detection: top-level `jobs:` + `on:` or `runs-on:` appearing nested.
+  if (!/^\s*jobs\s*:/m.test(content)) return false;
+  return /^\s*on\s*:/m.test(content) || /^\s*runs-on\s*:/m.test(content);
+}
+
+export { ProvenanceAccumulator } from "./provenance";
+export type { ProvenanceRecord, ProvenanceCategory } from "./provenance";
+export type { ActionMapping, ActionMapCtx, ActionMappedResult, ActionMappingRegistry } from "./actions/registry";
+export { createRegistry, getDefaultRegistry, lookupAction } from "./actions/registry";

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

@@ -0,0 +1,68 @@
+/**
+ * Per-node provenance for GitHub Actions → GitLab CI migration.
+ *
+ * Returned as a side channel from `transform()` so the IR stays clean
+ * (re-usable by `chant import`) while still capturing per-key migration
+ * history for SARIF/Markdown reporting.
+ */
+
+export type ProvenanceCategory =
+  | "literal"        // direct YAML key rename (env → variables, runs-on → image)
+  | "rewrite"        // expression/identifier substitution (github.ref → $CI_COMMIT_REF_NAME)
+  | "synthesis"      // emitted GitLab construct with no GH original (inferred stage)
+  | "needs-review"   // could not translate; emitted comment + diagnostic
+  | "skipped"        // intentionally dropped
+  | "action-map";    // a marketplace action mapping fired
+
+export interface ProvenanceRecord {
+  /** Where this lives in the output (GitLab IR) — e.g. "jobs.test.script[2]" */
+  gitlabPath: string;
+  /** Resource logicalId in the GitLab IR, if applicable */
+  gitlabLogicalId?: string;
+  /** Source file name (for SARIF) */
+  sourceFile?: string;
+  /** 1-based source line (best effort) */
+  sourceLine?: number;
+  /** 1-based source column (best effort) */
+  sourceColumn?: number;
+  /** YAML path in the source (e.g. "jobs.test.steps[1].uses") */
+  sourceKey?: string;
+  /** What category of translation happened */
+  category: ProvenanceCategory;
+  /** Rule ID (e.g. "MIG-TRIGGER-001", "ACT-actions-checkout") */
+  rule: string;
+  /** Free-form explanation for human readers */
+  note?: string;
+  /** Original action reference (e.g. "actions/checkout@v4") for action-map records */
+  actionRef?: string;
+  /** Tier 1/2/3 for action-map records */
+  mappingTier?: 1 | 2 | 3;
+}
+
+/**
+ * Accumulator passed through the transformer pipeline so any step can
+ * append to the same provenance list without threading return values.
+ */
+export class ProvenanceAccumulator {
+  private records: ProvenanceRecord[] = [];
+
+  push(record: ProvenanceRecord): void {
+    this.records.push(record);
+  }
+
+  pushAll(records: ProvenanceRecord[]): void {
+    this.records.push(...records);
+  }
+
+  all(): ProvenanceRecord[] {
+    return [...this.records];
+  }
+
+  byCategory(category: ProvenanceCategory): ProvenanceRecord[] {
+    return this.records.filter((r) => r.category === category);
+  }
+
+  needsReviewCount(): number {
+    return this.records.filter((r) => r.category === "needs-review").length;
+  }
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Static LintRule metadata for SARIF enrichment.
+ *
+ * Each rule fired by the transformer (provenance.rule field) gets a
+ * corresponding entry here so SARIF output carries description + helpUri.
+ *
+ * These rules don't actually run a `check()` — the work has already been
+ * done by the transformer. They're metadata-only.
+ */
+
+import type { LintRule } from "@intentius/chant/lint/rule";
+
+const noopCheck = () => [];
+
+function rule(id: string, severity: "error" | "warning" | "info", description: string): LintRule {
+  return {
+    id,
+    severity,
+    category: "correctness",
+    description,
+    helpUri: `https://intentius.io/chant/lexicons/gitlab/migration#${id.toLowerCase()}`,
+    check: noopCheck,
+  };
+}
+
+export const MIGRATION_RULES: LintRule[] = [
+  // Trigger translations
+  rule("MIG-ON-PUSH", "info", "GitHub on: push → workflow.rules push"),
+  rule("MIG-ON-PR", "info", "GitHub on: pull_request → workflow.rules merge_request_event"),
+  rule("MIG-ON-SCHEDULE", "warning", "GitHub on: schedule requires GitLab CI/CD > Schedules UI configuration"),
+  rule("MIG-ON-DISPATCH", "warning", "GitHub on: workflow_dispatch inputs require spec:inputs (GitLab 17+) with defaults"),
+  rule("MIG-ON-NON-GIT", "warning", "GitHub event has no GitLab equivalent — GitLab pipelines run on git events only"),
+  rule("MIG-ON-UNKNOWN", "warning", "Unknown GitHub trigger event"),
+
+  // Job-level translations
+  rule("MIG-WORKFLOW-NAME", "info", "name → workflow.name"),
+  rule("MIG-WORKFLOW-ENV", "info", "Workflow env → top-level variables"),
+  rule("MIG-JOB-ENV", "info", "Job env → variables"),
+  rule("MIG-TIMEOUT", "info", "timeout-minutes → timeout"),
+  rule("MIG-ALLOW-FAILURE", "info", "continue-on-error → allow_failure"),
+  rule("MIG-NEEDS", "info", "needs: passthrough"),
+  rule("MIG-CONCURRENCY", "info", "concurrency.group/cancel-in-progress → resource_group/interruptible"),
+  rule("MIG-SERVICES", "info", "services: passthrough"),
+  rule("MIG-CONTAINER", "info", "container.image → image"),
+  rule("MIG-MATRIX", "info", "strategy.matrix → parallel.matrix"),
+
+  // runs-on
+  rule("MIG-RUNS-ON-001", "info", "runs-on: linux runner → Docker image"),
+  rule("MIG-RUNS-ON-NON-LINUX", "warning", "Non-Linux runs-on requires self-hosted runner with tag"),
+  rule("MIG-RUNS-ON-TAG", "info", "Custom runs-on label → tags:"),
+
+  // Expressions
+  rule("MIG-EXPR-CONTEXT", "info", "github.*/runner.*/job.* → predefined $CI_* variable"),
+  rule("MIG-EXPR-USERVAR", "info", "env.*/vars.*/secrets.*/inputs.*/matrix.* → $NAME"),
+  rule("MIG-EXPR-FUNCTION", "info", "Boolean function → when: clause"),
+  rule("MIG-EXPR-NO-EQUIV", "warning", "GitHub expression has no GitLab equivalent"),
+  rule("MIG-EXPR-UNKNOWN", "warning", "Could not translate expression"),
+
+  // Rule conversions
+  rule("MIG-IF-WHEN", "info", "if: boolean_function() → when:"),
+
+  // Permissions and outputs
+  rule("MIG-PERMISSIONS-001", "warning", "GitHub permissions: has no per-job equivalent — configure CI/CD token at project level"),
+  rule("MIG-JOB-OUTPUTS", "warning", "GitHub job outputs require artifacts:reports:dotenv pattern in GitLab"),
+  rule("MIG-NEEDS-OUTPUTS-001", "warning", "steps/needs outputs require artifacts:reports:dotenv pattern"),
+
+  // Matrix
+  rule("MIG-MATRIX-INCLUDE-001", "warning", "matrix.include/exclude has no direct GitLab equivalent"),
+  rule("MIG-FAIL-FAST", "warning", "strategy.fail-fast has no GitLab equivalent (default behaviour is non-fail-fast)"),
+
+  // Reusable workflow + step env
+  rule("MIG-REUSABLE-WORKFLOW", "warning", "GitHub reusable workflow → GitLab include: with variable substitution (no typed inputs)"),
+  rule("MIG-STEP-ENV-CONFLICT", "warning", "Step-level env var conflict; using last value"),
+
+  // Stage inference
+  rule("MIG-STAGE-TOPO", "info", "Stage assigned by needs: depth"),
+  rule("MIG-STAGE-HEURISTIC", "info", "Stage assigned by job name heuristic"),
+  rule("MIG-NEEDS-CYCLE-001", "warning", "needs: cycle detected; each cycle member in its own stage"),
+
+  // Action mapping fallback
+  rule("MIG-ACTION-UNKNOWN", "warning", "Marketplace action has no registered mapping"),
+];