synthra 0.1.0

data/docs/DATA_CONTRACTS.md

@@ -0,0 +1,312 @@
+# Data Contracts Registry
+
+Version, publish, and manage your schemas centrally with the **Data Contracts Registry**.
+
+## Quick Start
+
+```bash
+# Publish a schema version
+fake_data_dsl contracts publish User -v 1.0.0 -s schemas/ -m "Initial release"
+
+# List all contracts
+fake_data_dsl contracts list
+
+# Check compatibility
+fake_data_dsl contracts diff User 1.0.0 2.0.0
+```
+
+## CLI Commands
+
+### Publish
+
+```bash
+fake_data_dsl contracts publish <Schema> -v <version> [options]
+
+Options:
+  -s, --schema-dir DIR   Schema directory
+  -m, --message MSG      Changelog message
+  -d, --dir DIR          Contracts directory (default: contracts)
+```
+
+Example:
+```bash
+fake_data_dsl contracts publish User -v 1.0.0 -s schemas/ -m "Initial User schema"
+```
+
+### Deprecate
+
+```bash
+fake_data_dsl contracts deprecate <Schema> -v <version> [options]
+
+Options:
+  --sunset DATE          Sunset date (YYYY-MM-DD)
+  -m, --message MSG      Deprecation message
+```
+
+Example:
+```bash
+fake_data_dsl contracts deprecate User -v 1.0.0 --sunset 2026-06-01 -m "Use v2.0.0 instead"
+```
+
+### List
+
+```bash
+fake_data_dsl contracts list
+```
+
+Output:
+```
+Data Contracts:
+
+  User:
+    ✅ v2.0.0 (5 fields)
+    ⚠️ v1.0.0 (3 fields)
+  
+  Order:
+    ✅ v1.0.0 (8 fields)
+```
+
+### History
+
+```bash
+fake_data_dsl contracts history User
+```
+
+Output:
+```
+History for User:
+
+  2026-01-24T10:30:00Z - v2.0.0 published
+    Added avatar field, changed email validation
+  2026-01-01T09:00:00Z - v1.0.0 deprecated
+    Use v2.0.0 instead
+  2025-06-15T14:00:00Z - v1.0.0 published
+    Initial release
+```
+
+### Diff
+
+```bash
+fake_data_dsl contracts diff User 1.0.0 2.0.0
+```
+
+Output:
+```
+Comparing User v1.0.0 → v2.0.0
+
+❌ Breaking changes detected!
+
+Changes:
+  Removed: legacy_field
+  Added: avatar, updated_at
+  Type changed: age (text → number)
+```
+
+## Ruby API
+
+### Initialize Registry
+
+```ruby
+# Create registry with storage directory
+registry = FakeDataDSL::ContractsRegistry.new("contracts/")
+```
+
+### Publish
+
+```ruby
+schema = FakeDataDSL.load("schemas/user.dsl")
+
+contract = registry.publish(
+  "User",
+  version: "1.0.0",
+  schema: schema,
+  changelog: "Initial release"
+)
+
+puts contract[:schema_hash]  # Content hash for integrity
+puts contract[:fields]       # Field signatures
+```
+
+### Deprecate
+
+```ruby
+registry.deprecate(
+  "User",
+  version: "1.0.0",
+  sunset_date: Date.new(2026, 6, 1),
+  message: "Migrate to v2.0.0"
+)
+```
+
+### Retire
+
+```ruby
+registry.retire("User", version: "1.0.0")
+```
+
+### Get Contract
+
+```ruby
+# Get specific version
+contract = registry.get("User", version: "1.0.0")
+
+# Get latest published version
+latest = registry.get("User")  # Returns newest published
+```
+
+### List Versions
+
+```ruby
+versions = registry.versions_for("User")
+# => ["1.0.0", "1.1.0", "2.0.0"]
+```
+
+### Check Compatibility
+
+```ruby
+result = registry.compatible?("User", "1.0.0", "2.0.0")
+
+if result[:breaking]
+  puts "Breaking changes detected!"
+  puts "Removed fields: #{result[:changes][:removed_fields]}"
+  puts "Type changes: #{result[:changes][:type_changes]}"
+else
+  puts "Compatible!"
+end
+```
+
+Compatibility result:
+```ruby
+{
+  compatible: false,
+  breaking: true,
+  changes: {
+    removed_fields: ["legacy_field"],
+    added_fields: ["avatar", "updated_at"],
+    type_changes: [{ field: "age", from: "text", to: "number" }],
+    required_changes: [{ field: "email", change: "optional → required" }]
+  },
+  summary: "Removed fields: legacy_field; Type changed: age (text → number)"
+}
+```
+
+### Validate Against Contract
+
+```ruby
+current_schema = FakeDataDSL.load("schemas/user.dsl")
+
+result = registry.validate("User", version: "1.0.0", schema: current_schema)
+
+if result[:valid]
+  puts "Schema matches contract!"
+else
+  puts "Schema drift detected!"
+  puts "Missing: #{result[:missing_fields]}"
+  puts "Extra: #{result[:extra_fields]}"
+end
+```
+
+### History
+
+```ruby
+history = registry.history("User")
+
+history.each do |entry|
+  puts "#{entry[:timestamp]} - v#{entry[:version]} #{entry[:action]}"
+  puts "  #{entry[:message]}" if entry[:message]
+end
+```
+
+### Export/Import
+
+```ruby
+# Export all contracts to directory
+registry.export("exported_contracts/")
+
+# Import contracts from directory
+registry.import("imported_contracts/")
+```
+
+## Contract States
+
+| State | Description |
+|-------|-------------|
+| `draft` | Not yet published |
+| `published` | Active and available |
+| `deprecated` | Scheduled for removal |
+| `retired` | No longer available |
+
+## Breaking Changes
+
+The following changes are considered **breaking**:
+
+| Change | Breaking? | Description |
+|--------|-----------|-------------|
+| Field removed | ✅ Yes | Consumers depend on this field |
+| Type changed | ✅ Yes | `number` → `text` breaks parsing |
+| Optional → Required | ✅ Yes | Consumers may not provide |
+| Field added | ❌ No | Backwards compatible |
+| Required → Optional | ❌ No | Backwards compatible |
+
+## CI Integration
+
+Use contracts in CI pipelines:
+
+```yaml
+# .github/workflows/schema-check.yml
+name: Schema Validation
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+      
+      - name: Check for breaking changes
+        run: |
+          # Publish current schema
+          bundle exec fake_data_dsl contracts publish User \
+            -v ${{ github.sha }} \
+            -s schemas/
+          
+          # Compare with main branch
+          bundle exec fake_data_dsl contracts diff User main ${{ github.sha }}
+```
+
+## Storage Format
+
+Contracts are stored as JSON files:
+
+```
+contracts/
+├── schemas/
+│   ├── User_v1.0.0.json
+│   ├── User_v2.0.0.json
+│   └── Order_v1.0.0.json
+└── history/
+    ├── User.json
+    └── Order.json
+```
+
+Contract file structure:
+```json
+{
+  "name": "User",
+  "version": "1.0.0",
+  "state": "published",
+  "schema_hash": "abc123def456",
+  "fields": [
+    { "name": "id", "type": "uuid", "optional": false, "nullable": false }
+  ],
+  "published_at": "2026-01-24T10:30:00Z",
+  "changelog": "Initial release"
+}
+```

