treaty 0.18.0 → 0.19.0

data/lib/treaty/entity/attribute/option_normalizer.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      # Normalizes options from simple mode to advanced mode.
+      #
+      # ## Purpose
+      #
+      # All options are stored and processed internally in advanced mode.
+      # This normalizer converts simple mode to advanced mode automatically.
+      #
+      # ## Modes Explained
+      #
+      # ### Simple Mode (Concise syntax)
+      # ```ruby
+      # {
+      #   required: true,
+      #   as: :value,
+      #   in: %w[twitter linkedin github],
+      #   default: 12
+      # }
+      # ```
+      #
+      # ### Advanced Mode (With messages)
+      # ```ruby
+      # {
+      #   required: { is: true, message: nil },
+      #   as: { is: :value, message: nil },
+      #   inclusion: { in: %w[twitter linkedin github], message: nil },
+      #   default: { is: 12, message: nil }
+      # }
+      # ```
+      #
+      # ## Key Mappings
+      #
+      # Some simple mode keys are renamed in advanced mode:
+      # - `in:` → `inclusion:` (with value key `:in`)
+      #
+      # Others keep the same name:
+      # - `required:` → `required:` (with value key `:is`)
+      # - `as:` → `as:` (with value key `:is`)
+      # - `default:` → `default:` (with value key `:is`)
+      #
+      # ## Value Keys
+      #
+      # Each option has a value key in advanced mode:
+      # - Default: `:is` (most options)
+      # - Special: `:in` (inclusion validator)
+      #
+      # ## Message Field
+      #
+      # The `message` field in advanced mode allows custom error messages:
+      # - `nil` - Use default message (most common)
+      # - String - Custom error message for validation failures
+      #
+      # ## Usage in DSL
+      #
+      # Users can write in either mode:
+      #
+      # Simple mode:
+      #   string :provider, in: %w[twitter linkedin]
+      #
+      # Advanced mode:
+      #   string :provider, inclusion: { in: %w[twitter linkedin], message: "Invalid provider" }
+      #
+      # Both are normalized to advanced mode internally.
+      class OptionNormalizer
+        # Maps simple mode option keys to their advanced mode configuration.
+        # Format: simple_key => { advanced_key:, value_key: }
+        OPTION_KEY_MAPPING = {
+          in: { advanced_key: :inclusion, value_key: :in },
+          as: { advanced_key: :as, value_key: :is },
+          default: { advanced_key: :default, value_key: :is },
+          cast: { advanced_key: :cast, value_key: :to }
+        }.freeze
+        private_constant :OPTION_KEY_MAPPING
+
+        # Reverse mapping: advanced_key => value_key
+        # Used to determine value key when option is already in advanced mode.
+        ADVANCED_KEY_TO_VALUE_KEY = OPTION_KEY_MAPPING.each_with_object({}) do |(_, config), result|
+          result[config.fetch(:advanced_key)] = config.fetch(:value_key)
+        end.freeze
+        private_constant :ADVANCED_KEY_TO_VALUE_KEY
+
+        DEFAULT_VALUE_KEY = :is
+        private_constant :DEFAULT_VALUE_KEY
+
+        class << self
+          # Normalizes all options from simple mode to advanced mode
+          # and sorts them by position for consistent execution order.
+          #
+          # @param options [Hash] Options hash in simple or advanced mode
+          # @return [Hash] Normalized options in advanced mode, sorted by position
+          def normalize(options)
+            normalized = options.each_with_object({}) do |(key, value), result|
+              advanced_key, normalized_value = normalize_option(key, value)
+              result[advanced_key] = normalized_value
+            end
+
+            sort_by_position(normalized)
+          end
+
+          private
+
+          # Sorts options by their registered position.
+          # Options without position (like conditionals) sort first (position 0).
+          #
+          # @param options_hash [Hash] Normalized options hash
+          # @return [Hash] Options sorted by position
+          def sort_by_position(options_hash)
+            options_hash.sort_by do |option_name, _|
+              Option::Registry.position_for(option_name) || 0
+            end.to_h
+          end
+
+          # Normalizes a single option to advanced mode
+          #
+          # @param key [Symbol] Option key
+          # @param value [Object] Option value
+          # @return [Array<Symbol, Hash>] Tuple of [advanced_key, normalized_value]
+          def normalize_option(key, value) # rubocop:disable Metrics/MethodLength
+            mapping = OPTION_KEY_MAPPING.fetch(key, nil)
+
+            if mapping.present?
+              # Special handling for mapped options (e.g., in -> inclusion).
+              advanced_key = mapping.fetch(:advanced_key)
+              value_key = mapping.fetch(:value_key)
+              normalized_value = normalize_value(value, value_key)
+              [advanced_key, normalized_value]
+            else
+              # Check if this key is already an advanced mode key.
+              value_key = ADVANCED_KEY_TO_VALUE_KEY.fetch(key, nil) || DEFAULT_VALUE_KEY
+              normalized_value = normalize_value(value, value_key)
+              [key, normalized_value]
+            end
+          end
+
+          # Normalizes option value to advanced mode format
+          #
+          # @param value [Object] The option value (simple or advanced mode)
+          # @param value_key [Symbol] The key to use for the value (:is or :in)
+          # @return [Hash] Normalized hash with value_key and :message
+          def normalize_value(value, value_key)
+            if advanced_mode?(value, value_key)
+              # Already in advanced mode, ensure it has both keys.
+              # message: nil means use I18n default message from validators
+              { value_key => value.fetch(value_key), message: value.fetch(:message, nil) }
+            else
+              # Simple mode, convert to advanced.
+              # message: nil means use I18n default message from validators
+              { value_key => value, message: nil }
+            end
+          end
+
+          # Checks if value is already in advanced mode
+          #
+          # @param value [Object] The value to check
+          # @param value_key [Symbol] The expected value key
+          # @return [Boolean] True if value is a hash with the value key
+          def advanced_mode?(value, value_key)
+            value.is_a?(Hash) && value.key?(value_key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/option_orchestrator.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      # Orchestrates all option processors for a single attribute.
+      #
+      # ## Purpose
+      #
+      # Coordinates the execution of all option processors (validators and modifiers)
+      # for an attribute through three distinct processing phases.
+      #
+      # ## Responsibilities
+      #
+      # 1. **Processor Building** - Creates instances of all relevant option processors
+      # 2. **Schema Validation** - Validates DSL definition correctness (phase 1)
+      # 3. **Value Validation** - Validates runtime data values (phase 2)
+      # 4. **Value Transformation** - Transforms values through modifiers (phase 3)
+      # 5. **Name Transformation** - Provides target name if `as:` option is used
+      #
+      # ## Processing Phases
+      #
+      # ### Phase 1: Schema Validation
+      # Validates that the attribute definition in the DSL is correct.
+      # Called once during treaty definition loading.
+      #
+      # ```ruby
+      # orchestrator.validate_schema!
+      # ```
+      #
+      # ### Phase 2: Value Validation
+      # Validates that runtime data matches the constraints.
+      # Called for each request/response.
+      #
+      # ```ruby
+      # orchestrator.validate_value!(value)
+      # ```
+      #
+      # ### Phase 3: Value Transformation
+      # Transforms the value (applies defaults, renaming, etc.).
+      # Called for each request/response after validation.
+      #
+      # ```ruby
+      # transformed = orchestrator.transform_value(value)
+      # ```
+      #
+      # ## Usage
+      #
+      # Used by AttributeValidator to coordinate all option processing:
+      #
+      #   orchestrator = OptionOrchestrator.new(attribute)
+      #   orchestrator.validate_schema!
+      #   orchestrator.validate_value!(value)
+      #   transformed = orchestrator.transform_value(value)
+      #   target_name = orchestrator.target_name
+      #
+      # ## Processor Building
+      #
+      # Automatically:
+      # - Builds processor instances for all defined options
+      # - Always includes TypeValidator (even if not explicitly defined)
+      # - Validates that all options are registered in Registry
+      # - Raises error for unknown options
+      #
+      # ## Architecture
+      #
+      # Works with:
+      # - Option::Registry - Looks up processor classes
+      # - Option::Base - Base class for all processors
+      # - AttributeValidator - Uses orchestrator to coordinate processing
+      class OptionOrchestrator
+        # Creates a new orchestrator instance
+        #
+        # @param attribute [Attribute::Base] The attribute to orchestrate options for
+        def initialize(attribute)
+          @attribute = attribute
+          @processors = build_processors
+        end
+
+        # Phase 1: Validates all option schemas
+        # Ensures DSL definition is correct and all options are registered
+        #
+        # @raise [Treaty::Exceptions::Validation] If unknown options found
+        # @return [void]
+        def validate_schema!
+          validate_known_options!
+
+          @processors.each_value(&:validate_schema!)
+        end
+
+        # Phase 2: Validates value against all option validators
+        # Validates runtime data against all defined constraints
+        #
+        # @param value [Object] The value to validate
+        # @raise [Treaty::Exceptions::Validation] If validation fails
+        # @return [void]
+        def validate_value!(value)
+          @processors.each_value do |processor|
+            processor.validate_value!(value)
+          end
+        end
+
+        # Phase 3: Transforms value through all option modifiers
+        # Applies transformations like defaults, type coercion, etc.
+        #
+        # @param value [Object] The value to transform
+        # @param root_data [Hash] Full raw data from root level (used by computed modifier)
+        # @return [Object] Transformed value
+        def transform_value(value, root_data = {})
+          @processors.values.reduce(value) do |current_value, processor|
+            processor.transform_value(current_value, root_data)
+          end
+        end
+
+        # Checks if any processor transforms the attribute name
+        #
+        # @return [Boolean] True if any processor (like AsModifier) transforms names
+        def transforms_name?
+          @processors.values.any?(&:transforms_name?)
+        end
+
+        # Gets the target name from the processor that transforms names
+        # Returns original name if no transformation
+        #
+        # @return [Symbol] The target attribute name
+        def target_name
+          name_transformer = @processors.values.find(&:transforms_name?)
+          name_transformer ? name_transformer.target_name : @attribute.name
+        end
+
+        # Gets specific processor by option name
+        #
+        # @param option_name [Symbol] The option name (:required, :type, etc.)
+        # @return [Option::Base, nil] The processor instance or nil if not found
+        def processor_for(option_name)
+          @processors.fetch(option_name)
+        end
+
+        private
+
+        # Builds processor instances for all defined options
+        # Always includes TypeValidator even if not explicitly defined
+        #
+        # @return [Hash<Symbol, Option::Base>] Hash of option_name => processor
+        def build_processors # rubocop:disable Metrics/MethodLength
+          processors_hash = {}
+
+          @attribute.options.each do |option_name, option_schema|
+            processor_class = Option::Registry.processor_for(option_name)
+
+            next if processor_class.nil?
+
+            processors_hash[option_name] = processor_class.new(
+              attribute_name: @attribute.name,
+              attribute_type: @attribute.type,
+              option_schema:
+            )
+          end
+
+          # Always include type validator
+          unless processors_hash.key?(:type)
+            processors_hash[:type] = Option::Validators::TypeValidator.new(
+              attribute_name: @attribute.name,
+              attribute_type: @attribute.type,
+              option_schema: nil
+            )
+          end
+
+          processors_hash
+        end
+
+        # Validates that all options are registered in the Registry
+        #
+        # @raise [Treaty::Exceptions::Validation] If unknown options found
+        # @return [void]
+        def validate_known_options!
+          unknown_options = @attribute.options.keys - Option::Registry.all_options
+
+          return if unknown_options.empty?
+
+          raise Treaty::Exceptions::Validation,
+                I18n.t(
+                  "treaty.attributes.options.unknown",
+                  attribute: @attribute.name,
+                  unknown: unknown_options.join(", "),
+                  known: Option::Registry.all_options.join(", ")
+                )
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/validation/attribute_validator.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Validation
+        # Validates and transforms individual attributes.
+        #
+        # ## Purpose
+        #
+        # Acts as the main interface for attribute validation and transformation.
+        # Delegates option processing to OptionOrchestrator and handles nested validation.
+        #
+        # ## Responsibilities
+        #
+        # 1. **Schema Validation** - Validates DSL definition correctness
+        # 2. **Value Validation** - Validates runtime data values
+        # 3. **Value Transformation** - Transforms values (defaults, etc.)
+        # 4. **Name Transformation** - Provides target name (for `as:` option)
+        # 5. **Nested Validation** - Delegates to NestedObjectValidator/NestedArrayValidator
+        #
+        # ## Usage
+        #
+        # Used by Orchestrator to validate each attribute:
+        #
+        #   validator = AttributeValidator.new(attribute)
+        #   validator.validate_schema!
+        #   validator.validate_value!(value)
+        #   transformed = validator.transform_value(value)
+        #   target_name = validator.target_name
+        #
+        # ## Architecture
+        #
+        # Delegates to:
+        # - `OptionOrchestrator` - Coordinates all option processors
+        # - `NestedObjectValidator` - Validates nested object structures
+        # - `NestedArrayValidator` - Validates nested array structures
+        class AttributeValidator
+          attr_reader :attribute, :option_orchestrator
+
+          # Creates a new attribute validator instance
+          #
+          # @param attribute [Attribute::Base] The attribute to validate
+          def initialize(attribute)
+            @attribute = attribute
+            @option_orchestrator = OptionOrchestrator.new(attribute)
+            @nested_object_validator = nil
+            @nested_array_validator = nil
+          end
+
+          # Validates the attribute schema (DSL definition)
+          #
+          # @raise [Treaty::Exceptions::Validation] If schema is invalid
+          # @return [void]
+          def validate_schema!
+            option_orchestrator.validate_schema!
+          end
+
+          # Validates attribute value against all constraints
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If validation fails
+          # @return [void]
+          def validate_value!(value)
+            option_orchestrator.validate_value!(value)
+            validate_nested!(value) if attribute.nested? && !value.nil?
+          end
+
+          # Transforms attribute value through all modifiers
+          #
+          # @param value [Object] The value to transform
+          # @param root_data [Hash] Full raw data from root level (used by computed modifier)
+          # @return [Object] Transformed value
+          def transform_value(value, root_data = {})
+            option_orchestrator.transform_value(value, root_data)
+          end
+
+          # Checks if attribute name is transformed
+          #
+          # @return [Boolean] True if name is transformed (as: option)
+          def transforms_name?
+            option_orchestrator.transforms_name?
+          end
+
+          # Gets the target attribute name
+          #
+          # @return [Symbol] The target name (or original if not transformed)
+          def target_name
+            option_orchestrator.target_name
+          end
+
+          # Validates only the type constraint
+          # Used by nested transformers to validate types before nested validation
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If type validation fails
+          # @return [void]
+          def validate_type!(value)
+            type_processor = option_orchestrator.processor_for(:type)
+            type_processor&.validate_value!(value)
+          end
+
+          # Validates only the required constraint
+          # Used by nested transformers to validate presence before nested validation
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If required validation fails
+          # @return [void]
+          def validate_required!(value)
+            required_processor = option_orchestrator.processor_for(:required)
+            required_processor&.validate_value!(value) if attribute.options.key?(:required)
+          end
+
+          private
+
+          # Validates nested attributes for object/array types
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If nested validation fails
+          # @return [void]
+          def validate_nested!(value)
+            case attribute.type
+            when :object
+              nested_object_validator.validate!(value)
+            when :array
+              nested_array_validator.validate!(value)
+            end
+          end
+
+          # Gets or creates nested object validator
+          #
+          # @return [NestedObjectValidator] Validator for nested objects
+          def nested_object_validator
+            @nested_object_validator ||= NestedObjectValidator.new(attribute)
+          end
+
+          # Gets or creates nested array validator
+          #
+          # @return [NestedArrayValidator] Validator for nested arrays
+          def nested_array_validator
+            @nested_array_validator ||= NestedArrayValidator.new(attribute)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/entity/attribute/validation/base.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    module Attribute
+      module Validation
+        # Base class for request and response validation.
+        #
+        # ## Purpose
+        #
+        # Provides common interface for validation used in Treaty.
+        # Subclasses implement specific validation logic for requests and responses.
+        #
+        # ## Responsibilities
+        #
+        # 1. **Validation Interface** - Defines common validation interface
+        # 2. **Factory Pattern** - Provides class-level validate! method
+        #
+        # ## Subclasses
+        #
+        # - Request::Validation - Validates request data (uses Orchestrator::Request)
+        # - Response::Validation - Validates response data (uses Orchestrator::Response)
+        #
+        # ## Usage
+        #
+        # Subclasses must implement:
+        # - `validate!` - Performs validation and returns transformed data
+        #
+        # Example usage:
+        #   Request::Validation.validate!(version_factory: factory, data: params)
+        #
+        # ## Factory Method
+        #
+        # The `self.validate!(...)` class method provides a convenient factory pattern:
+        # ```ruby
+        # Request::Validation.validate!(version_factory: factory, data: params)
+        # # Equivalent to:
+        # Request::Validation.new(version_factory: factory).validate!(data: params)
+        # ```
+        #
+        # ## Architecture
+        #
+        # Works with:
+        # - VersionFactory - Provides version information
+        # - Orchestrator::Base - Performs actual validation and transformation
+        class Base
+          # Class-level factory method for validation
+          # Creates instance and calls validate!
+          #
+          # @param args [Hash] Arguments passed to initialize and validate!
+          # @return [Hash] Validated and transformed data
+          def self.validate!(...)
+            new(...).validate!
+          end
+
+          # Creates a new validation instance
+          #
+          # @param version_factory [VersionFactory] Factory containing version information
+          def initialize(version_factory:)
+            @version_factory = version_factory
+          end
+
+          # Performs validation and transformation
+          # Must be implemented in subclasses
+          #
+          # @raise [Treaty::Exceptions::NotImplemented] If subclass doesn't implement
+          # @return [Hash] Validated and transformed data
+          def validate!
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.validators.nested.orchestrator.collection_not_implemented")
+          end
+        end
+      end
+    end
+  end
+end