synthra 0.1.0

data/tech_docs/dsl/schema_definition.md

@@ -0,0 +1,399 @@
+# Schema Definition
+
+Complete guide to defining schemas in FakeDataDSL.
+
+## Table of Contents
+
+- [Basic Syntax](#basic-syntax)
+- [Schema Names](#schema-names)
+- [Field Definitions](#field-definitions)
+- [Multiple Schemas](#multiple-schemas)
+- [Comments](#comments)
+- [Indentation](#indentation)
+- [Best Practices](#best-practices)
+
+---
+
+## Basic Syntax
+
+### Minimal Schema
+
+```dsl
+User:
+  id: uuid
+```
+
+### Complete Example
+
+```dsl
+# User schema with all common features
+User:
+  # Required fields
+  id: uuid(unique: true)
+  email: email(unique: true)
+  name: name
+  
+  # Field with range
+  age: number(18..100)
+  
+  # Boolean with probability
+  active: boolean(true:90%)
+  
+  # Enum with weights
+  role: enum(user:80%, admin:5%, moderator:15%)
+  
+  # Optional field (may not appear)
+  phone?: phone
+  
+  # Nullable field (may be null)
+  bio: text?
+  
+  # Optional and nullable
+  avatar?: url?
+  
+  # Nested object
+  address: Address
+  
+  # Date field
+  created_at: past_date(2y)
+  
+  # Schema-level behavior
+  @latency 10..50ms
+```
+
+---
+
+## Schema Names
+
+### Naming Rules
+
+- Must start with uppercase letter
+- Can contain letters, numbers, underscores
+- Must end with colon (`:`)
+- Must be unique within a file
+
+### Valid Names
+
+```dsl
+User:
+UserProfile:
+User_V2:
+OrderLineItem:
+API_Response:
+```
+
+### Invalid Names
+
+```dsl
+user:         # Must start with uppercase
+123User:      # Cannot start with number
+user-profile: # Hyphens not allowed
+```
+
+---
+
+## Field Definitions
+
+### Basic Field
+
+```dsl
+SchemaName:
+  field_name: type
+```
+
+### Field with Arguments
+
+```dsl
+SchemaName:
+  # Positional arguments
+  age: number(18..65)
+  
+  # Named arguments
+  id: uuid(unique: true, version: 7)
+  
+  # Mixed arguments
+  price: number(0..1000, precision: 2)
+```
+
+### Optional Fields
+
+Optional fields may not appear in the output:
+
+```dsl
+User:
+  name: name        # Always present
+  phone?: phone     # May not appear (50% probability)
+```
+
+### Nullable Fields
+
+Nullable fields may have a `null` value:
+
+```dsl
+User:
+  name: name        # Never null
+  nickname: text?   # May be null (50% probability)
+```
+
+### Optional AND Nullable
+
+```dsl
+User:
+  # May not appear, AND if present may be null
+  emergency_contact?: phone?
+```
+
+### Conditional Fields
+
+Fields that appear based on conditions:
+
+```dsl
+Order:
+  status: enum(pending, shipped, delivered)
+  
+  # Only present when status is truthy
+  tracking_number: text(20) if status
+```
+
+**Note:** Currently only truthiness checks are supported, not comparisons.
+
+### Field with Behaviors
+
+```dsl
+User:
+  profile_image: url @partial_data 30%
+  settings: object @latency 50..100ms
+```
+
+---
+
+## Multiple Schemas
+
+### In Same File
+
+```dsl
+User:
+  id: uuid
+  name: name
+  email: email
+
+Address:
+  street: text(10..100)
+  city: name
+  country: country_code
+  postal_code: postal_code
+
+Order:
+  id: uuid
+  user: User        # Embed User
+  shipping: Address # Embed Address
+```
+
+### Schema References
+
+```dsl
+# Reference another schema as a type
+User:
+  id: uuid
+  address: Address  # Embeds full Address schema
+
+# Reference specific field from another schema
+Order:
+  user_id: Ref(User.id)  # Just the ID, not full User
+```
+
+---
+
+## Comments
+
+### Single-Line Comments
+
+```dsl
+# This is a comment
+User:
+  id: uuid      # Inline comment
+  name: name    # Another comment
+```
+
+### Documentation Comments
+
+```dsl
+# =================================
+# User Schema
+# =================================
+# Represents a user in the system.
+# Generated for testing purposes.
+#
+# Fields:
+# - id: Unique identifier
+# - name: Full name
+# - email: Contact email
+# =================================
+
+User:
+  id: uuid
+  name: name
+  email: email
+```
+
+---
+
+## Indentation
+
+### Spaces (Recommended)
+
+Use 2 spaces for indentation:
+
+```dsl
+User:
+  id: uuid
+  name: name
+  address:
+    street: text
+    city: name
+```
+
+### Tabs
+
+Tabs are supported:
+
+```dsl
+User:
+	id: uuid
+	name: name
+```
+
+### Rules
+
+1. **Don't mix tabs and spaces** - Causes parsing error
+2. **Be consistent** - Use same indentation throughout
+3. **Schema at column 0** - Schema names must start at beginning
+4. **Fields indented** - Fields must be indented under schema
+
+### Error Examples
+
+```dsl
+# ERROR: Mixed tabs and spaces
+User:
+  id: uuid     # 2 spaces
+	name: name   # tab
+```
+
+```dsl
+# ERROR: Inconsistent indentation
+User:
+  id: uuid     # 2 spaces
+    name: name # 4 spaces
+```
+
+---
+
+## Best Practices
+
+### 1. Use Descriptive Names
+
+```dsl
+# Good
+UserProfile:
+  full_name: name
+  email_address: email
+  date_of_birth: past_date(100y)
+
+# Avoid
+UP:
+  n: name
+  e: email
+  d: date
+```
+
+### 2. Group Related Fields
+
+```dsl
+User:
+  # Identity
+  id: uuid
+  username: text(3..20)
+  
+  # Personal info
+  first_name: name
+  last_name: name
+  
+  # Contact
+  email: email
+  phone?: phone
+  
+  # Metadata
+  created_at: past_date(2y)
+  updated_at: past_date(30d)
+```
+
+### 3. Use Comments
+
+```dsl
+# E-commerce Order
+# 
+# Represents a customer order with line items.
+# Used for testing order processing workflow.
+Order:
+  id: uuid(unique: true)
+  
+  # Customer reference
+  customer_id: Ref(Customer.id)
+  
+  # Order details
+  items: array(LineItem, 1..10)
+  total: custom(:calculate_total)
+  
+  # Status tracking
+  status: enum(pending, processing, shipped, delivered)
+  tracking_number: text(20) if status  # Only when shipped
+```
+
+### 4. Separate Schemas by Domain
+
+```
+schemas/
+├── users/
+│   ├── user.dsl
+│   ├── profile.dsl
+│   └── preferences.dsl
+├── orders/
+│   ├── order.dsl
+│   ├── line_item.dsl
+│   └── shipping.dsl
+└── products/
+    ├── product.dsl
+    └── category.dsl
+```
+
+### 5. Use Unique Constraints
+
+```dsl
+User:
+  id: uuid(unique: true)
+  email: email(unique: true)
+  username: text(3..20, unique: true)
+```
+
+### 6. Set Realistic Ranges
+
+```dsl
+# Good - realistic ranges
+User:
+  age: number(18..100)
+  salary: number(30000..500000)
+
+# Avoid - unrealistic ranges
+User:
+  age: number(0..1000)
+  salary: number(0..999999999)
+```
+
+---
+
+## Next Steps
+
+- [Core Types](core_types.md) - All built-in types
+- [Field Modifiers](field_modifiers.md) - Optional, nullable, conditional
+- [Complex Types](complex_types.md) - Arrays, objects, references
+

data/tech_docs/export/README.md

@@ -0,0 +1,276 @@
+# FakeDataDSL Export Guide
+
+FakeDataDSL provides comprehensive export capabilities for both schema structure and generated data.
+
+## Export Categories
+
+### Schema Exports (Types/Structure)
+Export your schema definitions to different type systems:
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| `json-schema` | `.schema.json` | JSON Schema (draft 2020-12) |
+| `typescript` / `ts` | `.ts` | TypeScript interfaces |
+| `javascript` / `js` | `.js` | JavaScript with JSDoc types |
+| `python` / `py` / `pydantic` | `.py` | Python Pydantic models |
+| `dataclass` | `.py` | Python dataclasses |
+| `sql` / `sql-ddl` | `.sql` | SQL CREATE TABLE statements |
+| `graphviz` / `dot` | `.dot` | GraphViz diagram |
+
+### Data Exports (Generated Records)
+Export generated fake data in various formats:
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| `json` / `json-data` | `.json` | JSON array of records |
+| `csv` | `.csv` | CSV with headers |
+| `sql-insert` / `insert` | `.sql` | SQL INSERT statements |
+| `yaml` / `yml` | `.yaml` | YAML format |
+| `xml` | `.xml` | XML format |
+
+## Ruby API
+
+### Schema Exports
+
+```ruby
+require "fake_data_dsl"
+
+# Load schemas
+registry = FakeDataDSL::Registry.new
+registry.load_dir("schemas/")
+schema = registry.schema("User")
+
+# JSON Schema
+json_schema = FakeDataDSL.to_json_schema(schema, registry: registry)
+
+# TypeScript
+typescript = FakeDataDSL.to_typescript(schema, registry: registry)
+typescript_all = FakeDataDSL.to_typescript_all(registry)  # All schemas
+
+# JavaScript with JSDoc
+javascript = FakeDataDSL.to_javascript(schema, registry: registry)
+javascript_all = FakeDataDSL.to_javascript_all(registry)
+
+# Python (Pydantic, dataclass, TypedDict)
+pydantic = FakeDataDSL.to_python(schema, style: :pydantic)
+dataclass = FakeDataDSL.to_python(schema, style: :dataclass)
+typed_dict = FakeDataDSL.to_python(schema, style: :typed_dict)
+python_all = FakeDataDSL.to_python_all(registry, style: :pydantic)
+
+# SQL CREATE TABLE
+sql_pg = FakeDataDSL.to_sql(schema, dialect: :postgresql)
+sql_mysql = FakeDataDSL.to_sql(schema, dialect: :mysql)
+sql_sqlite = FakeDataDSL.to_sql(schema, dialect: :sqlite)
+sql_all = FakeDataDSL.to_sql_all(registry, dialect: :postgresql)
+
+# GraphViz DOT
+dot = FakeDataDSL.to_graphviz(registry: registry)
+```
+
+### Data Exports
+
+```ruby
+# CSV (headers + data)
+csv = FakeDataDSL.to_csv(schema, count: 100, seed: 12345)
+
+# JSON data
+json = FakeDataDSL.to_json(schema, count: 100, pretty: true)
+json_envelope = FakeDataDSL.to_json(schema, count: 50, envelope: "users")
+
+# SQL INSERT statements
+sql_insert = FakeDataDSL.to_sql_insert(schema, count: 100, dialect: :postgresql)
+sql_batch = FakeDataDSL.to_sql_insert(schema, count: 1000, dialect: :mysql, batch_insert: true)
+
+# YAML
+yaml = FakeDataDSL.to_yaml(schema, count: 20, root_key: "users")
+
+# XML
+xml = FakeDataDSL.to_xml(schema, count: 10, root: "users", item: "user")
+```
+
+### Generic Export
+
+```ruby
+# Use format name string
+output = FakeDataDSL.export(:typescript, schema)
+output = FakeDataDSL.export("json-schema", schema, registry: registry)
+output = FakeDataDSL.export("sql-insert", schema, count: 100, dialect: :mysql)
+
+# List available formats
+FakeDataDSL.export_formats        # All formats
+FakeDataDSL.schema_export_formats # Schema formats only
+FakeDataDSL.data_export_formats   # Data formats only
+```
+
+### Auto-File Export
+
+```ruby
+# Export to auto-generated filename
+path = FakeDataDSL.export_to_file(:typescript, schema, output_dir: "./types")
+# => "./types/user.ts"
+
+path = FakeDataDSL.export_to_file(:python, schema, output_dir: "./models")
+# => "./models/user.py"
+
+path = FakeDataDSL.export_to_file(:csv, schema, output_dir: "./data", count: 100)
+# => "./data/user.csv"
+
+# Get filename for format
+FakeDataDSL.export_filename("User", :typescript)  # => "user.ts"
+FakeDataDSL.export_filename("User", :python)      # => "user.py"
+FakeDataDSL.export_filename("User", :csv)         # => "user.csv"
+```
+
+## CLI Commands
+
+### Schema Exports
+
+```bash
+# JSON Schema
+fake_data_dsl export User -d schemas -f json-schema -o user.schema.json
+
+# TypeScript
+fake_data_dsl export User -d schemas -f typescript -o user.ts
+fake_data_dsl export --all -d schemas -f typescript -o types.ts
+
+# JavaScript with JSDoc
+fake_data_dsl export User -d schemas -f javascript -o user.js
+fake_data_dsl export --all -d schemas -f javascript -o types.js
+
+# Python (Pydantic, dataclass, TypedDict)
+fake_data_dsl export User -d schemas -f python --style pydantic
+fake_data_dsl export User -d schemas -f python --style dataclass -o models.py
+fake_data_dsl export User -d schemas -f python --style typed_dict
+fake_data_dsl export --all -d schemas -f python -o models.py
+
+# SQL CREATE TABLE
+fake_data_dsl export User -d schemas -f sql --dialect postgresql
+fake_data_dsl export User -d schemas -f sql --dialect mysql -o user.sql
+fake_data_dsl export --all -d schemas -f sql --dialect sqlite -o schema.sql
+
+# GraphViz
+fake_data_dsl graph schemas/ -o schema.dot --render --format svg
+```
+
+### Auto-File Generation
+
+```bash
+# Auto-generate filename based on schema name and format
+fake_data_dsl export User -d schemas -f typescript --auto-file
+# Creates: user.ts
+
+# Specify output directory (auto-generates filename)
+fake_data_dsl export User -d schemas -f python --out-dir ./generated
+# Creates: ./generated/user.py
+
+fake_data_dsl export User -d schemas -f csv -c 100 --out-dir ./data
+# Creates: ./data/user.csv
+
+# Multiple exports to same directory
+fake_data_dsl export User -d schemas -f typescript --out-dir ./types
+fake_data_dsl export Order -d schemas -f typescript --out-dir ./types
+# Creates: ./types/user.ts, ./types/order.ts
+```
+
+### Data Exports
+
+```bash
+# JSON data
+fake_data_dsl export User -d schemas -f json -c 100 -o users.json
+fake_data_dsl export User -d schemas -f json -c 50 --envelope users
+fake_data_dsl export User -d schemas -f json -c 1000 --compact
+
+# CSV
+fake_data_dsl export User -d schemas -f csv -c 1000 -o users.csv
+fake_data_dsl export User -d schemas -f csv -c 100 -s 12345  # With seed
+
+# SQL INSERT
+fake_data_dsl export User -d schemas -f sql-insert -c 100 --dialect postgresql
+fake_data_dsl export User -d schemas -f sql-insert -c 1000 --dialect mysql --batch
+fake_data_dsl export User -d schemas -f insert -c 500 -o seed_data.sql
+
+# YAML
+fake_data_dsl export User -d schemas -f yaml -c 50 -o users.yaml
+
+# XML
+fake_data_dsl export User -d schemas -f xml -c 20 -o users.xml
+fake_data_dsl export User -d schemas -f xml -c 10 --root users --item user
+```
+
+## Export Options Reference
+
+### Common Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--dir DIR` | `-d` | Directory containing .dsl files |
+| `--output FILE` | `-o` | Output file (default: stdout) |
+| `--count COUNT` | `-c` | Number of records for data exports |
+| `--seed SEED` | `-s` | Seed for deterministic generation |
+| `--all` | `-a` | Export all schemas (bulk export) |
+
+### SQL Options
+
+| Option | Description |
+|--------|-------------|
+| `--dialect DIALECT` | `postgresql`, `mysql`, or `sqlite` |
+| `--batch` | Use single INSERT with multiple VALUES |
+
+### JSON Options
+
+| Option | Description |
+|--------|-------------|
+| `--compact` | Disable pretty-printing |
+| `--envelope KEY` | Wrap output in envelope with metadata |
+
+### XML Options
+
+| Option | Description |
+|--------|-------------|
+| `--root NAME` | Custom root element name |
+| `--item NAME` | Custom item element name |
+
+## Examples
+
+### Generate Test Data for API
+
+```ruby
+# Generate 1000 users as JSON for API testing
+json = FakeDataDSL.to_json(schema, count: 1000, seed: 42, envelope: "data")
+File.write("test_users.json", json)
+```
+
+### Seed Database
+
+```ruby
+# Generate SQL INSERTs for seeding PostgreSQL
+sql = FakeDataDSL.to_sql_insert(schema, count: 500, dialect: :postgresql)
+File.write("seed_users.sql", sql)
+
+# Or use batch insert for MySQL (faster)
+sql = FakeDataDSL.to_sql_insert(schema, count: 10000, dialect: :mysql, batch_insert: true)
+```
+
+### Generate TypeScript Types
+
+```ruby
+# Generate TypeScript interfaces for all schemas
+registry = FakeDataDSL::Registry.new
+registry.load_dir("schemas/")
+typescript = FakeDataDSL.to_typescript_all(registry)
+File.write("src/types/api.ts", typescript)
+```
+
+### Export for Different Environments
+
+```ruby
+# Development: JSON with pretty printing
+dev_data = FakeDataDSL.to_json(schema, count: 10, pretty: true)
+
+# Testing: Deterministic CSV
+test_data = FakeDataDSL.to_csv(schema, count: 100, seed: 12345)
+
+# Production seeding: SQL batch insert
+prod_sql = FakeDataDSL.to_sql_insert(schema, count: 10000, batch_insert: true)
+```
+