treaty 0.18.0 → 0.20.0

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

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Versions
+      # Factory for version configuration and DSL.
+      #
+      # ## Purpose
+      #
+      # Provides the DSL interface within `version` blocks. Captures all
+      # version configuration: summary, deprecation, request schema,
+      # response schema, and executor delegation.
+      #
+      # ## Usage
+      #
+      # Created by:
+      # - Versions::DSL (when `version` is called)
+      #
+      # Consumed by:
+      # - Versions::Resolver (to find matching version)
+      # - Versions::Execution::Request (to execute the service)
+      # - Request::Validator / Response::Validator (to get schemas)
+      # - Info::Builder (to build version information)
+      #
+      # ## DSL Methods
+      #
+      # | Method | Purpose |
+      # |--------|---------|
+      # | `summary` | Set version description text |
+      # | `deprecated` | Mark version as deprecated (bool or proc) |
+      # | `request` | Define request schema (block or entity class) |
+      # | `response` | Define response schema with status code |
+      # | `delegate_to` | Set service class/proc to execute |
+      #
+      # ## Example
+      #
+      #   version 1, default: true do
+      #     summary "Initial API version"
+      #
+      #     deprecated { ENV["V1_DEPRECATED"] == "true" }
+      #
+      #     request do
+      #       object :post do
+      #         string :title, :required
+      #       end
+      #     end
+      #
+      #     response 201 do
+      #       object :post do
+      #         string :id
+      #       end
+      #     end
+      #
+      #     delegate_to Posts::CreateService
+      #   end
+      #
+      # ## Validation
+      #
+      # - `default` must be boolean or Proc
+      # - Cannot be both default and deprecated
+      class Factory
+        # @return [Treaty::Action::Versions::Semantic] Semantic version wrapper
+        attr_reader :version
+
+        # @return [Boolean] Whether this is the default version
+        attr_reader :default_result
+
+        # @return [String, nil] Version summary/description
+        attr_reader :summary_text
+
+        # @return [Boolean] Whether version is deprecated
+        attr_reader :deprecated_result
+
+        # @return [Treaty::Action::Versions::Executor, nil] Executor configuration
+        attr_reader :executor
+
+        # @return [Treaty::Action::Request::Factory, nil] Request schema factory
+        attr_reader :request_factory
+
+        # @return [Treaty::Action::Response::Factory, nil] Response schema factory
+        attr_reader :response_factory
+
+        # Creates a new version factory
+        #
+        # @param version [Integer, String, Array] Version identifier
+        # @param default [Boolean, Proc] Whether this is the default version
+        def initialize(version:, default:)
+          @version = Semantic.new(version)
+          @default_result = default.is_a?(Proc) ? default.call : default
+          @summary_text = nil
+          @deprecated_result = false
+          @executor = nil
+
+          validate!
+        end
+
+        # Validates configuration on creation
+        #
+        # @return [void]
+        def validate!
+          validate_default_option!
+        end
+
+        # Validates configuration after block evaluation
+        #
+        # @raise [Treaty::Exceptions::VersionDefaultDeprecatedConflict]
+        # @return [void]
+        def validate_after_block!
+          validate_default_deprecated_conflict!
+        end
+
+        # Sets version summary text
+        #
+        # @param text [String] Version description
+        # @return [void]
+        def summary(text)
+          @summary_text = text
+        end
+
+        # Marks version as deprecated
+        #
+        # Accepts boolean, Proc, or block that evaluates to boolean.
+        # Deprecated versions raise error when accessed.
+        #
+        # @param condition [Boolean, Proc, nil] Deprecation condition
+        # @yield Block that returns boolean
+        # @return [void]
+        def deprecated(condition = nil)
+          result =
+            if condition.is_a?(Proc)
+              condition.call
+            elsif condition.is_a?(TrueClass) || condition.is_a?(FalseClass)
+              condition
+            else
+              yield
+            end
+
+          @deprecated_result = result
+        end
+
+        # Defines request schema
+        #
+        # Accepts either an Entity class or a block with attribute definitions.
+        #
+        # @param entity_class [Class, nil] Entity class for request schema
+        # @yield Block with request attribute definitions
+        # @return [void]
+        def request(entity_class = nil, &block)
+          @request_factory ||= Request::Factory.new
+
+          if entity_class.present?
+            @request_factory.use_entity(entity_class)
+          elsif block_given?
+            @request_factory.instance_eval(&block)
+          end
+        end
+
+        # Defines response schema with HTTP status
+        #
+        # Accepts status code and either Entity class or block.
+        #
+        # @param status [Integer] HTTP status code (200, 201, 404, etc.)
+        # @param entity_class [Class, nil] Entity class for response schema
+        # @yield Block with response attribute definitions
+        # @return [void]
+        def response(status, entity_class = nil, &block)
+          @response_factory ||= Response::Factory.new(status)
+
+          if entity_class.present?
+            @response_factory.use_entity(entity_class)
+          elsif block_given?
+            @response_factory.instance_eval(&block)
+          end
+        end
+
+        # Configures service delegation
+        #
+        # Sets the executor (class, string, or proc) and method to call.
+        #
+        # @param executor [Class, String, Proc, Hash] Service reference
+        # @param method [Symbol] Method to call (default: :call)
+        # @return [void]
+        #
+        # @example Class reference
+        #   delegate_to Posts::CreateService
+        #
+        # @example With custom method
+        #   delegate_to Posts::CreateService => :call!
+        #
+        # @example String path
+        #   delegate_to "posts/create_service"
+        #
+        # @example Lambda
+        #   delegate_to ->(params:) { { id: SecureRandom.uuid } }
+        def delegate_to(executor, method = :call)
+          @executor = Executor.new(executor, method)
+        end
+
+        ##########################################################################
+
+        private
+
+        # Validates default option is boolean or Proc
+        #
+        # @raise [Treaty::Exceptions::Validation] If invalid type
+        # @return [Boolean, Proc]
+        def validate_default_option!
+          if @default_result.is_a?(TrueClass) || @default_result.is_a?(FalseClass) || @default_result.is_a?(Proc)
+            return @default_result
+          end
+
+          raise Treaty::Exceptions::Validation,
+                I18n.t(
+                  "treaty.versioning.factory.invalid_default_option",
+                  type: @default_result.class
+                )
+        end
+
+        # Validates version is not both default and deprecated
+        #
+        # @raise [Treaty::Exceptions::VersionDefaultDeprecatedConflict]
+        # @return [void]
+        def validate_default_deprecated_conflict!
+          return unless @default_result == true
+          return unless @deprecated_result == true
+
+          raise Treaty::Exceptions::VersionDefaultDeprecatedConflict,
+                I18n.t(
+                  "treaty.versioning.factory.default_deprecated_conflict",
+                  version: @version.version
+                )
+        end
+
+        ##########################################################################
+
+        # Catches unknown DSL methods with helpful error
+        #
+        # @raise [Treaty::Exceptions::MethodName]
+        def method_missing(name, *, &_block)
+          raise Treaty::Exceptions::MethodName,
+                I18n.t("treaty.versioning.factory.unknown_method", method: name)
+        end
+
+        # Required for method_missing
+        #
+        # @return [Boolean]
+        def respond_to_missing?(name, *)
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Versions
+      # Resolves version factory based on specified or default version.
+      #
+      # ## Purpose
+      #
+      # Finds the appropriate version factory from the collection based on:
+      # - Specified version (from request header or parameter)
+      # - Default version (if no version specified)
+      #
+      # Also enforces deprecation by raising error for deprecated versions.
+      #
+      # ## Usage
+      #
+      # Called internally by:
+      # - Versions::Workspace (at the start of treaty execution)
+      #
+      # ## Resolution Logic
+      #
+      # 1. If version specified → find matching factory or raise VersionNotFound
+      # 2. If no version → use default factory or raise SpecifiedVersionNotFound
+      # 3. If resolved factory is deprecated → raise Deprecated
+      #
+      # ## Error Types
+      #
+      # | Error | Condition |
+      # |-------|-----------|
+      # | VersionNotFound | Specified version doesn't exist |
+      # | SpecifiedVersionNotFound | No version specified and no default |
+      # | Deprecated | Resolved version is marked deprecated |
+      #
+      # ## Example
+      #
+      #   # Find specific version:
+      #   factory = Resolver.resolve!(
+      #     specified_version: "2",
+      #     collection_of_versions: collection
+      #   )
+      #
+      #   # Use default version:
+      #   factory = Resolver.resolve!(
+      #     specified_version: nil,
+      #     collection_of_versions: collection
+      #   )
+      class Resolver
+        # Resolves version factory (class method shortcut)
+        #
+        # @param specified_version [String, nil] Requested version or nil for default
+        # @param collection_of_versions [Treaty::Action::Versions::Collection] Available versions
+        # @return [Treaty::Action::Versions::Factory] Resolved version factory
+        # @raise [Treaty::Exceptions::VersionNotFound] If version doesn't exist
+        # @raise [Treaty::Exceptions::SpecifiedVersionNotFound] If no default available
+        # @raise [Treaty::Exceptions::Deprecated] If version is deprecated
+        def self.resolve!(...)
+          new(...).resolve!
+        end
+
+        # Creates a new resolver instance
+        #
+        # @param specified_version [String, nil] Requested version
+        # @param collection_of_versions [Treaty::Action::Versions::Collection] Available versions
+        def initialize(specified_version:, collection_of_versions:)
+          @specified_version = specified_version
+          @collection_of_versions = collection_of_versions
+        end
+
+        # Resolves and returns the appropriate version factory
+        #
+        # @return [Treaty::Action::Versions::Factory] Resolved version factory
+        # @raise [Treaty::Exceptions::VersionNotFound] If version doesn't exist
+        # @raise [Treaty::Exceptions::SpecifiedVersionNotFound] If no default available
+        # @raise [Treaty::Exceptions::Deprecated] If version is deprecated
+        def resolve!
+          determined_factory =
+            if specified_version_blank?
+              default_version_factory || raise_specified_version_not_found!
+            else
+              version_factory || raise_version_not_found!
+            end
+
+          raise_version_deprecated! if determined_factory.deprecated_result
+
+          determined_factory
+        end
+
+        private
+
+        # Finds factory matching specified version
+        #
+        # @return [Factory, nil] Matching factory or nil
+        def version_factory
+          @version_factory ||=
+            @collection_of_versions.find do |factory|
+              factory.version.version == @specified_version
+            end
+        end
+
+        # Finds default version factory
+        #
+        # @return [Factory, nil] Default factory or nil
+        def default_version_factory
+          @default_version_factory ||=
+            @collection_of_versions.find(&:default_result)
+        end
+
+        # Checks if specified version is blank
+        #
+        # @return [Boolean] True if version is nil or empty string
+        def specified_version_blank?
+          @specified_version.to_s.strip.empty?
+        end
+
+        ##########################################################################
+
+        # Raises error when no version specified and no default exists
+        #
+        # @raise [Treaty::Exceptions::SpecifiedVersionNotFound]
+        def raise_specified_version_not_found!
+          raise Treaty::Exceptions::SpecifiedVersionNotFound,
+                I18n.t("treaty.versioning.resolver.specified_version_required")
+        end
+
+        # Raises error when specified version doesn't exist
+        #
+        # @raise [Treaty::Exceptions::VersionNotFound]
+        def raise_version_not_found!
+          raise Treaty::Exceptions::VersionNotFound,
+                I18n.t(
+                  "treaty.versioning.resolver.version_not_found",
+                  version: @specified_version
+                )
+        end
+
+        # Raises error when resolved version is deprecated
+        #
+        # @raise [Treaty::Exceptions::Deprecated]
+        def raise_version_deprecated!
+          raise Treaty::Exceptions::Deprecated,
+                I18n.t(
+                  "treaty.versioning.resolver.version_deprecated",
+                  version: @specified_version
+                )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Versions
+      # Semantic version wrapper using Gem::Version.
+      #
+      # ## Purpose
+      #
+      # Normalizes version inputs (Integer, String, Array) into a consistent
+      # Gem::Version object. This enables proper version comparison and
+      # semantic versioning support.
+      #
+      # ## Usage
+      #
+      # Created internally by:
+      # - Versions::Factory (to store version number)
+      #
+      # Consumed by:
+      # - Versions::Resolver (to match requested version)
+      # - Info::Builder (to display version info)
+      #
+      # ## Version Formats
+      #
+      # Accepts multiple input formats:
+      # - Integer: `1` → "1"
+      # - String: `"1.0.0"` → "1.0.0"
+      # - Array: `[1, 0, 0]` → "1.0.0"
+      #
+      # ## Underlying Implementation
+      #
+      # Uses Gem::Version internally which provides:
+      # - Semantic version comparison (1.0.0 < 1.0.1 < 1.1.0 < 2.0.0)
+      # - Proper handling of pre-release versions (1.0.0-alpha < 1.0.0)
+      # - String normalization
+      #
+      # ## Example
+      #
+      #   Semantic.new(1).version           # => Gem::Version.new("1")
+      #   Semantic.new("1.2.3").version     # => Gem::Version.new("1.2.3")
+      #   Semantic.new([1, 2, 3]).version   # => Gem::Version.new("1.2.3")
+      class Semantic
+        # @return [Gem::Version] Normalized semantic version
+        attr_reader :version
+
+        # Creates a new semantic version wrapper
+        #
+        # @param version [Integer, String, Array] Version in any supported format
+        def initialize(version)
+          version =
+            if version.is_a?(Array)
+              version.join(".")
+            # elsif version.is_a?(Integer)
+            #   version.to_s
+            else
+              version # rubocop:disable Style/RedundantSelfAssignmentBranch
+            end
+
+          @version = Gem::Version.new(version)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Versions
+      # Core execution module for treaty call! method.
+      #
+      # ## Purpose
+      #
+      # Provides the `call!` instance method that orchestrates the complete
+      # treaty execution flow: version resolution, request validation,
+      # service execution, and response validation.
+      #
+      # ## Usage
+      #
+      # Included via:
+      # - Versions::DSL (when DSL is included in treaty class)
+      #
+      # Called by:
+      # - Controller integration (via Treaty::Action::Base.call!)
+      #
+      # ## Execution Flow
+      #
+      # ```
+      # call!(context:, inventory:, version:, params:)
+      #   │
+      #   ├─1─► Resolver.resolve! ──► Find version factory
+      #   │
+      #   ├─2─► Request::Validator.validate! ──► Validate params
+      #   │
+      #   ├─3─► Execution::Request.execute! ──► Run service
+      #   │
+      #   ├─4─► Response::Validator.validate! ──► Validate response
+      #   │
+      #   └─5─► Result.new ──► Return result object
+      # ```
+      #
+      # ## Parameters
+      #
+      # | Parameter | Description |
+      # |-----------|-------------|
+      # | context | Controller instance |
+      # | inventory | Inventory::Collection with controller data |
+      # | version | Requested version string (or nil for default) |
+      # | params | Request parameters |
+      #
+      # ## Return Value
+      #
+      # Returns `Treaty::Action::Result` with:
+      # - `data` - Validated response hash
+      # - `status` - HTTP status code
+      # - `version` - Resolved version string
+      module Workspace
+        private
+
+        # Executes the complete treaty flow
+        #
+        # Orchestrates version resolution, validation, execution,
+        # and returns a Result object.
+        #
+        # @param context [Object] Controller instance
+        # @param inventory [Treaty::Action::Inventory::Collection] Controller data
+        # @param version [String, nil] Requested version or nil for default
+        # @param params [Hash] Request parameters
+        # @return [Treaty::Action::Result] Execution result
+        # @raise [Treaty::Exceptions::VersionNotFound] If version not found
+        # @raise [Treaty::Exceptions::Deprecated] If version is deprecated
+        # @raise [Treaty::Exceptions::Validation] If validation fails
+        # @raise [Treaty::Exceptions::Execution] If service execution fails
+        def call!(context:, inventory:, version:, params:, **) # rubocop:disable Metrics/MethodLength
+          super
+
+          version_factory = Resolver.resolve!(
+            specified_version: version,
+            collection_of_versions: @collection_of_versions
+          )
+
+          validated_params = Request::Validator.validate!(
+            params:,
+            version_factory:
+          )
+
+          executor_result = Execution::Request.execute!(
+            context:,
+            inventory:,
+            version_factory:,
+            validated_params:
+          )
+
+          validated_response = Response::Validator.validate!(
+            version_factory:,
+            response_data: executor_result
+          )
+
+          status = version_factory.response_factory&.status || 200
+
+          Result.new(
+            data: validated_response,
+            status:,
+            version: version_factory.version.version
+          )
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Treaty
+  # Action namespace containing the base class and versioning system.
+  #
+  # Users should inherit from Treaty::Action::Base:
+  #
+  #   class Posts::CreateTreaty < Treaty::Action::Base
+  #     version 1, default: true do
+  #       summary "Create a new post"
+  #
+  #       request do
+  #         object :post do
+  #           string :title, :required
+  #         end
+  #       end
+  #
+  #       response 201 do
+  #         object :post do
+  #           string :id
+  #         end
+  #       end
+  #
+  #       delegate_to Posts::CreateService
+  #     end
+  #   end
+  #
+  # @see Treaty::Action::Base for full documentation and examples
+  module Action
+  end
+end

