@intentius/chant-lexicon-gitlab 0.124.31 → 0.124.33

package/dist/lint/rules/data/known-include-sources.js

@@ -0,0 +1,44 @@
+/**
+ * Vendored snapshot of well-known GitLab CI include/component source projects,
+ * used by the look-alike check (WGL032) as the reference set: an `include` or
+ * `component` source that is a near-miss (edit distance 1–2) of one of these —
+ * but not an exact match — is likely a typo or an impersonation.
+ *
+ * Advisory only. Refresh source: GitLab-maintained CI templates and the popular
+ * CI/CD Catalog components. Accept staleness — a stale entry only weakens
+ * look-alike detection, it never blocks a build.
+ */
+export const KNOWN_INCLUDE_SOURCES = [
+    "gitlab-org/gitlab",
+    "gitlab-org/security-products/ci-templates",
+    "components/sast",
+    "components/secret-detection",
+    "components/dependency-scanning",
+    "components/container-scanning",
+    "components/code-quality",
+    "gitlab-org/components/sast",
+    "gitlab-org/components/secret-detection",
+];
+/** Levenshtein edit distance, capped: returns early once it exceeds `max`. */
+export function editDistance(a, b, max) {
+    if (a === b)
+        return 0;
+    if (Math.abs(a.length - b.length) > max)
+        return max + 1;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const curr = [i];
+        let rowMin = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const val = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+            curr.push(val);
+            if (val < rowMin)
+                rowMin = val;
+        }
+        if (rowMin > max)
+            return max + 1;
+        prev = curr;
+    }
+    return prev[b.length];
+}

package/dist/lint/rules/data/untrusted-variables.js

@@ -0,0 +1,30 @@
+/**
+ * Vendored snapshot of GitLab CI predefined variables whose values are
+ * attacker-controllable — branch/tag names, commit and merge-request titles and
+ * descriptions, author identity. Interpolating these into a `script:` (or using
+ * them as a gate) lets a crafted branch name or commit title influence what runs.
+ *
+ * Source: GitLab "Predefined CI/CD variables" reference, filtered to the values
+ * an outside contributor can set on a fork or merge request. Advisory and
+ * necessarily incomplete; editing this list is the refresh mechanism.
+ */
+export const UNTRUSTED_CI_VARIABLES = [
+    "CI_COMMIT_TITLE",
+    "CI_COMMIT_MESSAGE",
+    "CI_COMMIT_DESCRIPTION",
+    "CI_COMMIT_REF_NAME",
+    "CI_COMMIT_REF_SLUG",
+    "CI_COMMIT_BRANCH",
+    "CI_COMMIT_TAG",
+    "CI_COMMIT_AUTHOR",
+    "CI_MERGE_REQUEST_TITLE",
+    "CI_MERGE_REQUEST_DESCRIPTION",
+    "CI_MERGE_REQUEST_SOURCE_BRANCH_NAME",
+    "CI_MERGE_REQUEST_SOURCE_BRANCH_SHA",
+    "CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME",
+];
+/** Reference forms a variable can take in a script: `$VAR` or `${VAR}`. */
+export function variableReferenced(text, name) {
+    const re = new RegExp(`\\$\\{?${name}\\}?(?![A-Z0-9_])`);
+    return re.test(text);
+}

package/dist/lint/rules/deprecated-only-except.js

