@intentius/chant-lexicon-gitlab 0.0.15 → 0.0.18

package/src/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/src/testdata/pipelines/deploy-envs.gitlab-ci.yml

@@ -0,0 +1,60 @@
+stages:
+  - build
+  - deploy
+  - cleanup
+
+build:
+  stage: build
+  script:
+    - npm ci
+    - npm run build
+  artifacts:
+    paths:
+      - dist/
+
+deploy-review:
+  stage: deploy
+  script:
+    - deploy-review.sh
+  environment:
+    name: review/$CI_COMMIT_REF_SLUG
+    url: https://$CI_ENVIRONMENT_SLUG.review.example.com
+    on_stop: stop-review
+    auto_stop_in: 1 week
+  resource_group: review/$CI_COMMIT_REF_SLUG
+  rules:
+    - if: $CI_MERGE_REQUEST_IID
+
+stop-review:
+  stage: cleanup
+  script:
+    - teardown-review.sh
+  environment:
+    name: review/$CI_COMMIT_REF_SLUG
+    action: stop
+  rules:
+    - if: $CI_MERGE_REQUEST_IID
+      when: manual
+  needs:
+    - deploy-review
+
+deploy-staging:
+  stage: deploy
+  script:
+    - deploy.sh staging
+  environment:
+    name: staging
+    url: https://staging.example.com
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+deploy-production:
+  stage: deploy
+  script:
+    - deploy.sh production
+  environment:
+    name: production
+    url: https://example.com
+  rules:
+    - if: $CI_COMMIT_TAG
+      when: manual

package/src/testdata/pipelines/docker-build.gitlab-ci.yml

@@ -0,0 +1,41 @@
+stages:
+  - build
+  - push
+
+variables:
+  DOCKER_TLS_CERTDIR: "/certs"
+  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
+
+build-image:
+  stage: build
+  image: docker:27-cli
+  services:
+    - name: docker:27-dind
+      alias: docker
+  variables:
+    DOCKER_HOST: tcp://docker:2376
+  before_script:
+    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+  script:
+    - docker build -t $IMAGE_TAG .
+    - docker push $IMAGE_TAG
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_MERGE_REQUEST_IID
+
+push-latest:
+  stage: push
+  image: docker:27-cli
+  services:
+    - name: docker:27-dind
+      alias: docker
+  needs:
+    - build-image
+  before_script:
+    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+  script:
+    - docker pull $IMAGE_TAG
+    - docker tag $IMAGE_TAG $CI_REGISTRY_IMAGE:latest
+    - docker push $CI_REGISTRY_IMAGE:latest
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

package/src/testdata/pipelines/includes-templates.gitlab-ci.yml

@@ -0,0 +1,52 @@
+include:
+  - template: Auto-DevOps.gitlab-ci.yml
+  - project: my-group/ci-templates
+    ref: main
+    file: /templates/build.yml
+
+stages:
+  - build
+  - test
+  - deploy
+
+default:
+  image: node:22-alpine
+  interruptible: true
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+
+.test-template: &test-defaults
+  stage: test
+  before_script:
+    - npm ci
+
+build:
+  stage: build
+  extends: .build-template
+  script:
+    - npm ci
+    - npm run build
+
+unit-test:
+  <<: *test-defaults
+  script:
+    - npm test
+
+integration-test:
+  <<: *test-defaults
+  script:
+    - npm run test:integration
+  rules:
+    - if: $CI_MERGE_REQUEST_IID
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+deploy:
+  stage: deploy
+  extends: .deploy-template
+  script:
+    - deploy.sh
+  rules:
+    - if: $CI_COMMIT_TAG

package/src/testdata/pipelines/monorepo.gitlab-ci.yml

@@ -0,0 +1,51 @@
+stages:
+  - build
+  - test
+  - deploy
+
+variables:
+  GIT_DEPTH: 20
+
+frontend:
+  stage: build
+  trigger:
+    include: frontend/.gitlab-ci.yml
+    strategy: depend
+  rules:
+    - changes:
+        - frontend/**/*
+
+backend:
+  stage: build
+  trigger:
+    include: backend/.gitlab-ci.yml
+    strategy: depend
+  rules:
+    - changes:
+        - backend/**/*
+
+e2e-matrix:
+  stage: test
+  image: cypress/included:13
+  needs:
+    - frontend
+    - backend
+  parallel:
+    matrix:
+      - BROWSER: [chrome, firefox]
+        VIEWPORT: [desktop, mobile]
+  script:
+    - cypress run --browser $BROWSER --config viewportPreset=$VIEWPORT
+  artifacts:
+    when: always
+    paths:
+      - cypress/screenshots/
+      - cypress/videos/
+    expire_in: 3 days
+
+deploy-all:
+  stage: deploy
+  script:
+    - deploy.sh
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

package/src/testdata/pipelines/multi-stage.gitlab-ci.yml

@@ -0,0 +1,56 @@
+stages:
+  - build
+  - test
+  - deploy
+
+build-app:
+  stage: build
+  image: node:22-alpine
+  script:
+    - npm ci
+    - npm run build
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 hour
+  cache:
+    key:
+      files:
+        - package-lock.json
+    paths:
+      - .npm/
+
+lint:
+  stage: test
+  image: node:22-alpine
+  needs:
+    - build-app
+  script:
+    - npm ci
+    - npm run lint
+
+unit-tests:
+  stage: test
+  image: node:22-alpine
+  needs:
+    - build-app
+  script:
+    - npm ci
+    - npm test -- --coverage
+  artifacts:
+    reports:
+      junit: junit.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage/cobertura-coverage.xml
+
+deploy-staging:
+  stage: deploy
+  needs:
+    - lint
+    - unit-tests
+  script:
+    - deploy.sh staging
+  environment:
+    name: staging
+    url: https://staging.example.com

