@intentius/chant-lexicon-gitlab 0.0.1

package/src/codegen/patches.ts

@@ -0,0 +1,100 @@
+/**
+ * Schema augmentation patches for GitLab CI JSON Schema.
+ *
+ * The official GitLab CI schema sometimes has gaps, missing properties,
+ * or incorrect types. Patches are applied after fetch but before parse
+ * to fix these issues.
+ */
+
+/**
+ * A targeted fix for a schema definition.
+ */
+export interface SchemaPatch {
+  /** Human-readable description of what this patch fixes */
+  description: string;
+  /** JSON path to the definition to patch (e.g. "definitions.job_template") */
+  path: string;
+  /** Function that applies the patch to the definition */
+  apply(def: Record<string, unknown>): void;
+}
+
+/**
+ * Registry of known schema patches.
+ */
+export const schemaPatches: SchemaPatch[] = [
+  {
+    description: "Add 'pages' property type to job_template if missing",
+    path: "definitions.job_template",
+    apply(def) {
+      const props = def.properties as Record<string, unknown> | undefined;
+      if (props && !props.pages) {
+        props.pages = {
+          description: "GitLab Pages configuration for publishing static sites.",
+          oneOf: [
+            { type: "object", properties: { publish: { type: "string" } } },
+            { type: "boolean" },
+          ],
+        };
+      }
+    },
+  },
+  {
+    description: "Add 'manual_confirmation' property to job_template if missing",
+    path: "definitions.job_template",
+    apply(def) {
+      const props = def.properties as Record<string, unknown> | undefined;
+      if (props && !props.manual_confirmation) {
+        props.manual_confirmation = {
+          type: "string",
+          description: "Confirmation message displayed when a manual job is triggered.",
+        };
+      }
+    },
+  },
+  {
+    description: "Add 'inputs' property to job_template if missing",
+    path: "definitions.job_template",
+    apply(def) {
+      const props = def.properties as Record<string, unknown> | undefined;
+      if (props && !props.inputs) {
+        props.inputs = {
+          type: "object",
+          description: "Input parameters for CI/CD component jobs.",
+          additionalProperties: true,
+        };
+      }
+    },
+  },
+];
+
+/**
+ * Apply all registered patches to a parsed schema.
+ * Modifies the schema in place.
+ */
+export function applyPatches(schema: Record<string, unknown>): { applied: string[]; skipped: string[] } {
+  const applied: string[] = [];
+  const skipped: string[] = [];
+
+  for (const patch of schemaPatches) {
+    const segments = patch.path.split(".");
+    let target: Record<string, unknown> | undefined = schema;
+
+    for (const segment of segments) {
+      if (target && typeof target === "object" && segment in target) {
+        target = target[segment] as Record<string, unknown>;
+      } else {
+        target = undefined;
+        break;
+      }
+    }
+
+    if (target) {
+      patch.apply(target);
+      applied.push(patch.description);
+    } else {
+      skipped.push(`${patch.description} (path "${patch.path}" not found)`);
+    }
+  }
+
+  return { applied, skipped };
+}

package/src/codegen/rollback.ts

@@ -0,0 +1,26 @@
+/**
+ * Rollback and snapshot management for GitLab CI lexicon.
+ *
+ * Wraps the core rollback module with GitLab-specific artifact names.
+ */
+
+export type { ArtifactSnapshot, SnapshotInfo } from "@intentius/chant/codegen/rollback";
+export {
+  snapshotArtifacts,
+  saveSnapshot,
+  restoreSnapshot,
+  listSnapshots,
+} from "@intentius/chant/codegen/rollback";
+
+/**
+ * GitLab-specific artifact filenames to snapshot.
+ */
+export const GITLAB_ARTIFACT_NAMES = ["lexicon-gitlab.json", "index.d.ts", "index.ts"];
+
+/**
+ * Snapshot GitLab lexicon artifacts.
+ */
+export function snapshotGitLabArtifacts(generatedDir: string) {
+  const { snapshotArtifacts } = require("@intentius/chant/codegen/rollback");
+  return snapshotArtifacts(generatedDir, GITLAB_ARTIFACT_NAMES);
+}

