cmdx 1.1.0 → 1.1.1

data/lib/cmdx/task_processor.rb

@@ -1,82 +1,72 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Handles the execution orchestration of Task instances with middleware and callback support.
+  # Core task execution processor handling the complete task lifecycle.
   #
-  # TaskProcessor provides the core execution logic for Task instances, managing
-  # the complete lifecycle including parameter validation, callback execution,
-  # middleware processing, error handling, and result finalization. It supports
-  # both regular and bang execution modes with different error handling behaviors.
+  # TaskProcessor manages the execution pipeline for individual tasks, coordinating
+  # parameter validation, callback invocation, error handling, and result state
+  # management. It provides both safe execution (capturing exceptions) and unsafe
+  # execution (re-raising exceptions) modes through call and call! methods respectively.
+  # The processor ensures proper state transitions, handles fault propagation, and
+  # maintains execution context throughout the task lifecycle.
   class TaskProcessor
 
     # @return [CMDx::Task] The task instance being executed
     attr_reader :task
 
-    # Creates a new TaskProcessor instance for the specified task.
+    # Creates a new task processor for the specified task instance.
     #
-    # @param task [CMDx::Task] the task instance to execute
+    # @param task [CMDx::Task] the task instance to process
     #
-    # @return [TaskProcessor] a new TaskProcessor instance
+    # @return [TaskProcessor] a new processor instance for the task
     #
-    # @example Create processor for a task
+    # @example Create a processor for a task
     #   task = MyTask.new(user_id: 123)
     #   processor = TaskProcessor.new(task)
-    #   processor.task # => #<MyTask:...>
     def initialize(task)
       @task = task
     end
 
     class << self
 
-      # Executes a task with full error handling and result management.
+      # Executes the specified task and returns the result without raising exceptions.
       #
-      # This is a convenience method that creates a new TaskProcessor instance
-      # and immediately calls the safe execution method. It provides the same
-      # comprehensive error handling as the instance method, catching faults
-      # and StandardErrors and converting them to failed results.
+      # Creates a new processor instance and executes the task through the complete
+      # lifecycle including validation, callbacks, and error handling. Exceptions
+      # are captured in the result rather than being raised to the caller.
       #
       # @param task [CMDx::Task] the task instance to execute
       #
-      # @return [Result] the task's result object after execution
+      # @return [CMDx::Result] the execution result containing state and status information
       #
-      # @raise [UndefinedCallError] if the task doesn't implement a call method
-      #
-      # @example Execute a task safely using class method
-      #   task = MyTask.new(name: "test")
-      #   result = TaskProcessor.call(task)
-      #   result.success? # => true or false
-      #
-      # @example Handle task with validation errors
-      #   task = MyTask.new # missing required parameters
+      # @example Execute a task safely
+      #   task = ProcessDataTask.new(data: raw_data)
       #   result = TaskProcessor.call(task)
-      #   result.failed? # => true
+      #   puts result.status #=> "success", "failed", or "skipped"
       def call(task)
         new(task).call
       end
 
-      # Executes a task with bang semantics, re-raising exceptions.
+      # Executes the specified task and raises exceptions on failure.
       #
-      # This is a convenience method that creates a new TaskProcessor instance
-      # and immediately calls the strict execution method. It provides the same
-      # strict error handling as the instance method, re-raising exceptions
-      # after proper cleanup and chain clearing.
+      # Creates a new processor instance and executes the task through the complete
+      # lifecycle. Unlike call, this method will re-raise exceptions including
+      # Fault exceptions when their status matches the task's halt configuration.
       #
       # @param task [CMDx::Task] the task instance to execute
       #
-      # @return [Result] the task's result object after execution
+      # @return [CMDx::Result] the execution result on success
       #
-      # @raise [UndefinedCallError] if the task doesn't implement a call method
-      # @raise [Fault] if a fault occurs during execution
+      # @raise [CMDx::Fault] when a fault occurs with status matching task halt configuration
+      # @raise [StandardError] when unexpected errors occur during execution
       #
