@intentius/chant-lexicon-gitlab 0.1.23 → 0.3.0

package/src/lint/post-synth/yaml-helpers.ts

@@ -223,3 +223,217 @@ export function extractJobRules(section: string): ParsedRule[] {
 
   return rules;
 }
+
+/** A container image reference (job/default `image:` or a `services:` entry). */
+export interface ImageRef {
+  /** Owning job name, or "default" for the global image. */
+  job: string;
+  /** The image reference (e.g. `node:20`). */
+  image: string;
+  /** Where the image was declared. */
+  source: "image" | "service";
+}
+
+/**
+ * Extract container image references from `image:` and `services:` across the
+ * pipeline. Handles both the object form (`image:\n  name: ...`) and the inline
+ * string form (`image: ...`).
+ */
+export function extractImageRefs(yaml: string): ImageRef[] {
+  const refs: ImageRef[] = [];
+  for (const section of yaml.split("\n\n")) {
+    const lines = section.split("\n");
+    const top = lines[0]?.match(/^(\.?[a-z][a-z0-9_.-]*):/i);
+    const job = top ? top[1] : "default";
+
+    for (let i = 0; i < lines.length; i++) {
+      // image: as object (next indented `name:`) or inline string
+      const imgInline = lines[i].match(/^\s+image:\s+(\S.*)$/);
+      if (imgInline) {
+        refs.push({ job, image: imgInline[1].trim().replace(/^['"]|['"]$/g, ""), source: "image" });
+        continue;
+      }
+      if (/^\s+image:\s*$/.test(lines[i])) {
+        const nameLine = lines.slice(i + 1, i + 4).find((l) => /^\s+name:\s+/.test(l));
+        if (nameLine) {
+          const v = nameLine.replace(/^\s+name:\s+/, "").trim().replace(/^['"]|['"]$/g, "");
+          refs.push({ job, image: v, source: "image" });
+        }
+        continue;
+      }
+      // services: list entries — `- name:` or `- 'image'`
+      const svcName = lines[i].match(/^\s+-\s+name:\s+(\S.*)$/);
+      if (svcName) {
+        refs.push({ job, image: svcName[1].trim().replace(/^['"]|['"]$/g, ""), source: "service" });
+      }
+    }
+  }
+  return refs;
+}
+
+/** An `include:` entry from the top-level include block. */
+export interface IncludeEntry {
+  kind: "project" | "remote" | "component" | "local" | "template" | "string";
+  /** The primary value (project path, URL, component address, …). */
+  value: string;
+  /** `ref:` for project includes, if present. */
+  ref?: string;
+}
+
+/**
+ * Parse the top-level `include:` block into structured entries.
+ */
+export function extractIncludes(yaml: string): IncludeEntry[] {
+  const entries: IncludeEntry[] = [];
+  const section = yaml.split("\n\n").find((s) => /^include:/.test(s));
+  if (!section) return entries;
+
+  // Inline string form: `include: <value>` (value on the same line, not a list)
+  const inline = section.match(/^include:[ \t]+(\S.*)$/m);
+  if (inline) {
+    entries.push({ kind: "string", value: inline[1].trim().replace(/^['"]|['"]$/g, "") });
+    return entries;
+  }
+
+  const lines = section.split("\n");
+  let current: IncludeEntry | undefined;
+  const push = () => { if (current) entries.push(current); current = undefined; };
+  for (const line of lines) {
+    const start = line.match(/^\s+-\s+(project|remote|component|local|template):\s*(.*)$/);
+    if (start) {
+      push();
+      current = { kind: start[1] as IncludeEntry["kind"], value: start[2].trim().replace(/^['"]|['"]$/g, "") };
+      continue;
+    }
+    const refLine = line.match(/^\s+ref:\s+(.+)$/);
+    if (refLine && current) {
+      current.ref = refLine[1].trim().replace(/^['"]|['"]$/g, "");
+    }
+    // A bare `- 'https://...'` short remote form
+    const bare = line.match(/^\s+-\s+(['"]?https?:\/\/\S+['"]?)\s*$/);
+    if (bare) {
+      push();
+      entries.push({ kind: "remote", value: bare[1].replace(/^['"]|['"]$/g, "") });
+    }
+  }
+  push();
+  return entries;
+}
+
+/** True if a git ref is an immutable pin (40-hex SHA or a vN.N.N-style tag). */
+export function isPinnedRef(ref: string): boolean {
+  if (/^[0-9a-f]{40}$/.test(ref)) return true;
+  // Semver-ish tag with all components fixed (v1.2.3 / 1.2.3)
+  if (/^v?\d+\.\d+\.\d+$/.test(ref)) return true;
+  return false;
+}
+
+/** An `id_tokens:` OIDC token declaration within a job. */
+export interface IdTokenDecl {
+  job: string;
+  /** Token variable name (e.g. `GCP_ID_TOKEN`). */
+  name: string;
+  /** Declared audiences (`aud:`), empty if none. */
+  aud: string[];
+}
+
+/**
+ * Extract `id_tokens:` declarations (OIDC) per job, with their audiences.
+ */
+export function extractIdTokens(yaml: string): IdTokenDecl[] {
+  const out: IdTokenDecl[] = [];
+  for (const section of yaml.split("\n\n")) {
+    const lines = section.split("\n");
+    const top = lines[0]?.match(/^(\.?[a-z][a-z0-9_.-]*):/i);
+    if (!top) continue;
+    const job = top[1];
+
+    let inIdTokens = false;
+    let idTokensIndent = -1;
+    let current: IdTokenDecl | undefined;
+    const flush = () => { if (current) out.push(current); current = undefined; };
+
+    for (const line of lines) {
+      if (/^\s+id_tokens:\s*$/.test(line)) {
+        inIdTokens = true;
+        idTokensIndent = line.search(/\S/);
+        continue;
+      }
+      if (!inIdTokens) continue;
+      const indent = line.search(/\S/);
+      if (line.trim() !== "" && indent <= idTokensIndent) { flush(); inIdTokens = false; continue; }
+
+      const tokenName = line.match(/^\s+([A-Z_][A-Z0-9_]*):\s*$/);
+      if (tokenName && indent === idTokensIndent + 2) {
+        flush();
+        current = { job, name: tokenName[1], aud: [] };
+        continue;
+      }
+      const audInline = line.match(/^\s+aud:\s+(\S.*)$/);
+      if (audInline && current) {
+        const v = audInline[1].trim();
+        if (v.startsWith("[")) {
+          for (const p of v.replace(/^\[|\]$/g, "").split(",")) {
+            const t = p.trim().replace(/^['"]|['"]$/g, "");
+            if (t) current.aud.push(t);
+          }
+        } else {
+          current.aud.push(v.replace(/^['"]|['"]$/g, ""));
+        }
+        continue;
+      }
+      const audItem = line.match(/^\s+-\s+(\S.*)$/);
+      if (audItem && current) {
+        current.aud.push(audItem[1].trim().replace(/^['"]|['"]$/g, ""));
+      }
+    }
+    flush();
+  }
+  return out;
+}
+
+/** True if a job section's rules make it reachable from merge-request pipelines. */
+export function isMergeRequestReachable(section: string): boolean {
+  return /merge_request_event|CI_MERGE_REQUEST|CI_PIPELINE_SOURCE\s*==\s*['"]?merge_request/.test(section);
+}
+
+/** A shell command line from a `script:` / `before_script:` / `after_script:`. */
+export interface ScriptCommand {
+  job: string;
+  command: string;
+}
+
+/**
+ * Extract shell command lines from all `script:` family blocks, per job.
+ */
+export function extractScriptCommands(yaml: string): ScriptCommand[] {
+  const out: ScriptCommand[] = [];
+  for (const section of yaml.split("\n\n")) {
+    const lines = section.split("\n");
+    const top = lines[0]?.match(/^(\.?[a-z][a-z0-9_.-]*):/i);
+    if (!top) continue;
+    const job = top[1];
+
+    let inScript = false;
+    let scriptIndent = -1;
+    for (const line of lines) {
+      if (/^\s+(before_script|after_script|script):\s*$/.test(line)) {
+        inScript = true;
+        scriptIndent = line.search(/\S/);
+        continue;
+      }
+      // inline form `script: cmd`
+      const inlineScript = line.match(/^\s+(?:before_script|after_script|script):\s+(\S.*)$/);
+      if (inlineScript) {
+        out.push({ job, command: inlineScript[1].trim().replace(/^['"]|['"]$/g, "") });
+        continue;
+      }
+      if (!inScript) continue;
+      const indent = line.search(/\S/);
+      if (line.trim() !== "" && indent <= scriptIndent) { inScript = false; continue; }
+      const item = line.match(/^\s+-\s+(.*)$/);
+      if (item) out.push({ job, command: item[1].trim().replace(/^['"]|['"]$/g, "") });
+    }
+  }
+  return out;
+}

package/src/lint/rules/data/known-include-sources.ts

@@ -0,0 +1,41 @@
+/**
+ * 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: readonly string[] = [
+  "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: string, b: string, max: number): number {
+  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/src/lint/rules/data/untrusted-variables.ts

@@ -0,0 +1,31 @@
+/**
+ * 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: readonly string[] = [
+  "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: string, name: string): boolean {
+  const re = new RegExp(`\\$\\{?${name}\\}?(?![A-Z0-9_])`);
+  return re.test(text);
+}

package/src/mcp/context-tools.test.ts

@@ -0,0 +1,178 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { gitlabContextTools, downstreamJobs, componentPinned } from "./context-tools";
+
+const tools = Object.fromEntries(gitlabContextTools().map((t) => [t.name, t]));
+
+async function call(name: string, params: Record<string, unknown>): Promise<unknown> {
+  return tools[name].handler(params);
+}
+
+describe("downstreamJobs / componentPinned (#327)", () => {
+  test("downstreamJobs follows the needs chain transitively", () => {
+    const yaml = `build:
+  stage: build
+  script:
+    - echo build
+
+test:
+  stage: test
+  needs:
+    - build
+  script:
+    - echo test
+
+deploy:
+  stage: deploy
+  needs:
+    - test
+  script:
+    - echo deploy
+`;
+    expect(downstreamJobs(yaml, "build").sort()).toEqual(["deploy", "test"]);
+    expect(downstreamJobs(yaml, "test")).toEqual(["deploy"]);
+    expect(downstreamJobs(yaml, "deploy")).toEqual([]);
+  });
+
+  test("componentPinned recognises a fixed version", () => {
+    expect(componentPinned("gitlab.com/g/comp@1.2.3")).toBe(true);
+    expect(componentPinned("gitlab.com/g/comp@main")).toBe(false);
+  });
+});
+
+describe("gitlab context tools — end to end (#327/#328)", () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = join(tmpdir(), `chant-mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, "pipeline.infra.ts"),
+      `const M = Symbol.for("chant.declarable");
+export const buildApp = { [M]: true, lexicon: "gitlab", entityType: "GitLab::CI::Job", kind: "resource",
+  props: { stage: "build", image: { name: "node:20" }, script: ["echo build"] } };
+export const testApp = { [M]: true, lexicon: "gitlab", entityType: "GitLab::CI::Job", kind: "resource",
+  props: { stage: "test", script: ["npm test"], needs: ["build-app"] } };
+`,
+    );
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("gitlab:pipeline returns stages and jobs", async () => {
+    const out = (await call("gitlab:pipeline", { path: dir })) as {
+      stages: string[];
+      jobs: Array<{ name: string; stage: string | null; runsAfter: string[] }>;
+    };
+    expect(out.stages).toEqual(expect.arrayContaining(["build", "test"]));
+    const names = out.jobs.map((j) => j.name);
+    expect(names).toEqual(expect.arrayContaining(["build-app", "test-app"]));
+    expect(out.jobs.find((j) => j.name === "test-app")?.runsAfter).toContain("build-app");
+  });
+
+  test("gitlab:references reports the unpinned image", async () => {
+    const out = (await call("gitlab:references", { path: dir })) as Array<{ kind: string; source: string; pinned: boolean | null }>;
+    const img = out.find((r) => r.kind === "image" && r.source === "node:20");
+    expect(img).toBeDefined();
+    expect(img?.pinned).toBe(false);
+  });
+
+  test("gitlab:checks returns the WGL findings (unpinned image trips WGL031)", async () => {
+    const out = (await call("gitlab:checks", { path: dir })) as { findings: Array<{ id: string; severity: string; job: string | null; message: string }> };
+    expect(Array.isArray(out.findings)).toBe(true);
+    expect(out.findings.some((f) => f.id === "WGL031")).toBe(true);
+    for (const f of out.findings) {
+      expect(typeof f.id).toBe("string");
+      expect(typeof f.message).toBe("string");
+    }
+  });
+
+  test("gitlab:affected lists downstream jobs", async () => {
+    const out = (await call("gitlab:affected", { path: dir, job: "build-app" })) as { job: string; wouldRerun: string[] };
+    expect(out.wouldRerun).toContain("test-app");
+  });
+
+  test("gitlab:pipeline-yaml returns the generated YAML for a path", async () => {
+    const out = (await call("gitlab:pipeline-yaml", { path: dir })) as { yaml: string };
+    expect(typeof out.yaml).toBe("string");
+    expect(out.yaml).toContain("stages:");
+  });
+
+  test("gitlab:source traces a job back to its declaring file", async () => {
+    const out = (await call("gitlab:source", { path: dir, job: "build-app" })) as {
+      job: string; found: boolean; entity: string; from: string | null; via: string | null;
+    };
+    expect(out.found).toBe(true);
+    expect(out.entity).toBe("buildApp");
+    expect(out.from).toMatch(/pipeline\.infra\.ts$/);
+    expect(out.via).toBeNull(); // plain declarable, not from a composite
+  });
+
+  test("gitlab:source reports not-found for an unknown job", async () => {
+    const out = (await call("gitlab:source", { path: dir, job: "nope" })) as { job: string; found: boolean };
+    expect(out.found).toBe(false);
+  });
+
+  test("gitlab:owns reports a declared job as owned, an unknown one as not", async () => {
+    const owned = (await call("gitlab:owns", { path: dir, job: "test-app" })) as { owned: boolean; basis: string };
+    expect(owned.owned).toBe(true);
+    expect(owned.basis).toBe("declared-in-source");
+    const foreign = (await call("gitlab:owns", { path: dir, job: "not-here" })) as { owned: boolean };
+    expect(foreign.owned).toBe(false);
+  });
+});
+
+describe("gitlab:compare — migration safety view (#327)", () => {
+  let dir: string;
+  let wf: string;
+  beforeEach(async () => {
+    dir = join(tmpdir(), `chant-mcp-cmp-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(dir, { recursive: true });
+    wf = join(dir, "ci.yml");
+    await writeFile(
+      wf,
+      `name: CI
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@${"a".repeat(40)}
+      - run: npm ci
+`,
+    );
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("reports the SHA pin as lost across the migration edge", async () => {
+    const out = (await call("gitlab:compare", { file: wf })) as {
+      found: boolean;
+      properties: Array<{ property: string; fate: string }>;
+      summary: Record<string, number>;
+    };
+    expect(out.found).toBe(true);
+    const pin = out.properties.find((p) => p.property === "Pinned action SHA");
+    expect(pin?.fate).toBe("lost");
+    expect(out.summary.lost).toBeGreaterThanOrEqual(1);
+  });
+
+  test("not-found for a missing file", async () => {
+    const out = (await call("gitlab:compare", { file: join(dir, "nope.yml") })) as { found: boolean };
+    expect(out.found).toBe(false);
+  });
+
+  test("not-found for a non-workflow file", async () => {
+    const notWf = join(dir, "plain.yml");
+    await writeFile(notWf, "hello: world\n");
+    const out = (await call("gitlab:compare", { file: notWf })) as { found: boolean };
+    expect(out.found).toBe(false);
+  });
+});