@intentius/chant-lexicon-gitlab 0.0.6 → 0.0.9

package/src/codegen/__snapshots__/snapshot.test.ts.snap

@@ -2,6 +2,12 @@
 
 exports[`generated lexicon-gitlab.json entries match snapshot 1`] = `
 {
+  "constraints": {
+    "coverage": {
+      "format": "regex",
+      "pattern": "^/.+/$",
+    },
+  },
   "kind": "resource",
   "lexicon": "gitlab",
   "resourceType": "GitLab::CI::Job",
@@ -10,6 +16,30 @@ exports[`generated lexicon-gitlab.json entries match snapshot 1`] = `
 
 exports[`generated lexicon-gitlab.json entries match snapshot 2`] = `
 {
+  "constraints": {
+    "access": {
+      "default": "all",
+      "enum": [
+        "none",
+        "developer",
+        "all",
+      ],
+    },
+    "expire_in": {
+      "default": "30 days",
+    },
+    "untracked": {
+      "default": false,
+    },
+    "when": {
+      "default": "on_success",
+      "enum": [
+        "on_success",
+        "on_failure",
+        "always",
+      ],
+    },
+  },
   "kind": "property",
   "lexicon": "gitlab",
   "resourceType": "GitLab::CI::Artifacts",
@@ -18,6 +48,26 @@ exports[`generated lexicon-gitlab.json entries match snapshot 2`] = `
 
 exports[`generated lexicon-gitlab.json entries match snapshot 3`] = `
 {
+  "constraints": {
+    "policy": {
+      "default": "pull-push",
+      "pattern": "pull-push|pull|push|\\$\\w{1,255}",
+    },
+    "unprotect": {
+      "default": false,
+    },
+    "untracked": {
+      "default": false,
+    },
+    "when": {
+      "default": "on_success",
+      "enum": [
+        "on_success",
+        "on_failure",
+        "always",
+      ],
+    },
+  },
   "kind": "property",
   "lexicon": "gitlab",
   "resourceType": "GitLab::CI::Cache",
@@ -26,6 +76,14 @@ exports[`generated lexicon-gitlab.json entries match snapshot 3`] = `
 
 exports[`generated lexicon-gitlab.json entries match snapshot 4`] = `
 {
+  "constraints": {
+    "name": {
+      "minLength": 1,
+    },
+    "pull_policy": {
+      "default": "always",
+    },
+  },
   "kind": "property",
   "lexicon": "gitlab",
   "resourceType": "GitLab::CI::Image",

package/src/codegen/docs.ts

@@ -58,8 +58,7 @@ The generated file includes:
 | Chant (TypeScript) | YAML output | Rule |
 |--------------------|-------------|------|
 | \`export const buildApp = new Job({...})\` | \`build-app:\` | Export name → kebab-case job key |
-| \`expireIn: "1 week"\` | \`expire_in: 1 week\` | camelCase → snake_case |
-| \`ifCondition: ...\` | \`if: ...\` | Reserved word properties use suffixed names |
+| \`expire_in: "1 week"\` | \`expire_in: 1 week\` | Property names use spec-native snake_case |
 | \`new Image({ name: "node:20" })\` | \`image: node:20\` | Single-property objects are collapsed |
 
 ## Validating locally
@@ -108,7 +107,7 @@ export async function generateDocs(opts?: { verbose?: boolean }): Promise<void>
         description: "Jobs, stages, artifacts, caching, images, rules, environments, and triggers in the GitLab CI/CD lexicon",
         content: `Every exported \`Job\` declaration becomes a job entry in the generated \`.gitlab-ci.yml\`. The serializer handles the translation automatically:
 
-- Converts camelCase property names to snake_case (\`expireIn\` → \`expire_in\`)
+- Property names use spec-native snake_case (\`expire_in\`, \`allow_failure\`)
 - Converts export names to kebab-case job keys (\`buildApp\` → \`build-app\`)
 - Collects stages from all jobs into a \`stages:\` list
 - Collapses single-property objects (\`new Image({ name: "node:20" })\` → \`image: node:20\`)
@@ -162,7 +161,7 @@ The lexicon provides 3 resource types and 13 property types:
 
 Extract reusable objects into a shared config file and import them across your pipeline files:
 
-{{file:docs-snippets/src/pipeline-barrel.ts}}
+{{file:docs-snippets/src/pipeline-shared-config.ts}}
 
 ## Jobs
 
@@ -339,9 +338,9 @@ lint:
     - npm run lint
 \`\`\`
 
-### When to use \`reference()\` vs barrel imports
+### When to use \`reference()\` vs direct imports
 
-{{file:docs-snippets/src/reference-vs-barrel.ts}}
+{{file:docs-snippets/src/reference-vs-import.ts}}
 `,
       },
       {
@@ -404,6 +403,30 @@ Flags jobs where all \`rules:\` entries have \`when: "never"\`, making the job u
 
 {{file:docs-snippets/src/lint-wgl011.ts}}
 
+### WGL012 — Deprecated property usage
+
+**Severity:** warning
+
+Flags properties marked as deprecated in the GitLab CI schema. Deprecation signals are mined from property descriptions (keywords like "deprecated", "legacy", "no longer available"). Using deprecated properties may cause unexpected behavior in future GitLab versions.
+
+### WGL013 — Invalid \`needs:\` target
+
+**Severity:** error
+
+Flags jobs whose \`needs:\` entries reference a job not defined in the pipeline, or reference themselves. Both cause GitLab pipeline validation failures. When \`include:\` is present, the check is skipped since needed jobs may come from included files.
+
+### WGL014 — Invalid \`extends:\` target
+
+**Severity:** error
+
+Flags jobs whose \`extends:\` references a template or hidden job not defined in the pipeline. GitLab rejects pipelines with unresolved extends references. When \`include:\` is present, the check is skipped since templates may come from included files.
+
+### WGL015 — Circular \`needs:\` chain
+
+**Severity:** error
+
+Detects cycles in the \`needs:\` dependency graph. If job A needs B and B needs A (directly or transitively), GitLab rejects the pipeline. Reports the full cycle chain in the diagnostic message.
+
 ## Running lint
 
 \`\`\`bash
@@ -532,13 +555,67 @@ deploy:
 
 **Patterns demonstrated:**
 
-1. **Barrel file** — single import point for lexicon types and shared config
-2. **Shared config** — reusable images, caches, artifacts, and rules extracted into \`config.ts\`
-3. **Conditional execution** — merge request and branch rules control when jobs run
-4. **Manual deployment** — deploy requires manual trigger on the default branch
-5. **JUnit reports** — test artifacts include JUnit XML for GitLab MR display
+1. **Shared config** — reusable images, caches, artifacts, and rules extracted into \`config.ts\`
+2. **Conditional execution** — merge request and branch rules control when jobs run
+3. **Manual deployment** — deploy requires manual trigger on the default branch
+4. **JUnit reports** — test artifacts include JUnit XML for GitLab MR display
 `,
       },