data/docs/ENHANCED_REPL.md

@@ -0,0 +1,304 @@
+# Enhanced REPL
+
+The FakeDataDSL REPL now includes visual inspection, step-through debugging, and table formatting.
+
+## Quick Start
+
+```bash
+fake_data_dsl repl
+```
+
+## Commands
+
+### Basic Commands
+
+- `load <path>` - Load schemas from file/directory
+- `list` - List loaded schemas
+- `info <Schema>` - Show schema details
+- `gen <Schema>` - Generate one record (JSON format)
+- `gen <Schema> N` - Generate N records (JSON format)
+- `seed <number>` - Set seed for deterministic output
+- `mode <mode>` - Set mode (random/edge/invalid/hostile/mixed)
+- `help` - Show help
+- `quit` / `exit` - Exit REPL
+
+### Enhanced Commands
+
+- `table <Schema>` - Generate one record (table view)
+- `table <Schema> N` - Generate N records (table view)
+- `debug <Schema>` - Step-through debugging
+- `inspect <Schema>` - Detailed inspection (table + JSON + statistics)
+
+## Table View
+
+Display records in a formatted table:
+
+```bash
+> table User
+  ────────────────────┼───────────────────────────────
+  id                  │ "550e8400-e29b-41d4-a716-..."
+  name                │ "John Doe"
+  email               │ "john.doe@example.com"
+  age                 │ 34
+```
+
+For multiple records:
+
+```bash
+> table User 5
+  id                  │ name                │ email
+  ────────────────────┼─────────────────────┼─────────────────────
+  550e8400...         │ John Doe            │ john@example.com
+  f47ac10b...         │ Jane Smith          │ jane@example.com
+  ...
+```
+
+## Step-Through Debugging
+
+Debug generation field-by-field:
+
+```bash
+> debug User
+🐛 Debug Mode: Generating User
+Press Enter to continue after each field, 'q' to quit, 'c' to continue without pausing
+
+[Field 1] id
+────────────────────────────────────────────────────────
+Value: "550e8400-e29b-41d4-a716-446655440000"
+
+Context State:
+  Depth: 0
+  Registry: available
+  Parent Context: no
+  Shared Context: none
+
+Generated Fields:
+  (none yet)
+
+Press Enter to continue, 'q' to quit, 'c' to continue without pausing: 
+
+[Field 2] name
+────────────────────────────────────────────────────────
+Value: "John Doe"
+
+Context State:
+  Depth: 0
+  Registry: available
+  Parent Context: no
+  Shared Context: none
+
+Generated Fields:
+  id                  = "550e8400-e29b-41d4-a716-446655440000"
+
+Press Enter to continue, 'q' to quit, 'c' to continue without pausing: c
+Continuing without pausing...
+```
+
+### Debug Controls
+
+- **Enter** - Continue to next field
+- **q** / **quit** - Cancel debugging
+- **c** / **continue** - Continue without pausing
+
+## Detailed Inspection
+
+Get comprehensive information about generated records:
+
+```bash
+> inspect User
+📊 Generated Record:
+============================================================
+  ────────────────────┼───────────────────────────────
+  id                  │ "550e8400-e29b-41d4-a716-..."
+  name                │ "John Doe"
+  email               │ "john.doe@example.com"
+  age                 │ 34
+  created_at          │ "2024-01-15T10:30:00Z"
+
+📋 JSON Format:
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "John Doe",
+  "email": "john.doe@example.com",
+  "age": 34,
+  "created_at": "2024-01-15T10:30:00Z"
+}
+
+📏 Statistics:
+  Fields: 5
+  Total size: 234 bytes
+    id: String (36)
+    name: String (8)
+    email: String (20)
+    age: Integer (2)
+    created_at: String (20)
+```
+
+## Examples
+
+### Loading Schemas
+
+```bash
+> load schemas/
+✅ Loaded 3 schema(s)
+
+> list
+Loaded schemas:
+  - User v1.0
+  - Order v2.3
+  - Product
+```
+
+### Generating Data
+
+```bash
+> gen User
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "John Doe",
+  "email": "john.doe@example.com"
+}
+
+> gen User 5
+[
+  { "id": "...", "name": "John Doe", ... },
+  { "id": "...", "name": "Jane Smith", ... },
+  ...
+]
+```
+
+### Using Seeds
+
+```bash
+> seed 42
+✅ Seed set to 42
+
+> gen User
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  ...
+}
+
+> gen User  # Same seed = same output
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  ...
+}
+```
+
+### Changing Modes
+
+```bash
+> mode edge
+✅ Mode set to edge
+
+> gen User
+{
+  "id": "00000000-0000-0000-0000-000000000000",
+  "name": "",
+  "email": ""
+}
+
+> mode hostile
+✅ Mode set to hostile
+
+> gen User
+{
+  "id": "' OR '1'='1",
+  "name": "<script>alert(1)</script>",
+  "email": "'; DROP TABLE users;--"
+}
+```
+
+## Use Cases
+
+### Debugging Complex Schemas
+
+Use `debug` to understand how complex schemas with `copy()` and `Ref()` work:
+
+```bash
+> debug Order
+# Step through each field to see context state
+# Understand how copy() resolves parent fields
+# See how Ref() resolves cross-schema references
+```
+
+### Quick Data Inspection
+
+Use `table` for quick visual inspection:
+
+```bash
+> table User 10
+# See 10 users in a clean table format
+# Easier to scan than JSON
+```
+
+### Schema Exploration
+
+Use `inspect` to understand schema output:
+
+```bash
+> inspect User
+# See table + JSON + statistics
+# Understand field types and sizes
+# Verify schema structure
+```
+
+## Tips
+
+1. **Use seeds for reproducibility** - Set a seed to get consistent output
+2. **Use table view for quick checks** - Faster than JSON for visual inspection
+3. **Use debug for complex schemas** - Understand field dependencies
+4. **Use inspect for analysis** - Get comprehensive information
+
+## Keyboard Shortcuts
+
+- **Ctrl+C** - Interrupt current operation
+- **Ctrl+D** - Exit REPL (same as `quit`)
+
+## Configuration
+
+The REPL respects global configuration:
+
+```ruby
+FakeDataDSL.configure do |config|
+  config.default_mode = :edge
+  config.limits.max_array_size = 100
+end
+```
+
+## Troubleshooting
+
+### No Output
+
+Check that schemas are loaded:
+
+```bash
+> list
+No schemas loaded. Use 'load <path>' first.
+```
+
+### Schema Not Found
+
+Verify schema name:
+
+```bash
+> list
+Loaded schemas:
+  - User
+  - Order
+
+> gen User  # Correct
+> gen user  # Wrong (case-sensitive)
+❌ Schema 'user' not found
+```
+
+### Debug Mode Not Working
+
+Ensure `on_field_generated` callback is available (it's built-in, should work automatically).
+
+## See Also
+
+- [CLI Guide](tech_example/04_cli_usage.md)
+- [Generation Modes](tech_docs/modes/overview.md)
+- [Schema Reference](tech_docs/dsl/schema_definition.md)