@intentius/chant-lexicon-gitlab 0.0.1

package/src/import/parser.ts

@@ -0,0 +1,282 @@
+/**
+ * GitLab CI YAML parser for `chant import`.
+ *
+ * Parses an existing .gitlab-ci.yml file into the core TemplateIR format,
+ * mapping GitLab CI constructs to resources and property types.
+ */
+
+import type { TemplateParser, TemplateIR, ResourceIR } from "@intentius/chant/import/parser";
+
+/**
+ * Reserved top-level keys in .gitlab-ci.yml that are NOT job definitions.
+ */
+const RESERVED_KEYS = new Set([
+  "stages",
+  "variables",
+  "default",
+  "workflow",
+  "include",
+  "image",
+  "services",
+  "before_script",
+  "after_script",
+  "cache",
+  "pages",
+]);
+
+/**
+ * Map snake_case GitLab CI keys to camelCase for Chant properties.
+ */
+function toCamelCase(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Recursively convert snake_case keys in an object to camelCase.
+ */
+function camelCaseKeys(value: unknown): unknown {
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) return value.map(camelCaseKeys);
+  if (typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      result[toCamelCase(key)] = camelCaseKeys(val);
+    }
+    return result;
+  }
+  return value;
+}
+
+/**
+ * Parse a YAML document into a plain object.
+ * Uses a simple YAML parser approach — GitLab CI YAML is straightforward
+ * enough that we can parse it without a full YAML library by parsing JSON
+ * or using Bun's built-in YAML support if available.
+ */
+function parseYAML(content: string): Record<string, unknown> {
+  // Try JSON first (some CI files may be JSON)
+  try {
+    return JSON.parse(content);
+  } catch {
+    // Fall through to YAML parsing
+  }
+
+  // Simple YAML parser for GitLab CI files
+  // This handles the common cases: scalars, arrays, objects, block scalars
+  const lines = content.split("\n");
+  return parseYAMLLines(lines, 0, 0).value as Record<string, unknown>;
+}
+
+interface ParseResult {
+  value: unknown;
+  endIndex: number;
+}
+
+function parseYAMLLines(lines: string[], startIndex: number, baseIndent: number): ParseResult {
+  const result: Record<string, unknown> = {};
+  let i = startIndex;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    // Skip empty lines and comments
+    if (line.trim() === "" || line.trim().startsWith("#")) {
+      i++;
+      continue;
+    }
+
+    const indent = line.search(/\S/);
+    if (indent < baseIndent) break; // Dedented — done with this block
+    if (indent > baseIndent && startIndex > 0) break; // Unexpected indent
+
+    const keyMatch = line.match(/^(\s*)([^\s:][^:]*?):\s*(.*)$/);
+    if (keyMatch) {
+      const key = keyMatch[2].trim();
+      const inlineValue = keyMatch[3].trim();
+
+      if (inlineValue === "" || inlineValue.startsWith("#")) {
+        // Check next line for array or nested object
+        if (i + 1 < lines.length) {
+          const nextLine = lines[i + 1];
+          const nextIndent = nextLine.search(/\S/);
+          if (nextIndent > indent && nextLine.trimStart().startsWith("- ")) {
+            // Array
+            const arr = parseYAMLArray(lines, i + 1, nextIndent);
+            result[key] = arr.value;
+            i = arr.endIndex;
+            continue;
+          } else if (nextIndent > indent) {
+            // Nested object
+            const nested = parseYAMLLines(lines, i + 1, nextIndent);
+            result[key] = nested.value;
+            i = nested.endIndex;
+            continue;
+          }
+        }
+        result[key] = null;
+        i++;
+      } else if (inlineValue.startsWith("[")) {
+        // Inline array
+        try {
+          result[key] = JSON.parse(inlineValue);
+        } catch {
+          result[key] = inlineValue;
+        }
+        i++;
+      } else if (inlineValue.startsWith("{")) {
+        // Inline object
+        try {
+          result[key] = JSON.parse(inlineValue);
+        } catch {
+          result[key] = inlineValue;
+        }
+        i++;
+      } else {
+        result[key] = parseScalar(inlineValue);
+        i++;
+      }
+    } else if (line.trimStart().startsWith("- ")) {
+      // We hit an array at the top level — shouldn't happen normally
+      break;
+    } else {
+      i++;
+    }
+  }
+
+  return { value: result, endIndex: i };
+}
+
+function parseYAMLArray(lines: string[], startIndex: number, baseIndent: number): ParseResult {
+  const result: unknown[] = [];
+  let i = startIndex;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim() === "" || line.trim().startsWith("#")) {
+      i++;
+      continue;
+    }
+
+    const indent = line.search(/\S/);
+    if (indent < baseIndent) break;
+
+    const itemMatch = line.match(/^(\s*)- (.*)$/);
+    if (itemMatch && indent === baseIndent) {
+      const itemValue = itemMatch[2].trim();
+      // Check if it's a key-value pair (object item in array)
+      const kvMatch = itemValue.match(/^([^\s:][^:]*?):\s*(.*)$/);
+      if (kvMatch) {
+        const obj: Record<string, unknown> = {};
+        obj[kvMatch[1].trim()] = parseScalar(kvMatch[2].trim());
+        // Check for more keys at indent+2
+        const nextIndent = indent + 2;
+        let j = i + 1;
+        while (j < lines.length) {
+          const nextLine = lines[j];
+          if (nextLine.trim() === "" || nextLine.trim().startsWith("#")) {
+            j++;
+            continue;
+          }
+          const ni = nextLine.search(/\S/);
+          if (ni !== nextIndent) break;
+          const nextKV = nextLine.match(/^(\s*)([^\s:][^:]*?):\s*(.*)$/);
+          if (nextKV) {
+            obj[nextKV[2].trim()] = parseScalar(nextKV[3].trim());
+            j++;
+          } else {
+            break;
+          }
+        }
+        result.push(obj);
+        i = j;
+      } else {
+        result.push(parseScalar(itemValue));
+        i++;
+      }
+    } else {
+      break;
+    }
+  }
+
+  return { value: result, endIndex: i };
+}
+
+function parseScalar(value: string): unknown {
+  if (value === "" || value === "~" || value === "null") return null;
+  if (value === "true" || value === "yes") return true;
+  if (value === "false" || value === "no") return false;
+  // Strip quotes
+  if ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"'))) {
+    return value.slice(1, -1);
+  }
+  // Number
+  const num = Number(value);
+  if (!isNaN(num) && value !== "") return num;
+  return value;
+}
+
+/**
+ * GitLab CI YAML parser implementation.
+ */
+export class GitLabParser implements TemplateParser {
+  parse(content: string): TemplateIR {
+    const doc = parseYAML(content);
+    const resources: ResourceIR[] = [];
+
+    // Extract default
+    if (doc.default && typeof doc.default === "object") {
+      resources.push({
+        logicalId: "defaults",
+        type: "GitLab::CI::Default",
+        properties: camelCaseKeys(doc.default) as Record<string, unknown>,
+      });
+    }
+
+    // Extract workflow
+    if (doc.workflow && typeof doc.workflow === "object") {
+      resources.push({
+        logicalId: "workflow",
+        type: "GitLab::CI::Workflow",
+        properties: camelCaseKeys(doc.workflow) as Record<string, unknown>,
+      });
+    }
+
+    // Extract jobs — any top-level key not in RESERVED_KEYS
+    for (const [key, value] of Object.entries(doc)) {
+      if (RESERVED_KEYS.has(key)) continue;
+      if (typeof value !== "object" || value === null) continue;
+
+      // Check if it looks like a job (has script, stage, trigger, extends, etc.)
+      const obj = value as Record<string, unknown>;
+      if (
+        obj.script !== undefined ||
+        obj.stage !== undefined ||
+        obj.trigger !== undefined ||
+        obj.extends !== undefined ||
+        obj.rules !== undefined ||
+        obj.needs !== undefined
+      ) {
+        resources.push({
+          logicalId: toCamelCase(key.replace(/-/g, "_")),
+          type: "GitLab::CI::Job",
+          properties: camelCaseKeys(obj) as Record<string, unknown>,
+          metadata: {
+            originalName: key,
+            stage: typeof obj.stage === "string" ? obj.stage : undefined,
+          },
+        });
+      }
+    }
+
+    // Record include references as metadata
+    const metadata: Record<string, unknown> = {};
+    if (doc.stages) metadata.stages = doc.stages;
+    if (doc.include) metadata.include = doc.include;
+    if (doc.variables) metadata.variables = doc.variables;
+
+    return {
+      resources,
+      parameters: [], // GitLab CI doesn't have parameters like CFN
+      metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+    };
+  }
+}

