synthra 0.1.0

data/tech_docs/integration/ci_cd_guide.md

@@ -0,0 +1,579 @@
+# CI/CD Integration Guide
+
+Complete guide for integrating FakeDataDSL validation into your CI/CD pipelines.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [GitHub Actions](#github-actions)
+- [GitLab CI](#gitlab-ci)
+- [CircleCI](#circleci)
+- [Jenkins](#jenkins)
+- [Pre-commit Hooks](#pre-commit-hooks)
+- [Exit Codes](#exit-codes)
+- [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+FakeDataDSL provides a `lint` command with `--strict` mode specifically designed for CI pipelines. This ensures schema quality and catches errors before they reach production.
+
+### Why Integrate in CI?
+
+| Benefit | Description |
+|---------|-------------|
+| **Early Detection** | Catch schema errors before merge |
+| **Consistency** | Enforce team-wide schema standards |
+| **Documentation** | Schema info in PR reviews |
+| **Safety** | Prevent broken schemas in production |
+
+---
+
+## Quick Start
+
+### Basic Validation
+
+```bash
+# Validate all schemas in a directory
+fake_data_dsl lint schemas/
+
+# Strict mode - treat warnings as errors
+fake_data_dsl lint schemas/ --strict
+
+# Verbose output for debugging
+fake_data_dsl lint schemas/ --strict --verbose
+```
+
+### Exit Codes
+
+| Code | Meaning | CI Behavior |
+|------|---------|-------------|
+| `0` | Success, no issues | ✅ Pass |
+| `1` | Warnings found (non-strict mode passes) | ⚠️ Pass (non-strict) |
+| `2` | Errors found | ❌ Fail |
+
+---
+
+## GitHub Actions
+
+### Basic Workflow
+
+```yaml
+# .github/workflows/schema-validation.yml
+name: Schema Validation
+
+on:
+  push:
+    paths:
+      - 'schemas/**/*.dsl'
+  pull_request:
+    paths:
+      - 'schemas/**/*.dsl'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      
+      - name: Install FakeDataDSL
+        run: gem install fake_data_dsl
+      
+      - name: Validate Schemas
+        run: fake_data_dsl lint schemas/ --strict --verbose
+
+      - name: Generate Schema Info
+        run: fake_data_dsl info schemas/ --verbose
+```
+
+### With Schema Diff on PR
+
+```yaml
+# .github/workflows/schema-review.yml
+name: Schema Review
+
+on:
+  pull_request:
+    paths:
+      - 'schemas/**/*.dsl'
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for diff
+      
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      
+      - name: Install FakeDataDSL
+        run: gem install fake_data_dsl
+      
+      - name: Lint Schemas
+        run: fake_data_dsl lint schemas/ --strict
+      
+      - name: Checkout Base Branch
+        run: git checkout ${{ github.base_ref }} -- schemas/ 2>/dev/null || true
+        continue-on-error: true
+      
+      - name: Schema Diff
+        run: |
+          if [ -d "schemas_base" ]; then
+            fake_data_dsl diff schemas_base/ schemas/
+          else
+            echo "No base schemas to compare"
+          fi
+        continue-on-error: true
+      
+      - name: Preview Sample Data
+        run: |
+          for schema in $(fake_data_dsl info schemas/ --format json | jq -r '.schemas[].name'); do
+            echo "=== $schema ==="
+            fake_data_dsl preview $schema --dir schemas/ --pretty
+          done
+```
+
+### Matrix Testing Multiple Ruby Versions
+
+```yaml
+# .github/workflows/compatibility.yml
+name: Compatibility
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ['3.1', '3.2', '3.3']
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      
+      - name: Install FakeDataDSL
+        run: gem install fake_data_dsl
+      
+      - name: Validate Schemas
+        run: fake_data_dsl lint schemas/ --strict
+      
+      - name: Run Generation Tests
+        run: |
+          fake_data_dsl generate User --dir schemas/ --count 100 --seed 12345 > /dev/null
+          echo "Generation successful"
+```
+
+---
+
+## GitLab CI
+
+### Basic Pipeline
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - validate
+  - test
+
+variables:
+  RUBY_VERSION: "3.3"
+
+schema-lint:
+  stage: validate
+  image: ruby:${RUBY_VERSION}
+  before_script:
+    - gem install fake_data_dsl
+  script:
+    - fake_data_dsl lint schemas/ --strict --verbose
+  rules:
+    - changes:
+        - schemas/**/*.dsl
+
+schema-preview:
+  stage: test
+  image: ruby:${RUBY_VERSION}
+  before_script:
+    - gem install fake_data_dsl
+  script:
+    - fake_data_dsl info schemas/ --verbose
+    - |
+      for schema in User Order Product; do
+        echo "=== Preview: $schema ==="
+        fake_data_dsl preview $schema --dir schemas/ --pretty || true
+      done
+  artifacts:
+    reports:
+      dotenv: schema-info.env
+  rules:
+    - changes:
+        - schemas/**/*.dsl
+```
+
+### With MR Comments
+
+```yaml
+# .gitlab-ci.yml
+schema-review:
+  stage: validate
+  image: ruby:3.3
+  before_script:
+    - gem install fake_data_dsl
+  script:
+    - |
+      # Lint and capture output
+      OUTPUT=$(fake_data_dsl lint schemas/ --strict 2>&1) || EXIT_CODE=$?
+      
+      # Post as MR comment (requires CI_JOB_TOKEN with api scope)
+      if [ -n "$CI_MERGE_REQUEST_IID" ]; then
+        curl --request POST \
+          --header "PRIVATE-TOKEN: ${CI_JOB_TOKEN}" \
+          --form "body=### Schema Validation\n\`\`\`\n${OUTPUT}\n\`\`\`" \
+          "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/merge_requests/${CI_MERGE_REQUEST_IID}/notes"
+      fi
+      
+      exit ${EXIT_CODE:-0}
+  rules:
+    - if: $CI_MERGE_REQUEST_IID
+      changes:
+        - schemas/**/*.dsl
+```
+
+---
+
+## CircleCI
+
+```yaml
+# .circleci/config.yml
+version: 2.1
+
+orbs:
+  ruby: circleci/ruby@2.1
+
+jobs:
+  validate-schemas:
+    docker:
+      - image: cimg/ruby:3.3
+    steps:
+      - checkout
+      - run:
+          name: Install FakeDataDSL
+          command: gem install fake_data_dsl
+      - run:
+          name: Lint Schemas
+          command: fake_data_dsl lint schemas/ --strict --verbose
+      - run:
+          name: Schema Info
+          command: fake_data_dsl info schemas/
+      - store_artifacts:
+          path: schema-report.txt
+
+workflows:
+  schema-validation:
+    jobs:
+      - validate-schemas:
+          filters:
+            branches:
+              only: /.*/
+```
+
+---
+
+## Jenkins
+
+### Jenkinsfile (Declarative)
+
+```groovy
+// Jenkinsfile
+pipeline {
+    agent {
+        docker {
+            image 'ruby:3.3'
+        }
+    }
+    
+    stages {
+        stage('Setup') {
+            steps {
+                sh 'gem install fake_data_dsl'
+            }
+        }
+        
+        stage('Lint Schemas') {
+            steps {
+                sh 'fake_data_dsl lint schemas/ --strict --verbose'
+            }
+        }
+        
+        stage('Schema Info') {
+            steps {
+                sh 'fake_data_dsl info schemas/ --verbose > schema-report.txt'
+                archiveArtifacts artifacts: 'schema-report.txt'
+            }
+        }
+        
+        stage('Preview') {
+            steps {
+                sh '''
+                    for schema in User Order Product; do
+                        fake_data_dsl preview $schema --dir schemas/ --pretty || true
+                    done
+                '''
+            }
+        }
+    }
+    
+    post {
+        failure {
+            echo 'Schema validation failed!'
+        }
+    }
+}
+```
+
+---
+
+## Pre-commit Hooks
+
+### Using pre-commit framework
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: fake-data-dsl-lint
+        name: FakeDataDSL Lint
+        entry: fake_data_dsl lint --strict
+        language: ruby
+        files: \.dsl$
+        types: [file]
+        additional_dependencies: ['fake_data_dsl']
+```
+
+### Using Git hooks directly
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Get list of staged .dsl files
+DSL_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.dsl$')
+
+if [ -n "$DSL_FILES" ]; then
+    echo "Validating DSL schemas..."
+    
+    # Create temp directory for staged versions
+    TMPDIR=$(mktemp -d)
+    trap "rm -rf $TMPDIR" EXIT
+    
+    # Copy staged files
+    for file in $DSL_FILES; do
+        mkdir -p "$TMPDIR/$(dirname $file)"
+        git show ":$file" > "$TMPDIR/$file"
+    done
+    
+    # Run lint
+    if ! fake_data_dsl lint "$TMPDIR" --strict; then
+        echo "❌ Schema validation failed. Please fix errors before committing."
+        exit 1
+    fi
+    
+    echo "✅ Schema validation passed"
+fi
+```
+
+### Installation script
+
+```bash
+#!/bin/bash
+# scripts/setup-hooks.sh
+
+# Install pre-commit hook
+cat > .git/hooks/pre-commit << 'EOF'
+#!/bin/bash
+DSL_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.dsl$')
+if [ -n "$DSL_FILES" ]; then
+    echo "Validating DSL schemas..."
+    fake_data_dsl lint schemas/ --strict || exit 1
+    echo "✅ Schema validation passed"
+fi
+EOF
+
+chmod +x .git/hooks/pre-commit
+echo "Pre-commit hook installed!"
+```
+
+---
+
+## Exit Codes
+
+### Detailed Exit Code Reference
+
+| Code | Status | Description | Action |
+|------|--------|-------------|--------|
+| `0` | ✅ Success | All schemas valid, no warnings | Continue pipeline |
+| `1` | ⚠️ Warning | Schemas valid but have warnings | Pass (non-strict), Fail (strict) |
+| `2` | ❌ Error | Schema parse errors | Fail pipeline |
+| `3` | ❌ Error | File not found | Check paths |
+| `4` | ❌ Error | Invalid arguments | Check command syntax |
+
+### Handling in Scripts
+
+```bash
+#!/bin/bash
+set -e
+
+fake_data_dsl lint schemas/ --strict
+EXIT_CODE=$?
+
+case $EXIT_CODE in
+    0) echo "✅ All schemas valid" ;;
+    1) echo "⚠️ Warnings found" ;;
+    2) echo "❌ Errors found"; exit 1 ;;
+    *) echo "❌ Unknown error"; exit 1 ;;
+esac
+```
+
+---
+
+## Best Practices
+
+### 1. Always Use `--strict` in CI
+
+```bash
+# ❌ Don't do this - warnings may slip through
+fake_data_dsl lint schemas/
+
+# ✅ Do this - treat warnings as errors
+fake_data_dsl lint schemas/ --strict
+```
+
+### 2. Pin FakeDataDSL Version
+
+```ruby
+# Gemfile
+gem 'fake_data_dsl', '~> 0.1.0'
+```
+
+```yaml
+# CI
+- run: gem install fake_data_dsl -v '~> 0.1.0'
+```
+
+### 3. Generate Test Data in CI
+
+```yaml
+# Verify schemas can generate data
+- name: Test Generation
+  run: |
+    for schema in $(fake_data_dsl info schemas/ --list); do
+      fake_data_dsl generate $schema --dir schemas/ --count 10 --seed 12345 > /dev/null
+    done
+```
+
+### 4. Archive Schema Documentation
+
+```yaml
+# GitHub Actions
+- name: Generate Schema Docs
+  run: |
+    fake_data_dsl info schemas/ --verbose > schema-docs.txt
+    fake_data_dsl export --all --dir schemas/ --format json-schema --out-dir ./json-schemas/
+  
+- uses: actions/upload-artifact@v4
+  with:
+    name: schema-documentation
+    path: |
+      schema-docs.txt
+      json-schemas/
+```
+
+### 5. Fail Fast on Schema Changes
+
+```yaml
+# Only run expensive tests if schemas are valid
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: gem install fake_data_dsl
+      - run: fake_data_dsl lint schemas/ --strict
+  
+  integration-tests:
+    needs: validate  # Only run if validation passes
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: bundle exec rspec
+```
+
+### 6. Use Seed for Reproducibility
+
+```bash
+# Same seed = same output across runs
+fake_data_dsl generate User --dir schemas/ --count 100 --seed 12345
+```
+
+### 7. Monitor Schema Complexity
+
+```yaml
+- name: Check Schema Complexity
+  run: |
+    # Fail if any schema has too many fields
+    fake_data_dsl info schemas/ --format json | \
+      jq -e '.schemas | all(.field_count < 50)' || \
+      (echo "Schema has too many fields!" && exit 1)
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `command not found: fake_data_dsl` | Gem not installed | Add `gem install fake_data_dsl` |
+| Exit code 2 on valid schema | Old gem version | Update to latest version |
+| Slow validation | Many schemas | Use parallel jobs |
+| Memory issues | Large schemas | Use streaming mode |
+
+### Debug Mode
+
+```bash
+# Verbose output for debugging
+fake_data_dsl lint schemas/ --strict --verbose 2>&1 | tee lint-output.log
+
+# Check specific schema
+fake_data_dsl validate schemas/problematic.dsl
+```
+
+---
+
+## Next Steps
+
+- [Schema Templates Gallery](../tutorials/template_gallery.md)
+- [CLI Reference](../../tech_example/04_cli_usage.md)
+- [Best Practices](../best_practices.md)