@intentius/chant-lexicon-gitlab 0.0.15 → 0.0.18

package/dist/rules/wgl027.ts

@@ -0,0 +1,54 @@
+/**
+ * WGL027: Empty Script
+ *
+ * Detects jobs with `script: []` or scripts containing only empty strings.
+ * GitLab rejects jobs with empty scripts at pipeline validation time.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+
+export const wgl027: PostSynthCheck = {
+  id: "WGL027",
+  description: "Empty script — jobs with empty or blank script entries",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [entityName, entity] of ctx.entities) {
+      if (isPropertyDeclarable(entity)) continue;
+      const entityType = (entity as Record<string, unknown>).entityType as string;
+      if (entityType !== "GitLab::CI::Job") continue;
+
+      const props = (entity as Record<string, unknown>).props as Record<string, unknown> | undefined;
+      if (!props) continue;
+
+      const script = props.script;
+      if (script === undefined || script === null) continue;
+
+      let isEmpty = false;
+
+      if (Array.isArray(script)) {
+        if (script.length === 0) {
+          isEmpty = true;
+        } else if (script.every((s) => typeof s === "string" && s.trim() === "")) {
+          isEmpty = true;
+        }
+      } else if (typeof script === "string" && script.trim() === "") {
+        isEmpty = true;
+      }
+
+      if (isEmpty) {
+        diagnostics.push({
+          checkId: "WGL027",
+          severity: "error",
+          message: `Job "${entityName}" has an empty script — GitLab will reject this pipeline`,
+          entity: entityName,
+          lexicon: "gitlab",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wgl028.ts

@@ -0,0 +1,67 @@
+/**
+ * WGL028: Redundant Needs
+ *
+ * Detects `needs:` entries that list jobs already implied by stage ordering.
+ * While not incorrect, redundant needs add noise and make the pipeline
+ * harder to maintain. This is informational only.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractStages, extractJobs } from "./yaml-helpers";
+
+export function checkRedundantNeeds(yaml: string): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  const stages = extractStages(yaml);
+  if (stages.length === 0) return diagnostics;
+
+  const stageIndex = new Map<string, number>();
+  for (let i = 0; i < stages.length; i++) {
+    stageIndex.set(stages[i], i);
+  }
+
+  const jobs = extractJobs(yaml);
+
+  for (const [jobName, job] of jobs) {
+    if (!job.needs || !job.stage) continue;
+
+    const jobStageIdx = stageIndex.get(job.stage);
+    if (jobStageIdx === undefined) continue;
+
+    for (const need of job.needs) {
+      const neededJob = jobs.get(need);
+      if (!neededJob?.stage) continue;
+
+      const needStageIdx = stageIndex.get(neededJob.stage);
+      if (needStageIdx === undefined) continue;
+
+      // If the needed job is in an earlier stage, it's already implied
+      // by GitLab's default stage-based ordering
+      if (needStageIdx < jobStageIdx) {
+        diagnostics.push({
+          checkId: "WGL028",
+          severity: "info",
+          message: `Job "${jobName}" lists "${need}" in needs: but it's already in an earlier stage (${neededJob.stage} → ${job.stage})`,
+          entity: jobName,
+          lexicon: "gitlab",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl028: PostSynthCheck = {
+  id: "WGL028",
+  description: "Redundant needs — needs listing jobs already implied by stage ordering",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      diagnostics.push(...checkRedundantNeeds(yaml));
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/yaml-helpers.ts

@@ -141,3 +141,85 @@ export function extractJobs(yaml: string): Map<string, ParsedJob> {
 export function hasInclude(yaml: string): boolean {
   return /^include:/m.test(yaml);
 }
+
+/**
+ * Extract global variables from serialized YAML.
+ */
+export function extractGlobalVariables(yaml: string): Map<string, string> {
+  const vars = new Map<string, string>();
+  const match = yaml.match(/^variables:\n((?:\s+.+\n?)+)/m);
+  if (!match) return vars;
+
+  for (const line of match[1].split("\n")) {
+    const kv = line.match(/^\s+(\w+):\s+(.+)$/);
+    if (kv) {
+      vars.set(kv[1], kv[2].trim().replace(/^['"]|['"]$/g, ""));
+    }
+  }
+  return vars;
+}
+
+/**
+ * Extract the full section text for a given job name.
+ */
+export function extractJobSection(yaml: string, jobName: string): string | null {
+  const sections = yaml.split("\n\n");
+  for (const section of sections) {
+    const lines = section.split("\n");
+    if (lines.length > 0 && lines[0].startsWith(`${jobName}:`)) {
+      return section;
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract rules from a job section.
+ */
+export function extractJobRules(section: string): ParsedRule[] {
+  const rules: ParsedRule[] = [];
+  const lines = section.split("\n");
+
+  let inRules = false;
+  let currentRule: ParsedRule = {};
+
+  for (const line of lines) {
+    if (line.match(/^\s+rules:$/)) {
+      inRules = true;
+      continue;
+    }
+
+    if (inRules) {
+      const ruleStart = line.match(/^\s+- (if|when|changes):\s*(.*)$/);
+      if (ruleStart) {
+        if (Object.keys(currentRule).length > 0) {
+          rules.push(currentRule);
+        }
+        currentRule = {};
+        if (ruleStart[1] === "if") currentRule.if = ruleStart[2].trim();
+        if (ruleStart[1] === "when") currentRule.when = ruleStart[2].trim();
+        continue;
+      }
+
+      const whenMatch = line.match(/^\s+when:\s+(.+)$/);
+      if (whenMatch) {
+        currentRule.when = whenMatch[1].trim();
+        continue;
+      }
+
+      // End of rules block
+      if (!line.match(/^\s+\s/) || line.match(/^\s+[a-z_]+:/) && !line.match(/^\s+when:/)) {
+        if (Object.keys(currentRule).length > 0) {
+          rules.push(currentRule);
+        }
+        inRules = false;
+      }
+    }
+  }
+
+  if (inRules && Object.keys(currentRule).length > 0) {
+    rules.push(currentRule);
+  }
+
+  return rules;
+}

package/dist/skills/chant-gitlab.md

@@ -147,7 +147,7 @@ Add `"dry_run": true, "include_merged_yaml": true` for full expansion with inclu
 | Step | Catches | When to run |
 |------|---------|-------------|
 | `chant lint` | Deprecated only/except (WGL001), missing script (WGL002), missing stage (WGL003), artifacts without expiry (WGL004) | Every edit |
-| `chant build` | Post-synth checks: undefined stages (WGL010), unreachable jobs (WGL011), deprecated properties (WGL012), invalid needs targets (WGL013), invalid extends targets (WGL014), circular needs chains (WGL015) | Before push |
+| `chant build` | Post-synth checks: undefined stages (WGL010), unreachable jobs (WGL011), deprecated properties (WGL012), invalid needs/extends targets (WGL013-014), circular needs (WGL015), secrets in variables (WGL016), insecure registry (WGL017), missing timeout/retry (WGL018-019), duplicate jobs (WGL020), unused variables (WGL021), missing artifacts expiry (WGL022), overly broad rules (WGL023), manual without allow_failure (WGL024), missing cache key (WGL025), DinD without TLS (WGL026), empty script (WGL027), redundant needs (WGL028) | Before push |
 | CI Lint API | GitLab-specific validation: include resolution, variable expansion, YAML schema errors | Before merge to default branch |
 
 Always run all three before deploying. Lint catches things the API cannot (and vice versa).

package/dist/skills/gitlab-ci-patterns.md

@@ -0,0 +1,309 @@
+---
+skill: gitlab-ci-patterns
+description: GitLab CI/CD pipeline stages, caching, artifacts, includes, and advanced patterns
+user-invocable: true
+---
+
+# GitLab CI/CD Pipeline Patterns
+
+## Pipeline Stage Design
+
+### Standard Stage Ordering
+
+```typescript
+import { Job, Image, Cache, Artifacts } from "@intentius/chant-lexicon-gitlab";
+
+// Stages execute in order. Jobs within a stage run in parallel.
+// Default stages: .pre, build, test, deploy, .post
+
+export const lint = new Job({
+  stage: "build",
+  image: new Image({ name: "node:22-alpine" }),
+  script: ["npm ci", "npm run lint"],
+});
+
+export const test = new Job({
+  stage: "test",
+  image: new Image({ name: "node:22-alpine" }),
+  script: ["npm ci", "npm test"],
+});
+
+export const deploy = new Job({
+  stage: "deploy",
+  script: ["./deploy.sh"],
+  rules: [{ if: '$CI_COMMIT_BRANCH == "main"' }],
+});
+```
+
+### Parallel Jobs with needs
+
+Use `needs` to create a DAG and skip waiting for the full stage:
+
+```typescript
+export const unitTests = new Job({
+  stage: "test",
+  script: ["npm run test:unit"],
+  needs: ["build"],
+});
+
+export const integrationTests = new Job({
+  stage: "test",
+  script: ["npm run test:integration"],
+  needs: ["build"],
+});
+
+export const deploy = new Job({
+  stage: "deploy",
+  script: ["./deploy.sh"],
+  needs: ["unitTests", "integrationTests"],
+});
+```
+
+## Caching Strategies
+
+### Language-Specific Cache Keys
+
+```typescript
+import { Cache } from "@intentius/chant-lexicon-gitlab";
+
+// Node.js: cache node_modules by lockfile hash
+export const nodeCache = new Cache({
+  key: { files: ["package-lock.json"] },
+  paths: ["node_modules/"],
+  policy: "pull-push",
+});
+
+// Python: cache pip downloads
+export const pipCache = new Cache({
+  key: { files: ["requirements.txt"] },
+  paths: [".pip-cache/"],
+  policy: "pull-push",
+});
+```
+
+### Cache Policies
+
+| Policy | Behavior | Use for |
+|--------|----------|---------|
+| `pull-push` | Download and upload cache | Build jobs that install dependencies |
+| `pull` | Download only, never upload | Test/deploy jobs (read from build cache) |
+| `push` | Upload only, never download | Initial cache population |
+
+```typescript
+export const build = new Job({
+  stage: "build",
+  cache: new Cache({
+    key: "$CI_COMMIT_REF_SLUG",
+    paths: ["node_modules/", "dist/"],
+    policy: "pull-push",  // build populates cache
+  }),
+  script: ["npm ci", "npm run build"],
+});
+
+export const test = new Job({
+  stage: "test",
+  cache: new Cache({
+    key: "$CI_COMMIT_REF_SLUG",
+    paths: ["node_modules/"],
+    policy: "pull",  // test only reads cache
+  }),
+  script: ["npm test"],
+});
+```
+
+## Artifacts
+
+### Pass Build Output Between Jobs
+
+```typescript
+import { Artifacts } from "@intentius/chant-lexicon-gitlab";
+
+export const buildArtifacts = new Artifacts({
+  paths: ["dist/"],
+  expire_in: "1 day",
+});
+
+export const testReports = new Artifacts({
+  reports: { junit: "coverage/junit.xml", coverage_report: { coverage_format: "cobertura", path: "coverage/cobertura.xml" } },
+  paths: ["coverage/"],
+  expire_in: "1 week",
+});
+
+export const build = new Job({
+  stage: "build",
+  script: ["npm ci", "npm run build"],
+  artifacts: buildArtifacts,
+});
+
+export const test = new Job({
+  stage: "test",
+  script: ["npm ci", "npm test -- --coverage"],
+  artifacts: testReports,
+  needs: ["build"],
+});
+```
+
+### Artifact Types
+
+| Type | Purpose | GitLab feature |
+|------|---------|----------------|
+| `junit` | Test results | MR test report widget |
+| `coverage_report` | Code coverage | MR coverage visualization |
+| `dotenv` | Export variables | Pass variables to downstream jobs |
+| `terraform` | Terraform plans | MR Terraform widget |
+
+## Include Patterns
+
+### Reusable Pipeline Components
+
+```typescript
+import { Include } from "@intentius/chant-lexicon-gitlab";
+
+// Include from same project
+export const localInclude = new Include({
+  local: ".gitlab/ci/deploy.yml",
+});
+
+// Include from another project
+export const projectInclude = new Include({
+  project: "devops/pipeline-templates",
+  ref: "main",
+  file: "/templates/docker-build.yml",
+});
+
+// Include from remote URL
+export const remoteInclude = new Include({
+  remote: "https://example.com/ci-templates/security-scan.yml",
+});
+
+// Include a GitLab CI template
+export const templateInclude = new Include({
+  template: "Security/SAST.gitlab-ci.yml",
+});
+```
+
+### Composites for Common Pipelines
+
+Use composites instead of raw includes for type-safe pipeline generation:
+
+```typescript
+import { NodePipeline } from "@intentius/chant-lexicon-gitlab";
+
+export const app = NodePipeline({
+  nodeVersion: "22",
+  installCommand: "npm ci",
+  buildScript: "build",
+  testScript: "test",
+});
+```
+
+## Rules and Conditional Execution
+
+### Branch-Based Rules
+
+```typescript
+export const deployStaging = new Job({
+  stage: "deploy",
+  script: ["./deploy.sh staging"],
+  rules: [
+    { if: '$CI_COMMIT_BRANCH == "develop"', when: "on_success" },
+  ],
+});
+
+export const deployProd = new Job({
+  stage: "deploy",
+  script: ["./deploy.sh production"],
+  rules: [
+    { if: '$CI_COMMIT_BRANCH == "main"', when: "manual" },
+  ],
+});
+```
+
+### MR vs Branch Pipelines
+
+```typescript
+// Run on merge requests only
+export const mrTest = new Job({
+  stage: "test",
+  script: ["npm test"],
+  rules: [{ if: "$CI_MERGE_REQUEST_IID" }],
+});
+
+// Run on default branch only
+export const release = new Job({
+  stage: "deploy",
+  script: ["npm publish"],
+  rules: [{ if: '$CI_COMMIT_BRANCH == "main"' }],
+});
+```
+
+## Review Apps
+
+### Deploy Per-MR Environments
+
+```typescript
+import { ReviewApp } from "@intentius/chant-lexicon-gitlab";
+
+export const review = ReviewApp({
+  name: "review",
+  deployScript: "kubectl apply -f manifests.yaml",
+  stopScript: "kubectl delete -f manifests.yaml",
+  autoStopIn: "1 week",
+});
+```
+
+This generates a deploy job with `environment` and a stop job with `action: stop` that triggers when the MR is merged or closed.
+
+## Docker Build Pattern
+
+### Multi-Stage Build and Push
+
+```typescript
+import { DockerBuild } from "@intentius/chant-lexicon-gitlab";
+
+export const docker = DockerBuild({
+  dockerfile: "Dockerfile",
+  context: ".",
+  tagLatest: true,
+  registry: "$CI_REGISTRY",
+  imageName: "$CI_REGISTRY_IMAGE",
+});
+```
+
+This generates a job using Docker-in-Docker (`dind`) service with proper `DOCKER_TLS_CERTDIR` configuration.
+
+## Matrix Builds
+
+### Test Across Multiple Versions
+
+```typescript
+export const test = new Job({
+  stage: "test",
+  parallel: {
+    matrix: [
+      { NODE_VERSION: ["18", "20", "22"] },
+    ],
+  },
+  image: new Image({ name: "node:${NODE_VERSION}-alpine" }),
+  script: ["npm ci", "npm test"],
+});
+```
+
+## Pipeline Security
+
+### Protected Variables
+
+Use protected variables for production secrets. They are only available on protected branches/tags:
+
+```typescript
+export const deploy = new Job({
+  stage: "deploy",
+  script: ["./deploy.sh"],
+  variables: { DEPLOY_ENV: "production" },
+  rules: [
+    { if: '$CI_COMMIT_BRANCH == "main"', when: "manual" },
+  ],
+});
+```
+
+Set `DEPLOY_TOKEN` as a protected, masked variable in project settings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.0.15",
+  "version": "0.0.18",
   "license": "Apache-2.0",
   "type": "module",
   "files": [
@@ -22,10 +22,10 @@
     "bundle": "bun run src/package-cli.ts",
     "validate": "bun run src/validate-cli.ts",
     "docs": "bun run src/codegen/docs-cli.ts",
-    "prepack": "bun run bundle && bun run validate"
+    "prepack": "bun run generate && bun run bundle && bun run validate"
   },
   "dependencies": {
-    "@intentius/chant": "0.0.15"
+    "@intentius/chant": "0.0.18"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/codegen/fetch.test.ts

@@ -0,0 +1,30 @@
+import { describe, test, expect } from "bun:test";
+import { fetchCISchema, fetchSchemas, getCachePath, GITLAB_SCHEMA_VERSION } from "./fetch";
+
+describe("fetch", () => {
+  test("fetchCISchema function exists", () => {
+    expect(typeof fetchCISchema).toBe("function");
+  });
+
+  test("fetchSchemas function exists", () => {
+    expect(typeof fetchSchemas).toBe("function");
+  });
+
+  test("GITLAB_SCHEMA_VERSION is defined", () => {
+    expect(typeof GITLAB_SCHEMA_VERSION).toBe("string");
+    expect(GITLAB_SCHEMA_VERSION).toMatch(/^v\d+\.\d+\.\d+-ee$/);
+  });
+
+  test("getCachePath returns a path", () => {
+    const cachePath = getCachePath();
+    expect(typeof cachePath).toBe("string");
+    expect(cachePath).toContain("gitlab-ci-schema.json");
+  });
+
+  test.skip("integration: fetchCISchema returns Buffer (requires network)", async () => {
+    const data = await fetchCISchema();
+    expect(data).toBeInstanceOf(Buffer);
+    const parsed = JSON.parse(data.toString("utf-8"));
+    expect(parsed.properties).toBeDefined();
+  });
+});

package/src/codegen/generate.test.ts

@@ -0,0 +1,65 @@
+import { describe, test, expect } from "bun:test";
+import { generate, writeGeneratedFiles } from "./generate";
+import { loadSchemaFixtureMap } from "../testdata/load-fixtures";
+
+describe("generate pipeline components", () => {
+  test("exports generate function", () => {
+    expect(typeof generate).toBe("function");
+  });
+
+  test("exports writeGeneratedFiles function", () => {
+    expect(typeof writeGeneratedFiles).toBe("function");
+  });
+
+  // Integration test — requires network, skip by default
+  test.skip("generates full pipeline (integration)", async () => {
+    const result = await generate({ verbose: false });
+
+    expect(result.resources).toBeGreaterThan(0);
+    expect(result.properties).toBeGreaterThan(0);
+    expect(result.lexiconJSON).toBeTruthy();
+    expect(result.typesDTS).toBeTruthy();
+    expect(result.indexTS).toBeTruthy();
+  });
+});
+
+describe("offline fixture pipeline", () => {
+  test("generates from fixtures", async () => {
+    const fixtures = loadSchemaFixtureMap();
+    const result = await generate({ schemaSource: fixtures });
+
+    expect(result.resources).toBeGreaterThanOrEqual(1);
+    expect(result.properties).toBeGreaterThanOrEqual(0);
+    expect(result.lexiconJSON).toBeTruthy();
+    expect(result.typesDTS).toBeTruthy();
+    expect(result.indexTS).toBeTruthy();
+  });
+
+  test("output contains expected entities", async () => {
+    const fixtures = loadSchemaFixtureMap();
+    const result = await generate({ schemaSource: fixtures });
+
+    const lexicon = JSON.parse(result.lexiconJSON);
+    // Core CI entities should be present
+    expect(lexicon["Job"]).toBeDefined();
+    expect(lexicon["Default"]).toBeDefined();
+    expect(lexicon["Workflow"]).toBeDefined();
+  });
+
+  test("resource and property counts are non-zero", async () => {
+    const fixtures = loadSchemaFixtureMap();
+    const result = await generate({ schemaSource: fixtures });
+
+    expect(result.resources).toBeGreaterThan(0);
+    // Properties are optional in a minimal fixture but count should be defined
+    expect(typeof result.properties).toBe("number");
+    expect(typeof result.enums).toBe("number");
+  });
+
+  test("produces no warnings from fixtures", async () => {
+    const fixtures = loadSchemaFixtureMap();
+    const result = await generate({ schemaSource: fixtures });
+
+    expect(result.warnings).toHaveLength(0);
+  });
+});

package/src/codegen/idempotency.test.ts

@@ -0,0 +1,28 @@
+import { describe, test, expect } from "bun:test";
+import { generate } from "./generate";
+import { loadSchemaFixtureMap } from "../testdata/load-fixtures";
+
+describe("generation idempotency", () => {
+  test("two generations from same fixtures produce identical content", async () => {
+    const fixtures = loadSchemaFixtureMap();
+
+    const result1 = await generate({ schemaSource: fixtures });
+    const result2 = await generate({ schemaSource: fixtures });
+
+    // Content should be byte-identical
+    expect(result1.lexiconJSON).toBe(result2.lexiconJSON);
+    expect(result1.typesDTS).toBe(result2.typesDTS);
+    expect(result1.indexTS).toBe(result2.indexTS);
+  });
+
+  test("resource counts match between runs", async () => {
+    const fixtures = loadSchemaFixtureMap();
+
+    const result1 = await generate({ schemaSource: fixtures });
+    const result2 = await generate({ schemaSource: fixtures });
+
+    expect(result1.resources).toBe(result2.resources);
+    expect(result1.properties).toBe(result2.properties);
+    expect(result1.enums).toBe(result2.enums);
+  });
+});