package/src/import/roundtrip.test.ts

@@ -0,0 +1,89 @@
+import { describe, test, expect } from "bun:test";
+import { GitLabParser } from "./parser";
+import { GitLabGenerator } from "./generator";
+
+const parser = new GitLabParser();
+const generator = new GitLabGenerator();
+
+describe("roundtrip: parse → generate", () => {
+  test("simple pipeline roundtrip", () => {
+    const yaml = `
+stages:
+  - test
+
+test-job:
+  stage: test
+  script:
+    - npm test
+`;
+    const ir = parser.parse(yaml);
+    const files = generator.generate(ir);
+
+    expect(files).toHaveLength(1);
+    const content = files[0].content;
+
+    // Should produce valid-looking TypeScript
+    expect(content).toContain("import");
+    expect(content).toContain("export const");
+    expect(content).toContain("new Job(");
+    expect(content).toContain('"test"');
+    expect(content).toContain("npm test");
+  });
+
+  test("multi-job pipeline roundtrip", () => {
+    const yaml = `
+stages:
+  - build
+  - test
+  - deploy
+
+build-app:
+  stage: build
+  script:
+    - npm ci
+    - npm run build
+
+run-tests:
+  stage: test
+  script:
+    - npm test
+
+deploy-prod:
+  stage: deploy
+  script:
+    - deploy.sh
+`;
+    const ir = parser.parse(yaml);
+    expect(ir.resources).toHaveLength(3);
+
+    const files = generator.generate(ir);
+    const content = files[0].content;
+
+    expect(content).toContain("buildApp");
+    expect(content).toContain("runTests");
+    expect(content).toContain("deployProd");
+    expect(content).toContain("Pipeline stages: build, test, deploy");
+  });
+
+  test("pipeline with defaults and workflow roundtrip", () => {
+    const yaml = `
+default:
+  interruptible: true
+
+workflow:
+  name: CI
+
+test-job:
+  stage: test
+  script:
+    - test
+`;
+    const ir = parser.parse(yaml);
+    const files = generator.generate(ir);
+    const content = files[0].content;
+
+    expect(content).toContain("new Default(");
+    expect(content).toContain("new Workflow(");
+    expect(content).toContain("new Job(");
+  });
+});

