Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

Rails Test Helper ⭐ NEW (Phase 2)

• generate_for_test(Model) for seamless Rails test integration
• create_for_test(Model) for persisted records
• generate_many_for_test(Model, count) for batch generation
• ActiveRecord schema inference from column types
• Location: lib/synthra/rails_test_helper.rb

Schema Mixins ⭐ NEW (Phase 2)

• @mixin directive for reusable field sets
• Pre-built mixins: Timestamps, SoftDelete, Auditable, Sluggable, Publishable
• Mixin registry with thread-safe operations
• Location: lib/synthra/mixin.rb

Data Relationships ⭐ NEW (Phase 2)

• belongs_to(Schema) - required reference
• has_one(Schema) - optional single reference
  
• has_many(Schema, 1..10) - collection reference
• Automatic cardinality handling
• Location: lib/synthra/relationships.rb

Schema Versioning ⭐ NEW (Phase 2)

• User@v2 versioned schema names
• @migrated_from User@v1 migration tracking
• Version registry with migration path finding
• Breaking change analyzer
• Location: lib/synthra/schema_versioning.rb

OpenAPI/Swagger Import ⭐ NEW (Phase 2)

• synthra import openapi.yaml --output schemas/
• Automatic type mapping from OpenAPI to DSL
• Enum, array, and reference support
• JSON and YAML format support
• Location: lib/synthra/openapi_importer.rb

Database Seeder ⭐ NEW (Phase 2)

• Synthra.seed_database { create User, count: 100 }
• Foreign key constraint awareness
• Batch insert support for performance
• Schema inference from ActiveRecord models
• Location: lib/synthra/database_seeder.rb

Live Preview Server ⭐ NEW (Phase 2)

• synthra live schemas/ --port 4567
• Beautiful web UI with real-time generation
• Hot reload on schema changes
• Multiple generation modes (random, edge, invalid, hostile)
• JSON copy-to-clipboard support
• Location: lib/synthra/live_preview.rb

Documentation Generator ⭐ NEW (Phase 2)

• synthra docs schemas/ --output docs/
• Beautiful dark-themed HTML documentation
• Sample data in both random and edge modes
• Schema statistics and field tables
• Location: lib/synthra/documentation_generator.rb

Deterministic IDs ⭐ NEW (Phase 2)

• DeterministicIds.uuid(variant: "user", index: 0)
• DeterministicIds.integer(variant: "order")
• DeterministicIds.short_id for YouTube-style IDs
• DeterministicIds.slug for URL-friendly IDs
• Batch generation support
• Location: lib/synthra/deterministic_ids.rb

New CLI Commands (Phase 2)

• synthra import - Import from OpenAPI/Swagger
• synthra docs - Generate HTML documentation
• synthra live - Start live preview server
• synthra seed - Database seeding

Rails Engine 🚂 NEW (Rails-Tier Phase)

• Zero-configuration Rails integration
• Auto-discovery of schemas from db/schemas/, app/schemas/, schemas/
• Automatic Factory Bot integration
• Test helpers (fake_data, fake_data_list, Synthra[:User])
• Auto-mount API in development at /fake_data
• Location: lib/synthra/engine.rb

ActiveRecord Inference 🔍 NEW (Rails-Tier Phase)

• Synthra::ActiveRecordInference.infer(User) - Infer schema from model
• discover_all! - Auto-discover all ActiveRecord models
• Smart type inference from column names (email, phone, url patterns)
• Validation-aware field mapping
• Association handling (belongs_to, has_many)
• Export to DSL files
• Location: lib/synthra/activerecord_inference.rb

Scenario-Based Fixtures 📸 NEW (Rails-Tier Phase)

• Define complex test data scenarios
• Synthra::Scenarios.define(:e_commerce_checkout) { ... }
• let(:user) { User(role: "admin") } fixture syntax
• Scenario inheritance with extends:
• RSpec and Minitest integration
• Reference resolution between fixtures
• Location: lib/synthra/scenarios.rb

Time Travel ⏰ NEW (Rails-Tier Phase)

• Synthra::TimeTravel.at(3.months.ago) { ... } - Generate historical data
• TimeTravel.between(start, end) - Random times in range
• TimeTravel.time_series(schema, count:, distribution:) - Generate time series
• TimeTravel.age(record, by:) - Age existing records
• TimeTravel.progression(schema, steps:, interval:) - Create data progressions
• Distributions: :uniform, :linear, :exponential, :logarithmic
• Location: lib/synthra/time_travel.rb

Personas 🎭 NEW (Rails-Tier Phase)

• Named data profiles: :happy_path, :edge_cases, :security_test
• Synthra.as(:happy_path) { generate("User") }
• Define custom personas with mode, seed, and overrides
• Trait system for reusable configurations
• Transform hooks for data modification
• YAML configuration support
• Location: lib/synthra/personas.rb

