treaty 0.0.1 → 0.1.0

data/lib/treaty/attribute/option/validators/type_validator.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Validators
+        # Validates that attribute value matches the declared type.
+        #
+        # ## Supported Types
+        #
+        # - `:integer` - Ruby Integer
+        # - `:string` - Ruby String
+        # - `:object` - Ruby Hash (for nested objects)
+        # - `:array` - Ruby Array (for collections)
+        # - `:datetime` - Ruby DateTime, Time, or Date
+        #
+        # ## Usage Examples
+        #
+        # Simple types:
+        #   integer :age
+        #   string :name
+        #   datetime :created_at
+        #
+        # Nested structures:
+        #   object :author do
+        #     string :name
+        #   end
+        #
+        #   array :tags do
+        #     string :_self  # Simple array of strings
+        #   end
+        #
+        # ## Validation Rules
+        #
+        # - Validates only non-nil values (nil handling is done by RequiredValidator)
+        # - Type mismatch raises Treaty::Exceptions::Validation
+        # - Datetime accepts DateTime, Time, or Date objects
+        #
+        # ## Note
+        #
+        # TypeValidator doesn't use option_schema - it validates based on attribute_type.
+        # This validator is always active for all attributes.
+        class TypeValidator < Treaty::Attribute::Option::Base
+          ALLOWED_TYPES = %i[integer string object array datetime].freeze
+
+          # Validates that the attribute type is one of the allowed types
+          #
+          # @raise [Treaty::Exceptions::Validation] If type is not allowed
+          # @return [void]
+          def validate_schema!
+            return if ALLOWED_TYPES.include?(@attribute_type)
+
+            # TODO: It is necessary to implement a translation system (I18n).
+            raise Treaty::Exceptions::Validation,
+                  "Unknown type '#{@attribute_type}' for attribute '#{@attribute_name}'. " \
+                  "Allowed types: #{ALLOWED_TYPES.join(', ')}"
+          end
+
+          # Validates that the value matches the declared type
+          # Skips validation for nil values (handled by RequiredValidator)
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If value type doesn't match
+          # @return [void]
+          def validate_value!(value) # rubocop:disable Metrics/MethodLength
+            return if value.nil? # Type validation doesn't check for nil, required does.
+
+            case @attribute_type
+            when :integer
+              validate_integer!(value)
+            when :string
+              validate_string!(value)
+            when :object
+              validate_object!(value)
+            when :array
+              validate_array!(value)
+            when :datetime
+              validate_datetime!(value)
+            end
+          end
+
+          private
+
+          # Validates that value is an Integer
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If value is not an Integer
+          # @return [void]
+          def validate_integer!(value)
+            return if value.is_a?(Integer)
+
+            # TODO: It is necessary to implement a translation system (I18n).
+            raise Treaty::Exceptions::Validation,
+                  "Attribute '#{@attribute_name}' must be an Integer, got #{value.class}"
+          end
+
+          # Validates that value is a String
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If value is not a String
+          # @return [void]
+          def validate_string!(value)
+            return if value.is_a?(String)
+
+            # TODO: It is necessary to implement a translation system (I18n).
+            raise Treaty::Exceptions::Validation,
+                  "Attribute '#{@attribute_name}' must be a String, got #{value.class}"
+          end
+
+          # Validates that value is a Hash (object type)
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If value is not a Hash
+          # @return [void]
+          def validate_object!(value)
+            return if value.is_a?(Hash)
+
+            # TODO: It is necessary to implement a translation system (I18n).
+            raise Treaty::Exceptions::Validation,
+                  "Attribute '#{@attribute_name}' must be a Hash (object), got #{value.class}"
+          end
+
+          # Validates that value is an Array
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If value is not an Array
+          # @return [void]
+          def validate_array!(value)
+            return if value.is_a?(Array)
+
+            # TODO: It is necessary to implement a translation system (I18n).
+            raise Treaty::Exceptions::Validation,
+                  "Attribute '#{@attribute_name}' must be an Array, got #{value.class}"
+          end
+
+          # Validates that value is a DateTime, Time, or Date
+          #
+          # @param value [Object] The value to validate
+          # @raise [Treaty::Exceptions::Validation] If value is not a datetime type
+          # @return [void]
+          def validate_datetime!(value)
+            # TODO: It is better to divide it into different methods for each class.
+            return if value.is_a?(DateTime) || value.is_a?(Time) || value.is_a?(Date)
+
+            # TODO: It is necessary to implement a translation system (I18n).
+            raise Treaty::Exceptions::Validation,
+                  "Attribute '#{@attribute_name}' must be a DateTime/Time/Date, got #{value.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/option_normalizer.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Treaty
+  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 }
+      }.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
+        #
+        # @param options [Hash] Options hash in simple or advanced mode
+        # @return [Hash] Normalized options in advanced mode
+        def normalize(options)
+          options.each_with_object({}) do |(key, value), result|
+            advanced_key, normalized_value = normalize_option(key, value)
+            result[advanced_key] = normalized_value
+          end
+        end
+
+        private
+
+        # 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.
+            { value_key => value.fetch(value_key), message: value.fetch(:message, nil) }
+          else
+            # Simple mode, convert to advanced.
+            # TODO: It is necessary to implement a translation system (I18n).
+            { 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

data/lib/treaty/attribute/option_orchestrator.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Treaty
+  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
+      # @return [Object] Transformed value
+      def transform_value(value)
+        @processors.values.reduce(value) do |current_value, processor|
+          processor.transform_value(current_value)
+        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[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 unless processor_class
+
+          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?
+
+        # TODO: It is necessary to implement a translation system (I18n).
+        raise Treaty::Exceptions::Validation,
+              "Unknown options for attribute '#{@attribute.name}': #{unknown_options.join(', ')}. " \
+              "Known options: #{Option::Registry.all_options.join(', ')}"
+      end
+    end
+  end
+end

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