treaty 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7b03c7d0eed4f560087ed9662f711e50ec947a78357d687ea2be29ddd9b7872
-  data.tar.gz: c9b3b121e50d75518e4db1a0b3c388f36334cce4b9995aefb5b24e3101e5d984
+  metadata.gz: 395c83deb4d618293b99588b6130e9529febdb028d2db017ee27181479371a80
+  data.tar.gz: c0b2b1e546542caeee840f105aa0752ae6d84067e78a494c5429204dd2ed3052
 SHA512:
-  metadata.gz: 13ca45c37ea6988a5b046a8c7825cf11acfd62fbc5c32d120888c66623da24f52dbea656120a71e815018765573aa3b1c05370bba356fc4913dd02ec342022c6
-  data.tar.gz: 431831fb76b2a44997aef884aa3662d7cff2a474f13a308472af78cd298471776f001454b98d02ed38a11e3d9f9f84ff2e5034f77004533d092483fd4b8f6420
+  metadata.gz: d5b28e9d167fadd9cf465d9318920342f8be404ffb32ec17aa1f73e24c34cc8b1f3658273627086c4361d12e7fcd51ee33c96c17115f471c174bc0371122e41d
+  data.tar.gz: 5d5f5b386389546b413ee28988bff90386aef2aa60e5234ee660f9fcda01aedffd3dc7b3eab03b10b94a842170119cf89ed60b0cbb21bdbe15b69695d35096eb

data/README.md

@@ -13,7 +13,7 @@
 </div>
 
 > [!WARNING]
-> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.19.0"`) until the 1.0 release.
+> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.20.0"`) until the 1.0 release.
 
 ## 📚 Documentation
 

data/lib/treaty/action/base.rb

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