Data Quality Metrics 📊 NEW (Rails-Tier Phase)

• Synthra::QualityMetrics.analyze(records) - Analyze generated data
• Uniqueness analysis per field
• Distribution analysis for categorical data
• Completeness scoring
• Type consistency checking
• Realism score (0-100)
• Pattern detection (prefixes, suffixes, lengths)
• Anomaly detection (duplicates, skewed distributions)
• Location: lib/synthra/quality_metrics.rb

GraphQL Federation Export 🔗 NEW (Rails-Tier Phase)

• synthra export --all -f graphql-federation -o schema.graphql
• Apollo Federation v2 compatible SDL
• @key, @shareable, @external, @provides directives
• Connection types with pagination (Relay-style)
• Query, Mutation, and Subscription types
• Input types for each schema
• Generation mode enum
• Location: lib/synthra/export/graphql_federation.rb

Webhook Simulation 🎬 NEW (Rails-Tier Phase)

• Synthra::WebhookSimulator.send("event.type", data: {...})
• Pre-built Stripe webhooks (payment_succeeded, subscription_created)
• Pre-built GitHub webhooks (push, pull_request)
• Template system for reusable webhooks
• Signature generation (Stripe-compatible)
• Async and delayed delivery
• Sequence support for multi-step flows
• Location: lib/synthra/webhook_simulator.rb

Schema Migration Generator 🧬 NEW (Rails-Tier Phase)

• Synthra::MigrationGenerator.create_table(schema)
• MigrationGenerator.generate(from: "User@v1", to: "User@v2")
• Generates Rails 7.1 compatible migrations
• Detects added, removed, and changed fields
• Type mapping to ActiveRecord column types
• Nullable field handling
• Location: lib/synthra/migration_generator.rb

Terraform/IaC Export 🏗️ NEW (Rails-Tier Phase)

• synthra export --all -f terraform -o main.tf
• AWS DynamoDB table generation
• AWS RDS PostgreSQL with SQL schema
• AWS S3 bucket with encryption
• GCP provider support
• HCL and JSON output formats
• Global Secondary Indexes for indexed fields
• Location: lib/synthra/export/terraform.rb

GitHub Action 🤖 NEW (Rails-Tier Phase)

• Composite action for CI/CD integration
• Schema validation in pull requests
• Breaking change detection
• Export generation (TypeScript, JSON Schema, etc.)
• Artifact upload for generated files
• Location: .github/actions/fake-data-dsl/action.yml

Production API Server 🔥 NEW (Production Phase)

• synthra server schemas/ --port 3000 - Start REST API server
• Full REST API for data generation (GET /api/:schema, /api/:schema/batch, /api/:schema/stream)
• API key and bearer token authentication
• Rate limiting with configurable limits per minute
• CORS support with customizable headers
• Metrics endpoint for monitoring
• Rack-compatible for deployment with Puma/Unicorn
• Location: lib/synthra/api_server.rb

gRPC/Protobuf Export 🔥 NEW (Production Phase)

• synthra export User -f protobuf -o user.proto
• Generate .proto files from DSL schemas
• Automatic service definition generation
• Enum extraction and mapping
• export_all for combined proto file
• Custom package and go_package options
• Location: lib/synthra/export/protobuf.rb

OpenAPI Export 🔥 NEW (Production Phase)

• synthra export --all -f openapi -o api.yaml
• Generate OpenAPI 3.0 specifications
• Complete endpoint documentation
• Request/response schema generation
• YAML and JSON output formats
• Custom title, version, and server URL
• Location: lib/synthra/export/openapi.rb

Mock Server with Recording 🔥 NEW (Production Phase)

• Synthra::MockServer.start(schema_dir: "schemas/", recording: true)
• Record real API responses for replay
• Persistent recording storage
• Rate limiting support
• Behavior simulation (latency, failures)
• Location: lib/synthra/mock_server.rb

Data Contracts Registry 🔥 NEW (Production Phase)

• synthra contracts publish User -v 1.0.0
• Semantic versioning support
• Publish, deprecate, and retire contracts
• Compatibility checking between versions
• Breaking change detection
• History tracking with timestamps
• Location: lib/synthra/contracts_registry.rb

Performance Mode 🔥 NEW (Production Phase)

• synthra perf User -c 1000000 -o users.ndjson
• Generate millions of records with parallel processing
• Progress callbacks with ETA
• File streaming (NDJSON, JSON, CSV)
• Benchmark mode for performance testing
• System capability detection
• Location: lib/synthra/performance_mode.rb

New CLI Commands (Production Phase)

