synthra 0.1.0

data/docs/FACTORY_BOT.md

@@ -0,0 +1,271 @@
+# Factory Bot Integration
+
+FakeDataDSL integrates seamlessly with [Factory Bot](https://github.com/thoughtbot/factory_bot) to provide powerful test data generation with the simplicity of Factory Bot's DSL.
+
+## Quick Start
+
+### 1. Define a Factory
+
+```ruby
+# spec/factories.rb or spec/support/fake_data_factories.rb
+require 'fake_data_dsl'
+
+FakeDataDSL.define_factory(:user, schema: "User") do
+  trait(:admin) do
+    role { "admin" }
+  end
+
+  trait(:inactive) do
+    active { false }
+  end
+
+  trait(:with_address) do
+    address { FakeDataDSL.generate("Address") }
+  end
+end
+```
+
+### 2. Use in Tests
+
+```ruby
+# spec/models/user_spec.rb
+RSpec.describe User do
+  it "creates a valid user" do
+    user = create(:user)
+    expect(user).to be_valid
+  end
+
+  it "creates an admin user" do
+    admin = create(:user, :admin)
+    expect(admin.role).to eq("admin")
+  end
+
+  it "accepts field overrides" do
+    user = create(:user, name: "Custom Name", email: "custom@example.com")
+    expect(user.name).to eq("Custom Name")
+  end
+end
+```
+
+## RSpec Helpers
+
+### Setup
+
+```ruby
+# spec/spec_helper.rb
+require 'fake_data_dsl'
+require 'fake_data_dsl/factory_bot_integration'
+
+RSpec.configure do |config|
+  config.include FakeDataDSL::FactoryBotIntegration::RSpec
+end
+```
+
+### Available Helpers
+
+```ruby
+# Build data without creating records
+user_data = fake_data_build(:user)
+user_data = build_fake_data(:user)  # Alias
+
+# With traits
+admin_data = fake_data_build(:user, :admin)
+
+# With overrides
+custom_data = fake_data_build(:user, :admin, name: "Jane Doe")
+```
+
+## Defining Factories
+
+### Basic Factory
+
+```ruby
+FakeDataDSL.define_factory(:user, schema: "User")
+```
+
+### Factory with Traits
+
+```ruby
+FakeDataDSL.define_factory(:user, schema: "User") do
+  trait(:admin) do
+    role { "admin" }
+    permissions { ["read", "write", "delete"] }
+  end
+
+  trait(:guest) do
+    role { "guest" }
+    permissions { ["read"] }
+  end
+
+  trait(:verified) do
+    email_verified { true }
+    phone_verified { true }
+  end
+end
+```
+
+### Combining Traits
+
+```ruby
+# Traits can be combined
+create(:user, :admin, :verified)
+create(:user, :guest, name: "Anonymous")
+```
+
+## Schema Requirements
+
+Your DSL schemas should be loaded before defining factories:
+
+```ruby
+# Load schemas first
+FakeDataDSL.load_schemas("schemas/")
+
+# Then define factories
+FakeDataDSL.define_factory(:user, schema: "User")
+FakeDataDSL.define_factory(:order, schema: "Order")
+```
+
+### Example Schema
+
+```
+# schemas/user.dsl
+User:
+  id: uuid
+  name: name
+  email: email
+  role: enum(user, admin, moderator)
+  active: boolean(true:90%)
+  created_at: timestamp
+```
+
+## Advanced Usage
+
+### Custom Factory Logic
+
+```ruby
+FakeDataDSL.define_factory(:user, schema: "User") do
+  trait(:with_orders) do
+    orders { 
+      3.times.map { FakeDataDSL::FactoryBotIntegration.build(:order) }
+    }
+  end
+end
+```
+
+### Sequence Support
+
+```ruby
+FakeDataDSL.define_factory(:user, schema: "User") do
+  trait(:numbered) do
+    # Use schema's built-in sequence type
+    # or override with custom sequence
+    id { |n| "user_#{n}" }
+  end
+end
+```
+
+### Dependent Attributes
+
+```ruby
+FakeDataDSL.define_factory(:user, schema: "User") do
+  trait(:consistent_name) do
+    first_name { "John" }
+    last_name { "Doe" }
+    email { "john.doe@example.com" }
+  end
+end
+```
+
+## Integration with Factory Bot (Optional)
+
+If Factory Bot is already installed, factories are automatically registered:
+
+```ruby
+# This just works if Factory Bot is available
+FactoryBot.create(:user)
+FactoryBot.create(:user, :admin)
+FactoryBot.build_list(:user, 10)
+```
+
+## Best Practices
+
+### 1. Organize Factories by Domain
+
+```ruby
+# spec/support/factories/users.rb
+FakeDataDSL.define_factory(:user, schema: "User") { ... }
+FakeDataDSL.define_factory(:admin_user, schema: "AdminUser") { ... }
+
+# spec/support/factories/orders.rb
+FakeDataDSL.define_factory(:order, schema: "Order") { ... }
+FakeDataDSL.define_factory(:order_item, schema: "OrderItem") { ... }
+```
+
+### 2. Use Traits for Common Scenarios
+
+```ruby
+FakeDataDSL.define_factory(:user, schema: "User") do
+  # State traits
+  trait(:active) { active { true } }
+  trait(:inactive) { active { false } }
+  
+  # Role traits
+  trait(:admin) { role { "admin" } }
+  trait(:guest) { role { "guest" } }
+  
+  # Feature traits
+  trait(:with_2fa) { two_factor_enabled { true } }
+  trait(:premium) { subscription_tier { "premium" } }
+end
+```
+
+### 3. Keep Factories DRY
+
+```ruby
+# Base user factory
+FakeDataDSL.define_factory(:user, schema: "User")
+
+# Specialized factories inherit behavior
+FakeDataDSL.define_factory(:admin, schema: "AdminUser") do
+  trait(:super_admin) { permissions { ["all"] } }
+end
+```
+
+## Troubleshooting
+
+### Factory Not Found
+
+```ruby
+# Error: Unknown factory: :user
+
+# Solution: Ensure factory is defined before use
+FakeDataDSL.define_factory(:user, schema: "User")
+```
+
+### Schema Not Found
+
+```ruby
+# Error: Unknown schema: User
+
+# Solution: Load schemas before defining factories
+FakeDataDSL.load_schemas("schemas/")
+FakeDataDSL.define_factory(:user, schema: "User")
+```
+
+### Trait Overrides Not Working
+
+```ruby
+# Traits should return hashes or use block syntax
+trait(:admin) do
+  role { "admin" }  # Correct: block syntax
+end
+
+# Not: role: "admin"  # This won't work as expected
+```
+
+## See Also
+
+- [Quick Start Guide](../tech_docs/quick_start.md)
+- [Schema Definition](../tech_docs/dsl/schema_definition.md)
+- [Property-Based Testing](PROPERTY_TESTING.md)
+- [RSpec Integration](../tech_example/07_rspec_integration.rb)

data/docs/GITHUB_ACTION.md

@@ -0,0 +1,420 @@
+# GitHub Action
+
+FakeDataDSL provides a **reusable GitHub Action** for CI/CD pipelines. Validate schemas, generate data, run diff checks, and more directly in your workflows.
+
+## Quick Start
+
+```yaml
+# .github/workflows/schemas.yml
+name: Schema Validation
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: fake-data-dsl/action@v1
+        with:
+          command: validate
+          schema_dir: schemas/
+```
+
+## Available Commands
+
+### validate
+
+Validate all schemas for syntax errors:
+
+```yaml
+- uses: fake-data-dsl/action@v1
+  with:
+    command: validate
+    schema_dir: schemas/
+    strict: true  # Fail on warnings too
+```
+
+### lint
+
+Run linter checks on schemas:
+
+```yaml
+- uses: fake-data-dsl/action@v1
+  with:
+    command: lint
+    schema_dir: schemas/
+    config: .fake_data_dsl.yml
+```
+
+### diff
+
+Check for breaking changes between schema versions:
+
+```yaml
+- uses: fake-data-dsl/action@v1
+  with:
+    command: diff
+    base_ref: ${{ github.base_ref }}
+    head_ref: ${{ github.head_ref }}
+    schema_dir: schemas/
+    breaking_only: true
+```
+
+### generate
+
+Generate sample data for testing:
+
+```yaml
+- uses: fake-data-dsl/action@v1
+  with:
+    command: generate
+    schema: User
+    count: 100
+    output: test_data/users.json
+    seed: 42
+```
+
+### export
+
+Export schemas to other formats:
+
+```yaml
+- uses: fake-data-dsl/action@v1
+  with:
+    command: export
+    schema_dir: schemas/
+    format: openapi
+    output: docs/openapi.yaml
+```
+
+### test
+
+Run schema-related tests:
+
+```yaml
+- uses: fake-data-dsl/action@v1
+  with:
+    command: test
+    schema_dir: schemas/
+    test_dir: spec/schemas/
+```
+
+## Input Parameters
+
+| Input | Description | Default |
+|-------|-------------|---------|
+| `command` | Command to run | `validate` |
+| `schema_dir` | Schema directory | `schemas/` |
+| `schema` | Specific schema name | - |
+| `config` | Config file path | `.fake_data_dsl.yml` |
+| `output` | Output file path | - |
+| `format` | Export format | - |
+| `count` | Number of records | `10` |
+| `seed` | Random seed | - |
+| `mode` | Generation mode | `random` |
+| `strict` | Strict validation | `false` |
+| `breaking_only` | Only report breaking changes | `false` |
+| `base_ref` | Base Git ref for diff | - |
+| `head_ref` | Head Git ref for diff | - |
+| `ruby_version` | Ruby version | `3.2` |
+
+## Output Variables
+
+| Output | Description |
+|--------|-------------|
+| `valid` | Whether schemas are valid |
+| `warnings` | Number of warnings |
+| `errors` | Number of errors |
+| `breaking_changes` | Number of breaking changes |
+| `generated_file` | Path to generated file |
+
+## Examples
+
+### Complete CI Workflow
+
+```yaml
+name: Schema CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - 'schemas/**'
+      - '.github/workflows/schemas.yml'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Validate Schemas
+        uses: fake-data-dsl/action@v1
+        with:
+          command: validate
+          schema_dir: schemas/
+          strict: true
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Lint Schemas
+        uses: fake-data-dsl/action@v1
+        with:
+          command: lint
+          schema_dir: schemas/
+
+  breaking-changes:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - name: Check Breaking Changes
+        id: diff
+        uses: fake-data-dsl/action@v1
+        with:
+          command: diff
+          schema_dir: schemas/
+          base_ref: ${{ github.base_ref }}
+          head_ref: ${{ github.head_ref }}
+          breaking_only: true
+      
+      - name: Comment on PR
+        if: steps.diff.outputs.breaking_changes > 0
+        uses: actions/github-script@v6
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '⚠️ Breaking schema changes detected!'
+            })
+
+  generate-docs:
+    runs-on: ubuntu-latest
+    needs: [validate, lint]
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Generate OpenAPI
+        uses: fake-data-dsl/action@v1
+        with:
+          command: export
+          schema_dir: schemas/
+          format: openapi
+          output: docs/api/openapi.yaml
+      
+      - name: Generate TypeScript Types
+        uses: fake-data-dsl/action@v1
+        with:
+          command: export
+          schema_dir: schemas/
+          format: typescript
+          output: frontend/src/types/schemas.ts
+      
+      - name: Commit Generated Files
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore: regenerate schema exports"
+          file_pattern: "docs/api/* frontend/src/types/*"
+```
+
+### Generate Test Data
+
+```yaml
+name: Generate Test Data
+
+on:
+  workflow_dispatch:
+    inputs:
+      schema:
+        description: 'Schema name'
+        required: true
+      count:
+        description: 'Number of records'
+        default: '1000'
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Generate Data
+        uses: fake-data-dsl/action@v1
+        with:
+          command: generate
+          schema: ${{ inputs.schema }}
+          count: ${{ inputs.count }}
+          output: test_data/${{ inputs.schema }}.json
+          seed: 42
+      
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-data
+          path: test_data/
+```
+
+### Schema Release
+
+```yaml
+name: Schema Release
+
+on:
+  push:
+    tags:
+      - 'schema-v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Validate
+        uses: fake-data-dsl/action@v1
+        with:
+          command: validate
+          schema_dir: schemas/
+          strict: true
+      
+      - name: Export All Formats
+        uses: fake-data-dsl/action@v1
+        with:
+          command: export
+          schema_dir: schemas/
+          format: all
+          output: dist/
+      
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            dist/openapi.yaml
+            dist/schemas.ts
+            dist/schemas.proto
+            dist/schemas.json
+```
+
+## Configuration File
+
+Create `.fake_data_dsl.yml` for action configuration:
+
+```yaml
+# .fake_data_dsl.yml
+schema_dir: schemas/
+strict: true
+
+validation:
+  require_descriptions: true
+  max_depth: 10
+
+lint:
+  rules:
+    - naming_convention
+    - required_fields
+    - type_consistency
+
+diff:
+  breaking_changes:
+    - field_removed
+    - type_changed
+    - required_added
+  
+  warnings:
+    - field_added
+    - optional_to_required
+
+export:
+  openapi:
+    version: "3.1.0"
+    info:
+      title: "My API"
+      version: "1.0.0"
+  
+  typescript:
+    style: interface
+    export_style: named
+```
+
+## Self-Hosted Runner
+
+For private schemas or faster builds:
+
+```yaml
+jobs:
+  validate:
+    runs-on: self-hosted
+    container:
+      image: ruby:3.2
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install FakeDataDSL
+        run: gem install fake_data_dsl
+      
+      - name: Validate
+        run: fake_data_dsl validate schemas/
+```
+
+## Troubleshooting
+
+### Action Not Found
+
+Make sure you're using the correct action reference:
+
+```yaml
+# Correct
+- uses: fake-data-dsl/action@v1
+
+# Or from GitHub Marketplace
+- uses: fake-data-dsl/fake-data-dsl-action@v1
+```
+
+### Schema Validation Errors
+
+Check the action output for details:
+
+```yaml
+- name: Validate
+  id: validate
+  uses: fake-data-dsl/action@v1
+  with:
+    command: validate
+    schema_dir: schemas/
+    
+- name: Show Errors
+  if: failure()
+  run: echo "${{ steps.validate.outputs.errors }}"
+```
+
+### Permission Issues
+
+For actions that write files:
+
+```yaml
+permissions:
+  contents: write  # For committing generated files
+
+jobs:
+  generate:
+    # ...
+```
+
+## See Also
+
+- [CI/CD Integration](best_practices.md#cicd)
+- [Data Contracts](DATA_CONTRACTS.md)
+- [Breaking Changes Diff](DATA_CONTRACTS.md#breaking-changes)
+- [Snapshot Testing](SNAPSHOT_TESTING.md)