+      {
+        slug: "skills",
+        title: "AI Skills",
+        description: "AI agent skills bundled with the GitLab CI/CD lexicon",
+        content: `The GitLab lexicon ships an AI skill called **chant-gitlab** that teaches AI coding agents (like Claude Code) how to build, validate, and deploy GitLab CI pipelines from a chant project.
+
+## What are skills?
+
+Skills are structured markdown documents bundled with a lexicon. When an AI agent works in a chant project, it discovers and loads relevant skills automatically — giving it operational knowledge about the deployment workflow without requiring the user to explain each step.
+
+## Installation
+
+When you scaffold a new project with \`chant init --lexicon gitlab\`, the skill is installed to \`.claude/skills/chant-gitlab/SKILL.md\` for automatic discovery by Claude Code.
+
+For existing projects, create the file manually:
+
+\`\`\`
+.claude/
+  skills/
+    chant-gitlab/
+      SKILL.md    # skill content (see below)
+\`\`\`
+
+## Skill: chant-gitlab
+
+The \`chant-gitlab\` skill covers the full deployment lifecycle:
+
+- **Build** — \`chant build src/ --output .gitlab-ci.yml\`
+- **Validate** — \`chant lint src/\` + GitLab CI Lint API
+- **Deploy** — commit and push the generated YAML
+- **Status** — GitLab UI or pipelines API
+- **Retry** — retry failed jobs via UI or API
+- **Cancel** — cancel running pipelines via API
+- **Troubleshooting** — job logs, lint rule codes (WGL001–WGL004), post-synth checks (WGL010–WGL015)
+
+The skill is invocable as a slash command: \`/chant-gitlab\`
+
+## MCP integration
+
+The lexicon also provides MCP (Model Context Protocol) tools and resources that AI agents can use programmatically:
+
+| MCP tool | Description |
+|----------|-------------|
+| \`build\` | Build the chant project |
+| \`lint\` | Run lint rules |
+| \`explain\` | Summarize project resources |
+| \`scaffold\` | Generate starter files |
+| \`search\` | Search available resource types |
+| \`gitlab:diff\` | Compare current build output against previous |
+
+| MCP resource | Description |
+|--------------|-------------|
+| \`resource-catalog\` | JSON list of all supported GitLab CI entity types |
+| \`examples/basic-pipeline\` | Example pipeline with build, test, and deploy jobs |`,
+      },
     ],
     basePath: "/chant/lexicons/gitlab/",
   };

