@intentius/chant-lexicon-gitlab 0.1.23 → 0.3.0

package/src/mcp/context-tools.ts

@@ -0,0 +1,282 @@
+/**
+ * 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, type BuildResult } from "@intentius/chant/build";
+import { runPostSynthChecks, getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { discoverPostSynthChecks } from "@intentius/chant/lint/discover";
+import { getProvenance } from "@intentius/chant/provenance";
+import type { McpToolContribution } from "@intentius/chant/mcp/types";
+import { dirname, join, relative, isAbsolute, resolve } from "path";
+import { readFile } from "fs/promises";
+import { fileURLToPath } from "url";
+import { gitlabSerializer } from "../serializer";
+import { transform, detectGitHubWorkflow } from "../migrate/from-github";
+import {
+  extractStages,
+  extractJobs,
+  extractIncludes,
+  extractImageRefs,
+  isPinnedRef,
+} from "../lint/post-synth/yaml-helpers";
+
+/** Build the project and return the emitted GitLab YAML plus the raw result. */
+async function buildGitlab(path: string): Promise<{ yaml: string; result: BuildResult }> {
+  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() {
+  const dir = join(dirname(fileURLToPath(import.meta.url)), "..", "lint", "post-synth");
+  return discoverPostSynthChecks(dir, import.meta.url);
+}
+
+/** Is a component address (`host/group/comp@version`) pinned to a fixed version? */
+export function componentPinned(value: string): boolean {
+  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: string): string {
+  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: BuildResult, job: string): { name: string; entity: object } | undefined {
+  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: string, file: string | undefined): string | undefined {
+  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: string, job: string): string[] {
+  const jobs = extractJobs(yaml);
+  // edge: upstream -> downstream (J depends on each of its needs)
+  const downstreamOf = new Map<string, string[]>();
+  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<string>();
+  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" as const,
+  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(): McpToolContribution[] {
+  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: Record<string, unknown>): Promise<unknown> {
+        const { yaml, result } = await buildGitlab((params.path as string) ?? ".");
+        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: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGitlab((params.path as string) ?? ".");
+        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: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGitlab((params.path as string) ?? ".");
+        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" as const,
+          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" as const,
+        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: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGitlab((params.path as string) ?? ".");
+        const job = params.job as string;
+        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: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGitlab((params.path as string) ?? ".");
+        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" as const,
+        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: Record<string, unknown>): Promise<unknown> {
+        const root = (params.path as string) ?? ".";
+        const { result } = await buildGitlab(root);
+        const job = params.job as string;
+        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" as const,
+        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: Record<string, unknown>): Promise<unknown> {
+        const root = (params.path as string) ?? ".";
+        const { result } = await buildGitlab(root);
+        const job = params.job as string;
+        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" as const,
+        properties: {
+          file: { type: "string", description: "Path to a .github/workflows/*.yml workflow file to migrate and compare" },
+        },
+        required: ["file"],
+      },
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const file = resolve((params.file as string) ?? "");
+        let content: string;
+        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 } as Record<string, number>;
+        for (const p of properties) summary[p.fate] = (summary[p.fate] ?? 0) + 1;
+        return { found: true, properties, summary };
+      },
+    },
+  ];
+}

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