data/lib/treaty/controller/dsl.rb

@@ -57,7 +57,7 @@ module Treaty
         def treaty_build_inventory_for(action_name, block)
           return nil unless block
 
-          factory = Treaty::Inventory::Factory.new(action_name)
+          factory = Treaty::Action::Inventory::Factory.new(action_name)
           factory.instance_eval(&block)
           factory.collection
         end

data/lib/treaty/engine.rb

@@ -12,7 +12,7 @@ module Treaty
 
     initializer "treaty.register_option_processors", before: :load_config_initializers do
       # Register all option processors (validators and modifiers)
-      require "treaty/attribute/option/registry_initializer"
+      require "treaty/entity/attribute/option/registry_initializer"
     end
 
     initializer "treaty.validate_configuration" do

data/lib/treaty/{attribute/entity → entity/attribute}/attribute.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Treaty
-  module Attribute
-    module Entity
+  module Entity
+    module Attribute
       # Entity-specific attribute that defaults to required: true
-      class Attribute < Treaty::Attribute::Base
+      class Attribute < Base
         private
 
         def apply_defaults!
@@ -16,7 +16,7 @@ module Treaty
         def process_nested_attributes(&block)
           return unless object_or_array?
 
-          builder = Builder.new(collection_of_attributes, @nesting_level + 1)
+          builder = Treaty::Entity::Builder.new(collection_of_attributes, @nesting_level + 1)
           builder.instance_eval(&block)
         end
       end