cmdx 1.1.0 → 1.1.1

data/lib/cmdx/coercion.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Base class for implementing type coercion functionality in parameter processing.
+  # Base class for implementing parameter coercion functionality in task processing.
   #
-  # Coercions are used to convert parameter values from one type to another,
-  # supporting both built-in types and custom coercion logic. All coercion
+  # Coercions are used to convert parameter values from one type to another during
+  # task execution, enabling automatic type conversion and normalization. All coercion
   # implementations must inherit from this class and implement the abstract call method.
   class Coercion
 
@@ -16,10 +16,13 @@ module CMDx
     # @return [Object] the coerced value
     #
     # @raise [UndefinedCallError] when the coercion subclass doesn't implement call
+    # @raise [CoercionError] when coercion fails in subclass implementations
     #
     # @example Execute a coercion on a value
-    #   IntegerCoercion.call("42")
-    #   # => 42
+    #   StringCoercion.call(123) #=> "123"
+    #
+    # @example Execute with options
+    #   CustomCoercion.call("value", strict: true) #=> processed_value
     def self.call(value, options = {})
       new.call(value, options)
     end
@@ -27,21 +30,26 @@ module CMDx
     # Abstract method that must be implemented by coercion subclasses.
     #
     # This method contains the actual coercion logic to convert the input
-    # value to the desired type. Subclasses must override this method to
-    # provide their specific coercion implementation.
+    # value to the desired type. Subclasses must override this method
+    # to provide their specific coercion implementation.
     #
-    # @param _value [Object] the value to be coerced
-    # @param _options [Hash] additional options for the coercion
+    # @param value [Object] the value to be coerced (unused in base class)
+    # @param options [Hash] additional options for the coercion (unused in base class)
     #
     # @return [Object] the coerced value
     #
     # @raise [UndefinedCallError] always raised in the base class
+    # @raise [CoercionError] when coercion fails in subclass implementations
     #
     # @example Implement in a subclass
-    #   def call(value, options = {})
-    #     Integer(value)
+    #   class StringCoercion < CMDx::Coercion
+    #     def call(value, _options = {})
+    #       String(value)
+    #     rescue ArgumentError, TypeError
+    #       raise CoercionError, "could not coerce into a string"
+    #     end
     #   end
-    def call(_value, _options = {})
+    def call(value, options = {}) # rubocop:disable Lint/UnusedMethodArgument
       raise UndefinedCallError, "call method not defined in #{self.class.name}"
     end
 

data/lib/cmdx/coercion_registry.rb

@@ -1,28 +1,31 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Registry for managing type coercion definitions and execution within tasks.
+  # Registry for managing parameter type coercion functionality.
   #
-  # This registry handles the registration and execution of coercions that convert
-  # parameter values from one type to another, supporting both built-in types and
-  # custom coercion logic.
+  # CoercionRegistry provides a centralized system for storing, accessing, and
+  # executing type coercions during task parameter processing. It maintains an
+  # internal registry of coercion type keys mapped to their corresponding coercion
+  # classes or callables, supporting both built-in framework coercions and custom
+  # user-defined coercions for flexible type conversion during task execution.
   class CoercionRegistry
 
-    # The internal hash storing coercion definitions.
-    #
     # @return [Hash] hash containing coercion type keys and coercion class/callable values
     attr_reader :registry
 
-    # Initializes a new coercion registry with default type coercions.
+    # Creates a new coercion registry with built-in coercion types.
     #
-    # Sets up the registry with built-in coercions for standard Ruby types
-    # including primitives, numerics, dates, and collections.
+    # Initializes the registry with all standard framework coercions including
+    # primitive types (string, integer, float, boolean), date/time types,
+    # collection types (array, hash), numeric types (big_decimal, rational, complex),
+    # and the virtual coercion type for parameter definitions without type conversion.
     #
-    # @return [CoercionRegistry] a new coercion registry instance
+    # @return [CoercionRegistry] a new registry instance with built-in coercions
     #
