treaty 0.0.1 → 0.1.0

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Validation
+      # Base class for validation strategies (adapter vs non-adapter).
+      #
+      # ## Purpose
+      #
+      # Provides common interface for validation strategies used in Treaty.
+      # Subclasses implement specific validation logic for different strategies.
+      #
+      # ## Responsibilities
+      #
+      # 1. **Strategy Interface** - Defines common validation interface
+      # 2. **Factory Pattern** - Provides class-level validate! method
+      # 3. **Strategy Detection** - Checks if adapter strategy is active
+      #
+      # ## 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)
+      #
+      # ## Strategy Pattern
+      #
+      # The validation system supports two strategies:
+      # - **Adapter Strategy** - Adapts between different API versions
+      # - **Standard Strategy** - Direct version handling
+      #
+      # This base class provides `adapter_strategy?` helper to check current strategy.
+      #
+      # ## 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 and strategy 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 and strategy
+        def initialize(version_factory:)
+          @version_factory = version_factory
+        end
+
+        # Performs validation and transformation
+        # Must be implemented in subclasses
+        #
+        # @raise [NotImplementedError] If subclass doesn't implement
+        # @return [Hash] Validated and transformed data
+        def validate!
+          # TODO: It is necessary to implement a translation system (I18n).
+          raise Treaty::Exceptions::Validation,
+                "Subclass must implement the validate! method"
+        end
+
+        private
+
+        # Checks if adapter strategy is active
+        #
+        # @return [Boolean] True if using adapter strategy
+        def adapter_strategy?
+          @version_factory.strategy_instance.adapter?
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/validation/nested_array_validator.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Validation
+      # Validates array elements against nested attribute definitions.
+      #
+      # ## Purpose
+      #
+      # Performs validation for nested array attributes during the validation phase.
+      # Handles both simple arrays (with :_self scope) and complex arrays (objects).
+      #
+      # ## Responsibilities
+      #
+      # 1. **Simple Array Validation** - Validates primitive values in arrays
+      # 2. **Complex Array Validation** - Validates hash objects within arrays
+      # 3. **Error Context** - Provides clear error messages with array index
+      # 4. **Type Checking** - Ensures elements match expected types
+      #
+      # ## Array Types
+      #
+      # ### Simple Array (`:_self` scope)
+      # Array containing primitive values (strings, integers, etc.)
+      #
+      # ```ruby
+      # array :tags do
+      #   string :_self  # Array of strings
+      # end
+      # ```
+      #
+      # Validates: `["ruby", "rails", "api"]`
+      #
+      # ### Complex Array (regular attributes)
+      # Array containing hash objects with defined structure
+      #
+      # ```ruby
+      # array :authors do
+      #   string :name, :required
+      #   string :email
+      # end
+      # ```
+      #
+      # Validates: `[{ name: "Alice", email: "alice@example.com" }, ...]`
+      #
+      # ## Usage
+      #
+      # Called by AttributeValidator for nested arrays:
+      #
+      #   validator = NestedArrayValidator.new(attribute)
+      #   validator.validate!(array_value)
+      #
+      # ## Error Handling
+      #
+      # Provides contextual error messages including:
+      # - Array attribute name
+      # - Element index (0-based)
+      # - Specific validation error
+      #
+      # Example error:
+      #   "Error in array 'tags' at index 2: Element must match one of the defined types"
+      #
+      # ## Architecture
+      #
+      # Uses:
+      # - `AttributeValidator` - Validates individual elements
+      # - Caches validators for performance
+      # - Separates self validators from regular validators
+      class NestedArrayValidator
+        # Creates a new nested array validator
+        #
+        # @param attribute [Attribute::Base] The array-type attribute with nested attributes
+        def initialize(attribute)
+          @attribute = attribute
+          @self_validators = nil
+          @regular_validators = nil
+        end
+
+        # Validates all items in an array
+        # Skips validation if value is not an Array
+        #
+        # @param array [Array] The array to validate
+        # @raise [Treaty::Exceptions::Validation] If any item validation fails
+        # @return [void]
+        def validate!(array)
+          return unless array.is_a?(Array)
+
+          array.each_with_index do |array_item, index|
+            validate_self_array_item!(array_item, index) if self_validators.any?
+
+            validate_regular_array_item!(array_item, index) if regular_validators.any?
+          end
+        end
+
+        private
+
+        # Validates array item for simple arrays (with :_self scope)
+        # Simple array contains primitive values: strings, integers, datetimes, etc.
+        # Example: ["ruby", "rails", "api"] where each item is a String
+        #
+        # @param array_item [String, Integer, DateTime] Primitive value from simple array
+        # @param index [Integer] Array index for error messages
+        # @raise [Treaty::Exceptions::Validation] If primitive value doesn't match defined type
+        # @return [void]
+        def validate_self_array_item!(array_item, index) # rubocop:disable Metrics/MethodLength
+          errors = []
+
+          validated = self_validators.any? do |validator|
+            validator.validate_value!(array_item)
+            true
+          rescue Treaty::Exceptions::Validation => e
+            errors << e.message
+            false
+          end
+
+          return if validated
+
+          # TODO: It is necessary to implement a translation system (I18n).
+          raise Treaty::Exceptions::Validation,
+                "Error in array '#{@attribute.name}' at index #{index}: " \
+                "Item must match one of the defined types. Errors: #{errors.join('; ')}"
+        end
+
+        # Validates array item for complex arrays (with regular attributes)
+        # Complex array contains hash objects with defined structure
+        # Example: [{ name: "Alice", email: "alice@example.com" }, ...] where each item is a Hash
+        #
+        # @param array_item [Hash] Hash object from complex array
+        # @param index [Integer] Array index for error messages
+        # @raise [Treaty::Exceptions::Validation] If item is not Hash or nested validation fails
+        # @return [void]
+        def validate_regular_array_item!(array_item, index) # rubocop:disable Metrics/MethodLength
+          unless array_item.is_a?(Hash)
+            # TODO: It is necessary to implement a translation system (I18n).
+            raise Treaty::Exceptions::Validation,
+                  "Error in array '#{@attribute.name}' at index #{index}: Expected Hash but got #{array_item.class}"
+          end
+
+          regular_validators.each do |nested_attribute, validator|
+            nested_value = array_item.fetch(nested_attribute.name, nil)
+            validator.validate_value!(nested_value)
+          rescue Treaty::Exceptions::Validation => e
+            # TODO: It is necessary to implement a translation system (I18n).
+            raise Treaty::Exceptions::Validation,
+                  "Error in array '#{@attribute.name}' at index #{index}: #{e.message}"
+          end
+        end
+
+        ########################################################################
+
+        # Gets cached self validators or builds them
+        #
+        # @return [Array<AttributeValidator>] Validators for :_self attributes
+        def self_validators
+          @self_validators ||= build_self_validators
+        end
+
+        # Gets cached regular validators or builds them
+        #
+        # @return [Hash] Hash of nested_attribute => validator
+        def regular_validators
+          @regular_validators ||= build_regular_validators
+        end
+
+        ########################################################################
+
+        # Builds validators for :_self attributes (simple array elements)
+        #
+        # @return [Array<AttributeValidator>] Array of validators
+        def build_self_validators
+          @attribute.collection_of_attributes
+                    .select { |attr| attr.name == :_self }
+                    .map do |self_attribute|
+            validator = AttributeValidator.new(self_attribute)
+            validator.validate_schema!
+            validator
+          end
+        end
+
+        # Builds validators for regular attributes (complex array elements)
+        #
+        # @return [Hash] Hash of nested_attribute => validator
+        def build_regular_validators
+          @attribute.collection_of_attributes
+                    .reject { |attr| attr.name == :_self }
+                    .each_with_object({}) do |nested_attribute, cache|
+            validator = AttributeValidator.new(nested_attribute)
+            validator.validate_schema!
+            cache[nested_attribute] = validator
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/validation/nested_object_validator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Validation
+      # Validates nested object (hash) attributes against their defined structure.
+      #
+      # ## Purpose
+      #
+      # Performs validation for nested object attributes during the validation phase.
+      # Ensures hash values conform to the nested attribute definitions.
+      #
+      # ## Responsibilities
+      #
+      # 1. **Structure Validation** - Validates hash structure matches definition
+      # 2. **Attribute Validation** - Validates each nested attribute's value
+      # 3. **Type Safety** - Ensures value is a Hash before validation
+      # 4. **Validator Caching** - Builds and caches validators for performance
+      #
+      # ## Usage
+      #
+      # Used for object-type attributes with nested definitions:
+      #
+      # ```ruby
+      # object :author do
+      #   string :name, :required
+      #   string :email
+      #   integer :age
+      # end
+      # ```
+      #
+      # Validates: `{ name: "Alice", email: "alice@example.com", age: 30 }`
+      #
+      # ## Usage in Code
+      #
+      # Called by AttributeValidator for nested objects:
+      #
+      #   validator = NestedObjectValidator.new(attribute)
+      #   validator.validate!(hash_value)
+      #
+      # ## Validation Flow
+      #
+      # 1. Check if value is a Hash
+      # 2. Build validators for all nested attributes (cached)
+      # 3. For each nested attribute:
+      #    - Extract value from hash
+      #    - Validate using AttributeValidator
+      # 4. Raise exception if any validation fails
+      #
+      # ## Architecture
+      #
+      # Uses:
+      # - `AttributeValidator` - Validates individual nested attributes
+      # - Caches validators to avoid rebuilding on each validation
+      class NestedObjectValidator
+        attr_reader :attribute
+
+        # Creates a new nested object validator
+        #
+        # @param attribute [Attribute::Base] The object-type attribute with nested attributes
+        def initialize(attribute)
+          @attribute = attribute
+          @validators_cache = nil
+        end
+
+        # Validates all nested attributes in a hash
+        # Skips validation if value is not a Hash
+        #
+        # @param hash [Hash] The hash to validate
+        # @raise [Treaty::Exceptions::Validation] If any nested validation fails
+        # @return [void]
+        def validate!(hash)
+          return unless hash.is_a?(Hash)
+
+          validators.each do |nested_attribute, nested_validator|
+            nested_value = hash.fetch(nested_attribute.name, nil)
+            nested_validator.validate_value!(nested_value)
+          end
+        end
+
+        private
+
+        # Gets cached validators or builds them
+        #
+        # @return [Hash] Hash of nested_attribute => validator
+        def validators
+          @validators ||= build_validators
+        end
+
+        # Builds validators for all nested attributes
+        #
+        # @return [Hash] Hash of nested_attribute => validator
+        def build_validators
+          attribute.collection_of_attributes.each_with_object({}) do |nested_attribute, cache|
+            validator = AttributeValidator.new(nested_attribute)
+            validator.validate_schema!
+            cache[nested_attribute] = validator
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/validation/nested_transformer.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Validation
+      # Handles transformation of nested attributes (objects and arrays).
+      # Extracted from Orchestrator::Base to reduce complexity.
+      class NestedTransformer
+        SELF_SCOPE = :_self
+        private_constant :SELF_SCOPE
+
+        attr_reader :attribute
+
+        # Creates a new nested transformer
+        #
+        # @param attribute [Attribute::Base] The attribute with nested structure
+        def initialize(attribute)
+          @attribute = attribute
+        end
+
+        # Transforms nested attribute value (object or array)
+        # Returns original value if nil or not nested
+        #
+        # @param value [Object] The value to transform
+        # @return [Object] Transformed value
+        def transform(value)
+          return value if value.nil?
+
+          case attribute.type
+          when :object
+            transform_object(value)
+          when :array
+            transform_array(value)
+          else
+            value
+          end
+        end
+
+        private
+
+        # Transforms object (hash) value
+        #
+        # @param value [Hash] The hash to transform
+        # @return [Hash] Transformed hash
+        def transform_object(value)
+          return value unless attribute.nested?
+
+          transformer = ObjectTransformer.new(attribute)
+          transformer.transform(value)
+        end
+
+        # Transforms array value
+        #
+        # @param value [Array] The array to transform
+        # @return [Array] Transformed array
+        def transform_array(value)
+          return value unless attribute.nested?
+
+          transformer = ArrayTransformer.new(attribute)
+          transformer.transform(value)
+        end
+
+        # Transforms object (hash) with nested attributes
+        class ObjectTransformer
+          attr_reader :attribute
+
+          # Creates a new object transformer
+          #
+          # @param attribute [Attribute::Base] The object-type attribute
+          def initialize(attribute)
+            @attribute = attribute
+          end
+
+          # Transforms hash by processing all nested attributes
+          #
+          # @param value [Hash] The source hash
+          # @return [Hash] Transformed hash with processed attributes
+          def transform(value)
+            transformed = {}
+
+            attribute.collection_of_attributes.each do |nested_attribute|
+              process_attribute(nested_attribute, value, transformed)
+            end
+
+            transformed
+          end
+
+          private
+
+          # Processes a single nested attribute
+          # Validates, transforms, and adds to target hash
+          #
+          # @param nested_attribute [Attribute::Base] Attribute to process
+          # @param source_hash [Hash] Source data
+          # @param target_hash [Hash] Target hash to populate
+          # @return [void]
+          def process_attribute(nested_attribute, source_hash, target_hash) # rubocop:disable Metrics/MethodLength
+            source_name = nested_attribute.name
+            nested_value = source_hash.fetch(source_name, nil)
+
+            validator = AttributeValidator.new(nested_attribute)
+            validator.validate_schema!
+
+            transformed_value = if nested_attribute.nested?
+                                  nested_transformer = NestedTransformer.new(nested_attribute)
+                                  validator.validate_type!(nested_value) unless nested_value.nil?
+                                  validator.validate_required!(nested_value)
+                                  nested_transformer.transform(nested_value)
+                                else
+                                  validator.validate_value!(nested_value)
+                                  validator.transform_value(nested_value)
+                                end
+
+            target_name = validator.target_name
+            target_hash[target_name] = transformed_value
+          end
+        end
+
+        # Transforms array with nested attributes
+        class ArrayTransformer
+          SELF_SCOPE = :_self
+          private_constant :SELF_SCOPE
+
+          attr_reader :attribute
+
+          # Creates a new array transformer
+          #
+          # @param attribute [Attribute::Base] The array-type attribute
+          def initialize(attribute)
+            @attribute = attribute
+          end
+
+          # Transforms array by processing each element
+          # Handles both simple arrays (:_self) and complex arrays (objects)
+          #
+          # @param value [Array] The source array
+          # @return [Array] Transformed array
+          def transform(value)
+            value.each_with_index.map do |item, index|
+              if simple_array?
+                validate_simple_element(item, index)
+                item
+              else
+                transform_array_item(item, index)
+              end
+            end
+          end
+
+          private
+
+          # Checks if this is a simple array (primitive values)
+          #
+          # @return [Boolean] True if array contains primitive values with :_self scope
+          def simple_array?
+            attribute.collection_of_attributes.size == 1 &&
+              attribute.collection_of_attributes.first.name == SELF_SCOPE
+          end
+
+          # Validates a simple array element (primitive value)
+          #
+          # @param item [Object] Array element to validate
+          # @param index [Integer] Element index for error messages
+          # @raise [Treaty::Exceptions::Validation] If validation fails
+          # @return [void]
+          def validate_simple_element(item, index) # rubocop:disable Metrics/MethodLength
+            self_attr = attribute.collection_of_attributes.first
+            validator = AttributeValidator.new(self_attr)
+            validator.validate_schema!
+
+            begin
+              validator.validate_value!(item)
+            rescue Treaty::Exceptions::Validation => e
+              raise Treaty::Exceptions::Validation,
+                    "Error in array '#{attribute.name}' at index #{index}: " \
+                    "Element must match one of the defined types. " \
+                    "Errors: #{e.message}"
+            end
+          end
+
+          # Transforms a complex array element (hash object)
+          #
+          # @param item [Hash] Array element to transform
+          # @param index [Integer] Element index for error messages
+          # @raise [Treaty::Exceptions::Validation] If item is not a Hash
+          # @return [Hash] Transformed hash
+          def transform_array_item(item, index)
+            unless item.is_a?(Hash)
+              raise Treaty::Exceptions::Validation,
+                    "Error in array '#{attribute.name}' at index #{index}: " \
+                    "Expected Hash but got #{item.class}"
+            end
+
+            transformed = {}
+
+            attribute.collection_of_attributes.each do |nested_attribute|
+              process_attribute(nested_attribute, item, transformed, index)
+            end
+
+            transformed
+          end
+
+          # Processes a single nested attribute in array element
+          # Validates, transforms, and adds to target hash
+          #
+          # @param nested_attribute [Attribute::Base] Attribute to process
+          # @param source_hash [Hash] Source data
+          # @param target_hash [Hash] Target hash to populate
+          # @param index [Integer] Array index for error messages
+          # @raise [Treaty::Exceptions::Validation] If validation fails
+          # @return [void]
+          def process_attribute(nested_attribute, source_hash, target_hash, index) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            source_name = nested_attribute.name
+            nested_value = source_hash.fetch(source_name, nil)
+
+            validator = AttributeValidator.new(nested_attribute)
+            validator.validate_schema!
+
+            begin
+              transformed_value = if nested_attribute.nested?
+                                    nested_transformer = NestedTransformer.new(nested_attribute)
+                                    validator.validate_type!(nested_value) unless nested_value.nil?
+                                    validator.validate_required!(nested_value)
+                                    nested_transformer.transform(nested_value)
+                                  else
+                                    validator.validate_value!(nested_value)
+                                    validator.transform_value(nested_value)
+                                  end
+            rescue Treaty::Exceptions::Validation => e
+              raise Treaty::Exceptions::Validation,
+                    "Error in array '#{attribute.name}' at index #{index}: #{e.message}"
+            end
+
+            target_name = validator.target_name
+            target_hash[target_name] = transformed_value
+          end
+        end
+      end
+    end
+  end
+end