@intentius/chant-lexicon-gitlab 0.1.12 → 0.1.14

package/src/migrate/from-github/composites/rewriter.ts

@@ -0,0 +1,29 @@
+/**
+ * `--use-composites` orchestrator: walks the registered patterns and
+ * applies the first match. Patterns are tried in declaration order
+ * (NodePipeline before NodeCI so the 2-job shape wins over the 1-job
+ * shape when both could match).
+ */
+
+import type { TemplateIR } from "@intentius/chant/import/parser";
+import type { ProvenanceRecord } from "../provenance";
+import { PATTERNS, type CompositePattern } from "./patterns";
+
+export function applyComposites(
+  ir: TemplateIR,
+  registry: CompositePattern[] = PATTERNS,
+): { ir: TemplateIR; provenance: ProvenanceRecord[] } {
+  const provenance: ProvenanceRecord[] = [];
+  let current = ir;
+  for (const pattern of registry) {
+    const match = pattern.match(current);
+    if (match) {
+      const result = pattern.rewrite(current, match);
+      current = result.ir;
+      provenance.push(...result.provenance);
+      // Only one composite rewrite per migrate run (keeps semantics simple)
+      break;
+    }
+  }
+  return { ir: current, provenance };
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Convert ProvenanceRecord[] into LintDiagnostic[] for SARIF output.
+ *
+ * Mapping:
+ *   - category "needs-review"   → severity "warning" (or "error" if --strict)
+ *   - category "skipped"        → severity "info"
+ *   - category "action-map" tier 3 → severity "warning"
+ *   - all others                → no diagnostic (clean translation)
+ */
+
+import type { LintDiagnostic } from "@intentius/chant/lint/rule";
+import type { ProvenanceRecord } from "./provenance";
+
+export interface DiagnosticOptions {
+  /** When true, needs-review records become errors instead of warnings */
+  strict?: boolean;
+}
+
+export function provenanceToDiagnostics(
+  records: ProvenanceRecord[],
+  opts: DiagnosticOptions = {},
+): LintDiagnostic[] {
+  const out: LintDiagnostic[] = [];
+  for (const r of records) {
+    let severity: "error" | "warning" | "info" | undefined;
+    if (r.category === "needs-review") {
+      severity = opts.strict ? "error" : "warning";
+    } else if (r.category === "skipped") {
+      severity = "info";
+    } else if (r.category === "action-map" && r.mappingTier === 3) {
+      severity = "warning";
+    } else {
+      continue;
+    }
+    out.push({
+      file: r.sourceFile ?? "<input>",
+      line: r.sourceLine ?? 1,
+      column: r.sourceColumn ?? 1,
+      ruleId: r.rule,
+      severity,
+      message: r.note ?? r.rule,
+    });
+  }
+  return out;
+}

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

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "vitest";
+import { transform } from "./index";
+
+describe("transform --emit ts", () => {
+  test("produces TS source importing from @intentius/chant-lexicon-gitlab", async () => {
+    const yml = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm ci
+      - run: npm run build
+`;
+    const result = await transform(yml, { emit: "ts", sourceFile: "ci.yml" });
+    expect(result.output).toContain('from "@intentius/chant-lexicon-gitlab"');
+    expect(result.output).toContain("new Job(");
+    expect(result.output).toContain("Migrated from ci.yml");
+  });
+
+  test("emits TODO footer for NeedsReview items", async () => {
+    const yml = `on: schedule
+jobs:
+  cron:
+    runs-on: ubuntu-latest
+    steps:
+      - run: ./run.sh
+`;
+    const result = await transform(yml, { emit: "ts", sourceFile: "ci.yml" });
+    expect(result.output).toContain("TODO(migration)");
+    expect(result.output).toContain("MIG-ON-SCHEDULE");
+  });
+
+  test("yaml and ts emit modes produce equivalent IR (same jobs)", async () => {
+    const yml = `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    needs: []
+    steps:
+      - run: make
+`;
+    const yamlResult = await transform(yml, { emit: "yaml" });
+    const tsResult = await transform(yml, { emit: "ts" });
+    // Same IR underneath; output strings differ.
+    expect(yamlResult.ir.resources.map((r) => r.logicalId)).toEqual(
+      tsResult.ir.resources.map((r) => r.logicalId),
+    );
+  });
+});

package/src/migrate/from-github/emit-yaml.ts

@@ -0,0 +1,128 @@
+/**
+ * Direct GitLab TemplateIR → `.gitlab-ci.yml` text emission.
+ *
+ * We deliberately bypass the existing `gitlabSerializer.serialize()` because
+ * that path consumes `Map<string, Declarable>` (entity instances built by
+ * user TS code), not a raw IR. Going through entity instances would require
+ * runtime construction of typed objects we don't have. Direct emission is
+ * ~60 LOC.
+ */
+
+import type { TemplateIR } from "@intentius/chant/import/parser";
+import { emitYAML } from "@intentius/chant/yaml";
+
+const RESERVED_TOP_LEVEL_ORDER = [
+  "spec",
+  "include",
+  "default",
+  "stages",
+  "variables",
+  "workflow",
+  "image",
+  "services",
+  "before_script",
+  "after_script",
+  "cache",
+  "pages",
+];
+
+function isReservedTopLevelKey(key: string): boolean {
+  return RESERVED_TOP_LEVEL_ORDER.includes(key);
+}
+
+function emitKeyValue(key: string, value: unknown, indent: number): string {
+  const prefix = "  ".repeat(indent);
+  if (value === null || value === undefined) return `${prefix}${key}: null`;
+  if (typeof value === "boolean" || typeof value === "number") return `${prefix}${key}: ${value}`;
+  if (typeof value === "string") return `${prefix}${key}: ${emitYAML(value, indent + 1)}`;
+  if (Array.isArray(value)) {
+    if (value.length === 0) return `${prefix}${key}: []`;
+    return `${prefix}${key}:${emitYAML(value, indent + 1)}`;
+  }
+  if (typeof value === "object") {
+    if (Object.keys(value).length === 0) return `${prefix}${key}: {}`;
+    return `${prefix}${key}:${emitYAML(value, indent + 1)}`;
+  }
+  return `${prefix}${key}: ${String(value)}`;
+}
+
+function emitBlock(obj: Record<string, unknown>, indent: number): string {
+  return Object.entries(obj)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => emitKeyValue(k, v, indent))
+    .join("\n");
+}
+
+/**
+ * Convert a GitLab `TemplateIR` (produced by the GH→GL transformer) into
+ * `.gitlab-ci.yml` text.
+ */
+export function emitGitlabYaml(ir: TemplateIR): string {
+  const top: Record<string, unknown> = {};
+
+  // Stages from metadata
+  const meta = (ir.metadata ?? {}) as Record<string, unknown>;
+  if (Array.isArray(meta.stages) && meta.stages.length > 0) {
+    top.stages = meta.stages;
+  }
+
+  // Top-level variables from metadata.variables
+  if (meta.variables && typeof meta.variables === "object" && Object.keys(meta.variables).length > 0) {
+    top.variables = meta.variables;
+  }
+
+  // Workflow / Default / Include resources go into reserved top-level keys
+  for (const r of ir.resources) {
+    if (r.type === "GitLab::CI::Workflow") {
+      top.workflow = r.properties;
+    } else if (r.type === "GitLab::CI::Default") {
+      top.default = r.properties;
+    } else if (r.type === "GitLab::CI::Include") {
+      top.include = r.properties;
+    }
+  }
+
+  // Job resources go at the top level keyed by logicalId (kebab-cased)
+  const jobs: Record<string, unknown> = {};
+  for (const r of ir.resources) {
+    if (r.type === "GitLab::CI::Job") {
+      const key = (r.metadata?.originalName as string) ?? r.logicalId;
+      if (isReservedTopLevelKey(key)) {
+        // Avoid colliding with reserved keywords; prefix
+        jobs[`job-${key}`] = r.properties;
+      } else {
+        jobs[key] = r.properties;
+      }
+    }
+  }
+
+  // Emit ordered top-level keys (reserved first, then jobs)
+  const lines: string[] = [];
+
+  for (const key of RESERVED_TOP_LEVEL_ORDER) {
+    if (top[key] !== undefined) {
+      lines.push(emitKeyValue(key, top[key], 0));
+    }
+  }
+
+  // Migration banner comment
+  if (meta.migration && typeof meta.migration === "object") {
+    const m = meta.migration as Record<string, unknown>;
+    if (lines.length === 0) {
+      lines.push(`# Generated by chant migrate from ${m.sourceFile ?? "(unknown)"}`);
+      lines.push("");
+    } else {
+      lines.unshift("");
+      lines.unshift(`# Generated by chant migrate from ${m.sourceFile ?? "(unknown)"}`);
+    }
+  }
+
+  // Jobs (sorted by logicalId for determinism)
+  const jobKeys = Object.keys(jobs).sort();
+  for (const key of jobKeys) {
+    lines.push("");
+    lines.push(emitKeyValue(key, jobs[key], 0));
+  }
+
+  return lines.join("\n") + "\n";
+}

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

@@ -0,0 +1,124 @@
+import { describe, test, expect } from "vitest";
+import { substituteExpressions, translateIfCondition, translateIfFunction } from "./expressions";
+
+describe("substituteExpressions — context vars", () => {
+  const ctx = { gitlabPath: "x", sourceKey: "y" };
+
+  test.each([
+    ["${{ github.sha }}", "$CI_COMMIT_SHA"],
+    ["${{ github.ref }}", "$CI_COMMIT_REF_NAME"],
+    ["${{ github.ref_name }}", "$CI_COMMIT_REF_NAME"],
+    ["${{ github.repository }}", "$CI_PROJECT_PATH"],
+    ["${{ github.repository_owner }}", "$CI_PROJECT_NAMESPACE"],
+    ["${{ github.actor }}", "$GITLAB_USER_LOGIN"],
+    ["${{ github.event_name }}", "$CI_PIPELINE_SOURCE"],
+    ["${{ github.run_id }}", "$CI_PIPELINE_ID"],
+    ["${{ github.run_number }}", "$CI_PIPELINE_IID"],
+    ["${{ github.job }}", "$CI_JOB_NAME"],
+    ["${{ github.head_ref }}", "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"],
+    ["${{ github.base_ref }}", "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"],
+    ["${{ github.workspace }}", "$CI_PROJECT_DIR"],
+    ["${{ runner.workspace }}", "$CI_PROJECT_DIR"],
+    ["${{ job.status }}", "$CI_JOB_STATUS"],
+    ["${{ strategy.job-index }}", "$CI_NODE_INDEX"],
+    ["${{ strategy.job-total }}", "$CI_NODE_TOTAL"],
+  ])("%s → %s", (input, expected) => {
+    expect(substituteExpressions(input, ctx).output).toBe(expected);
+  });
+});
+
+describe("substituteExpressions — user-defined vars", () => {
+  const ctx = { gitlabPath: "x", sourceKey: "y" };
+
+  test("env.NAME → $NAME", () => {
+    expect(substituteExpressions("${{ env.NODE_VERSION }}", ctx).output).toBe("$NODE_VERSION");
+  });
+
+  test("vars.NAME → $NAME", () => {
+    expect(substituteExpressions("${{ vars.REGISTRY }}", ctx).output).toBe("$REGISTRY");
+  });
+
+  test("secrets.NAME → $NAME", () => {
+    expect(substituteExpressions("${{ secrets.API_TOKEN }}", ctx).output).toBe("$API_TOKEN");
+  });
+
+  test("inputs.NAME → $NAME", () => {
+    expect(substituteExpressions("${{ inputs.environment }}", ctx).output).toBe("$environment");
+  });
+
+  test("matrix.NAME → $NAME", () => {
+    expect(substituteExpressions("${{ matrix.os }}", ctx).output).toBe("$os");
+  });
+
+  test("multiple substitutions in one string", () => {
+    expect(
+      substituteExpressions("Deploying ${{ env.APP }} to ${{ vars.ENV }}", ctx).output,
+    ).toBe("Deploying $APP to $ENV");
+  });
+});
+
+describe("substituteExpressions — needs-review", () => {
+  const ctx = { gitlabPath: "x", sourceKey: "y" };
+
+  test("steps.<id>.outputs.<name> → $name + needs-review", () => {
+    const { output, provenance } = substituteExpressions("${{ steps.get-version.outputs.tag }}", ctx);
+    expect(output).toBe("$tag");
+    expect(provenance.some((p) => p.category === "needs-review")).toBe(true);
+  });
+
+  test("needs.<job>.outputs.<name> → $name + needs-review", () => {
+    const { output, provenance } = substituteExpressions("${{ needs.build.outputs.version }}", ctx);
+    expect(output).toBe("$version");
+    expect(provenance.some((p) => p.rule === "MIG-NEEDS-OUTPUTS-001")).toBe(true);
+  });
+
+  test("runner.os has no equivalent", () => {
+    const { provenance } = substituteExpressions("${{ runner.os }}", ctx);
+    expect(provenance.some((p) => p.rule === "MIG-EXPR-NO-EQUIV")).toBe(true);
+  });
+
+  test("github.run_attempt has no equivalent", () => {
+    const { provenance } = substituteExpressions("${{ github.run_attempt }}", ctx);
+    expect(provenance.some((p) => p.rule === "MIG-EXPR-NO-EQUIV")).toBe(true);
+  });
+});
+
+describe("translateIfFunction", () => {
+  test("always()", () => {
+    expect(translateIfFunction("always()").whenClause).toBe("always");
+  });
+  test("success()", () => {
+    expect(translateIfFunction("success()").whenClause).toBe("on_success");
+  });
+  test("failure()", () => {
+    expect(translateIfFunction("failure()").whenClause).toBe("on_failure");
+  });
+  test("cancelled() flagged for review", () => {
+    expect(translateIfFunction("cancelled()").needsReview).toBe(true);
+  });
+});
+
+describe("translateIfCondition", () => {
+  const ctx = { gitlabPath: "rules", sourceKey: "if" };
+
+  test("simple branch comparison", () => {
+    const { ifExpression } = translateIfCondition("github.ref == 'refs/heads/main'", ctx);
+    expect(ifExpression).toContain("$CI_COMMIT_REF_NAME");
+  });
+
+  test("boolean function alone → when:", () => {
+    const r = translateIfCondition("failure()", ctx);
+    expect(r.whenClause).toBe("on_failure");
+    expect(r.ifExpression).toBe("");
+  });
+
+  test("retains operators", () => {
+    const { ifExpression } = translateIfCondition(
+      "github.event_name == 'push' && github.ref == 'refs/heads/main'",
+      ctx,
+    );
+    expect(ifExpression).toContain("$CI_PIPELINE_SOURCE");
+    expect(ifExpression).toContain("$CI_COMMIT_REF_NAME");
+    expect(ifExpression).toContain("&&");
+  });
+});

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

@@ -0,0 +1,302 @@
+/**
+ * GitHub Actions expression substitution.
+ *
+ * Translates `${{ github.X }}`, `${{ runner.X }}`, `${{ secrets.X }}`,
+ * `${{ env.X }}`, `${{ vars.X }}`, `${{ inputs.X }}`, `${{ matrix.X }}`,
+ * and a small set of expression functions (`always()`, `failure()`, etc.)
+ * to their GitLab CI predefined-variable equivalents.
+ *
+ * Source: the upstream `github-actions-to-gitlab-ci` skill's
+ * `references/syntax-mapping.md` "github.* context expressions" tables.
+ */
+
+import type { ProvenanceRecord } from "./provenance";
+
+/**
+ * Direct 1:1 mappings from GitHub context identifiers to GitLab predefined
+ * variables. Keys are the dotted identifier *without* the `${{ }}` wrapper.
+ */
+const GITHUB_CONTEXT_MAP: Record<string, string> = {
+  "github.sha": "$CI_COMMIT_SHA",
+  "github.ref": "$CI_COMMIT_REF_NAME",
+  "github.ref_name": "$CI_COMMIT_REF_NAME",
+  "github.repository": "$CI_PROJECT_PATH",
+  "github.repository_owner": "$CI_PROJECT_NAMESPACE",
+  "github.actor": "$GITLAB_USER_LOGIN",
+  "github.triggering_actor": "$GITLAB_USER_LOGIN",
+  "github.event_name": "$CI_PIPELINE_SOURCE",
+  "github.workflow": "$CI_PIPELINE_NAME",
+  "github.run_id": "$CI_PIPELINE_ID",
+  "github.run_number": "$CI_PIPELINE_IID",
+  "github.job": "$CI_JOB_NAME",
+  "github.head_ref": "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME",
+  "github.base_ref": "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME",
+  "github.workspace": "$CI_PROJECT_DIR",
+  "github.server_url": "$CI_SERVER_URL",
+  "runner.workspace": "$CI_PROJECT_DIR",
+  "job.status": "$CI_JOB_STATUS",
+  "strategy.job-index": "$CI_NODE_INDEX",
+  "strategy.job-total": "$CI_NODE_TOTAL",
+};
+
+/**
+ * GitHub expressions with no GitLab equivalent. When detected, the
+ * substitution leaves a placeholder and registers a needs-review record.
+ */
+const NO_EQUIVALENT = new Set<string>([
+  "github.run_attempt",
+  "runner.os",
+  "runner.arch",
+  "runner.temp",
+  "job.container.id",
+]);
+
+/**
+ * Map a GitHub `if:` boolean function to a GitLab `when:` value or rule.
+ *
+ * Returned tuple is `[gitlabExpression, isWhenClause]` — when `isWhenClause`
+ * is true, the caller should emit `when: <expr>` rather than `if: <expr>`.
+ */
+export function translateIfFunction(
+  expr: string,
+): { expression: string; whenClause?: string; needsReview?: boolean } {
+  const trimmed = expr.trim();
+  if (trimmed === "always()") return { expression: "true", whenClause: "always" };
+  if (trimmed === "success()") return { expression: "true", whenClause: "on_success" };
+  if (trimmed === "failure()") return { expression: "true", whenClause: "on_failure" };
+  if (trimmed === "cancelled()" || trimmed === "canceled()") {
+    return { expression: "true", needsReview: true };
+  }
+  return { expression: trimmed };
+}
+
+/**
+ * Substitute all `${{ ... }}` template expressions in a string with their
+ * GitLab equivalents. Returns the substituted string plus any provenance
+ * records describing which substitutions happened (or which need review).
+ */
+export function substituteExpressions(
+  input: string,
+  ctx: { gitlabPath: string; sourceKey?: string; sourceFile?: string },
+): { output: string; provenance: ProvenanceRecord[] } {
+  const records: ProvenanceRecord[] = [];
+  // GitHub expressions are wrapped in ${{ ... }}.
+  const output = input.replace(/\$\{\{\s*([^}]+?)\s*\}\}/g, (match, expr: string) => {
+    const trimmed = expr.trim();
+
+    // Direct context lookup
+    if (Object.prototype.hasOwnProperty.call(GITHUB_CONTEXT_MAP, trimmed)) {
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "rewrite",
+        rule: "MIG-EXPR-CONTEXT",
+        note: `${trimmed} → ${GITHUB_CONTEXT_MAP[trimmed]}`,
+      });
+      return GITHUB_CONTEXT_MAP[trimmed];
+    }
+
+    // env.NAME / vars.NAME / secrets.NAME → $NAME
+    const userVarMatch = /^(env|vars|secrets|inputs|matrix)\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(trimmed);
+    if (userVarMatch) {
+      const [, , name] = userVarMatch;
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "rewrite",
+        rule: "MIG-EXPR-USERVAR",
+        note: `${trimmed} → $${name}`,
+      });
+      return `$${name}`;
+    }
+
+    // steps.<id>.outputs.<name> → $name with needs-review note (requires dotenv)
+    const stepsOutputMatch = /^steps\.([A-Za-z_][A-Za-z0-9_-]*)\.outputs\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(trimmed);
+    if (stepsOutputMatch) {
+      const [, , name] = stepsOutputMatch;
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "needs-review",
+        rule: "MIG-NEEDS-OUTPUTS-001",
+        note: `${trimmed} requires artifacts:reports:dotenv pattern in GitLab; emitting $${name} placeholder`,
+      });
+      return `$${name}`;
+    }
+
+    // needs.<job>.outputs.<name> → $name with needs-review note
+    const needsOutputMatch = /^needs\.([A-Za-z_][A-Za-z0-9_-]*)\.outputs\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(trimmed);
+    if (needsOutputMatch) {
+      const [, , name] = needsOutputMatch;
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "needs-review",
+        rule: "MIG-NEEDS-OUTPUTS-001",
+        note: `${trimmed} requires artifacts:reports:dotenv pattern in GitLab; emitting $${name} placeholder`,
+      });
+      return `$${name}`;
+    }
+
+    // Boolean expression functions: always(), success(), failure(), cancelled()
+    const fnResult = translateIfFunction(trimmed);
+    if (fnResult.whenClause) {
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "rewrite",
+        rule: "MIG-EXPR-FUNCTION",
+        note: `${trimmed} → when: ${fnResult.whenClause}`,
+      });
+      return fnResult.expression;
+    }
+
+    // No-equivalent context expressions
+    if (NO_EQUIVALENT.has(trimmed)) {
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "needs-review",
+        rule: "MIG-EXPR-NO-EQUIV",
+        note: `${trimmed} has no GitLab predefined variable equivalent`,
+      });
+      return `# TODO: ${trimmed} has no GitLab equivalent`;
+    }
+
+    // Unknown expression — leave the original and flag
+    records.push({
+      gitlabPath: ctx.gitlabPath,
+      sourceKey: ctx.sourceKey,
+      sourceFile: ctx.sourceFile,
+      category: "needs-review",
+      rule: "MIG-EXPR-UNKNOWN",
+      note: `Could not translate expression: ${match}`,
+    });
+    return match;
+  });
+
+  return { output, provenance: records };
+}
+
+/**
+ * Substitute GitHub identifiers (e.g. `github.ref`) appearing anywhere
+ * in a string with their GitLab predefined-variable equivalents.
+ * Used for if-conditions, concurrency.group values, and other places
+ * where identifiers appear without `${{ }}` wrapping.
+ */
+export function substituteIdentifiers(
+  input: string,
+  ctx: { gitlabPath: string; sourceKey?: string; sourceFile?: string },
+): { output: string; provenance: ProvenanceRecord[] } {
+  const records: ProvenanceRecord[] = [];
+  // Match dotted identifiers like `github.ref_name`, `runner.os`,
+  // `steps.foo.outputs.bar`, `env.NAME`, etc. — but not when they are
+  // already prefixed by `$` (already substituted).
+  const output = input.replace(/(?<![\w$])([a-z]+(?:\.[A-Za-z_][A-Za-z0-9_-]*)+)/g, (match: string) => {
+    if (Object.prototype.hasOwnProperty.call(GITHUB_CONTEXT_MAP, match)) {
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "rewrite",
+        rule: "MIG-EXPR-CONTEXT",
+        note: `${match} → ${GITHUB_CONTEXT_MAP[match]}`,
+      });
+      return GITHUB_CONTEXT_MAP[match];
+    }
+    const userVar = /^(env|vars|secrets|inputs|matrix)\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(match);
+    if (userVar) {
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "rewrite",
+        rule: "MIG-EXPR-USERVAR",
+        note: `${match} → $${userVar[2]}`,
+      });
+      return `$${userVar[2]}`;
+    }
+    const stepsOutput = /^steps\.[A-Za-z_][A-Za-z0-9_-]*\.outputs\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(match);
+    if (stepsOutput) {
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "needs-review",
+        rule: "MIG-NEEDS-OUTPUTS-001",
+        note: `${match} requires artifacts:reports:dotenv pattern; emitting $${stepsOutput[1]} placeholder`,
+      });
+      return `$${stepsOutput[1]}`;
+    }
+    const needsOutput = /^needs\.[A-Za-z_][A-Za-z0-9_-]*\.outputs\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(match);
+    if (needsOutput) {
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "needs-review",
+        rule: "MIG-NEEDS-OUTPUTS-001",
+        note: `${match} requires artifacts:reports:dotenv pattern; emitting $${needsOutput[1]} placeholder`,
+      });
+      return `$${needsOutput[1]}`;
+    }
+    if (NO_EQUIVALENT.has(match)) {
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "needs-review",
+        rule: "MIG-EXPR-NO-EQUIV",
+        note: `${match} has no GitLab predefined variable equivalent`,
+      });
+      return match;
+    }
+    return match;
+  });
+  return { output, provenance: records };
+}
+
+/**
+ * Translate a GitHub `if:` condition expression (without `${{ }}` wrapping)
+ * into a GitLab `rules:if:` expression. Returns substituted expression and
+ * any whenClause hint extracted from boolean function calls.
+ */
+export function translateIfCondition(
+  rawIf: string,
+  ctx: { gitlabPath: string; sourceKey?: string; sourceFile?: string },
+): { ifExpression: string; whenClause?: string; provenance: ProvenanceRecord[] } {
+  const records: ProvenanceRecord[] = [];
+  let whenClause: string | undefined;
+
+  // If the whole expression is a single boolean function, translate to when:
+  const fnAlone = /^\s*([a-z]+\(\))\s*$/i.exec(rawIf);
+  if (fnAlone) {
+    const fnResult = translateIfFunction(fnAlone[1]);
+    if (fnResult.whenClause) {
+      records.push({
+        gitlabPath: ctx.gitlabPath,
+        sourceKey: ctx.sourceKey,
+        sourceFile: ctx.sourceFile,
+        category: "rewrite",
+        rule: "MIG-IF-WHEN",
+        note: `if: ${fnAlone[1]} → when: ${fnResult.whenClause}`,
+      });
+      whenClause = fnResult.whenClause;
+      return { ifExpression: "", whenClause, provenance: records };
+    }
+  }
+
+  // Strip any `${{ }}` wrappers first
+  const unwrapped = rawIf.replace(/\$\{\{\s*/g, "").replace(/\s*\}\}/g, "");
+  // Then substitute identifiers inline
+  const subbed = substituteIdentifiers(unwrapped, ctx);
+  records.push(...subbed.provenance);
+
+  return { ifExpression: subbed.output, whenClause, provenance: records };
+}