tasker-rb 0.1.1

data/lib/tasker_core/registry/resolver_chain.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require_relative 'resolvers/base_resolver'
+require_relative 'resolvers/method_dispatch_wrapper'
+
+module TaskerCore
+  module Registry
+    # TAS-93: Resolver Chain - Priority-Ordered Handler Resolution
+    #
+    # The ResolverChain orchestrates handler resolution by trying resolvers
+    # in priority order until one successfully resolves the handler.
+    #
+    # == Resolution Contract
+    #
+    # 1. If HandlerDefinition has `resolver:` hint, use ONLY that resolver
+    # 2. Otherwise, try resolvers in priority order (lower = first)
+    # 3. Wrap resolved handler with MethodDispatchWrapper if needed
+    # 4. Return nil if no resolver can handle the definition
+    #
+    # == Default Chain (when using .default)
+    #
+    # Priority 10:  ExplicitMappingResolver - registered handlers
+    # Priority 100: ClassConstantResolver   - class path inference
+    #
+    # == Usage
+    #
+    #   # Create default chain
+    #   chain = ResolverChain.default
+    #
+    #   # Or build custom chain
+    #   chain = ResolverChain.new
+    #     .with_resolver(MyResolver.new)
+    #     .with_resolver(AnotherResolver.new)
+    #
+    #   # Resolve a handler
+    #   handler = chain.resolve(definition, config)
+    #
+    # == Adding Custom Resolvers
+    #
+    #   chain.add_resolver(CustomResolver.new)
+    #
+    # == Named Resolver Access
+    #
+    #   # Add with name for resolver hint support
+    #   chain.add_resolver(PaymentResolver.new)
+    #
+    #   # Definition with resolver hint
+    #   definition.resolver = 'payment_resolver'
+    #   # Chain will ONLY use PaymentResolver
+    #
+    class ResolverChain
+      # Error raised when resolver hint points to unknown resolver
+      class ResolverNotFoundError < StandardError; end
+
+      # Error raised when resolution fails completely
+      class ResolutionError < StandardError; end
+
+      def initialize
+        @resolvers = []
+        @resolvers_by_name = {}
+        @logger = TaskerCore::Logger.instance
+      end
+
+      # Create a chain with default resolvers
+      #
+      # @return [ResolverChain] Chain with Explicit + ClassConstant resolvers
+      def self.default
+        require_relative 'resolvers/explicit_mapping_resolver'
+        require_relative 'resolvers/class_constant_resolver'
+
+        new.tap do |chain|
+          chain.add_resolver(Resolvers::ExplicitMappingResolver.new)
+          chain.add_resolver(Resolvers::ClassConstantResolver.new)
+        end
+      end
+
+      # Add a resolver to the chain
+      #
+      # @param resolver [Resolvers::BaseResolver] Resolver to add
+      # @return [self] For method chaining
+      def add_resolver(resolver)
+        @resolvers << resolver
+        @resolvers.sort_by!(&:priority)
+        @resolvers_by_name[resolver.name] = resolver
+        self
+      end
+
+      # Fluent API for adding resolvers
+      alias with_resolver add_resolver
+
+      # Remove a resolver by name
+      #
+      # @param name [String] Resolver name to remove
+      # @return [Resolvers::BaseResolver, nil] Removed resolver
+      def remove_resolver(name)
+        resolver = @resolvers_by_name.delete(name)
+        @resolvers.delete(resolver) if resolver
+        resolver
+      end
+
+      # Get a resolver by name
+      #
+      # @param name [String] Resolver name
+      # @return [Resolvers::BaseResolver, nil]
+      def get_resolver(name)
+        @resolvers_by_name[name]
+      end
+
+      # Get the explicit mapping resolver (convenience method)
+      #
+      # @return [Resolvers::ExplicitMappingResolver, nil]
+      def explicit_resolver
+        @resolvers_by_name['explicit_mapping']
+      end
+
+      # Resolve a handler from the definition
+      #
+      # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+      # @param config [Hash] Additional context
+      # @return [Object, nil] Resolved handler or nil
+      def resolve(definition, config = {})
+        # Contract: If resolver hint is present, use ONLY that resolver
+        return resolve_with_hint(definition, config) if definition.has_resolver_hint?
+
+        # Otherwise: Try inferential chain resolution
+        resolve_with_chain(definition, config)
+      end
+
+      # Check if any resolver can handle this definition
+      #
+      # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+      # @param config [Hash] Additional context
+      # @return [Boolean]
+      def can_resolve?(definition, config = {})
+        if definition.has_resolver_hint?
+          resolver = @resolvers_by_name[definition.resolver]
+          return resolver&.can_resolve?(definition, config) || false
+        end
+
+        @resolvers.any? { |r| r.can_resolve?(definition, config) }
+      end
+
+      # Get all registered callables across all resolvers
+      #
+      # @return [Array<String>] List of all registered callable identifiers
+      def registered_callables
+        @resolvers.flat_map(&:registered_callables).uniq
+      end
+
+      # Register a handler directly (convenience method for ExplicitMappingResolver)
+      #
+      # @param key [String] Handler key
+      # @param handler [Object] Handler class or instance
+      # @return [self]
+      def register(key, handler)
+        explicit = explicit_resolver
+        raise 'No ExplicitMappingResolver in chain' unless explicit
+
+        explicit.register(key, handler)
+        self
+      end
+
+      # Get chain info for debugging
+      #
+      # @return [Array<Hash>] Resolver info
+      def chain_info
+        @resolvers.map do |resolver|
+          {
+            name: resolver.name,
+            priority: resolver.priority,
+            callables: resolver.registered_callables.size
+          }
+        end
+      end
+
+      # @return [Integer] Number of resolvers in chain
+      def size
+        @resolvers.size
+      end
+
+      # @return [Array<String>] Names of resolvers in priority order
+      def resolver_names
+        @resolvers.map(&:name)
+      end
+
+      # Wrap handler for method dispatch if needed.
+      #
+      # This method is public because HandlerRegistry needs to wrap handlers
+      # that it instantiates directly (outside the resolver chain flow).
+      #
+      # @param handler [Object] Resolved handler instance
+      # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+      # @return [Object, nil] Handler (possibly wrapped), or nil if method not found
+      def wrap_for_method_dispatch(handler, definition)
+        # No wrapping needed if using default .call method
+        return handler unless definition.uses_method_dispatch?
+
+        effective_method = definition.effective_method.to_sym
+
+        # Verify handler responds to the target method
+        unless handler.respond_to?(effective_method)
+          @logger.warn("ResolverChain: Handler #{handler.class} doesn't respond to ##{effective_method}")
+          return nil
+        end
+
+        @logger.debug("ResolverChain: Wrapping #{handler.class} for method dispatch → ##{effective_method}")
+        Resolvers::MethodDispatchWrapper.new(handler, effective_method)
+      end
+
+      private
+
+      # Resolve using explicit resolver hint (bypasses chain)
+      #
+      # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+      # @param config [Hash] Additional context
+      # @return [Object, nil] Resolved handler
+      def resolve_with_hint(definition, config)
+        resolver_name = definition.resolver
+        resolver = @resolvers_by_name[resolver_name]
+
+        unless resolver
+          @logger.warn("ResolverChain: Unknown resolver hint '#{resolver_name}'")
+          raise ResolverNotFoundError, "Unknown resolver: '#{resolver_name}'"
+        end
+
+        handler = resolver.resolve(definition, config)
+
+        unless handler
+          @logger.warn("ResolverChain: Resolver '#{resolver_name}' failed to resolve '#{definition.callable}'")
+          return nil
+        end
+
+        @logger.debug("ResolverChain: Resolved '#{definition.callable}' via hint '#{resolver_name}'")
+        wrap_for_method_dispatch(handler, definition)
+      end
+
+      # Resolve using chain (tries resolvers in priority order)
+      #
+      # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+      # @param config [Hash] Additional context
+      # @return [Object, nil] Resolved handler
+      def resolve_with_chain(definition, config)
+        @resolvers.each do |resolver|
+          next unless resolver.can_resolve?(definition, config)
+
+          handler = resolver.resolve(definition, config)
+          next unless handler
+
+          @logger.debug("ResolverChain: Resolved '#{definition.callable}' via '#{resolver.name}'")
+          return wrap_for_method_dispatch(handler, definition)
+        end
+
+        @logger.debug("ResolverChain: No resolver could handle '#{definition.callable}'")
+        nil
+      end
+    end
+  end
+end

