@intentius/chant-lexicon-gitlab 0.0.4 → 0.0.6

package/README.md

@@ -1,58 +1,21 @@
 # @intentius/chant-lexicon-gitlab
 
-> Part of the [chant](../../README.md) monorepo. Published as [`@intentius/chant-lexicon-gitlab`](https://www.npmjs.com/package/@intentius/chant-lexicon-gitlab) on npm.
+GitLab CI lexicon for [chant](https://intentius.io/chant/) — declare CI/CD pipelines as typed TypeScript that serializes to `.gitlab-ci.yml`.
 
-GitLab CI lexicon for chant — declare CI/CD pipelines as flat, typed TypeScript that serializes to `.gitlab-ci.yml`.
+This package provides typed constructors for all GitLab CI keywords (Jobs, Workflows, Defaults, and property types like Artifacts, Cache, Image, Rule, Environment, and Trigger), the `CI` pseudo-parameter object for predefined variables, the `reference()` intrinsic for YAML `!reference` tags, and GitLab-specific lint rules. It also includes LSP and MCP server support for editor completions and hover.
 
-## Overview
-
-This package provides:
-
-- **GitLab CI serializer** — converts chant declarables to GitLab CI YAML
-- **Resource types** — typed constructors for `Job`, `Default`, `Workflow`, and all GitLab CI keywords
-- **Property types** — `Artifacts`, `Cache`, `Image`, `Rule`, `Retry`, `Environment`, `Trigger`, and more
-- **Lint rules** — GitLab-specific validation (e.g. missing script, deprecated only/except)
-- **Code generation** — generates TypeScript types from the GitLab CI JSON schema
-- **LSP/MCP support** — completions and hover for GitLab CI keywords
-
-## Usage
-
-```typescript
-import { Job, Artifacts, Image } from "@intentius/chant-lexicon-gitlab";
-
-export const testJob = new Job({
-  stage: "test",
-  image: new Image({ name: "node:20" }),
-  script: ["npm ci", "npm test"],
-  artifacts: new Artifacts({
-    paths: ["coverage/"],
-    expireIn: "1 week",
-  }),
-});
+```bash
+npm install --save-dev @intentius/chant @intentius/chant-lexicon-gitlab
 ```
 
-## Lint Rules
-
-| Rule | Description |
-|------|-------------|
-| `missing-script` | Job must have a `script` keyword |
-| `missing-stage` | Job should declare a `stage` |
-| `deprecated-only-except` | Flags use of deprecated `only`/`except` keywords |
-| `artifact-no-expiry` | Artifacts should have `expire_in` set |
-
-## Code Generation
-
-The GitLab lexicon generates types from the [GitLab CI JSON schema](https://gitlab.com/gitlab-org/gitlab/-/raw/master/app/assets/javascripts/editor/schema/ci.json):
-
-- `codegen/generate.ts` — calls core `generatePipeline<GitLabParseResult>` with GitLab callbacks
-- `codegen/naming.ts` — extends core `NamingStrategy` for GitLab CI keywords
-- `codegen/package.ts` — calls core `packagePipeline` with GitLab manifest
-- `codegen/parse.ts` — parses the GitLab CI JSON schema into typed entities
+**[Documentation →](https://intentius.io/chant/lexicons/gitlab/)**
 
 ## Related Packages
 
-- `@intentius/chant` — core functionality, type system, and CLI
-- `@intentius/chant-lexicon-aws` — AWS CloudFormation lexicon
+| Package | Role |
+|---------|------|
+| [@intentius/chant](https://www.npmjs.com/package/@intentius/chant) | Core type system, CLI, build pipeline |
+| [@intentius/chant-lexicon-aws](https://www.npmjs.com/package/@intentius/chant-lexicon-aws) | AWS CloudFormation lexicon |
 
 ## License
 

package/dist/integrity.json

@@ -1,9 +1,9 @@
 {
   "algorithm": "xxhash64",
   "artifacts": {
-    "manifest.json": "81dcdbe14578ccdf",
-    "meta.json": "3a60a5c15437a93b",
-    "types/index.d.ts": "2ab52d25cd1a5a14",
+    "manifest.json": "c72b64b58dec21e0",
+    "meta.json": "9ee0d2f2d1679f09",
+    "types/index.d.ts": "4e56a7de40d655c0",
     "rules/missing-stage.ts": "6d5379e74209a735",
     "rules/missing-script.ts": "923dde9acb46cc28",
     "rules/deprecated-only-except.ts": "1f5a8c785777fb03",
@@ -13,5 +13,5 @@
     "rules/wgl010.ts": "1548cad287cdf286",
     "skills/gitlab-ci.md": "f860e40c2643c327"
   },
-  "composite": "3bc48547ad8cfc19"
+  "composite": "95b9f28f579d5862"
 }

package/dist/manifest.json

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

package/dist/meta.json

@@ -64,6 +64,11 @@
     "kind": "property",
     "lexicon": "gitlab"
   },
+  "Service": {
+    "resourceType": "GitLab::CI::Service",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
   "Trigger": {
     "resourceType": "GitLab::CI::Trigger",
     "kind": "property",

package/dist/types/index.d.ts

@@ -203,6 +203,19 @@ export declare class Rule {
   });
 }
 
+export declare class Service {
+  constructor(props: {
+    /** Full name of the image that should be used. It should contain the Registry part if needed. */
+    name: string;
+    alias?: string;
+    command?: string[];
+    docker?: Record<string, unknown>;
+    entrypoint?: string[];
+    pull_policy?: "always" | "never" | "if-not-present" | "always" | "never" | "if-not-present"[];
+    variables?: Record<string, unknown>;
+  });
+}
+
 export declare class Trigger {
   constructor(props: {
     /** Path to the project, e.g. `group/project`, or `group/sub-group/project`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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.4"
+  "@intentius/chant": "0.0.5"
 },
 "devDependencies": {
   "typescript": "^5.9.3"

package/src/codegen/docs.ts

@@ -28,20 +28,7 @@ npm install --save-dev @intentius/chant-lexicon-gitlab
 
 ## Quick Start
 
-\`\`\`typescript
-import { Job, Image, Cache, Artifacts, CI } from "@intentius/chant-lexicon-gitlab";
-
-export const test = new Job({
-  stage: "test",
-  image: new Image({ name: "node:20" }),
-  cache: new Cache({ key: CI.CommitRef, paths: ["node_modules/"] }),
-  script: ["npm ci", "npm test"],
-  artifacts: new Artifacts({
-    paths: ["coverage/"],
-    expireIn: "1 week",
-  }),
-});
-\`\`\`
+{{file:docs-snippets/src/quickstart.ts}}
 
 The lexicon provides **3 resources** (Job, Workflow, Default), **13 property types** (Image, Cache, Artifacts, Rule, Environment, Trigger, and more), the \`CI\` pseudo-parameter object for predefined variables, and the \`reference()\` intrinsic for YAML \`!reference\` tags.
 `;
@@ -113,6 +100,7 @@ export async function generateDocs(opts?: { verbose?: boolean }): Promise<void>
     outputFormat,
     serviceFromType,
     suppressPages: ["intrinsics", "rules"],
+    examplesDir: join(pkgDir, "examples"),
     extraPages: [
       {
         slug: "pipeline-concepts",
@@ -125,14 +113,7 @@ export async function generateDocs(opts?: { verbose?: boolean }): Promise<void>
 - Collects stages from all jobs into a \`stages:\` list
 - Collapses single-property objects (\`new Image({ name: "node:20" })\` → \`image: node:20\`)
 
-\`\`\`typescript
-// This chant declaration...
-export const buildApp = new Job({
-  stage: "build",
-  image: new Image({ name: "node:20" }),
-  script: ["npm ci", "npm run build"],
-});
-\`\`\`
+{{file:docs-snippets/src/job-basic.ts}}
 
 Produces this YAML:
 
@@ -177,47 +158,17 @@ The lexicon provides 3 resource types and 13 property types:
 | \`Release\` | Job | GitLab Release creation |
 | \`AutoCancel\` | Workflow | Pipeline auto-cancellation settings |
 
-## The barrel file
-
-Every chant project has a barrel file (conventionally \`_.ts\`) that re-exports the lexicon:
-
-\`\`\`typescript
-// _.ts — the barrel file
-export * from "@intentius/chant-lexicon-gitlab";
-export * from "./config";
-\`\`\`
+## Shared config
 
-Other files import the barrel and use its exports:
+Extract reusable objects into a shared config file and import them across your pipeline files:
 
-\`\`\`typescript
-// pipeline.ts
-import * as _ from "./_";
-
-export const build = new _.Job({
-  stage: "build",
-  image: _.nodeImage,        // from config.ts via barrel
-  cache: _.npmCache,         // from config.ts via barrel
-  script: ["npm ci", "npm run build"],
-  artifacts: _.buildArtifacts,
-});
-\`\`\`
+{{file:docs-snippets/src/pipeline-barrel.ts}}
 
 ## Jobs
 
 A \`Job\` is the fundamental unit. Every exported \`Job\` becomes a job entry in the YAML:
 
-\`\`\`typescript
-export const test = new Job({
-  stage: "test",
-  image: new Image({ name: "node:20-alpine" }),
-  script: ["npm ci", "npm test"],
-  artifacts: new Artifacts({
-    paths: ["coverage/"],
-    expireIn: "1 week",
-    reports: { junit: "coverage/junit.xml" },
-  }),
-});
-\`\`\`
+{{file:docs-snippets/src/job-test.ts}}
 
 Key properties:
 - \`script\` — **required** (or \`trigger\`/\`run\`). Array of shell commands to execute.
@@ -229,12 +180,7 @@ Key properties:
 
 Stages define the execution order of a pipeline. The serializer automatically collects unique stage values from all jobs:
 
-\`\`\`typescript
-export const lint = new Job({ stage: "test", script: ["npm run lint"] });
-export const test = new Job({ stage: "test", script: ["npm test"] });
-export const build = new Job({ stage: "build", script: ["npm run build"] });
-export const deploy = new Job({ stage: "deploy", script: ["npm run deploy"] });
-\`\`\`
+{{file:docs-snippets/src/stages.ts}}
 
 Produces:
 
@@ -249,30 +195,9 @@ Jobs in the same stage run in parallel. Stages run sequentially in declaration o
 
 ## Artifacts and caching
 
-**Artifacts** are files produced by a job and passed to later stages or stored for download:
-
-\`\`\`typescript
-export const buildArtifacts = new Artifacts({
-  paths: ["dist/"],
-  expireIn: "1 hour",         // always set expiry (WGL004 warns if missing)
-});
-
-export const testArtifacts = new Artifacts({
-  paths: ["coverage/"],
-  expireIn: "1 week",
-  reports: { junit: "coverage/junit.xml" },  // parsed by GitLab for MR display
-});
-\`\`\`
+**Artifacts** are files produced by a job and passed to later stages or stored for download. **Caches** persist files between pipeline runs to speed up builds. Both are shown in the shared config:
 
-**Caches** persist files between pipeline runs to speed up builds:
-
-\`\`\`typescript
-export const npmCache = new Cache({
-  key: "$CI_COMMIT_REF_SLUG",   // cache per branch
-  paths: ["node_modules/"],
-  policy: "pull-push",          // "pull" for read-only, "push" for write-only
-});
-\`\`\`
+{{file:docs-snippets/src/config.ts:4-22}}
 
 The key difference: artifacts are for passing files between **stages in the same pipeline**; caches are for speeding up **repeated pipeline runs**.
 
@@ -280,22 +205,7 @@ The key difference: artifacts are for passing files between **stages in the same
 
 \`Rule\` objects control when a job runs. They map to \`rules:\` entries in the YAML:
 
-\`\`\`typescript
-export const onMergeRequest = new Rule({
-  ifCondition: CI.MergeRequestIid,    // → if: $CI_MERGE_REQUEST_IID
-});
-
-export const onDefaultBranch = new Rule({
-  ifCondition: \`\${CI.CommitBranch} == \${CI.DefaultBranch}\`,
-  when: "manual",                      // require manual trigger
-});
-
-export const deploy = new Job({
-  stage: "deploy",
-  script: ["npm run deploy"],
-  rules: [onDefaultBranch],
-});
-\`\`\`
+{{file:docs-snippets/src/rules-conditions.ts}}
 
 Produces:
 
@@ -315,19 +225,7 @@ The \`ifCondition\` property maps to \`if:\` in the YAML (since \`if\` is a rese
 
 \`Environment\` defines a deployment target:
 
-\`\`\`typescript
-export const productionEnv = new Environment({
-  name: "production",
-  url: "https://example.com",
-});
-
-export const deploy = new Job({
-  stage: "deploy",
-  script: ["npm run deploy"],
-  environment: productionEnv,
-  rules: [onDefaultBranch],
-});
-\`\`\`
+{{file:docs-snippets/src/environment.ts}}
 
 GitLab tracks deployments to environments and provides rollback capabilities in the UI.
 
@@ -335,44 +233,19 @@ GitLab tracks deployments to environments and provides rollback capabilities in
 
 \`Image\` specifies the Docker image for a job:
 
-\`\`\`typescript
-export const nodeImage = new Image({ name: "node:20-alpine" });
-
-// With entrypoint override
-export const customImage = new Image({
-  name: "registry.example.com/my-image:latest",
-  entrypoint: ["/bin/sh", "-c"],
-});
-\`\`\`
+{{file:docs-snippets/src/images.ts}}
 
 ## Workflow
 
 \`Workflow\` controls pipeline-level settings — when pipelines run, auto-cancellation, and global includes:
 
-\`\`\`typescript
-export const workflow = new Workflow({
-  name: "CI Pipeline for $CI_COMMIT_REF_NAME",
-  rules: [
-    new Rule({ ifCondition: CI.MergeRequestIid }),
-    new Rule({ ifCondition: CI.CommitBranch }),
-  ],
-  autoCancel: new AutoCancel({
-    onNewCommit: "interruptible",
-  }),
-});
-\`\`\`
+{{file:docs-snippets/src/workflow.ts}}
 
 ## Default
 
 \`Default\` sets shared configuration inherited by all jobs:
 
-\`\`\`typescript
-export const defaults = new Default({
-  image: new Image({ name: "node:20-alpine" }),
-  cache: new Cache({ key: CI.CommitRef, paths: ["node_modules/"] }),
-  retry: new Retry({ max: 2, when: ["runner_system_failure"] }),
-});
-\`\`\`
+{{file:docs-snippets/src/defaults.ts}}
 
 Jobs can override any default property individually.
 
@@ -380,16 +253,7 @@ Jobs can override any default property individually.
 
 \`Trigger\` creates downstream pipeline jobs:
 
-\`\`\`typescript
-export const deployInfra = new Job({
-  stage: "deploy",
-  trigger: new Trigger({
-    project: "my-group/infra-repo",
-    branch: "main",
-    strategy: "depend",
-  }),
-});
-\`\`\``,
+{{file:docs-snippets/src/trigger.ts}}`,
       },
       {
         slug: "variables",
@@ -397,25 +261,7 @@ export const deployInfra = new Job({
         description: "GitLab CI/CD predefined variable references",
         content: `The \`CI\` object provides type-safe access to GitLab CI/CD predefined variables. These map to \`$CI_*\` environment variables at runtime.
 
-\`\`\`typescript
-import { CI, Job, Rule } from "@intentius/chant-lexicon-gitlab";
-
-// Use in rule conditions
-const onDefault = new Rule({
-  ifCondition: \`\${CI.CommitBranch} == \${CI.DefaultBranch}\`,
-});
-
-// Use in cache keys
-const cache = new Cache({
-  key: CI.CommitRef,       // → $CI_COMMIT_REF_NAME
-  paths: ["node_modules/"],
-});
-
-// Use in workflow names
-const workflow = new Workflow({
-  name: \`Pipeline for \${CI.CommitRef}\`,
-});
-\`\`\`
+{{file:docs-snippets/src/variables-usage.ts}}
 
 ## Variable reference
 
@@ -442,44 +288,7 @@ const workflow = new Workflow({
 
 ## Common patterns
 
-**Conditional on branch type:**
-
-\`\`\`typescript
-// Only on merge requests
-new Rule({ ifCondition: CI.MergeRequestIid })
-
-// Only on default branch
-new Rule({ ifCondition: \`\${CI.CommitBranch} == \${CI.DefaultBranch}\` })
-
-// Only on tags
-new Rule({ ifCondition: CI.CommitTag })
-\`\`\`
-
-**Dynamic naming:**
-
-\`\`\`typescript
-export const deploy = new Job({
-  stage: "deploy",
-  environment: new Environment({
-    name: \`review/\${CI.CommitRef}\`,
-    url: \`https://\${CI.CommitRef}.preview.example.com\`,
-  }),
-  script: ["deploy-preview"],
-});
-\`\`\`
-
-**Container registry:**
-
-\`\`\`typescript
-export const buildImage = new Job({
-  stage: "build",
-  image: new Image({ name: "docker:24" }),
-  script: [
-    \`docker build -t \${CI.RegistryImage}:\${CI.CommitSha} .\`,
-    \`docker push \${CI.RegistryImage}:\${CI.CommitSha}\`,
-  ],
-});
-\`\`\`
+{{file:docs-snippets/src/variables-patterns.ts}}
 `,
       },
       {
@@ -488,21 +297,11 @@ export const buildImage = new Job({
         description: "GitLab CI/CD intrinsic functions and their chant syntax",
         content: `The GitLab lexicon provides one intrinsic function: \`reference()\`, which maps to GitLab's \`!reference\` YAML tag.
 
-\`\`\`typescript
-import { reference } from "@intentius/chant-lexicon-gitlab";
-\`\`\`
-
 ## \`reference()\` — reuse job properties
 
 The \`reference()\` intrinsic lets you reuse properties from other jobs or hidden keys. It produces the \`!reference\` YAML tag:
 
-\`\`\`typescript
-import { reference, Job } from "@intentius/chant-lexicon-gitlab";
-
-export const deploy = new Job({
-  script: reference(".setup", "script"),
-});
-\`\`\`
+{{file:docs-snippets/src/reference-basic.ts}}
 
 Serializes to:
 
@@ -522,24 +321,7 @@ reference(jobName: string, property: string): ReferenceTag
 
 ### Use cases
 
-**Shared setup scripts:**
-
-\`\`\`typescript
-// Hidden key with shared setup (defined in .gitlab-ci.yml or included)
-// Reference its script from multiple jobs:
-
-export const test = new Job({
-  stage: "test",
-  beforeScript: reference(".node-setup", "before_script"),
-  script: ["npm test"],
-});
-
-export const lint = new Job({
-  stage: "test",
-  beforeScript: reference(".node-setup", "before_script"),
-  script: ["npm run lint"],
-});
-\`\`\`
+{{file:docs-snippets/src/reference-shared.ts}}
 
 Produces:
 
@@ -557,46 +339,9 @@ lint:
     - npm run lint
 \`\`\`
 
-**Shared rules:**
-
-\`\`\`typescript
-export const build = new Job({
-  stage: "build",
-  rules: reference(".default-rules", "rules"),
-  script: ["npm run build"],
-});
-\`\`\`
-
-**Nested references (multi-level):**
-
-\`\`\`typescript
-// Reference a specific nested element
-export const deploy = new Job({
-  script: reference(".setup", "script"),
-  environment: reference(".deploy-defaults", "environment"),
-});
-\`\`\`
-
 ### When to use \`reference()\` vs barrel imports
 
-Use **barrel imports** (\`_.$\`) when referencing chant-managed objects — the serializer resolves them at build time:
-
-\`\`\`typescript
-// Preferred for chant-managed config
-export const test = new Job({
-  cache: _.npmCache,           // resolved at build time
-  artifacts: _.testArtifacts,  // resolved at build time
-});
-\`\`\`
-
-Use **\`reference()\`** when referencing jobs or hidden keys defined outside chant (e.g. in included YAML files or templates):
-
-\`\`\`typescript
-// For external/included YAML definitions
-export const test = new Job({
-  beforeScript: reference(".ci-setup", "before_script"),
-});
-\`\`\`
+{{file:docs-snippets/src/reference-vs-barrel.ts}}
 `,
       },
       {
@@ -615,23 +360,7 @@ Lint rules analyze your TypeScript source code before build.
 
 Flags usage of \`only:\` and \`except:\` keywords, which are deprecated in favor of \`rules:\`. The \`rules:\` syntax is more flexible and is the recommended approach.
 
-\`\`\`typescript
-// Triggers WGL001
-export const deploy = new Job({
-  stage: "deploy",
-  script: ["npm run deploy"],
-  only: ["main"],                // deprecated
-});
-
-// Fixed — use rules instead
-export const deploy = new Job({
-  stage: "deploy",
-  script: ["npm run deploy"],
-  rules: [new Rule({
-    ifCondition: \`\${CI.CommitBranch} == \${CI.DefaultBranch}\`,
-  })],
-});
-\`\`\`
+{{file:docs-snippets/src/lint-wgl001.ts}}
 
 ### WGL002 — Missing script
 
@@ -639,26 +368,7 @@ export const deploy = new Job({
 
 A GitLab CI job must have \`script\`, \`trigger\`, or \`run\` defined. Jobs without any of these will fail pipeline validation.
 
-\`\`\`typescript
-// Triggers WGL002
-export const build = new Job({
-  stage: "build",
-  image: new Image({ name: "node:20" }),
-  // Missing script!
-});
-
-// Fixed — add script
-export const build = new Job({
-  stage: "build",
-  image: new Image({ name: "node:20" }),
-  script: ["npm run build"],
-});
-
-// Also valid — trigger job (no script needed)
-export const downstream = new Job({
-  trigger: new Trigger({ project: "my-group/other-repo" }),
-});
-\`\`\`
+{{file:docs-snippets/src/lint-wgl002.ts}}
 
 ### WGL003 — Missing stage
 
@@ -666,19 +376,7 @@ export const downstream = new Job({
 
 Jobs should declare a \`stage\` property. Without it, the job defaults to the \`test\` stage, which may not be the intended behavior.
 
-\`\`\`typescript
-// Triggers WGL003
-export const build = new Job({
-  script: ["npm run build"],
-  // No stage — defaults to "test"
-});
-
-// Fixed — declare the stage
-export const build = new Job({
-  stage: "build",
-  script: ["npm run build"],
-});
-\`\`\`
+{{file:docs-snippets/src/lint-wgl003.ts}}
 
 ### WGL004 — Artifacts without expiry
 
@@ -686,25 +384,7 @@ export const build = new Job({
 
 Flags \`Artifacts\` without \`expireIn\`. Artifacts without expiry are kept indefinitely, consuming storage. Always set an expiration.
 
-\`\`\`typescript
-// Triggers WGL004
-export const build = new Job({
-  script: ["npm run build"],
-  artifacts: new Artifacts({
-    paths: ["dist/"],
-    // Missing expireIn!
-  }),
-});
-
-// Fixed — set expiry
-export const build = new Job({
-  script: ["npm run build"],
-  artifacts: new Artifacts({
-    paths: ["dist/"],
-    expireIn: "1 hour",
-  }),
-});
-\`\`\`
+{{file:docs-snippets/src/lint-wgl004.ts}}
 
 ## Post-synth checks
 
@@ -722,16 +402,7 @@ Flags jobs that reference a stage not present in the collected stages list. This
 
 Flags jobs where all \`rules:\` entries have \`when: "never"\`, making the job unreachable. This usually indicates a configuration error.
 
-\`\`\`typescript
-// Triggers WGL011 — job can never run
-export const noop = new Job({
-  script: ["echo unreachable"],
-  rules: [
-    new Rule({ ifCondition: CI.CommitBranch, when: "never" }),
-    new Rule({ ifCondition: CI.CommitTag, when: "never" }),
-  ],
-});
-\`\`\`
+{{file:docs-snippets/src/lint-wgl011.ts}}
 
 ## Running lint
 
@@ -756,7 +427,7 @@ To suppress globally in \`chant.config.ts\`:
 export default {
   lint: {
     rules: {
-      WGL003: "off",  // don't require stage on every job
+      WGL003: "off",
     },
   },
 };
@@ -783,100 +454,21 @@ bun test       # runs the example's tests
 
 \`\`\`
 src/
-├── _.ts           # Barrel — re-exports lexicon + shared config
 ├── config.ts      # Shared config: images, caches, artifacts, rules, environments
 └── pipeline.ts    # Job definitions: build, test, deploy
 \`\`\`
 
-### Barrel file
-
-The barrel re-exports both the lexicon and shared config, so pipeline files only need one import:
-
-\`\`\`typescript
-// _.ts
-export * from "@intentius/chant-lexicon-gitlab";
-export * from "./config";
-\`\`\`
-
 ### Shared configuration
 
 \`config.ts\` extracts reusable objects — images, caches, artifacts, rules, and environments — so jobs stay concise:
 
-\`\`\`typescript
-// config.ts
-import * as _ from "./_";
-
-export const nodeImage = new _.Image({ name: "node:20-alpine" });
-
-export const npmCache = new _.Cache({
-  key: "$CI_COMMIT_REF_SLUG",
-  paths: ["node_modules/"],
-  policy: "pull-push",
-});
-
-export const buildArtifacts = new _.Artifacts({
-  paths: ["dist/"],
-  expireIn: "1 hour",
-});
-
-export const testArtifacts = new _.Artifacts({
-  paths: ["coverage/"],
-  expireIn: "1 week",
-  reports: { junit: "coverage/junit.xml" },
-});
-
-export const onMergeRequest = new _.Rule({
-  ifCondition: _.CI.MergeRequestIid,
-});
-
-export const onCommit = new _.Rule({
-  ifCondition: _.CI.CommitBranch,
-});
-
-export const onDefaultBranch = new _.Rule({
-  ifCondition: \`\${_.CI.CommitBranch} == \${_.CI.DefaultBranch}\`,
-  when: "manual",
-});
-
-export const productionEnv = new _.Environment({
-  name: "production",
-  url: "https://example.com",
-});
-\`\`\`
+{{file:getting-started/src/config.ts}}
 
 ### Pipeline jobs
 
-\`pipeline.ts\` defines three jobs that reference shared config via the barrel:
+\`pipeline.ts\` defines three jobs that import shared config directly:
 
-\`\`\`typescript
-// pipeline.ts
-import * as _ from "./_";
-
-export const build = new _.Job({
-  stage: "build",
-  image: _.nodeImage,
-  cache: _.npmCache,
-  script: ["npm ci", "npm run build"],
-  artifacts: _.buildArtifacts,
-});
-
-export const test = new _.Job({
-  stage: "test",
-  image: _.nodeImage,
-  cache: _.npmCache,
-  script: ["npm ci", "npm test"],
-  artifacts: _.testArtifacts,
-  rules: [_.onMergeRequest, _.onCommit],
-});
-
-export const deploy = new _.Job({
-  stage: "deploy",
-  image: _.nodeImage,
-  script: ["npm run deploy"],
-  environment: _.productionEnv,
-  rules: [_.onDefaultBranch],
-});
-\`\`\`
+{{file:getting-started/src/pipeline.ts}}
 
 ### Generated output
 

package/src/codegen/generate-lexicon.ts

@@ -29,7 +29,7 @@ export function generateLexiconJSON(
     typeName: r.resource.typeName,
     attributes: r.resource.attributes,
     properties: r.resource.properties,
-    propertyTypes: r.propertyTypes.map((pt) => ({ name: pt.name, cfnType: pt.defType })),
+    propertyTypes: r.propertyTypes.map((pt) => ({ name: pt.name, specType: pt.defType })),
   }));
 
   const entries = buildRegistry<LexiconEntry>(registryResources, naming, {

package/src/codegen/parse.test.ts

@@ -5,9 +5,9 @@ import { loadSchemaFixture } from "../testdata/load-fixtures";
 const fixture = loadSchemaFixture();
 
 describe("parseCISchema", () => {
-  test("returns 15 entities", () => {
+  test("returns 16 entities", () => {
     const results = parseCISchema(fixture);
-    expect(results).toHaveLength(15);
+    expect(results).toHaveLength(16);
   });
 
   test("returns 3 resource entities", () => {
@@ -20,14 +20,15 @@ describe("parseCISchema", () => {
     expect(names).toContain("GitLab::CI::Workflow");
   });
 
-  test("returns 12 property entities", () => {
+  test("returns 13 property entities", () => {
     const results = parseCISchema(fixture);
     const properties = results.filter((r) => r.isProperty);
-    expect(properties).toHaveLength(12);
+    expect(properties).toHaveLength(13);
     const names = properties.map((r) => r.resource.typeName);
     expect(names).toContain("GitLab::CI::Artifacts");
     expect(names).toContain("GitLab::CI::Cache");
     expect(names).toContain("GitLab::CI::Image");
+    expect(names).toContain("GitLab::CI::Service");
     expect(names).toContain("GitLab::CI::Rule");
     expect(names).toContain("GitLab::CI::Retry");
     expect(names).toContain("GitLab::CI::AllowFailure");

package/src/codegen/parse.ts

@@ -132,6 +132,7 @@ const PROPERTY_ENTITIES: Array<{
   { typeName: "GitLab::CI::Artifacts", source: "#/definitions/artifacts", description: "Job artifact configuration" },
   { typeName: "GitLab::CI::Cache", source: "#/definitions/cache_item", description: "Cache configuration" },
   { typeName: "GitLab::CI::Image", source: "#/definitions/image", description: "Docker image for a job" },
+  { typeName: "GitLab::CI::Service", source: "#/definitions/services:item", description: "Docker service container for a job" },
   { typeName: "GitLab::CI::Rule", source: "#/definitions/rules:item", description: "Conditional rule for job execution" },
   { typeName: "GitLab::CI::Retry", source: "#/definitions/retry", description: "Job retry configuration" },
   { typeName: "GitLab::CI::AllowFailure", source: "#/definitions/allow_failure", description: "Allow failure configuration" },
@@ -266,17 +267,14 @@ function extractPropertyEntity(
  * Resolve a source path to a schema definition.
  */
 function resolveSource(schema: CISchema, source: string): CISchemaDefinition | null {
-  // Special case: rules array item extraction
-  if (source === "#/definitions/rules:item") {
-    const rulesDef = schema.definitions?.rules;
-    if (!rulesDef) return null;
-    // rules is an array — get items
-    const items = rulesDef.items;
-    if (!items) return null;
-    return findObjectVariant(items);
-  }
-
   if (source.startsWith("#/definitions/")) {
+    // Array item extraction: "#/definitions/foo:item" → foo.items object variant
+    if (source.includes(":item")) {
+      const defName = source.slice("#/definitions/".length).replace(":item", "");
+      const arrayDef = schema.definitions?.[defName];
+      if (!arrayDef?.items) return null;
+      return findObjectVariant(arrayDef.items);
+    }
     const defName = source.slice("#/definitions/".length);
     return schema.definitions?.[defName] ?? null;
   }

package/src/codegen/snapshot.test.ts

@@ -10,7 +10,7 @@ describe("generated lexicon-gitlab.json", () => {
   const registry = JSON.parse(content);
 
   test("is valid JSON with expected entries", () => {
-    expect(Object.keys(registry)).toHaveLength(15);
+    expect(Object.keys(registry)).toHaveLength(16);
   });
 
   test("contains all resource entities", () => {
@@ -30,7 +30,7 @@ describe("generated lexicon-gitlab.json", () => {
     const propertyNames = [
       "AllowFailure", "Artifacts", "AutoCancel", "Cache",
       "Environment", "Image", "Include", "Parallel",
-      "Release", "Retry", "Rule", "Trigger",
+      "Release", "Retry", "Rule", "Service", "Trigger",
     ];
     for (const name of propertyNames) {
       expect(registry[name]).toBeDefined();
@@ -55,7 +55,7 @@ describe("generated index.d.ts", () => {
       "Job", "Default", "Workflow",
       "AllowFailure", "Artifacts", "AutoCancel", "Cache",
       "Environment", "Image", "Include", "Parallel",
-      "Release", "Retry", "Rule", "Trigger",
+      "Release", "Retry", "Rule", "Service", "Trigger",
     ];
     for (const cls of expectedClasses) {
       expect(content).toContain(`export declare class ${cls}`);

package/src/generated/index.d.ts

@@ -203,6 +203,19 @@ export declare class Rule {
   });
 }
 
+export declare class Service {
+  constructor(props: {
+    /** Full name of the image that should be used. It should contain the Registry part if needed. */
+    name: string;
+    alias?: string;
+    command?: string[];
+    docker?: Record<string, unknown>;
+    entrypoint?: string[];
+    pull_policy?: "always" | "never" | "if-not-present" | "always" | "never" | "if-not-present"[];
+    variables?: Record<string, unknown>;
+  });
+}
+
 export declare class Trigger {
   constructor(props: {
     /** Path to the project, e.g. `group/project`, or `group/sub-group/project`. */

package/src/generated/index.ts

@@ -16,6 +16,7 @@ export const Parallel = createProperty("GitLab::CI::Parallel", "gitlab");
 export const Release = createProperty("GitLab::CI::Release", "gitlab");
 export const Retry = createProperty("GitLab::CI::Retry", "gitlab");
 export const Rule = createProperty("GitLab::CI::Rule", "gitlab");
+export const Service = createProperty("GitLab::CI::Service", "gitlab");
 export const Trigger = createProperty("GitLab::CI::Trigger", "gitlab");
 
 // Re-exports for convenience

package/src/generated/lexicon-gitlab.json

@@ -64,6 +64,11 @@
     "kind": "property",
     "lexicon": "gitlab"
   },
+  "Service": {
+    "resourceType": "GitLab::CI::Service",
+    "kind": "property",
+    "lexicon": "gitlab"
+  },
   "Trigger": {
     "resourceType": "GitLab::CI::Trigger",
     "kind": "property",

package/src/plugin.test.ts

@@ -96,7 +96,6 @@ describe("gitlabPlugin", () => {
   test("returns init templates", () => {
     const templates = gitlabPlugin.initTemplates!();
     expect(templates).toBeDefined();
-    expect(templates["_.ts"]).toBeDefined();
     expect(templates["config.ts"]).toBeDefined();
     expect(templates["test.ts"]).toBeDefined();
   });
@@ -192,7 +191,7 @@ describe("gitlabPlugin", () => {
     const result = await catalog.handler();
     const parsed = JSON.parse(result);
     expect(Array.isArray(parsed)).toBe(true);
-    expect(parsed.length).toBe(15);
+    expect(parsed.length).toBe(16);
     const job = parsed.find((e: { className: string }) => e.className === "Job");
     expect(job).toBeDefined();
     expect(job.kind).toBe("resource");

package/src/plugin.ts

@@ -41,20 +41,19 @@ export const gitlabPlugin: LexiconPlugin = {
 
   initTemplates(): Record<string, string> {
     return {
-      "_.ts": `export * from "./config";\n`,
       "config.ts": `/**
  * Shared pipeline configuration
  */
 
-import * as gl from "@intentius/chant-lexicon-gitlab";
+import { Image, Cache } from "@intentius/chant-lexicon-gitlab";
 
 // Default image for all jobs
-export const defaultImage = new gl.Image({
+export const defaultImage = new Image({
   name: "node:20-alpine",
 });
 
 // Standard cache configuration
-export const npmCache = new gl.Cache({
+export const npmCache = new Cache({
   key: "$CI_COMMIT_REF_SLUG",
   paths: ["node_modules/"],
   policy: "pull-push",
@@ -64,15 +63,15 @@ export const npmCache = new gl.Cache({
  * Test job
  */
 
-import * as gl from "@intentius/chant-lexicon-gitlab";
-import * as _ from "./_";
+import { Job, Artifacts } from "@intentius/chant-lexicon-gitlab";
+import { defaultImage, npmCache } from "./config";
 
-export const test = new gl.Job({
+export const test = new Job({
   stage: "test",
-  image: _.defaultImage,
-  cache: _.npmCache,
+  image: defaultImage,
+  cache: npmCache,
   script: ["npm ci", "npm test"],
-  artifacts: new gl.Artifacts({
+  artifacts: new Artifacts({
     reports: { junit: "coverage/junit.xml" },
     paths: ["coverage/"],
     expireIn: "1 week",
@@ -142,18 +141,9 @@ export const test = new gl.Job({
 
   async validate(options?: { verbose?: boolean }): Promise<void> {
     const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
     const result = await validate();
-
-    for (const check of result.checks) {
-      const status = check.ok ? "OK" : "FAIL";
-      const msg = check.error ? ` — ${check.error}` : "";
-      console.error(`  [${status}] ${check.name}${msg}`);
-    }
-
-    if (!result.success) {
-      throw new Error("Validation failed");
-    }
-    console.error("All validation checks passed.");
+    printValidationResult(result);
   },
 
   async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
@@ -166,7 +156,7 @@ export const test = new gl.Job({
 
   async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
     const { packageLexicon } = await import("./codegen/package");
-    const { writeFileSync, mkdirSync } = await import("fs");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
     const { join, dirname } = await import("path");
     const { fileURLToPath } = await import("url");
 
@@ -174,24 +164,7 @@ export const test = new gl.Job({
 
     const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
     const distDir = join(pkgDir, "dist");
-    mkdirSync(join(distDir, "types"), { recursive: true });
-    mkdirSync(join(distDir, "rules"), { recursive: true });
-    mkdirSync(join(distDir, "skills"), { recursive: true });
-
-    writeFileSync(join(distDir, "manifest.json"), JSON.stringify(spec.manifest, null, 2));
-    writeFileSync(join(distDir, "meta.json"), spec.registry);
-    writeFileSync(join(distDir, "types", "index.d.ts"), spec.typesDTS);
-
-    for (const [name, content] of spec.rules) {
-      writeFileSync(join(distDir, "rules", name), content);
-    }
-    for (const [name, content] of spec.skills) {
-      writeFileSync(join(distDir, "skills", name), content);
-    }
-
-    if (spec.integrity) {
-      writeFileSync(join(distDir, "integrity.json"), JSON.stringify(spec.integrity, null, 2));
-    }
+    writeBundleSpec(spec, distDir);
 
     console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
   },

package/src/validate.test.ts

@@ -6,38 +6,29 @@ import { fileURLToPath } from "url";
 const basePath = dirname(dirname(fileURLToPath(import.meta.url)));
 
 describe("validate", () => {
-  test("passes validation for current generated artifacts", async () => {
+  test("runs validation checks on current generated artifacts", async () => {
     const result = await validate({ basePath });
-    expect(result.success).toBe(true);
     expect(result.checks.length).toBeGreaterThan(0);
   });
 
-  test("checks all expected entities are present", async () => {
+  test("checks lexicon JSON exists and parses", async () => {
     const result = await validate({ basePath });
-    const checkNames = result.checks.map((c) => c.name);
-    expect(checkNames).toContain("resource Job present");
-    expect(checkNames).toContain("resource Default present");
-    expect(checkNames).toContain("resource Workflow present");
-    expect(checkNames).toContain("property Artifacts present");
-    expect(checkNames).toContain("property Cache present");
-    expect(checkNames).toContain("property Image present");
+    const jsonCheck = result.checks.find((c) => c.name === "lexicon-json-exists");
+    expect(jsonCheck).toBeDefined();
+    expect(jsonCheck?.ok).toBe(true);
   });
 
-  test("checks file existence", async () => {
+  test("checks types exist", async () => {
     const result = await validate({ basePath });
-    const fileChecks = result.checks.filter((c) => c.name.endsWith("exists"));
-    expect(fileChecks.length).toBeGreaterThan(0);
-    for (const check of fileChecks) {
-      expect(check.ok).toBe(true);
-    }
+    const typesCheck = result.checks.find((c) => c.name === "types-exist");
+    expect(typesCheck).toBeDefined();
+    expect(typesCheck?.ok).toBe(true);
   });
 
-  test("checks index.d.ts class declarations", async () => {
+  test("checks required names are present", async () => {
     const result = await validate({ basePath });
-    const dtsChecks = result.checks.filter((c) => c.name.startsWith("index.d.ts declares"));
-    expect(dtsChecks.length).toBeGreaterThan(0);
-    for (const check of dtsChecks) {
-      expect(check.ok).toBe(true);
-    }
+    const requiredCheck = result.checks.find((c) => c.name === "required-names");
+    expect(requiredCheck).toBeDefined();
+    expect(requiredCheck?.ok).toBe(true);
   });
 });

package/src/validate.ts

@@ -1,125 +1,34 @@
 /**
- * Semantic validation for GitLab CI lexicon artifacts.
+ * Validate generated lexicon-gitlab artifacts.
  *
- * Checks that generated files exist, contain expected entities,
- * and pass basic structural validation.
+ * Thin wrapper around the core validation framework
+ * with GitLab-specific configuration.
  */
 
-import { existsSync, readFileSync } from "fs";
-import { join, dirname } from "path";
+import { dirname } from "path";
 import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
 
-export interface ValidateCheck {
-  name: string;
-  ok: boolean;
-  error?: string;
-}
-
-export interface ValidateResult {
-  success: boolean;
-  checks: ValidateCheck[];
-}
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
 
-const EXPECTED_RESOURCES = ["Job", "Default", "Workflow"];
-const EXPECTED_PROPERTIES = [
-  "Artifacts", "Cache", "Image", "Rule", "Retry",
+const REQUIRED_NAMES = [
+  "Job", "Default", "Workflow",
+  "Artifacts", "Cache", "Image", "Service", "Rule", "Retry",
   "AllowFailure", "Parallel", "Include", "Release",
   "Environment", "Trigger", "AutoCancel",
 ];
 
 /**
- * Validate lexicon artifacts.
+ * Validate the generated lexicon-gitlab artifacts.
+ *
+ * @param opts.basePath - Override the package directory (defaults to lexicon-gitlab package root)
  */
 export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
   const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
-  const generatedDir = join(basePath, "src", "generated");
-  const checks: ValidateCheck[] = [];
-
-  // Check files exist
-  for (const file of ["lexicon-gitlab.json", "index.d.ts", "index.ts", "runtime.ts"]) {
-    const path = join(generatedDir, file);
-    checks.push({
-      name: `${file} exists`,
-      ok: existsSync(path),
-      error: existsSync(path) ? undefined : `File not found: ${path}`,
-    });
-  }
-
-  // Validate lexicon JSON structure
-  const lexiconPath = join(generatedDir, "lexicon-gitlab.json");
-  if (existsSync(lexiconPath)) {
-    try {
-      const content = readFileSync(lexiconPath, "utf-8");
-      const registry = JSON.parse(content);
-      const entries = Object.keys(registry);
-
-      // Check expected count
-      const expectedCount = EXPECTED_RESOURCES.length + EXPECTED_PROPERTIES.length;
-      checks.push({
-        name: `lexicon-gitlab.json has ${expectedCount} entries`,
-        ok: entries.length === expectedCount,
-        error: entries.length !== expectedCount
-          ? `Expected ${expectedCount} entries, found ${entries.length}`
-          : undefined,
-      });
-
-      // Check resource entities present
-      for (const name of EXPECTED_RESOURCES) {
-        const entry = registry[name];
-        const ok = entry !== undefined && entry.kind === "resource";
-        checks.push({
-          name: `resource ${name} present`,
-          ok,
-          error: ok ? undefined : `Missing or invalid resource entry: ${name}`,
-        });
-      }
-
-      // Check property entities present
-      for (const name of EXPECTED_PROPERTIES) {
-        const entry = registry[name];
-        const ok = entry !== undefined && entry.kind === "property";
-        checks.push({
-          name: `property ${name} present`,
-          ok,
-          error: ok ? undefined : `Missing or invalid property entry: ${name}`,
-        });
-      }
-
-      // Check all entries have required fields
-      for (const [name, entry] of Object.entries(registry)) {
-        const e = entry as Record<string, unknown>;
-        const hasRequired = e.resourceType && e.kind && e.lexicon === "gitlab";
-        checks.push({
-          name: `${name} has required fields`,
-          ok: !!hasRequired,
-          error: hasRequired ? undefined : `Entry ${name} missing required fields`,
-        });
-      }
-    } catch (err) {
-      checks.push({
-        name: "lexicon-gitlab.json is valid JSON",
-        ok: false,
-        error: `Parse error: ${err}`,
-      });
-    }
-  }
-
-  // Validate index.d.ts has class declarations
-  const dtsPath = join(generatedDir, "index.d.ts");
-  if (existsSync(dtsPath)) {
-    const dts = readFileSync(dtsPath, "utf-8");
-    for (const name of [...EXPECTED_RESOURCES, ...EXPECTED_PROPERTIES]) {
-      const has = dts.includes(`export declare class ${name}`);
-      checks.push({
-        name: `index.d.ts declares ${name}`,
-        ok: has,
-        error: has ? undefined : `Missing class declaration: ${name}`,
-      });
-    }
-  }
 
-  return {
-    success: checks.every((c) => c.ok),
-    checks,
-  };
+  return validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-gitlab.json",
+    requiredNames: REQUIRED_NAMES,
+    basePath,
+  });
 }