package/src/codegen/generate-lexicon.ts

@@ -3,6 +3,7 @@
  * for all GitLab CI entities.
  */
 
+import type { PropertyConstraints } from "@intentius/chant/codegen/json-schema";
 import type { GitLabParseResult } from "./parse";
 import { gitlabShortName } from "./parse";
 import type { NamingStrategy } from "./naming";
@@ -16,6 +17,8 @@ export interface LexiconEntry {
   resourceType: string;
   kind: "resource" | "property";
   lexicon: "gitlab";
+  deprecatedProperties?: string[];
+  constraints?: Record<string, PropertyConstraints>;
 }
 
 /**
@@ -34,12 +37,14 @@ export function generateLexiconJSON(
 
   const entries = buildRegistry<LexiconEntry>(registryResources, naming, {
     shortName: gitlabShortName,
-    buildEntry: (resource, _tsName, _attrs, _propConstraints) => {
+    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,
+        ...(r?.resource.deprecatedProperties?.length && { deprecatedProperties: r.resource.deprecatedProperties }),
+        ...(propConstraints && Object.keys(propConstraints).length > 0 && { constraints: propConstraints }),
       };
     },
     buildPropertyEntry: (resourceType, propertyType) => ({

package/src/codegen/generate.ts

@@ -30,61 +30,56 @@ export interface GitLabGenerateOptions extends GenerateOptions {
   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 };
-  },
+/**
+ * Run the full GitLab generation pipeline.
+ */
+export async function generate(opts: GitLabGenerateOptions = {}): Promise<GenerateResult> {
+  // Pipeline state captured in closure — no module-level mutation
+  let pendingResults: GitLabParseResult[] = [];
 
-  generateRegistry: (results, naming) => {
-    return generateLexiconJSON(results, naming as NamingStrategy);
-  },
+  const config: GeneratePipelineConfig<GitLabParseResult> = {
+    fetchSchemas: async (fetchOpts) => {
+      return fetchSchemas(fetchOpts.force, opts.schemaVersion);
+    },
 
-  generateTypes: (results, naming) => {
-    return generateTypeScriptDeclarations(results, naming as NamingStrategy);
-  },
+    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];
+    },
 
-  generateRuntimeIndex: (results, naming) => {
-    return generateRuntimeIndex(results, naming as NamingStrategy);
-  },
-};
+    createNaming: (results) => new NamingStrategy(results),
 
-// Shared state between parseSchema and augmentResults
-let pendingResults: GitLabParseResult[] = [];
+    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 };
+    },
 
-/**
- * Run the full GitLab generation pipeline.
- */
-export async function generate(opts: GitLabGenerateOptions = {}): Promise<GenerateResult> {
-  pendingResults = [];
-  activeSchemaVersion = opts.schemaVersion;
-  return generatePipeline(gitlabPipelineConfig, opts);
+    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);
+    },
+  };
+
+  return generatePipeline(config, opts);
 }
 
 /**

package/src/codegen/naming.ts

@@ -29,6 +29,9 @@ const gitlabNamingConfig: NamingConfig = {
     "GitLab::CI::Environment": "Environment",
     "GitLab::CI::Trigger": "Trigger",
     "GitLab::CI::AutoCancel": "AutoCancel",
+    "GitLab::CI::WorkflowRule": "WorkflowRule",
+    "GitLab::CI::Need": "Need",
+    "GitLab::CI::Inherit": "Inherit",
   },
   priorityAliases: {},
   priorityPropertyAliases: {},

package/src/codegen/package.ts

@@ -3,7 +3,9 @@
  * with GitLab-specific manifest building and skill collection.
  */
 