package/src/codegen/snapshot.test.ts

@@ -0,0 +1,109 @@
+import { describe, test, expect } from "bun:test";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const generatedDir = join(dirname(dirname(fileURLToPath(import.meta.url))), "generated");
+
+describe("generated lexicon-gitlab.json", () => {
+  const content = readFileSync(join(generatedDir, "lexicon-gitlab.json"), "utf-8");
+  const registry = JSON.parse(content);
+
+  test("is valid JSON with expected entries", () => {
+    expect(Object.keys(registry)).toHaveLength(15);
+  });
+
+  test("contains all resource entities", () => {
+    expect(registry.Job).toBeDefined();
+    expect(registry.Job.kind).toBe("resource");
+    expect(registry.Job.resourceType).toBe("GitLab::CI::Job");
+    expect(registry.Job.lexicon).toBe("gitlab");
+
+    expect(registry.Default).toBeDefined();
+    expect(registry.Default.kind).toBe("resource");
+
+    expect(registry.Workflow).toBeDefined();
+    expect(registry.Workflow.kind).toBe("resource");
+  });
+
+  test("contains all property entities", () => {
+    const propertyNames = [
+      "AllowFailure", "Artifacts", "AutoCancel", "Cache",
+      "Environment", "Image", "Include", "Parallel",
+      "Release", "Retry", "Rule", "Trigger",
+    ];
+    for (const name of propertyNames) {
+      expect(registry[name]).toBeDefined();
+      expect(registry[name].kind).toBe("property");
+      expect(registry[name].lexicon).toBe("gitlab");
+    }
+  });
+
+  test("entries match snapshot", () => {
+    expect(registry.Job).toMatchSnapshot();
+    expect(registry.Artifacts).toMatchSnapshot();
+    expect(registry.Cache).toMatchSnapshot();
+    expect(registry.Image).toMatchSnapshot();
+  });
+});
+
+describe("generated index.d.ts", () => {
+  const content = readFileSync(join(generatedDir, "index.d.ts"), "utf-8");
+
+  test("contains all class declarations", () => {
+    const expectedClasses = [
+      "Job", "Default", "Workflow",
+      "AllowFailure", "Artifacts", "AutoCancel", "Cache",
+      "Environment", "Image", "Include", "Parallel",
+      "Release", "Retry", "Rule", "Trigger",
+    ];
+    for (const cls of expectedClasses) {
+      expect(content).toContain(`export declare class ${cls}`);
+    }
+  });
+
+  test("contains CI variables declaration", () => {
+    expect(content).toContain("export declare const CI");
+    expect(content).toContain("readonly CommitBranch: string");
+    expect(content).toContain("readonly CommitSha: string");
+    expect(content).toContain("readonly PipelineId: string");
+  });
+
+  test("Job class has key properties in constructor", () => {
+    // Extract the Job class declaration
+    const jobMatch = content.match(/export declare class Job \{[\s\S]*?\n\}/);
+    expect(jobMatch).toBeDefined();
+    const jobDecl = jobMatch![0];
+    expect(jobDecl).toContain("script");
+    expect(jobDecl).toContain("stage");
+    expect(jobDecl).toContain("image");
+    expect(jobDecl).toContain("artifacts");
+    expect(jobDecl).toContain("cache");
+  });
+});
+
+describe("generated index.ts", () => {
+  const content = readFileSync(join(generatedDir, "index.ts"), "utf-8");
+
+  test("has correct resource createResource calls", () => {
+    expect(content).toContain('createResource("GitLab::CI::Default"');
+    expect(content).toContain('createResource("GitLab::CI::Job"');
+    expect(content).toContain('createResource("GitLab::CI::Workflow"');
+  });
+
+  test("has correct property createProperty calls", () => {
+    expect(content).toContain('createProperty("GitLab::CI::Artifacts"');
+    expect(content).toContain('createProperty("GitLab::CI::Cache"');
+    expect(content).toContain('createProperty("GitLab::CI::Image"');
+    expect(content).toContain('createProperty("GitLab::CI::Rule"');
+  });
+
+  test("re-exports reference and CI", () => {
+    expect(content).toContain('export { reference } from "../intrinsics"');
+    expect(content).toContain('export { CI } from "../variables"');
+  });
+
+  test("imports from runtime", () => {
+    expect(content).toContain('from "./runtime"');
+  });
+});