• synthra server - Start production API server
• synthra contracts - Manage data contracts registry
• synthra perf - High-performance generation mode

GraphQL Schema Export ⭐ NEW

• Export schemas to GraphQL SDL (Schema Definition Language)
• Automatic Query type generation with pagination
• Enum type extraction and mapping
• Full registry export support with export_all
• Location: lib/synthra/export/graphql.rb

Config File Support ⭐ NEW

• YAML configuration file support (config/synthra.yml)
• Environment-specific configuration (development, test, production)
• Auto-loading from standard locations
• Rails-like convention over configuration
• Location: lib/synthra/config_file.rb

Factory Bot Integration ⭐ NEW

• Bridge between Synthra and Factory Bot
• Synthra.define_factory(:user, schema: "User") syntax
• Trait support for different data variations
• RSpec helpers: fake_data_build, build_fake_data
• Location: lib/synthra/factory_bot_integration.rb

Schema Inheritance ⭐ NEW

• Schema inheritance with < operator
• AdminUser < BaseUser: syntax support
• Child fields override parent fields
• Reduces schema duplication
• Location: lib/synthra/schema_inheritance.rb

Breaking Changes Diff for CI ⭐ NEW

• synthra diff schemas/v1/ schemas/v2/ --breaking-only
• Detects: removed schemas, removed fields, type changes
• Perfect for CI pipelines to block breaking PRs
• Exit code 1 on breaking changes
• Location: lib/synthra/cli/commands/diff.rb

Snapshot Testing Integration ⭐ NEW

• expect_snapshot(schema, seed: 42) for RSpec
• match_snapshot("User") custom matcher
• generate_all_snapshots for bulk operations
• Deterministic seed-based comparisons
• Location: lib/synthra/snapshot_testing.rb

Shared Type Mapping ⭐ NEW

• Centralized type mapping module for all exporters
• Consistent JSON Schema, TypeScript, Python, and SQL mappings
• Reduces code duplication across export modules
• Location: lib/synthra/export/type_mapping.rb

Changed

Architecture Improvements

• Refactored main lib file from ~1000 to ~140 lines
• Split into api.rb (public API) and type_definitions.rb (type registrations)
• CLI command pattern with individual command classes
• Optimized Generator::Engine hot path with cached observability check
• Added observability_enabled? method to Configuration

CLI Command Pattern

• Base command class: lib/synthra/cli/commands/base.rb
• Individual commands: validate.rb, lint.rb, generate.rb, export.rb, diff.rb
• Each command is focused, testable, and maintainable

LSP Server

• Full Language Server Protocol (LSP) implementation for IDE integration
• Go-to-definition support for schema references
• Hover information with type details and documentation
• Auto-completion for schema names, types, and field names
• Real-time diagnostics and validation
• Location: lib/synthra/lsp/server.rb
• Documentation: docs/LSP.md

Property-Based Testing

• RSpec integration for property-based testing with Synthra schemas
• verify_property helper for verifying properties across multiple generated records
• verify_property_stream for memory-efficient testing with large datasets
• shrink_counterexample for finding minimal failing test cases
• Automatic seed tracking for reproducible test failures
• Location: lib/synthra/property_testing.rb
• Documentation: docs/PROPERTY_TESTING.md

Enhanced REPL

• Visual data inspection with table command (tabular format)
• Step-through debugging with debug command (field-by-field generation)
• Detailed inspection with inspect command (context state, generated fields)
• Better formatting for hashes, arrays, and nested structures
• NEW: Command aliases (t, d, i, g, l, h, q)
• NEW: Readline-based command history with arrow key navigation
• NEW: Tab completion for commands and schema names
• NEW: Export to file support (gen User 100 > users.json)
• NEW: "Did you mean" suggestions for typos
• NEW: Enhanced debug context showing all previously generated fields
• Location: lib/synthra/repl/formatter.rb, lib/synthra/repl/enhanced_repl.rb
• Documentation: docs/ENHANCED_REPL.md

Security Fuzzing (Hostile Mode)

• New :hostile generation mode for security testing
• SQL injection payloads
• XSS (Cross-Site Scripting) attack vectors
• Buffer overflow payloads
• Unicode attack strings
• Comprehensive hostile payload library
• Location: lib/synthra/generator/modes.rb, lib/synthra/types/hostile_payloads.rb
• Documentation: docs/SECURITY_TESTING.md

Documentation

• Comprehensive YARD documentation generation
• Rake tasks for documentation (rake docs, rake docs_server)
• Full API documentation with examples
• Contributing guidelines (CONTRIBUTING.md)
• Code of Conduct (CODE_OF_CONDUCT.md)
• Strategic planning documents for SIMD optimization and Cloud Registry

Integration Tests

