treaty 0.0.1 → 0.2.0

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

@@ -0,0 +1,246 @@
+# 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,
+                    I18n.t("treaty.attributes.validators.nested.array.element_validation_error",
+                           attribute: attribute.name,
+                           index:,
+                           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) # rubocop:disable Metrics/MethodLength
+            unless item.is_a?(Hash)
+              raise Treaty::Exceptions::Validation,
+                    I18n.t("treaty.attributes.validators.nested.array.element_type_error",
+                           attribute: attribute.name,
+                           index:,
+                           actual: 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,
+                    I18n.t("treaty.attributes.validators.nested.array.attribute_error",
+                           attribute: attribute.name,
+                           index:,
+                           message: e.message)
+            end
+
+            target_name = validator.target_name
+            target_hash[target_name] = transformed_value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Validation
+      module Orchestrator
+        # Base orchestrator for validating and transforming data according to treaty definitions.
+        #
+        # ## Purpose
+        #
+        # Coordinates the validation and transformation of request/response data for a specific
+        # API version. Processes all scopes and their attributes, applying validations and
+        # transformations defined in the treaty DSL.
+        #
+        # ## Responsibilities
+        #
+        # 1. **Scope Processing** - Iterates through all defined scopes
+        # 2. **Attribute Validation** - Validates each attribute's value
+        # 3. **Data Transformation** - Transforms values (defaults, renaming)
+        # 4. **Nested Handling** - Delegates nested structures to NestedTransformer
+        # 5. **Result Assembly** - Builds final transformed data structure
+        #
+        # ## Usage
+        #
+        # Subclasses must implement:
+        # - `collection_of_scopes` - Returns scopes for this context (request/response)
+        # - `scope_data_for(name)` - Extracts data for a specific scope
+        #
+        # Example:
+        #   orchestrator = Request::Orchestrator.new(version_factory: factory, data: params)
+        #   validated_data = orchestrator.validate!
+        #
+        # ## Special Scopes
+        #
+        # - Normal scope: `{ scope_name: { ... } }`
+        # - Self scope (`:_self`): Attributes merged directly into parent
+        #
+        # ## Architecture
+        #
+        # Uses:
+        # - `AttributeValidator` - Validates individual attributes
+        # - `NestedTransformer` - Handles nested objects and arrays
+        #
+        # The refactored design separates concerns:
+        # - Orchestrator: High-level flow and scope iteration
+        # - Validator: Individual attribute validation
+        # - Transformer: Nested structure transformation
+        class Base
+          SELF_SCOPE = :_self
+          private_constant :SELF_SCOPE
+
+          attr_reader :version_factory, :data
+
+          # Class-level factory method for validation
+          # Creates instance and calls validate!
+          #
+          # @param args [Hash] Arguments passed to initialize
+          # @return [Hash] Validated and transformed data
+          def self.validate!(...)
+            new(...).validate!
+          end
+
+          # Creates a new orchestrator instance
+          #
+          # @param version_factory [VersionFactory] Factory containing version info
+          # @param data [Hash] Data to validate and transform (default: {})
+          def initialize(version_factory:, data: {})
+            @version_factory = version_factory
+            @data = data
+          end
+
+          # Validates and transforms all scopes
+          # Iterates through scopes, processes attributes, handles :_self scope
+          #
+          # @return [Hash] Transformed data with all scopes processed
+          def validate!
+            transformed_data = {}
+
+            collection_of_scopes.each do |scope_factory|
+              transformed_scope_data = validate_and_transform_scope!(scope_factory)
+              transformed_data[scope_factory.name] = transformed_scope_data if scope_factory.name != SELF_SCOPE
+              transformed_data.merge!(transformed_scope_data) if scope_factory.name == SELF_SCOPE
+            end
+
+            transformed_data
+          end
+
+          private
+
+          # Returns collection of scopes for this context
+          # Must be implemented in subclasses
+          #
+          # @raise [Treaty::Exceptions::Validation] If not implemented
+          # @return [Array<ScopeFactory>] Collection of scope factories
+          def collection_of_scopes
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.validators.nested.orchestrator.collection_not_implemented")
+          end
+
+          # Validates all attributes in a scope (deprecated, not used)
+          #
+          # @param scope_factory [ScopeFactory] The scope to validate
+          # @return [void]
+          def validate_scope!(scope_factory)
+            scope_data = scope_data_for(scope_factory.name)
+
+            validators_for_scope(scope_factory).each do |attribute, validator|
+              value = scope_data.fetch(attribute.name, nil)
+              validator.validate_value!(value)
+            end
+          end
+
+          # Gets cached validators for scope or builds them
+          #
+          # @param scope_factory [ScopeFactory] The scope factory
+          # @return [Hash] Hash of attribute => validator
+          def validators_for_scope(scope_factory)
+            @validators_cache ||= {}
+            @validators_cache[scope_factory] ||= build_validators_for_scope(scope_factory)
+          end
+
+          # Builds validators for all attributes in a scope
+          #
+          # @param scope_factory [ScopeFactory] The scope factory
+          # @return [Hash] Hash of attribute => validator
+          def build_validators_for_scope(scope_factory)
+            scope_factory.collection_of_attributes.each_with_object({}) do |attribute, cache|
+              validator = AttributeValidator.new(attribute)
+              validator.validate_schema!
+              cache[attribute] = validator
+            end
+          end
+
+          # Extracts data for a specific scope
+          # Must be implemented in subclasses
+          #
+          # @param _name [Symbol] The scope name
+          # @raise [Treaty::Exceptions::Validation] If not implemented
+          # @return [Hash] Scope data
+          def scope_data_for(_name)
+            raise Treaty::Exceptions::Validation,
+                  I18n.t("treaty.attributes.validators.nested.orchestrator.scope_data_not_implemented")
+          end
+
+          # Validates and transforms all attributes in a scope
+          # Handles both nested and regular attributes
+          #
+          # @param scope_factory [ScopeFactory] The scope to process
+          # @return [Hash] Transformed scope data
+          def validate_and_transform_scope!(scope_factory) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            scope_data = scope_data_for(scope_factory.name)
+
+            return scope_data if scope_factory.collection_of_attributes.empty?
+
+            transformed_scope_data = {}
+
+            validators_for_scope(scope_factory).each do |attribute, validator|
+              source_name = attribute.name
+              value = scope_data.fetch(source_name, nil)
+
+              if attribute.nested?
+                transformed_value = validate_and_transform_nested(attribute, value, validator)
+              else
+                validator.validate_value!(value)
+                transformed_value = validator.transform_value(value)
+              end
+
+              target_name = validator.target_name
+
+              transformed_scope_data[target_name] = transformed_value
+            end
+
+            transformed_scope_data
+          end
+
+          # Validates and transforms nested attribute (object/array)
+          # Delegates transformation to NestedTransformer
+          #
+          # @param attribute [Attribute::Base] The nested attribute
+          # @param value [Object] The value to validate and transform
+          # @param validator [AttributeValidator] The validator instance
+          # @return [Object] Transformed nested value
+          def validate_and_transform_nested(attribute, value, validator)
+            validator.validate_type!(value) unless value.nil?
+            validator.validate_required!(value)
+
+            transformer = NestedTransformer.new(attribute)
+            transformer.transform(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/base.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Treaty
+  class Base
+    include Info::DSL
+    include Context::DSL
+    include Versions::DSL
+  end
+end

data/lib/treaty/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Treaty
+  class Configuration
+    include ::ActiveModel::Validations
+
+    attr_accessor :version
+
+    attr_reader :attribute_nesting_level
+
+    def initialize
+      @version = ->(context) { context }
+
+      @attribute_nesting_level = 5
+    end
+  end
+end

data/lib/treaty/context/callable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Context
+    module Callable
+      def call!(controller:, params:)
+        context = send(:new)
+
+        _call!(context, controller:, params:)
+      end
+
+      private
+
+      def _call!(context, controller:, params:)
+        context.send(
+          :_call!,
+          controller:,
+          params:,
+          collection_of_versions:
+        )
+      end
+    end
+  end
+end

data/lib/treaty/context/dsl.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Context
+    module DSL
+      def self.included(base)
+        base.extend(Callable)
+        base.include(Workspace)
+      end
+    end
+  end
+end

data/lib/treaty/context/workspace.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Context
+    module Workspace
+      private
+
+      def _call!(
+        controller:,
+        params:,
+        collection_of_versions:
+      )
+        call!(
+          controller:,
+          params:,
+          collection_of_versions:
+        )
+      end
+
+      def call!(
+        collection_of_versions:,
+        **
+      )
+        @collection_of_versions = collection_of_versions
+      end
+    end
+  end
+end

data/lib/treaty/controller/dsl.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Controller
+    module DSL
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.include(InstanceMethods)
+      end
+
+      module ClassMethods
+        private
+
+        def treaty(action_name)
+          define_method(action_name) do
+            treaty = treaty_class.call!(controller: self, params:)
+
+            render json: treaty.data, status: treaty.status
+          end
+        end
+      end
+
+      module InstanceMethods
+        def treaty_class
+          treaty_class_name.constantize
+        rescue NameError
+          raise Treaty::Exceptions::ClassName,
+                I18n.t("treaty.controller.treaty_class_not_found", class_name: treaty_class_name)
+        end
+
+        def treaty_class_name
+          # TODO: Need to move `Treaty` to configuration.
+          self.class.name.sub(/Controller$/, "::#{action_name.to_s.classify}Treaty")
+        end
+      end
+    end
+  end
+end

data/lib/treaty/engine.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Treaty
+  class Engine < ::Rails::Engine
+    isolate_namespace Treaty
+
+    config.treaty = Treaty::Configuration.new
+
+    def self.configure
+      yield(config.treaty) if block_given?
+    end
+
+    initializer "treaty.register_option_processors", before: :load_config_initializers do
+      # Register all option processors (validators and modifiers)
+      require "treaty/attribute/option/registry_initializer"
+    end
+
+    initializer "treaty.validate_configuration" do
+      config.after_initialize do
+        unless config.treaty.valid?
+          errors = config.treaty.errors.full_messages
+          raise "Invalid Treaty configuration: #{errors.join(', ')}"
+        end
+      end
+    end
+
+    initializer "treaty.controller_methods" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include Treaty::Controller::DSL
+      end
+
+      ActiveSupport.on_load(:action_controller_api) do
+        include Treaty::Controller::DSL
+      end
+    end
+  end
+end

data/lib/treaty/exceptions/base.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Exceptions
+    # Base exception class for all Treaty-specific exceptions
+    #
+    # ## Purpose
+    #
+    # Serves as the parent class for all custom exceptions in the Treaty gem.
+    # Allows catching all Treaty-related exceptions with a single rescue clause.
+    #
+    # ## Usage
+    #
+    # All Treaty exceptions inherit from this base class:
+    #
+    # ```ruby
+    # begin
+    #   Treaty::Base.call!(controller: self, params: params)
+    # rescue Treaty::Exceptions::Base => e
+    #   # Catches any Treaty-specific exception
+    #   handle_treaty_error(e)
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be used in application controllers for centralized error handling:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::Base, with: :handle_treaty_error
+    # ```
+    #
+    # ## Subclasses
+    #
+    # - Validation - Attribute validation errors
+    # - Execution - Service execution errors
+    # - Deprecated - API version deprecation
+    # - Strategy - Invalid strategy specification
+    # - ClassName - Treaty class not found
+    # - MethodName - Unknown method in DSL
+    # - NestedAttributes - Nesting depth exceeded
+    # - NotImplemented - Abstract method not implemented
+    # - Unexpected - General unexpected errors
+    class Base < StandardError
+    end
+  end
+end