Add pipeline simulation with simulate CLI command (#21)

* update deps

* update parameter description for `flattenScriptArray` function

* add missing dependency

* reorganize script properties

* add tests for flattening nested script arrays in YAML import

* fix lint issue

* enhance service merging logic and update schemas for better type handling

* feat: Implement pipeline simulation feature

- Added a new command `simulate` to simulate GitLab CI pipeline execution based on variables and rules.
- Introduced `PipelineSimulator` class to handle the simulation logic, including job evaluation based on rules and context.
- Created `RuleEvaluator` class to evaluate rules against the provided context.
- Enhanced job definitions to support rules for conditional execution.
- Updated types to accommodate new simulation features, including support for multiple job inputs and outputs.
- Added comprehensive unit tests to validate simulation behavior under various scenarios, including rules evaluation and job execution order.

* Add integration tests for pipeline simulation with nested remote includes

* - add comprehensive test cases for config builder, rule evaluator, and template validation
- Introduced tests for remote job extends normalization to ensure string extends are handled correctly.
- Added tests for variable and job merge order, verifying child definitions override parent definitions.
- Implemented tests for rule evaluator, covering AND operator and not-equal operator scenarios.
- Enhanced simulation tests to cover file existence checks, variable interpolation, and various rule conditions.
- Created tests for template extends chain resolution and lenient validation of templates.
- Updated visualization tests to ensure graceful handling of missing includes.

Author: noxify

.changeset/smooth-cows-doubt.md

@@ -0,0 +1,27 @@
+---
+"@noxify/gitlab-ci-builder": minor
+---
+
+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

.github/copilot-instructions.md

@@ -30,8 +30,7 @@
   1. Types first
   2. React/Next.js/Expo (if applicable)
   3. Third-party modules
-  4. @vorsteh-queue packages
-  5. Relative imports (~/,../, ./)
+  4. Relative imports (~/,../, ./)
 
 ## Code Generation Guidelines
 

.github/workflows/ci.yml

@@ -80,6 +80,9 @@ jobs:
       - name: Integration Tests
         run: pnpm test:integration
 
+      - name: E2E Tests
+        run: pnpm test:e2e
+
   pkg-new-release:
     needs: [lint, format, typecheck]
     if: github.event_name == 'pull_request'