@@ -0,0 +1,46 @@
+/**
+ * WGL001: Deprecated only/except keywords
+ *
+ * Flags usage of `only:` and `except:` in GitLab CI jobs.
+ * These keywords are deprecated in favor of `rules:` which provides
+ * more flexible conditional execution.
+ */
+import { ts } from "@intentius/chant/lint/typescript";
+export const deprecatedOnlyExceptRule = {
+    id: "WGL001",
+    severity: "warning",
+    category: "style",
+    check(context) {
+        const { sourceFile } = context;
+        const diagnostics = [];
+        function visit(node) {
+            // Look for property assignments named "only" or "except"
+            // inside new Job(...) or similar constructor calls
+            if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name)) {
+                const propName = node.name.text;
+                if (propName === "only" || propName === "except") {
+                    // Check if this is inside a new expression (Job constructor)
+                    let parent = node.parent;
+                    while (parent) {
+                        if (ts.isNewExpression(parent)) {
+                            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                            diagnostics.push({
+                                file: sourceFile.fileName,
+                                line: line + 1,
+                                column: character + 1,
+                                ruleId: "WGL001",
+                                severity: "warning",
+                                message: `"${propName}" is deprecated. Use "rules" for conditional job execution instead.`,
+                            });
+                            break;
+                        }
+                        parent = parent.parent;
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/import-source.js

@@ -0,0 +1,61 @@
+/**
+ * Shared helper for gitlab lint rules that match a bare TypeScript
+ * identifier (`Job`, ...) and need to know whether it actually came from
+ * this lexicon before flagging it (chant #1544 — cross-lexicon rule bleed:
+ * `new Job(...)` matches ANY lexicon's `Job` class by name alone, so a
+ * multi-lexicon project got gitlab-only rules applied to github/forgejo
+ * jobs that were never missing anything).
+ */
+import { ts } from "@intentius/chant/lint/typescript";
+/**
+ * The module specifier a top-level import bound `name` to, whether via a
+ * named import (`import { Job } from "..."`, matched on its local —
+ * possibly aliased — binding) or a namespace import (`import * as gl from
+ * "..."`, matched on the namespace's own name). Undefined when `name` isn't
+ * bound by any top-level import in this file (no import at all, a
+ * re-export chain, a dynamic `require`, …) — the caller should treat that
+ * as "can't tell", not "not gitlab", to stay conservative for the common
+ * single-lexicon-project case (and every pre-#1544 unit test fixture, which
+ * has no import statements at all).
+ */
+export function importSourceFor(sourceFile, name) {
+    for (const stmt of sourceFile.statements) {
+        if (!ts.isImportDeclaration(stmt))
+            continue;
+        const moduleSpecifier = stmt.moduleSpecifier;
+        if (!ts.isStringLiteral(moduleSpecifier))
+            continue;
+        const namedBindings = stmt.importClause?.namedBindings;
+        if (!namedBindings)
+            continue;
+        if (ts.isNamespaceImport(namedBindings)) {
+            if (namedBindings.name.text === name)
+                return moduleSpecifier.text;
+        }
+        else if (ts.isNamedImports(namedBindings)) {
+            for (const element of namedBindings.elements) {
+                if (element.name.text === name)
+                    return moduleSpecifier.text;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * True when `expression` (a `new`-expression callee) resolves — via a
+ * traced import — to a lexicon OTHER than gitlab. False for an unresolved
+ * import (conservative: still checked) or one that does resolve to gitlab.
+ */
+export function isJobFromAnotherLexicon(sourceFile, expression) {
+    let bindingName;
+    if (ts.isIdentifier(expression)) {
+        bindingName = expression.text;
+    }
+    else if (ts.isPropertyAccessExpression(expression)) {
+        bindingName = ts.isIdentifier(expression.expression) ? expression.expression.text : undefined;
+    }
+    if (!bindingName)
+        return false;
+    const source = importSourceFor(sourceFile, bindingName);
+    return source !== undefined && !source.includes("chant-lexicon-gitlab");
+}

package/dist/lint/rules/index.js

@@ -0,0 +1,7 @@
+/**
+ * GitLab CI/CD lint rules
+ */
+export { deprecatedOnlyExceptRule } from "./deprecated-only-except.js";
+export { missingScriptRule } from "./missing-script.js";
+export { missingStageRule } from "./missing-stage.js";
+export { artifactNoExpiryRule } from "./artifact-no-expiry.js";

package/dist/lint/rules/missing-script.js

@@ -0,0 +1,67 @@
+/**
+ * WGL002: Missing script
+ *
+ * A GitLab CI job must have `script`, `trigger`, or `run` defined.
+ * Jobs without any of these will fail pipeline validation.
+ */
+import { ts } from "@intentius/chant/lint/typescript";
+import { isJobFromAnotherLexicon } from "./import-source.js";
+const VALID_EXECUTION_PROPS = new Set(["script", "trigger", "run"]);
+export const missingScriptRule = {
+    id: "WGL002",
+    severity: "error",
+    category: "correctness",
+    check(context) {
+        const { sourceFile } = context;
+        const diagnostics = [];
+        function visit(node) {
+            if (ts.isNewExpression(node)) {
+                // Check for `new Job(...)` or `new gl.Job(...)`
+                let isJob = false;
+                const expression = node.expression;
+                if (ts.isIdentifier(expression) && expression.text === "Job") {
+                    isJob = true;
+                }
+                else if (ts.isPropertyAccessExpression(expression) && expression.name.text === "Job") {
+                    isJob = true;
+                }
+                // chant #1544 — cross-lexicon rule bleed: `new Job(...)` matches
+                // ANY lexicon's `Job` class by bare name alone (github's, forgejo's,
+                // ...), so a multi-lexicon project got WGL002 (gitlab-only) applied
+                // to github/forgejo jobs that were never missing anything — they
+                // just don't use `script`/`trigger`/`run`. Skip when the import
+                // resolves to a lexicon other than gitlab; an unresolved import
+                // (no `import` statement — most unit-test fixtures, a re-export) is
+                // "can't tell", so it keeps the previous, conservative behavior.
+                if (isJob && isJobFromAnotherLexicon(sourceFile, expression)) {
+                    isJob = false;
+                }
+                if (isJob && node.arguments && node.arguments.length > 0) {
+                    const props = node.arguments[0];
+                    if (ts.isObjectLiteralExpression(props)) {
+                        const hasExecution = props.properties.some((prop) => {
+                            if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                                return VALID_EXECUTION_PROPS.has(prop.name.text);
+                            }
+                            return false;
+                        });
+                        if (!hasExecution) {
+                            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                            diagnostics.push({
+                                file: sourceFile.fileName,
+                                line: line + 1,
+                                column: character + 1,
+                                ruleId: "WGL002",
+                                severity: "error",
+                                message: 'Job must have "script", "trigger", or "run" defined.',
+                            });
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/missing-stage.js

@@ -0,0 +1,60 @@
+/**
+ * WGL003: Missing stage
+ *
+ * Jobs should declare a `stage` property. Without it, the job defaults
+ * to the "test" stage which may not be the intended behavior.
+ */
+import { ts } from "@intentius/chant/lint/typescript";
+import { isJobFromAnotherLexicon } from "./import-source.js";
+export const missingStageRule = {
+    id: "WGL003",
+    severity: "info",
+    category: "style",
+    check(context) {
+        const { sourceFile } = context;
+        const diagnostics = [];
+        function visit(node) {
+            if (ts.isNewExpression(node)) {
+                let isJob = false;
+                const expression = node.expression;
+                if (ts.isIdentifier(expression) && expression.text === "Job") {
+                    isJob = true;
+                }
+                else if (ts.isPropertyAccessExpression(expression) && expression.name.text === "Job") {
+                    isJob = true;
+                }
+                // chant #1544 — same cross-lexicon rule bleed as WGL002 (see
+                // missing-script.ts): a github/forgejo `Job` must not be judged
+                // against gitlab's `stage` convention.
+                if (isJob && isJobFromAnotherLexicon(sourceFile, expression)) {
+                    isJob = false;
+                }
+                if (isJob && node.arguments && node.arguments.length > 0) {
+                    const props = node.arguments[0];
+                    if (ts.isObjectLiteralExpression(props)) {
+                        const hasStage = props.properties.some((prop) => {
+                            if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                                return prop.name.text === "stage";
+                            }
+                            return false;
+                        });
+                        if (!hasStage) {
+                            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                            diagnostics.push({
+                                file: sourceFile.fileName,
+                                line: line + 1,
+                                column: character + 1,
+                                ruleId: "WGL003",
+                                severity: "info",
+                                message: 'Job does not declare a "stage". It will default to "test".',
+                            });
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        return diagnostics;
+    },
+};

package/dist/lsp/completions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/lsp/completions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAapF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAE1E"}
+{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/lsp/completions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAapF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAE1E"}

package/dist/lsp/completions.js

@@ -0,0 +1,18 @@
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let cachedIndex = null;
+function getIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const data = require("../generated/lexicon-gitlab.json");
+    cachedIndex = new LexiconIndex(data);
+    return cachedIndex;
+}
+/**
+ * Provide GitLab CI completions based on context.
+ */
+export function gitlabCompletions(ctx) {
+    return lexiconCompletions(ctx, getIndex(), "GitLab CI entity");
+}

package/dist/lsp/hover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hover.d.ts","sourceRoot":"","sources":["../../src/lsp/hover.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAa1E;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAEpE"}
+{"version":3,"file":"hover.d.ts","sourceRoot":"","sources":["../../src/lsp/hover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAa1E;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAEpE"}

package/dist/lsp/hover.js

@@ -0,0 +1,33 @@
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { LexiconIndex, lexiconHover } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let cachedIndex = null;
+function getIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const data = require("../generated/lexicon-gitlab.json");
+    cachedIndex = new LexiconIndex(data);
+    return cachedIndex;
+}
+/**
+ * Provide hover information for GitLab CI entity types.
+ */
+export function gitlabHover(ctx) {
+    return lexiconHover(ctx, getIndex(), resourceHover);
+}
+function resourceHover(className, entry) {
+    const lines = [];
+    lines.push(`**${className}**`);
+    lines.push("");
+    lines.push(`GitLab CI type: \`${entry.resourceType}\``);
+    if (entry.kind === "resource") {
+        lines.push("");
+        lines.push("*Resource entity — serialized as a top-level CI key*");
+    }
+    else {
+        lines.push("");
+        lines.push("*Property entity — used as a nested value in resources*");
+    }
+    return { contents: lines.join("\n") };
+}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gitlab",
-  "version": "0.124.31",
+  "version": "0.124.33",
   "chantVersion": ">=0.1.0",
   "namespace": "GitLab",
   "intrinsics": [

package/dist/mcp/context-tools.js

@@ -0,0 +1,262 @@
+/**
+ * Read-only MCP tools that expose what `chant build` already computes about a
+ * GitLab pipeline — its stages and jobs, what it pulls in from outside, its
+ * security findings — so an agent can ask about a change *before it runs or
+ * merges* (#327, #328).
+ *
+ * Every tool here builds from source and returns data. None of them touch the
+ * live GitLab instance, read run history, or write anything — that boundary is
+ * what keeps chant a context producer and not a copy of the live tooling.
+ */
+import { build } from "@intentius/chant/build";
+import { runPostSynthChecks, getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { postSynthChecks } from "../lint/post-synth/index.js";
+import { getProvenance } from "@intentius/chant/provenance";
+import { relative, isAbsolute, resolve } from "path";
+import { readFile } from "fs/promises";
+import { gitlabSerializer } from "../serializer.js";
+import { transform, detectGitHubWorkflow } from "../migrate/from-github/index.js";
+import { extractStages, extractJobs, extractIncludes, extractImageRefs, isPinnedRef, } from "../lint/post-synth/yaml-helpers.js";
+/** Build the project and return the emitted GitLab YAML plus the raw result. */
+async function buildGitlab(path) {
+    const result = await build(path, [gitlabSerializer]);
+    const out = result.outputs.get("gitlab");
+    return { yaml: out ? getPrimaryOutput(out) : "", result };
+}
+/** Discover the lexicon's post-synth checks without depending on the plugin. */
+function gitlabPostSynthChecks() {
+    return postSynthChecks;
+}
+/** Is a component address (`host/group/comp@version`) pinned to a fixed version? */
+export function componentPinned(value) {
+    const at = value.lastIndexOf("@");
+    return at !== -1 && isPinnedRef(value.slice(at + 1));
+}
+/** The YAML job name a build entity serializes to (camelCase → kebab-case). */
+export function jobNameOf(entityName) {
+    return entityName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** Find the build entity whose serialized job name matches `job`. */
+function entityForJob(result, job) {
+    for (const [name, entity] of result.entities) {
+        if (name === job || jobNameOf(name) === job)
+            return { name, entity };
+    }
+    return undefined;
+}
+/** Render a source-file path relative to the project root, when possible. */
+function relSource(root, file) {
+    if (!file)
+        return undefined;
+    if (!isAbsolute(file))
+        return file;
+    const rel = relative(root, file);
+    return rel.startsWith("..") ? file : rel;
+}
+/** Jobs that would re-run because they depend (transitively) on `job`. */
+export function downstreamJobs(yaml, job) {
+    const jobs = extractJobs(yaml);
+    // edge: upstream -> downstream (J depends on each of its needs)
+    const downstreamOf = new Map();
+    for (const [name, j] of jobs) {
+        for (const dep of j.needs ?? []) {
+            const arr = downstreamOf.get(dep) ?? [];
+            arr.push(name);
+            downstreamOf.set(dep, arr);
+        }
+    }
+    const out = new Set();
+    const queue = [job];
+    while (queue.length) {
+        const cur = queue.shift();
+        for (const next of downstreamOf.get(cur) ?? []) {
+            if (!out.has(next)) {
+                out.add(next);
+                queue.push(next);
+            }
+        }
+    }
+    return [...out];
+}
+const PATH_INPUT = {
+    type: "object",
+    properties: {
+        path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+    },
+};
+/** The read-only context tools for the GitLab lexicon. */
+export function gitlabContextTools() {
+    return [
+        {
+            name: "gitlab:checks",
+            description: "Build the pipeline and return its security and correctness findings (the WGL checks) as JSON. Read-only — does not touch the live GitLab instance.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { yaml, result } = await buildGitlab(params.path ?? ".");
+                if (!yaml)
+                    return { findings: [], note: "no GitLab pipeline produced from this project" };
+                const scoped = { ...result, outputs: new Map([["gitlab", result.outputs.get("gitlab")]]) };
+                const diags = runPostSynthChecks(gitlabPostSynthChecks(), scoped);
+                return {
+                    findings: diags.map((d) => ({
+                        id: d.checkId,
+                        severity: d.severity,
+                        job: d.entity ?? null,
+                        message: d.message,
+                    })),
+                };
+            },
+        },
+        {
+            name: "gitlab:pipeline",
+            description: "Build the pipeline and return its stages and jobs as written (name, stage, and what each job runs after) — before anything runs. Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { yaml } = await buildGitlab(params.path ?? ".");
+                const jobs = [...extractJobs(yaml).values()].map((j) => ({
+                    name: j.name,
+                    stage: j.stage ?? null,
+                    runsAfter: j.needs ?? [],
+                }));
+                return { stages: extractStages(yaml), jobs };
+            },
+        },
+        {
+            name: "gitlab:references",
+            description: "Build the pipeline and list everything it pulls in from outside (includes, components, images) and whether each is pinned to a fixed version. Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { yaml } = await buildGitlab(params.path ?? ".");
+                const includes = extractIncludes(yaml).map((e) => ({
+                    kind: e.kind,
+                    source: e.value,
+                    ref: e.ref ?? null,
+                    pinned: e.kind === "project" ? (e.ref ? isPinnedRef(e.ref) : false) : e.kind === "component" ? componentPinned(e.value) : null,
+                }));
+                const images = extractImageRefs(yaml).map((i) => ({
+                    kind: "image",
+                    source: i.image,
+                    ref: null,
+                    pinned: i.image.includes("@sha256:"),
+                }));
+                return [...includes, ...images];
+            },
+        },
+        {
+            name: "gitlab:affected",
+            description: "Build the pipeline and, given a job name, list the jobs that would re-run because they depend on it (the needs chain). Read-only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+                    job: { type: "string", description: "Job name to trace downstream from" },
+                },
+                required: ["job"],
+            },
+            async handler(params) {
+                const { yaml } = await buildGitlab(params.path ?? ".");
+                const job = params.job;
+                return { job, wouldRerun: downstreamJobs(yaml, job) };
+            },
+        },
+        {
+            name: "gitlab:pipeline-yaml",
+            description: "Build the project and return the generated .gitlab-ci.yml as a string. Read-only.",
+            inputSchema: PATH_INPUT,
+            async handler(params) {
+                const { yaml } = await buildGitlab(params.path ?? ".");
+                return { yaml };
+            },
+        },
+        {
+            name: "gitlab:source",
+            description: "Build the project and, given a job name, say where it came from in the TypeScript source — the file that declared it and the composite that expanded it, if any. Entity-level provenance (file + composite), not a YAML-line source map. Read-only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+                    job: { type: "string", description: "Job name (as it appears in the generated YAML) to trace back to source" },
+                },
+                required: ["job"],
+            },
+            async handler(params) {
+                const root = params.path ?? ".";
+                const { result } = await buildGitlab(root);
+                const job = params.job;
+                const found = entityForJob(result, job);
+                if (!found)
+                    return { job, found: false, note: "no build entity serializes to that job name" };
+                const prov = getProvenance(found.entity);
+                return {
+                    job,
+                    found: true,
+                    entity: found.name,
+                    from: relSource(root, prov?.sourceFile) ?? null,
+                    via: prov?.composite ?? null,
+                };
+            },
+        },
+        {
+            name: "gitlab:owns",
+            description: "Build the project and report whether a job is declared (owned) by chant in this project's source. For pipeline config, ownership means \"declared here\" — GitLab CI jobs are not taggable cloud resources, so there is no live ownership marker as there is for cloud lexicons. Read-only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+                    job: { type: "string", description: "Job name (as it appears in the generated YAML) to check" },
+                },
+                required: ["job"],
+            },
+            async handler(params) {
+                const root = params.path ?? ".";
+                const { result } = await buildGitlab(root);
+                const job = params.job;
+                const found = entityForJob(result, job);
+                return {
+                    job,
+                    owned: Boolean(found),
+                    basis: "declared-in-source",
+                    note: "GitLab CI jobs are not taggable cloud resources; ownership here means the job is declared by chant in this project. Live ownership markers apply to cloud lexicons (aws/azure/k8s).",
+                };
+            },
+        },
+        {
+            name: "gitlab:compare",
+            description: "Given a GitHub Actions workflow file, migrate it to GitLab CI and report which security properties survive the move and which weaken or are lost (the migration safety view). Returns a per-property fate (translated/approximated/needs-review/lost). Read-only — builds and analyzes, never writes.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    file: { type: "string", description: "Path to a .github/workflows/*.yml workflow file to migrate and compare" },
+                },
+                required: ["file"],
+            },
+            async handler(params) {
+                const file = resolve(params.file ?? "");
+                let content;
+                try {
+                    content = await readFile(file, "utf8");
+                }
+                catch {
+                    return { file: params.file ?? null, found: false, note: "could not read the workflow file" };
+                }
+                if (!detectGitHubWorkflow(content)) {
+                    return { file: params.file ?? null, found: false, note: "file does not look like a GitHub Actions workflow" };
+                }
+                const migration = await transform(content, { security: true, sourceFile: file });
+                const properties = migration.provenance
+                    .filter((r) => r.security)
+                    .map((r) => ({
+                    property: r.security.property,
+                    fate: r.security.fate,
+                    severity: r.security.severity,
+                    reestablish: r.security.reestablish ?? null,
+                    note: r.note ?? null,
+                }));
+                const summary = { translated: 0, approximated: 0, "needs-review": 0, lost: 0 };
+                for (const p of properties)
+                    summary[p.fate] = (summary[p.fate] ?? 0) + 1;
+                return { found: true, properties, summary };
+            },
+        },
+    ];
+}