synthra 0.1.0

data/tech_docs/appendices/type_chart.md

@@ -0,0 +1,193 @@
+# Type Reference Chart
+
+Quick reference for all available types in FakeDataDSL.
+
+## Identifier Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `uuid` | UUID v4/v6/v7 | `version: 4\|6\|7`, `unique: true` | `"550e8400-e29b-41d4-a716-446655440000"` | `"00000000-0000-0000-0000-000000000000"` |
+| `ulid` | ULID | - | `"01ARZ3NDEKTSV4RRFQ69G5FAV"` | `"00000000000000000000000000"` |
+| `id_sequence` | Auto-increment | `start: N`, `step: N` | `1`, `2`, `3`... | Same as random |
+
+## Personal Data Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `name` | Full name | - | `"John Smith"` | `""`, `"X"` |
+| `first_name` | First name | - | `"John"` | `""` |
+| `last_name` | Last name | - | `"Smith"` | `""` |
+| `email` | Email address | `unique: true` | `"john@example.com"` | `"a@b.c"` |
+| `phone` | Phone number | `locale: XX` | `"+1-555-123-4567"` | `""` |
+| `username` | Username | - | `"john_smith42"` | `""`, `"x"` |
+| `avatar` | Avatar URL | - | `"https://example.com/avatar.jpg"` | `""` |
+
+## Text Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `text` | Random text | `min..max`, `length: N` | `"Lorem ipsum..."` | `""`, max length |
+| `paragraph` | Paragraph(s) | `count: N` | Multi-sentence text | `""` |
+| `sentence` | Sentence(s) | `count: N` | `"The quick brown fox."` | `""` |
+| `word` | Word(s) | `count: N` | `"hello"` | `""` |
+| `words` | Multiple words | `count: N` | `"hello world foo"` | `""` |
+
+## Number Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `number` | Integer/float | `min..max`, `precision: N` | `42`, `3.14` | `0`, min, max |
+| `integer` | Integer only | `min..max` | `42` | `0`, min, max |
+| `float` | Float only | `min..max` | `42.5` | `0.0`, min, max |
+| `latitude` | Latitude | - | `40.7128` | `-90.0`, `90.0` |
+| `longitude` | Longitude | - | `-74.0060` | `-180.0`, `180.0` |
+
+## Boolean & Enum
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `boolean` | True/false | `true:N%`, `false:N%` | `true`, `false` | `true`, `false` |
+| `enum` | One of values | `val1, val2:N%` | `"val1"` | First, last value |
+
+## Date & Time Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `date` | Random date | - | `"2024-06-15"` | `"1970-01-01"` |
+| `past_date` | Past date | `Nd`, `Nm`, `Ny` | `"2024-01-15"` | Min date |
+| `future_date` | Future date | `Nd`, `Nm`, `Ny` | `"2025-06-15"` | Max date |
+| `timestamp` | DateTime | - | `"2024-06-15T14:30:00Z"` | Min/max timestamp |
+| `now` | Current time | - | `"2024-07-15T10:30:00Z"` | Current time |
+| `datetime` | DateTime range | `from:`, `to:` | `"2024-06-15T14:30:00Z"` | From/to bounds |
+| `time` | Time only | - | `"14:30:00"` | `"00:00:00"` |
+
+## Location Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `address` | Full address | - | `"123 Main St, City, ST 12345"` | `""` |
+| `street_address` | Street address | - | `"123 Main Street"` | `""` |
+| `city` | City name | - | `"New York"` | `""` |
+| `state` | State/province | - | `"California"` | `""` |
+| `country` | Country name | - | `"United States"` | `""` |
+| `country_code` | ISO country code | - | `"US"` | `"XX"` |
+| `postal_code` | ZIP/postal code | `country: XX` | `"10001"` | `"00000"` |
+| `time_zone` | Timezone | - | `"America/New_York"` | `"UTC"` |
+
+## Technology Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `url` | URL | - | `"https://example.com"` | `""`, long URL |
+| `domain` | Domain name | - | `"example.com"` | `""` |
+| `ip` | IPv4 address | - | `"192.168.1.1"` | `"0.0.0.0"` |
+| `ipv6` | IPv6 address | - | `"2001:db8::1"` | `"::"` |
+| `mac_address` | MAC address | - | `"00:1B:44:11:3A:B7"` | `"00:00:00:00:00:00"` |
+| `user_agent` | User agent | - | `"Mozilla/5.0..."` | `""` |
+
+## Finance Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `money` | Amount + currency | `range:`, `currency:` | `{"amount": 99.99, "currency": "USD"}` | Min/max |
+| `currency` | Currency name | - | `"US Dollar"` | `""` |
+| `currency_code` | ISO currency | - | `"USD"` | `"XXX"` |
+| `iban` | IBAN | - | `"GB82WEST12345698765432"` | Invalid format |
+| `credit_card` | Card number | - | `"4111111111111111"` | Test numbers |
+| `bank_name` | Bank name | - | `"Chase"` | `""` |
+
+## Crypto Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `bitcoin_address` | BTC address | - | `"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"` | Invalid |
+| `ethereum_address` | ETH address | - | `"0x71C7656EC7ab88b098defB751B7401B5f6d8976F"` | Invalid |
+| `hash` | Hash string | `algorithm: md5\|sha256` | `"d41d8cd98f00b..."` | `""` |
+
+## Content Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `title` | Title/headline | - | `"Breaking News"` | `""` |
+| `company_name` | Company name | - | `"Acme Corp"` | `""` |
+| `job_title` | Job title | - | `"Software Engineer"` | `""` |
+| `buzzword` | Business buzzword | - | `"synergize"` | `""` |
+| `color` | Color name | - | `"blue"` | `""` |
+| `color_hex` | Hex color | - | `"#FF5733"` | `"#000000"` |
+
+## Health Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `blood_type` | Blood type | - | `"A+"` | All types |
+
+## Travel Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `airport_code` | IATA code | - | `"JFK"` | `"XXX"` |
+| `airline` | Airline name | - | `"Delta"` | `""` |
+| `flight_number` | Flight number | - | `"AA1234"` | `"XX0000"` |
+
+## Complex Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `array` | Array of items | `element, size` | `["a", "b", "c"]` | `[]`, large array |
+| `object` | Generic object | - | `{"key": "value"}` | `{}` |
+| `Ref(Schema.field)` | Reference | - | Referenced value | - |
+| `custom` | Custom function | `:function_name` | Function result | - |
+
+## Special Types
+
+| Type | Description | Arguments | Random Example | Edge Example |
+|------|-------------|-----------|----------------|--------------|
+| `formula` | Math expression | `"field1 + field2"` | Computed value | - |
+| `template` | String template | `"${field} text"` | Interpolated string | - |
+| `sequence` | Custom sequence | Various | Sequential value | - |
+
+---
+
+## Type Arguments Reference
+
+### Range Arguments
+
+```dsl
+number(0..100)      # Integer range
+number(0.0..100.0)  # Float range
+text(10..50)        # Character count range
+```
+
+### Named Arguments
+
+```dsl
+uuid(unique: true, version: 7)
+number(min: 0, max: 100, precision: 2)
+past_date(days: 30)
+```
+
+### Duration Arguments
+
+```dsl
+past_date(30d)   # 30 days
+past_date(6m)    # 6 months
+past_date(2y)    # 2 years
+```
+
+### Probability Arguments
+
+```dsl
+boolean(true:80%)              # 80% true
+enum(a:60%, b:30%, c:10%)     # Weighted enum
+```
+
+---
+
+## Mode Output Summary
+
+| Mode | String | Number | Boolean | Date |
+|------|--------|--------|---------|------|
+| `:random` | Realistic | In range | 50/50 | Realistic |
+| `:edge` | Empty, long | Min, max | true, false | Boundaries |
+| `:invalid` | nil, wrong type | String | nil, "yes" | Invalid format |
+

