synthra 0.1.0

data/docs/PROPERTY_TESTING.md

@@ -0,0 +1,284 @@
+# Property-Based Testing
+
+FakeDataDSL integrates seamlessly with RSpec for property-based testing, allowing you to verify that properties hold for all generated data.
+
+## Quick Start
+
+```ruby
+require 'fake_data_dsl'
+include FakeDataDSL::PropertyTesting
+
+RSpec.describe "User Registration" do
+  it "accepts all valid users" do
+    verify_property("User", count: 1000) do |user_data|
+      user = User.create(user_data)
+      expect(user).to be_valid
+      expect(user.save).to be_truthy
+    end
+  end
+end
+```
+
+## Features
+
+### verify_property
+
+Verifies a property holds for multiple generated records:
+
+```ruby
+verify_property("User", count: 100) do |user_data|
+  expect(user_data["email"]).to match(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+  expect(user_data["age"]).to be_between(18, 80)
+end
+```
+
+**Options:**
+- `count` - Number of records to generate (default: 100)
+- `seed` - Random seed for reproducibility
+- `mode` - Generation mode (`:random`, `:edge`, `:invalid`, `:hostile`, `:mixed`)
+- `registry` - Custom schema registry
+
+### verify_property_stream
+
+Memory-efficient streaming verification for large counts:
+
+```ruby
+verify_property_stream("User", count: 10_000) do |user_data|
+  expect(user_data["id"]).to be_a(String)
+end
+```
+
+Records are generated lazily and garbage collected as they're processed.
+
+### shrink_counterexample
+
+Shrinks a failing test case to find a minimal counterexample:
+
+```ruby
+failing_record = schema.generate(mode: :hostile)
+
+minimal = shrink_counterexample("User", failing_record) do |record|
+  expect(record["age"]).to be > 100 # This will fail
+end
+
+# minimal contains the smallest record that still fails
+```
+
+## Examples
+
+### Email Format Validation
+
+```ruby
+verify_property("User", count: 1000) do |user_data|
+  email = user_data["email"]
+  expect(email).to match(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+end
+```
+
+### Age Range Validation
+
+```ruby
+verify_property("User", count: 1000) do |user_data|
+  age = user_data["age"]
+  expect(age).to be_between(18, 80)
+end
+```
+
+### UUID Format Validation
+
+```ruby
+verify_property("User", count: 1000) do |user_data|
+  uuid = user_data["id"]
+  expect(uuid).to match(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
+end
+```
+
+### Model Validation
+
+```ruby
+verify_property("User", count: 500) do |user_data|
+  user = User.new(user_data)
+  expect(user).to be_valid
+end
+```
+
+### API Endpoint Testing
+
+```ruby
+verify_property("Order", count: 200) do |order_data|
+  response = post("/api/orders", order_data)
+  expect(response.status).to eq(201)
+  expect(response.json["id"]).to be_present
+end
+```
+
+### Deterministic Testing
+
+```ruby
+seed = 12345
+
+verify_property("User", count: 100, seed: seed) do |user_data|
+  # Same seed = same data every time
+  expect(user_data["email"]).to eq(expected_email)
+end
+```
+
+## Error Messages
+
+When a property fails, you get detailed error information:
+
+```
+Property failed for record 42/100 (seed: 12345):
+expected 25 to be > 100
+Record: {"id"=>"550e8400...", "age"=>25, ...}
+```
+
+This includes:
+- Record index (which record failed)
+- Seed (for reproducibility)
+- Full error message
+- Complete record data
+
+## Best Practices
+
+### 1. Use Appropriate Counts
+
+```ruby
+# Quick validation (fast)
+verify_property("User", count: 10) do |user_data|
+  expect(user_data).to be_a(Hash)
+end
+
+# Comprehensive testing (thorough)
+verify_property("User", count: 1000) do |user_data|
+  expect(user_data["email"]).to match(/@/)
+end
+```
+
+### 2. Use Seeds for Reproducibility
+
+```ruby
+# Same seed = same data = reproducible tests
+verify_property("User", count: 100, seed: 42) do |user_data|
+  # Test logic
+end
+```
+
+### 3. Use Streaming for Large Counts
+
+```ruby
+# Memory-efficient for 10K+ records
+verify_property_stream("User", count: 50_000) do |user_data|
+  expect(user_data["id"]).to be_present
+end
+```
+
+### 4. Test Edge Cases
+
+```ruby
+# Test with edge case mode
+verify_property("User", count: 100, mode: :edge) do |user_data|
+  # Should handle empty strings, nulls, extremes
+  expect(user_data["email"]).to be_a(String).or(be_nil)
+end
+```
+
+### 5. Test Invalid Data Handling
+
+```ruby
+# Test validation logic
+verify_property("User", count: 100, mode: :invalid) do |user_data|
+  # Should reject invalid data
+  user = User.new(user_data)
+  expect(user).not_to be_valid
+end
+```
+
+## Integration with RSpec
+
+The `PropertyTesting` module is automatically included in RSpec when available:
+
+```ruby
+# No need to include manually
+RSpec.describe "User" do
+  it "validates all users" do
+    verify_property("User") do |user_data|
+      # Test logic
+    end
+  end
+end
+```
+
+## Advanced Usage
+
+### Custom Registry
+
+```ruby
+custom_registry = FakeDataDSL::Registry.new
+custom_registry.load_dir("spec/schemas/")
+
+verify_property("User", count: 100, registry: custom_registry) do |user_data|
+  # Test logic
+end
+```
+
+### Multiple Properties
+
+```ruby
+RSpec.describe "User" do
+  it "validates email format" do
+    verify_property("User", count: 100) do |user_data|
+      expect(user_data["email"]).to match(/@/)
+    end
+  end
+
+  it "validates age range" do
+    verify_property("User", count: 100) do |user_data|
+      expect(user_data["age"]).to be_between(18, 80)
+    end
+  end
+end
+```
+
+### Shrinking Counterexamples
+
+```ruby
+it "finds minimal failing case" do
+  failing_record = {
+    "id" => "test",
+    "name" => "Test",
+    "email" => "test@example.com",
+    "age" => 25,
+    "optional_field" => "can be removed"
+  }
+
+  minimal = shrink_counterexample("User", failing_record) do |record|
+    expect(record["age"]).to be > 100
+  end
+
+  # minimal may have optional_field removed if it still fails
+  expect(minimal["age"]).to be <= 100
+end
+```
+
+## Performance
+
+Property-based testing is efficient:
+
+- **100 records**: ~0.1s
+- **1,000 records**: ~1s
+- **10,000 records**: ~10s (use streaming)
+
+Use `verify_property_stream` for counts > 1,000 to avoid memory issues.
+
+## Limitations
+
+- Requires RSpec (automatically detected)
+- Shrinking is basic (removes optional fields, simplifies arrays)
+- No automatic property discovery (you must write properties)
+
+## See Also
+
+- [RSpec Integration Guide](tech_docs/integration/rspec.md)
+- [Generation Modes](tech_docs/modes/overview.md)
+- [API Reference](tech_docs/api/overview.md)

