synthra 0.1.0

data/lib/synthra/generator/rng.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Random Number Generator (RNG)
+# =============================================================================
+#
+# Thread-safe seeded random number generator for deterministic fake data
+# generation. When the same seed is used, the RNG produces identical
+# sequences of random numbers, enabling reproducible test data.
+#
+# @example Deterministic generation
+#   rng1 = RNG.new(12345)
+#   rng2 = RNG.new(12345)
+#   rng1.int(1, 100) == rng2.int(1, 100)  # => true
+#
+# @example Thread-safe usage
+#   rng = RNG.new(42)
+#   threads = 10.times.map { Thread.new { rng.int(1, 100) } }
+#   threads.each(&:join)  # Safe - mutex protects internal state
+#
+# =============================================================================
+
+
+module Synthra
+  module Generator
+
+    # Thread-safe seeded random number generator
+    #
+    # Provides deterministic random number generation using Ruby's Random
+    # class with mutex protection for thread safety. All type generators
+    # use this RNG to ensure reproducible output.
+    #
+    # @example Basic usage
+    #   rng = RNG.new(12345)
+    #   rng.int(1, 100)   # => 42 (always same with seed 12345)
+    #   rng.boolean(0.7)  # => true/false with 70% true probability
+    #
+
+    class RNG
+
+      # @!attribute [r] seed
+      #   The seed value used for this RNG
+      #   @return [Integer] the seed
+
+      attr_reader :seed
+
+
+      # Create a new RNG instance
+      #
+      # @param seed [Integer, nil] seed for determinism (nil for random seed)
+      #
+      # @example With seed
+      #   rng = RNG.new(12345)  # Deterministic
+      #
+      # @example Without seed
+      #   rng = RNG.new  # Random seed
+      #
+
+      def initialize(seed = nil)
+        @seed = seed || Random.new_seed
+        @random = Random.new(@seed)
+        @mutex = Mutex.new
+      end
+
+
+      # Generate a random number
+      #
+      # Flexible random number generation supporting multiple argument types.
+      #
+      # @param max [Integer, Range, nil] max value, range, or nil for 0.0-1.0 float
+      # @return [Integer, Float] random number
+      #
+      # @example No argument (0.0 to 1.0)
+      #   rng.rand  # => 0.7342...
+      #
+      # @example With max (0 to max-1)
+      #   rng.rand(100)  # => 42
+      #
+      # @example With range
+      #   rng.rand(1..10)  # => 7
+      #
+
+      def rand(max = nil)
+        @mutex.synchronize do
+          case max
+          when nil
+            @random.rand
+          when Range
+            @random.rand(max)
+          else
+            @random.rand(max)
+          end
+        end
+      end
+
+
+      # Generate a random number in a range (alias)
+      #
+      # @param range [Range] the range
+      # @return [Numeric] random number in range
+      #
+
+      def rand_range(range)
+        rand(range)
+      end
+
+
+      # Pick a random element from an array
+      #
+      # @param array [Array] the array to sample from
+      # @return [Object, nil] random element or nil if empty
+      #
+      # @example
+      #   rng.sample(["a", "b", "c"])  # => "b"
+      #
+
+      def sample(array)
+        return nil if array.empty?
+
+        @mutex.synchronize do
+          array.sample(random: @random)
+        end
+      end
+
+
+      # Sample multiple elements from an array
+      #
+      # @param array [Array] the array to sample from
+      # @param count [Integer] number of elements to sample
+      # @return [Array] sampled elements
+      #
+      # @example
+      #   rng.sample_many(["a", "b", "c", "d"], 2)  # => ["c", "a"]
+      #
+
+      def sample_many(array, count)
+        @mutex.synchronize do
+          array.sample(count, random: @random)
+        end
+      end
+
+
+      # Shuffle an array
+      #
+      # Returns a new shuffled array; does not modify original.
+      #
+      # @param array [Array] the array to shuffle
+      # @return [Array] shuffled copy
+      #
+      # @example
+      #   rng.shuffle([1, 2, 3, 4])  # => [3, 1, 4, 2]
+      #
+
+      def shuffle(array)
+        @mutex.synchronize do
+          array.shuffle(random: @random)
+        end
+      end
+
+
+      # Generate a random boolean
+      #
+      # @param true_probability [Float] probability of true (0.0 to 1.0)
+      # @return [Boolean] random boolean
+      #
+      # @example 50/50 chance
+      #   rng.boolean  # => true or false
+      #
+      # @example 70% true
+      #   rng.boolean(0.7)  # => true (70% of the time)
+      #
+
+      def boolean(true_probability = 0.5)
+        rand < true_probability
+      end
+
+
+      # Select based on weighted probabilities
+      #
+      # @param options [Hash] mapping of values to weights (any positive numbers)
+      # @return [Object, nil] selected value based on weights
+      #
+      # @example
+      #   rng.weighted_choice({ "common" => 80, "rare" => 20 })
+      #   # => "common" (80% chance) or "rare" (20% chance)
+      #
+
+      def weighted_choice(options)
+        return nil if options.empty?
+
+        total = options.values.sum.to_f
+        target = rand * total
+        cumulative = 0.0
+
+        options.each do |value, weight|
+          cumulative += weight
+          return value if target <= cumulative
+        end
+
+
+        # Fallback (shouldn't happen but handles float precision)
+        options.keys.last
+      end
+
+
+      # Generate a random integer in inclusive range
+      #
+      # @param min [Integer] minimum value (inclusive)
+      # @param max [Integer] maximum value (inclusive)
+      # @return [Integer] random integer
+      #
+      # @example
+      #   rng.int(1, 10)  # => 7 (between 1 and 10 inclusive)
+      #
+
+      def int(min, max)
+        rand(min..max)
+      end
+
+
+      # Generate a random float in range
+      #
+      # @param min [Float] minimum value
+      # @param max [Float] maximum value
+      # @return [Float] random float
+      #
+      # @example
+      #   rng.float(0.0, 1.0)  # => 0.7342...
+      #
+
+      def float(min, max)
+        min + rand * (max - min)
+      end
+
+
+      # Create a duplicate RNG with the same seed
+      #
+      # Creates a new RNG that will produce the same sequence.
+      #
+      # @return [RNG] new RNG with same seed
+      #
+      # @example
+      #   rng2 = rng.dup
+      #   rng2.int(1, 100) == rng.int(1, 100)  # Both start fresh
+      #
+
+      def dup
+        self.class.new(@seed)
+      end
+
+
+      # Reset the RNG to initial state
+      #
+      # Re-initializes the internal random generator to start sequence over.
+      #
+      # @return [void]
+      #
+      # @example
+      #   rng.int(1, 100)  # => 42
+      #   rng.int(1, 100)  # => 73
+      #   rng.reset!
+      #   rng.int(1, 100)  # => 42 (back to start)
+      #
+
+      def reset!
+        @mutex.synchronize do
+          @random = Random.new(@seed)
+        end
+      end
+    end
+  end
+end