@@ -22,6 +22,24 @@ export function provenanceToDiagnostics(
 ): LintDiagnostic[] {
   const out: LintDiagnostic[] = [];
   for (const r of records) {
+    // Security records always emit a diagnostic, at their own severity
+    // (escalated to error under --strict when the property was lost or needs
+    // review), independent of the functional category.
+    if (r.security) {
+      const sev =
+        opts.strict && (r.security.fate === "lost" || r.security.fate === "needs-review")
+          ? "error"
+          : r.security.severity;
+      out.push({
+        file: r.sourceFile ?? "<input>",
+        line: r.sourceLine ?? 1,
+        column: r.sourceColumn ?? 1,
+        ruleId: r.rule,
+        severity: sev,
+        message: r.note ?? r.rule,
+      });
+      continue;
+    }
     let severity: "error" | "warning" | "info" | undefined;
     if (r.category === "needs-review") {
       severity = opts.strict ? "error" : "warning";

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

@@ -12,6 +12,7 @@ import { ProvenanceAccumulator, type ProvenanceRecord } from "./provenance";
 import { transformIR } from "./transformer";
 import { emitGitlabYaml } from "./emit-yaml";
 import { provenanceToDiagnostics } from "./diagnostics";
+import { analyzeSecurity, runSecurityChecks, renderSecurityPosture } from "./security";
 import { GitLabGenerator } from "../../import/generator";
 import { applyComposites } from "./composites/rewriter";
 import type { ActionMappingRegistry } from "./actions/registry";
@@ -31,6 +32,12 @@ export interface MigrateOptions {
   registry?: ActionMappingRegistry;
   /** Escalate needs-review diagnostics to errors. */
   strict?: boolean;
+  /**
+   * 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. Enabled by the CLI's `--validate` path.
+   */
+  security?: boolean;
 }
 
 export interface MigrationResult {
@@ -44,6 +51,8 @@ export interface MigrationResult {
   diagnostics: LintDiagnostic[];
   /** Inferred stage list. */
   stages: string[];
+  /** Markdown "Security posture" section (#306). */
+  securityPosture: string;
 }
 
 /**
@@ -106,10 +115,20 @@ export async function transform(
     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 };
+  return { ir, output, provenance, diagnostics, stages, securityPosture };
 }
 
 /**

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

@@ -37,6 +37,29 @@ export interface ProvenanceRecord {
   actionRef?: string;
   /** Tier 1/2/3 for action-map records */
   mappingTier?: 1 | 2 | 3;
+  /** Security classification, when this record concerns a security property. */
+  security?: SecurityProvenance;
+}
+
+/**
+ * Fate of a security property as it crosses the GitHub → GitLab boundary,
+ * mirroring the functional provenance categories.
+ */
+export type SecurityFate = "translated" | "approximated" | "needs-review" | "lost";
+
+/**
+ * Security classification attached to a provenance record — tracks whether a
+ * security-relevant property survived migration, alongside the functional one.
+ */
+export interface SecurityProvenance {
+  /** Human label for the property (e.g. "Pinned action SHA"). */
+  property: string;
+  /** What happened to the property across the migration edge. */
+  fate: SecurityFate;
+  /** Diagnostic severity for this finding. */
+  severity: "error" | "warning" | "info";
+  /** Cross-reference to the endpoint that re-establishes the property. */
+  reestablish?: string;
 }
 
 /**
@@ -65,4 +88,9 @@ export class ProvenanceAccumulator {
   needsReviewCount(): number {
     return this.records.filter((r) => r.category === "needs-review").length;
   }
+
+  /** Records carrying a security classification. */
+  securityRecords(): ProvenanceRecord[] {
+    return this.records.filter((r) => r.security !== undefined);
+  }
 }

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

@@ -79,4 +79,11 @@ export const MIGRATION_RULES: LintRule[] = [
 
   // 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/src/migrate/from-github/security.test.ts

@@ -0,0 +1,98 @@
+import { describe, test, expect } from "vitest";
+import { analyzeSecurity, runSecurityChecks, renderSecurityPosture } from "./security";
+import { transform } from "./index";
+
+const WORKFLOW = `name: CI
+on:
+  pull_request_target:
+permissions:
+  contents: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - run: echo "title is \${{ github.event.pull_request.title }}"
+      - run: deploy --token \${{ secrets.DEPLOY_TOKEN }}
+`;
+
+describe("analyzeSecurity (#306)", () => {
+  test("classifies each security property's fate", () => {
+    const records = analyzeSecurity(WORKFLOW, { sourceFile: "ci.yml" });
+    const byRule = new Map(records.map((r) => [r.rule, r]));
+
+    expect(byRule.get("MIG-PIN-LOST")?.security?.fate).toBe("lost");
+    expect(byRule.get("MIG-SECRET-UNSCOPED")?.security?.fate).toBe("needs-review");
+    expect(byRule.get("MIG-INJECTION-CARRIED")?.security?.fate).toBe("translated");
+    expect(byRule.get("MIG-TRUST-BOUNDARY")?.security?.fate).toBe("needs-review");
+    expect(byRule.get("MIG-PERMISSIONS-001")?.security?.fate).toBe("needs-review");
+
+    // each cross-references the endpoint that re-establishes the property
+    expect(byRule.get("MIG-PIN-LOST")?.security?.reestablish).toBe("#297");
+    expect(byRule.get("MIG-SECRET-UNSCOPED")?.security?.reestablish).toBe("#300");
+  });
+
+  test("does not flag a clean workflow", () => {
+    const clean = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    expect(analyzeSecurity(clean)).toHaveLength(0);
+  });
+});
+
+describe("runSecurityChecks (#306)", () => {
+  test("runs the GitLab post-synth checks against migrated YAML", async () => {
+    // A migrated pipeline whose image is unpinned should trip WGL031.
+    const yaml = `stages:
+  - build
+
+build:
+  stage: build
+  image:
+    name: node:20
+  script:
+    - npm ci
+`;
+    const records = await runSecurityChecks(yaml);
+    expect(records.some((r) => r.rule === "WGL031")).toBe(true);
+    expect(records.every((r) => r.security !== undefined)).toBe(true);
+  });
+});
+
+describe("renderSecurityPosture (#306)", () => {
+  test("renders a posture table", () => {
+    const records = analyzeSecurity(WORKFLOW, { sourceFile: "ci.yml" });
+    const md = renderSecurityPosture(records);
+    expect(md).toContain("## Security posture");
+    expect(md).toContain("MIG-PIN-LOST");
+    expect(md).toContain("lost");
+  });
+
+  test("reports nothing for a clean workflow", () => {
+    expect(renderSecurityPosture([])).toContain("No security-relevant properties");
+  });
+});
+
+describe("transform with security: true (#306)", () => {
+  test("security findings flow into provenance + diagnostics + posture", async () => {
+    const result = await transform(WORKFLOW, { sourceFile: "ci.yml", security: true });
+    const ruleIds = new Set(result.diagnostics.map((d) => d.ruleId));
+    expect(ruleIds.has("MIG-PIN-LOST")).toBe(true);
+    expect(ruleIds.has("MIG-TRUST-BOUNDARY")).toBe(true);
+    expect(result.securityPosture).toContain("## Security posture");
+    expect(result.provenance.some((p) => p.security)).toBe(true);
+  });
+
+  test("security analysis is off by default", async () => {
+    const result = await transform(WORKFLOW, { sourceFile: "ci.yml" });
+    const ruleIds = new Set(result.diagnostics.map((d) => d.ruleId));
+    expect(ruleIds.has("MIG-PIN-LOST")).toBe(false);
+    expect(result.provenance.some((p) => p.security)).toBe(false);
+  });
+});