refactor: make finalize() private, add public validation API

- Add validate() and safeValidate() methods for validation
- Enhance getPlainObject/toJSON/toYaml with skipValidation option
- Remove visualizeGraph() method (use individual methods instead)
- Update all tests to use new validation pattern

Author: noxify

.changeset/add-fluent-api.md

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

.changeset/add-graph-visualization.md

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

.changeset/add-validation-api.md

@@ -0,0 +1,53 @@
+---
+"@noxify/gitlab-ci-builder": minor
+---
+
+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:**
+
+```typescript
+// 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()`)

README.md

@@ -506,18 +506,20 @@ the runtime builder and are derived from the JSDoc on the source `ConfigBuilder`
 - `patch(callback: (plain: GitLabCi) => void): void`
   - Register a patcher callback that runs on the plain object before it is returned.
 
-- `getPlainObject(): PipelineOutput`
+- `validate(): void`
+  - Validate the configuration and throw an error if validation fails. Logs warnings to console.
+
+- `safeValidate(): SafeValidationResult`
+  - Validate the configuration without throwing. Returns `{ valid: boolean, errors: ValidationError[], warnings: ValidationError[] }`.
+
+- `getPlainObject(options?: { skipValidation?: boolean }): PipelineOutput`
   - Return a YAML-serializable pipeline object with resolved extends and applied patchers.
-    Returns the result of `finalize().pipeline`.
+  - By default, validates before returning. Set `skipValidation: true` to skip validation (e.g., after calling `safeValidate()`).
 
-- `toJSON(): PipelineOutput`
+- `toJSON(options?: { skipValidation?: boolean }): PipelineOutput`
   - Alias for `getPlainObject()` (useful for `JSON.stringify`).
 
-- `finalize(): FinalizeResult`
-  - Finalize the configuration and return the resolved pipeline with validation metadata.
-  - Returns `{ pipeline: PipelineOutput, errors: ValidationError[], warnings: ValidationError[], metadata: { skippedChecks: string[] } }`
-
-- `toYaml(): string`
+- `toYaml(options?: { skipValidation?: boolean }): string`
   - Convert the configuration to a formatted YAML string.
 
 - `writeYamlFile(filePath: string): Promise<void>`