synthra 0.1.0

data/lib/synthra/generator/context.rb

@@ -0,0 +1,372 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Generator Context
+# =============================================================================
+#
+# The Context holds generated field values during record generation.
+# It provides access to previously generated values for computed fields
+# and conditional logic.
+#
+# @example Using context in custom functions
+#   Synthra.register_function(:full_name) do |ctx|
+#     "#{ctx['first_name']} #{ctx['last_name']}"
+#   end
+#
+# @example Conditional field using context
+#   # admin_note: text if is_admin
+#   # The context contains { "is_admin" => true } when evaluating
+#
+# =============================================================================
+
+
+module Synthra
+  module Generator
+
+    # Generation context for accessing generated field values
+    #
+    # Context acts as a hash-like container for field values during
+    # generation. It supports multiple access patterns (hash, dot notation)
+    # and nested path lookups.
+    #
+    # @example Create and use context
+    #   ctx = Context.new
+    #   ctx["name"] = "John"
+    #   ctx["name"]  # => "John"
+    #   ctx.name     # => "John" (dot notation)
+    #
+    # @example Nested access
+    #   ctx["address"] = { "city" => "NYC" }
+    #   ctx.get("address.city")  # => "NYC"
+    #
+
+    class Context
+
+      # @!attribute [r] schema_name
+      #   Name of the schema being generated (for reference resolution)
+      #   @return [String, nil] the schema name
+
+      attr_reader :schema_name
+
+
+      # @!attribute [rw] registry
+      #   Registry for resolving cross-schema references
+      #   @return [Registry, nil] the schema registry
+
+      attr_accessor :registry
+
+
+      # @!attribute [rw] depth
+      #   Current recursion depth for nested schema generation
+      #   @return [Integer] the depth level
+
+      attr_accessor :depth
+
+
+      # @!attribute [rw] parent_context
+      #   Parent context for nested schemas (enables copy() from parent)
+      #   @return [Context, nil] the parent context
+
+      attr_accessor :parent_context
+
+
+      # @!attribute [rw] shared_context
+      #   Shared context for batch generation (values persist across records)
+      #   @return [Hash] the shared context hash
+
+      attr_accessor :shared_context
+
+
+      # @!attribute [rw] resolver
+      #   Resolver for cross-schema reference resolution
+      #   @return [Resolver, nil] the resolver instance
+
+      attr_accessor :resolver
+
+
+      # @!attribute [rw] faker_adapter
+      #   Faker adapter for deterministic fake data generation
+      #   @return [FakerAdapter, nil] the faker adapter
+
+      attr_accessor :faker_adapter
+
+
+      # Create a new Context
+      #
+      # @param data [Hash] initial data to populate the context
+      # @param registry [Registry, nil] registry for resolving references
+      # @param depth [Integer] current recursion depth
+      # @param parent_context [Context, nil] parent context for nested schemas
+      # @param shared_context [Hash, nil] shared context for batch generation
+      # @param resolver [Resolver, nil] resolver for cross-schema references
+      # @param faker_adapter [FakerAdapter, nil] adapter for Faker
+      #
+      # @example Empty context
+      #   ctx = Context.new
+      #
+      # @example Pre-populated context
+      #   ctx = Context.new({ name: "John", age: 30 })
+      #
+      # @example With all options
+      #   ctx = Context.new(
+      #     { name: "John" },
+      #     registry: my_registry,
+      #     depth: 1,
+      #     parent_context: parent_ctx,
+      #     shared_context: {}
+      #   )
+      #
+
+      def initialize(data = {}, registry: nil, depth: 0, parent_context: nil, shared_context: nil, resolver: nil, faker_adapter: nil)
+        @data = data.transform_keys(&:to_s)
+        @schema_name = nil
+        @registry = registry
+        @depth = depth
+        @parent_context = parent_context
+        @shared_context = shared_context || {}
+        @resolver = resolver
+        @faker_adapter = faker_adapter
+      end
+
+
+      # Get value by key (hash-style access)
+      #
+      # @param key [String, Symbol] the key to look up
+      # @return [Object, nil] the value or nil if not found
+      #
+      # @example
+      #   ctx["name"]  # => "John"
+      #   ctx[:name]   # => "John" (symbols work too)
+      #
+
+      def [](key)
+        @data[key.to_s]
+      end
+
+
+      # Set value by key (hash-style access)
+      #
+      # @param key [String, Symbol] the key to set
+      # @param value [Object] the value to store
+      # @return [Object] the value
+      #
+      # @example
+      #   ctx["name"] = "John"
+      #
+
+      def []=(key, value)
+        @data[key.to_s] = value
+      end
+
+
+      # Set value (chainable)
+      #
+      # @param key [String, Symbol] the key to set
+      # @param value [Object] the value to store
+      # @return [Context] self for chaining
+      #
+      # @example
+      #   ctx.set(:name, "John").set(:age, 30)
+      #
+
+      def set(key, value)
+        self[key] = value
+        self
+      end
+
+
+      # Get value with dot notation path support
+      #
+      # Traverses nested hashes/contexts using dot-separated paths.
+      #
+      # @param path [String] dot-separated path (e.g., "address.city")
+      # @return [Object, nil] the value or nil if not found
+      #
+      # @example
+      #   ctx["user"] = { "address" => { "city" => "NYC" } }
+      #   ctx.get("user.address.city")  # => "NYC"
+      #
+
+      def get(path)
+        parts = path.to_s.split(".")
+        result = @data
+
+        parts.each do |part|
+          case result
+          when Hash
+            result = result[part] || result[part.to_sym]
+          when Context
+            result = result[part]
+          else
+            return nil
+          end
+          return nil if result.nil?
+        end
+
+        result
+      end
+
+
+      # Check if a key exists
+      #
+      # @param key [String, Symbol] the key to check
+      # @return [Boolean] true if key exists
+      #
+      # @example
+      #   ctx.has?("name")  # => true
+      #   ctx.has?("unknown")  # => false
+      #
+
+      def has?(key)
+        @data.key?(key.to_s)
+      end
+
+      alias key? has?
+      alias include? has?
+
+
+      # Convert to a plain Hash
+      #
+      # @return [Hash] copy of internal data
+      #
+      # @example
+      #   ctx.to_h  # => { "name" => "John", "age" => 30 }
+      #
+
+      def to_h
+        @data.dup
+      end
+
+      alias to_hash to_h
+
+
+      # Merge with another hash or context
+      #
+      # Creates a new Context with merged data. Does not modify original.
+      #
+      # @param other [Hash, Context] values to merge in
+      # @return [Context] new context with merged data
+      #
+      # @example
+      #   new_ctx = ctx.merge({ email: "john@example.com" })
+      #
+
+      def merge(other)
+        other_data = other.respond_to?(:to_h) ? other.to_h : other
+        Context.new(@data.merge(other_data.transform_keys(&:to_s)))
+      end
+
+
+      # Set the schema name for reference resolution
+      #
+      # @param name [String] the schema name
+      # @return [Context] self for chaining
+      #
+
+      def with_schema(name)
+        @schema_name = name
+        self
+      end
+
+
+      # Dynamic method access (dot notation for fields)
+      #
+      # Provides Ruby-style attribute access to context values.
+      # Nested hashes are automatically wrapped in Context objects.
+      #
+      # @example
+      #   ctx.name       # same as ctx["name"]
+      #   ctx.name = "X" # same as ctx["name"] = "X"
+      #
+
+      def method_missing(method, *args, &block)
+        method_name = method.to_s
+
+
+        # Handle setters (method=)
+        if method_name.end_with?("=")
+          key = method_name.chomp("=")
+          return self[key] = args.first
+        end
+
+
+        # Handle getters
+        if @data.key?(method_name)
+          value = @data[method_name]
+
+          # Wrap nested hashes in Context for continued dot access
+          return value.is_a?(Hash) ? Context.new(value) : value
+        end
+
+        super
+      end
+
+
+      # Check if method responds (for method_missing)
+      #
+      # @param method [Symbol] method name
+      # @param include_private [Boolean] include private methods
+      # @return [Boolean] true if method would be handled
+      #
+
+      def respond_to_missing?(method, include_private = false)
+        method_name = method.to_s.chomp("=")
+        @data.key?(method_name) || super
+      end
+
+
+      # Get all keys
+      #
+      # @return [Array<String>] list of keys
+      #
+
+      def keys
+        @data.keys
+      end
+
+
+      # Get all values
+      #
+      # @return [Array] list of values
+      #
+
+      def values
+        @data.values
+      end
+
+
+      # Iterate over key-value pairs
+      #
+      # @yield [key, value] block for each pair
+      # @return [Enumerator] if no block given
+      #
+
+      def each(&block)
+        @data.each(&block)
+      end
+
+
+      # Check if context is empty
+      #
+      # @return [Boolean] true if no data
+      #
+
+      def empty?
+        @data.empty?
+      end
+
+
+      # Get number of entries
+      #
+      # @return [Integer] number of key-value pairs
+      #
+
+      def size
+        @data.size
+      end
+
+      alias length size
+    end
+  end
+end