-    # @example Creating a new registry
+    # @example Create a new coercion registry
     #   registry = CoercionRegistry.new
-    #   registry.registry[:string] # => Coercions::String
+    #   registry.registry.keys
+    #   #=> [:array, :big_decimal, :boolean, :complex, :date, :datetime, :float, :hash, :integer, :rational, :string, :time, :virtual]
     def initialize
       @registry = {
         array: Coercions::Array,
@@ -41,44 +44,60 @@ module CMDx
       }
     end
 
-    # Registers a custom coercion for a specific type.
+    # Registers a new coercion type in the registry.
+    #
+    # Adds or overwrites a coercion type mapping in the registry, allowing custom
+    # coercions to be used during task parameter processing. The coercion can be
+    # a class that responds to `call`, a callable object, or a symbol/string
+    # representing a method to invoke on the task instance.
     #
-    # @param type [Symbol] the type identifier for the coercion
-    # @param coercion [Object] the coercion callable (class, proc, symbol, or string)
+    # @param type [Symbol] the coercion type identifier to register
+    # @param coercion [Class, Proc, Symbol, String] the coercion implementation
     #
-    # @return [CoercionRegistry] returns self for method chaining
+    # @return [CoercionRegistry] self for method chaining
     #
-    # @example Registering a custom coercion class
-    #   registry.register(:uuid, UUIDCoercion)
+    # @example Register a custom coercion class
+    #   registry.register(:temperature, TemperatureCoercion)
     #
-    # @example Registering a proc coercion
-    #   registry.register(:upcase, ->(value, options) { value.to_s.upcase })
+    # @example Register a coercion proc
+    #   registry.register(:upcase, proc { |value, options| value.to_s.upcase })
     #
-    # @example Chaining registrations
-    #   registry.register(:custom1, MyCoercion).register(:custom2, AnotherCoercion)
+    # @example Register a method symbol
+    #   registry.register(:custom_parse, :parse_custom_format)
     def register(type, coercion)
       registry[type] = coercion
       self
     end
 
-    # Executes a coercion for the specified type and value.
+    # Executes a coercion by type on the provided value.
     #
-    # @param task [Task] the task instance executing the coercion
+    # Looks up and executes the coercion implementation for the specified type,
+    # applying it to the provided value with optional configuration. Handles
+    # different coercion implementation types including callable objects,
+    # method symbols/strings, and coercion classes.
+    #
+    # @param task [CMDx::Task] the task instance for context when calling methods
     # @param type [Symbol] the coercion type to execute
     # @param value [Object] the value to be coerced
-    # @param options [Hash] additional options for the coercion
+    # @param options [Hash] additional options passed to the coercion
+    # @option options [Object] any any additional configuration for the coercion
     #
     # @return [Object] the coerced value
     #
-    # @raise [UnknownCoercionError] when the coercion type is not registered
+    # @raise [UnknownCoercionError] when the specified coercion type is not registered
+    # @raise [CoercionError] when the coercion fails to convert the value
+    #
+    # @example Execute a built-in coercion
+    #   registry.call(task, :integer, "123")
+    #   #=> 123
     #
-    # @example Coercing a string to integer
-    #   registry.call(task, :integer, "42")
-    #   # => 42
+    # @example Execute with options
+    #   registry.call(task, :date, "2024-01-15", format: "%Y-%m-%d")
+    #   #=> #<Date: 2024-01-15>
     #
-    # @example Coercing with options
-    #   registry.call(task, :array, "a,b,c", delimiter: ",")
-    #   # => ["a", "b", "c"]
+    # @example Handle unknown coercion type
+    #   registry.call(task, :unknown_type, "value")
+    #   #=> raises UnknownCoercionError
     def call(task, type, value, options = {})
       raise UnknownCoercionError, "unknown coercion #{type}" unless registry.key?(type)
 

data/lib/cmdx/configuration.rb