package/src/coverage.test.ts

@@ -0,0 +1,39 @@
+import { describe, test, expect } from "bun:test";
+import { computeCoverage, overallPct, formatSummary } from "./coverage";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const basePath = dirname(dirname(fileURLToPath(import.meta.url)));
+const lexiconJSON = readFileSync(join(basePath, "src", "generated", "lexicon-gitlab.json"), "utf-8");
+
+describe("coverage analysis", () => {
+  test("computes coverage for GitLab lexicon", () => {
+    const report = computeCoverage(lexiconJSON);
+    expect(report.resourceCount).toBe(3); // Job, Default, Workflow
+    expect(report.resources).toHaveLength(3);
+  });
+
+  test("reports resource names correctly", () => {
+    const report = computeCoverage(lexiconJSON);
+    const names = report.resources.map((r) => r.name);
+    expect(names).toContain("Job");
+    expect(names).toContain("Default");
+    expect(names).toContain("Workflow");
+  });
+
+  test("overallPct returns a number", () => {
+    const report = computeCoverage(lexiconJSON);
+    const pct = overallPct(report);
+    expect(typeof pct).toBe("number");
+    expect(pct).toBeGreaterThanOrEqual(0);
+    expect(pct).toBeLessThanOrEqual(100);
+  });
+
+  test("formatSummary returns readable string", () => {
+    const report = computeCoverage(lexiconJSON);
+    const summary = formatSummary(report);
+    expect(summary).toContain("Coverage Report");
+    expect(summary).toContain("3 resources");
+  });
+});

package/src/coverage.ts

@@ -0,0 +1,52 @@
+/**
+ * Coverage analysis for GitLab CI lexicon.
+ *
+ * Measures how many of the CI schema's definitions are covered
+ * by the generated lexicon entities.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  computeCoverage,
+  overallPct,
+  formatSummary,
+  formatVerbose,
+  checkThresholds,
+  type CoverageReport,
+  type CoverageThresholds,
+} from "@intentius/chant/codegen/coverage";
+
+export type { CoverageReport, CoverageThresholds };
+export { computeCoverage, overallPct, formatSummary, formatVerbose, checkThresholds };
+
+/**
+ * Run coverage analysis for the GitLab lexicon.
+ */
+export async function analyzeGitLabCoverage(opts?: {
+  basePath?: string;
+  verbose?: boolean;
+  minOverall?: number;
+}): Promise<CoverageReport> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  const lexiconPath = join(basePath, "src", "generated", "lexicon-gitlab.json");
+  const content = readFileSync(lexiconPath, "utf-8");
+  const report = computeCoverage(content);
+
+  if (opts?.verbose) {
+    console.error(formatVerbose(report));
+  } else {
+    console.error(formatSummary(report));
+  }
+
+  if (typeof opts?.minOverall === "number") {
+    const result = checkThresholds(report, { minOverallPct: opts.minOverall });
+    if (!result.ok) {
+      for (const v of result.violations) console.error(`  FAIL: ${v}`);
+      throw new Error("Coverage below threshold");
+    }
+  }
+
+  return report;
+}

package/src/generated/index.d.ts