data/lib/synthra/generator/engine.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Generator Engine
+# =============================================================================
+#
+# The Engine is the core component responsible for generating fake data
+# from schema definitions. It coordinates type generation, field behaviors,
+# uniqueness constraints, and deterministic seeding.
+#
+# @example Basic usage
+#   engine = Generator::Engine.new(schema)
+#   record = engine.generate
+#
+# @example Deterministic generation
+#   engine = Generator::Engine.new(schema)
+#   record1 = engine.generate(seed: 12345)
+#   record2 = engine.generate(seed: 12345)
+#   # record1 == record2 (same seed = same output)
+#
+# =============================================================================
+
+
+module Synthra
+  module Generator
+
+    # Core generation engine
+    #
+    # The Engine orchestrates the data generation process, handling:
+    # - Field iteration and value generation
+    # - Type lookup and invocation
+    # - Uniqueness constraint enforcement
+    # - Optional and conditional field handling
+    # - Field-level behavior application
+    # - Deterministic seeding via RNG
+    #
+    # @example Generate a single record
+    #   engine = Engine.new(schema)
+    #   user = engine.generate(seed: 42, mode: :random)
+    #
+    # @example Generate multiple records
+    #   users = engine.generate_many(100, seed: 42)
+    #
+
+    class Engine
+
+      # @!attribute [r] schema
+      #   The schema being generated from
+      #   @return [Schema] the schema definition
+
+      attr_reader :schema
+
+
+      # @!attribute [r] rng
+      #   The random number generator for determinism
+      #   @return [RNG, nil] the RNG instance
+
+      attr_reader :rng
+
+
+      # @!attribute [r] registry
+      #   Registry for cross-schema references
+      #   @return [Registry, nil] schema registry
+
+      attr_reader :registry
+
+
+      # Create a new Engine instance
+      #
+      # @param schema [Schema] the schema to generate from
+      # @param registry [Registry, nil] optional registry for Ref() lookups
+      # @param resolver [Resolver, nil] optional resolver instance to reuse (for cycle detection)
+      #
+      # @example
+      #   engine = Engine.new(user_schema, registry: schema_registry)
+      #
+
+      def initialize(schema, registry: nil, resolver: nil)
+        @schema = schema
+        @registry = registry
+        @rng = nil
+        @faker_adapter = nil
+        @uniqueness = Uniqueness.new(schema_name: schema.name)
+
+        # Use provided resolver or create new one if registry is available
+        # Reusing resolver ensures @generating set is shared for cycle detection
+        @resolver = resolver || (registry ? Resolver.new(registry) : nil)
+
+        # Pre-compute observability flag at initialization to avoid repeated
+        # config lookups in the hot path (called once per Engine, not per record)
+        @observability_enabled = Synthra.configuration.observability_enabled?
+      end
+
+
+      # Generate a single record
+      #
+      # Creates one fake data record based on the schema definition.
+      # Use the seed parameter for deterministic/reproducible output.
+      #
+      # @param seed [Integer, nil] random seed for deterministic output
+      # @param mode [Symbol] generation mode (:random, :edge, :invalid, :mixed)
+      # @param overrides [Hash] field values to use instead of generating
+      # @return [Hash] the generated record
+      #
+      # @example Basic generation
+      #   record = engine.generate
+      #
+      # @example Deterministic generation
+      #   record = engine.generate(seed: 12345)
+      #
+      # @example With overrides
+      #   record = engine.generate(overrides: { "name" => "Test User" })
+      #
+
+      def generate(seed: nil, mode: :random, overrides: {}, depth: 0, parent_context: nil, shared_context: nil)
+
+        # Reset RNG if seed is provided, or create one if none exists
+        setup_rng(seed) if seed || @rng.nil?
+        generate_single(mode: mode, overrides: overrides, depth: depth, parent_context: parent_context, shared_context: shared_context)
+      end
+
+
+      # Generate multiple records
+      #
+      # Creates multiple fake data records efficiently. Uniqueness
+      # constraints are enforced across the entire batch.
+      #
+      # @param count [Integer] number of records to generate
+      # @param seed [Integer, nil] random seed for deterministic output
+      # @param mode [Symbol] generation mode
+      # @param overrides [Hash] field values to override in all records
+      # @return [Array<Hash>] array of generated records
+      #
+      # @example Generate 100 users
+      #   users = engine.generate_many(100)
+      #
+      # @example Deterministic batch
+      #   users = engine.generate_many(100, seed: 42)
+      #
+      # @note For large batches (10K+ records), consider using
+      #   generate_many_stream for memory-efficient lazy generation.
+      #
+
+      def generate_many(count, seed: nil, mode: :random, overrides: {}, shared_context: nil)
+        setup_rng(seed)
+        @uniqueness.clear  # Reset uniqueness tracking for new batch
+
+        # Create shared context for batch - values persist across all records
+        shared_context ||= {}
+
+        count.times.map do
+          generate_single(mode: mode, overrides: overrides, depth: 0, shared_context: shared_context)
+        end
+      end
+
+
+      # Generate multiple records as a lazy stream (Enumerator)
+      #
+      # Returns an Enumerator that generates records on-demand. This is
+      # memory-efficient for large batches as records are not all held
+      # in memory at once.
+      #
+      # @param count [Integer] number of records to generate
+      # @param seed [Integer, nil] random seed for deterministic output
+      # @param mode [Symbol] generation mode
+      # @param overrides [Hash] field values to override in all records
+      # @return [Enumerator] lazy enumerator of records
+      #
+      # @example Generate 10K users efficiently
+      #   engine.generate_many_stream(10000, seed: 42).each do |user|
+      #     process(user)  # Records generated one at a time
+      #   end
+      #
+
+      def generate_many_stream(count, seed: nil, mode: :random, overrides: {}, shared_context: nil)
+        setup_rng(seed)
+        @uniqueness.clear  # Reset uniqueness tracking for new batch
+
+        # Create shared context for batch - values persist across all records
+        shared_context ||= {}
+
+        Enumerator.new(count) do |yielder|
+          count.times do
+            yielder << generate_single(mode: mode, overrides: overrides, depth: 0, shared_context: shared_context)
+          end
+        end
+      end
+
+      private
+
+
+      # Setup RNG and FakerAdapter for deterministic output
+      #
+      # @param seed [Integer, nil] seed value (nil generates random seed)
+      # @return [void]
+      #
+
+      def setup_rng(seed)
+        @rng = RNG.new(seed)
+        @faker_adapter = FakerAdapter.new(@rng)
+      end
+
+
+      # Generate a single record (internal)
+      #
+      # @param mode [Symbol] generation mode
+      # @param overrides [Hash] field overrides
+      # @param depth [Integer] current recursion depth
+      # @param shared_context [Hash] shared values that persist across batch
+      # @return [Hash] generated record
+      #
+
+      def generate_single(mode:, overrides:, depth: 0, parent_context: nil, shared_context: nil)
+        # Cache config locally to avoid repeated method calls
+        config = Synthra.configuration
+        presence_rate = config.optional_field_presence_rate || Synthra::OPTIONAL_FIELD_PRESENCE_RATE
+        null_rate = config.nullable_field_null_rate || Synthra::NULLABLE_FIELD_NULL_RATE
+
+        # Create context with proper initialization
+        context = Context.new(
+          {},
+          registry: @registry,
+          depth: depth,
+          parent_context: parent_context,
+          shared_context: shared_context || {},
+          resolver: @resolver,
+          faker_adapter: @faker_adapter
+        )
+
+        result = {}
+        applicator = Behaviors::Applicator.new(@schema, @rng)
+
+        # Iterate fields in definition order (important for copy() to work)
+        @schema.fields.each do |field|
+          # Skip if override provided
+          if overrides.key?(field.name) || overrides.key?(field.name.to_sym)
+            result[field.name] = overrides[field.name] || overrides[field.name.to_sym]
+            context[field.name] = result[field.name]
+            next
+          end
+
+          # Handle conditional fields
+          if field.conditional?
+            next unless context[field.condition]
+          end
+
+          # Handle optional fields
+          next if field.optional? && !@rng.boolean(presence_rate)
+
+          # Generate the field value with optional timing
+          start_time = @observability_enabled ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
+          value = generate_field(field, context, mode)
+
+          # Apply field-level behaviors
+          value = applicator.apply_field_behaviors(field, value)
+          next if value == :omit
+
+          # Handle nullable fields
+          value = nil if field.nullable? && @rng.boolean(null_rate)
+
+          # Observability hooks (only if enabled - checked once at init)
+          if @observability_enabled
+            duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round
+            emit_observability(config, field, value, duration_ms)
+          end
+
+          result[field.name] = value
+          context[field.name] = value
+        end
+
+        result
+      end
+
+      def emit_observability(config, field, value, duration_ms)
+        if config.metrics_collector
+          config.metrics_collector.timing(
+            "synthra.field_generation",
+            duration_ms,
+            schema: @schema.name,
+            field: field.name,
+            type: field.type_name
+          )
+        end
+
+        config.logger&.debug(
+          "Generated field #{@schema.name}.#{field.name} (#{field.type_name}) in #{duration_ms}ms"
+        )
+
+        config.on_field_generated&.call(@schema.name, field.name, value, duration_ms)
+      end
+
+
+      # Generate a single field value
+      #
+      # @param field [Field] the field definition
+      # @param context [Context] current generation context
+      # @param mode [Symbol] generation mode
+      # @return [Object] generated value
+      #
+
+      def generate_field(field, context, mode)
+        type_name = field.type_name
+        type_args = field.type_args
+
+
+        # Look up the type generator - first try Types::Registry
+        type_gen = begin
+          Types::Registry.lookup(type_name)
+        rescue Errors::UnknownTypeError
+          # If not a registered type, check if it's a schema reference
+          if @registry && @registry.schema?(type_name)
+            # Create an ObjectType for the schema reference
+            Types::Core::ObjectType.new(type_name)
+          else
+            raise  # Re-raise the UnknownTypeError if not a schema either
+          end
+        end
+
+
+        # Pass faker_adapter in context for type generators to use
+        context.faker_adapter = @faker_adapter if @faker_adapter
+
+
+        # Handle uniqueness constraint
+        if field.unique?
+          @uniqueness.generate_unique(field.name) do
+            type_gen.generate(@rng, context, type_args, mode)
+          end
+        else
+          type_gen.generate(@rng, context, type_args, mode)
+        end
+      end
+    end
+  end
+end