synthra 0.1.0

data/docs/dsl_reference.md

@@ -0,0 +1,172 @@
+# DSL Reference
+
+Complete reference for the FakeDataDSL syntax.
+
+## Schema Definition
+
+A schema starts with a name followed by a colon:
+
+```ruby
+SchemaName:
+  field1: type1
+  field2: type2
+```
+
+## Field Types
+
+### Basic Types
+
+```ruby
+User:
+  id: uuid              # UUID v4
+  name: name            # Full name
+  email: email          # Email address
+  age: number(18..65)   # Number in range
+  active: boolean       # True/false
+  bio: text(100..500)   # Text with length range
+```
+
+### Type Arguments
+
+Many types accept arguments:
+
+```ruby
+User:
+  age: number(18..65)           # Range
+  price: number(min: 10, max: 100)  # Min/max
+  status: enum(active, inactive, pending)  # Enum values
+  tags: array(text, 3..10)     # Array with element type and size
+```
+
+### Nullable Fields
+
+Add `?` to make a field nullable:
+
+```ruby
+User:
+  middle_name: name?    # May be null
+  nickname: text?       # Optional field
+```
+
+### Optional Fields
+
+Use `optional` modifier to omit fields sometimes:
+
+```ruby
+User:
+  phone: phone optional  # May be omitted
+```
+
+## Comments
+
+Use `#` for comments:
+
+```ruby
+User:
+  # Primary identifier
+  id: uuid
+  name: name  # User's full name
+```
+
+## Behaviors
+
+Behaviors modify how data is generated:
+
+### Schema-Level Behaviors
+
+```ruby
+User:
+  @latency 100ms        # Add 100ms delay
+  @failure 5%           # 5% chance of failure
+  id: uuid
+  name: name
+```
+
+### Field-Level Behaviors
+
+```ruby
+User:
+  id: uuid @latency 50ms
+  name: name @failure 1%
+```
+
+See [Behaviors Guide](behaviors.md) for details.
+
+## Arrays
+
+Generate arrays of values:
+
+```ruby
+User:
+  tags: array(text, 3..10)           # 3-10 text items
+  scores: array(number(0..100), 5)  # Exactly 5 numbers
+```
+
+## Nested Objects
+
+Use the `object` type for nested structures:
+
+```ruby
+User:
+  address: object(
+    street: text,
+    city: city,
+    zip: postal_code
+  )
+```
+
+## References
+
+Reference other schemas:
+
+```ruby
+User:
+  id: uuid
+  name: name
+
+Order:
+  id: uuid
+  user_id: reference(User, id)  # Reference User's id field
+```
+
+## Custom Functions
+
+Use custom functions for computed values:
+
+```ruby
+User:
+  id: uuid
+  name: name
+  slug: custom(:generate_slug)  # Custom function
+```
+
+## Conditional Fields
+
+Fields can be conditional:
+
+```ruby
+User:
+  is_admin: boolean
+  admin_key: text if is_admin  # Only if is_admin is true
+```
+
+## Multiple Schemas
+
+Define multiple schemas in one file:
+
+```ruby
+User:
+  id: uuid
+  name: name
+
+Order:
+  id: uuid
+  user_id: reference(User, id)
+  total: number(10..1000)
+```
+
+## See Also
+
+- [Type Reference](type_reference.md) - Complete list of types
+- [Examples](examples.md) - Usage examples
+

data/docs/examples.md

