@intentius/chant-lexicon-gitlab 0.0.1

package/src/plugin.ts

@@ -0,0 +1,380 @@
+/**
+ * GitLab CI/CD lexicon plugin.
+ *
+ * Provides serializer, template detection, and code generation
+ * for GitLab CI/CD pipelines.
+ */
+
+import type { LexiconPlugin, IntrinsicDef, SkillDefinition } from "@intentius/chant/lexicon";
+import type { LintRule } from "@intentius/chant/lint/rule";
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import { gitlabSerializer } from "./serializer";
+
+export const gitlabPlugin: LexiconPlugin = {
+  name: "gitlab",
+  serializer: gitlabSerializer,
+
+  lintRules(): LintRule[] {
+    const { deprecatedOnlyExceptRule } = require("./lint/rules/deprecated-only-except");
+    const { missingScriptRule } = require("./lint/rules/missing-script");
+    const { missingStageRule } = require("./lint/rules/missing-stage");
+    const { artifactNoExpiryRule } = require("./lint/rules/artifact-no-expiry");
+    return [deprecatedOnlyExceptRule, missingScriptRule, missingStageRule, artifactNoExpiryRule];
+  },
+
+  postSynthChecks(): PostSynthCheck[] {
+    const { wgl010 } = require("./lint/post-synth/wgl010");
+    const { wgl011 } = require("./lint/post-synth/wgl011");
+    return [wgl010, wgl011];
+  },
+
+  intrinsics(): IntrinsicDef[] {
+    return [
+      {
+        name: "reference",
+        description: "!reference tag — reference another job's properties",
+        outputKey: "!reference",
+        isTag: true,
+      },
+    ];
+  },
+
+  initTemplates(): Record<string, string> {
+    return {
+      "_.ts": `export * from "./config";\n`,
+      "config.ts": `/**
+ * Shared pipeline configuration
+ */
+
+import * as gl from "@intentius/chant-lexicon-gitlab";
+
+// Default image for all jobs
+export const defaultImage = new gl.Image({
+  name: "node:20-alpine",
+});
+
+// Standard cache configuration
+export const npmCache = new gl.Cache({
+  key: "$CI_COMMIT_REF_SLUG",
+  paths: ["node_modules/"],
+  policy: "pull-push",
+});
+`,
+      "test.ts": `/**
+ * Test job
+ */
+
+import * as gl from "@intentius/chant-lexicon-gitlab";
+import * as _ from "./_";
+
+export const test = new gl.Job({
+  stage: "test",
+  image: _.defaultImage,
+  cache: _.npmCache,
+  script: ["npm ci", "npm test"],
+  artifacts: new gl.Artifacts({
+    reports: { junit: "coverage/junit.xml" },
+    paths: ["coverage/"],
+    expireIn: "1 week",
+  }),
+});
+`,
+    };
+  },
+
+  detectTemplate(data: unknown): boolean {
+    if (typeof data !== "object" || data === null) return false;
+    const obj = data as Record<string, unknown>;
+
+    // GitLab CI files typically have stages, or job-like top-level keys
+    if (Array.isArray(obj.stages)) return true;
+    if (obj.image !== undefined && obj.script !== undefined) return true;
+
+    // Check for job-like entries (objects with "stage" or "script" properties)
+    for (const value of Object.values(obj)) {
+      if (typeof value === "object" && value !== null) {
+        const entry = value as Record<string, unknown>;
+        if (entry.stage !== undefined || entry.script !== undefined) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  },
+
+  completionProvider(ctx: import("@intentius/chant/lsp/types").CompletionContext) {
+    const { gitlabCompletions } = require("./lsp/completions");
+    return gitlabCompletions(ctx);
+  },
+
+  hoverProvider(ctx: import("@intentius/chant/lsp/types").HoverContext) {
+    const { gitlabHover } = require("./lsp/hover");
+    return gitlabHover(ctx);
+  },
+
+  templateParser() {
+    const { GitLabParser } = require("./import/parser");
+    return new GitLabParser();
+  },
+
+  templateGenerator() {
+    const { GitLabGenerator } = require("./import/generator");
+    return new GitLabGenerator();
+  },
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate, writeGeneratedFiles } = await import("./codegen/generate");
+    const { dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const result = await generate({ verbose: options?.verbose ?? true });
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeGeneratedFiles(result, pkgDir);
+
+    console.error(
+      `Generated ${result.resources} entities, ${result.properties} property types, ${result.enums} enums`,
+    );
+    if (result.warnings.length > 0) {
+      console.error(`${result.warnings.length} warnings`);
+    }
+  },
+
+  async validate(options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const result = await validate();
+
+    for (const check of result.checks) {
+      const status = check.ok ? "OK" : "FAIL";
+      const msg = check.error ? ` — ${check.error}` : "";
+      console.error(`  [${status}] ${check.name}${msg}`);
+    }
+
+    if (!result.success) {
+      throw new Error("Validation failed");
+    }
+    console.error("All validation checks passed.");
+  },
+
+  async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    const { analyzeGitLabCoverage } = await import("./coverage");
+    await analyzeGitLabCoverage({
+      verbose: options?.verbose,
+      minOverall: options?.minOverall,
+    });
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeFileSync, mkdirSync } = await import("fs");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon({ verbose: options?.verbose, force: options?.force });
+
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const distDir = join(pkgDir, "dist");
+    mkdirSync(join(distDir, "types"), { recursive: true });
+    mkdirSync(join(distDir, "rules"), { recursive: true });
+    mkdirSync(join(distDir, "skills"), { recursive: true });
+
+    writeFileSync(join(distDir, "manifest.json"), JSON.stringify(spec.manifest, null, 2));
+    writeFileSync(join(distDir, "meta.json"), spec.registry);
+    writeFileSync(join(distDir, "types", "index.d.ts"), spec.typesDTS);
+
+    for (const [name, content] of spec.rules) {
+      writeFileSync(join(distDir, "rules", name), content);
+    }
+    for (const [name, content] of spec.skills) {
+      writeFileSync(join(distDir, "skills", name), content);
+    }
+
+    if (spec.integrity) {
+      writeFileSync(join(distDir, "integrity.json"), JSON.stringify(spec.integrity, null, 2));
+    }
+
+    console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  async rollback(options?: { restore?: string; verbose?: boolean }): Promise<void> {
+    const { listSnapshots, restoreSnapshot } = await import("./codegen/rollback");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const snapshotsDir = join(pkgDir, ".snapshots");
+
+    if (options?.restore) {
+      const generatedDir = join(pkgDir, "src", "generated");
+      restoreSnapshot(String(options.restore), generatedDir);
+      console.error(`Restored snapshot: ${options.restore}`);
+    } else {
+      const snapshots = listSnapshots(snapshotsDir);
+      if (snapshots.length === 0) {
+        console.error("No snapshots available.");
+      } else {
+        console.error(`Available snapshots (${snapshots.length}):`);
+        for (const s of snapshots) {
+          console.error(`  ${s.timestamp}  ${s.resourceCount} resources  ${s.path}`);
+        }
+      }
+    }
+  },
+
+  mcpTools() {
+    return [
+      {
+        name: "diff",
+        description: "Compare current build output against previous output for GitLab CI",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            path: {
+              type: "string",
+              description: "Path to the infrastructure project directory",
+            },
+          },
+        },
+        async handler(params: Record<string, unknown>): Promise<unknown> {
+          const { diffCommand } = await import("@intentius/chant/cli/commands/diff");
+          const result = await diffCommand({
+            path: (params.path as string) ?? ".",
+            serializers: [gitlabSerializer],
+          });
+          return result;
+        },
+      },
+    ];
+  },
+
+  mcpResources() {
+    return [
+      {
+        uri: "resource-catalog",
+        name: "GitLab CI Entity Catalog",
+        description: "JSON list of all supported GitLab CI entity types",
+        mimeType: "application/json",
+        async handler(): Promise<string> {
+          const lexicon = require("./generated/lexicon-gitlab.json") as Record<string, { resourceType: string; kind: string }>;
+          const entries = Object.entries(lexicon).map(([className, entry]) => ({
+            className,
+            resourceType: entry.resourceType,
+            kind: entry.kind,
+          }));
+          return JSON.stringify(entries);
+        },
+      },
+      {
+        uri: "examples/basic-pipeline",
+        name: "Basic Pipeline Example",
+        description: "A basic GitLab CI pipeline with build, test, and deploy stages",
+        mimeType: "text/typescript",
+        async handler(): Promise<string> {
+          return `import { Job, Image, Cache, Artifacts, CI } from "@intentius/chant-lexicon-gitlab";
+
+export const build = new Job({
+  stage: "build",
+  image: new Image({ name: "node:20" }),
+  cache: new Cache({ key: CI.CommitRef, paths: ["node_modules/"] }),
+  script: ["npm ci", "npm run build"],
+  artifacts: new Artifacts({ paths: ["dist/"], expireIn: "1 day" }),
+});
+
+export const test = new Job({
+  stage: "test",
+  image: new Image({ name: "node:20" }),
+  cache: new Cache({ key: CI.CommitRef, paths: ["node_modules/"], policy: "pull" }),
+  script: ["npm ci", "npm test"],
+  artifacts: new Artifacts({
+    reports: { junit: "coverage/junit.xml" },
+    expireIn: "1 week",
+  }),
+});
+
+export const deploy = new Job({
+  stage: "deploy",
+  script: ["./deploy.sh"],
+  rules: [{ if: "$CI_COMMIT_BRANCH == \\"main\\"", when: "manual" }],
+});
+`;
+        },
+      },
+    ];
+  },
+
+  async docs(options?: { verbose?: boolean }): Promise<void> {
+    const { generateDocs } = await import("./codegen/docs");
+    await generateDocs(options);
+  },
+
+  skills(): SkillDefinition[] {
+    return [
+      {
+        name: "gitlab-ci",
+        description: "GitLab CI/CD best practices and common patterns",
+        content: `---
+name: gitlab-ci
+description: GitLab CI/CD best practices and common patterns
+---
+
+# GitLab CI/CD with Chant
+
+## Common Entity Types
+
+- \`Job\` — Pipeline job definition
+- \`Default\` — Default settings inherited by all jobs
+- \`Workflow\` — Pipeline-level configuration
+- \`Artifacts\` — Job artifact configuration
+- \`Cache\` — Cache configuration
+- \`Image\` — Docker image for a job
+- \`Rule\` — Conditional execution rule
+- \`Environment\` — Deployment environment
+- \`Trigger\` — Trigger downstream pipeline
+- \`Include\` — Include external CI configuration
+
+## Predefined Variables
+
+- \`CI.CommitBranch\` — Current branch name
+- \`CI.CommitSha\` — Current commit SHA
+- \`CI.PipelineSource\` — What triggered the pipeline
+- \`CI.ProjectPath\` — Project path (group/project)
+- \`CI.Registry\` — Container registry URL
+- \`CI.MergeRequestIid\` — MR internal ID
+
+## Best Practices
+
+1. **Use stages** — Organize jobs into logical stages (build, test, deploy)
+2. **Cache dependencies** — Cache node_modules, pip packages, etc.
+3. **Use rules** — Prefer \`rules:\` over \`only:/except:\` for conditional execution
+4. **Minimize artifacts** — Only preserve files needed by later stages
+5. **Use includes** — Share common configuration across projects
+6. **Set timeouts** — Prevent stuck jobs from blocking pipelines
+`,
+        triggers: [
+          { type: "file-pattern", value: "**/*.gitlab.ts" },
+          { type: "context", value: "gitlab" },
+        ],
+        parameters: [],
+        examples: [
+          {
+            title: "Basic test job",
+            description: "Create a test job with caching and artifacts",
+            input: "Create a test job",
+            output: `new Job({
+  stage: "test",
+  image: new Image({ name: "node:20" }),
+  script: ["npm ci", "npm test"],
+  cache: new Cache({
+    key: "$CI_COMMIT_REF_SLUG",
+    paths: ["node_modules/"],
+  }),
+  artifacts: new Artifacts({
+    reports: { junit: "coverage/junit.xml" },
+  }),
+})`,
+          },
+        ],
+      },
+    ];
+  },
+};