data/lib/treaty/action/context/callable.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Context
+      # Class methods for calling treaty actions.
+      #
+      # ## Purpose
+      #
+      # Provides the public `call!` class method that serves as the entry
+      # point for treaty execution. Handles instance creation and delegates
+      # to instance methods.
+      #
+      # ## Usage
+      #
+      # Extended into:
+      # - Treaty classes (via Context::DSL)
+      #
+      # Called by:
+      # - Controller integration
+      # - Direct treaty invocation in tests
+      #
+      # ## Call Pattern
+      #
+      # ```ruby
+      # # Public API:
+      # result = Posts::CreateTreaty.call!(
+      #   version: "1",
+      #   params: { post: { title: "Hello" } },
+      #   context: controller,      # optional
+      #   inventory: inventory      # optional
+      # )
+      #
+      # result.data    # => validated response hash
+      # result.status  # => HTTP status code
+      # result.version # => resolved version
+      # ```
+      #
+      # ## Implementation
+      #
+      # Creates a new treaty instance and delegates to `_call!` which
+      # passes through to Workspace, then to Versions::Workspace for
+      # actual execution.
+      module Callable
+        # Executes treaty with given parameters
+        #
+        # Main entry point for treaty execution. Creates instance
+        # and delegates to instance methods for actual work.
+        #
+        # @param version [String, nil] Requested API version (nil uses default)
+        # @param params [Hash] Request parameters
+        # @param context [Object, nil] Controller context (for inventory evaluation)
+        # @param inventory [Treaty::Action::Inventory::Collection, nil] Inventory items
+        # @return [Treaty::Action::Result] Execution result
+        # @raise [Treaty::Exceptions::VersionNotFound] If version not found
+        # @raise [Treaty::Exceptions::Validation] If validation fails
+        # @raise [Treaty::Exceptions::Execution] If service execution fails
+        def call!(version:, params:, context: nil, inventory: nil)
+          treaty_instance = send(:new)
+
+          _call!(treaty_instance, context:, inventory:, version:, params:)
+        end
+
+        private
+
+        # Internal call delegation to instance
+        #
+        # Passes all parameters plus class-level collection_of_versions
+        # to the instance's _call! method.
+        #
+        # @param treaty_instance [Object] Treaty instance
+        # @param context [Object, nil] Controller context
+        # @param inventory [Treaty::Action::Inventory::Collection, nil] Inventory items
+        # @param version [String, nil] Requested version
+        # @param params [Hash] Request parameters
+        # @return [Treaty::Action::Result] Execution result
+        def _call!(treaty_instance, context:, inventory:, version:, params:)
+          treaty_instance.send(
+            :_call!,
+            context:,
+            inventory:,
+            version:,
+            params:,
+            collection_of_versions:
+          )
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/context/dsl.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Context
+      # DSL module that wires up callable and workspace functionality.
+      #
+      # ## Purpose
+      #
+      # Acts as a composition root that includes both Callable (class methods)
+      # and Workspace (instance methods) when included in a treaty class.
+      # This enables the `call!` API pattern.
+      #
+      # ## Usage
+      #
+      # Included in:
+      # - Treaty::Action::Base (as part of core DSL)
+      #
+      # ## What it provides
+      #
+      # When included, adds:
+      # - Class method: `call!` (from Callable)
+      # - Instance methods: `_call!`, `call!` (from Workspace)
+      #
+      # ## Architecture
+      #
+      # The call chain works as follows:
+      #
+      # ```
+      # MyTreaty.call!(version:, params:, ...)
+      #   │
+      #   └─► Callable.call! (class method)
+      #         │
+      #         ├─► Creates treaty instance
+      #         │
+      #         └─► Workspace._call! (instance method)
+      #               │
+      #               └─► Workspace.call! (stores @collection_of_versions)
+      #                     │
+      #                     └─► super → Versions::Workspace.call!
+      # ```
+      module DSL
+        # Hook called when module is included
+        #
+        # Extends the including class with Callable (class methods)
+        # and includes Workspace (instance methods).
+        #
+        # @param base [Class] The class including this module
+        def self.included(base)
+          base.extend(Callable)
+          base.include(Workspace)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Context
+      # Instance methods for treaty execution context.
+      #
+      # ## Purpose
+      #
+      # Provides instance-level methods that bridge between Callable
+      # (class methods) and Versions::Workspace (actual execution).
+      # Stores the collection_of_versions in instance variable for
+      # use by Versions::Workspace.
+      #
+      # ## Usage
+      #
+      # Included via:
+      # - Context::DSL (when DSL is included)
+      #
+      # ## Method Chain
+      #
+      # ```
+      # Callable.call! (class)
+      #   │
+      #   └─► _call! (receives all params from class)
+      #         │
+      #         └─► call! (stores @collection_of_versions)
+      #               │
+      #               └─► super → Versions::Workspace.call!
+      # ```
+      #
+      # ## Why Two Methods?
+      #
+      # - `_call!` - Entry point from Callable, receives raw parameters
+      # - `call!` - Stores collection_of_versions, then calls super
+      #
+      # The separation allows Versions::Workspace to override `call!`
+      # while keeping the parameter passing clean.
+      #
+      # ## Instance Variable
+      #
+      # Stores `@collection_of_versions` which is used by
+      # Versions::Workspace.call! for version resolution.
+      module Workspace
+        private
+
+        # Entry point for instance execution
+        #
+        # Receives all parameters from Callable and forwards to call!.
+        # This method exists to provide a clean interface between
+        # class methods and instance methods.
+        #
+        # @param context [Object, nil] Controller context
+        # @param inventory [Treaty::Action::Inventory::Collection, nil] Inventory items
+        # @param version [String, nil] Requested version
+        # @param params [Hash] Request parameters
+        # @param collection_of_versions [Treaty::Action::Versions::Collection] Version factories
+        # @return [Treaty::Action::Result] Execution result
+        def _call!(
+          context:,
+          inventory:,
+          version:,
+          params:,
+          collection_of_versions:
+        )
+          call!(
+            context:,
+            inventory:,
+            version:,
+            params:,
+            collection_of_versions:
+          )
+        end
+
+        # Stores collection and delegates to Versions::Workspace
+        #
+        # Captures collection_of_versions in instance variable,
+        # then calls super which invokes Versions::Workspace.call!
+        # for actual treaty execution.
+        #
+        # @param collection_of_versions [Treaty::Action::Versions::Collection] Version factories
+        # @return [Treaty::Action::Result] Execution result (from super)
+        def call!(
+          collection_of_versions:,
+          **
+        )
+          @collection_of_versions = collection_of_versions
+        end
+      end
+    end
+  end
+end