-      # @example Execute task with strict error handling
-      #   task = MyTask.new(name: "test")
-      #   result = TaskProcessor.call!(task) # raises on failure
-      #
-      # @example Handle exceptions in bang mode
+      # @example Execute a task with exception raising
+      #   task = CriticalTask.new(operation: "delete")
       #   begin
-      #     TaskProcessor.call!(task)
+      #     result = TaskProcessor.call!(task)
+      #     puts "Success: #{result.status}"
       #   rescue CMDx::Fault => e
-      #     puts "Task failed: #{e.result.status}"
+      #     puts "Task failed: #{e.message}"
       #   end
       def call!(task)
         new(task).call!
@@ -84,28 +74,24 @@ module CMDx
 
     end
 
-    # Executes the task with full error handling and result management.
-    #
-    # This method provides safe task execution with comprehensive error handling,
-    # automatic result state management, and callback execution. Faults are caught
-    # and processed according to task halt settings, while StandardErrors are
-    # converted to failed results.
+    # Executes the task with safe error handling and returns the result.
     #
-    # @return [Result] the task's result object after execution
+    # Runs the complete task execution pipeline including parameter validation,
+    # callback invocation, and the task's call method. Captures all exceptions
+    # as result status rather than raising them, ensuring the chain continues
+    # execution. Handles both standard errors and Fault exceptions according
+    # to the task's halt configuration.
     #
-    # @raise [UndefinedCallError] if the task doesn't implement a call method
+    # @return [CMDx::Result] the execution result with captured state and status
     #
-    # @example Execute a task safely
-    #   task = MyTask.new(name: "test")
+    # @example Safe task execution
     #   processor = TaskProcessor.new(task)
     #   result = processor.call
-    #   result.success? # => true or false
-    #
-    # @example Handle task with validation errors
-    #   task = MyTask.new # missing required parameters
-    #   processor = TaskProcessor.new(task)
-    #   result = processor.call
-    #   result.failed? # => true
+    #   if result.success?
+    #     puts "Task completed successfully"
+    #   else
+    #     puts "Task failed: #{result.metadata[:reason]}"
+    #   end
     def call
       task.result.runtime do
         before_call
@@ -128,27 +114,27 @@ module CMDx
       terminate_call
     end
 
-    # Executes the task with bang semantics, re-raising exceptions.
+    # Executes the task with exception raising on halt conditions.
     #
-    # This method provides strict task execution where exceptions are re-raised
-    # after proper cleanup. It clears the execution chain on failures and
-    # provides different error handling behavior compared to the regular call method.
+    # Runs the complete task execution pipeline including parameter validation,
+    # callback invocation, and the task's call method. Unlike call, this method
+    # will re-raise Fault exceptions when their status matches the task's halt
+    # configuration, and clears the execution chain before raising.
     #
-    # @return [Result] the task's result object after execution
+    # @return [CMDx::Result] the execution result on successful completion
     #
-    # @raise [UndefinedCallError] if the task doesn't implement a call method
-    # @raise [Fault] if a fault occurs during execution
+    # @raise [CMDx::Fault] when a fault occurs with status matching task halt configuration
+    # @raise [CMDx::UndefinedCallError] when the task's call method is not implemented
+    # @raise [StandardError] when unexpected errors occur during execution
     #
-    # @example Execute task with strict error handling
-    #   task = MyTask.new(name: "test")
-    #   processor = TaskProcessor.new(task)
-    #   result = processor.call! # raises on failure
-    #
-    # @example Handle exceptions in bang mode
+    # @example Task execution with exception raising
+    #   processor = TaskProcessor.new(critical_task)
     #   begin
-    #     processor.call!
+    #     result = processor.call!
+    #     puts "Task succeeded"
     #   rescue CMDx::Fault => e
-    #     puts "Task failed: #{e.result.status}"
+    #     puts "Critical failure: #{e.message}"
+    #     # Chain is cleared, execution stops
     #   end
     def call!
       task.result.runtime do
