treaty 0.19.0 → 0.20.0

data/lib/treaty/action/response/attribute/attribute.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Response
+      module Attribute
+        # Response-specific attribute definition.
+        #
+        # ## Purpose
+        #
+        # Extends Entity::Attribute::Base with Response-specific behavior.
+        # Key difference: attributes are **optional by default**.
+        #
+        # ## Default Behavior
+        #
+        # Unlike Request attributes (required by default), Response attributes
+        # default to `required: false`. This allows flexible response structures
+        # where not all fields must be present.
+        #
+        # ## Usage
+        #
+        # Created internally by:
+        # - Response::Attribute::Builder (when defining nested attributes)
+        # - Response::Entity (when defining top-level attributes)
+        #
+        # ## Nesting
+        #
+        # Object and array types create nested builders:
+        #
+        #   response 200 do
+        #     object :post do           # Creates Attribute with nested builder
+        #       string :title           # Nested attribute (optional by default)
+        #       array :comments do      # Nested array
+        #         object :_self do      # Array element definition
+        #           string :text
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # ## Example
+        #
+        #   # These are equivalent:
+        #   string :title               # optional by default
+        #   string :title, :optional    # explicit optional
+        #
+        #   # Must explicitly mark required:
+        #   string :id, :required
+        class Attribute < Treaty::Entity::Attribute::Base
+          private
+
+          # Sets default required behavior for response attributes
+          #
+          # Response attributes are optional by default (is: false).
+          # This can be overridden with `:required` helper or `required: true`.
+          #
+          # @return [void]
+          def apply_defaults!
+            @options[:required] ||= { is: false, message: nil }
+          end
+
+          # Creates nested builder for object/array type processing
+          #
+          # When a block is given to object or array attributes,
+          # creates a Builder to process the nested attribute definitions.
+          #
+          # @param block [Proc] Block containing nested attribute definitions
+          # @return [void]
+          def process_nested_attributes(&block)
+            return unless object_or_array?
+
+            builder = Builder.new(collection_of_attributes, @nesting_level + 1)
+            builder.instance_eval(&block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/response/attribute/builder.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Response
+      module Attribute
+        # DSL builder for defining response attributes.
+        #
+        # ## Purpose
+        #
+        # Provides Response-specific implementation of the attribute builder.
+        # Creates Response::Attribute::Attribute instances instead of generic ones.
+        #
+        # ## Inheritance
+        #
+        # Extends Treaty::Entity::Attribute::Builder::Base which provides:
+        # - DSL interface (string, integer, object, array, etc.)
+        # - method_missing magic for type-based method calls
+        # - Helper support (:required, :optional)
+        # - Entity reuse via use_entity
+        #
+        # ## Usage
+        #
+        # Used internally by:
+        # - Response::Attribute::Attribute (when processing nested object/array blocks)
+        #
+        # ## DSL Example
+        #
+        #   response 201 do
+        #     object :post do
+        #       string :id
+        #       string :title
+        #       datetime :created_at
+        #     end
+        #   end
+        #
+        # ## Methods
+        #
+        # Implements abstract methods from base class:
+        # - `create_attribute` - Creates Response::Attribute::Attribute
+        # - `deep_copy_attribute` - Deep copies attribute for use_entity support
+        class Builder < Treaty::Entity::Attribute::Builder::Base
+          private
+
+          # Creates a new response attribute instance
+          #
+          # Called by base class when defining attributes via DSL.
+          #
+          # @param name [Symbol] Attribute name
+          # @param type [Symbol] Attribute type (:string, :integer, :object, etc.)
+          # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+          # @param nesting_level [Integer] Current nesting depth
+          # @param options [Hash] Attribute options (default:, format:, etc.)
+          # @param block [Proc] Block for nested attributes (object/array)
+          # @return [Treaty::Action::Response::Attribute::Attribute] Created attribute instance
+          def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
+            Attribute.new(
+              name,
+              type,
+              *helpers,
+              nesting_level:,
+              **options,
+              &block
+            )
+          end
+
+          # Deep copies an attribute with adjusted nesting level
+          #
+          # Used when copying attributes from Entity classes via use_entity.
+          # Recursively copies nested attributes for object/array types.
+          #
+          # @param source_attribute [Treaty::Entity::Attribute::Base] Source attribute to copy
+          # @param new_nesting_level [Integer] Nesting level for copied attribute
+          # @return [Treaty::Action::Response::Attribute::Attribute] Deep copied attribute
+          def deep_copy_attribute(source_attribute, new_nesting_level) # rubocop:disable Metrics/MethodLength
+            copied = Attribute.new(
+              source_attribute.name,
+              source_attribute.type,
+              nesting_level: new_nesting_level,
+              **deep_copy_options(source_attribute.options)
+            )
+
+            return copied unless source_attribute.nested?
+
+            source_attribute.collection_of_attributes.each do |nested_source|
+              nested_copied = deep_copy_attribute(nested_source, new_nesting_level + 1)
+              copied.collection_of_attributes << nested_copied
+            end
+
+            copied
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/response/entity.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Response
+      # Internal entity class for response attribute definitions.
+      #
+      # ## Purpose
+      #
+      # Provides DSL interface for defining response attributes when using
+      # inline block syntax in treaty definitions. Serves as the anonymous
+      # class base when `response STATUS do ... end` is used.
+      #
+      # ## Usage
+      #
+      # Created internally by:
+      # - Response::Factory (when using inline DSL blocks)
+      #
+      # ## DSL Interface
+      #
+      # Includes Treaty::Entity::Attribute::DSL which provides:
+      # - Type methods: string, integer, boolean, date, time, datetime
+      # - Structure methods: object, array
+      # - Helper support: :required, :optional
+      #
+      # ## Difference from Treaty::Entity::Base
+      #
+      # While Treaty::Entity::Base creates standalone entity classes,
+      # Response::Entity creates Response-specific attributes with:
+      # - Optional by default behavior
+      # - Response::Attribute::Attribute instances
+      #
+      # ## Example
+      #
+      #   # When you write:
+      #   version 1 do
+      #     response 201 do
+      #       object :post do
+      #         string :id
+      #         string :title
+      #       end
+      #     end
+      #   end
+      #
+      #   # Factory creates: Class.new(Response::Entity)
+      #   # and calls string, object etc. on it
+      class Entity
+        include Treaty::Entity::Attribute::DSL
+
+        class << self
+          private
+
+          # Creates response-specific attribute instances
+          #
+          # Called by DSL methods (string, integer, etc.) to create
+          # Response::Attribute::Attribute instead of generic attributes.
+          #
+          # @param name [Symbol] Attribute name
+          # @param type [Symbol] Attribute type
+          # @param helpers [Array<Symbol>] Helper symbols (:required, :optional)
+          # @param nesting_level [Integer] Current nesting depth
+          # @param options [Hash] Attribute options
+          # @param block [Proc] Block for nested attributes
+          # @return [Treaty::Action::Response::Attribute::Attribute] Created attribute
+          def create_attribute(name, type, *helpers, nesting_level:, **options, &block)
+            Attribute::Attribute.new(
+              name,
+              type,
+              *helpers,
+              nesting_level:,
+              **options,
+              &block
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/response/factory.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Response
+      # Factory for creating response attribute collections.
+      #
+      # ## Purpose
+      #
+      # Captures response attribute definitions from treaty DSL and provides
+      # access to the resulting attribute collection. Supports both inline
+      # block syntax and Entity class references.
+      #
+      # ## Difference from Request::Factory
+      #
+      # Response::Factory stores HTTP status code along with attributes.
+      # This allows treaty to validate responses against expected status.
+      #
+      # ## Usage
+      #
+      # Created internally by:
+      # - Versions::Factory (when `response STATUS do ... end` is called)
+      #
+      # Consumed by:
+      # - Response::Validator (to validate service output)
+      # - Info::Builder (to build response schema information)
+      # - Versions::Execution::Base (to set response status)
+      #
+      # ## Definition Modes
+      #
+      # ### Inline Block Mode
+      #
+      #   response 201 do
+      #     object :post do
+      #       string :id
+      #       string :title
+      #     end
+      #   end
+      #
+      # ### Entity Class Mode
+      #
+      #   response 201, Posts::Create::ResponseEntity
+      #
+      # ## Example
+      #
+      #   factory = Response::Factory.new(201)
+      #   factory.status  # => 201
+      #   factory.object :post do
+      #     factory.string :id
+      #   end
+      #   factory.collection_of_attributes  # => Collection with post attribute
+      class Factory
+        # @return [Integer] HTTP status code for this response
+        attr_reader :status
+
+        # Creates new response factory with HTTP status
+        #
+        # @param status [Integer] HTTP status code (200, 201, 404, etc.)
+        def initialize(status)
+          @status = status
+        end
+
+        # Registers an Entity class for response schema
+        #
+        # Use this to reference a pre-defined Entity class instead of
+        # inline attribute definitions.
+        #
+        # @param entity_class [Class] Must be Treaty::Entity::Base subclass
+        # @raise [Treaty::Exceptions::Validation] If entity_class is invalid
+        # @return [void]
+        def use_entity(entity_class)
+          validate_entity_class!(entity_class)
+          @entity_class = entity_class
+        end
+
+        # Returns the collection of defined attributes
+        #
+        # @return [Treaty::Entity::Attribute::Collection] Attribute collection
+        def collection_of_attributes
+          return Treaty::Entity::Attribute::Collection.new if @entity_class.nil?
+
+          @entity_class.collection_of_attributes
+        end
+
+        # Forwards DSL method calls to internal Entity class
+        #
+        # Creates an anonymous Entity class on first call, then forwards
+        # all DSL methods (string, integer, object, etc.) to it.
+        #
+        # @param type [Symbol] Attribute type (method name)
+        # @param helpers [Array] Helper symbols and arguments
+        # @param options [Hash] Attribute options
+        # @param block [Proc] Block for nested attributes
+        # @return [void]
+        def method_missing(type, *helpers, **options, &block)
+          @entity_class ||= Class.new(Entity)
+
+          @entity_class.public_send(type, *helpers, **options, &block)
+        end
+
+        # Checks if method should be handled by method_missing
+        #
+        # @param name [Symbol] Method name
+        # @return [Boolean]
+        def respond_to_missing?(name, *)
+          super
+        end
+
+        private
+
+        # Validates that entity_class is a Treaty::Entity::Base subclass
+        #
+        # @param entity_class [Class] Class to validate
+        # @raise [Treaty::Exceptions::Validation] If validation fails
+        # @return [void]
+        def validate_entity_class!(entity_class)
+          return if entity_class.is_a?(Class) && entity_class < Treaty::Entity::Base
+
+          raise Treaty::Exceptions::Validation,
+                I18n.t(
+                  "treaty.response.factory.invalid_entity_class",
+                  type: entity_class.class,
+                  value: entity_class
+                )
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/response/validator.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Response
+      # Validates service response data against schema.
+      #
+      # ## Purpose
+      #
+      # Validates response data from service execution against the response
+      # schema defined in the treaty version. Ensures service output matches
+      # the documented API contract.
+      #
+      # ## Usage
+      #
+      # Called internally by:
+      # - Versions::Execution::Response (after service execution)
+      #
+      # ## Validation Flow
+      #
+      # 1. Check if response schema is defined
+      # 2. Create dynamic Orchestrator with version's response attributes
+      # 3. Run validation pipeline (validate + transform)
+      # 4. Return validated/transformed data or raise error
+      #
+      # ## Error Handling
+      #
+      # Raises Treaty::Exceptions::Validation with detailed messages
+      # including attribute path and specific validation failures.
+      #
+      # ## Difference from Request::Validator
+      #
+      # - Validates service output, not controller params
+      # - Response attributes are optional by default
+      # - Used after service execution, not before
+      #
+      # ## Example
+      #
+      #   # Typically called via class method:
+      #   validated = Response::Validator.validate!(
+      #     version_factory: version_factory,
+      #     response_data: service_result
+      #   )
+      #
+      #   # validated contains transformed response for client
+      class Validator
+        class << self
+          # Validates response data
+          #
+          # @param version_factory [Treaty::Action::Versions::Factory] Version with response schema
+          # @param response_data [Hash] Response data from service
+          # @return [Hash] Validated and transformed response
+          # @raise [Treaty::Exceptions::Validation] If validation fails
+          def validate!(version_factory:, response_data: {})
+            new(version_factory:, response_data:).validate!
+          end
+        end
+
+        # Creates new validator instance
+        #
+        # @param version_factory [Treaty::Action::Versions::Factory] Version with response schema
+        # @param response_data [Hash] Response data to validate
+        def initialize(version_factory:, response_data: {})
+          @version_factory = version_factory
+          @response_data = response_data
+        end
+
+        # Runs validation pipeline
+        #
+        # @return [Hash] Validated and transformed response
+        # @raise [Treaty::Exceptions::Validation] If validation fails
+        def validate!
+          validate_response_attributes!
+        end
+
+        private
+
+        # Validates and transforms response data
+        #
+        # Creates dynamic Orchestrator class that uses version's response
+        # attributes for validation. Returns raw data if no schema defined.
+        #
+        # @return [Hash] Validated and transformed data
+        # @raise [Treaty::Exceptions::Validation] If validation fails
+        def validate_response_attributes!
+          return @response_data unless response_attributes_exist?
+
+          orchestrator_class = Class.new(Treaty::Entity::Attribute::Validation::Orchestrator::Base) do
+            define_method(:collection_of_attributes) do
+              @version_factory.response_factory.collection_of_attributes
+            end
+          end
+
+          orchestrator_class.validate!(
+            version_factory: @version_factory,
+            data: @response_data
+          )
+        end
+
+        # Checks if response schema is defined for this version
+        #
+        # @return [Boolean] True if response attributes exist
+        def response_attributes_exist?
+          return false if @version_factory.response_factory&.collection_of_attributes&.empty?
+
+          @version_factory.response_factory.collection_of_attributes.exists?
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/result.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    # Value object returned from treaty execution.
+    #
+    # ## Purpose
+    #
+    # Encapsulates the result of a treaty call, containing validated
+    # response data, HTTP status code, and resolved version. This is
+    # the primary return type from `Treaty.call!`.
+    #
+    # ## Usage
+    #
+    # Created by:
+    # - Versions::Workspace (at the end of treaty execution)
+    #
+    # Consumed by:
+    # - Controller::DSL (to render JSON response)
+    # - Test assertions (to verify treaty behavior)
+    #
+    # ## Attributes
+    #
+    # | Attribute | Description |
+    # |-----------|-------------|
+    # | `data` | Validated and transformed response hash |
+    # | `status` | HTTP status code from response definition |
+    # | `version` | Resolved Gem::Version object |
+    #
+    # ## Example
+    #
+    #   result = Posts::CreateTreaty.call!(
+    #     version: "1",
+    #     params: { post: { title: "Hello" } }
+    #   )
+    #
+    #   result.data    # => { post: { id: "abc", title: "Hello" } }
+    #   result.status  # => 201
+    #   result.version # => Gem::Version.new("1")
+    #
+    #   # In controller:
+    #   render json: result.data, status: result.status
+    class Result
+      # @return [Hash] Validated response data
+      attr_reader :data
+
+      # @return [Integer] HTTP status code
+      attr_reader :status
+
+      # @return [Gem::Version] Resolved API version
+      attr_reader :version
+
+      # Creates a new result instance
+      #
+      # @param data [Hash] Validated response data
+      # @param status [Integer] HTTP status code
+      # @param version [Gem::Version] Resolved version
+      def initialize(data:, status:, version:)
+        @data = data
+        @status = status
+        @version = version
+      end
+
+      # Returns human-readable representation for debugging
+      #
+      # @return [String] Inspection string with all attributes
+      def inspect
+        "#<#{self.class.name} #{draw_result}>"
+      end
+
+      private
+
+      # Formats attributes for inspect output
+      #
+      # @return [String] Formatted attribute string
+      def draw_result
+        "@data=#{@data.inspect}, @status=#{@status.inspect}, @version=#{@version.inspect}"
+      end
+    end
+  end
+end

data/lib/treaty/action/versions/collection.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Versions
+      # Collection wrapper for sets of version factories.
+      #
+      # ## Purpose
+      #
+      # Provides a unified interface for working with collections of version factories.
+      # Uses Ruby Set internally for uniqueness but exposes Array-like interface.
+      #
+      # ## Usage
+      #
+      # Used internally by:
+      # - Versions::DSL (to store version factories)
+      # - Versions::Resolver (to find matching version)
+      # - Info::Builder (to build version information)
+      #
+      # ## Methods
+      #
+      # Delegates common collection methods to internal Set:
+      # - `<<` - Add version factory
+      # - `map` - Iteration with transformation
+      # - `find` - Access by condition
+      #
+      # ## Example
+      #
+      #   collection = Collection.new
+      #   collection << Factory.new(version: 1, default: true)
+      #   collection << Factory.new(version: 2, default: false)
+      #   collection.find { |f| f.default_result }  # => Factory(v1)
+      class Collection
+        extend Forwardable
+
+        def_delegators :@collection, :<<, :map, :find
+
+        # Creates a new collection instance
+        #
+        # @param collection [Set] Initial collection (default: empty Set)
+        def initialize(collection = Set.new)
+          @collection = collection
+        end
+      end
+    end
+  end
+end