@intentius/chant-lexicon-gitlab 0.1.12 → 0.1.14

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

@@ -0,0 +1,719 @@
+/**
+ * GitHub Actions → GitLab CI transformer.
+ *
+ * Takes a GitHub TemplateIR (produced by `GitHubActionsParser.parse`)
+ * and rewrites it into a GitLab TemplateIR (consumed by the existing
+ * `GitLabGenerator` for TS emit, or by `emit-yaml.ts` for direct YAML).
+ *
+ * Per-key provenance is collected in a side-channel `ProvenanceAccumulator`
+ * so the IR stays clean (re-usable by `chant import`).
+ */
+
+import type { TemplateIR, ResourceIR } from "@intentius/chant/import/parser";
+import type { ProvenanceAccumulator } from "./provenance";
+import { substituteExpressions, translateIfCondition } from "./expressions";
+import { inferStages, type GhJobSummary } from "./stages";
+import { lookupAction, type ActionMappingRegistry } from "./actions/registry";
+
+/**
+ * Apply expression substitution to a string that may contain `${{ ... }}`
+ * wrappers anywhere in its content. Used for property values like `image:`,
+ * `variables.*`, and service hostnames that flow through from GitHub source
+ * verbatim and need their embedded expressions translated.
+ *
+ * Returns the substituted string unchanged when no expressions are present.
+ */
+function substituteValueExpressions(
+  value: unknown,
+  gitlabPath: string,
+  sourceKey: string | undefined,
+  prov: ProvenanceAccumulator,
+  sourceFile?: string,
+): unknown {
+  if (typeof value !== "string") return value;
+  if (!value.includes("${{")) return value;
+  const r = substituteExpressions(value, { gitlabPath, sourceKey, sourceFile });
+  prov.pushAll(r.provenance);
+  return r.output;
+}
+
+export interface TransformOptions {
+  /** Source file path for provenance (best-effort, no parse) */
+  sourceFile?: string;
+  /** Optional registry override for testability */
+  registry?: ActionMappingRegistry;
+  /** Provenance accumulator to write to */
+  provenance: ProvenanceAccumulator;
+}
+
+/**
+ * Map GitHub `runs-on` value to a GitLab `image` (best effort).
+ * Self-hosted runners with extra labels map to `tags:`.
+ */
+function translateRunsOn(
+  runsOn: unknown,
+  ctx: { logicalId: string; jobName: string; sourceFile?: string },
+  prov: ProvenanceAccumulator,
+): { image?: string; tags?: string[] } {
+  if (typeof runsOn === "string") {
+    const map: Record<string, string> = {
+      "ubuntu-latest": "ubuntu:24.04",
+      "ubuntu-24.04": "ubuntu:24.04",
+      "ubuntu-22.04": "ubuntu:22.04",
+      "ubuntu-20.04": "ubuntu:20.04",
+    };
+    if (Object.prototype.hasOwnProperty.call(map, runsOn)) {
+      prov.push({
+        gitlabPath: `jobs.${ctx.logicalId}.image`,
+        gitlabLogicalId: ctx.logicalId,
+        sourceKey: `jobs.${ctx.jobName}.runs-on`,
+        sourceFile: ctx.sourceFile,
+        category: "literal",
+        rule: "MIG-RUNS-ON-001",
+        note: `runs-on: ${runsOn} → image: ${map[runsOn]}`,
+      });
+      return { image: map[runsOn] };
+    }
+    if (/^macos|^windows/.test(runsOn)) {
+      prov.push({
+        gitlabPath: `jobs.${ctx.logicalId}.image`,
+        gitlabLogicalId: ctx.logicalId,
+        sourceKey: `jobs.${ctx.jobName}.runs-on`,
+        sourceFile: ctx.sourceFile,
+        category: "needs-review",
+        rule: "MIG-RUNS-ON-NON-LINUX",
+        note: `runs-on: ${runsOn} has no direct GitLab image; configure a self-hosted runner with appropriate tag`,
+      });
+      return { tags: [runsOn] };
+    }
+    // Custom label → tags
+    prov.push({
+      gitlabPath: `jobs.${ctx.logicalId}.tags`,
+      gitlabLogicalId: ctx.logicalId,
+      sourceKey: `jobs.${ctx.jobName}.runs-on`,
+      sourceFile: ctx.sourceFile,
+      category: "literal",
+      rule: "MIG-RUNS-ON-TAG",
+      note: `runs-on: ${runsOn} → tags: [${runsOn}]`,
+    });
+    return { tags: [runsOn] };
+  }
+  if (Array.isArray(runsOn)) {
+    prov.push({
+      gitlabPath: `jobs.${ctx.logicalId}.tags`,
+      gitlabLogicalId: ctx.logicalId,
+      sourceKey: `jobs.${ctx.jobName}.runs-on`,
+      sourceFile: ctx.sourceFile,
+      category: "literal",
+      rule: "MIG-RUNS-ON-TAG",
+      note: `runs-on: [${runsOn.join(", ")}] → tags`,
+    });
+    return { tags: runsOn.map(String) };
+  }
+  return {};
+}
+
+/**
+ * Translate a GitHub `on:` trigger spec to GitLab `workflow.rules`.
+ */
+function translateOnTrigger(
+  on: unknown,
+  ctx: { sourceFile?: string },
+  prov: ProvenanceAccumulator,
+): unknown[] {
+  const rules: unknown[] = [];
+
+  const sources = typeof on === "string"
+    ? [on]
+    : Array.isArray(on)
+      ? on.map(String)
+      : on && typeof on === "object"
+        ? Object.keys(on as Record<string, unknown>)
+        : [];
+
+  for (const event of sources) {
+    switch (event) {
+      case "push":
+        rules.push({ if: '$CI_PIPELINE_SOURCE == "push"' });
+        prov.push({
+          gitlabPath: "workflow.rules",
+          sourceKey: "on.push",
+          sourceFile: ctx.sourceFile,
+          category: "literal",
+          rule: "MIG-ON-PUSH",
+          note: 'on: push → if: $CI_PIPELINE_SOURCE == "push"',
+        });
+        break;
+      case "pull_request":
+      case "pull_request_target":
+        rules.push({ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' });
+        prov.push({
+          gitlabPath: "workflow.rules",
+          sourceKey: `on.${event}`,
+          sourceFile: ctx.sourceFile,
+          category: "literal",
+          rule: "MIG-ON-PR",
+          note: `on: ${event} → if: $CI_PIPELINE_SOURCE == "merge_request_event"`,
+        });
+        break;
+      case "schedule":
+        rules.push({ if: '$CI_PIPELINE_SOURCE == "schedule"' });
+        prov.push({
+          gitlabPath: "workflow.rules",
+          sourceKey: "on.schedule",
+          sourceFile: ctx.sourceFile,
+          category: "needs-review",
+          rule: "MIG-ON-SCHEDULE",
+          note: "on: schedule → cron schedules must be configured in GitLab UI under CI/CD > Schedules",
+        });
+        break;
+      case "workflow_dispatch":
+        rules.push({ if: '$CI_PIPELINE_SOURCE == "web"' });
+        rules.push({ if: '$CI_PIPELINE_SOURCE == "api"' });
+        prov.push({
+          gitlabPath: "workflow.rules",
+          sourceKey: "on.workflow_dispatch",
+          sourceFile: ctx.sourceFile,
+          category: "needs-review",
+          rule: "MIG-ON-DISPATCH",
+          note: "on: workflow_dispatch → web/api triggers; inputs require spec:inputs (GitLab 17+) and per-input defaults",
+        });
+        break;
+      case "release":
+      case "issues":
+      case "issue_comment":
+      case "discussion":
+      case "label":
+        prov.push({
+          gitlabPath: "workflow.rules",
+          sourceKey: `on.${event}`,
+          sourceFile: ctx.sourceFile,
+          category: "needs-review",
+          rule: "MIG-ON-NON-GIT",
+          note: `on: ${event} has no GitLab equivalent — GitLab pipelines run only on git events. Consider gitlab-triage or webhooks.`,
+        });
+        break;
+      default:
+        prov.push({
+          gitlabPath: "workflow.rules",
+          sourceKey: `on.${event}`,
+          sourceFile: ctx.sourceFile,
+          category: "needs-review",
+          rule: "MIG-ON-UNKNOWN",
+          note: `on: ${event} not recognised; review manually`,
+        });
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Translate a step's env into job-level variables (merged later).
+ */
+function collectStepEnv(
+  steps: Array<Record<string, unknown>>,
+  ctx: { logicalId: string; jobName: string; sourceFile?: string },
+  prov: ProvenanceAccumulator,
+): Record<string, unknown> {
+  const variables: Record<string, unknown> = {};
+  for (const [i, step] of steps.entries()) {
+    if (step.env && typeof step.env === "object") {
+      for (const [k, v] of Object.entries(step.env as Record<string, unknown>)) {
+        if (k in variables && variables[k] !== v) {
+          prov.push({
+            gitlabPath: `jobs.${ctx.logicalId}.variables.${k}`,
+            gitlabLogicalId: ctx.logicalId,
+            sourceKey: `jobs.${ctx.jobName}.steps[${i}].env.${k}`,
+            sourceFile: ctx.sourceFile,
+            category: "needs-review",
+            rule: "MIG-STEP-ENV-CONFLICT",
+            note: `Step-level env var ${k} conflicts across steps; using last value`,
+          });
+        }
+        variables[k] = v;
+      }
+    }
+  }
+  return variables;
+}
+
+/**
+ * Translate a step's `run` block into script lines, applying expression
+ * substitution. Returns the produced script lines + provenance.
+ */
+function translateRunStep(
+  step: Record<string, unknown>,
+  i: number,
+  ctx: { logicalId: string; jobName: string; sourceFile?: string },
+  prov: ProvenanceAccumulator,
+): string[] {
+  const run = String(step.run ?? "");
+  // GitHub's `run:` supports multi-line shell. Split on newlines.
+  const lines = run.split(/\r?\n/).filter((l) => l.length > 0);
+  const out: string[] = [];
+  for (const [j, line] of lines.entries()) {
+    const subbed = substituteExpressions(line, {
+      gitlabPath: `jobs.${ctx.logicalId}.script[${out.length}]`,
+      sourceKey: `jobs.${ctx.jobName}.steps[${i}].run[${j}]`,
+      sourceFile: ctx.sourceFile,
+    });
+    prov.pushAll(subbed.provenance);
+    out.push(subbed.output);
+  }
+  return out;
+}
+
+/**
+ * Translate a single GH job ResourceIR into a GitLab Job ResourceIR.
+ */
+function translateJob(
+  ghJob: ResourceIR,
+  opts: TransformOptions,
+): { gitlabJob: ResourceIR; logicalId: string; needs: string[] } {
+  const prov = opts.provenance;
+  const logicalId = ghJob.logicalId;
+  const jobName = (ghJob.metadata?.originalName as string) ?? logicalId;
+  const props = ghJob.properties as Record<string, unknown>;
+  const gitlabProps: Record<string, unknown> = {};
+
+  // runs-on
+  if (props["runs-on"] !== undefined) {
+    const { image, tags } = translateRunsOn(props["runs-on"], { logicalId, jobName, sourceFile: opts.sourceFile }, prov);
+    if (image) {
+      gitlabProps.image = substituteValueExpressions(image, `jobs.${logicalId}.image`, `jobs.${jobName}.runs-on`, prov, opts.sourceFile);
+    }
+    if (tags) gitlabProps.tags = tags;
+  }
+
+  // env → variables (with embedded ${{ }} substitution on each value)
+  if (props.env && typeof props.env === "object") {
+    const rawEnv = props.env as Record<string, unknown>;
+    const substituted: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(rawEnv)) {
+      substituted[k] = substituteValueExpressions(
+        v,
+        `jobs.${logicalId}.variables.${k}`,
+        `jobs.${jobName}.env.${k}`,
+        prov,
+        opts.sourceFile,
+      );
+    }
+    gitlabProps.variables = substituted;
+    prov.push({
+      gitlabPath: `jobs.${logicalId}.variables`,
+      gitlabLogicalId: logicalId,
+      sourceKey: `jobs.${jobName}.env`,
+      sourceFile: opts.sourceFile,
+      category: "literal",
+      rule: "MIG-JOB-ENV",
+      note: "env: → variables:",
+    });
+  }
+
+  // timeout-minutes → timeout
+  if (props["timeout-minutes"] !== undefined) {
+    gitlabProps.timeout = `${props["timeout-minutes"]} minutes`;
+    prov.push({
+      gitlabPath: `jobs.${logicalId}.timeout`,
+      gitlabLogicalId: logicalId,
+      sourceKey: `jobs.${jobName}.timeout-minutes`,
+      sourceFile: opts.sourceFile,
+      category: "literal",
+      rule: "MIG-TIMEOUT",
+      note: `timeout-minutes → timeout`,
+    });
+  }
+
+  // continue-on-error → allow_failure
+  if (props["continue-on-error"] !== undefined) {
+    gitlabProps.allow_failure = props["continue-on-error"];
+    prov.push({
+      gitlabPath: `jobs.${logicalId}.allow_failure`,
+      gitlabLogicalId: logicalId,
+      sourceKey: `jobs.${jobName}.continue-on-error`,
+      sourceFile: opts.sourceFile,
+      category: "literal",
+      rule: "MIG-ALLOW-FAILURE",
+      note: "continue-on-error → allow_failure",
+    });
+  }
+
+  // if → rules
+  if (typeof props.if === "string") {
+    const { ifExpression, whenClause, provenance } = translateIfCondition(props.if, {
+      gitlabPath: `jobs.${logicalId}.rules[0]`,
+      sourceKey: `jobs.${jobName}.if`,
+      sourceFile: opts.sourceFile,
+    });
+    prov.pushAll(provenance);
+    const rule: Record<string, unknown> = {};
+    if (ifExpression) rule.if = ifExpression;
+    if (whenClause) rule.when = whenClause;
+    gitlabProps.rules = [rule];
+  }
+
+  // permissions — no per-job equivalent
+  if (props.permissions !== undefined) {
+    prov.push({
+      gitlabPath: `jobs.${logicalId}.permissions`,
+      gitlabLogicalId: logicalId,
+      sourceKey: `jobs.${jobName}.permissions`,
+      sourceFile: opts.sourceFile,
+      category: "needs-review",
+      rule: "MIG-PERMISSIONS-001",
+      note: "GitHub permissions: has no per-job GitLab equivalent. Configure CI/CD token access at the project level.",
+    });
+  }
+
+  // outputs — needs review (dotenv pattern)
+  if (props.outputs !== undefined) {
+    prov.push({
+      gitlabPath: `jobs.${logicalId}.artifacts.reports.dotenv`,
+      gitlabLogicalId: logicalId,
+      sourceKey: `jobs.${jobName}.outputs`,
+      sourceFile: opts.sourceFile,
+      category: "needs-review",
+      rule: "MIG-JOB-OUTPUTS",
+      note: "GitHub job outputs require the artifacts:reports:dotenv pattern in GitLab.",
+    });
+  }
+
+  // strategy.matrix → parallel.matrix
+  if (props.strategy && typeof props.strategy === "object") {
+    const strategy = props.strategy as Record<string, unknown>;
+    if (strategy.matrix && typeof strategy.matrix === "object") {
+      const matrix = strategy.matrix as Record<string, unknown>;
+      const parallel: Record<string, unknown> = {};
+      const matrixEntries: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(matrix)) {
+        if (k === "include" || k === "exclude") {
+          prov.push({
+            gitlabPath: `jobs.${logicalId}.parallel.matrix`,
+            gitlabLogicalId: logicalId,
+            sourceKey: `jobs.${jobName}.strategy.matrix.${k}`,
+            sourceFile: opts.sourceFile,
+            category: "needs-review",
+            rule: "MIG-MATRIX-INCLUDE-001",
+            note: `matrix.${k} has no direct GitLab equivalent; review manually`,
+          });
+          continue;
+        }
+        matrixEntries[k.toUpperCase()] = v;
+      }
+      if (Object.keys(matrixEntries).length > 0) {
+        parallel.matrix = [matrixEntries];
+        gitlabProps.parallel = parallel;
+        prov.push({
+          gitlabPath: `jobs.${logicalId}.parallel.matrix`,
+          gitlabLogicalId: logicalId,
+          sourceKey: `jobs.${jobName}.strategy.matrix`,
+          sourceFile: opts.sourceFile,
+          category: "literal",
+          rule: "MIG-MATRIX",
+          note: "strategy.matrix → parallel.matrix",
+        });
+      }
+    }
+    if (strategy["fail-fast"] === true) {
+      prov.push({
+        gitlabPath: `jobs.${logicalId}.parallel.matrix`,
+        gitlabLogicalId: logicalId,
+        sourceKey: `jobs.${jobName}.strategy.fail-fast`,
+        sourceFile: opts.sourceFile,
+        category: "needs-review",
+        rule: "MIG-FAIL-FAST",
+        note: "strategy.fail-fast: true has no GitLab equivalent (GitLab's default is non-fail-fast)",
+      });
+    }
+  }
+
+  // needs → needs (passthrough, kebab-case names preserved)
+  const needsArray: string[] = [];
+  if (props.needs !== undefined) {
+    const raw = props.needs;
+    const list = typeof raw === "string" ? [raw] : Array.isArray(raw) ? raw.map(String) : [];
+    needsArray.push(...list);
+    if (list.length > 0) {
+      gitlabProps.needs = list;
+      prov.push({
+        gitlabPath: `jobs.${logicalId}.needs`,
+        gitlabLogicalId: logicalId,
+        sourceKey: `jobs.${jobName}.needs`,
+        sourceFile: opts.sourceFile,
+        category: "literal",
+        rule: "MIG-NEEDS",
+        note: "needs: passthrough",
+      });
+    }
+  }
+
+  // concurrency.group → resource_group, cancel-in-progress → interruptible
+  if (props.concurrency !== undefined) {
+    const c = typeof props.concurrency === "object" && props.concurrency !== null
+      ? props.concurrency as Record<string, unknown>
+      : { group: String(props.concurrency) };
+    if (c.group) {
+      const subbed = substituteExpressions(String(c.group), {
+        gitlabPath: `jobs.${logicalId}.resource_group`,
+        sourceKey: `jobs.${jobName}.concurrency.group`,
+        sourceFile: opts.sourceFile,
+      });
+      prov.pushAll(subbed.provenance);
+      gitlabProps.resource_group = subbed.output;
+    }
+    if (c["cancel-in-progress"] === true) {
+      gitlabProps.interruptible = true;
+    }
+    prov.push({
+      gitlabPath: `jobs.${logicalId}.resource_group`,
+      gitlabLogicalId: logicalId,
+      sourceKey: `jobs.${jobName}.concurrency`,
+      sourceFile: opts.sourceFile,
+      category: "literal",
+      rule: "MIG-CONCURRENCY",
+      note: "concurrency.group → resource_group; cancel-in-progress → interruptible",
+    });
+  }
+
+  // services — pass through (shape is similar)
+  if (props.services !== undefined) {
+    gitlabProps.services = props.services;
+    prov.push({
+      gitlabPath: `jobs.${logicalId}.services`,
+      gitlabLogicalId: logicalId,
+      sourceKey: `jobs.${jobName}.services`,
+      sourceFile: opts.sourceFile,
+      category: "literal",
+      rule: "MIG-SERVICES",
+      note: "services: passthrough",
+    });
+  }
+
+  // container.image → image (overrides runs-on default)
+  if (props.container && typeof props.container === "object") {
+    const container = props.container as Record<string, unknown>;
+    if (container.image) {
+      gitlabProps.image = substituteValueExpressions(
+        container.image,
+        `jobs.${logicalId}.image`,
+        `jobs.${jobName}.container.image`,
+        prov,
+        opts.sourceFile,
+      );
+      prov.push({
+        gitlabPath: `jobs.${logicalId}.image`,
+        gitlabLogicalId: logicalId,
+        sourceKey: `jobs.${jobName}.container.image`,
+        sourceFile: opts.sourceFile,
+        category: "literal",
+        rule: "MIG-CONTAINER",
+        note: "container.image → image",
+      });
+    }
+  }
+
+  // steps → script
+  const script: string[] = [];
+  const beforeScript: string[] = [];
+  const stepEnv = collectStepEnv(Array.isArray(props.steps) ? props.steps as Array<Record<string, unknown>> : [], { logicalId, jobName, sourceFile: opts.sourceFile }, prov);
+  if (Object.keys(stepEnv).length > 0) {
+    const existing = (gitlabProps.variables as Record<string, unknown> | undefined) ?? {};
+    gitlabProps.variables = { ...existing, ...stepEnv };
+  }
+
+  if (Array.isArray(props.steps)) {
+    const stepsArr = props.steps as Array<Record<string, unknown>>;
+    for (const [i, step] of stepsArr.entries()) {
+      // run: shell command
+      if (typeof step.run === "string") {
+        const lines = translateRunStep(step, i, { logicalId, jobName, sourceFile: opts.sourceFile }, prov);
+        script.push(...lines);
+        continue;
+      }
+      // uses: marketplace action
+      if (typeof step.uses === "string") {
+        const action = lookupAction(step.uses, opts.registry);
+        if (action) {
+          const result = action.translate(step, {
+            logicalId,
+            jobName,
+            sourceFile: opts.sourceFile,
+            stepIndex: i,
+          });
+          script.push(...result.scriptLines);
+          if (result.beforeScript) beforeScript.push(...result.beforeScript);
+          if (result.image) {
+            // Action-mapping image values pass through user input like
+            // `node-version: ${{ matrix.node }}` verbatim from `with:`; run
+            // expression substitution so embedded ${{ ... }} doesn't leak
+            // into the output as a GitLab-side dead identifier.
+            gitlabProps.image = substituteValueExpressions(
+              result.image,
+              `jobs.${logicalId}.image`,
+              `jobs.${jobName}.steps[${i}].uses`,
+              prov,
+              opts.sourceFile,
+            );
+          }
+          if (result.services) gitlabProps.services = result.services;
+          if (result.cache) gitlabProps.cache = result.cache;
+          if (result.artifacts) gitlabProps.artifacts = result.artifacts;
+          if (result.variables) {
+            const existing = (gitlabProps.variables as Record<string, unknown> | undefined) ?? {};
+            const subbed: Record<string, unknown> = { ...existing };
+            for (const [k, v] of Object.entries(result.variables)) {
+              subbed[k] = substituteValueExpressions(
+                v,
+                `jobs.${logicalId}.variables.${k}`,
+                `jobs.${jobName}.steps[${i}].uses`,
+                prov,
+                opts.sourceFile,
+              );
+            }
+            gitlabProps.variables = subbed;
+          }
+          prov.pushAll(result.provenance);
+        } else {
+          script.push(`# TODO(migration): action "${step.uses}" not mapped — review manually`);
+          prov.push({
+            gitlabPath: `jobs.${logicalId}.script[${script.length - 1}]`,
+            gitlabLogicalId: logicalId,
+            sourceKey: `jobs.${jobName}.steps[${i}].uses`,
+            sourceFile: opts.sourceFile,
+            category: "needs-review",
+            rule: "MIG-ACTION-UNKNOWN",
+            note: `Marketplace action "${step.uses}" has no registered mapping; emitted TODO`,
+            actionRef: step.uses,
+          });
+        }
+      }
+    }
+  }
+  if (script.length > 0) gitlabProps.script = script;
+  if (beforeScript.length > 0) gitlabProps.before_script = beforeScript;
+
+  return { gitlabJob: { logicalId, type: "GitLab::CI::Job", properties: gitlabProps, metadata: { originalName: jobName } }, logicalId, needs: needsArray };
+}
+
+export async function transformIR(
+  ghIR: TemplateIR,
+  opts: TransformOptions,
+): Promise<{ ir: TemplateIR; stages: string[] }> {
+  const prov = opts.provenance;
+  const resources: ResourceIR[] = [];
+
+  // Extract workflow-level properties
+  const workflowResource = ghIR.resources.find((r) => r.type === "GitHub::Actions::Workflow");
+  if (workflowResource) {
+    const wf = workflowResource.properties;
+    const gitlabWorkflowProps: Record<string, unknown> = {};
+    if (wf.name) {
+      gitlabWorkflowProps.name = wf.name;
+      prov.push({
+        gitlabPath: "workflow.name",
+        sourceKey: "name",
+        sourceFile: opts.sourceFile,
+        category: "literal",
+        rule: "MIG-WORKFLOW-NAME",
+        note: "name → workflow.name",
+      });
+    }
+    if (wf.on !== undefined) {
+      const rules = translateOnTrigger(wf.on, { sourceFile: opts.sourceFile }, prov);
+      if (rules.length > 0) gitlabWorkflowProps.rules = rules;
+    }
+    if (Object.keys(gitlabWorkflowProps).length > 0) {
+      resources.push({
+        logicalId: "workflow",
+        type: "GitLab::CI::Workflow",
+        properties: gitlabWorkflowProps,
+      });
+    }
+    // Workflow-level env → top-level variables (handled via metadata)
+    if (wf.env && typeof wf.env === "object") {
+      prov.push({
+        gitlabPath: "variables",
+        sourceKey: "env",
+        sourceFile: opts.sourceFile,
+        category: "literal",
+        rule: "MIG-WORKFLOW-ENV",
+        note: "workflow env → top-level variables",
+      });
+    }
+    // Workflow-level permissions
+    if (wf.permissions !== undefined) {
+      prov.push({
+        gitlabPath: "(none)",
+        sourceKey: "permissions",
+        sourceFile: opts.sourceFile,
+        category: "needs-review",
+        rule: "MIG-PERMISSIONS-001",
+        note: "GitHub workflow-level permissions: configure CI/CD token access at the project level (no YAML equivalent).",
+      });
+    }
+  }
+
+  // Translate jobs
+  const ghJobs = ghIR.resources.filter(
+    (r) => r.type === "GitHub::Actions::Job" || r.type === "GitHub::Actions::ReusableWorkflowCallJob",
+  );
+  const translatedJobs: Array<ReturnType<typeof translateJob>> = [];
+  const jobSummaries: GhJobSummary[] = [];
+  for (const ghJob of ghJobs) {
+    if (ghJob.type === "GitHub::Actions::ReusableWorkflowCallJob") {
+      prov.push({
+        gitlabPath: `jobs.${ghJob.logicalId}`,
+        gitlabLogicalId: ghJob.logicalId,
+        sourceKey: `jobs.${(ghJob.metadata?.originalName as string) ?? ghJob.logicalId}.uses`,
+        sourceFile: opts.sourceFile,
+        category: "needs-review",
+        rule: "MIG-REUSABLE-WORKFLOW",
+        note: "GitHub reusable workflow `uses:` requires GitLab `include:` + variable substitution (no typed inputs/outputs)",
+      });
+      continue;
+    }
+    const translated = translateJob(ghJob, opts);
+    translatedJobs.push(translated);
+    jobSummaries.push({
+      logicalId: translated.logicalId,
+      originalName: (ghJob.metadata?.originalName as string) ?? translated.logicalId,
+      needs: translated.needs,
+    });
+  }
+
+  // Infer stages
+  const stageResult = inferStages(jobSummaries);
+  prov.pushAll(stageResult.provenance);
+
+  // Apply stage assignments
+  for (const tj of translatedJobs) {
+    const stage = stageResult.stageByJob.get(tj.logicalId);
+    if (stage) {
+      (tj.gitlabJob.properties as Record<string, unknown>).stage = stage;
+    }
+    resources.push(tj.gitlabJob);
+  }
+
+  // Workflow-level env collected into a top-level metadata.variables slot
+  const topLevelVars: Record<string, unknown> = {};
+  if (workflowResource && workflowResource.properties.env && typeof workflowResource.properties.env === "object") {
+    Object.assign(topLevelVars, workflowResource.properties.env);
+  }
+
+  const metadata: Record<string, unknown> = {
+    migration: {
+      sourceFile: opts.sourceFile ?? "(unknown)",
+      sourceTool: "github-actions",
+    },
+    stages: stageResult.stages,
+  };
+  if (Object.keys(topLevelVars).length > 0) {
+    metadata.variables = topLevelVars;
+  }
+
+  return {
+    ir: { resources, parameters: [], metadata },
+    stages: stageResult.stages,
+  };
+}