package/src/index.ts

@@ -0,0 +1,25 @@
+// Serializer
+export { gitlabSerializer } from "./serializer";
+
+// Plugin
+export { gitlabPlugin } from "./plugin";
+
+// Intrinsics
+export { reference, ReferenceIntrinsic } from "./intrinsics";
+
+// CI/CD Variables
+export { CI } from "./variables";
+
+// Generated entities — export everything from generated index
+// After running `chant generate`, this re-exports all CI entity classes
+export * from "./generated/index";
+
+// Spec utilities (for tooling)
+export { fetchCISchema, fetchSchemas, GITLAB_SCHEMA_VERSION } from "./codegen/fetch";
+export { parseCISchema, gitlabShortName, gitlabServiceName } from "./codegen/parse";
+export type { GitLabParseResult, ParsedResource, ParsedProperty, ParsedPropertyType, ParsedEnum } from "./codegen/parse";
+
+// Code generation pipeline
+export { generate, writeGeneratedFiles } from "./codegen/generate";
+export { packageLexicon } from "./codegen/package";
+export type { PackageOptions, PackageResult } from "./codegen/package";

package/src/intrinsics.test.ts

@@ -0,0 +1,42 @@
+import { describe, test, expect } from "bun:test";
+import { reference, ReferenceIntrinsic } from "./intrinsics";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+
+describe("reference intrinsic", () => {
+  test("creates a ReferenceIntrinsic instance", () => {
+    const ref = reference("job_name", "script");
+    expect(ref).toBeInstanceOf(ReferenceIntrinsic);
+  });
+
+  test("has INTRINSIC_MARKER set to true", () => {
+    const ref = reference("job_name", "script");
+    expect(ref[INTRINSIC_MARKER]).toBe(true);
+  });
+
+  test("toJSON returns the path array", () => {
+    const ref = reference("job_name", "script");
+    expect(ref.toJSON()).toEqual(["job_name", "script"]);
+  });
+
+  test("toJSON returns single-element path", () => {
+    const ref = reference(".setup");
+    expect(ref.toJSON()).toEqual([".setup"]);
+  });
+
+  test("toJSON returns multi-element path", () => {
+    const ref = reference(".base", "before_script", "0");
+    expect(ref.toJSON()).toEqual([".base", "before_script", "0"]);
+  });
+
+  test("toYAML returns !reference tag with path", () => {
+    const ref = reference("job_name", "script");
+    const yaml = ref.toYAML();
+    expect(yaml.tag).toBe("!reference");
+    expect(yaml.value).toEqual(["job_name", "script"]);
+  });
+
+  test("empty path produces empty array", () => {
+    const ref = reference();
+    expect(ref.toJSON()).toEqual([]);
+  });
+});

package/src/intrinsics.ts

