@intentius/chant-lexicon-gitlab 0.0.1

package/src/codegen/fetch.ts

@@ -0,0 +1,73 @@
+/**
+ * GitLab CI schema fetching — downloads the CI JSON Schema
+ * and caches it locally.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache, clearCacheFile } from "@intentius/chant/codegen/fetch";
+
+/**
+ * Pinned schema version — a GitLab release tag that produces a known-good
+ * schema. Override at runtime with `--schema-version <tag>` in generate-cli
+ * or by setting `schemaVersion` in the generate options.
+ *
+ * Using a tag (e.g. "v17.8.1-ee") rather than `master` ensures reproducible
+ * codegen across environments and CI runs.
+ */
+export const GITLAB_SCHEMA_VERSION = "v17.8.1-ee";
+
+/**
+ * Build the schema URL for a given version ref.
+ */
+function schemaUrl(version: string): string {
+  return `https://gitlab.com/gitlab-org/gitlab/-/raw/${version}/app/assets/javascripts/editor/schema/ci.json`;
+}
+
+/**
+ * Get the cache file path for the CI schema.
+ */
+export function getCachePath(): string {
+  return join(homedir(), ".chant", "gitlab-ci-schema.json");
+}
+
+/**
+ * Fetch the GitLab CI JSON Schema, returning the raw JSON buffer.
+ * Uses local file caching with 24-hour TTL.
+ *
+ * @param force  Bypass cache and download fresh.
+ * @param version  GitLab ref (tag, branch, or SHA) to fetch from.
+ *                 Defaults to {@link GITLAB_SCHEMA_VERSION}.
+ */
+export async function fetchCISchema(force?: boolean, version?: string): Promise<Buffer> {
+  const ref = version ?? GITLAB_SCHEMA_VERSION;
+  return fetchWithCache(
+    {
+      url: schemaUrl(ref),
+      cacheFile: getCachePath(),
+    },
+    force,
+  );
+}
+
+/**
+ * Fetch the CI schema and return it as a Map<typeName, Buffer>
+ * compatible with the generatePipeline fetchSchemas callback.
+ *
+ * The CI schema is a single document, so we return a single entry
+ * keyed by "GitLab::CI::Pipeline" — the parse step will split it
+ * into multiple entities.
+ */
+export async function fetchSchemas(force?: boolean, version?: string): Promise<Map<string, Buffer>> {
+  const data = await fetchCISchema(force, version);
+  const schemas = new Map<string, Buffer>();
+  schemas.set("GitLab::CI::Pipeline", data);
+  return schemas;
+}
+
+/**
+ * Clear the cached schema file.
+ */
+export function clearCache(): void {
+  clearCacheFile(getCachePath());
+}

