@intentius/chant-lexicon-gitlab 0.1.12 → 0.1.14

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

@@ -0,0 +1,99 @@
+import { describe, test, expect } from "vitest";
+import { inferStages, type GhJobSummary } from "./stages";
+
+function job(name: string, needs: string[] = [], id?: string): GhJobSummary {
+  return { logicalId: id ?? name, originalName: name, needs };
+}
+
+describe("inferStages", () => {
+  test("single job → build", () => {
+    const r = inferStages([job("build")]);
+    expect(r.stageByJob.get("build")).toBe("build");
+    expect(r.stages).toEqual(["build"]);
+  });
+
+  test("name heuristic: lint goes to lint stage", () => {
+    const r = inferStages([job("lint-check")]);
+    expect(r.stageByJob.get("lint-check")).toBe("lint");
+  });
+
+  test("name heuristic: deploy at depth 0 still maps to deploy", () => {
+    const r = inferStages([job("deploy-prod")]);
+    expect(r.stageByJob.get("deploy-prod")).toBe("deploy");
+  });
+
+  test("linear chain build → test → deploy", () => {
+    const r = inferStages([
+      job("build"),
+      job("test", ["build"]),
+      job("deploy", ["test"]),
+    ]);
+    expect(r.stageByJob.get("build")).toBe("build");
+    expect(r.stageByJob.get("test")).toBe("test");
+    expect(r.stageByJob.get("deploy")).toBe("deploy");
+    expect(r.stages).toEqual(["build", "test", "deploy"]);
+  });
+
+  test("diamond DAG", () => {
+    const r = inferStages([
+      job("setup"),
+      job("test-unit", ["setup"]),
+      job("test-int", ["setup"]),
+      job("ship", ["test-unit", "test-int"]),
+    ]);
+    expect(r.stageByJob.get("setup")).toBe("build");
+    expect(r.stageByJob.get("test-unit")).toBe("test");
+    expect(r.stageByJob.get("test-int")).toBe("test");
+    expect(r.stageByJob.get("ship")).toBe("deploy");
+  });
+
+  test("multiple roots", () => {
+    const r = inferStages([
+      job("build-a"),
+      job("build-b"),
+      job("test-a", ["build-a"]),
+      job("test-b", ["build-b"]),
+    ]);
+    expect(r.stageByJob.get("build-a")).toBe("build");
+    expect(r.stageByJob.get("build-b")).toBe("build");
+    expect(r.stageByJob.get("test-a")).toBe("test");
+    expect(r.stageByJob.get("test-b")).toBe("test");
+  });
+
+  test("cycle: each job in its own stage + needs-review", () => {
+    const r = inferStages([
+      job("a", ["b"]),
+      job("b", ["a"]),
+    ]);
+    expect(r.stageByJob.get("a")).toBe("cycle-a");
+    expect(r.stageByJob.get("b")).toBe("cycle-b");
+    expect(r.provenance.some((p) => p.rule === "MIG-NEEDS-CYCLE-001")).toBe(true);
+  });
+
+  test("post-N for depths beyond deploy", () => {
+    const r = inferStages([
+      job("a"),
+      job("b", ["a"]),
+      job("c", ["b"]),
+      job("d", ["c"]),
+      job("e", ["d"]),
+    ]);
+    expect(r.stageByJob.get("d")).toBe("post-1");
+    expect(r.stageByJob.get("e")).toBe("post-2");
+  });
+
+  test("stages sorted lint < build < test < deploy", () => {
+    const r = inferStages([
+      job("deploy"),
+      job("test", ["build"]),
+      job("build"),
+      job("lint"),
+    ]);
+    // lint and build are both at depth 0, deploy is at depth 0 too (no needs)
+    // The sort guarantees lint, build, deploy ordering for those at the same depth.
+    const indexOf = (s: string) => r.stages.indexOf(s);
+    expect(indexOf("lint")).toBeLessThan(indexOf("build"));
+    expect(indexOf("build")).toBeLessThan(indexOf("test"));
+    expect(indexOf("test")).toBeLessThan(indexOf("deploy"));
+  });
+});

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

