treaty 0.0.1 → 0.2.0

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Treaty
+  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
+        # @return [Object] Transformed value
+        def transform_value(value)
+          option_orchestrator.transform_value(value)
+        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

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

@@ -0,0 +1,92 @@
+# 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 [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
+
+        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,199 @@
+# 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
+
+          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

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