@@ -0,0 +1,162 @@
+# Examples
+
+Real-world examples of using FakeDataDSL.
+
+## E-Commerce Application
+
+```ruby
+# schemas/ecommerce.dsl
+User:
+  id: uuid
+  email: email unique
+  name: name
+  created_at: past_date(days: 365)
+
+Product:
+  id: uuid
+  name: product_name
+  category: product_category
+  price: money(min: 10, max: 1000)
+  sku: sku
+
+Order:
+  id: uuid
+  user_id: reference(User, id)
+  product_id: reference(Product, id)
+  quantity: number(1..10)
+  total: formula(quantity * price)
+  status: enum(placed: 60%, processing: 30%, shipped: 10%)
+  created_at: past_date(days: 30)
+```
+
+## Social Media Platform
+
+```ruby
+# schemas/social.dsl
+User:
+  id: uuid
+  username: username unique
+  email: email unique
+  full_name: full_name
+  bio: text(50..200) optional
+  avatar_url: url optional
+  created_at: past_date(days: 730)
+
+Post:
+  id: uuid
+  author_id: reference(User, id)
+  content: text(100..1000)
+  likes: number(0..10000)
+  created_at: past_date(days: 30)
+
+Comment:
+  id: uuid
+  post_id: reference(Post, id)
+  author_id: reference(User, id)
+  content: text(10..500)
+  created_at: past_date(days: 7)
+```
+
+## Healthcare System
+
+```ruby
+# schemas/healthcare.dsl
+Patient:
+  id: uuid
+  first_name: first_name
+  last_name: last_name
+  date_of_birth: past_date(days: 36500)  # ~100 years
+  blood_type: blood_type
+  medical_record_number: medical_code(type: :icd10)
+
+VitalSigns:
+  patient_id: reference(Patient, id)
+  heart_rate: heart_rate(min: 60, max: 100)
+  bmi: bmi(range: 18.5..30.0)
+  recorded_at: past_date(days: 7)
+
+Diagnosis:
+  patient_id: reference(Patient, id)
+  code: medical_code(type: :icd10)
+  description: text(50..500)
+  diagnosed_at: past_date(days: 365)
+```
+
+## Financial Application
+
+```ruby
+# schemas/finance.dsl
+Account:
+  id: uuid
+  account_number: account_number
+  bank_name: bank_name
+  iban: iban(country: :us)
+  balance: transaction_amount(min: 0, max: 100000)
+  currency: currency
+
+Transaction:
+  id: uuid
+  from_account_id: reference(Account, id)
+  to_account_id: reference(Account, id)
+  amount: transaction_amount(min: 1, max: 10000)
+  currency: currency
+  status: enum(pending: 20%, completed: 75%, failed: 5%)
+  created_at: past_date(days: 30)
+
+Payment:
+  id: uuid
+  account_id: reference(Account, id)
+  credit_card: credit_card(type: :visa)
+  amount: transaction_amount(min: 10, max: 1000)
+  status: enum(approved: 90%, declined: 10%)
+  processed_at: past_date(days: 7)
+```
+
+## Testing Scenarios
+
+### Edge Case Testing
+
+```ruby
+# Generate edge cases
+schema = registry.schema('User')
+edge_records = schema.generate_many(100, mode: :edge)
+
+# Test validation
+edge_records.each do |record|
+  validate_user(record)  # Should handle edge cases
+end
+```
+
+### Invalid Data Testing
+
+```ruby
+# Generate invalid data
+invalid_records = schema.generate_many(100, mode: :invalid)
+
+# Test error handling
+invalid_records.each do |record|
+  expect { create_user(record) }.to raise_error(ValidationError)
+end
+```
+
+### Performance Testing
+
+```ruby
+# Generate with latency
+User:
+  @latency 50ms..200ms
+  id: uuid
+  name: name
+
+# Measure generation time
+start = Time.now
+records = schema.generate_many(1000)
+duration = Time.now - start
+puts "Generated 1000 records in #{duration}s"
+```
+
+## See Also
+
+- [Getting Started](getting_started.md) - Basic usage
+- [DSL Reference](dsl_reference.md) - Syntax details
+

data/docs/generation_modes.md

