@intentius/chant-lexicon-gitlab 0.0.8 → 0.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "license": "Apache-2.0",
   "type": "module",
   "files": ["src/", "dist/"],
@@ -21,7 +21,7 @@
   "prepack": "bun run bundle && bun run validate"
 },
 "dependencies": {
-  "@intentius/chant": "0.0.5"
+  "@intentius/chant": "0.0.9"
 },
 "devDependencies": {
   "typescript": "^5.9.3"

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

@@ -161,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
 
@@ -338,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}}
 `,
       },
       {
@@ -403,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
@@ -531,11 +555,10 @@ 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
 `,
       },
       {
@@ -571,7 +594,7 @@ The \`chant-gitlab\` skill covers the full deployment lifecycle:
 - **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, WGL011)
+- **Troubleshooting** — job logs, lint rule codes (WGL001–WGL004), post-synth checks (WGL010–WGL015)
 
 The skill is invocable as a slash command: \`/chant-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/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: {} });