@@ -0,0 +1,248 @@
+// Code generated by chant gitlab generate. DO NOT EDIT.
+
+// --- CI Entity classes ---
+
+export declare class AllowFailure {
+  constructor(props: {
+    exit_codes: number;
+  });
+}
+
+export declare class Artifacts {
+  constructor(props: {
+    access?: "none" | "developer" | "all";
+    exclude?: string[];
+    expire_in?: string;
+    expose_as?: string;
+    name?: string;
+    paths?: string[];
+    reports?: Record<string, unknown>;
+    untracked?: boolean;
+    when?: "on_success" | "on_failure" | "always";
+  });
+}
+
+export declare class AutoCancel {
+  constructor(props: {
+    on_job_failure?: "none" | "all";
+    on_new_commit?: "conservative" | "interruptible" | "none";
+  });
+}
+
+export declare class Cache {
+  constructor(props: {
+    fallback_keys?: string[];
+    key?: string | Record<string, any>;
+    paths?: string[];
+    policy?: string;
+    unprotect?: boolean;
+    untracked?: boolean;
+    when?: "on_success" | "on_failure" | "always";
+  });
+}
+
+export declare class Default {
+  constructor(props: {
+    after_script?: string | string[];
+    artifacts?: Artifacts;
+    before_script?: string | string[];
+    cache?: Cache | Cache[];
+    hooks?: Record<string, unknown>;
+    id_tokens?: Record<string, unknown>;
+    identity?: "google_cloud";
+    image?: Image;
+    interruptible?: boolean;
+    retry?: Retry | number;
+    services?: Service[];
+    tags?: any[];
+    timeout?: string;
+  });
+}
+
+export declare class Environment {
+  constructor(props: {
+    /** The name of the environment, e.g. 'qa', 'staging', 'production'. */
+    name: string;
+    /** Specifies what this job will do. 'start' (default) indicates the job will start the deployment. 'prepare'/'verify'/'access' indicates this will not affect the deployment. 'stop' indicates this will stop the deployment. */
+    action?: "start" | "prepare" | "stop" | "verify" | "access";
+    /** The amount of time it should take before Gitlab will automatically stop the environment. Supports a wide variety of formats, e.g. '1 week', '3 mins 4 sec', '2 hrs 20 min', '2h20min', '6 mos 1 day', '47 yrs 6 mos and 4d', '3 weeks and 2 days'. */
+    auto_stop_in?: string;
+    /** Explicitly specifies the tier of the deployment environment if non-standard environment name is used. */
+    deployment_tier?: "production" | "staging" | "testing" | "development" | "other";
+    /** Used to configure the kubernetes deployment for this environment. This is currently not supported for kubernetes clusters that are managed by Gitlab. */
+    kubernetes?: Record<string, unknown>;
+    /** The name of a job to execute when the environment is about to be stopped. */
+    on_stop?: string;
+    /** When set, this will expose buttons in various places for the current environment in Gitlab, that will take you to the defined URL. */
+    url?: string;
+  });
+}
+
+export declare class Image {
+  constructor(props: {
+    /** Full name of the image that should be used. It should contain the Registry part if needed. */
+    name: string;
+    docker?: Record<string, unknown>;
+    /** Command or script that should be executed as the container's entrypoint. It will be translated to Docker's --entrypoint option while creating the container. The syntax is similar to Dockerfile's ENTRYPOINT directive, where each shell token is a separate string in the array. */
+    entrypoint?: any[];
+    pull_policy?: "always" | "never" | "if-not-present" | "always" | "never" | "if-not-present"[];
+  });
+}
+
+export declare class Include {
+  constructor(props: {
+    file: string | string[];
+    /** Path to the project, e.g. `group/project`, or `group/sub-group/project` [Learn more](https://docs.gitlab.com/ee/ci/yaml/index.html#includefile). */
+    project: string;
+    inputs?: Record<string, unknown>;
+    /** Branch/Tag/Commit-hash for the target project. */
+    ref?: string;
+    rules?: any[];
+  });
+}
+
+export declare class Job {
+  constructor(props: {
+    after_script?: string | string[];
+    allow_failure?: AllowFailure | boolean;
+    artifacts?: Artifacts;
+    before_script?: string | string[];
+    cache?: Cache | Cache[];
+    /** Must be a regular expression, optionally but recommended to be quoted, and must be surrounded with '/'. Example: '/Code coverage: \d+\.\d+/' */
+    coverage?: string;
+    /** Specify a list of job names from earlier stages from which artifacts should be loaded. By default, all previous artifacts are passed. Use an empty array to skip downloading artifacts. */
+    dependencies?: string[];
+    /** Used to associate environment metadata with a deploy. Environment can have a name and URL attached to it, and will be displayed under /environments under the project. */
+    environment?: string | Record<string, any>;
+    /** Job will run *except* for when these filtering options match. */
+    except?: any;
+    /** The name of one or more jobs to inherit configuration from. */
+    extends?: string | string[];
+    hooks?: Record<string, unknown>;
+    id_tokens?: Record<string, unknown>;
+    identity?: "google_cloud";
+    image?: Image;
+    inherit?: Record<string, unknown>;
+    interruptible?: boolean;
+    manual_confirmation?: string;
+    /** The list of jobs in previous stages whose sole completion is needed to start the current job. */
+    needs?: string | Record<string, any> | any[][];
+    /** Job will run *only* when these filtering options match. */
+    only?: any;
+    pages?: Record<string, any> | boolean;
+    parallel?: Parallel | number;
+    /** A path to a directory that contains the files to be published with Pages */
+    publish?: string;
+    /** Indicates that the job creates a Release. */
+    release?: Record<string, unknown>;
+    /** Limit job concurrency. Can be used to ensure that the Runner will not run certain jobs simultaneously. */
+    resource_group?: string;
+    retry?: Retry | number;
+    rules?: Rule[];
+    run?: any[];
+    script?: string | string[];
+    secrets?: Record<string, unknown>;
+    services?: Service[];
+    /** Define what stage the job will run in. */
+    stage?: string | string[];
+    start_in?: string;
+    tags?: any[];
+    timeout?: string;
+    trigger?: Record<string, any> | string;
+    variables?: Record<string, unknown>;
+    when?: "on_success" | "on_failure" | "always" | "never" | "manual" | "delayed";
+  });
+}
+
+export declare class Parallel {
+  constructor(props: {
+    /** Defines different variables for jobs that are running in parallel. */
+    matrix: Record<string, unknown>[];
+  });
+}
+
+export declare class Release {
+  constructor(props: {
+    /** Specifies the longer description of the Release. */
+    description: string;
+    /** The tag_name must be specified. It can refer to an existing Git tag or can be specified by the user. */
+    tag_name: string;
+    assets?: Record<string, unknown>;
+    /** The title of each milestone the release is associated with. */
+    milestones?: string[];
+    /** The Release name. If omitted, it is populated with the value of release: tag_name. */
+    name?: string;
+    /** If the release: tag_name doesn’t exist yet, the release is created from ref. ref can be a commit SHA, another tag name, or a branch name. */
+    ref?: string;
+    /** The date and time when the release is ready. Defaults to the current date and time if not defined. Should be enclosed in quotes and expressed in ISO 8601 format. */
+    released_at?: string;
+    /** Message to use if creating a new annotated tag. */
+    tag_message?: string;
+  });
+}
+
+export declare class Retry {
+  constructor(props: {
+    exit_codes?: number[] | number;
+    max?: number;
+    when?: any[];
+  });
+}
+
+export declare class Rule {
+  constructor(props: {
+    allow_failure?: AllowFailure | boolean;
+    changes?: any;
+    exists?: any;
+    if?: string;
+    interruptible?: boolean;
+    needs?: any[];
+    start_in?: string;
+    variables?: Record<string, unknown>;
+    when?: "on_success" | "on_failure" | "always" | "never" | "manual" | "delayed";
+  });
+}
+
+export declare class Trigger {
+  constructor(props: {
+    /** Path to the project, e.g. `group/project`, or `group/sub-group/project`. */
+    project: string;
+    /** The branch name that a downstream pipeline will use */
+    branch?: string;
+    /** Specify what to forward to the downstream pipeline. */
+    forward?: Record<string, unknown>;
+    /** You can mirror the pipeline status from the triggered pipeline to the source bridge job by using strategy: depend */
+    strategy?: "depend";
+  });
+}
+
+export declare class Workflow {
+  constructor(props: {
+    auto_cancel?: AutoCancel;
+    name?: string;
+    rules?: Record<string, any> | string[][];
+  });
+}
+
+// --- CI/CD Variables ---
+
+export declare const CI: {
+  readonly CommitBranch: string;
+  readonly CommitRef: string;
+  readonly CommitSha: string;
+  readonly CommitTag: string;
+  readonly DefaultBranch: string;
+  readonly Environment: string;
+  readonly JobId: string;
+  readonly JobName: string;
+  readonly JobStage: string;
+  readonly MergeRequestIid: string;
+  readonly PipelineId: string;
+  readonly PipelineSource: string;
+  readonly ProjectDir: string;
+  readonly ProjectId: string;
+  readonly ProjectName: string;
+  readonly ProjectPath: string;
+  readonly Registry: string;
+  readonly RegistryImage: string;
+};