data/tech_docs/basic_concepts.md

@@ -0,0 +1,383 @@
+# Basic Concepts
+
+Understanding the core concepts and terminology of FakeDataDSL.
+
+## Table of Contents
+
+- [What is FakeDataDSL?](#what-is-fakedatadsl)
+- [Core Concepts](#core-concepts)
+- [The DSL](#the-dsl)
+- [Types](#types)
+- [Generation](#generation)
+- [Modes](#modes)
+- [Behaviors](#behaviors)
+- [Registry](#registry)
+
+---
+
+## What is FakeDataDSL?
+
+FakeDataDSL is a Ruby gem that lets you:
+
+1. **Define data schemas** using a simple, human-readable DSL
+2. **Generate fake data** that matches those schemas
+3. **Simulate real-world conditions** like network latency and failures
+4. **Test edge cases** with different generation modes
+
+### Key Benefits
+
+| Benefit | Description |
+|---------|-------------|
+| **Declarative** | Define WHAT data looks like, not HOW to generate it |
+| **Deterministic** | Same seed always produces same output |
+| **Flexible** | Multiple generation modes for different testing needs |
+| **Scalable** | Stream millions of records without memory issues |
+| **Extensible** | Add custom types, functions, and behaviors |
+
+---
+
+## Core Concepts
+
+### Schema
+
+A **schema** defines the structure of your data. It specifies:
+- Field names
+- Field types
+- Optional constraints and arguments
+
+```dsl
+User:              # Schema name
+  id: uuid         # Field: name: type
+  name: name       # Field: name: type
+  age: number(18..65)  # Field with arguments
+```
+
+### Field
+
+A **field** is a single data point within a schema:
+
+```dsl
+SchemaName:
+  field_name: type              # Basic field
+  field_name: type(args)        # Field with arguments
+  optional_field?: type         # Optional field
+  nullable_field: type?         # Nullable field
+```
+
+### Type
+
+A **type** is a generator that produces specific kinds of data:
+
+| Type | Generates |
+|------|-----------|
+| `uuid` | `"550e8400-e29b-41d4-a716-446655440000"` |
+| `name` | `"John Smith"` |
+| `email` | `"john@example.com"` |
+| `number(1..100)` | `42` |
+| `boolean` | `true` or `false` |
+
+### Mode
+
+A **mode** determines what kind of data to generate:
+
+| Mode | Purpose |
+|------|---------|
+| `:random` | Typical, realistic values (default) |
+| `:edge` | Boundary values, edge cases |
+| `:invalid` | Invalid data for validation testing |
+| `:mixed` | Combination of all modes |
+
+### Behavior
+
+A **behavior** simulates real-world conditions:
+
+```dsl
+APIResponse:
+  @latency 100..500ms    # Add delay
+  @failure 5%            # 5% chance of error
+  
+  data: text
+```
+
+---
+
+## The DSL
+
+### Syntax Overview
+
+FakeDataDSL uses an indentation-based syntax:
+
+```dsl
+# Comments start with #
+
+SchemaName:                    # Schema declaration (ends with colon)
+  field_name: type             # Field definition (indented)
+  field_name: type(arguments)  # Field with arguments
+  
+  @behavior value              # Schema-level behavior
+```
+
+### Indentation Rules
+
+- Use **2 spaces** for indentation (recommended)
+- Tabs are supported but don't mix tabs and spaces
+- Each schema starts at column 0
+- Fields are indented under their schema
+
+### Multiple Schemas
+
+```dsl
+User:
+  id: uuid
+  name: name
+
+Order:
+  id: uuid
+  user_id: Ref(User.id)
+```
+
+---
+
+## Types
+
+### Built-in Types
+
+FakeDataDSL includes 50+ built-in types:
+
+#### Identifiers
+- `uuid`, `uuid(version: 7)`, `ulid`, `id_sequence`
+
+#### Personal Data
+- `name`, `first_name`, `last_name`, `email`, `phone`
+
+#### Location
+- `address`, `city`, `country`, `postal_code`, `latitude`, `longitude`
+
+#### Date/Time
+- `date`, `past_date`, `future_date`, `timestamp`, `now`
+
+#### Finance
+- `money`, `currency`, `iban`, `credit_card`
+
+#### Technology
+- `url`, `ip`, `ipv6`, `domain`, `mac_address`
+
+#### Text
+- `text(min..max)`, `paragraph`, `sentence`, `word`
+
+#### Primitives
+- `number(min..max)`, `boolean`, `enum(val1, val2)`
+
+### Type Arguments
+
+Types can accept arguments:
+
+```dsl
+User:
+  # Range arguments
+  age: number(18..65)
+  bio: text(50..500)
+  
+  # Named arguments
+  id: uuid(unique: true, version: 7)
+  role: enum(user, admin:10%)
+  
+  # Duration arguments
+  created_at: past_date(1y)
+  expires_at: future_date(30d)
+```
+
+### Custom Types
+
+Create your own types:
+
+```ruby
+FakeDataDSL.register_type(:ssn) do |rng, context, args, mode|
+  "#{rng.int(100, 999)}-#{rng.int(10, 99)}-#{rng.int(1000, 9999)}"
+end
+```
+
+---
+
+## Generation
+
+### Single Record
+
+```ruby
+schema = FakeDataDSL.load('schema.dsl')
+record = schema.generate
+```
+
+### Multiple Records
+
+```ruby
+records = schema.generate_many(100)
+```
+
+### Streaming (Large Batches)
+
+```ruby
+schema.generate_stream(count: 1_000_000).each do |record|
+  process(record)
+end
+```
+
+### With Options
+
+```ruby
+record = schema.generate(
+  seed: 12345,           # For reproducibility
+  mode: :edge,           # Generation mode
+  registry: registry,    # For cross-references
+  overrides: {           # Override specific fields
+    'status' => 'active'
+  }
+)
+```
+
+---
+
+## Modes
+
+### Random Mode (Default)
+
+Generates typical, realistic data:
+
+```ruby
+schema.generate(mode: :random)
+# => {"age" => 34, "name" => "John Smith"}
+```
+
+### Edge Mode
+
+Generates boundary values and edge cases:
+
+```ruby
+schema.generate(mode: :edge)
+# => {"age" => 0, "name" => ""}
+```
+
+Edge cases include:
+- Empty strings
+- Minimum/maximum values
+- Boundary dates
+- Special characters
+
+### Invalid Mode
+
+Generates invalid data for validation testing:
+
+```ruby
+schema.generate(mode: :invalid)
+# => {"age" => "not_a_number", "name" => nil}
+```
+
+Invalid data includes:
+- Wrong types
+- Null values
+- Malformed formats
+- Out-of-range values
+
+### Mixed Mode
+
+Combines all modes randomly:
+
+```ruby
+schema.generate(mode: :mixed)
+# 80% random, 15% edge, 5% invalid
+```
+
+---
+
+## Behaviors
+
+### What Are Behaviors?
+
+Behaviors simulate real-world conditions:
+
+| Behavior | Description |
+|----------|-------------|
+| `@latency` | Adds artificial delay |
+| `@failure` | Throws errors randomly |
+| `@partial_data` | Omits random fields |
+| `@close_connection` | Simulates connection drops |
+| `@simulate_error` | Returns HTTP error codes |
+
+### Schema-Level Behaviors
+
+Apply to all generation:
+
+```dsl
+APIResponse:
+  @latency 100..500ms
+  @failure 5%
+  
+  id: uuid
+  data: text
+```
+
+### Field-Level Behaviors
+
+Apply to specific fields:
+
+```dsl
+User:
+  id: uuid
+  avatar: url @partial_data 30%
+```
+
+---
+
+## Registry
+
+### What is a Registry?
+
+A **registry** manages multiple schemas and resolves cross-schema references.
+
+### Creating a Registry
+
+```ruby
+registry = FakeDataDSL::Registry.new
+
+# Load individual files
+registry.load_file('schemas/user.dsl')
+registry.load_file('schemas/order.dsl')
+
+# Or load entire directory
+registry.load_dir('schemas/')
+```
+
+### Cross-Schema References
+
+```dsl
+# user.dsl
+User:
+  id: uuid
+  name: name
+
+# order.dsl
+Order:
+  id: uuid
+  user_id: Ref(User.id)  # References User schema
+```
+
+```ruby
+registry = FakeDataDSL::Registry.new
+registry.load_dir('schemas/')
+
+# Generate with resolved references
+order = registry.schema('Order').generate(registry: registry)
+# order["user_id"] is a valid UUID
+```
+
+---
+
+## Next Steps
+
+Now that you understand the basics:
+
+1. [DSL Reference](dsl/schema_definition.md) - Complete syntax guide
+2. [Type Reference](dsl/core_types.md) - All available types
+3. [API Reference](api/overview.md) - Ruby API documentation
+4. [Examples](../tech_example/README.md) - Real-world examples
+