data/lib/synthra/generator/streamer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Synthra
+  module Generator
+
+    # Streaming generator for large batches
+    class Streamer
+      def initialize(schema, registry: nil, **options)
+        @schema = schema
+        @registry = registry
+        @options = options
+      end
+
+
+      # Generate records as a stream
+      #
+      # Returns an Enumerator that generates records on-demand. The Engine
+      # instance is reused across all records in the stream for efficiency.
+      #
+      # @param count [Integer] number of records
+      # @return [Enumerator] lazy enumerator of records
+      #
+      # @example Stream processing
+      #   streamer = Streamer.new(schema, seed: 42)
+      #   streamer.generate_stream(count: 1000).each do |record|
+      #     process(record)  # Records generated one at a time
+      #   end
+      #
+
+      def generate_stream(count:)
+        seed = @options[:seed]
+        mode = @options[:mode] || :random
+        overrides = @options[:overrides] || {}
+
+        Enumerator.new(count) do |yielder|
+
+          # Reuse single Engine instance for efficiency
+          engine = Engine.new(@schema, registry: @registry)
+          
+
+          # Initialize RNG once with seed if provided
+          # This ensures deterministic streaming - all records use the same RNG sequence
+          if seed
+
+            # Initialize RNG and FakerAdapter without generating a record
+            rng = Synthra::Generator::RNG.new(seed)
+            engine.instance_variable_set(:@rng, rng)
+            engine.instance_variable_set(:@faker_adapter, 
+              Synthra::Generator::FakerAdapter.new(rng))
+          end
+          
+          count.times do
+
+            # Continue RNG sequence without resetting (seed: nil)
+            record = engine.generate(seed: nil, mode: mode, overrides: overrides)
+            yielder << record
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/synthra/generator/uniqueness.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Synthra
+  module Generator
+
+    # Tracks unique values for uniqueness constraints
+    class Uniqueness
+      def initialize(max_retries: nil, schema_name: nil)
+        @max_retries = max_retries || Synthra.configuration.max_unique_retries
+        @schema_name = schema_name
+        @values = Hash.new { |h, k| h[k] = Set.new }
+        @mutex = Mutex.new
+      end
+
+
+      # Track a generated value
+      #
+      # @param field [String] field name
+      # @param value [Object] generated value
+      # @return [void]
+
+      def track(field, value)
+        @mutex.synchronize do
+          @values[field.to_s].add(value)
+        end
+      end
+
+
+      # Check if a value is unique for a field
+      #
+      # @param field [String] field name
+      # @param value [Object] value to check
+      # @return [Boolean]
+
+      def unique?(field, value)
+        @mutex.synchronize do
+          !@values[field.to_s].include?(value)
+        end
+      end
+
+
+      # Generate a unique value
+      #
+      # @param field [String] field name
+      # @yield block that generates a value
+      # @return [Object] unique value
+      # @raise [UniquenessError] if unable to generate unique value
+
+      def generate_unique(field)
+        last_values = []
+        @max_retries.times do
+          value = yield
+          if unique?(field, value)
+            track(field, value)
+            return value
+          end
+          last_values << value
+          last_values.shift if last_values.length > 10
+        end
+
+        raise UniquenessError.new(
+          field: field,
+          attempts: @max_retries,
+          last_values: last_values,
+          schema_name: @schema_name
+        )
+      end
+
+
+      # Clear all tracked values
+      #
+      # @return [void]
+
+      def clear
+        @mutex.synchronize do
+          @values.clear
+        end
+      end
+
+
+      # Clear values for a specific field
+      #
+      # @param field [String] field name
+      # @return [void]
+
+      def clear_field(field)
+        @mutex.synchronize do
+          @values.delete(field.to_s)
+        end
+      end
+
+
+      # Get all tracked values for a field
+      #
+      # @param field [String] field name
+      # @return [Set]
+
+      def values_for(field)
+        @mutex.synchronize do
+          @values[field.to_s].dup
+        end
+      end
+
+
+      # Number of unique values tracked for a field
+      #
+      # @param field [String] field name
+      # @return [Integer]
+
+      def count_for(field)
+        @mutex.synchronize do
+          @values[field.to_s].size
+        end
+      end
+    end
+  end
+end
+