@@ -3,7 +3,15 @@
 module CMDx
 
   # Global configuration class for CMDx framework settings.
-  # Manages logging, middleware, callbacks, coercions, validators, and halt conditions.
+  #
+  # Manages logging, middleware, callbacks, coercions, validators, and halt conditions
+  # for the entire CMDx framework. The Configuration class provides centralized control
+  # over framework behavior including task execution flow, error handling, and component
+  # registration. All settings configured here become defaults for tasks and workflows
+  # unless explicitly overridden at the task or workflow level.
+  #
+  # The configuration system supports both global and per-task customization, allowing
+  # fine-grained control over framework behavior while maintaining sensible defaults.
   class Configuration
 
     DEFAULT_HALT = "failed"
@@ -29,13 +37,18 @@ module CMDx
     # @return [String, Array<String>] Result statuses that halt workflow execution
     attr_accessor :workflow_halt
 
-    # Initialize a new Configuration instance with default settings.
+    # Creates a new configuration instance with default settings.
+    #
+    # Initializes all configuration attributes with sensible defaults including
+    # a stdout logger with line formatting, empty registries for extensibility
+    # components, and default halt conditions for both tasks and workflows.
     #
-    # @example
-    #   config = CMDx::Configuration.new
-    #   config.logger.level = Logger::DEBUG
+    # @return [Configuration] a new configuration instance with default settings
     #
-    # @return [Configuration] A new configuration instance
+    # @example Create a new configuration
+    #   config = Configuration.new
+    #   config.logger.class #=> Logger
+    #   config.task_halt #=> "failed"
     def initialize
       @logger        = ::Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
       @middlewares   = MiddlewareRegistry.new
@@ -46,14 +59,26 @@ module CMDx
       @workflow_halt = DEFAULT_HALT
     end
 
-    # Convert the configuration to a hash representation.
+    # Converts the configuration to a hash representation.
     #
-    # @example
-    #   config = CMDx::Configuration.new
-    #   hash = config.to_h
-    #   puts hash[:task_halt] # => "failed"
+    # Creates a hash containing all configuration attributes for serialization,
+    # inspection, or transfer between processes. The hash includes all registries
+    # and settings in their current state.
+    #
+    # @return [Hash] hash representation of the configuration
+    # @option return [Logger] :logger the configured logger instance
+    # @option return [MiddlewareRegistry] :middlewares the middleware registry
+    # @option return [CallbackRegistry] :callbacks the callback registry
+    # @option return [CoercionRegistry] :coercions the coercion registry
+    # @option return [ValidatorRegistry] :validators the validator registry
+    # @option return [String, Array<String>] :task_halt the task halt configuration
+    # @option return [String, Array<String>] :workflow_halt the workflow halt configuration
     #
