synthra 0.1.0

data/tech_docs/integration/rails.md

@@ -0,0 +1,630 @@
+# Rails Integration
+
+Using FakeDataDSL with Ruby on Rails applications.
+
+## Table of Contents
+
+- [Setup](#setup)
+- [Database Seeding](#database-seeding)
+- [Test Environment](#test-environment)
+- [Development Data](#development-data)
+- [API Testing](#api-testing)
+- [Background Jobs](#background-jobs)
+- [Best Practices](#best-practices)
+
+---
+
+## Setup
+
+### Installation
+
+Add to your `Gemfile`:
+
+```ruby
+# Gemfile
+
+# For development and test only
+group :development, :test do
+  gem 'fake_data_dsl'
+end
+
+# Or if you want it in production (for seeding)
+gem 'fake_data_dsl'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### Directory Structure
+
+Create a schemas directory:
+
+```
+app/
+config/
+db/
+  schemas/               # FakeDataDSL schemas
+    user.dsl
+    post.dsl
+    comment.dsl
+  seeds.rb
+lib/
+spec/
+  schemas/               # Test-specific schemas
+    api_response.dsl
+```
+
+### Initializer
+
+Create `config/initializers/fake_data_dsl.rb`:
+
+```ruby
+# config/initializers/fake_data_dsl.rb
+
+if defined?(FakeDataDSL)
+  FakeDataDSL.configure do |config|
+    # Default generation mode
+    config.default_mode = :random
+    
+    # Resource limits
+    config.limits.max_array_size = 100
+    config.limits.max_recursion = 5
+  end
+  
+  # Register custom types for your domain
+  FakeDataDSL.register_type(:user_role) do |rng, _context, _args, _mode|
+    %w[user admin moderator].sample(random: rng.random)
+  end
+  
+  # Register computed field functions
+  FakeDataDSL.register_function(:full_name) do |context|
+    "#{context['first_name']} #{context['last_name']}"
+  end
+end
+```
+
+---
+
+## Database Seeding
+
+### Basic Seeds
+
+Create `db/seeds.rb`:
+
+```ruby
+# db/seeds.rb
+
+require 'fake_data_dsl'
+
+# Load all schemas
+registry = FakeDataDSL::Registry.new
+registry.load_dir(Rails.root.join('db/schemas'))
+
+# Seed configuration
+SEED = ENV.fetch('SEED', 12345).to_i
+puts "Using seed: #{SEED}"
+
+# Clear existing data (optional)
+if Rails.env.development?
+  puts "Clearing existing data..."
+  [Comment, Post, User].each(&:delete_all)
+end
+
+# Seed users
+puts "Seeding users..."
+user_schema = registry.schema('User')
+users_data = user_schema.generate_many(100, seed: SEED)
+
+users = users_data.map do |data|
+  User.create!(
+    email: data['email'],
+    name: data['name'],
+    role: data['role'],
+    created_at: data['created_at']
+  )
+end
+puts "Created #{users.count} users"
+
+# Seed posts
+puts "Seeding posts..."
+post_schema = registry.schema('Post')
+posts = []
+
+users.each do |user|
+  post_count = rand(0..5)
+  post_data = post_schema.generate_many(post_count)
+  
+  post_data.each do |data|
+    posts << Post.create!(
+      user: user,
+      title: data['title'],
+      body: data['body'],
+      published: data['published'],
+      created_at: data['created_at']
+    )
+  end
+end
+puts "Created #{posts.count} posts"
+
+# Seed comments
+puts "Seeding comments..."
+comment_schema = registry.schema('Comment')
+comment_count = 0
+
+posts.sample(posts.count / 2).each do |post|
+  comments_data = comment_schema.generate_many(rand(0..10))
+  
+  comments_data.each do |data|
+    Comment.create!(
+      post: post,
+      user: users.sample,
+      body: data['body'],
+      created_at: data['created_at']
+    )
+    comment_count += 1
+  end
+end
+puts "Created #{comment_count} comments"
+
+puts "Seeding complete!"
+```
+
+### Schema Files
+
+Create `db/schemas/user.dsl`:
+
+```dsl
+User:
+  email: email(unique: true)
+  name: name
+  role: enum(user:80%, admin:10%, moderator:10%)
+  avatar_url?: url
+  bio?: text(50..500)
+  created_at: past_date(2y)
+```
+
+Create `db/schemas/post.dsl`:
+
+```dsl
+Post:
+  title: text(20..100)
+  body: text(200..2000)
+  slug: text(10..50)
+  published: boolean(true:70%)
+  view_count: number(0..10000)
+  created_at: past_date(1y)
+```
+
+### Running Seeds
+
+```bash
+# Basic seeding
+rails db:seed
+
+# With specific seed for reproducibility
+SEED=42 rails db:seed
+
+# Reset and reseed
+rails db:reset  # Runs drop, create, migrate, seed
+```
+
+### Rake Tasks
+
+Create `lib/tasks/fake_data.rake`:
+
+```ruby
+# lib/tasks/fake_data.rake
+
+namespace :fake_data do
+  desc "Generate fake users"
+  task :users, [:count] => :environment do |_t, args|
+    count = (args[:count] || 10).to_i
+    
+    registry = FakeDataDSL::Registry.new
+    registry.load_file(Rails.root.join('db/schemas/user.dsl'))
+    
+    schema = registry.schema('User')
+    
+    puts "Generating #{count} users..."
+    schema.generate_stream(count: count).each_with_index do |data, i|
+      User.create!(
+        email: data['email'],
+        name: data['name'],
+        role: data['role']
+      )
+      print '.' if (i + 1) % 100 == 0
+    end
+    puts "\nDone!"
+  end
+  
+  desc "Clear all fake data"
+  task clear: :environment do
+    puts "Clearing data..."
+    [Comment, Post, User].each(&:delete_all)
+    puts "Done!"
+  end
+  
+  desc "Validate all schemas"
+  task validate: :environment do
+    Dir[Rails.root.join('db/schemas/*.dsl')].each do |file|
+      print "Validating #{File.basename(file)}... "
+      begin
+        FakeDataDSL.load(file)
+        puts "✓"
+      rescue StandardError => e
+        puts "✗ #{e.message}"
+      end
+    end
+  end
+end
+```
+
+Usage:
+
+```bash
+rails fake_data:users[100]
+rails fake_data:clear
+rails fake_data:validate
+```
+
+---
+
+## Test Environment
+
+### RSpec Setup
+
+Create `spec/support/fake_data.rb`:
+
+```ruby
+# spec/support/fake_data.rb
+
+require 'fake_data_dsl'
+
+module FakeDataSupport
+  extend ActiveSupport::Concern
+  
+  included do
+    let(:fake_registry) do
+      FakeDataDSL::Registry.new.tap do |r|
+        r.load_dir(Rails.root.join('spec/schemas'))
+      end
+    end
+  end
+  
+  def fake(schema_name, **options)
+    fake_registry.schema(schema_name.to_s.camelize).generate(**options)
+  end
+  
+  def fake_many(schema_name, count, **options)
+    fake_registry.schema(schema_name.to_s.camelize).generate_many(count, **options)
+  end
+  
+  def build_fake(model_class, **overrides)
+    schema_name = model_class.name
+    data = fake(schema_name)
+    model_class.new(data.merge(overrides.stringify_keys))
+  end
+  
+  def create_fake(model_class, **overrides)
+    build_fake(model_class, **overrides).tap(&:save!)
+  end
+end
+
+RSpec.configure do |config|
+  config.include FakeDataSupport
+end
+```
+
+### Usage in Specs
+
+```ruby
+# spec/models/user_spec.rb
+
+RSpec.describe User, type: :model do
+  describe "validations" do
+    let(:user_data) { fake(:user) }
+    
+    it "is valid with fake data" do
+      user = User.new(user_data)
+      expect(user).to be_valid
+    end
+    
+    it "handles edge cases" do
+      user = User.new(fake(:user, mode: :edge))
+      expect { user.valid? }.not_to raise_error
+    end
+  end
+  
+  describe "associations" do
+    let(:user) { create_fake(User) }
+    
+    it "has many posts" do
+      3.times { create_fake(Post, user: user) }
+      expect(user.posts.count).to eq(3)
+    end
+  end
+end
+```
+
+### Request Specs
+
+```ruby
+# spec/requests/users_spec.rb
+
+RSpec.describe "Users API", type: :request do
+  describe "POST /api/users" do
+    let(:user_params) do
+      fake(:user).slice('email', 'name').merge('password' => 'password123')
+    end
+    
+    it "creates a user" do
+      post '/api/users', params: { user: user_params }
+      
+      expect(response).to have_http_status(:created)
+      expect(json_response['email']).to eq(user_params['email'])
+    end
+    
+    context "with invalid data" do
+      let(:user_params) { fake(:user, mode: :invalid) }
+      
+      it "returns validation errors" do
+        post '/api/users', params: { user: user_params }
+        
+        expect(response).to have_http_status(:unprocessable_entity)
+      end
+    end
+  end
+end
+```
+
+---
+
+## Development Data
+
+### Development Seeds
+
+Create `db/seeds/development.rb`:
+
+```ruby
+# db/seeds/development.rb
+
+return unless Rails.env.development?
+
+require 'fake_data_dsl'
+
+registry = FakeDataDSL::Registry.new
+registry.load_dir(Rails.root.join('db/schemas'))
+
+# Create admin user
+admin_data = registry.schema('User').generate
+User.find_or_create_by!(email: 'admin@example.com') do |user|
+  user.name = 'Admin User'
+  user.role = 'admin'
+  user.password = 'password123'
+end
+
+# Create sample data
+100.times do |i|
+  user_data = registry.schema('User').generate(seed: i)
+  user = User.create!(user_data.merge('password' => 'password123'))
+  
+  rand(0..5).times do
+    post_data = registry.schema('Post').generate
+    user.posts.create!(post_data)
+  end
+  
+  print '.' if (i + 1) % 10 == 0
+end
+
+puts "\nDevelopment data created!"
+```
+
+### Console Helpers
+
+Add to `.irbrc` or create `config/initializers/console_helpers.rb`:
+
+```ruby
+# config/initializers/console_helpers.rb
+
+if defined?(Rails::Console)
+  module ConsoleHelpers
+    def fake_registry
+      @fake_registry ||= FakeDataDSL::Registry.new.tap do |r|
+        r.load_dir(Rails.root.join('db/schemas'))
+      end
+    end
+    
+    def fake(schema_name, **options)
+      fake_registry.schema(schema_name.to_s.camelize).generate(**options)
+    end
+    
+    def create_fake_user(**overrides)
+      User.create!(fake(:user).merge(overrides.stringify_keys))
+    end
+    
+    def create_fake_post(user: nil, **overrides)
+      user ||= User.first || create_fake_user
+      user.posts.create!(fake(:post).merge(overrides.stringify_keys))
+    end
+  end
+  
+  Rails.application.console do
+    include ConsoleHelpers
+    puts "FakeDataDSL helpers loaded: fake(:schema_name), create_fake_user, create_fake_post"
+  end
+end
+```
+
+Usage in console:
+
+```ruby
+# rails console
+fake(:user)                        # Generate user data
+create_fake_user                   # Create and save user
+create_fake_user(role: 'admin')    # With overrides
+create_fake_post                   # Create post for first user
+```
+
+---
+
+## API Testing
+
+### API Response Schemas
+
+Create `spec/schemas/api_response.dsl`:
+
+```dsl
+APIResponse:
+  @latency 50..200ms
+  @failure 2%
+  
+  success: boolean(true:95%)
+  data: object
+  meta: ResponseMeta
+
+ResponseMeta:
+  request_id: uuid
+  timestamp: now
+  version: enum(v1, v2)
+```
+
+### Controller Specs
+
+```ruby
+# spec/controllers/api/users_controller_spec.rb
+
+RSpec.describe Api::UsersController, type: :controller do
+  describe "GET #index" do
+    before do
+      10.times { create_fake(User) }
+    end
+    
+    it "returns users" do
+      get :index
+      
+      expect(response).to be_successful
+      expect(json_response['users'].length).to eq(10)
+    end
+  end
+  
+  describe "POST #create" do
+    let(:params) { { user: fake(:user).slice('email', 'name') } }
+    
+    it "creates user" do
+      expect {
+        post :create, params: params
+      }.to change(User, :count).by(1)
+    end
+  end
+end
+```
+
+---
+
+## Background Jobs
+
+### Testing with Fake Data
+
+```ruby
+# spec/jobs/send_newsletter_job_spec.rb
+
+RSpec.describe SendNewsletterJob, type: :job do
+  let(:users) { 10.times.map { create_fake(User) } }
+  
+  it "sends to all users" do
+    expect {
+      described_class.perform_now(users.map(&:id))
+    }.to change { ActionMailer::Base.deliveries.count }.by(10)
+  end
+end
+```
+
+### Generating Test Data for Jobs
+
+```ruby
+# spec/jobs/import_job_spec.rb
+
+RSpec.describe ImportJob, type: :job do
+  let(:import_data) do
+    fake_many(:import_record, 1000).map(&:to_json).join("\n")
+  end
+  
+  it "imports all records" do
+    expect {
+      described_class.perform_now(import_data)
+    }.to change(ImportedRecord, :count).by(1000)
+  end
+end
+```
+
+---
+
+## Best Practices
+
+### 1. Separate Schemas by Purpose
+
+```
+db/schemas/          # Production seeding
+spec/schemas/        # Testing only
+lib/schemas/         # Shared schemas
+```
+
+### 2. Use Deterministic Seeds
+
+```ruby
+# In seeds.rb
+SEED = ENV.fetch('SEED', Rails.env.hash).to_i
+
+# Always reproducible per environment
+users = schema.generate_many(100, seed: SEED)
+```
+
+### 3. Match Your Models
+
+```dsl
+# db/schemas/user.dsl - matches User model
+User:
+  email: email(unique: true)        # validates :email, uniqueness: true
+  name: name                        # validates :name, presence: true
+  role: enum(user, admin, moderator) # enum role: [:user, :admin, :moderator]
+  created_at: past_date(2y)
+```
+
+### 4. Use Transactions in Tests
+
+```ruby
+RSpec.configure do |config|
+  config.use_transactional_fixtures = true
+end
+```
+
+### 5. Avoid N+1 in Seeds
+
+```ruby
+# Bad - N+1 queries
+100.times do
+  user = User.create!(fake(:user))
+  5.times { Post.create!(fake(:post).merge(user_id: user.id)) }
+end
+
+# Good - Batch insert
+users_data = fake_many(:user, 100)
+users = User.insert_all!(users_data, returning: [:id])
+
+posts_data = users.flat_map do |user|
+  5.times.map { fake(:post).merge(user_id: user['id']) }
+end
+Post.insert_all!(posts_data)
+```
+
+---
+
+## Next Steps
+
+- [RSpec Integration](rspec.md) - RSpec testing patterns
+- [Factory Bot Comparison](factory_bot.md) - Migration guide
+- [Database Seeding Example](../../tech_example/05_database_seeding.rb) - Code examples
+