data/lib/tasker_core/registry/resolvers/base_resolver.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module Registry
+    module Resolvers
+      # TAS-93: Abstract base class for step handler resolvers
+      #
+      # This class defines the contract that all resolvers must implement.
+      # Resolvers are tried in priority order by the ResolverChain until
+      # one successfully resolves the handler.
+      #
+      # == Resolution Contract
+      #
+      # 1. `name` - Human-readable identifier for logging/debugging
+      # 2. `priority` - Lower numbers = tried first (10 = explicit, 100 = inferential)
+      # 3. `can_resolve?` - Quick check if this resolver might handle the definition
+      # 4. `resolve` - Actually resolve the handler callable
+      #
+      # == Implementation Example
+      #
+      #   class MyResolver < BaseResolver
+      #     def name
+      #       'my_custom_resolver'
+      #     end
+      #
+      #     def priority
+      #       50  # Between explicit (10) and class constant (100)
+      #     end
+      #
+      #     def can_resolve?(definition, config)
+      #       # Quick eligibility check
+      #       definition.callable.start_with?('MyApp::')
+      #     end
+      #
+      #     def resolve(definition, config)
+      #       # Return handler or nil
+      #       # handler must respond to effective_method
+      #     end
+      #   end
+      #
+      class BaseResolver
+        # Human-readable name for this resolver (for logging/debugging)
+        #
+        # @return [String] The resolver name
+        def name
+          raise NotImplementedError, "#{self.class}#name must be implemented"
+        end
+
+        # Resolution priority (lower = tried first)
+        #
+        # Standard priorities:
+        # - 10: Explicit mapping (registered handlers)
+        # - 100: Class constant (inferential)
+        #
+        # @return [Integer] The priority value
+        def priority
+          raise NotImplementedError, "#{self.class}#priority must be implemented"
+        end
+
+        # Quick eligibility check (called before resolve)
+        #
+        # This should be a fast check to determine if this resolver
+        # is even worth trying for the given definition.
+        #
+        # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+        # @param config [Hash] Additional configuration context
+        # @return [Boolean] true if this resolver might be able to resolve the handler
+        def can_resolve?(definition, config)
+          raise NotImplementedError, "#{self.class}#can_resolve? must be implemented"
+        end
+
+        # Resolve the handler callable from the definition
+        #
+        # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+        # @param config [Hash] Additional configuration context
+        # @return [Object, nil] Handler object or nil if cannot resolve
+        def resolve(definition, config)
+          raise NotImplementedError, "#{self.class}#resolve must be implemented"
+        end
+
+        # Return all callable keys this resolver knows about (for debugging/introspection)
+        #
+        # @return [Array<String>] List of registered callable identifiers
+        def registered_callables
+          []
+        end
+      end
+    end
+  end
+end