data/docs/PROTOBUF_EXPORT.md

@@ -0,0 +1,276 @@
+# gRPC/Protobuf Export
+
+Export your FakeDataDSL schemas to **Protocol Buffer definitions** for use with gRPC microservices.
+
+## Quick Start
+
+```bash
+# Export single schema
+fake_data_dsl export User -d schemas/ -f protobuf -o user.proto
+
+# Export all schemas
+fake_data_dsl export --all -d schemas/ -f protobuf -o all.proto
+```
+
+## Generated Output
+
+For this schema:
+
+```
+User:
+  id: uuid
+  name: name
+  email: email
+  age: number(18..65)
+  active: boolean
+  role: enum(admin, user, moderator)
+```
+
+The exporter generates:
+
+```protobuf
+syntax = "proto3";
+
+package generated;
+
+import "google/protobuf/timestamp.proto";
+
+enum UserRole {
+  USERROLE_UNSPECIFIED = 0;
+  USERROLE_ADMIN = 1;
+  USERROLE_USER = 2;
+  USERROLE_MODERATOR = 3;
+}
+
+message User {
+  string id = 1;
+  string name = 2;
+  string email = 3;
+  int64 age = 4;
+  bool active = 5;
+  UserRole role = 6;
+}
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (User);
+  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
+  rpc GenerateUser(GenerateUserRequest) returns (User);
+  rpc GenerateManyUsers(GenerateManyUsersRequest) returns (stream User);
+}
+
+message GetUserRequest {
+  string id = 1;
+}
+
+message ListUsersRequest {
+  int32 page = 1;
+  int32 page_size = 2;
+}
+
+message ListUsersResponse {
+  repeated User users = 1;
+  int32 total_count = 2;
+  int32 page = 3;
+  int32 page_size = 4;
+}
+
+message GenerateUserRequest {
+  optional int64 seed = 1;
+  optional string mode = 2;
+  map<string, string> overrides = 3;
+}
+
+message GenerateManyUsersRequest {
+  int32 count = 1;
+  optional int64 seed = 2;
+  optional string mode = 3;
+}
+```
+
+## Ruby API
+
+### Single Schema
+
+```ruby
+schema = FakeDataDSL.load("schemas/user.dsl")
+
+exporter = FakeDataDSL::Export::Protobuf.new(
+  schema,
+  registry: registry,
+  package: "myapp.v1",
+  go_package: "github.com/myapp/proto/v1",
+  with_service: true
+)
+
+proto = exporter.export
+File.write("user.proto", proto)
+```
+
+### All Schemas
+
+```ruby
+proto = FakeDataDSL::Export::Protobuf.export_all(
+  registry,
+  package: "myapp.v1",
+  go_package: "github.com/myapp/proto/v1",
+  with_service: true
+)
+
+File.write("all.proto", proto)
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `package` | Proto package name | "generated" |
+| `go_package` | Go package path | nil |
+| `syntax` | Proto syntax version | "proto3" |
+| `with_service` | Generate gRPC service | true |
+
+## Type Mapping
+
+| FakeDataDSL | Protobuf |
+|-------------|----------|
+| `text`, `name`, `email`, etc. | `string` |
+| `uuid`, `ulid`, `nanoid` | `string` |
+| `number`, `integer` | `int64` |
+| `int`, `int32` | `int32` |
+| `float`, `double`, `money` | `double` |
+| `boolean` | `bool` |
+| `timestamp`, `datetime` | `google.protobuf.Timestamp` |
+| `date`, `time` | `string` |
+| `binary`, `base64` | `bytes` |
+| `array(T)` | `repeated T` |
+| `enum(a, b, c)` | Custom enum |
+| `SchemaRef` | Message reference |
+
+## Arrays
+
+Arrays map to `repeated` fields:
+
+```
+Tags:
+  items: array(text, 1..10)
+```
+
+Becomes:
+
+```protobuf
+message Tags {
+  repeated string items = 1;
+}
+```
+
+## Nested Schemas
+
+Schema references become message references:
+
+```
+Address:
+  street: street
+  city: city
+
+Person:
+  name: name
+  address: Address
+```
+
+Becomes:
+
+```protobuf
+message Address {
+  string street = 1;
+  string city = 2;
+}
+
+message Person {
+  string name = 1;
+  Address address = 2;
+}
+```
+
+## Enums
+
+Enums are extracted and generated separately:
+
+```
+User:
+  role: enum(admin, user, moderator)
+```
+
+Becomes:
+
+```protobuf
+enum UserRole {
+  USERROLE_UNSPECIFIED = 0;  // Required zero value
+  USERROLE_ADMIN = 1;
+  USERROLE_USER = 2;
+  USERROLE_MODERATOR = 3;
+}
+
+message User {
+  UserRole role = 1;
+}
+```
+
+## Using with gRPC
+
+1. Generate the .proto file:
+   ```bash
+   fake_data_dsl export --all -d schemas/ -f protobuf -o service.proto
+   ```
+
+2. Compile to your language:
+   ```bash
+   # Go
+   protoc --go_out=. --go-grpc_out=. service.proto
+   
+   # Ruby
+   grpc_tools_ruby_protoc --ruby_out=. --grpc_out=. service.proto
+   
+   # Python
+   python -m grpc_tools.protoc --python_out=. --grpc_python_out=. service.proto
+   ```
+
+3. Implement the service using FakeDataDSL for data generation.
+
+## Example gRPC Server (Ruby)
+
+```ruby
+require 'grpc'
+require_relative 'service_services_pb'
+require 'fake_data_dsl'
+
+class DataGenerationService < Generated::DataGenerationService::Service
+  def initialize
+    @registry = FakeDataDSL::Registry.new
+    @registry.load_dir("schemas/")
+  end
+
+  def generate_user(request, _call)
+    schema = @registry.schema("User")
+    data = schema.generate(
+      seed: request.seed.zero? ? nil : request.seed,
+      mode: request.mode.empty? ? :random : request.mode.to_sym
+    )
+    
+    Generated::User.new(data)
+  end
+
+  def generate_many_users(request, _call)
+    schema = @registry.schema("User")
+    
+    return enum_for(:generate_many_users, request, _call) unless block_given?
+    
+    schema.generate_stream(count: request.count).each do |data|
+      yield Generated::User.new(data)
+    end
+  end
+end
+
+server = GRPC::RpcServer.new
+server.add_http2_port('0.0.0.0:50051', :this_port_is_insecure)
+server.handle(DataGenerationService.new)
+server.run_till_terminated
+```