+import { createRequire } from "module";
 import { readFileSync } from "fs";
+const require = createRequire(import.meta.url);
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import type { IntrinsicDef } from "@intentius/chant/lexicon";

package/src/codegen/parse.test.ts

@@ -5,9 +5,9 @@ import { loadSchemaFixture } from "../testdata/load-fixtures";
 const fixture = loadSchemaFixture();
 
 describe("parseCISchema", () => {
-  test("returns 16 entities", () => {
+  test("returns 19 entities", () => {
     const results = parseCISchema(fixture);
-    expect(results).toHaveLength(16);
+    expect(results).toHaveLength(19);
   });
 
   test("returns 3 resource entities", () => {
@@ -20,10 +20,10 @@ describe("parseCISchema", () => {
     expect(names).toContain("GitLab::CI::Workflow");
   });
 
-  test("returns 13 property entities", () => {
+  test("returns 16 property entities", () => {
     const results = parseCISchema(fixture);
     const properties = results.filter((r) => r.isProperty);
-    expect(properties).toHaveLength(13);
+    expect(properties).toHaveLength(16);
     const names = properties.map((r) => r.resource.typeName);
     expect(names).toContain("GitLab::CI::Artifacts");
     expect(names).toContain("GitLab::CI::Cache");
@@ -38,6 +38,9 @@ describe("parseCISchema", () => {
     expect(names).toContain("GitLab::CI::Environment");
     expect(names).toContain("GitLab::CI::Trigger");
     expect(names).toContain("GitLab::CI::AutoCancel");
+    expect(names).toContain("GitLab::CI::WorkflowRule");
+    expect(names).toContain("GitLab::CI::Need");
+    expect(names).toContain("GitLab::CI::Inherit");
   });
 
   test("property entities have isProperty set to true", () => {
@@ -125,6 +128,108 @@ describe("Cache entity", () => {
   });
 });
 
+describe("spec conformance — type mappings", () => {
+  const results = parseCISchema(fixture);
+  const findEntity = (name: string) => results.find((r) => r.resource.typeName === `GitLab::CI::${name}`);
+  const findProp = (entityName: string, propName: string) =>
+    findEntity(entityName)?.resource.properties.find((p) => p.name === propName);
+
+  test("Job.environment → Environment | string", () => {
+    expect(findProp("Job", "environment")?.tsType).toBe("Environment | string");
+  });
+
+  test("Job.trigger → Trigger | string", () => {
+    expect(findProp("Job", "trigger")?.tsType).toBe("Trigger | string");
+  });
+
+  test("Job.release → Release", () => {
+    expect(findProp("Job", "release")?.tsType).toBe("Release");
+  });
+
+  test("Job.needs → Need[]", () => {
+    expect(findProp("Job", "needs")?.tsType).toBe("Need[]");
+  });
+
+  test("Job.inherit → Inherit", () => {
+    expect(findProp("Job", "inherit")?.tsType).toBe("Inherit");
+  });
+
+  test("Workflow.rules → WorkflowRule[]", () => {
+    expect(findProp("Workflow", "rules")?.tsType).toBe("WorkflowRule[]");
+  });
+
+  test("AllowFailure.exit_codes → number | number[]", () => {
+    expect(findProp("AllowFailure", "exit_codes")?.tsType).toBe("number | number[]");
+  });
+
+  test("Image.pull_policy has no duplicate enum values", () => {
+    const pp = findProp("Image", "pull_policy");
+    expect(pp).toBeDefined();
+    // Should be clean union with parens on array form
+    expect(pp!.tsType).toContain("always");
+    expect(pp!.tsType).toContain("never");
+    expect(pp!.tsType).toContain("if-not-present");
+    // Array variant should use parens
+    expect(pp!.tsType).toContain(")[]");
+  });
+
+  test("Include has local, remote, template, component fields", () => {
+    const include = findEntity("Include");
+    expect(include).toBeDefined();
+    const propNames = include!.resource.properties.map((p) => p.name);
+    expect(propNames).toContain("project");
+    expect(propNames).toContain("file");
+    expect(propNames).toContain("local");
+    expect(propNames).toContain("remote");
+    expect(propNames).toContain("template");
+    expect(propNames).toContain("component");
+  });
+
+  test("Trigger has include field for child pipelines", () => {
+    const trigger = findEntity("Trigger");
+    expect(trigger).toBeDefined();
+    const propNames = trigger!.resource.properties.map((p) => p.name);
+    expect(propNames).toContain("project");
+    expect(propNames).toContain("include");
+    expect(propNames).toContain("strategy");
+    expect(propNames).toContain("forward");
+  });
+
+  test("Need has merged properties from all object variants", () => {
+    const need = findEntity("Need");
+    expect(need).toBeDefined();
+    const propNames = need!.resource.properties.map((p) => p.name);
+    expect(propNames).toContain("job");
+    expect(propNames).toContain("artifacts");
+    expect(propNames).toContain("project");
+    expect(propNames).toContain("ref");
+    expect(propNames).toContain("pipeline");
+    expect(propNames).toContain("optional");
+    // job should be required (in all object variants)
+    const jobProp = need!.resource.properties.find((p) => p.name === "job");
+    expect(jobProp?.required).toBe(true);
+  });
+
+  test("WorkflowRule has restricted when enum", () => {
+    const wr = findEntity("WorkflowRule");
+    expect(wr).toBeDefined();
+    const propNames = wr!.resource.properties.map((p) => p.name);
+    expect(propNames).toContain("if");
+    expect(propNames).toContain("when");
+    expect(propNames).toContain("auto_cancel");
+    const whenProp = wr!.resource.properties.find((p) => p.name === "when");
+    expect(whenProp?.tsType).toBe('"always" | "never"');
+  });
+
+  test("Inherit has default and variables properties", () => {
+    const inherit = findEntity("Inherit");
+    expect(inherit).toBeDefined();
+    const propNames = inherit!.resource.properties.map((p) => p.name);
+    expect(propNames).toContain("default");
+    expect(propNames).toContain("variables");
+  });
+});
+
 describe("property types and enums", () => {
   test("entities have empty propertyTypes (nested types extracted as top-level)", () => {
     const results = parseCISchema(fixture);
@@ -141,6 +246,51 @@ describe("property types and enums", () => {
   });
 });
 
+describe("deprecatedProperties", () => {
+  test("all entities have a deprecatedProperties array", () => {
+    const results = parseCISchema(fixture);
+    for (const r of results) {
+      expect(Array.isArray(r.resource.deprecatedProperties)).toBe(true);
+    }
+  });
+
+  test("mines deprecation from property description", () => {
+    const schema = JSON.stringify({
+      definitions: {
+        job_template: {
+          properties: {
+            script: { type: "string" },
+            oldProp: { type: "string", description: "Deprecated in 12.0: use newProp instead." },
+            newProp: { type: "string", description: "The replacement property" },
+          },
+        },
+      },
+    });
+    const results = parseCISchema(schema);
+    const job = results.find((r) => r.resource.typeName === "GitLab::CI::Job");
+    expect(job).toBeDefined();
+    expect(job!.resource.deprecatedProperties).toContain("oldProp");
+    expect(job!.resource.deprecatedProperties).not.toContain("newProp");
+    expect(job!.resource.deprecatedProperties).not.toContain("script");
+  });
+
+  test("empty deprecatedProperties when no deprecation signals", () => {
+    const schema = JSON.stringify({
+      definitions: {
+        job_template: {
+          properties: {
+            script: { type: "string", description: "Commands to run" },
+            stage: { type: "string", description: "Pipeline stage" },
+          },
+        },
+      },
+    });
+    const results = parseCISchema(schema);
+    const job = results.find((r) => r.resource.typeName === "GitLab::CI::Job");
+    expect(job!.resource.deprecatedProperties).toEqual([]);
+  });
+});
+
 describe("edge cases", () => {
   test("empty schema returns empty results", () => {
     const emptySchema = JSON.stringify({ definitions: {} });