package/src/generated/index.ts

@@ -0,0 +1,23 @@
+// Code generated by chant generate. DO NOT EDIT.
+import { createResource, createProperty } from "./runtime";
+
+export const Default = createResource("GitLab::CI::Default", "gitlab", {});
+export const Job = createResource("GitLab::CI::Job", "gitlab", {});
+export const Workflow = createResource("GitLab::CI::Workflow", "gitlab", {});
+
+export const AllowFailure = createProperty("GitLab::CI::AllowFailure", "gitlab");
+export const Artifacts = createProperty("GitLab::CI::Artifacts", "gitlab");
+export const AutoCancel = createProperty("GitLab::CI::AutoCancel", "gitlab");
+export const Cache = createProperty("GitLab::CI::Cache", "gitlab");
+export const Environment = createProperty("GitLab::CI::Environment", "gitlab");
+export const Image = createProperty("GitLab::CI::Image", "gitlab");
+export const Include = createProperty("GitLab::CI::Include", "gitlab");
+export const Parallel = createProperty("GitLab::CI::Parallel", "gitlab");
+export const Release = createProperty("GitLab::CI::Release", "gitlab");
+export const Retry = createProperty("GitLab::CI::Retry", "gitlab");
+export const Rule = createProperty("GitLab::CI::Rule", "gitlab");
+export const Trigger = createProperty("GitLab::CI::Trigger", "gitlab");
+
+// Re-exports for convenience
+export { reference } from "../intrinsics";
+export { CI } from "../variables";