@@ -0,0 +1,125 @@
+# Generation Modes
+
+FakeDataDSL supports different generation modes for various testing scenarios.
+
+## Available Modes
+
+### Random Mode (Default)
+
+Generates realistic random data:
+
+```ruby
+schema = registry.schema('User')
+record = schema.generate(mode: :random)
+# => Normal, realistic data
+```
+
+### Edge Mode
+
+Generates edge case values (empty, boundary, null):
+
+```ruby
+record = schema.generate(mode: :edge)
+# => Edge cases: empty strings, null values, boundary numbers
+```
+
+**Use cases:**
+- Testing validation logic
+- Finding boundary bugs
+- Stress testing
+
+### Invalid Mode
+
+Generates intentionally invalid data:
+
+```ruby
+record = schema.generate(mode: :invalid)
+# => Invalid data: wrong types, malformed values
+```
+
+**Use cases:**
+- Testing error handling
+- Validating input sanitization
+- Security testing
+
+### Mixed Mode
+
+Combines random, edge, and invalid values:
+
+```ruby
+record = schema.generate(mode: :mixed)
+# => Mix of random, edge, and invalid values
+```
+
+**Custom ratios:**
+
+```ruby
+record = schema.generate(mode: :mixed, ratios: { random: 70, edge: 20, invalid: 10 })
+```
+
+## Mode Examples
+
+### Random Mode
+
+```ruby
+User:
+  name: name
+  age: number(18..65)
+  email: email
+
+# Generates:
+# { "name" => "John Smith", "age" => 42, "email" => "john@example.com" }
+```
+
+### Edge Mode
+
+```ruby
+# Same schema, edge mode:
+# { "name" => "", "age" => 18, "email" => "" }
+# or
+# { "name" => "A", "age" => 65, "email" => "a@b.c" }
+```
+
+### Invalid Mode
+
+```ruby
+# Same schema, invalid mode:
+# { "name" => 123, "age" => "not a number", "email" => nil }
+```
+
+## Mode Configuration
+
+Set default mode globally:
+
+```ruby
+FakeDataDSL.configure do |config|
+  config.default_mode = :edge
+end
+```
+
+Or per-schema:
+
+```ruby
+schema = registry.schema('User')
+schema.default_mode = :invalid
+```
+
+## Combining with Behaviors
+
+Modes work with behaviors:
+
+```ruby
+User:
+  @latency 100ms
+  @failure 5%
+  name: name
+
+# Edge mode + behaviors:
+# Generates edge cases with delays and occasional failures
+```
+
+## See Also
+
+- [Behaviors Guide](behaviors.md) - Behavior system
+- [Examples](examples.md) - Mode usage examples
+

data/docs/getting_started.md

@@ -0,0 +1,92 @@
+# Getting Started with FakeDataDSL
+
+FakeDataDSL is a Ruby gem for generating realistic fake data using a simple, human-friendly DSL (Domain-Specific Language).
+
+## Installation
+
+Add FakeDataDSL to your Gemfile:
+
+```ruby
+gem 'fake_data_dsl'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install fake_data_dsl
+```
+
+## Basic Usage
+
+### 1. Define a Schema
+
+Create a schema file (e.g., `user.dsl`):
+
+```ruby
+User:
+  id: uuid
+  name: name
+  email: email
+  age: number(18..65)
+  active: boolean
+```
+
+### 2. Load and Generate
+
+```ruby
+require 'fake_data_dsl'
+
+# Load schema
+registry = FakeDataDSL::Registry.new
+registry.load_file('user.dsl')
+
+# Generate a single record
+schema = registry.schema('User')
+record = schema.generate
+# => { "id" => "550e8400-e29b-41d4-a716-446655440000", 
+#      "name" => "John Smith", 
+#      "email" => "john.smith@example.com", 
+#      "age" => 42, 
+#      "active" => true }
+
+# Generate multiple records
+records = schema.generate_many(10)
+# => Array of 10 user records
+```
+
+## Key Concepts
+
+### Schemas
+
+A **schema** defines the structure of your data. Each schema has a name (like `User`) and contains fields with types.
+
+### Types
+
+Types define what kind of data to generate. Examples:
+- `uuid` - Universally unique identifiers
+- `name` - Person names
+- `email` - Email addresses
+- `number` - Numeric values
+- `boolean` - True/false values
+
+See [Type Reference](type_reference.md) for the complete list.
+
+### Fields
+
+Fields are the properties of your schema. Each field has:
+- A name (e.g., `id`, `name`)
+- A type (e.g., `uuid`, `name`)
+- Optional arguments (e.g., `number(18..65)`)
+
+## Next Steps
+
+- Read the [DSL Reference](dsl_reference.md) to learn the full syntax
+- Explore [Examples](examples.md) for real-world use cases
+- Check out [Advanced Features](advanced_features.md) for complex scenarios
+