@@ -173,7 +159,11 @@ module CMDx
 
     private
 
-    # Executes pre-execution callbacks and parameter validation.
+    # Executes pre-execution callbacks and sets the task to executing state.
+    #
+    # Invokes before_execution callbacks, transitions the result to executing
+    # state, and triggers on_executing callbacks. This method prepares the
+    # task for execution and notifies registered callbacks about the state change.
     #
     # @return [void]
     def before_call
@@ -183,16 +173,14 @@ module CMDx
       task.cmd_callbacks.call(task, :on_executing)
     end
 
-    # Validates task parameters and handles validation errors.
+    # Validates task parameters and handles validation failures.
     #
-    # This method orchestrates the parameter validation process by executing
-    # validation callbacks, performing parameter validation, and handling
-    # any validation errors that occur. If validation fails, the task result
-    # is marked as failed with detailed error messages.
+    # Executes parameter validation callbacks, validates all task parameters
+    # against their defined rules, and sets the task result to failed if
+    # validation errors are found. Collects all validation messages into
+    # the result metadata.
     #
     # @return [void]
-    #
-    # @raise [Exception] Validations, coercions, or exceptions
     def validate_parameters
       task.cmd_callbacks.call(task, :before_validation)
 
@@ -207,19 +195,28 @@ module CMDx
       task.cmd_callbacks.call(task, :after_validation)
     end
 
-    # Clears the execution chain and re-raises the given exception.
+    # Clears the execution chain and raises the specified exception.
     #
-    # @param exception [Exception] the exception to re-raise after chain cleanup
+    # This method is used to clean up the execution context before
+    # re-raising exceptions, ensuring that the chain state is properly
+    # reset when execution cannot continue.
     #
-    # @return [void] this method never returns as it always raises
+    # @param exception [Exception] the exception to raise after clearing the chain
     #
-    # @raise [Exception] always re-raises the provided exception
+    # @return [void]
+    #
+    # @raise [Exception] the provided exception after chain cleanup
     def raise!(exception)
       Chain.clear
       raise(exception)
     end
 
-    # Executes post-execution callbacks based on result state and status.
+    # Executes post-execution callbacks based on task result state and status.
+    #
+    # Invokes appropriate callbacks based on the task's final execution state
+    # (success, failure, etc.) and status. Handles both state-specific and
+    # status-specific callback invocation, as well as general execution
+    # completion callbacks.
     #
     # @return [void]
     def after_call
@@ -233,9 +230,13 @@ module CMDx
       task.cmd_callbacks.call(task, :after_execution)
     end
 
-    # Finalizes task execution with immutability and logging.
+    # Finalizes task execution by freezing state and logging results.
     #
-    # @return [Result] the task's result object
+    # Applies immutability to the task instance and logs the execution
+    # result. This method ensures that the task state cannot be modified
+    # after execution and provides visibility into the execution outcome.
+    #
+    # @return [void]
     def terminate_call
       Immutator.call(task)
       ResultLogger.call(task.result)

data/lib/cmdx/task_serializer.rb

@@ -1,33 +1,46 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Serializes Task objects into hash representations for external consumption.
-  # Provides a consistent interface for converting task execution data into
-  # structured format suitable for logging, API responses, or persistence.
+  # Task serialization module for converting task objects to hash format.
+  #
+  # TaskSerializer provides functionality to serialize task objects into a
+  # standardized hash representation that includes essential metadata about
+  # the task such as its index, chain ID, type, class, ID, and tags. The
+  # serialized format is commonly used for debugging, logging, and introspection
+  # purposes throughout the task execution pipeline.
   module TaskSerializer
 
     module_function
 
-    # Converts a task object into a hash representation containing task metadata.
-    # Extracts key task attributes including execution index, chain association,
-    # type classification, and associated tags for complete task identification.
+    # Serializes a task object into a hash representation.
     #
