synthra 0.1.0

data/lib/synthra/config_file.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Synthra
+  # Configuration File Support
+  #
+  # Loads configuration from YAML files following Rails conventions.
+  # Supports environment-specific configuration.
+  #
+  # @example synthra.yml
+  #   default_mode: random
+  #   seed: 12345
+  #   locale: en
+  #   limits:
+  #     max_array_size: 100
+  #     max_recursion: 5
+  #
+  #   test:
+  #     seed: 42  # Deterministic in tests
+  #
+  #   development:
+  #     seed: null  # Random in dev
+  #
+  module ConfigFile
+    # Default config file locations (searched in order)
+    CONFIG_PATHS = [
+      "config/synthra.yml",
+      "synthra.yml",
+      ".synthra.yml"
+    ].freeze
+
+    class << self
+      # Load configuration from file
+      #
+      # @param path [String, nil] explicit path or nil to search defaults
+      # @param env [String, Symbol] environment name (default: RAILS_ENV or RACK_ENV or 'development')
+      # @return [Hash] configuration hash
+      #
+      def load(path = nil, env: nil)
+        path ||= find_config_file
+        return {} unless path && File.exist?(path)
+
+        env ||= determine_environment
+        
+        raw_config = YAML.safe_load(
+          File.read(path),
+          permitted_classes: [Symbol, Date, Time],
+          aliases: true
+        ) || {}
+        
+        # Merge base config with environment-specific config
+        base_config = raw_config.except(*known_environments)
+        env_config = raw_config[env.to_s] || {}
+        
+        deep_merge(base_config, env_config)
+      end
+
+      # Apply configuration to Synthra
+      #
+      # @param config [Hash] configuration hash
+      # @return [void]
+      #
+      def apply(config)
+        Synthra.configure do |c|
+          # Core settings
+          c.default_mode = config["default_mode"].to_sym if config["default_mode"]
+          c.max_unique_retries = config["max_unique_retries"] if config["max_unique_retries"]
+          c.allow_eval = config["allow_eval"] if config.key?("allow_eval")
+          c.fast_mode = config["fast_mode"] if config.key?("fast_mode")
+          
+          # Field handling
+          c.optional_field_presence_rate = config["optional_field_presence_rate"] if config["optional_field_presence_rate"]
+          c.nullable_field_null_rate = config["nullable_field_null_rate"] if config["nullable_field_null_rate"]
+          
+          # Limits
+          if config["limits"]
+            c.limits.max_latency_ms = config["limits"]["max_latency_ms"] if config["limits"]["max_latency_ms"]
+            c.limits.max_recursion = config["limits"]["max_recursion"] if config["limits"]["max_recursion"]
+            c.limits.max_array_size = config["limits"]["max_array_size"] if config["limits"]["max_array_size"]
+            c.limits.max_text_length = config["limits"]["max_text_length"] if config["limits"]["max_text_length"]
+          end
+        end
+      end
+
+      # Load and apply configuration in one step
+      #
+      # @param path [String, nil] config file path
+      # @param env [String, Symbol] environment
+      # @return [Hash] loaded configuration
+      #
+      def load_and_apply(path = nil, env: nil)
+        config = load(path, env: env)
+        apply(config) if config.any?
+        config
+      end
+
+      # Find configuration file in default locations
+      #
+      # @return [String, nil] path to config file or nil
+      #
+      def find_config_file
+        CONFIG_PATHS.find { |p| File.exist?(p) }
+      end
+
+      private
+
+      def determine_environment
+        ENV["RAILS_ENV"] || ENV["RACK_ENV"] || ENV["SYNTHRA_ENV"] || "development"
+      end
+
+      def known_environments
+        %w[development test production staging]
+      end
+
+      def deep_merge(base, override)
+        result = base.dup
+        override.each do |key, value|
+          if base[key].is_a?(Hash) && value.is_a?(Hash)
+            result[key] = deep_merge(base[key], value)
+          else
+            result[key] = value
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/synthra/configuration.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Configuration
+# =============================================================================
+#
+# This file defines the global configuration settings for Synthra.
+# Configuration can be modified using the Synthra.configure block
+# or by directly accessing Synthra.configuration.
+#
+# @example Configure Synthra
+#   Synthra.configure do |config|
+#     config.default_mode = :edge
+#     config.max_unique_retries = 500
+#     config.limits.max_latency_ms = 5000
+#   end
+#
+# =============================================================================
+
+
+module Synthra
+
+  # Global configuration settings for Synthra
+  #
+  # The Configuration class holds all global settings that affect how
+  # Synthra behaves. Settings include default generation mode,
+  # uniqueness retry limits, and resource limits.
+  #
+  # Access the configuration via {Synthra.configuration} or
+  # modify it using {Synthra.configure}.
+  #
+  # @example Access configuration
+  #   config = Synthra.configuration
+  #   config.default_mode        # => :random
+  #   config.max_unique_retries  # => 1000
+  #
+  # @example Modify configuration
+  #   Synthra.configure do |config|
+  #     config.default_mode = :mixed
+  #     config.null_optional = true
+  #   end
+  #
+  # @example Reset to defaults
+  #   Synthra.reset_configuration!
+  #
+
+  class Configuration
+
+    # Valid generation modes
+    #
+    # @return [Array<Symbol>] the list of valid mode symbols
+    #
+    # Modes:
+    # - :random - Standard fake data generation using Faker
+    # - :edge   - Generate edge case values (empty strings, nulls, extremes)
+    # - :invalid - Generate intentionally invalid data for validation testing
+    # - :hostile - Generate security attack payloads (SQL injection, XSS, buffer overflow)
+    # - :mixed  - Probabilistically mix all modes (80% random, 15% edge, 5% invalid)
+    #
+
+    VALID_MODES = %i[random edge invalid hostile mixed].freeze
+
+
+    # @!attribute allow_eval
+    #   Whether to allow eval() in custom expressions (default: false)
+    #   @return [Boolean] true to allow eval, false to disallow
+    #   @note Enabling eval is a security risk and should only be used
+    #     in trusted environments
+
+    attr_accessor :allow_eval
+
+
+    # @!attribute max_unique_retries
+    #   Maximum attempts to generate a unique value before giving up
+    #   @return [Integer] the maximum retry count (default: 1000)
+    #   @see UniquenessError raised when limit is exceeded
+
+    attr_accessor :max_unique_retries
+
+
+    # @!attribute null_optional
+    #   Whether optional fields should default to null/nil
+    #   @return [Boolean] true to default optional to null (default: false)
+
+    attr_accessor :null_optional
+
+
+    # @!attribute registry_cache_size
+    #   Maximum number of AST entries to cache in the registry
+    #   @return [Integer] the maximum cache size (default: 100)
+
+    attr_accessor :registry_cache_size
+
+
+    # @!attribute logger
+    #   Optional logger for observability (Logger instance or compatible object)
+    #   @return [Logger, nil] logger instance or nil
+
+    attr_accessor :logger
+
+
+    # @!attribute warn_on_shared_misuse
+    #   Whether to emit warnings when shared() is used outside generate_many()
+    #   @return [Boolean] true to emit warnings (default: true)
+    #   @note When shared() is used with generate() instead of generate_many(),
+    #     values won't be shared across calls, which may be unintended behavior
+
+    attr_accessor :warn_on_shared_misuse
+
+
+    # @!attribute validate_paths_on_load
+    #   Whether to automatically validate copy() paths when loading schemas
+    #   @return [Boolean] true to validate on load (default: true)
+    #   @note This catches typos in copy() paths at load time rather than
+    #     at generation time, preventing silent nil values
+
+    attr_accessor :validate_paths_on_load
+
+
+    # @!attribute optional_field_presence_rate
+    #   Probability that an optional field will be included in output (default: 0.8 = 80%)
+    #   @return [Float] probability between 0.0 and 1.0
+
+    attr_accessor :optional_field_presence_rate
+
+
+    # @!attribute nullable_field_null_rate
+    #   Probability that a nullable field will be null (default: 0.1 = 10%)
+    #   @return [Float] probability between 0.0 and 1.0
+
+    attr_accessor :nullable_field_null_rate
+
+
+    # @!attribute fast_mode
+    #   Whether to use FastEngine for batch generation (default: false)
+    #   @return [Boolean] true to use FastEngine, false to use standard Engine
+    #   @note FastEngine is optimized for batch generation but is NOT thread-safe
+
+    attr_accessor :fast_mode
+
+
+    # @!attribute metrics_collector
+    #   Optional metrics collector for observability
+    #   @return [Object, nil] metrics collector instance or nil
+
+    attr_accessor :metrics_collector
+
+
+    # @!attribute on_field_generated
+    #   Optional callback invoked when a field is generated
+    #   @return [Proc, nil] callback proc or nil
+    #   @note Callback receives (field_name, value, context) as arguments
+
+    attr_accessor :on_field_generated
+
+
+    # @!attribute [r] default_mode
+    #   The default generation mode when not explicitly specified
+    #   @return [Symbol] one of :random, :edge, :invalid, :hostile, :mixed
+    #   @see #default_mode= to set this value
+
+    attr_reader :default_mode
+
+
+    # Create a new Configuration with default values
+    #
+    # @return [Configuration] a new configuration instance
+    #
+    # @example
+    #   config = Synthra::Configuration.new
+    #   config.default_mode  # => :random
+    #
+
+    def initialize
+      reset!
+    end
+
+
+    # Access the resource limits configuration
+    #
+    # The limits object controls maximum values for latency, recursion
+    # depth, and array sizes to prevent runaway generation.
+    #
+    # @return [Limits] the limits configuration object
+    #
+    # @example Configure limits
+    #   Synthra.configure do |config|
+    #     config.limits.max_latency_ms = 10000   # 10 seconds
+    #     config.limits.max_recursion = 5        # 5 levels deep
+    #     config.limits.max_array_size = 100     # 100 elements max
+    #   end
+    #
+
+    def limits
+      @limits ||= Limits.new
+    end
+
+
+    # Set the default generation mode
+    #
+    # @param mode [Symbol] the generation mode
+    # @option mode :random Standard fake data generation
+    # @option mode :edge Edge case values (empty, null, extremes)
+    # @option mode :invalid Intentionally invalid data
+    # @option mode :hostile Security attack payloads (SQL injection, XSS, etc.)
+    # @option mode :mixed Probabilistic mix of all modes
+    # @raise [ArgumentError] if mode is not one of the valid modes
+    # @return [Symbol] the set mode
+    #
+    # @example
+    #   config.default_mode = :edge
+    #
+    # @example Invalid mode
+    #   config.default_mode = :unknown
+    #   # => ArgumentError: Invalid mode: unknown. Valid modes: random, edge, invalid, mixed
+    #
+
+    def default_mode=(mode)
+      unless VALID_MODES.include?(mode)
+        raise ArgumentError, "Invalid mode: #{mode}. Valid modes: #{VALID_MODES.join(", ")}"
+      end
+
+      @default_mode = mode
+    end
+
+
+    # Reset all configuration settings to their defaults
+    #
+    # This method restores all settings to their initial values:
+    # - allow_eval: false
+    # - default_mode: :random
+    # - max_unique_retries: 1000
+    # - null_optional: false
+    # - limits: new Limits instance with defaults
+    #
+    # @return [void]
+    #
+    # @example Reset after tests
+    #   after(:each) do
+    #     Synthra.configuration.reset!
+    #   end
+    #
+
+      def reset!
+        @allow_eval = false
+        @default_mode = :random
+        @max_unique_retries = 1000
+        @null_optional = false
+        @limits = nil  # Will be lazily initialized with defaults
+        @logger = nil
+        @metrics_collector = nil
+        @on_field_generated = nil
+        @registry_cache_size = 100
+        @warn_on_shared_misuse = true  # Warn when shared() used outside generate_many()
+        @validate_paths_on_load = true  # Auto-validate copy() paths on schema load
+        @optional_field_presence_rate = Synthra::OPTIONAL_FIELD_PRESENCE_RATE
+        @nullable_field_null_rate = Synthra::NULLABLE_FIELD_NULL_RATE
+        @fast_mode = false  # Use standard Engine by default (thread-safe)
+      end
+
+
+    # Check if observability features are enabled
+    #
+    # Returns true if any of the observability features (metrics, logging,
+    # or field generation callbacks) are configured. Used to optimize the
+    # hot path by avoiding unnecessary checks.
+    #
+    # @return [Boolean] true if observability is enabled
+    #
+    # @example
+    #   config.observability_enabled?  # => false (by default)
+    #   config.logger = Logger.new(STDOUT)
+    #   config.observability_enabled?  # => true
+    #
+
+    def observability_enabled?
+      !!(@metrics_collector || @logger || @on_field_generated)
+    end
+  end
+end