package/src/testdata/pipelines/simple.gitlab-ci.yml

@@ -0,0 +1,9 @@
+stages:
+  - test
+
+unit-test:
+  stage: test
+  image: node:22-alpine
+  script:
+    - npm ci
+    - npm test

package/src/validate.test.ts

@@ -1,31 +1,37 @@
 import { describe, test, expect } from "bun:test";
-import { validate } from "./validate";
-import { dirname } from "path";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 
 const basePath = dirname(dirname(fileURLToPath(import.meta.url)));
+const lexiconPath = join(basePath, "src", "generated", "lexicon-gitlab.json");
+const hasGenerated = existsSync(lexiconPath);
 
 describe("validate", () => {
-  test("runs validation checks on current generated artifacts", async () => {
+  test.skipIf(!hasGenerated)("runs validation checks on current generated artifacts", async () => {
+    const { validate } = await import("./validate");
     const result = await validate({ basePath });
     expect(result.checks.length).toBeGreaterThan(0);
   });
 
-  test("checks lexicon JSON exists and parses", async () => {
+  test.skipIf(!hasGenerated)("checks lexicon JSON exists and parses", async () => {
+    const { validate } = await import("./validate");
     const result = await validate({ basePath });
     const jsonCheck = result.checks.find((c) => c.name === "lexicon-json-exists");
     expect(jsonCheck).toBeDefined();
     expect(jsonCheck?.ok).toBe(true);
   });
 
-  test("checks types exist", async () => {
+  test.skipIf(!hasGenerated)("checks types exist", async () => {
+    const { validate } = await import("./validate");
     const result = await validate({ basePath });
     const typesCheck = result.checks.find((c) => c.name === "types-exist");
     expect(typesCheck).toBeDefined();
     expect(typesCheck?.ok).toBe(true);
   });
 
-  test("checks required names are present", async () => {
+  test.skipIf(!hasGenerated)("checks required names are present", async () => {
+    const { validate } = await import("./validate");
     const result = await validate({ basePath });
     const requiredCheck = result.checks.find((c) => c.name === "required-names");
     expect(requiredCheck).toBeDefined();

package/src/variables.test.ts

@@ -0,0 +1,58 @@
+import { describe, test, expect } from "bun:test";
+import { CI } from "./variables";
+
+describe("CI variables", () => {
+  test("all values start with $CI_", () => {
+    for (const [key, value] of Object.entries(CI)) {
+      expect(value).toMatch(/^\$CI_/);
+    }
+  });
+
+  test("all values are non-empty strings", () => {
+    for (const [key, value] of Object.entries(CI)) {
+      expect(typeof value).toBe("string");
+      expect(value.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("contains expected commit variables", () => {
+    expect(CI.CommitBranch).toBe("$CI_COMMIT_BRANCH");
+    expect(CI.CommitRef).toBe("$CI_COMMIT_REF_NAME");
+    expect(CI.CommitRefSlug).toBe("$CI_COMMIT_REF_SLUG");
+    expect(CI.CommitSha).toBe("$CI_COMMIT_SHA");
+    expect(CI.CommitTag).toBe("$CI_COMMIT_TAG");
+  });
+
+  test("contains expected project variables", () => {
+    expect(CI.ProjectDir).toBe("$CI_PROJECT_DIR");
+    expect(CI.ProjectId).toBe("$CI_PROJECT_ID");
+    expect(CI.ProjectName).toBe("$CI_PROJECT_NAME");
+    expect(CI.ProjectPath).toBe("$CI_PROJECT_PATH");
+  });
+
+  test("contains expected pipeline variables", () => {
+    expect(CI.PipelineId).toBe("$CI_PIPELINE_ID");
+    expect(CI.PipelineSource).toBe("$CI_PIPELINE_SOURCE");
+    expect(CI.JobId).toBe("$CI_JOB_ID");
+    expect(CI.JobName).toBe("$CI_JOB_NAME");
+    expect(CI.JobStage).toBe("$CI_JOB_STAGE");
+  });
+
+  test("contains expected registry variables", () => {
+    expect(CI.Registry).toBe("$CI_REGISTRY");
+    expect(CI.RegistryImage).toBe("$CI_REGISTRY_IMAGE");
+    expect(CI.RegistryUser).toBe("$CI_REGISTRY_USER");
+    expect(CI.RegistryPassword).toBe("$CI_REGISTRY_PASSWORD");
+  });
+
+  test("contains environment variables", () => {
+    expect(CI.Environment).toBe("$CI_ENVIRONMENT_NAME");
+    expect(CI.EnvironmentSlug).toBe("$CI_ENVIRONMENT_SLUG");
+    expect(CI.DefaultBranch).toBe("$CI_DEFAULT_BRANCH");
+    expect(CI.MergeRequestIid).toBe("$CI_MERGE_REQUEST_IID");
+  });
+
+  test("exports at least 20 variables", () => {
+    expect(Object.keys(CI).length).toBeGreaterThanOrEqual(20);
+  });
+});