v1.6.1

Patch Changes

• 34e30ad: updated dependencies

v1.6.0

Minor Changes

• e53a7c1: Added pipeline simulation feature and improved remote extends handling

  Simulation Features:

  • Added simulate CLI command to simulate GitLab CI pipeline execution
  • Added PipelineSimulator class for rule evaluation and job filtering
  • Support for branch, tag, and merge request pipeline simulation
  • Multiple output formats: summary, table, JSON, YAML, and text
  • Predefined CI variables automatically set based on context
  • Comprehensive integration and E2E test coverage

  Remote Extends Improvements:

  • Added mergeRemoteExtends global option to control remote extends resolution
  • Fixed remote extends resolution for accurate pipeline simulation
  • Better handling of remote includes and templates

  Documentation & Testing:

  • Enhanced CLI documentation with predefined variables table
  • Added error handling documentation for remote includes
  • Added "Common Pitfalls & Best Practices" section
  • Improved JSDoc coverage for all public APIs

v1.5.0

Minor Changes

• b6d0966: Add child pipeline visualization and fluent API support

  New Features:

  • Added childPipeline() method to define child pipelines via callback API
  • Added writeYamlFiles() method to automatically write parent and all child pipeline YAML files
  • Child pipelines are now fully visualized in Mermaid diagrams, ASCII trees, and stage tables
  • Child pipelines defined via callback are tracked and don't require filesystem access for visualization

  API Changes:

  • Added ChildPipelineConfig interface to track child pipeline configurations
  • Extended PipelineState with childPipelines map and getter methods
  • Added public getters to ConfigBuilder: jobs, templates, stages, jobOptionsMap
  • Extended VisualizationParams with trackedChildPipelines parameter
  • Enhanced extractChildPipelines to prioritize tracked configs over file system parsing

  Visualization Enhancements:

  • generateMermaidDiagram shows child pipelines as subgraphs with dotted trigger edges
  • generateAsciiTree displays child pipelines with 🔀 indicator
  • generateStageTable includes child pipeline jobs with separator rows and proper indentation
  • Added TriggerInfo interface to track trigger configurations in ExtendsGraphNode
  • Extended buildExtendsGraph to extract trigger information from job definitions

  Example:

  config.childPipeline(
    "trigger:deploy",
    (child) => {
      child.stages("deploy")
      child.job("deploy:prod", { script: ["./deploy.sh"] })
      return child
    },
    {
      strategy: "depend",
      outputPath: "ci/deploy-pipeline.yml",
    },
  )
  
  await config.writeYamlFiles(".")
  // Writes: .gitlab-ci.yml + ci/deploy-pipeline.yml

v1.4.2

Patch Changes

• ac8da01: Add "Limitations" section to README

v1.4.1

Patch Changes

• 2b79ae0: Add comprehensive JSDoc documentation across the entire codebase
  • Added detailed JSDoc comments to all public APIs and internal functions
  • Included practical examples for complex methods
  • Added @see references linking to official GitLab CI/CD documentation
  • Documented all helper functions in importer, resolver, serializer, and visualization modules
  • Enhanced PipelineState class methods with parameter descriptions and usage examples
  • Improved documentation for TypeScript AST generation utilities

v1.4.0

Minor Changes

• 87c99cf: Improve visualization rendering with professional libraries
  • Replace custom ASCII tree rendering with oo-ascii-tree for better box-drawing characters
  • Replace custom table rendering with climt for professional CLI tables
    • Change table layout from horizontal to vertical (Stage | Job columns)
    • Display one job per row with full ext ends chains

v1.3.0

Minor Changes