data/lib/tasker_core/registry/resolvers/class_constant_resolver.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative 'base_resolver'
+
+module TaskerCore
+  module Registry
+    module Resolvers
+      # TAS-93: Class Constant Resolver (Inferential)
+      #
+      # This resolver uses Ruby's `const_get` to resolve class paths
+      # to actual handler classes. It's the fallback resolver with
+      # lowest priority (100), tried after explicit mappings.
+      #
+      # == Resolution Behavior
+      #
+      # Given callable: "MyApp::Handlers::PaymentHandler"
+      # 1. Attempts `Object.const_get('MyApp::Handlers::PaymentHandler')`
+      # 2. Verifies the result is a Class
+      # 3. Verifies the class responds to effective_method (from HandlerDefinition)
+      # 4. Instantiates with config if supported
+      #
+      # == Usage
+      #
+      #   resolver = ClassConstantResolver.new
+      #
+      #   # This will find any loaded Ruby class
+      #   handler = resolver.resolve(definition, config)
+      #
+      # == When This Resolver is Used
+      #
+      # - Standard handler class paths (e.g., "MyApp::PaymentHandler")
+      # - Handler classes already loaded in memory
+      # - Conventional Ruby handler patterns
+      #
+      class ClassConstantResolver < BaseResolver
+        PRIORITY = 100 # Lowest priority - tried last
+
+        def initialize
+          super
+          @logger = TaskerCore::Logger.instance
+        end
+
+        # @return [String] Human-readable resolver name
+        def name
+          'class_constant'
+        end
+
+        # @return [Integer] Resolution priority (100 = lowest)
+        def priority
+          PRIORITY
+        end
+
+        # Check if callable looks like a Ruby class constant path.
+        #
+        # This method checks the STRING FORMAT, not whether the class exists.
+        # Actual class existence is verified in resolve() - this allows the
+        # resolver chain to skip this resolver for callables that are clearly
+        # not class paths (e.g., "payment_handler", "./path/to/handler").
+        #
+        # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+        # @param config [Hash] Additional context
+        # @return [Boolean] true if callable looks like a class constant
+        def can_resolve?(definition, _config)
+          callable = definition.callable.to_s
+
+          # Basic validation: should look like a class constant
+          # (starts with uppercase, may contain ::)
+          callable.match?(/\A[A-Z]/)
+        end
+
+        # Resolve handler class from constant path
+        #
+        # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+        # @param config [Hash] Additional context
+        # @return [Object, nil] Handler instance or nil
+        def resolve(definition, _config)
+          callable = definition.callable.to_s
+          effective_method = definition.effective_method.to_sym
+
+          # Resolve the class constant
+          klass = resolve_constant(callable)
+          return nil unless klass
+
+          # Verify it's a class
+          unless klass.is_a?(Class)
+            @logger.debug("ClassConstantResolver: '#{callable}' is not a Class (#{klass.class})")
+            return nil
+          end
+
+          # Verify it responds to the effective method
+          unless responds_to_method?(klass, effective_method)
+            @logger.debug("ClassConstantResolver: '#{callable}' does not respond to ##{effective_method}")
+            return nil
+          end
+
+          # Instantiate with configuration
+          instantiate_handler(klass, definition.initialization)
+        rescue StandardError => e
+          @logger.debug("ClassConstantResolver: Failed to resolve '#{callable}': #{e.message}")
+          nil
+        end
+
+        private
+
+        # Resolve constant path to class
+        #
+        # @param callable [String] Class constant path
+        # @return [Class, nil] Resolved class or nil
+        def resolve_constant(callable)
+          # Use constantize from ActiveSupport if available
+          if callable.respond_to?(:constantize)
+            callable.constantize
+          else
+            Object.const_get(callable)
+          end
+        rescue NameError => e
+          @logger.debug("ClassConstantResolver: Constant '#{callable}' not found: #{e.message}")
+          nil
+        end
+
+        # Check if class or its instances respond to the method
+        #
+        # @param klass [Class] Handler class
+        # @param method_name [Symbol] Method to check
+        # @return [Boolean] true if responds to method
+        def responds_to_method?(klass, method_name)
+          # Check instance methods (most common case)
+          klass.instance_methods.include?(method_name) ||
+            # Check if the class itself responds (for class methods)
+            klass.respond_to?(method_name)
+        end
+
+        # Instantiate a handler with configuration
+        #
+        # @param klass [Class] Handler class
+        # @param initialization [Hash] Configuration to pass
+        # @return [Object] Handler instance
+        def instantiate_handler(klass, initialization)
+          arity = klass.instance_method(:initialize).arity
+
+          if arity.positive? || (arity.negative? && accepts_config_kwarg?(klass))
+            klass.new(config: initialization || {})
+          else
+            klass.new
+          end
+        end
+
+        # Check if the class accepts config: keyword argument
+        def accepts_config_kwarg?(klass)
+          params = klass.instance_method(:initialize).parameters
+          params.any? { |type, name| %i[key keyreq].include?(type) && name == :config }
+        end
+      end
+    end
+  end
+end