-    # @param task [Task] the task instance to serialize
+    # Converts a task instance into a standardized hash format containing
+    # key metadata about the task's execution context and classification.
+    # The serialization includes information from the task's result, chain,
+    # and command settings to provide comprehensive task identification.
     #
-    # @return [Hash] hash containing task metadata and execution details
+    # @param task [CMDx::Task, CMDx::Workflow] the task or workflow object to serialize
     #
-    # @raise [NoMethodError] if task doesn't respond to required methods
+    # @return [Hash] a hash containing the task's metadata
+    # @option return [Integer] :index the task's position index in the execution chain
+    # @option return [String] :chain_id the unique identifier of the task's execution chain
+    # @option return [String] :type the task type, either "Task" or "Workflow"
+    # @option return [String] :class the full class name of the task
+    # @option return [String] :id the unique identifier of the task instance
+    # @option return [Array] :tags the tags associated with the task from cmd settings
     #
-    # @example Serializing a task
-    #   task = UserRegistrationTask.call(email: "user@example.com")
+    # @raise [NoMethodError] if the task doesn't respond to required methods
+    #
+    # @example Serialize a basic task
+    #   task = ProcessDataTask.new
     #   TaskSerializer.call(task)
-    #   # => {
+    #   #=> {
     #   #   index: 0,
     #   #   chain_id: "abc123",
     #   #   type: "Task",
-    #   #   class: "UserRegistrationTask",
+    #   #   class: "ProcessDataTask",
     #   #   id: "def456",