@@ -0,0 +1,177 @@
+/**
+ * Stage inference for GitHub jobs → GitLab stages.
+ *
+ * GitHub Actions has no `stages:` concept; jobs only declare optional
+ * `needs:` edges. GitLab CI requires every job to belong to a stage.
+ *
+ * Approach (Kahn topological sort on the `needs:` DAG):
+ *   1. Build adjacency from `needs:` (jobs without `needs:` are depth 0).
+ *   2. Peel zero-indegree nodes; assign stage by depth + name heuristic.
+ *   3. Map depths to stage names:
+ *      depth 0 → "lint" / "build" (by name heuristic, default "build")
+ *      depth 1 → "test"
+ *      depth 2 → "deploy"
+ *      depth N>2 → `post-${N-2}`
+ *   4. If a cycle is detected, place each remaining job in its own stage
+ *      and append a needs-review record so the user notices.
+ */
+
+import type { ProvenanceRecord } from "./provenance";
+
+export interface GhJobSummary {
+  logicalId: string;
+  needs: string[];
+  /** Original GH job key (kebab-case) for name heuristics */
+  originalName: string;
+}
+
+export interface StageInferenceResult {
+  /** Map from job logicalId to assigned stage name */
+  stageByJob: Map<string, string>;
+  /** Ordered list of distinct stages, declaration-order */
+  stages: string[];
+  /** Any provenance records (cycles, synthesis events) */
+  provenance: ProvenanceRecord[];
+}
+
+const NAME_HEURISTIC_PATTERNS: Array<{ pattern: RegExp; stage: string }> = [
+  { pattern: /^(lint|check|fmt|format|style|typecheck|tsc)/i, stage: "lint" },
+  { pattern: /^(build|compile|bundle|pack)/i, stage: "build" },
+  { pattern: /^(test|spec|e2e|integration|unit)/i, stage: "test" },
+  { pattern: /^(deploy|publish|release|push)/i, stage: "deploy" },
+];
+
+function heuristicStage(name: string, fallback: string): string {
+  for (const { pattern, stage } of NAME_HEURISTIC_PATTERNS) {
+    if (pattern.test(name)) return stage;
+  }
+  return fallback;
+}
+
+function defaultStageForDepth(depth: number): string {
+  if (depth === 0) return "build";
+  if (depth === 1) return "test";
+  if (depth === 2) return "deploy";
+  return `post-${depth - 2}`;
+}
+
+export function inferStages(jobs: GhJobSummary[]): StageInferenceResult {
+  const provenance: ProvenanceRecord[] = [];
+  const stageByJob = new Map<string, string>();
+  const jobsById = new Map(jobs.map((j) => [j.logicalId, j]));
+
+  // Compute indegree based on needs that resolve to known jobs
+  const indegree = new Map<string, number>();
+  for (const job of jobs) {
+    indegree.set(job.logicalId, 0);
+  }
+  for (const job of jobs) {
+    for (const dep of job.needs) {
+      if (jobsById.has(dep)) {
+        indegree.set(job.logicalId, (indegree.get(job.logicalId) ?? 0) + 1);
+      }
+    }
+  }
+
+  // Kahn's algorithm, recording depth per node
+  const depth = new Map<string, number>();
+  const queue: string[] = [];
+  for (const job of jobs) {
+    if ((indegree.get(job.logicalId) ?? 0) === 0) {
+      queue.push(job.logicalId);
+      depth.set(job.logicalId, 0);
+    }
+  }
+
+  const processed = new Set<string>();
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    processed.add(current);
+    const currentDepth = depth.get(current) ?? 0;
+    for (const next of jobs) {
+      if (next.needs.includes(current)) {
+        const remaining = (indegree.get(next.logicalId) ?? 0) - 1;
+        indegree.set(next.logicalId, remaining);
+        const proposed = currentDepth + 1;
+        const existing = depth.get(next.logicalId);
+        if (existing === undefined || proposed > existing) {
+          depth.set(next.logicalId, proposed);
+        }
+        if (remaining === 0) {
+          queue.push(next.logicalId);
+        }
+      }
+    }
+  }
+
+  // Detect cycles — any job not processed is on a cycle
+  const cycleJobs = jobs.filter((j) => !processed.has(j.logicalId));
+  for (const job of cycleJobs) {
+    provenance.push({
+      gitlabPath: `jobs.${job.logicalId}.stage`,
+      gitlabLogicalId: job.logicalId,
+      sourceKey: `jobs.${job.originalName}.needs`,
+      category: "needs-review",
+      rule: "MIG-NEEDS-CYCLE-001",
+      note: `Job "${job.originalName}" is part of a needs: cycle; assigned its own stage`,
+    });
+  }
+
+  // Assign stages
+  for (const job of jobs) {
+    if (cycleJobs.includes(job)) {
+      stageByJob.set(job.logicalId, `cycle-${job.logicalId}`);
+      continue;
+    }
+    const d = depth.get(job.logicalId) ?? 0;
+    const defaultStage = defaultStageForDepth(d);
+    const stage = d === 0
+      ? heuristicStage(job.originalName, defaultStage)
+      : d === 1
+        ? heuristicStage(job.originalName, defaultStage)
+        : defaultStage;
+    stageByJob.set(job.logicalId, stage);
+    if (stage !== defaultStage) {
+      provenance.push({
+        gitlabPath: `jobs.${job.logicalId}.stage`,
+        gitlabLogicalId: job.logicalId,
+        sourceKey: `jobs.${job.originalName}`,
+        category: "synthesis",
+        rule: "MIG-STAGE-HEURISTIC",
+        note: `Stage "${stage}" inferred from job name "${job.originalName}"`,
+      });
+    } else {
+      provenance.push({
+        gitlabPath: `jobs.${job.logicalId}.stage`,
+        gitlabLogicalId: job.logicalId,
+        sourceKey: `jobs.${job.originalName}`,
+        category: "synthesis",
+        rule: "MIG-STAGE-TOPO",
+        note: `Stage "${stage}" assigned from needs: depth ${d}`,
+      });
+    }
+  }
+
+  // Collect distinct stages, ordered by appearance
+  const stagesSet = new Set<string>();
+  const stagesOrdered: string[] = [];
+  for (const job of jobs) {
+    const s = stageByJob.get(job.logicalId);
+    if (s && !stagesSet.has(s)) {
+      stagesSet.add(s);
+      stagesOrdered.push(s);
+    }
+  }
+  // Sort by canonical depth order: lint, build, test, deploy, post-N, cycle-*
+  const canonicalOrder = ["lint", "build", "test", "deploy"];
+  stagesOrdered.sort((a, b) => {
+    const ai = canonicalOrder.indexOf(a);
+    const bi = canonicalOrder.indexOf(b);
+    if (ai !== -1 && bi !== -1) return ai - bi;
+    if (ai !== -1) return -1;
+    if (bi !== -1) return 1;
+    return a.localeCompare(b);
+  });
+
+  return { stageByJob, stages: stagesOrdered, provenance };
+}

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