• 280e33e: Add CLI visualization tool for GitLab CI pipelines

  • New gitlab-ci-builder command-line tool with visualize subcommand
  • Supports multiple input formats: local YAML files and remote URLs
  • Three visualization formats:
    • Mermaid diagram: Interactive flowchart visualization
    • ASCII tree: Text-based dependency tree
    • Stage table: Organized view by pipeline stages
  • Built-in support for extends resolution and dependency analysis
  • Easy to use: npx @noxify/gitlab-ci-builder visualize .gitlab-ci.yml

  CLI Usage

  # Visualize local YAML file (all formats)
  gitlab-ci-builder visualize .gitlab-ci.yml
  
  # Show only Mermaid diagram
  gitlab-ci-builder visualize .gitlab-ci.yml -f mermaid
  
  # Visualize remote pipeline
  gitlab-ci-builder visualize https://gitlab.com/my-org/my-project/-/raw/main/.gitlab-ci.yml
  
  # Show ASCII tree without stages
  gitlab-ci-builder visualize pipeline.yml -f ascii --show-stages=false

  Programmatic Usage

  Using YAML

  import { visualizeYaml } from "@noxify/gitlab-ci-builder"
  
  const yamlContent = `
  stages: [build, test]
  build:
    stage: build
    script: npm run build
  `
  
  const result = await visualizeYaml(yamlContent, { format: "all" })
  console.log(result.mermaid) // Mermaid diagram
  console.log(result.ascii) // ASCII tree
  console.log(result.table) // Stage table

  Using ConfigBuilder - Show only local jobs

  import { ConfigBuilder } from "@noxify/gitlab-ci-builder"
  
  const config = new ConfigBuilder()
    .stages("build", "test", "deploy")
    .template(".base", { image: "node:22" })
    .extends(".base", "build", { stage: "build", script: ["npm run build"] })
    .extends(".base", "test", { stage: "test", script: ["npm test"] })
  
  // Generate visualizations directly from ConfigBuilder
  const mermaid = config.generateMermaidDiagram({ showStages: true })
  const ascii = config.generateAsciiTree({ showRemotes: true })
  const table = config.generateStageTable()
  
  console.log(mermaid)
  console.log(ascii)
  console.log(table)

  Using ConfigBuilder - Resolve also configured includes

  import { ConfigBuilder, visualizeYaml } from "@noxify/gitlab-ci-builder"
  
  const config = new ConfigBuilder()
    .include({ remote: "https://custom-gitlab-host.com/org/branch/spec.yml" })
    .stages("build", "test", "deploy")
    .template(".base", { image: "node:22" })
    .extends(".base", "build", { stage: "build", script: ["npm run build"] })
    .extends(".base", "test", { stage: "test", script: ["npm test"] })
  
  const yaml = config.toYaml()
  const result = await visualizeYaml(yaml, {
    format: "all",
    // Optional: Authentication for private repositories
    gitlabToken: process.env.GITLAB_TOKEN,
    // Optional: GitLab host URL for project/template includes (default: https://gitlab.com)
    gitlabUrl: "https://custom-gitlab-host.com",
  })
  
  console.log(result.mermaid)
  console.log(result.ascii)
  console.log(result.table)

v1.2.0

Minor Changes

• 712ec0d: Fluent Job Builder API

  New Feature: Fluent Job Builder API

  Added a powerful fluent builder interface for defining jobs and templates with chainable methods:

  New Methods:

  • addJob(name) - Create a new job with fluent builder interface
  • addTemplate(name) - Create a new template with fluent builder interface

  JobBuilder Methods:
  Common properties:

  • stage(stage) - Set job stage
  • extends(extend) - Set extends
  • image(image) - Set image
  • script(script) - Set script
  • beforeScript(script) - Set before_script
  • afterScript(script) - Set after_script
  • services(services) - Set services
  • cache(cache) - Set cache
  • artifacts(artifacts) - Set artifacts
  • setVariables(vars) - Set job variables
  • environment(env) - Set environment
  • when(when) - Set when condition
  • rules(rules) - Set rules
  • needs(needs) - Set needs
  • tags(tags) - Set tags
  • allowFailure(bool) - Set allow_failure
  • timeout(timeout) - Set timeout
  • retry(retry) - Set retry
  • parallel(parallel) - Set parallel
  • trigger(trigger) - Set trigger
  • coverage(pattern) - Set coverage pattern
  • dependencies(deps) - Set dependencies
  • resourceGroup(group) - Set resource_group
  • release(release) - Set release
  • interruptible(bool) - Set interruptible
  • idTokens(tokens) - Set id_tokens

  Utility methods:

  • set(props) - Bulk set multiple properties at once
  • jobOptions(opts) - Set job options (remote, mergeExtends, etc.)
  • remote(bool) - Mark job as remote
  • mergeExtends(bool) - Control extends merging
  • resolveTemplatesOnly(bool) - Control template resolution
  • done() - Finalize job and return to ConfigBuilder

  Auto-Return Behavior:
  When you call addJob() or addTemplate() from a JobBuilder, the previous job is automatically saved and a new builder is returned:

  const config = new ConfigBuilder()
  
  // Fluent API with auto-return
  config
    .stages("build", "test", "deploy")
    .addTemplate(".node")
    .image("node:20")
    .cache({ paths: ["node_modules/"] })
    .addJob("test")
    .stage("test")
    .extends(".node")
    .script(["npm test"])
    .addJob("build")
    .stage("build")
    .extends(".node")
    .script(["npm run build"])
    .addJob("deploy")
    .stage("deploy")
    .extends("build")
    .script(["kubectl apply -f k8s/"])
    .when("manual")
    .done()
  
  // Or use done() to explicitly return to ConfigBuilder
  config
    .addJob("lint")
    .stage("test")
    .script(["npm run lint"])
    .done()
    .addJob("format")
    .stage("test")
    .script(["npm run format:check"])
    .done()
  
  // Bulk property updates with set()
  config
    .addJob("complex")
    .set({
      stage: "test",
      image: "node:20",
      script: ["npm test"],
      cache: { paths: ["node_modules/"] },
      artifacts: { paths: ["coverage/"] },
    })
    .done()

  Benefits:

  • Type-safe: Full TypeScript support with autocomplete
  • Readable: Clear, declarative pipeline definitions
  • Flexible: Mix with existing job() and template() methods
  • Convenient: Auto-return behavior reduces boilerplate
  • Powerful: All job properties supported with dedicated methods

  This fluent API is especially useful for complex pipelines with many jobs, making the code more maintainable and easier to read.