@@ -0,0 +1,40 @@
+/**
+ * GitLab CI/CD intrinsic functions.
+ *
+ * GitLab CI has a single intrinsic: the !reference tag.
+ * CI/CD variables ($CI_*) are just strings, not intrinsic functions.
+ */
+
+import { INTRINSIC_MARKER, type Intrinsic } from "@intentius/chant/intrinsic";
+
+/**
+ * !reference tag intrinsic.
+ * References another job's properties: !reference [job_name, key]
+ */
+export class ReferenceIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private path: string[];
+
+  constructor(...path: string[]) {
+    this.path = path;
+  }
+
+  toJSON(): string[] {
+    return this.path;
+  }
+
+  /**
+   * YAML representation uses the !reference tag.
+   */
+  toYAML(): { tag: "!reference"; value: string[] } {
+    return { tag: "!reference", value: this.path };
+  }
+}
+
+/**
+ * Create a !reference intrinsic.
+ * Usage: reference("job_name", "script") → !reference [job_name, script]
+ */
+export function reference(...path: string[]): ReferenceIntrinsic {
+  return new ReferenceIntrinsic(...path);
+}

package/src/lint/post-synth/post-synth.test.ts

@@ -0,0 +1,155 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { wgl010 } from "./wgl010";
+import { wgl011 } from "./wgl011";
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+class MockJob implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "gitlab";
+  readonly entityType = "GitLab::CI::Job";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+function makeCtx(
+  yaml: string,
+  entities: Map<string, Declarable> = new Map(),
+): PostSynthContext {
+  return {
+    outputs: new Map([["gitlab", yaml]]),
+    entities,
+    buildResult: {
+      outputs: new Map([["gitlab", yaml]]),
+      entities,
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+// ── WGL010: Undefined stage ─────────────────────────────────────────
+
+describe("WGL010: undefined stage", () => {
+  test("flags job referencing undefined stage", () => {
+    const yaml = `stages:
+  - build
+  - test
+
+deploy-app:
+  stage: deploy
+  script:
+    - deploy.sh
+`;
+    const diags = wgl010.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL010");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("deploy");
+    expect(diags[0].message).toContain("deploy-app");
+  });
+
+  test("does not flag job with valid stage", () => {
+    const yaml = `stages:
+  - build
+  - test
+
+test-job:
+  stage: test
+  script:
+    - npm test
+`;
+    const diags = wgl010.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag when no stages are defined", () => {
+    const yaml = `test-job:
+  script:
+    - npm test
+`;
+    const diags = wgl010.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("flags multiple jobs with undefined stages", () => {
+    const yaml = `stages:
+  - build
+
+deploy-job:
+  stage: deploy
+  script:
+    - deploy.sh
+
+release-job:
+  stage: release
+  script:
+    - release.sh
+`;
+    const diags = wgl010.check(makeCtx(yaml));
+    expect(diags).toHaveLength(2);
+  });
+});
+
+// ── WGL011: Unreachable job ─────────────────────────────────────────
+
+describe("WGL011: unreachable job", () => {
+  test("flags job where all rules have when: never", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("neverJob", new MockJob({
+      script: ["test"],
+      rules: [
+        { when: "never" },
+        { when: "never" },
+      ],
+    }));
+
+    const diags = wgl011.check(makeCtx("", entities));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL011");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("neverJob");
+  });
+
+  test("does not flag job with reachable rules", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("okJob", new MockJob({
+      script: ["test"],
+      rules: [
+        { if: "$CI_COMMIT_BRANCH", when: "always" },
+        { when: "never" },
+      ],
+    }));
+
+    const diags = wgl011.check(makeCtx("", entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag job without rules", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("simpleJob", new MockJob({
+      script: ["test"],
+    }));
+
+    const diags = wgl011.check(makeCtx("", entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag job with empty rules array", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("emptyRulesJob", new MockJob({
+      script: ["test"],
+      rules: [],
+    }));
+
+    const diags = wgl011.check(makeCtx("", entities));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/wgl010.ts

@@ -0,0 +1,41 @@
+/**
+ * WGL010: Undefined stage
+ *
+ * Detects jobs that reference a stage not declared in the `stages:` list.
+ * This will cause a pipeline validation error in GitLab.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractStages, extractJobs } from "./yaml-helpers";
+
+export const wgl010: PostSynthCheck = {
+  id: "WGL010",
+  description: "Job references a stage not in the stages list",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const stages = extractStages(yaml);
+      if (stages.length === 0) continue; // No explicit stages — GitLab uses defaults
+
+      const stageSet = new Set(stages);
+      const jobs = extractJobs(yaml);
+
+      for (const [jobName, job] of jobs) {
+        if (job.stage && !stageSet.has(job.stage)) {
+          diagnostics.push({
+            checkId: "WGL010",
+            severity: "error",
+            message: `Job "${jobName}" references undefined stage "${job.stage}". Add it to the stages list.`,
+            entity: jobName,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};