• Comprehensive integration tests for enhanced features
• End-to-end REPL workflow tests
• Property testing integration tests
• LSP server hover and documentation tests
• Debug engine callback tests
• Location: spec/integration/enhanced_features_spec.rb

Performance Tests

• Comprehensive performance benchmarks
• Generation throughput tests (simple and complex schemas)
• Streaming performance tests (10,000+ records)
• REPL formatter performance tests
• Property testing performance tests
• LSP server response time tests
• Location: spec/synthra/performance_spec.rb

Changed

• Enhanced README with detailed examples and troubleshooting
• Improved documentation coverage across all modules
• Updated test coverage to 94.57% line, 79.05% branch

Fixed

• Property testing tests now properly pass registry parameter
• REPL DebugEngine callback signature matches engine's 4-argument format
• RSpec integration test uses correct method for checking module inclusion

[0.1.0] - 2024-01-01

Added

• Initial release - Full-featured fake data generation DSL

• Custom DSL Parser - Indentation-based syntax similar to YAML

  • Lexer for tokenizing DSL input
  • Recursive descent parser
  • Abstract Syntax Tree (AST) representation
  • Support for multiple schemas per file

• Core Data Types:

  • uuid - UUID v4, v6, and v7 support with uniqueness constraints
  • ulid - Time-sortable ULID identifiers
  • id_sequence - Auto-incrementing sequential IDs
  • name - Full names using Faker
  • email - Email addresses
  • text - Random text with configurable length ranges
  • number - Integers and floats with min/max ranges
  • boolean - True/false with probability support
  • enum - Value selection with weighted probabilities
  • date - Random dates
  • past_date - Dates in the past with time ranges (d/m/y)
  • future_date - Dates in the future with time ranges
  • now - Current timestamp
  • timestamp - DateTime values

• Extended Data Types:

  • phone - Phone numbers with locale support
  • url - URLs
  • ip - IPv4 addresses
  • ipv6 - IPv6 addresses
  • country_code - ISO 3166-1 alpha-2 country codes (using Faker)
  • currency - ISO 4217 currency codes (using Faker)
  • postal_code - Postal/ZIP codes with country-specific formats (using Faker)
  • money - Money amounts with currency (using Faker for currency)
  • locale - Locale codes

• Complex Types:

  • array - Arrays of values or nested schemas with size constraints
  • object - Nested object structures
  • reference - Cross-schema field references with Ref(Schema.field) syntax
  • custom - Computed fields using registered functions

• Field Modifiers:

  • Optional fields with ? suffix (e.g., email?: email)
  • Nullable types with ? prefix (e.g., bio: text?)
  • Combined optional and nullable (e.g., phone?: phone?)
  • Conditional fields with if syntax

• Behaviors - Simulation behaviors for testing:

  • @latency - Add artificial delays (schema or field level)
  • @failure - Simulate failures with probability
  • @partial_data - Remove random fields with probability
  • @close_connection - Simulate connection drops
  • @simulate_error - Return HTTP error codes
  • @randomize_order - Shuffle array field order

• Generation Modes:

  • :random - Standard realistic data (default)
  • :edge - Boundary values and edge cases
  • :invalid - Invalid data for validation testing
  • :mixed - Combination of all modes (80% random, 15% edge, 5% invalid)

• Advanced Features:

  • Cross-schema references with automatic resolution
  • Computed fields with custom functions
  • Conditional field generation
  • Uniqueness constraints with configurable scopes
  • Deterministic generation with seed support
  • Thread-safe random number generation
  • Streaming generation for large datasets (memory-efficient)
  • Resource limits (max latency, recursion depth, array size)
  • Schema registry for multi-schema projects
  • Circular dependency detection

• CLI Tool (synthra):

  • validate command - Validate DSL schema files
  • generate command - Generate data from schemas
  • Support for pretty JSON, NDJSON, and CSV output formats
  • Seed support for reproducible generation
  • Generation mode selection

• Output Formatters:

  • JSON formatter with pretty printing
  • NDJSON (newline-delimited JSON) for streaming
  • File writing support

• Error Handling:

  • Custom error classes for different failure scenarios
  • Detailed error messages with context
  • Graceful handling of uniqueness constraint failures

• Configuration:

  • Global configuration system
  • Resource limits configuration
  • Default generation mode
  • Behavior enable/disable

• Extensibility:

  • Custom type registration
  • Custom function registration
  • Custom behavior registration
  • Plugin architecture

• Testing:

  • Comprehensive RSpec test suite
  • 100% code coverage
  • Integration tests
  • Shared examples and custom matchers

• Documentation:

  • Comprehensive README with examples
  • YARD documentation for all public APIs
  • Contributing guidelines
  • Code of Conduct