-    #   #   tags: [:authentication, :user_management]
+    #   #   tags: []
     #   # }
     def call(task)
       {

data/lib/cmdx/utils/monotonic_runtime.rb

@@ -19,12 +19,10 @@ module CMDx
       # @return [Integer] the execution time in milliseconds
       #
       # @example Basic usage
-      #   runtime = MonotonicRuntime.call { sleep(0.1) }
-      #   # => 100 (approximately)
+      #   MonotonicRuntime.call { sleep(0.1) } #=> 100 (approximately)
       #
       # @example Measuring database query time
-      #   query_time = MonotonicRuntime.call { User.find(1) }
-      #   # => 15 (milliseconds)
+      #   MonotonicRuntime.call { User.find(1) } #=> 15 (milliseconds)
       def call(&)
         now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
         yield

data/lib/cmdx/validator.rb

@@ -1,46 +1,55 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Base class for implementing validation functionality in parameter processing.
+  # Base class for implementing parameter validation functionality in task processing.
   #
-  # Validators are used to validate parameter values during task execution to
-  # ensure data integrity and business rule compliance. All validator implementations
-  # must inherit from this class and implement the abstract call method.
+  # Validators are used to validate parameter values against specific rules and constraints,
+  # supporting both built-in validation types and custom validation logic. All validator
+  # implementations must inherit from this class and implement the abstract call method.
   class Validator
 
     # Executes a validator by creating a new instance and calling it.
     #
     # @param value [Object] the value to be validated
-    # @param options [Hash] optional validation configuration
+    # @param options [Hash] additional options for the validation
     #
-    # @return [Object] the result of the validation execution
+    # @return [Object] the validated value if validation passes
     #
     # @raise [UndefinedCallError] when the validator subclass doesn't implement call
+    # @raise [ValidationError] when validation fails
     #
     # @example Execute a validator on a value
-    #   MyValidator.call("example", { min_length: 5 })
+    #   PresenceValidator.call("some_value") #=> "some_value"
+    #
+    # @example Execute with options
+    #   NumericValidator.call(42, greater_than: 10) #=> 42
     def self.call(value, options = {})
       new.call(value, options)
     end
 
     # Abstract method that must be implemented by validator subclasses.
     #
-    # This method contains the actual validation logic to be executed.
-    # Subclasses must override this method to provide their specific
-    # validation implementation.
+    # This method contains the actual validation logic to verify the input
+    # value meets the specified criteria. Subclasses must override this method
+    # to provide their specific validation implementation.
     #
-    # @param _value [Object] the value to be validated
-    # @param _options [Hash] optional validation configuration
+    # @param value [Object] the value to be validated
+    # @param options [Hash] additional options for the validation
     #
-    # @return [Object] the result of the validation execution
+    # @return [Object] the validated value if validation passes
     #
     # @raise [UndefinedCallError] always raised in the base class
+    # @raise [ValidationError] when validation fails in subclass implementations
     #
     # @example Implement in a subclass
-    #   def call(value, options)
-    #     raise ValidationError, "Value too short" if value.length < options[:min_length]
+    #   class BlankValidator < CMDx::Validator
+    #     def call(value, options = {})
+    #       if value.nil? || value.empty?
+    #         raise ValidationError, options[:message] || "Value cannot be blank"
+    #       end
+    #     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/validator_registry.rb

@@ -1,24 +1,30 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Registry for managing validator definitions and execution within tasks.
+  # Registry for parameter validation handlers in the CMDx framework.
   #
-  # This registry handles the registration and execution of validators for
-  # parameter validation, including built-in validators and custom validators
-  # that can be registered at runtime.
+  # ValidatorRegistry manages the collection of validator implementations
+  # that can be used for parameter validation in tasks. It provides a
+  # centralized registry where validators can be registered by type and
+  # invoked during parameter processing. The registry comes pre-loaded
+  # with built-in validators for common validation scenarios.
   class ValidatorRegistry
 
-    # The internal hash storing validator definitions.
-    #
-    # @return [Hash] hash containing validator type keys and validator class values
+    # @return [Hash] internal hash storing validator implementations by type
     attr_reader :registry
 
-    # Initializes a new validator registry with built-in validators.
+    # Creates a new validator registry with built-in validators.
+    #
+    # The registry is initialized with standard validators including
+    # exclusion, format, inclusion, length, numeric, and presence validation.
+    # These built-in validators provide common validation functionality
+    # that can be immediately used without additional registration.
     #
-    # @return [ValidatorRegistry] a new validator registry instance
+    # @return [ValidatorRegistry] a new registry instance with built-in validators
     #
-    # @example Creating a validator registry
-    #   ValidatorRegistry.new
+    # @example Create a new validator registry
+    #   registry = ValidatorRegistry.new
+    #   registry.registry.keys #=> [:exclusion, :format, :inclusion, :length, :numeric, :presence]
     def initialize
       @registry = {
         exclusion: Validators::Exclusion,
@@ -30,46 +36,62 @@ module CMDx
       }
     end
 
-    # Registers a custom validator for a specific type.
+    # Registers a new validator implementation for the specified type.
+    #
+    # This method allows custom validators to be added to the registry,
+    # enabling extended validation functionality beyond the built-in
+    # validators. The validator can be a class, symbol, string, or proc
+    # that implements the validation logic.
     #
-    # @param type [Symbol] the validator type to register
-    # @param validator [Class, Module, Symbol, Proc] the validator to register
+    # @param type [Symbol] the validator type identifier
+    # @param validator [Class, Symbol, String, Proc] the validator implementation
     #
     # @return [ValidatorRegistry] returns self for method chaining
     #
-    # @example Registering a custom validator class
+    # @example Register a custom validator class
     #   registry.register(:email, EmailValidator)
     #
-    # @example Registering a Proc validator
-    #   registry.register(:custom, ->(value, opts) { value.length > 3 })
+    # @example Register a symbol validator
+    #   registry.register(:zipcode, :validate_zipcode)
     #
-    # @example Registering a Symbol validator
-    #   registry.register(:password, :validate_password_strength)
+    # @example Register a proc validator
+    #   registry.register(:positive, ->(value, options) { value > 0 })
     #
-    # @example Chaining validator registrations
-    #   registry.register(:phone, PhoneValidator)
-    #           .register(:zipcode, ZipcodeValidator)
+    # @example Method chaining
+    #   registry.register(:email, EmailValidator)
+    #           .register(:phone, PhoneValidator)
     def register(type, validator)
       registry[type] = validator
       self
     end
 
-    # Executes validation for a specific type on a given value.
+    # Executes validation for a parameter value using the specified validator type.
+    #
+    # This method performs validation by looking up the registered validator
+    # for the given type and executing it with the provided value and options.
+    # The validation is only performed if the task's evaluation of the options
+    # returns a truthy value, allowing for conditional validation.
     #
-    # @param task [Task] the task instance to execute validation on
-    # @param type [Symbol] the validator type to execute
+    # @param task [Task] the task instance performing validation
+    # @param type [Symbol] the validator type to use
     # @param value [Object] the value to validate
-    # @param options [Hash] options for conditional validation execution
+    # @param options [Hash] validation options and configuration
     #
-    # @return [Object, nil] returns the validation result or nil if skipped
+    # @return [Object, nil] the validation result or nil if validation was skipped
     #
-    # @raise [UnknownValidatorError] when the validator type is not registered
+    # @raise [UnknownValidatorError] if the specified validator type is not registered
     #
-    # @example Validating with a built-in validator
+    # @example Validate with a built-in validator
     #   registry.call(task, :presence, "", {})
+    #   #=> may raise ValidationError if value is blank
+    #
+    # @example Validate with options
+    #   registry.call(task, :length, "hello", minimum: 3, maximum: 10)
+    #   #=> validates string length is between 3 and 10 characters
     #
-    # @example Validating with options
-    #   registry.call(task, :length, "test", { minimum: 5 })
+    # @example Conditional validation that gets skipped
+    #   registry.call(task, :presence, "", if: -> { false })
+    #   #=> returns nil without performing validation
     def call(task, type, value, options = {})
       raise UnknownValidatorError, "unknown validator #{type}" unless registry.key?(type)
       return unless task.cmdx_eval(options)

data/lib/cmdx/validators/exclusion.rb

@@ -35,7 +35,7 @@ module CMDx
       #
       # @example Valid exclusion
       #   Validators::Exclusion.call("user", exclusion: { in: ["admin", "root"] })
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Using a custom message
       #   Validators::Exclusion.call("admin", exclusion: { in: ["admin", "root"], message: "Reserved username not allowed" })

data/lib/cmdx/validators/format.rb

@@ -25,7 +25,7 @@ module CMDx
       #
       # @example Validating with a positive pattern
       #   Validators::Format.call("user123", format: { with: /\A[a-z]+\d+\z/ })
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Validating with a negative pattern
       #   Validators::Format.call("admin", format: { without: /admin|root/ })
@@ -33,7 +33,7 @@ module CMDx
       #
       # @example Validating with both patterns
       #   Validators::Format.call("user123", format: { with: /\A[a-z]+\d+\z/, without: /admin|root/ })
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Invalid format with positive pattern
       #   Validators::Format.call("123abc", format: { with: /\A[a-z]+\d+\z/ })

data/lib/cmdx/validators/inclusion.rb

@@ -27,11 +27,11 @@ module CMDx
       #
       # @example Including from an array
       #   Validators::Inclusion.call("user", inclusion: { in: ["user", "admin"] })
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Including from a range
       #   Validators::Inclusion.call(5, inclusion: { in: 1..10 })
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Invalid inclusion from array
       #   Validators::Inclusion.call("guest", inclusion: { in: ["user", "admin"] })

data/lib/cmdx/validators/length.rb

@@ -39,7 +39,7 @@ module CMDx
       #
       # @example Validating within a range
       #   Validators::Length.call("hello", length: { within: 1..10 })
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Validating minimum length
       #   Validators::Length.call("hi", length: { min: 5 })
@@ -47,7 +47,7 @@ module CMDx
       #
       # @example Validating exact length
       #   Validators::Length.call("test", length: { is: 4 })
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Validating with custom message
       #   Validators::Length.call("", length: { min: 1, message: "cannot be empty" })