package/src/generated/lexicon-gitlab.json

@@ -0,0 +1,77 @@
+{
+  "AllowFailure": {
+    "resourceType": "GitLab::CI::AllowFailure",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Artifacts": {
+    "resourceType": "GitLab::CI::Artifacts",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "AutoCancel": {
+    "resourceType": "GitLab::CI::AutoCancel",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Cache": {
+    "resourceType": "GitLab::CI::Cache",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Default": {
+    "resourceType": "GitLab::CI::Default",
+    "kind": "resource",
+    "lexicon": "gitlab"
+  },
+  "Environment": {
+    "resourceType": "GitLab::CI::Environment",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Image": {
+    "resourceType": "GitLab::CI::Image",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Include": {
+    "resourceType": "GitLab::CI::Include",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Job": {
+    "resourceType": "GitLab::CI::Job",
+    "kind": "resource",
+    "lexicon": "gitlab"
+  },
+  "Parallel": {
+    "resourceType": "GitLab::CI::Parallel",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Release": {
+    "resourceType": "GitLab::CI::Release",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Retry": {
+    "resourceType": "GitLab::CI::Retry",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Rule": {
+    "resourceType": "GitLab::CI::Rule",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Trigger": {
+    "resourceType": "GitLab::CI::Trigger",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
+  "Workflow": {
+    "resourceType": "GitLab::CI::Workflow",
+    "kind": "resource",
+    "lexicon": "gitlab"
+  }
+}

package/src/generated/runtime.ts

@@ -0,0 +1,4 @@
+/**
+ * Runtime factory constructors — re-exported from core.
+ */
+export { createResource, createProperty } from "@intentius/chant/runtime";