@@ -0,0 +1,278 @@
+import { describe, test, expect } from "vitest";
+import { transform, detectGitHubWorkflow } from "./index";
+
+describe("detectGitHubWorkflow", () => {
+  test("recognises a minimal GH workflow", () => {
+    const yml = `name: CI\non: push\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo hello\n`;
+    expect(detectGitHubWorkflow(yml)).toBe(true);
+  });
+
+  test("rejects unrelated YAML", () => {
+    const yml = `stages:\n  - build\nbuild-job:\n  script:\n    - make\n`;
+    expect(detectGitHubWorkflow(yml)).toBe(false);
+  });
+});
+
+describe("transform — minimal workflow", () => {
+  test("emits jobs at top level + stages", async () => {
+    const yml = `name: CI
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm ci
+      - run: npm run build
+  test:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - run: npm test
+`;
+    const result = await transform(yml, { sourceFile: "ci.yml" });
+    expect(result.output).toContain("stages:");
+    expect(result.output).toContain("build:");
+    expect(result.output).toContain("test:");
+    expect(result.output).toContain("- npm ci");
+    expect(result.output).toContain("- npm test");
+    expect(result.stages).toContain("build");
+    expect(result.stages).toContain("test");
+  });
+
+  test("workflow name → workflow.name", async () => {
+    const yml = `name: My CI
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: make
+`;
+    const result = await transform(yml);
+    expect(result.output).toMatch(/workflow:[\s\S]*name:/);
+  });
+
+  test("runs-on: ubuntu-latest → image: ubuntu:24.04", async () => {
+    const yml = `on: push
+jobs:
+  job1:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hi
+`;
+    const result = await transform(yml);
+    expect(result.output).toContain("ubuntu:24.04");
+  });
+
+  test("env at workflow + job level lands in variables", async () => {
+    const yml = `on: push
+env:
+  TOP: top-value
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      JOBVAR: job-value
+    steps:
+      - run: echo $TOP $JOBVAR
+`;
+    const result = await transform(yml);
+    expect(result.output).toContain("TOP");
+    expect(result.output).toContain("JOBVAR");
+  });
+
+  test("matrix → parallel.matrix", async () => {
+    const yml = `on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [18, 20, 22]
+        os: [ubuntu, windows]
+    steps:
+      - run: echo testing
+`;
+    const result = await transform(yml);
+    expect(result.output).toContain("parallel:");
+    expect(result.output).toContain("matrix:");
+    expect(result.output).toContain("NODE");
+    expect(result.output).toContain("OS");
+  });
+
+  test("timeout-minutes → timeout", async () => {
+    const yml = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - run: make
+`;
+    const result = await transform(yml);
+    expect(result.output).toMatch(/timeout:\s*'?30 minutes'?/);
+  });
+
+  test("continue-on-error → allow_failure", async () => {
+    const yml = `on: push
+jobs:
+  flaky:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - run: maybe-fail
+`;
+    const result = await transform(yml);
+    expect(result.output).toMatch(/allow_failure:\s*true/);
+  });
+
+  test("if: github.ref == 'refs/heads/main' translates", async () => {
+    const yml = `on: push
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - run: ./deploy.sh
+`;
+    const result = await transform(yml);
+    expect(result.output).toContain("$CI_COMMIT_REF_NAME");
+    expect(result.output).toContain("rules:");
+  });
+
+  test("permissions emits needs-review", async () => {
+    const yml = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - run: make
+`;
+    const result = await transform(yml);
+    expect(result.provenance.some((p) => p.rule === "MIG-PERMISSIONS-001")).toBe(true);
+  });
+
+  test("actions/checkout becomes a no-op skip (Tier 1 registry)", async () => {
+    const yml = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm test
+`;
+    const result = await transform(yml);
+    // With Tier 1 registry, actions/checkout is intentionally skipped
+    expect(result.provenance.some((p) => p.rule === "ACT-actions-checkout" && p.category === "skipped")).toBe(true);
+    // npm test still emitted
+    expect(result.output).toContain("- npm test");
+  });
+
+  test("unknown action emits MIG-ACTION-UNKNOWN", async () => {
+    const yml = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: some-org/never-mapped-action@v1
+      - run: echo done
+`;
+    const result = await transform(yml);
+    expect(result.provenance.some((p) => p.rule === "MIG-ACTION-UNKNOWN")).toBe(true);
+  });
+});
+
+describe("transform — provenance + diagnostics", () => {
+  test("clean translation emits no error diagnostics", async () => {
+    const yml = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm test
+`;
+    const result = await transform(yml);
+    const errors = result.diagnostics.filter((d) => d.severity === "error");
+    expect(errors).toHaveLength(0);
+  });
+
+  test("strict escalates needs-review to error", async () => {
+    const yml = `on: schedule
+jobs:
+  cron:
+    runs-on: ubuntu-latest
+    steps:
+      - run: ./run.sh
+`;
+    const result = await transform(yml, { strict: true });
+    const errors = result.diagnostics.filter((d) => d.severity === "error");
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  test("matrix-driven image substitutes to $NODE (not leaking ${{ }})", async () => {
+    const yml = `on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [18, 20, 22]
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: \${{ matrix.node }}
+      - run: npm test
+`;
+    const result = await transform(yml);
+    expect(result.output).toContain("image: node:$node");
+    expect(result.output).not.toContain("\${{ matrix.node }}");
+  });
+
+  test("env value with embedded ${{ secrets.X }} substitutes to $X", async () => {
+    const yml = `on: push
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      TOKEN: \${{ secrets.API_TOKEN }}
+    steps:
+      - run: ./deploy.sh
+`;
+    const result = await transform(yml);
+    // YAML emitter quotes strings starting with `$` as `'$API_TOKEN'`
+    expect(result.output).toMatch(/TOKEN:\s*'?\$API_TOKEN'?/);
+    expect(result.output).not.toContain("\${{ secrets.API_TOKEN }}");
+  });
+
+  test("container.image with embedded expression substitutes", async () => {
+    const yml = `on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    container:
+      image: my-registry/app:\${{ github.sha }}
+    steps:
+      - run: ./test.sh
+`;
+    const result = await transform(yml);
+    expect(result.output).toContain("my-registry/app:$CI_COMMIT_SHA");
+    expect(result.output).not.toContain("\${{ github.sha }}");
+  });
+
+  test("ir.metadata.migration is set", async () => {
+    const yml = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: make
+`;
+    const result = await transform(yml, { sourceFile: "ci.yml" });
+    expect(result.ir.metadata?.migration).toEqual({
+      sourceFile: "ci.yml",
+      sourceTool: "github-actions",
+    });
+  });
+});