data/lib/synthra/initializer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# =============================================================================
+# Synthra - Eager Loading and Initialization
+# =============================================================================
+
+# NOTE: Do not create a new Zeitwerk loader here - this file is autoloaded
+# by the main gem loader in synthra.rb. Creating another loader would
+# cause a conflict.
+
+# Load core utilities
+require_relative "utils/string_distance"
+require_relative "validator/path_validator"
+
+# Export system
+require_relative "export"
+require_relative "export/type_mapping"
+
+# LSP and REPL
+require_relative "lsp/server"
+require_relative "repl/formatter"
+require_relative "repl/enhanced_repl"
+
+# Hostile payloads
+require_relative "types/hostile_payloads"
+
+# New features
+require_relative "schema_inheritance"
+require_relative "factory_bot_integration"
+require_relative "snapshot_testing"
+
+# Phase 2 features
+require_relative "rails_test_helper"
+require_relative "mixin"
+require_relative "relationships"
+require_relative "schema_versioning"
+require_relative "openapi_importer"
+require_relative "database_seeder"
+require_relative "live_preview"
+require_relative "documentation_generator"
+require_relative "deterministic_ids"
+
+# Production-grade features
+require_relative "export/protobuf"
+require_relative "export/openapi"
+require_relative "mock_server"
+require_relative "contracts_registry"
+require_relative "performance_mode"
+require_relative "api_server"
+
+# Rails-tier features
+require_relative "time_travel"
+require_relative "scenarios"
+require_relative "personas"
+require_relative "quality_metrics"
+require_relative "webhook_simulator"
+require_relative "migration_generator"
+require_relative "export/graphql_federation"
+require_relative "export/terraform"
+
+# Rails Engine (only if Rails is available)
+if defined?(Rails::Engine)
+  require_relative "engine"
+  require_relative "activerecord_inference"
+end
+
+# CLI command pattern
+require_relative "cli/commands/base"
+require_relative "cli/commands/validate"
+require_relative "cli/commands/lint"
+require_relative "cli/commands/generate"
+require_relative "cli/commands/export"
+require_relative "cli/commands/diff"
+require_relative "cli/commands/import"
+require_relative "cli/commands/docs"
+require_relative "cli/commands/live"
+require_relative "cli/commands/seed"
+
+# Load domain folder type files
+IGNORED_DOMAIN_FOLDERS = %w[
+  address_location finance_banking technology_internet commerce_products
+  media_entertainment personal_names text_content health_medical travel
+  date_time crypto core
+].freeze
+
+IGNORED_DOMAIN_FOLDERS.each do |folder|
+  dir = File.join(__dir__, "types/#{folder}")
+  next unless Dir.exist?(dir)
+
+  Dir.glob(File.join(dir, "*.rb")).sort.each do |file|
+    require_relative file.sub(%r{^#{__dir__}/}, "")
+  end
+end
+
+# Register built-in types and behaviors
+Synthra.register_builtin_types!
+Synthra::Behaviors::Registry.register_builtins!