package/src/codegen/generate-cli.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point for GitLab CI lexicon generation.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate";
+import { GITLAB_SCHEMA_VERSION } from "./fetch";
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+async function main() {
+  const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+  const force = process.argv.includes("--force") || process.argv.includes("-f");
+
+  // Parse --schema-version <ref>
+  const versionIdx = process.argv.indexOf("--schema-version");
+  const schemaVersion = versionIdx !== -1 ? process.argv[versionIdx + 1] : undefined;
+
+  console.error(`Generating GitLab CI lexicon (schema: ${schemaVersion ?? GITLAB_SCHEMA_VERSION})...`);
+
+  const result = await generate({ verbose, force, schemaVersion });
+  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:`);
+    for (const w of result.warnings) {
+      console.error(`  ${w.file}: ${w.error}`);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error("Generation failed:", err);
+  process.exit(1);
+});

package/src/codegen/generate-lexicon.ts

@@ -0,0 +1,53 @@
+/**
+ * Lexicon JSON generator — produces lexicon-gitlab.json with metadata
+ * for all GitLab CI entities.
+ */
+
+import type { GitLabParseResult } from "./parse";
+import { gitlabShortName } from "./parse";
+import type { NamingStrategy } from "./naming";
+import {
+  buildRegistry,
+  serializeRegistry,
+  type RegistryResource,
+} from "@intentius/chant/codegen/generate-registry";
+
+export interface LexiconEntry {
+  resourceType: string;
+  kind: "resource" | "property";
+  lexicon: "gitlab";
+}
+
+/**
+ * Generate the lexicon-gitlab.json content.
+ */
+export function generateLexiconJSON(
+  results: GitLabParseResult[],
+  naming: NamingStrategy,
+): string {
+  const registryResources: RegistryResource[] = results.map((r) => ({
+    typeName: r.resource.typeName,
+    attributes: r.resource.attributes,
+    properties: r.resource.properties,
+    propertyTypes: r.propertyTypes.map((pt) => ({ name: pt.name, cfnType: pt.defType })),
+  }));
+
+  const entries = buildRegistry<LexiconEntry>(registryResources, naming, {
+    shortName: gitlabShortName,
+    buildEntry: (resource, _tsName, _attrs, _propConstraints) => {
+      const r = results.find((res) => res.resource.typeName === resource.typeName);
+      return {
+        resourceType: resource.typeName,
+        kind: (r?.isProperty ? "property" : "resource") as "resource" | "property",
+        lexicon: "gitlab" as const,
+      };
+    },
+    buildPropertyEntry: (resourceType, propertyType) => ({
+      resourceType: `${resourceType}.${propertyType}`,
+      kind: "property" as const,
+      lexicon: "gitlab" as const,
+    }),
+  });
+
+  return serializeRegistry(entries);
+}

package/src/codegen/generate-typescript.ts

@@ -0,0 +1,144 @@
+/**
+ * TypeScript declaration file generator — produces index.d.ts with all
+ * GitLab CI entity classes.
+ */
+
+import type { GitLabParseResult } from "./parse";
+import { gitlabShortName } from "./parse";
+import type { NamingStrategy } from "./naming";
+import { propertyTypeName, extractDefName } from "./naming";
+import {
+  writeResourceClass,
+  writePropertyClass,
+  writeEnumType,
+  type DtsProperty,
+  type DtsAttribute,
+} from "@intentius/chant/codegen/generate-typescript";
+
+interface ResourceEntry {
+  tsName: string;
+  properties: DtsProperty[];
+  attributes: DtsAttribute[];
+  remap: Map<string, string>;
+}
+
+interface EnumEntry {
+  tsName: string;
+  values: string[];
+}
+
+/**
+ * Generate the complete .d.ts file content.
+ */
+export function generateTypeScriptDeclarations(
+  results: GitLabParseResult[],
+  naming: NamingStrategy,
+): string {
+  const lines: string[] = [];
+  lines.push("// Code generated by chant gitlab generate. DO NOT EDIT.");
+
+  const resources: ResourceEntry[] = [];
+  const enums: EnumEntry[] = [];
+
+  for (const r of results) {
+    const typeName = r.resource.typeName;
+    const tsName = naming.resolve(typeName);
+    if (!tsName) continue;
+
+    const shortName = gitlabShortName(typeName);
+    const remap = new Map<string, string>();
+    for (const pt of r.propertyTypes) {
+      const defName = extractDefName(pt.name, shortName);
+      remap.set(pt.name, propertyTypeName(tsName, defName));
+    }
+    for (const e of r.enums) {
+      const defName = extractDefName(e.name, shortName);
+      remap.set(e.name, propertyTypeName(tsName, defName));
+    }
+
+    const dtsProps: DtsProperty[] = r.resource.properties.map((p) => ({
+      name: p.name,
+      type: p.tsType,
+      required: p.required,
+      description: p.description,
+    }));
+    const dtsAttrs: DtsAttribute[] = r.resource.attributes.map((a) => ({
+      name: a.name,
+      type: a.tsType,
+    }));
+
+    resources.push({ tsName, properties: dtsProps, attributes: dtsAttrs, remap });
+
+    for (const alias of naming.aliases(typeName)) {
+      resources.push({ tsName: alias, properties: dtsProps, attributes: dtsAttrs, remap });
+    }
+
+    for (const e of r.enums) {
+      const defName = extractDefName(e.name, shortName);
+      const eName = propertyTypeName(tsName, defName);
+      enums.push({ tsName: eName, values: e.values });
+    }
+  }
+
+  // Sort alphabetically
+  resources.sort((a, b) => a.tsName.localeCompare(b.tsName));
+  enums.sort((a, b) => a.tsName.localeCompare(b.tsName));
+
+  // Resource classes (all CI entities use writeResourceClass since they're
+  // all top-level — the "property" distinction is only in the registry)
+  lines.push("");
+  lines.push("// --- CI Entity classes ---");
+  for (const re of resources) {
+    writeResourceClass(lines, re.tsName, re.properties, re.attributes, re.remap);
+  }
+
+  // Enum types
+  if (enums.length > 0) {
+    lines.push("");
+    lines.push("// --- Enum types ---");
+    for (const ee of enums) {
+      writeEnumType(lines, ee.tsName, ee.values);
+    }
+  }
+
+  // Static content
+  lines.push("");
+  lines.push(staticTypeScript());
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function staticTypeScript(): string {
+  const lines: string[] = [];
+
+  lines.push("// --- CI/CD Variables ---");
+  lines.push("");
+  lines.push("export declare const CI: {");
+  const ciVars = [
+    "CommitBranch",
+    "CommitRef",
+    "CommitSha",
+    "CommitTag",
+    "DefaultBranch",
+    "Environment",
+    "JobId",
+    "JobName",
+    "JobStage",
+    "MergeRequestIid",
+    "PipelineId",
+    "PipelineSource",
+    "ProjectDir",
+    "ProjectId",
+    "ProjectName",
+    "ProjectPath",
+    "Registry",
+    "RegistryImage",
+  ];
+  for (const v of ciVars) {
+    lines.push(`  readonly ${v}: string;`);
+  }
+  lines.push("};");
+
+  return lines.join("\n");
+}

package/src/codegen/generate.ts

@@ -0,0 +1,166 @@
+/**
+ * GitLab CI generation pipeline — uses core generatePipeline
+ * with GitLab-specific fetch, parse, naming, and generation callbacks.
+ */
+
+import { join } from "path";
+import {
+  generatePipeline,
+  writeGeneratedArtifacts,
+  type GenerateOptions,
+  type GenerateResult,
+  type GeneratePipelineConfig,
+} from "@intentius/chant/codegen/generate";
+import { fetchSchemas } from "./fetch";
+import { parseCISchema, type GitLabParseResult } from "./parse";
+import { NamingStrategy, propertyTypeName, extractDefName } from "./naming";
+import { gitlabShortName } from "./parse";
+import { generateLexiconJSON } from "./generate-lexicon";
+import { generateTypeScriptDeclarations } from "./generate-typescript";
+import {
+  generateRuntimeIndex as coreGenerateRuntimeIndex,
+  type RuntimeIndexEntry,
+  type RuntimeIndexPropertyEntry,
+} from "@intentius/chant/codegen/generate-runtime-index";
+
+export type { GenerateResult };
+
+export interface GitLabGenerateOptions extends GenerateOptions {
+  /** GitLab ref (tag, branch, or SHA) to fetch the schema from. */
+  schemaVersion?: string;
+}
+
+// Captured from generate() call so the pipeline config can access it
+let activeSchemaVersion: string | undefined;
+
+const gitlabPipelineConfig: GeneratePipelineConfig<GitLabParseResult> = {
+  fetchSchemas: async (opts) => {
+    return fetchSchemas(opts.force, activeSchemaVersion);
+  },
+
+  parseSchema: (_typeName, data) => {
+    // The CI schema is a single document — parseCISchema returns multiple results.
+    // The pipeline calls this once per schema entry. We return the first result
+    // and use augmentResults to inject the rest.
+    const results = parseCISchema(data);
+    if (results.length === 0) return null;
+    // Return the first result; stash the rest for augmentResults
+    pendingResults = results.slice(1);
+    return results[0];
+  },
+
+  createNaming: (results) => new NamingStrategy(results),
+
+  augmentResults: (results, _opts, log) => {
+    // Add the remaining results from the single-schema parse
+    if (pendingResults.length > 0) {
+      results.push(...pendingResults);
+      log(`Added ${pendingResults.length} additional CI entities from single schema`);
+      pendingResults = [];
+    }
+    log(`Total: ${results.length} CI entity schemas`);
+    return { results };
+  },
+
+  generateRegistry: (results, naming) => {
+    return generateLexiconJSON(results, naming as NamingStrategy);
+  },
+
+  generateTypes: (results, naming) => {
+    return generateTypeScriptDeclarations(results, naming as NamingStrategy);
+  },
+
+  generateRuntimeIndex: (results, naming) => {
+    return generateRuntimeIndex(results, naming as NamingStrategy);
+  },
+};
+
+// Shared state between parseSchema and augmentResults
+let pendingResults: GitLabParseResult[] = [];
+
+/**
+ * Run the full GitLab generation pipeline.
+ */
+export async function generate(opts: GitLabGenerateOptions = {}): Promise<GenerateResult> {
+  pendingResults = [];
+  activeSchemaVersion = opts.schemaVersion;
+  return generatePipeline(gitlabPipelineConfig, opts);
+}
+
+/**
+ * Write generated artifacts to disk.
+ */
+export function writeGeneratedFiles(result: GenerateResult, baseDir: string): void {
+  writeGeneratedArtifacts({
+    baseDir,
+    files: {
+      "lexicon-gitlab.json": result.lexiconJSON,
+      "index.d.ts": result.typesDTS,
+      "index.ts": result.indexTS,
+      "runtime.ts": `/**\n * Runtime factory constructors — re-exported from core.\n */\nexport { createResource, createProperty } from "@intentius/chant/runtime";\n`,
+    },
+  });
+}
+
+/**
+ * Generate the runtime index.ts with factory constructor exports.
+ */
+function generateRuntimeIndex(
+  results: GitLabParseResult[],
+  naming: NamingStrategy,
+): string {
+  const resourceEntries: RuntimeIndexEntry[] = [];
+  const propertyEntries: RuntimeIndexPropertyEntry[] = [];
+
+  for (const r of results) {
+    const typeName = r.resource.typeName;
+    const tsName = naming.resolve(typeName);
+    if (!tsName) continue;
+
+    // CI entities have no read-only attributes
+    const attrs: Record<string, string> = {};
+
+    if (r.isProperty) {
+      // Property-kind entities (Artifacts, Cache, Image, etc.)
+      propertyEntries.push({ tsName, resourceType: typeName });
+      for (const alias of naming.aliases(typeName)) {
+        propertyEntries.push({ tsName: alias, resourceType: typeName });
+      }
+    } else {
+      // Resource-kind entities (Job, Default, Workflow)
+      resourceEntries.push({ tsName, resourceType: typeName, attrs });
+      for (const alias of naming.aliases(typeName)) {
+        resourceEntries.push({ tsName: alias, resourceType: typeName, attrs });
+      }
+    }
+
+    // Property types
+    const shortName = gitlabShortName(typeName);
+    const ptAliases = naming.propertyTypeAliases(typeName);
+    for (const pt of r.propertyTypes) {
+      const defName = extractDefName(pt.name, shortName);
+      const ptName = propertyTypeName(tsName, defName);
+      const ptType = `${typeName}.${pt.defType}`;
+      propertyEntries.push({ tsName: ptName, resourceType: ptType });
+
+      if (ptAliases) {
+        const aliasName = ptAliases.get(defName);
+        if (aliasName) {
+          propertyEntries.push({ tsName: aliasName, resourceType: ptType });
+        }
+      }
+    }
+  }
+
+  return coreGenerateRuntimeIndex(resourceEntries, propertyEntries, {
+    lexiconName: "gitlab",
+    intrinsicReExports: {
+      names: ["reference"],
+      from: "../intrinsics",
+    },
+    pseudoReExports: {
+      names: ["CI"],
+      from: "../variables",
+    },
+  });
+}

package/src/codegen/naming.ts

@@ -0,0 +1,52 @@
+/**
+ * GitLab CI naming strategy — simpler than AWS since CI entities
+ * use a flat GitLab::CI:: namespace with few collisions.
+ */
+
+import {
+  NamingStrategy as CoreNamingStrategy,
+  type NamingConfig,
+  type NamingInput,
+} from "@intentius/chant/codegen/naming";
+import { gitlabShortName, gitlabServiceName, type GitLabParseResult } from "./parse";
+
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+
+const gitlabNamingConfig: NamingConfig = {
+  priorityNames: {
+    "GitLab::CI::Job": "Job",
+    "GitLab::CI::Default": "Default",
+    "GitLab::CI::Workflow": "Workflow",
+    "GitLab::CI::Artifacts": "Artifacts",
+    "GitLab::CI::Cache": "Cache",
+    "GitLab::CI::Image": "Image",
+    "GitLab::CI::Rule": "Rule",
+    "GitLab::CI::Retry": "Retry",
+    "GitLab::CI::AllowFailure": "AllowFailure",
+    "GitLab::CI::Parallel": "Parallel",
+    "GitLab::CI::Include": "Include",
+    "GitLab::CI::Release": "Release",
+    "GitLab::CI::Environment": "Environment",
+    "GitLab::CI::Trigger": "Trigger",
+    "GitLab::CI::AutoCancel": "AutoCancel",
+  },
+  priorityAliases: {},
+  priorityPropertyAliases: {},
+  serviceAbbreviations: {},
+  shortName: gitlabShortName,
+  serviceName: gitlabServiceName,
+};
+
+/**
+ * GitLab-specific naming strategy.
+ * Extends core NamingStrategy with GitLab naming config.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+  constructor(results: GitLabParseResult[]) {
+    const inputs: NamingInput[] = results.map((r) => ({
+      typeName: r.resource.typeName,
+      propertyTypes: r.propertyTypes,
+    }));
+    super(inputs, gitlabNamingConfig);
+  }
+}

package/src/codegen/package.ts

@@ -0,0 +1,64 @@
+/**
+ * GitLab lexicon packaging — delegates to core packagePipeline
+ * with GitLab-specific manifest building and skill collection.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import type { IntrinsicDef } from "@intentius/chant/lexicon";
+import {
+  packagePipeline,
+  collectSkills,
+  type PackageOptions,
+  type PackageResult,
+} from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+
+export type { PackageOptions, PackageResult };
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Package the GitLab lexicon into a distributable BundleSpec.
+ */
+export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
+  const pkgJson = JSON.parse(readFileSync(join(pkgDir, "..", "package.json"), "utf-8"));
+
+  return packagePipeline(
+    {
+      generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+
+      buildManifest: (_genResult) => {
+        const intrinsics: IntrinsicDef[] = [
+          {
+            name: "reference",
+            description: "!reference tag — reference another job's properties",
+            outputKey: "!reference",
+            isTag: true,
+          },
+        ];
+
+        return {
+          name: "gitlab",
+          version: pkgJson.version ?? "0.0.0",
+          chantVersion: ">=0.1.0",
+          namespace: "GitLab",
+          intrinsics,
+          pseudoParameters: {},
+        };
+      },
+
+      srcDir: pkgDir,
+
+      collectSkills: () => {
+        const { gitlabPlugin } = require("../plugin");
+        const skillDefs = gitlabPlugin.skills?.() ?? [];
+        return collectSkills(skillDefs);
+      },
+
+      version: pkgJson.version ?? "0.0.0",
+    },
+    opts,
+  );
+}