• 712ec0d: Graph Visualization

  New Features: Graph Visualization

  Added powerful visualization capabilities to analyze and visualize extends relationships in your GitLab CI pipelines:

  New Methods:

  • getExtendsGraph() - Get the extends dependency graph for programmatic access
  • generateMermaidDiagram(options?) - Generate Mermaid diagram for documentation/GitHub
  • generateAsciiTree(options?) - Generate ASCII tree for terminal output
  • generateStageTable(options?) - Generate CLI table with stages as columns

  Visualization Options:

  • showRemote: boolean - Show remote jobs with 🌐 indicator
  • showStages: boolean - Include job stages in output
  • highlightCycles: boolean - Highlight circular dependencies if detected

  Example Usage:

  const config = new ConfigBuilder()
  // ... configure your pipeline ...
  
  // Generate individual visualizations
  const mermaid = config.generateMermaidDiagram({ showStages: true })
  const ascii = config.generateAsciiTree({ showRemote: true })
  const table = config.generateStageTable()
  
  console.log(mermaid) // Mermaid diagram
  console.log(ascii) // ASCII tree
  console.log(table) // Stage table

  This feature is especially useful for:

  • Documenting complex CI configurations
  • Debugging extends chains and dependencies
  • Understanding job relationships at a glance
  • Detecting circular dependencies visually

• 712ec0d: Enhanced Validation API

  New Feature: Enhanced Validation API

  Added dedicated validation methods for better control over pipeline validation:

  New Methods:

  • validate() - Validate pipeline and throw errors if validation fails (logs warnings to console)
  • safeValidate() - Validate pipeline without throwing errors, returns validation result with { valid, errors, warnings }

  Enhanced Methods:

  • getPlainObject(options?) - Now accepts { skipValidation?: boolean } option to skip validation when you've already validated separately
  • toJSON(options?) - Now accepts { skipValidation?: boolean } option
  • toYaml(options?) - Now accepts { skipValidation?: boolean } option

  Breaking Changes:

  • finalize() is now private - use safeValidate() for programmatic validation or validate() for validation that throws errors

  Usage Examples:

  // Standard validation (throws on error)
  config.validate()
  const pipeline = config.getPlainObject({ skipValidation: true })
  
  // Safe validation (no throw)
  const result = config.safeValidate()
  if (!result.valid) {
    console.error("Validation errors:", result.errors)
    return
  }
  if (result.warnings.length > 0) {
    console.warn("Warnings:", result.warnings)
  }
  const pipeline = config.getPlainObject({ skipValidation: true })
  
  // Quick validation (default behavior)
  const pipeline = config.getPlainObject() // validates automatically

  Benefits:

  • Separation of concerns: Validation is now separate from pipeline retrieval
  • Better error handling: safeValidate() enables programmatic error handling without try/catch
  • Performance: Skip validation when using multiple output methods (toYaml(), toJSON(), etc.)
  • Flexible: Choose between throwing (validate()) or returning errors (safeValidate())

v1.1.1

Patch Changes

• 118f5d4: Fixed extends resolution behavior with resolveTemplatesOnly: true

  Previously, when resolveTemplatesOnly: true was set (the default), ALL extends were removed after merging, including normal jobs and remote references that should have been preserved.

  Old behavior (incorrect):

  • Templates (.prefix) were merged ✅
  • Normal jobs (without .) were merged ❌ (should stay in extends)
  • Remote jobs were merged ❌ (should stay in extends)
  • Unknown/external jobs were merged ❌ (should stay in extends)

  New behavior (correct):

  • Templates (.prefix) are merged ✅
  • Normal jobs (without .) remain in extends ✅
  • Remote jobs remain in extends ✅
  • Unknown/external jobs remain in extends ✅

  This fix enables proper GitLab CI template composition patterns, particularly for shallow jobs that use remote: true to reference jobs from other configurations without merging them.

v1.1.0

Minor Changes

• a04d3ff: Add comprehensive test infrastructure for GitLab CI templates with local YAML storage and improve type safety for rules array access
  • Add test helper utilities for GitLab template round-trip testing
  • Add 22 official GitLab CI templates as local test fixtures
  • Add integration tests for language templates (19 tests)
  • Add integration tests for infrastructure templates (3 tests)
  • Add integration tests for browser performance artifacts (2 tests)
  • Add support for spec with inputs (GitLab CI/CD components)
  • Add integration tests for multi-document YAML with OpenTofu component
  • Add interpolation support for schema fields that can contain GitLab CI/CD variables
  • Fix TypeScript type errors in test assertions for rules array access by adding proper type guards
  • Remove 'pages' from reserved job names (it's a valid GitLab Pages job name)
  • Reorganize tests into unit and integration directories