data/lib/treaty/action/executor/inventory.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Executor
+      # Lazy-evaluating proxy for accessing inventory items.
+      #
+      # ## Purpose
+      #
+      # Provides lazy evaluation and caching of inventory items defined in controllers.
+      # Acts as a proxy that evaluates inventory items only when accessed, avoiding
+      # unnecessary computation for unused items.
+      #
+      # ## Usage
+      #
+      # Created internally by:
+      # - Versions::Execution::Request (when executing treaty versions)
+      #
+      # Passed to:
+      # - Service classes (as `inventory` parameter)
+      # - Proc executors (as `inventory:` keyword argument)
+      #
+      # ## Access Patterns
+      #
+      # Method-based access (lazy, cached):
+      #   inventory.current_user  # Evaluates and caches on first call
+      #   inventory.current_user  # Returns cached value
+      #
+      # Hash-based access (evaluates all items):
+      #   inventory.to_h  # => { current_user: <User>, posts: [...] }
+      #
+      # ## Caching
+      #
+      # Once an item is evaluated via method access, the result is cached
+      # in `@evaluated_cache`. Subsequent calls return the cached value
+      # without re-evaluation.
+      #
+      # ## Example
+      #
+      #   # In controller:
+      #   treaty :index do
+      #     provide :current_user
+      #     provide :posts, from: :load_posts
+      #   end
+      #
+      #   # In service:
+      #   class Posts::IndexService
+      #     def call(inventory:, params:)
+      #       user = inventory.current_user  # Lazy evaluation
+      #       posts = inventory.posts        # Lazy evaluation
+      #       # ...
+      #     end
+      #   end
+      class Inventory
+        # Creates a new inventory executor instance
+        #
+        # @param inventory [Treaty::Action::Inventory::Collection, nil] Collection of inventory items
+        # @param context [Object] Controller context for evaluating items (typically ActionController instance)
+        def initialize(inventory, context)
+          @inventory = inventory
+          @context = context
+          @evaluated_cache = {}
+        end
+
+        # Handles dynamic method calls to access inventory items
+        #
+        # Looks up the inventory item by method name, evaluates it with
+        # the controller context, and caches the result.
+        #
+        # @param method_name [Symbol] Name of the inventory item to access
+        # @return [Object] Evaluated value from the inventory item
+        # @raise [Treaty::Exceptions::Inventory] If item with given name not found
+        def method_missing(method_name, *_args)
+          return @evaluated_cache[method_name] if @evaluated_cache.key?(method_name)
+
+          item = find_inventory_item(method_name)
+
+          @evaluated_cache[method_name] = item.evaluate(@context)
+        end
+
+        # Checks if method corresponds to an inventory item
+        #
+        # @param method_name [Symbol] Method name to check
+        # @param include_private [Boolean] Whether to include private methods
+        # @return [Boolean] True if inventory contains item with given name
+        def respond_to_missing?(method_name, include_private = false)
+          return false if @inventory.nil?
+
+          @inventory.names.include?(method_name) || super
+        end
+
+        # Evaluates all inventory items and returns as hash
+        #
+        # Unlike method-based access, this evaluates ALL items at once.
+        # Useful when you need all inventory data as a hash.
+        #
+        # @return [Hash{Symbol => Object}] Hash of all evaluated inventory values
+        def to_h
+          return {} if @inventory.nil?
+
+          @inventory.evaluate(@context)
+        end
+
+        # Returns human-readable representation for debugging
+        #
+        # @return [String] Inspection string with available item names
+        def inspect
+          items = @inventory&.names || []
+          "#<Treaty::Action::Executor::Inventory items=#{items.inspect}>"
+        end
+
+        private
+
+        # Finds inventory item by name or raises error
+        #
+        # @param name [Symbol] Name of the inventory item
+        # @return [Treaty::Action::Inventory::Inventory] Found inventory item
+        # @raise [Treaty::Exceptions::Inventory] If item not found
+        def find_inventory_item(name)
+          item = @inventory&.find { |item| item.name == name }
+
+          return item if item
+
+          available = @inventory&.names || []
+
+          raise Treaty::Exceptions::Inventory,
+                I18n.t(
+                  "treaty.executor.inventory.item_not_found",
+                  name:,
+                  available: available.join(", ")
+                )
+        end
+      end
+    end
+  end
+end

data/lib/treaty/{info/rest → action/info}/builder.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Treaty
-  module Info
-    module Rest
+  module Action
+    module Info
       class Builder
         attr_reader :versions
 

data/lib/treaty/{info/rest → action/info}/dsl.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Treaty
-  module Info
-    module Rest
+  module Action
+    module Info
       module DSL
         def self.included(base)
           base.extend(ClassMethods)