data/lib/tasker_core/registry/resolvers/explicit_mapping_resolver.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative 'base_resolver'
+
+module TaskerCore
+  module Registry
+    module Resolvers
+      # TAS-93: Explicit Key-to-Handler Mapping Resolver
+      #
+      # This resolver handles explicitly registered handlers with direct
+      # key → handler mappings. It has the highest priority (10) because
+      # explicit registrations should always take precedence.
+      #
+      # == Usage
+      #
+      #   resolver = ExplicitMappingResolver.new
+      #   resolver.register('payment.process', PaymentHandler)
+      #   resolver.register('payment.refund', RefundHandler.new)
+      #
+      #   # Later, during resolution
+      #   handler = resolver.resolve(definition, config)
+      #
+      # == When to Use
+      #
+      # - Handlers registered at application boot
+      # - Proc/Lambda handlers that can't be resolved by class path
+      # - Overriding inferential resolution with specific handlers
+      # - Testing with mock handlers
+      #
+      class ExplicitMappingResolver < BaseResolver
+        PRIORITY = 10 # Highest priority - explicit mappings always win
+
+        def initialize(resolver_name = 'explicit_mapping')
+          super()
+          @resolver_name = resolver_name
+          @handlers = Concurrent::Hash.new
+          @logger = TaskerCore::Logger.instance
+        end
+
+        # @return [String] Human-readable resolver name
+        def name
+          @resolver_name
+        end
+
+        # @return [Integer] Resolution priority (10 = highest)
+        def priority
+          PRIORITY
+        end
+
+        # Check if we have an explicit mapping for this callable
+        #
+        # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+        # @param config [Hash] Additional context
+        # @return [Boolean] true if callable is registered
+        def can_resolve?(definition, _config)
+          @handlers.key?(definition.callable.to_s)
+        end
+
+        # Resolve handler from explicit registration
+        #
+        # @param definition [TaskerCore::Types::HandlerDefinition] Handler configuration
+        # @param config [Hash] Additional context
+        # @return [Object, nil] Handler instance or nil
+        def resolve(definition, _config)
+          callable = definition.callable.to_s
+          handler = @handlers[callable]
+
+          return nil unless handler
+
+          instantiate_handler(handler, definition.initialization)
+        rescue StandardError => e
+          @logger.warn("ExplicitMappingResolver: Failed to instantiate '#{callable}': #{e.message}")
+          nil
+        end
+
+        # @return [Array<String>] List of registered callable keys
+        def registered_callables
+          @handlers.keys
+        end
+
+        # Register a handler with an explicit key
+        #
+        # @param key [String] Handler key (usually the callable string)
+        # @param handler [Class, Object, Proc] Handler class, instance, or callable
+        # @return [void]
+        def register(key, handler)
+          @handlers[key.to_s] = handler
+          @logger.debug("ExplicitMappingResolver: Registered '#{key}'")
+        end
+
+        # Unregister a handler
+        #
+        # @param key [String] Handler key to remove
+        # @return [Object, nil] Removed handler or nil
+        def unregister(key)
+          @handlers.delete(key.to_s)
+        end
+
+        # Check if a handler is registered
+        #
+        # @param key [String] Handler key
+        # @return [Boolean] true if registered
+        def registered?(key)
+          @handlers.key?(key.to_s)
+        end
+
+        # Clear all registered handlers
+        def clear!
+          @handlers.clear
+        end
+
+        # @return [Integer] Number of registered handlers
+        def size
+          @handlers.size
+        end
+
+        private
+
+        # Instantiate a handler with configuration
+        #
+        # @param handler [Class, Object, Proc] Handler class, instance, or callable
+        # @param initialization [Hash] Configuration to pass
+        # @return [Object] Handler instance or callable
+        def instantiate_handler(handler, initialization)
+          # Already an instance or Proc - return as-is
+          return handler if handler.is_a?(Proc) || !handler.is_a?(Class)
+
+          # Class - instantiate with config if supported
+          arity = handler.instance_method(:initialize).arity
+
+          if arity.positive? || (arity.negative? && accepts_config_kwarg?(handler))
+            handler.new(config: initialization || {})
+          else
+            handler.new
+          end
+        end
+
+        # Check if the class accepts config: keyword argument
+        def accepts_config_kwarg?(klass)
+          params = klass.instance_method(:initialize).parameters
+          params.any? { |type, name| %i[key keyreq].include?(type) && name == :config }
+        end
+      end
+    end
+  end
+end