@intentius/chant-lexicon-gitlab 0.0.8 → 0.0.10

package/dist/integrity.json

@@ -1,17 +1,21 @@
 {
   "algorithm": "xxhash64",
   "artifacts": {
-    "manifest.json": "3a48cdeca93a7a4d",
-    "meta.json": "9ee0d2f2d1679f09",
-    "types/index.d.ts": "4e56a7de40d655c0",
+    "manifest.json": "592bb8cd37d44fed",
+    "meta.json": "c663c6c63748a9d0",
+    "types/index.d.ts": "64e65524615be023",
     "rules/missing-stage.ts": "6d5379e74209a735",
     "rules/missing-script.ts": "923dde9acb46cc28",
     "rules/deprecated-only-except.ts": "1f5a8c785777fb03",
     "rules/artifact-no-expiry.ts": "26874cb6adfbca26",
     "rules/wgl011.ts": "b6b97e5104d91267",
-    "rules/yaml-helpers.ts": "a66cc193b4ef4f0a",
+    "rules/wgl015.ts": "d7e9e080994f985",
+    "rules/wgl012.ts": "3d188d13fb2236c0",
+    "rules/yaml-helpers.ts": "1f3c4e98b89b8deb",
     "rules/wgl010.ts": "1548cad287cdf286",
-    "skills/chant-gitlab.md": "92ce73e97ee82ac9"
+    "rules/wgl014.ts": "6248a852888e8028",
+    "rules/wgl013.ts": "3519c933e23fc605",
+    "skills/chant-gitlab.md": "4393eb63e0b84b7f"
   },
-  "composite": "c6ad87f69da787de"
+  "composite": "6c4db775282a1a38"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gitlab",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "chantVersion": ">=0.1.0",
   "namespace": "GitLab",
   "intrinsics": [

package/dist/meta.json

@@ -7,17 +7,77 @@
   "Artifacts": {
     "resourceType": "GitLab::CI::Artifacts",
     "kind": "property",
-    "lexicon": "gitlab"
+    "lexicon": "gitlab",
+    "constraints": {
+      "untracked": {
+        "default": false
+      },
+      "when": {
+        "default": "on_success",
+        "enum": [
+          "on_success",
+          "on_failure",
+          "always"
+        ]
+      },
+      "access": {
+        "default": "all",
+        "enum": [
+          "none",
+          "developer",
+          "all"
+        ]
+      },
+      "expire_in": {
+        "default": "30 days"
+      }
+    }
   },
   "AutoCancel": {
     "resourceType": "GitLab::CI::AutoCancel",
     "kind": "property",
-    "lexicon": "gitlab"
+    "lexicon": "gitlab",
+    "constraints": {
+      "on_job_failure": {
+        "default": "none",
+        "enum": [
+          "none",
+          "all"
+        ]
+      },
+      "on_new_commit": {
+        "enum": [
+          "conservative",
+          "interruptible",
+          "none"
+        ]
+      }
+    }
   },
   "Cache": {
     "resourceType": "GitLab::CI::Cache",
     "kind": "property",
-    "lexicon": "gitlab"
+    "lexicon": "gitlab",
+    "constraints": {
+      "policy": {
+        "pattern": "pull-push|pull|push|\\$\\w{1,255}",
+        "default": "pull-push"
+      },
+      "unprotect": {
+        "default": false
+      },
+      "untracked": {
+        "default": false
+      },
+      "when": {
+        "default": "on_success",
+        "enum": [
+          "on_success",
+          "on_failure",
+          "always"
+        ]
+      }
+    }
   },
   "Default": {
     "resourceType": "GitLab::CI::Default",
@@ -27,21 +87,93 @@
   "Environment": {
     "resourceType": "GitLab::CI::Environment",
     "kind": "property",
-    "lexicon": "gitlab"
+    "lexicon": "gitlab",
+    "constraints": {
+      "name": {
+        "minLength": 1
+      },
+      "url": {
+        "pattern": "^(https?://.+|\\$[A-Za-z]+)",
+        "format": "uri"
+      },
+      "action": {
+        "default": "start",
+        "enum": [
+          "start",
+          "prepare",
+          "stop",
+          "verify",
+          "access"
+        ]
+      },
+      "deployment_tier": {
+        "enum": [
+          "production",
+          "staging",
+          "testing",
+          "development",
+          "other"
+        ]
+      }
+    }
   },
   "Image": {
     "resourceType": "GitLab::CI::Image",
     "kind": "property",
-    "lexicon": "gitlab"
+    "lexicon": "gitlab",
+    "constraints": {
+      "name": {
+        "minLength": 1
+      },
+      "pull_policy": {
+        "default": "always"
+      }
+    }
   },
   "Include": {
     "resourceType": "GitLab::CI::Include",
     "kind": "property",
+    "lexicon": "gitlab",
+    "constraints": {
+      "project": {
+        "pattern": "(?:\\S/\\S|\\$\\S+)"
+      },
+      "local": {
+        "pattern": "\\.ya?ml$",
+        "format": "uri-reference"
+      },
+      "template": {
+        "pattern": "\\.ya?ml$",
+        "format": "uri-reference"
+      },
+      "component": {
+        "format": "uri-reference"
+      },
+      "remote": {
+        "pattern": "^https?://.+\\.ya?ml$",
+        "format": "uri-reference"
+      }
+    }
+  },
+  "Inherit": {
+    "resourceType": "GitLab::CI::Inherit",
+    "kind": "property",
     "lexicon": "gitlab"
   },
   "Job": {
     "resourceType": "GitLab::CI::Job",
     "kind": "resource",
+    "lexicon": "gitlab",
+    "constraints": {
+      "coverage": {
+        "pattern": "^/.+/$",
+        "format": "regex"
+      }
+    }
+  },
+  "Need": {
+    "resourceType": "GitLab::CI::Need",
+    "kind": "property",
     "lexicon": "gitlab"
   },
   "Parallel": {
@@ -52,7 +184,19 @@
   "Release": {
     "resourceType": "GitLab::CI::Release",
     "kind": "property",
-    "lexicon": "gitlab"
+    "lexicon": "gitlab",
+    "constraints": {
+      "tag_name": {
+        "minLength": 1
+      },
+      "description": {
+        "minLength": 1
+      },
+      "released_at": {
+        "pattern": "^(?:[1-9]\\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:Z|[+-][01]\\d:[0-5]\\d)$",
+        "format": "date-time"
+      }
+    }
   },
   "Retry": {
     "resourceType": "GitLab::CI::Retry",
@@ -67,16 +211,50 @@
   "Service": {
     "resourceType": "GitLab::CI::Service",
     "kind": "property",
-    "lexicon": "gitlab"
+    "lexicon": "gitlab",
+    "constraints": {
+      "name": {
+        "minLength": 1
+      },
+      "pull_policy": {
+        "default": "always"
+      },
+      "alias": {
+        "minLength": 1
+      }
+    }
   },
   "Trigger": {
     "resourceType": "GitLab::CI::Trigger",
     "kind": "property",
-    "lexicon": "gitlab"
+    "lexicon": "gitlab",
+    "constraints": {
+      "project": {
+        "pattern": "(?:\\S/\\S|\\$\\S+)"
+      },
+      "strategy": {
+        "enum": [
+          "depend"
+        ]
+      }
+    }
   },
   "Workflow": {
     "resourceType": "GitLab::CI::Workflow",
     "kind": "resource",
     "lexicon": "gitlab"
+  },
+  "WorkflowRule": {
+    "resourceType": "GitLab::CI::WorkflowRule",
+    "kind": "property",
+    "lexicon": "gitlab",
+    "constraints": {
+      "when": {
+        "enum": [
+          "always",
+          "never"
+        ]
+      }
+    }
   }
 }

package/dist/rules/wgl012.ts

@@ -0,0 +1,86 @@
+/**
+ * WGL012: Deprecated Property Usage
+ *
+ * Flags properties marked as deprecated in the GitLab CI schema.
+ * Sources: description text mining (keywords like "Deprecated", "legacy").
+ */
+
+import { readFileSync } from "fs";
+import { join } from "path";
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+
+interface LexiconEntry {
+  kind: string;
+  resourceType: string;
+  deprecatedProperties?: string[];
+  [key: string]: unknown;
+}
+
+/**
+ * Load deprecated properties per entity type from the lexicon JSON.
+ */
+function loadDeprecatedProperties(): Map<string, Set<string>> {
+  const map = new Map<string, Set<string>>();
+  try {
+    const pkgDir = join(__dirname, "..", "..", "..");
+    const lexiconPath = join(pkgDir, "src", "generated", "lexicon-gitlab.json");
+    const content = readFileSync(lexiconPath, "utf-8");
+    const data = JSON.parse(content) as Record<string, LexiconEntry>;
+
+    for (const [_name, entry] of Object.entries(data)) {
+      if (entry.resourceType && entry.deprecatedProperties && entry.deprecatedProperties.length > 0) {
+        map.set(entry.resourceType, new Set(entry.deprecatedProperties));
+      }
+    }
+  } catch {
+    // Lexicon not available — skip
+  }
+  return map;
+}
+
+/**
+ * Core detection logic — exported for direct testing with synthetic data.
+ */
+export function checkDeprecatedProperties(
+  ctx: PostSynthContext,
+  deprecated: Map<string, Set<string>>,
+): PostSynthDiagnostic[] {
+  if (deprecated.size === 0) return [];
+
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [entityName, entity] of ctx.entities) {
+    if (isPropertyDeclarable(entity)) continue;
+
+    const entityType = (entity as Record<string, unknown>).entityType as string;
+    const deprProps = deprecated.get(entityType);
+    if (!deprProps) continue;
+
+    const props = (entity as Record<string, unknown>).props as Record<string, unknown> | undefined;
+    if (!props) continue;
+
+    for (const propName of Object.keys(props)) {
+      if (deprProps.has(propName)) {
+        diagnostics.push({
+          checkId: "WGL012",
+          severity: "warning",
+          message: `Entity "${entityName}" (${entityType}) uses deprecated property "${propName}" — consider alternatives`,
+          entity: entityName,
+          lexicon: "gitlab",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl012: PostSynthCheck = {
+  id: "WGL012",
+  description: "Deprecated property usage — flags properties marked as deprecated in the GitLab CI schema",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkDeprecatedProperties(ctx, loadDeprecatedProperties());
+  },
+};

package/dist/rules/wgl013.ts

@@ -0,0 +1,62 @@
+/**
+ * WGL013: Invalid `needs:` Target
+ *
+ * Detects two cases in the serialized YAML:
+ * - Dangling reference: `needs:` names a job not defined in the pipeline
+ * - Self-reference: job lists itself in `needs:`
+ *
+ * Both cause GitLab pipeline validation failures.
+ *
+ * Caveat: when `include:` is present, referenced jobs may come from
+ * included files, so the check is skipped.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs, hasInclude } from "./yaml-helpers";
+
+export function checkInvalidNeeds(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [, output] of ctx.outputs) {
+    const yaml = getPrimaryOutput(output);
+    if (hasInclude(yaml)) continue;
+
+    const jobs = extractJobs(yaml);
+    const jobNames = new Set(jobs.keys());
+
+    for (const [jobName, job] of jobs) {
+      if (!job.needs) continue;
+
+      for (const need of job.needs) {
+        if (need === jobName) {
+          diagnostics.push({
+            checkId: "WGL013",
+            severity: "error",
+            message: `Job "${jobName}" lists itself in needs: — self-references are invalid`,
+            entity: jobName,
+            lexicon: "gitlab",
+          });
+        } else if (!jobNames.has(need)) {
+          diagnostics.push({
+            checkId: "WGL013",
+            severity: "error",
+            message: `Job "${jobName}" needs "${need}" which is not defined in the pipeline`,
+            entity: jobName,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl013: PostSynthCheck = {
+  id: "WGL013",
+  description: "Invalid needs: target — dangling reference or self-reference",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkInvalidNeeds(ctx);
+  },
+};

package/dist/rules/wgl014.ts

@@ -0,0 +1,51 @@
+/**
+ * WGL014: Invalid `extends:` Target
+ *
+ * Detects jobs that `extends:` a template not defined in the pipeline YAML.
+ * GitLab rejects pipelines with unresolved extends references.
+ *
+ * Caveat: when `include:` is present, templates may come from
+ * included files, so the check is skipped.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs, hasInclude } from "./yaml-helpers";
+
+export function checkInvalidExtends(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [, output] of ctx.outputs) {
+    const yaml = getPrimaryOutput(output);
+    if (hasInclude(yaml)) continue;
+
+    const jobs = extractJobs(yaml);
+    const jobNames = new Set(jobs.keys());
+
+    for (const [jobName, job] of jobs) {
+      if (!job.extends) continue;
+
+      for (const target of job.extends) {
+        if (!jobNames.has(target)) {
+          diagnostics.push({
+            checkId: "WGL014",
+            severity: "error",
+            message: `Job "${jobName}" extends "${target}" which is not defined in the pipeline`,
+            entity: jobName,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl014: PostSynthCheck = {
+  id: "WGL014",
+  description: "Invalid extends: target — references a template not in the pipeline",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkInvalidExtends(ctx);
+  },
+};

package/dist/rules/wgl015.ts

@@ -0,0 +1,85 @@
+/**
+ * WGL015: Circular `needs:` Chain
+ *
+ * DFS-based cycle detection on the `needs:` dependency graph.
+ * If A needs B and B needs A, GitLab rejects the pipeline.
+ *
+ * Reports one diagnostic per cycle found, listing the full chain.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs } from "./yaml-helpers";
+
+export function checkCircularNeeds(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [, output] of ctx.outputs) {
+    const yaml = getPrimaryOutput(output);
+    const jobs = extractJobs(yaml);
+
+    // Build adjacency list from needs
+    const graph = new Map<string, string[]>();
+    for (const [jobName, job] of jobs) {
+      graph.set(jobName, job.needs ?? []);
+    }
+
+    // DFS cycle detection
+    const visited = new Set<string>();
+    const inStack = new Set<string>();
+    const reportedInCycle = new Set<string>();
+
+    function dfs(node: string, path: string[]): void {
+      if (inStack.has(node)) {
+        // Found a cycle — extract the cycle portion
+        const cycleStart = path.indexOf(node);
+        const cycle = path.slice(cycleStart);
+        cycle.push(node);
+
+        // Only report if we haven't already reported a cycle containing these nodes
+        const cycleKey = [...cycle].sort().join(",");
+        if (!reportedInCycle.has(cycleKey)) {
+          reportedInCycle.add(cycleKey);
+          diagnostics.push({
+            checkId: "WGL015",
+            severity: "error",
+            message: `Circular needs: chain detected: ${cycle.join(" → ")}`,
+            entity: node,
+            lexicon: "gitlab",
+          });
+        }
+        return;
+      }
+
+      if (visited.has(node)) return;
+
+      visited.add(node);
+      inStack.add(node);
+
+      for (const neighbor of graph.get(node) ?? []) {
+        // Only follow edges to known jobs
+        if (graph.has(neighbor)) {
+          dfs(neighbor, [...path, node]);
+        }
+      }
+
+      inStack.delete(node);
+    }
+
+    for (const jobName of graph.keys()) {
+      if (!visited.has(jobName)) {
+        dfs(jobName, []);
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl015: PostSynthCheck = {
+  id: "WGL015",
+  description: "Circular needs: chain — cycle in job dependency graph",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkCircularNeeds(ctx);
+  },
+};

package/dist/rules/yaml-helpers.ts

@@ -29,6 +29,8 @@ export interface ParsedJob {
   name: string;
   stage?: string;
   rules?: ParsedRule[];
+  needs?: string[];
+  extends?: string[];
 }
 
 export interface ParsedRule {
@@ -63,8 +65,8 @@ export function extractJobs(yaml: string): Map<string, ParsedJob> {
     const lines = section.split("\n");
     if (lines.length === 0) continue;
 
-    // Top-level key
-    const topMatch = lines[0].match(/^([a-z][a-z0-9_-]*):/);
+    // Top-level key (including dot-prefixed hidden jobs like .deploy-template)
+    const topMatch = lines[0].match(/^(\.?[a-z][a-z0-9_.-]*):/);
     if (!topMatch) continue;
 
     const name = topMatch[1];
@@ -73,12 +75,63 @@ export function extractJobs(yaml: string): Map<string, ParsedJob> {
 
     const job: ParsedJob = { name };
 
-    // Find stage within the section
+    // Find stage, needs, extends within the section
+    let inNeeds = false;
     for (const line of lines) {
       const stageMatch = line.match(/^\s+stage:\s+(.+)$/);
       if (stageMatch) {
         job.stage = stageMatch[1].trim().replace(/^'|'$/g, "");
       }
+
+      // extends: .template or extends: [.a, .b]
+      const extendsMatch = line.match(/^\s+extends:\s+(.+)$/);
+      if (extendsMatch) {
+        const val = extendsMatch[1].trim();
+        if (val.startsWith("[")) {
+          // Inline array: [.a, .b]
+          job.extends = val.slice(1, -1).split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
+        } else {
+          job.extends = [val.replace(/^'|'$/g, "")];
+        }
+      }
+
+      // needs: block (list form)
+      if (line.match(/^\s+needs:$/)) {
+        inNeeds = true;
+        job.needs = [];
+        continue;
+      }
+
+      if (inNeeds) {
+        // - job-name (simple string form)
+        const simpleNeed = line.match(/^\s+- ([a-z][a-z0-9_.-]*)$/);
+        if (simpleNeed) {
+          job.needs!.push(simpleNeed[1]);
+          continue;
+        }
+        // - 'job-name' (quoted string form)
+        const quotedNeed = line.match(/^\s+- '([^']+)'$/);
+        if (quotedNeed) {
+          job.needs!.push(quotedNeed[1]);
+          continue;
+        }
+        // - job: job-name (object form)
+        const objectNeed = line.match(/^\s+- job:\s+(.+)$/);
+        if (objectNeed) {
+          job.needs!.push(objectNeed[1].trim().replace(/^'|'$/g, ""));
+          continue;
+        }
+        // End of needs block when we hit a non-indented-list line
+        if (!line.match(/^\s+\s/) || line.match(/^\s+[a-z_]+:/)) {
+          inNeeds = false;
+        }
+      }
+
+      // needs: [a, b] (inline array form)
+      const inlineNeeds = line.match(/^\s+needs:\s+\[(.+)\]$/);
+      if (inlineNeeds) {
+        job.needs = inlineNeeds[1].split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
+      }
     }
 
     jobs.set(name, job);
@@ -86,3 +139,12 @@ export function extractJobs(yaml: string): Map<string, ParsedJob> {
 
   return jobs;
 }
+
+/**
+ * Check whether the YAML contains an `include:` directive.
+ * When includes are present, `needs:` and `extends:` may reference
+ * jobs/templates from included files, so checks should be lenient.
+ */
+export function hasInclude(yaml: string): boolean {
+  return /^include:/m.test(yaml);
+}