synthra 0.1.0

data/tech_docs/modes/overview.md

@@ -0,0 +1,350 @@
+# Generation Modes Overview
+
+Understanding and using different generation modes for comprehensive testing.
+
+## Table of Contents
+
+- [What are Generation Modes?](#what-are-generation-modes)
+- [Available Modes](#available-modes)
+- [Using Modes](#using-modes)
+- [Mode Details](#mode-details)
+- [Choosing the Right Mode](#choosing-the-right-mode)
+- [Custom Mode Handling](#custom-mode-handling)
+
+---
+
+## What are Generation Modes?
+
+Generation modes control what KIND of data is generated:
+
+| Mode | Purpose | Output |
+|------|---------|--------|
+| `:random` | Typical testing | Realistic values |
+| `:edge` | Boundary testing | Edge cases |
+| `:invalid` | Validation testing | Invalid data |
+| `:mixed` | Comprehensive testing | Mix of all |
+
+---
+
+## Available Modes
+
+### Random Mode (Default)
+
+Generates typical, realistic data:
+
+```ruby
+schema.generate(mode: :random)
+# => { "age" => 34, "name" => "John Smith", "email" => "john@example.com" }
+```
+
+### Edge Mode
+
+Generates boundary values and edge cases:
+
+```ruby
+schema.generate(mode: :edge)
+# => { "age" => 0, "name" => "", "email" => "a@b.c" }
+```
+
+### Invalid Mode
+
+Generates invalid data for validation testing:
+
+```ruby
+schema.generate(mode: :invalid)
+# => { "age" => "not_a_number", "name" => nil, "email" => "not-an-email" }
+```
+
+### Mixed Mode
+
+Randomly combines all modes:
+
+```ruby
+schema.generate(mode: :mixed)
+# 80% random, 15% edge, 5% invalid
+```
+
+---
+
+## Using Modes
+
+### Single Record
+
+```ruby
+# Default (random)
+user = schema.generate
+
+# Explicit mode
+user = schema.generate(mode: :random)
+user = schema.generate(mode: :edge)
+user = schema.generate(mode: :invalid)
+user = schema.generate(mode: :mixed)
+```
+
+### Multiple Records
+
+```ruby
+# All same mode
+users = schema.generate_many(100, mode: :edge)
+
+# Mixed naturally varies per-record
+users = schema.generate_many(100, mode: :mixed)
+```
+
+### Streaming
+
+```ruby
+schema.generate_stream(count: 1000, mode: :edge).each do |user|
+  test_edge_case(user)
+end
+```
+
+### CLI
+
+```bash
+fake_data_dsl generate User --mode random
+fake_data_dsl generate User --mode edge
+fake_data_dsl generate User --mode invalid
+fake_data_dsl generate User --mode mixed
+```
+
+---
+
+## Mode Details
+
+### Random Mode
+
+Generates typical values:
+
+| Type | Random Output |
+|------|---------------|
+| `uuid` | `"550e8400-e29b-41d4-a716-446655440000"` |
+| `name` | `"John Smith"` |
+| `email` | `"john.smith@example.com"` |
+| `number(0..100)` | `42` |
+| `text(10..50)` | `"Lorem ipsum dolor sit amet"` |
+| `boolean` | `true` or `false` |
+| `date` | `"2024-06-15"` |
+
+### Edge Mode
+
+Generates boundary values:
+
+| Type | Edge Cases |
+|------|------------|
+| `uuid` | All zeros, all ones, version variants |
+| `name` | Empty, single char, very long, unicode |
+| `email` | Minimal (`a@b.c`), special chars, long |
+| `number(0..100)` | `0`, `100`, `-1`, `101` |
+| `text(10..50)` | Empty, min length, max length |
+| `boolean` | `true`, `false` |
+| `date` | Min date, max date, leap year |
+
+#### Edge Case Examples
+
+```ruby
+# Numbers
+{ "age" => 0 }           # Minimum
+{ "age" => 100 }         # Maximum
+{ "score" => -1 }        # Below minimum
+{ "score" => 101 }       # Above maximum
+
+# Strings
+{ "name" => "" }         # Empty
+{ "name" => "X" }        # Single character
+{ "name" => "X" * 1000 } # Very long
+
+# Dates
+{ "date" => "1970-01-01" }  # Unix epoch
+{ "date" => "2038-01-19" }  # Y2038
+{ "date" => "2024-02-29" }  # Leap day
+```
+
+### Invalid Mode
+
+Generates invalid data:
+
+| Type | Invalid Values |
+|------|----------------|
+| `uuid` | `nil`, `"not-a-uuid"`, `123` |
+| `name` | `nil`, `123`, `[]` |
+| `email` | `"not-email"`, `"@invalid"`, `nil` |
+| `number` | `"string"`, `nil`, `NaN` |
+| `text` | `nil`, `123`, `[]` |
+| `boolean` | `nil`, `"maybe"`, `1` |
+| `date` | `"not-date"`, `nil`, `"2024-13-45"` |
+
+#### Invalid Value Examples
+
+```ruby
+# Wrong types
+{ "age" => "thirty-four" }    # String instead of number
+{ "active" => "yes" }         # String instead of boolean
+{ "email" => 12345 }          # Number instead of string
+
+# Null values
+{ "name" => nil }
+{ "required_field" => nil }
+
+# Malformed formats
+{ "email" => "not-an-email" }
+{ "date" => "yesterday" }
+{ "uuid" => "12345" }
+```
+
+### Mixed Mode
+
+Distributes modes across generation:
+
+```ruby
+# Distribution (approximate)
+# - 80% random
+# - 15% edge
+# - 5% invalid
+
+users = schema.generate_many(1000, mode: :mixed)
+
+# Result distribution:
+# ~800 with realistic values
+# ~150 with edge cases
+# ~50 with invalid values
+```
+
+---
+
+## Choosing the Right Mode
+
+### Testing Scenarios
+
+| Scenario | Recommended Mode |
+|----------|------------------|
+| Happy path testing | `:random` |
+| Boundary testing | `:edge` |
+| Input validation | `:invalid` |
+| Integration testing | `:mixed` |
+| Load testing | `:random` |
+| Security testing | `:edge` + `:invalid` |
+| UI testing | `:random` |
+| API contract testing | `:mixed` |
+
+### RSpec Examples
+
+```ruby
+RSpec.describe User do
+  describe "validations" do
+    context "with valid data" do
+      let(:user) { schema.generate(mode: :random) }
+      
+      it "is valid" do
+        expect(User.new(user)).to be_valid
+      end
+    end
+    
+    context "with edge cases" do
+      let(:user) { schema.generate(mode: :edge) }
+      
+      it "handles edge cases" do
+        user_obj = User.new(user)
+        # May or may not be valid depending on constraints
+        expect { user_obj.validate! }.not_to raise_error(StandardError)
+      end
+    end
+    
+    context "with invalid data" do
+      let(:user) { schema.generate(mode: :invalid) }
+      
+      it "rejects invalid data" do
+        expect(User.new(user)).not_to be_valid
+      end
+    end
+  end
+end
+```
+
+### Comprehensive Testing
+
+```ruby
+# Test all modes
+[:random, :edge, :invalid, :mixed].each do |mode|
+  context "with #{mode} data" do
+    let(:data) { schema.generate(mode: mode) }
+    
+    it "handles #{mode} data gracefully" do
+      expect { process(data) }.not_to raise_error
+    end
+  end
+end
+```
+
+---
+
+## Custom Mode Handling
+
+### In Custom Types
+
+```ruby
+class CustomType < FakeDataDSL::Types::Base
+  def generate_random(rng, args)
+    # Typical value
+    "normal-value-#{rng.int(1, 100)}"
+  end
+  
+  def generate_edge(rng, args)
+    # Boundary cases
+    ["", "x", "x" * 1000, "特殊字符", "\x00\x00"].sample
+  end
+  
+  def generate_invalid(rng, args)
+    # Invalid values
+    [nil, 123, [], {}, false].sample
+  end
+end
+```
+
+### In Custom Functions
+
+```ruby
+FakeDataDSL.register_function(:computed_field) do |context|
+  mode = context[:__mode__]
+  
+  case mode
+  when :random
+    calculate_normal_value(context)
+  when :edge
+    calculate_edge_value(context)
+  when :invalid
+    generate_invalid_value
+  else
+    calculate_normal_value(context)
+  end
+end
+```
+
+---
+
+## Mode-Specific Type Output
+
+### Complete Reference Table
+
+| Type | Random | Edge | Invalid |
+|------|--------|------|---------|
+| `uuid` | Valid v4 UUID | All zeros | `nil`, string |
+| `ulid` | Valid ULID | Min/max time | `nil`, number |
+| `name` | "John Smith" | "", unicode | `nil`, `123` |
+| `email` | Valid email | "a@b.c" | "invalid" |
+| `url` | Valid URL | Long URL | "not-url" |
+| `number(0..100)` | 42 | 0, 100 | "string" |
+| `boolean` | true/false | true, false | `nil`, "yes" |
+| `date` | Recent date | Epoch, Y2038 | "invalid" |
+| `text(10..50)` | Lorem ipsum | Empty, max | `nil`, `123` |
+| `enum(a,b,c)` | "a", "b", "c" | First, last | `nil`, "invalid" |
+
+---
+
+## Next Steps
+
+- [Random Mode](random.md) - Detailed random generation
+- [Edge Mode](edge.md) - Boundary value testing
+- [Invalid Mode](invalid.md) - Validation testing
+- [Mixed Mode](mixed.md) - Comprehensive testing
+