data/lib/treaty/{info/rest → action/info}/result.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Treaty
-  module Info
-    module Rest
+  module Action
+    module Info
       class Result
         attr_reader :versions
 

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Inventory
+      # Collection wrapper for sets of inventory items.
+      #
+      # ## Purpose
+      #
+      # Provides a unified interface for working with collections of inventory items.
+      # Uses Ruby Set internally for uniqueness but exposes Array-like interface.
+      #
+      # ## Usage
+      #
+      # Used internally by:
+      # - Inventory::Factory (to store inventory items)
+      # - Executor::Inventory (to evaluate and access items)
+      #
+      # ## Methods
+      #
+      # Delegates common collection methods to internal Set:
+      # - `<<` - Add inventory item
+      # - `each_with_object` - Iteration with accumulator
+      # - `find` - Access by condition
+      # - `empty?` - Size check
+      #
+      # Custom methods:
+      # - `exists?` - Returns true if collection is not empty
+      # - `names` - Returns array of inventory item names
+      # - `evaluate` - Evaluates all items with controller context
+      #
+      # ## Example
+      #
+      #   collection = Collection.new
+      #   collection << Inventory.new(name: :current_user, source: :current_user)
+      #   collection << Inventory.new(name: :posts, source: :load_posts)
+      #   collection.exists?  # => true
+      #   collection.names    # => [:current_user, :posts]
+      class Collection
+        extend Forwardable
+
+        def_delegators :@collection, :<<, :each_with_object, :find, :empty?
+
+        # Creates a new collection instance
+        #
+        # @param collection [Set] Initial collection (default: empty Set)
+        def initialize(collection = Set.new)
+          @collection = collection
+        end
+
+        # Checks if collection has any elements
+        #
+        # @return [Boolean] True if collection is not empty
+        def exists?
+          !empty?
+        end
+
+        # Returns array of all inventory item names
+        #
+        # @return [Array<Symbol>] Array of inventory item names
+        def names
+          @collection.each_with_object([]) { |item, names| names << item.name }
+        end
+
+        # Evaluates all inventory items with controller context
+        #
+        # @param context [Object] Controller context for evaluation
+        # @return [Hash{Symbol => Object}] Hash of evaluated inventory values
+        def evaluate(context)
+          @collection.each_with_object({}) do |inventory_item, hash|
+            hash[inventory_item.name] = inventory_item.evaluate(context)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Action
+    module Inventory
+      # Factory for building inventory collections from controller DSL.
+      #
+      # ## Purpose
+      #
+      # Provides the `provide` DSL method used in controller treaty blocks
+      # to define inventory items. Inventory allows controllers to pass
+      # data (current_user, loaded records, etc.) to services.
+      #
+      # ## Usage
+      #
+      # Created by:
+      # - Controller::DSL (when treaty block is evaluated)
+      #
+      # ## DSL Method
+      #
+      # The only supported method is `provide`:
+      #
+      #   treaty :index do
+      #     provide :current_user                    # Shorthand: same name as method
+      #     provide :posts, from: :load_posts        # Symbol source
+      #     provide :meta, from: -> { build_meta }   # Proc source
+      #     provide :limit, from: 10                 # Direct value
+      #   end
+      #
+      # ## Source Types
+      #
+      # | Type | Description | Evaluation |
+      # |------|-------------|------------|
+      # | Symbol | Controller method name | `context.send(source)` |
+      # | Proc | Lambda/block | `context.instance_exec(&source)` |
+      # | Other | Direct value | Returned as-is |
+      #
+      # ## Example
+      #
+      #   factory = Factory.new(:index)
+      #   factory.provide :current_user
+      #   factory.provide :posts, from: :load_posts
+      #   factory.collection  # => Collection with 2 items
+      class Factory
+        # @return [Treaty::Action::Inventory::Collection] Collection of inventory items
+        attr_reader :collection
+
+        # Creates a new factory instance
+        #
+        # @param action_name [Symbol] Controller action name (for error messages)
+        def initialize(action_name)
+          @action_name = action_name
+          @collection = Collection.new
+        end
+
+        # Handles DSL method calls (only `provide` is supported)
+        #
+        # Creates an Inventory item and adds it to the collection.
+        # Validates that only `provide` method is called and name is a Symbol.
+        #
+        # @param method_name [Symbol] Method name (must be :provide)
+        # @param args [Array] Arguments (first must be inventory name as Symbol)
+        # @param options [Hash] Options (:from for source)
+        # @raise [Treaty::Exceptions::Inventory] If method is not `provide`
+        # @raise [Treaty::Exceptions::Inventory] If name is not a Symbol
+        # @return [Treaty::Action::Inventory::Collection] Updated collection
+        def method_missing(method_name, *args, **options, &_block) # rubocop:disable Metrics/MethodLength
+          unless method_name == :provide
+            raise Treaty::Exceptions::Inventory,
+                  I18n.t(
+                    "treaty.inventory.unknown_method",
+                    method: method_name,
+                    action: @action_name
+                  )
+          end
+
+          inventory_name = args.first
+
+          unless inventory_name.is_a?(Symbol)
+            raise Treaty::Exceptions::Inventory,
+                  I18n.t(
+                    "treaty.inventory.name_must_be_symbol",
+                    name: inventory_name.inspect
+                  )
+          end
+
+          source = if options.key?(:from)
+                     options.fetch(:from)
+                   else
+                     inventory_name
+                   end
+
+          @collection << Inventory.new(name: inventory_name, source:)
+
+          @collection
+        end
+
+        # Checks if method should be handled by method_missing
+        #
+        # @param method_name [Symbol] Method name
+        # @return [Boolean] True only for :provide
+        def respond_to_missing?(method_name, *)
+          method_name == :provide || super
+        end
+      end
+    end
+  end
+end