treaty 0.18.0 → 0.20.0

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

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

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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 attribute) 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` attribute)
+        # 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 attribute)
+          # 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
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t(
+                    "treaty.attributes.validators.nested.array.element_validation_error",
+                    attribute: @attribute.name,
+                    index:,
+                    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)
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.validators.nested.array.element_type_error",
+                      attribute: @attribute.name,
+                      index:,
+                      actual: 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
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.validators.nested.array.attribute_error",
+                      attribute: @attribute.name,
+                      index:,
+                      message: 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
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Entity
+    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
+end