package/src/serializer.test.ts

@@ -0,0 +1,309 @@
+import { describe, test, expect } from "bun:test";
+import { gitlabSerializer } from "./serializer";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+
+// ── Mock entities ──────────────────────────────────────────────────
+
+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;
+  }
+}
+
+class MockDefault implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "gitlab";
+  readonly entityType = "GitLab::CI::Default";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+class MockWorkflow implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "gitlab";
+  readonly entityType = "GitLab::CI::Workflow";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+class MockPropertyEntity implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "gitlab";
+  readonly entityType: string;
+  readonly kind = "property" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(entityType: string, props: Record<string, unknown> = {}) {
+    this.entityType = entityType;
+    this.props = props;
+  }
+}
+
+// ── Tests ──────────────────────────────────────────────────────────
+
+describe("gitlabSerializer", () => {
+  test("has correct name", () => {
+    expect(gitlabSerializer.name).toBe("gitlab");
+  });
+
+  test("has correct rulePrefix", () => {
+    expect(gitlabSerializer.rulePrefix).toBe("WGL");
+  });
+});
+
+describe("gitlabSerializer.serialize", () => {
+  test("serializes empty entities", () => {
+    const entities = new Map<string, Declarable>();
+    const output = gitlabSerializer.serialize(entities);
+    // Empty pipeline should produce minimal output
+    expect(output).toBe("\n");
+  });
+
+  test("serializes a simple job", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("testJob", new MockJob({
+      stage: "test",
+      script: ["npm test"],
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("stages:");
+    expect(output).toContain("- test");
+    expect(output).toContain("test-job:");
+    expect(output).toContain("script:");
+    expect(output).toContain("- npm test");
+  });
+
+  test("collects stages from all jobs", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("buildJob", new MockJob({ stage: "build", script: ["make"] }));
+    entities.set("testJob", new MockJob({ stage: "test", script: ["npm test"] }));
+    entities.set("deployJob", new MockJob({ stage: "deploy", script: ["deploy.sh"] }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("stages:");
+    expect(output).toContain("- build");
+    expect(output).toContain("- test");
+    expect(output).toContain("- deploy");
+  });
+
+  test("deduplicates stages", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("jobA", new MockJob({ stage: "build", script: ["build1"] }));
+    entities.set("jobB", new MockJob({ stage: "build", script: ["build2"] }));
+
+    const output = gitlabSerializer.serialize(entities);
+    // "build" should appear only once in the stages list
+    const stagesSection = output.split("\n\n")[0]; // stages is the first section
+    const stagesMatch = stagesSection.match(/- build/g);
+    expect(stagesMatch).toHaveLength(1);
+  });
+
+  test("converts camelCase job names to kebab-case", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("myTestJob", new MockJob({ script: ["test"] }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("my-test-job:");
+  });
+
+  test("converts camelCase property keys to snake_case", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("job", new MockJob({
+      beforeScript: ["echo hello"],
+      afterScript: ["echo done"],
+      expireIn: "1 week",
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("before_script:");
+    expect(output).toContain("after_script:");
+    expect(output).toContain("expire_in:");
+  });
+
+  test("serializes default settings", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("defaults", new MockDefault({
+      interruptible: true,
+      timeout: "30 minutes",
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("default:");
+    expect(output).toContain("interruptible: true");
+    // "30 minutes" starts with a digit, so it gets quoted
+    expect(output).toContain("timeout: '30 minutes'");
+  });
+
+  test("serializes workflow", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("workflow", new MockWorkflow({
+      name: "My Pipeline",
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("workflow:");
+    expect(output).toContain("name: My Pipeline");
+  });
+
+  test("skips property-kind declarables", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("myImage", new MockPropertyEntity("GitLab::CI::Image", { name: "node:20" }));
+
+    const output = gitlabSerializer.serialize(entities);
+    // Property entities are embedded inline, not serialized as top-level
+    expect(output).toBe("\n");
+  });
+
+  test("omits properties not present in props", () => {
+    const entities = new Map<string, Declarable>();
+    // Only set script — image and cache are not in props at all
+    entities.set("job", new MockJob({
+      script: ["test"],
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).not.toContain("image:");
+    expect(output).not.toContain("cache:");
+  });
+
+  test("serializes multi-job pipeline with defaults and workflow", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("defaults", new MockDefault({
+      image: "node:20",
+    }));
+    entities.set("workflow", new MockWorkflow({
+      name: "CI Pipeline",
+    }));
+    entities.set("lint", new MockJob({ stage: "test", script: ["npm run lint"] }));
+    entities.set("test", new MockJob({ stage: "test", script: ["npm test"] }));
+    entities.set("deploy", new MockJob({ stage: "deploy", script: ["deploy.sh"] }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("stages:");
+    expect(output).toContain("default:");
+    expect(output).toContain("workflow:");
+    expect(output).toContain("lint:");
+    expect(output).toContain("test:");
+    expect(output).toContain("deploy:");
+  });
+});
+
+describe("string quoting", () => {
+  test("quotes strings starting with $", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("job", new MockJob({
+      script: ["$CI_COMMIT_SHA"],
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    // String starting with $ should be quoted
+    expect(output).toContain("'$CI_COMMIT_SHA'");
+  });
+
+  test("quotes strings starting with *", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("job", new MockJob({
+      script: ["*glob"],
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("'*glob'");
+  });
+
+  test("quotes strings containing :", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("job", new MockJob({
+      script: ["key: value"],
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("'key: value'");
+  });
+
+  test("quotes YAML boolean-like strings", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("job", new MockJob({
+      variables: { FLAG: "true", OTHER: "false", MAYBE: "null" },
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("'true'");
+    expect(output).toContain("'false'");
+    expect(output).toContain("'null'");
+  });
+
+  test("does not quote plain strings", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("job", new MockJob({
+      stage: "test",
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("stage: test");
+  });
+});
+
+describe("nested objects and arrays", () => {
+  test("serializes nested objects", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("job", new MockJob({
+      variables: {
+        NODE_ENV: "production",
+        CI: "true",
+      },
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("variables:");
+    expect(output).toContain("node_env: production");
+  });
+
+  test("serializes arrays of strings", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("job", new MockJob({
+      script: ["npm ci", "npm test", "npm run build"],
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("- npm ci");
+    expect(output).toContain("- npm test");
+    expect(output).toContain("- npm run build");
+  });
+
+  test("serializes boolean values", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("job", new MockJob({
+      interruptible: true,
+      allowFailure: false,
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("interruptible: true");
+    expect(output).toContain("allow_failure: false");
+  });
+
+  test("serializes numeric values", () => {
+    const entities = new Map<string, Declarable>();
+    entities.set("job", new MockJob({
+      parallel: 5,
+    }));
+
+    const output = gitlabSerializer.serialize(entities);
+    expect(output).toContain("parallel: 5");
+  });
+});