synthra 0.1.0

data/tech_example/04_cli_usage.md

@@ -0,0 +1,429 @@
+# CLI Usage Examples
+
+Complete guide to using the FakeDataDSL command-line interface.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Basic Commands](#basic-commands)
+- [Generate Command](#generate-command)
+- [Validate Command](#validate-command)
+- [Advanced Usage](#advanced-usage)
+- [Shell Integration](#shell-integration)
+
+---
+
+## Installation
+
+After installing the gem, the CLI is available:
+
+```bash
+# Via gem
+gem install fake_data_dsl
+fake_data_dsl --version
+
+# Via bundler
+bundle add fake_data_dsl
+bundle exec fake_data_dsl --version
+```
+
+---
+
+## Basic Commands
+
+### Help
+
+```bash
+# Show all commands
+fake_data_dsl --help
+
+# Show help for specific command
+fake_data_dsl generate --help
+fake_data_dsl validate --help
+```
+
+### Version
+
+```bash
+fake_data_dsl --version
+# => fake_data_dsl 1.0.0
+```
+
+---
+
+## Generate Command
+
+### Basic Generation
+
+```bash
+# Generate one record
+fake_data_dsl generate User --dir schemas
+
+# Generate multiple records
+fake_data_dsl generate User --dir schemas --count 10
+
+# Short flags
+fake_data_dsl generate User -d schemas -c 10
+```
+
+### Output Formats
+
+```bash
+# JSON array (default)
+fake_data_dsl generate User -d schemas -c 3
+# [{"id":"...","name":"John"},{"id":"...","name":"Jane"}]
+
+# Pretty printed JSON
+fake_data_dsl generate User -d schemas -c 3 --pretty
+# [
+#   {
+#     "id": "...",
+#     "name": "John"
+#   },
+#   ...
+# ]
+
+# NDJSON (newline-delimited JSON)
+fake_data_dsl generate User -d schemas -c 3 --ndjson
+# {"id":"...","name":"John"}
+# {"id":"...","name":"Jane"}
+# {"id":"...","name":"Bob"}
+```
+
+### Generation Modes
+
+```bash
+# Random mode (default) - realistic data
+fake_data_dsl generate User -d schemas --mode random
+
+# Edge mode - boundary values
+fake_data_dsl generate User -d schemas --mode edge
+
+# Invalid mode - invalid data for testing
+fake_data_dsl generate User -d schemas --mode invalid
+
+# Mixed mode - combination
+fake_data_dsl generate User -d schemas --mode mixed
+```
+
+### Deterministic Output
+
+```bash
+# Use seed for reproducible output
+fake_data_dsl generate User -d schemas --seed 12345
+
+# Same seed = same output
+fake_data_dsl generate User -d schemas -s 12345
+fake_data_dsl generate User -d schemas -s 12345
+# Both produce identical output
+```
+
+### Output to File
+
+```bash
+# Redirect to JSON file
+fake_data_dsl generate User -d schemas -c 1000 > users.json
+
+# NDJSON file
+fake_data_dsl generate User -d schemas -c 1000 --ndjson > users.ndjson
+
+# Pretty formatted file
+fake_data_dsl generate User -d schemas -c 100 --pretty > users_formatted.json
+```
+
+### Generate from Stdin
+
+```bash
+# Pipe schema directly
+echo 'User:
+  id: uuid
+  name: name' | fake_data_dsl generate User --stdin
+
+# Here document
+fake_data_dsl generate User --stdin <<EOF
+User:
+  id: uuid
+  name: name
+  email: email
+EOF
+```
+
+---
+
+## Validate Command
+
+### Basic Validation
+
+```bash
+# Validate single file
+fake_data_dsl validate schemas/user.dsl
+# ✓ schemas/user.dsl is valid
+
+# Validate multiple files
+fake_data_dsl validate schemas/*.dsl
+
+# Validate directory
+fake_data_dsl validate schemas/
+```
+
+### Verbose Output
+
+```bash
+fake_data_dsl validate schemas/user.dsl --verbose
+# Validating schemas/user.dsl...
+# Found schema: User
+#   - id: uuid
+#   - name: name
+#   - email: email
+# ✓ schemas/user.dsl is valid
+```
+
+### Error Output
+
+```bash
+# Invalid schema
+fake_data_dsl validate invalid.dsl
+# ✗ invalid.dsl has errors:
+#   Line 3, column 5: Unknown type 'invald_type'
+#   Line 5, column 1: Expected field definition, got EOF
+```
+
+---
+
+## Advanced Usage
+
+### Multiple Schemas
+
+```bash
+# Generate from file with multiple schemas
+fake_data_dsl generate Order -d schemas
+fake_data_dsl generate User -d schemas
+
+# Generate different counts for each
+fake_data_dsl generate User -d schemas -c 100 > users.json
+fake_data_dsl generate Order -d schemas -c 500 > orders.json
+```
+
+### Large Batch Generation
+
+```bash
+# Generate large dataset (streaming)
+fake_data_dsl generate User -d schemas -c 1000000 --ndjson > large_dataset.ndjson
+
+# Monitor progress
+fake_data_dsl generate User -d schemas -c 1000000 --ndjson | pv -l > large_dataset.ndjson
+```
+
+### Piping to Other Commands
+
+```bash
+# Pipe to jq for processing
+fake_data_dsl generate User -d schemas -c 10 | jq '.[].name'
+
+# Pipe to database import
+fake_data_dsl generate User -d schemas -c 1000 --ndjson | \
+  mongoimport --db mydb --collection users
+
+# Pipe to HTTP endpoint
+fake_data_dsl generate User -d schemas | \
+  curl -X POST -H "Content-Type: application/json" -d @- http://api/users
+
+# Count records
+fake_data_dsl generate User -d schemas -c 100 | jq length
+```
+
+### Environment Variables
+
+```bash
+# Set default directory
+export FAKE_DATA_DSL_DIR=./schemas
+fake_data_dsl generate User -c 10
+
+# Set default seed for reproducibility
+export FAKE_DATA_DSL_SEED=12345
+fake_data_dsl generate User -d schemas
+```
+
+---
+
+## Shell Integration
+
+### Bash Alias
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+alias fdd="fake_data_dsl"
+alias fddg="fake_data_dsl generate"
+alias fddv="fake_data_dsl validate"
+
+# Usage
+fddg User -d schemas -c 10
+fddv schemas/
+```
+
+### Bash Function
+
+```bash
+# Generate and copy to clipboard (macOS)
+fdd_copy() {
+  fake_data_dsl generate "$1" -d schemas | pbcopy
+  echo "Generated and copied to clipboard"
+}
+
+# Generate and save with timestamp
+fdd_save() {
+  local schema=$1
+  local count=${2:-1}
+  local filename="${schema,,}_$(date +%Y%m%d_%H%M%S).json"
+  fake_data_dsl generate "$schema" -d schemas -c "$count" --pretty > "$filename"
+  echo "Saved to $filename"
+}
+```
+
+### Fish Shell
+
+```fish
+# ~/.config/fish/functions/fdd.fish
+function fdd
+  fake_data_dsl $argv
+end
+
+function fddg
+  fake_data_dsl generate $argv
+end
+```
+
+### Completion Scripts
+
+```bash
+# Generate completion script (if supported)
+fake_data_dsl completion bash > ~/.fake_data_dsl_completion
+source ~/.fake_data_dsl_completion
+
+# Or add to shell config
+echo 'source ~/.fake_data_dsl_completion' >> ~/.bashrc
+```
+
+---
+
+## Examples
+
+### Database Seeding Script
+
+```bash
+#!/bin/bash
+# seed_database.sh
+
+SCHEMA_DIR="./schemas"
+SEED=12345
+
+echo "Seeding database..."
+
+# Generate users
+echo "Generating users..."
+fake_data_dsl generate User -d $SCHEMA_DIR -c 100 -s $SEED --ndjson | \
+  psql -c "COPY users FROM STDIN WITH (FORMAT json)"
+
+# Generate products
+echo "Generating products..."
+fake_data_dsl generate Product -d $SCHEMA_DIR -c 500 -s $SEED --ndjson | \
+  psql -c "COPY products FROM STDIN WITH (FORMAT json)"
+
+# Generate orders
+echo "Generating orders..."
+fake_data_dsl generate Order -d $SCHEMA_DIR -c 1000 -s $SEED --ndjson | \
+  psql -c "COPY orders FROM STDIN WITH (FORMAT json)"
+
+echo "Done!"
+```
+
+### API Testing Script
+
+```bash
+#!/bin/bash
+# test_api.sh
+
+API_URL="http://localhost:3000/api"
+SCHEMA_DIR="./schemas"
+
+echo "Testing API endpoints..."
+
+# Test user creation
+echo "Testing POST /users..."
+fake_data_dsl generate User -d $SCHEMA_DIR | \
+  curl -s -X POST -H "Content-Type: application/json" \
+       -d @- "$API_URL/users" | jq
+
+# Test batch user creation
+echo "Testing POST /users/batch..."
+fake_data_dsl generate User -d $SCHEMA_DIR -c 10 | \
+  curl -s -X POST -H "Content-Type: application/json" \
+       -d @- "$API_URL/users/batch" | jq
+
+# Test with invalid data
+echo "Testing validation with invalid data..."
+fake_data_dsl generate User -d $SCHEMA_DIR --mode invalid | \
+  curl -s -X POST -H "Content-Type: application/json" \
+       -d @- "$API_URL/users" | jq
+```
+
+### Load Testing with wrk
+
+```bash
+#!/bin/bash
+# Generate test data file
+fake_data_dsl generate User -d schemas -c 1000 --ndjson > test_data.ndjson
+
+# Create Lua script for wrk
+cat > wrk_test.lua <<'EOF'
+-- Load test data
+local data = {}
+for line in io.lines("test_data.ndjson") do
+  table.insert(data, line)
+end
+local index = 1
+
+request = function()
+  local body = data[index]
+  index = (index % #data) + 1
+  return wrk.format("POST", "/api/users", {
+    ["Content-Type"] = "application/json"
+  }, body)
+end
+EOF
+
+# Run load test
+wrk -t4 -c100 -d30s -s wrk_test.lua http://localhost:3000
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+```bash
+# Schema not found
+fake_data_dsl generate User -d wrong_dir
+# Error: No schema 'User' found in wrong_dir
+
+# Fix: Check directory path
+fake_data_dsl generate User -d ./schemas
+
+# Invalid schema syntax
+fake_data_dsl validate bad.dsl
+# Error: Syntax error at line 3
+
+# Fix: Check schema file for typos
+```
+
+### Debug Mode
+
+```bash
+# Verbose output
+fake_data_dsl generate User -d schemas --verbose
+
+# Show parsed schema
+fake_data_dsl validate schemas/user.dsl --verbose
+```
+

data/tech_example/05_database_seeding.rb

@@ -0,0 +1,283 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# ============================================================================
+# FakeDataDSL - Database Seeding Examples
+# ============================================================================
+# This file demonstrates how to use FakeDataDSL for seeding databases.
+# Run with: cd fake_data_dsl && ruby tech_example/05_database_seeding.rb
+# ============================================================================
+
+# Load the local gem
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'fake_data_dsl'
+require 'json'
+
+puts "=" * 70
+puts "FakeDataDSL Database Seeding Examples"
+puts "=" * 70
+puts
+
+# ============================================================================
+# Example 1: Simple User Seeding
+# ============================================================================
+puts "1. SIMPLE USER SEEDING"
+puts "-" * 40
+
+user_schema = FakeDataDSL.parse(<<~DSL)
+  User:
+    id: id_sequence
+    uuid: uuid(unique: true)
+    email: email(unique: true)
+    name: name
+    encrypted_password: text(60)
+    created_at: past_date(2y)
+    updated_at: past_date(30d)
+DSL
+
+puts "Generated Users for DB seeding:"
+users = user_schema.generate_many(5)
+users.each do |user|
+  puts "  INSERT INTO users (id, uuid, email, name, ...) VALUES "
+  puts "    (#{user['id']}, '#{user['uuid']}', '#{user['email']}', '#{user['name']}', ...)"
+end
+puts
+
+# ============================================================================
+# Example 2: Related Tables (Foreign Keys)
+# ============================================================================
+puts "2. RELATED TABLES WITH FOREIGN KEYS"
+puts "-" * 40
+
+# Simulate a registry with multiple schemas
+registry = FakeDataDSL::Registry.new
+
+# Define schemas as strings for demonstration
+registry.load_string(<<~DSL)
+  User:
+    id: id_sequence(start: 1)
+    uuid: uuid(unique: true)
+    email: email(unique: true)
+    name: name
+    created_at: past_date(2y)
+
+  Post:
+    id: id_sequence(start: 1)
+    uuid: uuid(unique: true)
+    title: text(20..100)
+    body: text(200..1000)
+    published: boolean(true:70%)
+    created_at: past_date(1y)
+
+  Comment:
+    id: id_sequence(start: 1)
+    body: text(10..200)
+    created_at: past_date(30d)
+DSL
+
+# Generate users
+users = registry.schema('User').generate_many(3)
+puts "Users:"
+users.each { |u| puts "  #{u['id']}: #{u['name']} (#{u['email']})" }
+puts
+
+# Generate posts linked to users
+posts = []
+users.each do |user|
+  num_posts = rand(1..3)
+  num_posts.times do
+    post = registry.schema('Post').generate
+    post['user_id'] = user['id']  # Add foreign key
+    posts << post
+  end
+end
+
+puts "Posts (with user_id foreign key):"
+posts.each { |p| puts "  Post #{p['id']}: user_id=#{p['user_id']}, '#{p['title'][0..30]}...'" }
+puts
+
+# Generate comments linked to posts and users
+comments = []
+posts.each do |post|
+  num_comments = rand(0..5)
+  num_comments.times do
+    comment = registry.schema('Comment').generate
+    comment['post_id'] = post['id']
+    comment['user_id'] = users.sample['id']  # Random user
+    comments << comment
+  end
+end
+
+puts "Comments (with foreign keys):"
+comments.first(5).each do |c|
+  puts "  Comment #{c['id']}: post_id=#{c['post_id']}, user_id=#{c['user_id']}"
+end
+puts "  ... (#{comments.length} total comments)"
+puts
+
+# ============================================================================
+# Example 3: Batch Insert with Streaming
+# ============================================================================
+puts "3. BATCH INSERT WITH STREAMING"
+puts "-" * 40
+
+large_schema = FakeDataDSL.parse(<<~DSL)
+  LogEntry:
+    id: id_sequence
+    level: enum(debug:50%, info:30%, warn:15%, error:5%)
+    message: text(50..200)
+    timestamp: past_date(30d)
+    source: enum(web, api, worker, scheduler)
+DSL
+
+puts "Streaming 1000 log entries in batches of 100:"
+batch_size = 100
+batch = []
+count = 0
+
+large_schema.generate_stream(count: 1000).each do |entry|
+  batch << entry
+  count += 1
+  
+  if batch.size >= batch_size
+    puts "  Inserting batch #{count / batch_size} (#{batch.size} records)..."
+    # In real code: Model.insert_all(batch)
+    batch = []
+  end
+end
+
+# Insert remaining
+if batch.any?
+  puts "  Inserting final batch (#{batch.size} records)..."
+end
+puts "  Total: #{count} records inserted"
+puts
+
+# ============================================================================
+# Example 4: E-commerce Database Seed
+# ============================================================================
+puts "4. E-COMMERCE DATABASE SEED"
+puts "-" * 40
+
+ecommerce_registry = FakeDataDSL::Registry.new
+ecommerce_registry.load_string(<<~DSL)
+  Category:
+    id: id_sequence
+    name: enum(Electronics, Clothing, Home, Sports, Books, Toys)
+    slug: text(5..20)
+    
+  Product:
+    id: id_sequence
+    uuid: uuid(unique: true)
+    name: text(10..50)
+    description: text(50..300)
+    price_cents: number(100..100000)
+    currency: currency_code
+    in_stock: boolean(true:85%)
+    created_at: past_date(1y)
+    
+  Customer:
+    id: id_sequence
+    uuid: uuid(unique: true)
+    email: email(unique: true)
+    name: name
+    loyalty_tier: enum(bronze:60%, silver:25%, gold:10%, platinum:5%)
+    created_at: past_date(2y)
+    
+  Order:
+    id: id_sequence
+    uuid: uuid(unique: true)
+    status: enum(pending:20%, processing:10%, shipped:40%, delivered:30%)
+    total_cents: number(1000..50000)
+    created_at: past_date(60d)
+DSL
+
+# Generate seed data
+categories = ecommerce_registry.schema('Category').generate_many(6)
+products = []
+50.times do
+  product = ecommerce_registry.schema('Product').generate
+  product['category_id'] = categories.sample['id']
+  products << product
+end
+customers = ecommerce_registry.schema('Customer').generate_many(20)
+orders = []
+100.times do
+  order = ecommerce_registry.schema('Order').generate
+  order['customer_id'] = customers.sample['id']
+  orders << order
+end
+
+puts "E-commerce seed summary:"
+puts "  Categories: #{categories.length}"
+puts "  Products: #{products.length}"
+puts "  Customers: #{customers.length}"
+puts "  Orders: #{orders.length}"
+puts
+puts "Sample data:"
+puts "  Category: #{categories.first.inspect}"
+puts "  Product: #{products.first['name']} - $#{products.first['price_cents'] / 100.0}"
+puts "  Customer: #{customers.first['name']} (#{customers.first['loyalty_tier']})"
+puts "  Order: ##{orders.first['id']} - #{orders.first['status']}"
+puts
+
+# ============================================================================
+# Example 5: Deterministic Seeding (Reproducible)
+# ============================================================================
+puts "5. DETERMINISTIC SEEDING (Reproducible)"
+puts "-" * 40
+
+seed_value = 42
+puts "Using seed: #{seed_value}"
+puts
+
+deterministic_users_1 = user_schema.generate_many(3, seed: seed_value)
+deterministic_users_2 = user_schema.generate_many(3, seed: seed_value)
+
+puts "First generation:"
+deterministic_users_1.each { |u| puts "  #{u['name']} - #{u['email']}" }
+puts
+puts "Second generation (same seed):"
+deterministic_users_2.each { |u| puts "  #{u['name']} - #{u['email']}" }
+puts
+puts "Are they identical? #{deterministic_users_1 == deterministic_users_2}"
+puts
+
+# ============================================================================
+# Example 6: Rails db/seeds.rb Style
+# ============================================================================
+puts "6. RAILS db/seeds.rb STYLE"
+puts "-" * 40
+
+puts <<~RUBY
+  # db/seeds.rb example
+  
+  require 'fake_data_dsl'
+  
+  # Load schema
+  schema = FakeDataDSL.load('db/schemas/user.dsl')
+  
+  # Clear existing data (optional)
+  User.delete_all
+  
+  # Seed users
+  puts "Seeding users..."
+  users = schema.generate_many(100, seed: ENV.fetch('SEED', 12345).to_i)
+  User.insert_all(users.map do |u|
+    {
+      uuid: u['uuid'],
+      email: u['email'],
+      name: u['name'],
+      encrypted_password: BCrypt::Password.create('password123'),
+      created_at: u['created_at'],
+      updated_at: Time.current
+    }
+  end)
+  
+  puts "Created \#{User.count} users"
+RUBY
+
+puts "=" * 70
+puts "Database seeding examples completed!"
+puts "=" * 70
+