-    # @return [Hash] Hash containing all configuration values
+    # @example Convert configuration to hash
+    #   config = Configuration.new
+    #   hash = config.to_h
+    #   hash[:logger].class #=> Logger
+    #   hash[:task_halt] #=> "failed"
     def to_h
       {
         logger: @logger,
@@ -70,33 +95,49 @@ module CMDx
 
   module_function
 
-  # Get the current global configuration instance.
-  # Creates a new configuration if none exists.
+  # Returns the current global configuration instance.
   #
-  # @example
-  #   config = CMDx.configuration
-  #   config.logger.level = Logger::INFO
+  # Provides access to the singleton configuration instance used by the entire
+  # CMDx framework. Creates a new configuration with default settings if none
+  # exists. This method is thread-safe and ensures only one configuration
+  # instance exists per process.
+  #
+  # @return [Configuration] the current global configuration instance
   #
-  # @return [Configuration] The global configuration instance
+  # @example Access global configuration
+  #   config = CMDx.configuration
+  #   config.logger.level = Logger::DEBUG
+  #   config.task_halt = ["failed", "skipped"]
   def configuration
     return @configuration if @configuration
 
     @configuration ||= Configuration.new
   end
 
-  # Configure the global CMDx settings using a block.
+  # Configures the global CMDx settings using a block.
   #
-  # @example
-  #   CMDx.configure do |config|
-  #     config.task_halt = ["failed", "error"]
-  #     config.logger.level = Logger::DEBUG
-  #   end
+  # Yields the current configuration instance to the provided block for
+  # modification. This is the recommended way to configure CMDx as it
+  # provides a clean DSL-like interface for setting up the framework.
   #
-  # @yield [Configuration] The configuration instance
+  # @param block [Proc] configuration block that receives the configuration instance
   #
-  # @return [Configuration] The configured instance
+  # @return [Configuration] the configured configuration instance
   #
-  # @raise [ArgumentError] If no block is provided
+  # @raise [ArgumentError] if no block is provided
+  #
+  # @example Configure CMDx settings
+  #   CMDx.configure do |config|
+  #     config.logger.level = Logger::INFO
+  #     config.task_halt = ["failed", "skipped"]
+  #     config.middlewares.register(CMDx::Middlewares::Timeout.new(seconds: 30))
+  #   end
+  #
+  # @example Configure with custom logger
+  #   CMDx.configure do |config|
+  #     config.logger = Rails.logger
+  #     config.logger.formatter = CMDx::LogFormatters::JSON.new
+  #   end
   def configure
     raise ArgumentError, "block required" unless block_given?
 
@@ -105,13 +146,25 @@ module CMDx
     config
   end
 
-  # Reset the global configuration to default values.
+  # Resets the global configuration to default settings.
+  #
+  # Creates a new configuration instance with default settings, discarding
+  # any existing configuration. This is useful for testing scenarios or
+  # when you need to start with a clean configuration state.
+  #
+  # @return [Configuration] a new configuration instance with default settings
+  #
+  # @example Reset to defaults
+  #   CMDx.configure { |c| c.task_halt = ["failed", "skipped"] }
+  #   CMDx.configuration.task_halt #=> ["failed", "skipped"]
   #
-  # @example
   #   CMDx.reset_configuration!
-  #   CMDx.configuration.task_halt # => "failed"
+  #   CMDx.configuration.task_halt #=> "failed"
   #
-  # @return [Configuration] A new configuration instance with defaults
+  # @example Use in test setup
+  #   RSpec.configure do |config|
+  #     config.before(:each) { CMDx.reset_configuration! }
+  #   end
   def reset_configuration!
     @configuration = Configuration.new
   end

data/lib/cmdx/context.rb

@@ -1,38 +1,49 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter and data context for task execution.
+  # Execution context container for task parameter storage and access.
   #
-  # Context provides flexible data storage and access patterns for task
-  # parameters and runtime data. Built on LazyStruct, it supports both
-  # hash-like and object-like access patterns with dynamic attribute
-  # assignment and automatic key normalization.
+  # Context provides normalized parameter storage for task execution, inheriting
+  # from LazyStruct to provide flexible attribute access patterns. It serves as
+  # the primary interface for storing and retrieving execution parameters, allowing
+  # both hash-style and method-style attribute access with automatic key normalization.
+  # Context instances are used throughout task execution to maintain parameter state
+  # and provide consistent data access across the task lifecycle.
   class Context < LazyStruct
 
-    # Creates or returns a context instance from the given input.
+    # Creates or returns a Context instance from the provided input.
     #
-    # This method provides a safe way to build context instances, returning
-    # the input unchanged if it's already a Context instance and not frozen,
-    # otherwise creating a new Context instance with the provided data.
+    # This factory method normalizes various input types into a proper Context instance,
+    # ensuring consistent context handling throughout the framework. If the input is
+    # already a Context instance and not frozen, it returns the input unchanged to
+    # avoid unnecessary object creation. Otherwise, it creates a new Context instance
+    # with the provided data.
     #
-    # @param context [Hash, Context, Object] input data to build context from
+    # @param context [Hash, Context, Object] input data to convert to Context
+    # @option context [Object] any any attribute keys and values for context initialization
     #
     # @return [Context] a Context instance containing the provided data
     #
-    # @raise [ArgumentError] if the input doesn't respond to to_h
+    # @example Create context from hash
+    #   context = Context.build(user_id: 123, action: "process")
+    #   context.user_id #=> 123
+    #   context.action #=> "process"
     #
-    # @example Build context from hash
-    #   Context.build(name: "John", age: 30)
-    #   # => #<CMDx::Context :name="John" :age=30>
+    # @example Return existing unfrozen context
+    #   existing = Context.new(status: "active")
+    #   result = Context.build(existing)
+    #   result.equal?(existing) #=> true
     #
-    # @example Build context from existing context
-    #   existing = Context.build(user_id: 123)
-    #   Context.build(existing)
-    #   # => returns existing context unchanged
+    # @example Create new context from frozen context
+    #   frozen_context = Context.new(data: "test").freeze
+    #   new_context = Context.build(frozen_context)
+    #   new_context.equal?(frozen_context) #=> false
+    #   new_context.data #=> "test"
     #
-    # @example Build context from hash-like object
-    #   Context.build(OpenStruct.new(status: "active"))
-    #   # => #<CMDx::Context :status="active">
+    # @example Create context from empty input
+    #   context = Context.build
+    #   context.class #=> CMDx::Context
+    #   context.to_h #=> {}
     def self.build(context = {})
       return context if context.is_a?(self) && !context.frozen?
 

data/lib/cmdx/core_ext/hash.rb

@@ -16,13 +16,13 @@ module CMDx
       #
       # @example Fetch with symbol key
       #   hash = { name: "John", "age" => 30 }
-      #   hash.cmdx_fetch(:name) # => "John"
-      #   hash.cmdx_fetch(:age)  # => 30
+      #   hash.cmdx_fetch(:name) #=> "John"
+      #   hash.cmdx_fetch(:age)  #=> 30
       #
       # @example Fetch with string key
       #   hash = { name: "John", "age" => 30 }
-      #   hash.cmdx_fetch("name") # => "John"
-      #   hash.cmdx_fetch("age")  # => 30
+      #   hash.cmdx_fetch("name") #=> "John"
+      #   hash.cmdx_fetch("age")  #=> 30
       def cmdx_fetch(key)
         case key
         when Symbol then fetch(key) { self[key.to_s] }
@@ -40,11 +40,11 @@ module CMDx
       #
       # @example Check key existence
       #   hash = { name: "John", "age" => 30 }
-      #   hash.cmdx_key?(:name)   # => true
-      #   hash.cmdx_key?("name")  # => true
-      #   hash.cmdx_key?(:age)    # => true
-      #   hash.cmdx_key?("age")   # => true
-      #   hash.cmdx_key?(:missing) # => false
+      #   hash.cmdx_key?(:name)   #=> true
+      #   hash.cmdx_key?("name")  #=> true
+      #   hash.cmdx_key?(:age)    #=> true
+      #   hash.cmdx_key?("age")   #=> true
+      #   hash.cmdx_key?(:missing) #=> false
       def cmdx_key?(key)
         key?(key) || key?(
           case key
@@ -66,10 +66,10 @@ module CMDx
       #
       # @example Check method or key response
       #   hash = { name: "John", "age" => 30 }
-      #   hash.cmdx_respond_to?(:keys)     # => true (method exists)
-      #   hash.cmdx_respond_to?(:name)     # => true (key exists)
-      #   hash.cmdx_respond_to?("age")     # => true (key exists)
-      #   hash.cmdx_respond_to?(:missing)  # => false
+      #   hash.cmdx_respond_to?(:keys)     #=> true (method exists)
+      #   hash.cmdx_respond_to?(:name)     #=> true (key exists)
+      #   hash.cmdx_respond_to?("age")     #=> true (key exists)
+      #   hash.cmdx_respond_to?(:missing)  #=> false
       def cmdx_respond_to?(key, include_private = false)
         respond_to?(key.to_sym, include_private) || cmdx_key?(key)
       rescue NoMethodError

data/lib/cmdx/core_ext/module.rb

@@ -71,7 +71,7 @@ module CMDx
       #     cmdx_attr_setting :timeout, default: 30
       #   end
       #
-      #   BaseTask.timeout # => 30
+      #   BaseTask.timeout #=> 30
       #
       # @example Define a setting with a dynamic default
       #   class Task

data/lib/cmdx/core_ext/object.rb

@@ -18,14 +18,14 @@ module CMDx
       # @return [Object, nil] the result of the method call, proc evaluation, or hash access; nil if not found
       #
       # @example Try calling a method
-      #   "hello".cmdx_try(:upcase) # => "HELLO"
-      #   "hello".cmdx_try(:missing) # => nil
+      #   "hello".cmdx_try(:upcase) #=> "HELLO"
+      #   "hello".cmdx_try(:missing) #=> nil
       #
       # @example Try evaluating a proc
-      #   obj.cmdx_try(-> { self.class.name }) # => "String"
+      #   obj.cmdx_try(-> { self.class.name }) #=> "String"
       #
       # @example Try accessing a hash key
-      #   {name: "John"}.cmdx_try(:name) # => "John"
+      #   {name: "John"}.cmdx_try(:name) #=> "John"
       def cmdx_try(key, *args, **kwargs, &)
         if key.is_a?(Proc)
           return instance_eval(&key) unless is_a?(Module) || key.inspect.include?("(lambda)")
@@ -53,13 +53,13 @@ module CMDx
       # @return [Boolean] true if conditions are met, false otherwise
       #
       # @example Evaluate with if condition
-      #   user.cmdx_eval(if: :active?) # => true if user.active? is truthy
+      #   user.cmdx_eval(if: :active?) #=> true if user.active? is truthy
       #
       # @example Evaluate with unless condition
-      #   user.cmdx_eval(unless: :banned?) # => true if user.banned? is falsy
+      #   user.cmdx_eval(unless: :banned?) #=> true if user.banned? is falsy
       #
       # @example Evaluate with both conditions
-      #   user.cmdx_eval(if: :active?, unless: :banned?) # => true if active and not banned
+      #   user.cmdx_eval(if: :active?, unless: :banned?) #=> true if active and not banned
       def cmdx_eval(options = {})
         if options[:if] && options[:unless]
           cmdx_try(options[:if]) && !cmdx_try(options[:unless])
@@ -81,13 +81,13 @@ module CMDx
       # @return [Object] the result of method call, proc evaluation, or the value itself
       #
       # @example Yield a method call
-      #   "hello".cmdx_yield(:upcase) # => "HELLO"
+      #   "hello".cmdx_yield(:upcase) #=> "HELLO"
       #
       # @example Yield a static value
-      #   obj.cmdx_yield("static") # => "static"
+      #   obj.cmdx_yield("static") #=> "static"
       #
       # @example Yield a proc
-      #   obj.cmdx_yield(-> { Time.now }) # => 2023-01-01 12:00:00 UTC
+      #   obj.cmdx_yield(-> { Time.now }) #=> 2023-01-01 12:00:00 UTC
       def cmdx_yield(key, ...)
         if key.is_a?(Symbol) || key.is_a?(String)
           return key unless respond_to?(key, true)
@@ -108,10 +108,10 @@ module CMDx
       # @return [Object] the result of calling the object, or the object itself if not callable
       #
       # @example Invoke a proc
-      #   proc { "hello" }.cmdx_call # => "hello"
+      #   proc { "hello" }.cmdx_call #=> "hello"
       #
       # @example Invoke a non-callable object
-      #   "hello".cmdx_call # => "hello"
+      #   "hello".cmdx_call #=> "hello"
       def cmdx_call(...)
         return self unless respond_to?(:call)