@intentius/chant-lexicon-gitlab 0.124.30 → 0.124.32

package/dist/migrate/from-github/expressions.js

@@ -0,0 +1,275 @@
+/**
+ * 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.
+ */
+/**
+ * Direct 1:1 mappings from GitHub context identifiers to GitLab predefined
+ * variables. Keys are the dotted identifier *without* the `${{ }}` wrapper.
+ */
+const GITHUB_CONTEXT_MAP = {
+    "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([
+    "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) {
+    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, ctx) {
+    const records = [];
+    // GitHub expressions are wrapped in ${{ ... }}.
+    const output = input.replace(/\$\{\{\s*([^}]+?)\s*\}\}/g, (match, expr) => {
+        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, ctx) {
+    const records = [];
+    // 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) => {
+        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, ctx) {
+    const records = [];
+    let whenClause;
+    // 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 };
+}

package/dist/migrate/from-github/index.js

@@ -0,0 +1,96 @@
+/**
+ * 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 { ProvenanceAccumulator } from "./provenance.js";
+import { transformIR } from "./transformer.js";
+import { emitGitlabYaml } from "./emit-yaml.js";
+import { provenanceToDiagnostics } from "./diagnostics.js";
+import { analyzeSecurity, runSecurityChecks, renderSecurityPosture } from "./security.js";
+import { GitLabGenerator } from "../../import/generator.js";
+import { applyComposites } from "./composites/rewriter.js";
+// 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.js";
+/**
+ * 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, opts = {}) {
+    // Lazy-import the GitHub parser to keep the github lexicon dep optional.
+    let 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;
+    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);
+    }
+    // Security-aware migration (#306): classify each security property's fate
+    // across the edge, and run the GitLab security post-synth checks against the
+    // migrated YAML so weaknesses lost in translation surface on the target side.
+    if (opts.security) {
+        const yamlForSecurity = opts.emit === "ts" ? emitGitlabYaml(ir) : output;
+        provAcc.pushAll(analyzeSecurity(yamlContent, { sourceFile: opts.sourceFile }));
+        provAcc.pushAll(await runSecurityChecks(yamlForSecurity, { sourceFile: opts.sourceFile }));
+    }
+    const provenance = provAcc.all();
+    const diagnostics = provenanceToDiagnostics(provenance, { strict: opts.strict });
+    const securityPosture = renderSecurityPosture(provenance);
+    return { ir, output, provenance, diagnostics, stages, securityPosture };
+}
+/**
+ * Lightweight detector: does this YAML look like a GitHub Actions workflow?
+ * Used by the plugin's `migrationSource("github")` extension.
+ */
+export function detectGitHubWorkflow(content) {
+    // 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.js";
+export { createRegistry, getDefaultRegistry, lookupAction } from "./actions/registry.js";

package/dist/migrate/from-github/provenance.js

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+/**
+ * Accumulator passed through the transformer pipeline so any step can
+ * append to the same provenance list without threading return values.
+ */
+export class ProvenanceAccumulator {
+    constructor() {
+        this.records = [];
+    }
+    push(record) {
+        this.records.push(record);
+    }
+    pushAll(records) {
+        this.records.push(...records);
+    }
+    all() {
+        return [...this.records];
+    }
+    byCategory(category) {
+        return this.records.filter((r) => r.category === category);
+    }
+    needsReviewCount() {
+        return this.records.filter((r) => r.category === "needs-review").length;
+    }
+    /** Records carrying a security classification. */
+    securityRecords() {
+        return this.records.filter((r) => r.security !== undefined);
+    }
+}

package/dist/migrate/from-github/rules.js

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+const noopCheck = () => [];
+function rule(id, severity, description) {
+    return {
+        id,
+        severity,
+        category: "correctness",
+        description,
+        helpUri: `https://intentius.io/chant/lexicons/gitlab/migration#${id.toLowerCase()}`,
+        check: noopCheck,
+    };
+}
+export const MIGRATION_RULES = [
+    // 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"),
+    // ── Security posture across the migration edge (#306) ──────────────────
+    // Each cross-references the endpoint issue that re-establishes the property.
+    rule("MIG-PIN-LOST", "warning", "A pinned action SHA could not be carried to the GitLab include/image — re-pin on the GitLab side (#297)"),
+    rule("MIG-SECRET-UNSCOPED", "warning", "Migrated secret reference assumes a masked + protected GitLab variable (#300)"),
+    rule("MIG-INJECTION-CARRIED", "warning", "An untrusted-input injection site was translated verbatim across the edge (#299)"),
+    rule("MIG-TRUST-BOUNDARY", "warning", "Trigger/fork semantics shifted the trust boundary (pull_request_target → MR/fork pipeline) (#299)"),
+];

package/dist/migrate/from-github/security.js

@@ -0,0 +1,189 @@
+/**
+ * Security-aware migration (#306).
+ *
+ * Migration is the edge between the two security endpoints (#296 ↔ #305).
+ * Security properties don't translate 1:1 — some are silently preserved, some
+ * lost, some need re-establishing on the GitLab side. This module classifies
+ * each security-relevant property's fate as it crosses the boundary and runs
+ * the GitLab security post-synth checks against the migrated output so anything
+ * lost in translation is caught on the target side.
+ */
+const UNTRUSTED_CONTEXTS = [
+    "github.event.issue.title",
+    "github.event.issue.body",
+    "github.event.pull_request.title",
+    "github.event.pull_request.body",
+    "github.event.pull_request.head.ref",
+    "github.event.comment.body",
+    "github.event.review.body",
+    "github.event.head_commit.message",
+    "github.head_ref",
+];
+const SHA_PINNED_USES = /uses:\s*['"]?([\w.-]+\/[\w.-]+(?:\/[\w.-]+)*)@([0-9a-f]{40})['"]?/g;
+const SECRET_REF = /\$\{\{\s*secrets\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+/**
+ * Classify the fate of security-relevant properties as they migrate from a
+ * GitHub Actions workflow to GitLab CI. Returns provenance records carrying a
+ * `security` classification (which flow into diagnostics, SARIF, and the report
+ * like any other provenance record).
+ */
+export function analyzeSecurity(sourceYaml, opts = {}) {
+    const records = [];
+    const file = opts.sourceFile;
+    // MIG-PIN-LOST — a GitHub SHA pin has no meaning once the action maps to a
+    // GitLab include/image (or becomes a hand-written script). Re-pin on GitLab.
+    const seenPins = new Set();
+    let m;
+    SHA_PINNED_USES.lastIndex = 0;
+    while ((m = SHA_PINNED_USES.exec(sourceYaml)) !== null) {
+        const slug = m[1];
+        if (seenPins.has(slug))
+            continue;
+        seenPins.add(slug);
+        records.push({
+            gitlabPath: "(target)",
+            sourceKey: `uses: ${slug}`,
+            sourceFile: file,
+            category: "synthesis",
+            rule: "MIG-PIN-LOST",
+            note: `The SHA pin on "${slug}" does not carry to its GitLab include/image — re-pin the GitLab target to a tag or digest (WGL029/WGL031).`,
+            security: { property: "Pinned action SHA", fate: "lost", severity: "warning", reestablish: "#297" },
+        });
+    }
+    // MIG-SECRET-UNSCOPED — ${{ secrets.X }} → $X, but masking/protection is set
+    // outside the YAML; the reference assumes a masked + protected variable.
+    const seenSecrets = new Set();
+    SECRET_REF.lastIndex = 0;
+    while ((m = SECRET_REF.exec(sourceYaml)) !== null) {
+        const name = m[1];
+        if (seenSecrets.has(name))
+            continue;
+        seenSecrets.add(name);
+        records.push({
+            gitlabPath: "(target)",
+            sourceKey: `secrets.${name}`,
+            sourceFile: file,
+            category: "needs-review",
+            rule: "MIG-SECRET-UNSCOPED",
+            note: `secrets.${name} → $${name}, which assumes a masked + protected GitLab CI/CD variable. Mark it masked and protected (WGL038).`,
+            security: { property: "Secret reference", fate: "needs-review", severity: "warning", reestablish: "#300" },
+        });
+    }
+    // MIG-INJECTION-CARRIED — an untrusted-context interpolation translates
+    // verbatim, carrying the injection straight across.
+    const seenInjection = new Set();
+    for (const ctx of UNTRUSTED_CONTEXTS) {
+        if (sourceYaml.includes(ctx) && !seenInjection.has(ctx)) {
+            seenInjection.add(ctx);
+            records.push({
+                gitlabPath: "(target)",
+                sourceKey: ctx,
+                sourceFile: file,
+                category: "needs-review",
+                rule: "MIG-INJECTION-CARRIED",
+                note: `Untrusted input \${{ ${ctx} }} translates to a $CI_* reference verbatim — the script-injection risk carries across (WGL035).`,
+                security: { property: "Template injection site", fate: "translated", severity: "warning", reestablish: "#299" },
+            });
+        }
+    }
+    // MIG-TRUST-BOUNDARY — pull_request_target maps to merge-request pipelines,
+    // which fork contributors can trigger; the trust boundary shifts.
+    if (/pull_request_target/.test(sourceYaml)) {
+        records.push({
+            gitlabPath: "(target)",
+            sourceKey: "on.pull_request_target",
+            sourceFile: file,
+            category: "needs-review",
+            rule: "MIG-TRUST-BOUNDARY",
+            note: `pull_request_target → merge-request pipelines, which fork contributors can trigger. Re-establish the trust boundary (protected refs, approvals) on GitLab (WGL034/WGL036).`,
+            security: { property: "Trigger trust boundary", fate: "needs-review", severity: "warning", reestablish: "#299" },
+        });
+    }
+    // MIG-PERMISSIONS-001 (reframed as least-privilege) — permissions: has no
+    // per-job GitLab YAML equivalent; least privilege lives in project settings.
+    if (/^permissions:/m.test(sourceYaml) || /^\s+permissions:/m.test(sourceYaml)) {
+        records.push({
+            gitlabPath: "(target)",
+            sourceKey: "permissions",
+            sourceFile: file,
+            category: "needs-review",
+            rule: "MIG-PERMISSIONS-001",
+            note: `Least-privilege permissions: have no per-job GitLab YAML equivalent — re-establish via project CI/CD token settings and id_tokens scoping (WGL033).`,
+            security: { property: "Least-privilege permissions", fate: "needs-review", severity: "warning", reestablish: "#298" },
+        });
+    }
+    return records;
+}
+/**
+ * Run the GitLab security post-synth checks against the migrated `.gitlab-ci.yml`
+ * and return their findings as provenance records — *migrate, then prove the
+ * output clears the GitLab security bar*. Anything lost in translation that
+ * lands as a concrete weakness on the target is caught here.
+ */
+export async function runSecurityChecks(gitlabYaml, opts = {}) {
+    const { gitlabPlugin } = await import("../../plugin.js");
+    const checks = gitlabPlugin.postSynthChecks?.() ?? [];
+    const ctx = {
+        outputs: new Map([["gitlab", gitlabYaml]]),
+        entities: new Map(),
+        buildResult: {
+            outputs: new Map([["gitlab", gitlabYaml]]),
+            entities: new Map(),
+            warnings: [],
+            errors: [],
+            sourceFileCount: 1,
+        },
+    };
+    const records = [];
+    for (const check of checks) {
+        let diags;
+        try {
+            diags = check.check(ctx);
+        }
+        catch {
+            continue; // a check that needs entities/other context simply yields nothing here
+        }
+        for (const d of diags) {
+            records.push({
+                gitlabPath: "(target)",
+                sourceKey: d.entity ?? d.checkId,
+                sourceFile: opts.sourceFile,
+                category: "synthesis",
+                rule: d.checkId,
+                note: `Migrated output triggers ${d.checkId}: ${d.message}`,
+                security: {
+                    property: "GitLab security check",
+                    fate: "needs-review",
+                    severity: d.severity === "error" ? "error" : d.severity === "info" ? "info" : "warning",
+                },
+            });
+        }
+    }
+    return records;
+}
+/**
+ * Render a "Security posture" Markdown section from the security provenance
+ * records (those carrying a `security` classification).
+ */
+export function renderSecurityPosture(records) {
+    const security = records.filter((r) => r.security);
+    if (security.length === 0) {
+        return "## Security posture\n\nNo security-relevant properties detected at the migration edge.\n";
+    }
+    const byRule = new Map();
+    for (const r of security) {
+        const s = r.security;
+        const existing = byRule.get(r.rule);
+        if (existing)
+            existing.count += 1;
+        else
+            byRule.set(r.rule, { property: s.property, fate: s.fate, rule: r.rule, count: 1 });
+    }
+    let out = "## Security posture\n\n";
+    out += "| Property | Fate | Rule | Count |\n|---|---|---|---|\n";
+    for (const line of byRule.values()) {
+        out += `| ${line.property} | ${line.fate} | ${line.rule} | ${line.count} |\n`;
+    }
+    out += "\nFates: **translated** (weakness carried as-is) · **approximated** · **needs-review** (re-establish on GitLab) · **lost** (no GitLab equivalent for the property).\n";
+    return out;
+}