cmdx 1.0.1 → 1.1.0

data/lib/cmdx/task_deprecator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Handles deprecation checking for CMDx tasks.
+  #
+  # This module provides functionality to check if a task is marked as deprecated
+  # and raise appropriate errors when deprecated tasks are instantiated. It integrates
+  # with the task lifecycle to prevent usage of deprecated functionality.
+  module TaskDeprecator
+
+    module_function
+
+    # Checks deprecation status of a task and handles it according to the configured behavior.
+    #
+    # This method examines the task's deprecation setting and takes appropriate action:
+    # - :raise - raises DeprecationError to prevent task execution
+    # - :warn - issues Ruby deprecation warning
+    # - :log or true - logs deprecation warning
+    # - nil or false - allows task execution without warnings
+    #
+    # @param task [Task] the task instance to check for deprecation
+    #
+    # @return [void]
+    #
+    # @raise [DeprecationError] when task is marked with deprecated: :raise
+    #
+    # @example Task with raise deprecation setting
+    #   class MyTask < CMDx::Task
+    #     cmd_settings! deprecated: :raise
+    #   end
+    #   CMDx::TaskDeprecator.call(MyTask.new) # raises DeprecationError
+    #
+    # @example Task with a proc deprecation setting
+    #   class MyTask < CMDx::Task
+    #     cmd_settings! deprecated: -> { Time.now.year > 2025 ? :raise : :log }
+    #   end
+    #   CMDx::TaskDeprecator.call(MyTask.new) # issues warnings
+    #
+    # @example Task with no deprecation setting
+    #   class MyTask < CMDx::Task
+    #   end
+    #   CMDx::TaskDeprecator.call(MyTask.new) # no action taken
+    def call(task)
+      case task.cmd_setting(:deprecated)
+      when :raise
+        raise(DeprecationError, "#{task.class.name} usage prohibited")
+      when :log, true
+        task.logger.warn { "DEPRECATED: migrate to replacement or discontinue use" }
+      when :warn
+        warn("[#{task.class.name}] DEPRECATED: migrate to replacement or discontinue use", category: :deprecated)
+      end
+    end
+
+  end
+end

data/lib/cmdx/task_processor.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Handles the execution orchestration of Task instances with middleware and callback support.
+  #
+  # 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.
+  class TaskProcessor
+
+    # @return [CMDx::Task] The task instance being executed
+    attr_reader :task
+
+    # Creates a new TaskProcessor instance for the specified task.
+    #
+    # @param task [CMDx::Task] the task instance to execute
+    #
+    # @return [TaskProcessor] a new TaskProcessor instance
+    #
+    # @example Create 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.
+      #
+      # 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.
+      #
+      # @param task [CMDx::Task] the task instance to execute
+      #
+      # @return [Result] the task's result object after execution
+      #
+      # @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
+      #   result = TaskProcessor.call(task)
+      #   result.failed? # => true
+      def call(task)
+        new(task).call
+      end
+
+      # Executes a task with bang semantics, re-raising exceptions.
+      #
+      # 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.
+      #
+      # @param task [CMDx::Task] the task instance to execute
+      #
+      # @return [Result] the task's result object after execution
+      #
+      # @raise [UndefinedCallError] if the task doesn't implement a call method
+      # @raise [Fault] if a fault occurs 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
+      #   begin
+      #     TaskProcessor.call!(task)
+      #   rescue CMDx::Fault => e
+      #     puts "Task failed: #{e.result.status}"
+      #   end
+      def call!(task)
+        new(task).call!
+      end
+
+    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.
+    #
+    # @return [Result] the task's result object after execution
+    #
+    # @raise [UndefinedCallError] if the task doesn't implement a call method
+    #
+    # @example Execute a task safely
+    #   task = MyTask.new(name: "test")
+    #   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
+    def call
+      task.result.runtime do
+        before_call
+        validate_parameters
+        task.call
+      rescue UndefinedCallError => e
+        raise(e)
+      rescue Fault => e
+        if Array(task.cmd_setting(:task_halt)).include?(e.result.status)
+          # No need to clear the Chain since exception is not being re-raised
+          task.result.throw!(e.result, original_exception: e)
+        end
+      rescue StandardError => e
+        task.result.fail!(reason: "[#{e.class}] #{e.message}", original_exception: e)
+      ensure
+        task.result.executed!
+        after_call
+      end
+
+      terminate_call
+    end
+
+    # Executes the task with bang semantics, re-raising exceptions.
+    #
+    # 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.
+    #
+    # @return [Result] the task's result object after execution
+    #
+    # @raise [UndefinedCallError] if the task doesn't implement a call method
+    # @raise [Fault] if a fault occurs 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
+    #   begin
+    #     processor.call!
+    #   rescue CMDx::Fault => e
+    #     puts "Task failed: #{e.result.status}"
+    #   end
+    def call!
+      task.result.runtime do
+        before_call
+        validate_parameters
+        task.call
+      rescue UndefinedCallError => e
+        raise!(e)
+      rescue Fault => e
+        task.result.executed!
+
+        raise!(e) if Array(task.cmd_setting(:task_halt)).include?(e.result.status)
+
+        after_call # HACK: treat as NO-OP
+      else
+        task.result.executed!
+        after_call # ELSE: treat as success
+      end
+
+      terminate_call
+    end
+
+    private
+
+    # Executes pre-execution callbacks and parameter validation.
+    #
+    # @return [void]
+    def before_call
+      task.cmd_callbacks.call(task, :before_execution)
+
+      task.result.executing!
+      task.cmd_callbacks.call(task, :on_executing)
+    end
+
+    # Validates task parameters and handles validation errors.
+    #
+    # 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.
+    #
+    # @return [void]
+    #
+    # @raise [Exception] Validations, coercions, or exceptions
+    def validate_parameters
+      task.cmd_callbacks.call(task, :before_validation)
+
+      task.cmd_parameters.validate!(task)
+      unless task.errors.empty?
+        task.result.fail!(
+          reason: task.errors.full_messages.join(". "),
+          messages: task.errors.messages
+        )
+      end
+
+      task.cmd_callbacks.call(task, :after_validation)
+    end
+
+    # Clears the execution chain and re-raises the given exception.
+    #
+    # @param exception [Exception] the exception to re-raise after chain cleanup
+    #
+    # @return [void] this method never returns as it always raises
+    #
+    # @raise [Exception] always re-raises the provided exception
+    def raise!(exception)
+      Chain.clear
+      raise(exception)
+    end
+
+    # Executes post-execution callbacks based on result state and status.
+    #
+    # @return [void]
+    def after_call
+      task.cmd_callbacks.call(task, :"on_#{task.result.state}")
+      task.cmd_callbacks.call(task, :on_executed) if task.result.executed?
+
+      task.cmd_callbacks.call(task, :"on_#{task.result.status}")
+      task.cmd_callbacks.call(task, :on_good) if task.result.good?
+      task.cmd_callbacks.call(task, :on_bad) if task.result.bad?
+
+      task.cmd_callbacks.call(task, :after_execution)
+    end
+
+    # Finalizes task execution with immutability and logging.
+    #
+    # @return [Result] the task's result object
+    def terminate_call
+      Immutator.call(task)
+      ResultLogger.call(task.result)
+    end
+
+  end
+end

data/lib/cmdx/task_serializer.rb

@@ -1,82 +1,34 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # TaskSerializer converts task instances into hash representations for
-  # logging, debugging, and serialization purposes. It extracts key metadata
-  # about the task execution context and identification.
-  #
-  # The serialized format includes:
-  # - Execution index within the chain
-  # - Chain identifier for grouping related tasks
-  # - Task type (Task vs Workflow)
-  # - Class name for identification
-  # - Unique task instance ID
-  # - Associated tags for categorization
-  #
-  # @example Basic serialization
-  #   class ProcessOrderTask < CMDx::Task
-  #     task_settings!(tags: [:order, :payment])
-  #   end
-  #
-  #   task = ProcessOrderTask.call(order_id: 123)
-  #   TaskSerializer.call(task)
-  #   #=> {
-  #   #     index: 1,
-  #   #     chain_id: "abc123...",
-  #   #     type: "Task",
-  #   #     class: "ProcessOrderTask",
-  #   #     id: "def456...",
-  #   #     tags: [:order, :payment]
-  #   #   }
-  #
-  # @example Workflow serialization
-  #   class OrderProcessingWorkflow < CMDx::Workflow
-  #     task_settings!(tags: [:workflow, :orders])
-  #   end
-  #
-  #   workflow = OrderProcessingWorkflow.call(orders: [...])
-  #   TaskSerializer.call(workflow)
-  #   #=> {
-  #   #     index: 1,
-  #   #     chain_id: "abc123...",
-  #   #     type: "Workflow",
-  #   #     class: "OrderProcessingWorkflow",
-  #   #     id: "ghi789...",
-  #   #     tags: [:workflow, :orders]
-  #   #   }
-  #
-  # @see Task Task class for execution context
-  # @see Workflow Workflow class for multi-task execution
-  # @see Chain Chain class for execution grouping
-  # @since 1.0.0
+  # 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.
   module TaskSerializer
 
     module_function
 
-    ##
-    # Serializes a task instance into a hash representation containing
-    # essential metadata for identification and tracking.
+    # 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.
     #
-    # @param task [Task, Workflow] the task instance to serialize
-    # @return [Hash] serialized task data with the following keys:
-    #   - :index [Integer] position within the execution chain
-    #   - :chain_id [String] identifier of the containing chain
-    #   - :type [String] "Task" or "Workflow" based on instance type
-    #   - :class [String] class name of the task
-    #   - :id [String] unique identifier for this task instance
-    #   - :tags [Array] array of tags associated with the task
+    # @param task [Task] the task instance to serialize
     #
-    # @example Serializing a task
-    #   task = MyTask.call(param: "value")
-    #   data = TaskSerializer.call(task)
-    #   data[:class] #=> "MyTask"
-    #   data[:type] #=> "Task"
-    #   data[:id] #=> "550e8400-e29b-41d4-a716-446655440000"
+    # @return [Hash] hash containing task metadata and execution details
+    #
+    # @raise [NoMethodError] if task doesn't respond to required methods
     #
-    # @example Using serialized data for logging
-    #   task_data = TaskSerializer.call(task)
-    #   logger.info("Task executed", task_data)
+    # @example Serializing a task
+    #   task = UserRegistrationTask.call(email: "user@example.com")
+    #   TaskSerializer.call(task)
+    #   # => {
+    #   #   index: 0,
+    #   #   chain_id: "abc123",
+    #   #   type: "Task",
+    #   #   class: "UserRegistrationTask",
+    #   #   id: "def456",
+    #   #   tags: [:authentication, :user_management]
+    #   # }
     def call(task)
       {
         index: task.result.index,
@@ -84,7 +36,7 @@ module CMDx
         type: task.is_a?(Workflow) ? "Workflow" : "Task",
         class: task.class.name,
         id: task.id,
-        tags: task.task_setting(:tags)
+        tags: task.cmd_setting(:tags)
       }
     end
 

data/lib/cmdx/utils/ansi_color.rb

@@ -2,59 +2,12 @@
 
 module CMDx
   module Utils
-    # Utility for adding ANSI color codes to terminal output.
+    # Utility module for applying ANSI color and formatting codes to text.
     #
-    # AnsiColor provides methods to colorize text output in terminal
-    # environments, supporting various colors and text modes for
-    # enhanced readability of logs and console output. Used extensively
-    # by CMDx's pretty formatters to provide visual distinction between
-    # different log levels, statuses, and metadata.
-    #
-    # @example Basic color usage
-    #   Utils::AnsiColor.call("Error", color: :red)
-    #   # => "\e[0;31;49mError\e[0m"
-    #
-    # @example Color with text modes
-    #   Utils::AnsiColor.call("Warning", color: :yellow, mode: :bold)
-    #   Utils::AnsiColor.call("Info", color: :blue, mode: :underline)
-    #
-    # @example Log severity coloring
-    #   Utils::AnsiColor.call("ERROR", color: :red, mode: :bold)
-    #   Utils::AnsiColor.call("WARN", color: :yellow)
-    #   Utils::AnsiColor.call("INFO", color: :blue)
-    #   Utils::AnsiColor.call("DEBUG", color: :light_black)
-    #
-    # @example Status indicator coloring
-    #   Utils::AnsiColor.call("success", color: :green, mode: :bold)
-    #   Utils::AnsiColor.call("failed", color: :red, mode: :bold)
-    #   Utils::AnsiColor.call("skipped", color: :yellow)
-    #
-    # @example Available colors
-    #   Utils::AnsiColor.call("Text", color: :red)
-    #   Utils::AnsiColor.call("Text", color: :green)
-    #   Utils::AnsiColor.call("Text", color: :blue)
-    #   Utils::AnsiColor.call("Text", color: :light_cyan)
-    #   Utils::AnsiColor.call("Text", color: :magenta)
-    #
-    # @example Available text modes
-    #   Utils::AnsiColor.call("Bold", color: :white, mode: :bold)
-    #   Utils::AnsiColor.call("Italic", color: :white, mode: :italic)
-    #   Utils::AnsiColor.call("Underline", color: :white, mode: :underline)
-    #   Utils::AnsiColor.call("Strikethrough", color: :white, mode: :strike)
-    #
-    # @see CMDx::ResultAnsi Uses this for result status coloring
-    # @see CMDx::LoggerAnsi Uses this for log severity coloring
-    # @see CMDx::LogFormatters::PrettyLine Uses this for colorized log output
-    # @see CMDx::LogFormatters::PrettyKeyValue Uses this for colorized key-value pairs
+    # This module provides functionality to colorize and format text output
+    # using ANSI escape sequences, supporting various colors and text modes.
     module AnsiColor
 
-      # Available color codes for text coloring.
-      #
-      # Maps color names to their corresponding ANSI escape code numbers.
-      # Includes both standard and light variants of common colors for
-      # flexible visual styling in terminal environments.
-      #
-      # @return [Hash<Symbol, Integer>] mapping of color names to ANSI codes
       COLOR_CODES = {
         black: 30,
         red: 31,
@@ -74,14 +27,6 @@ module CMDx
         light_cyan: 96,
         light_white: 97
       }.freeze
-
-      # Available text mode codes for formatting.
-      #
-      # Maps text formatting mode names to their corresponding ANSI escape
-      # code numbers. Provides various text styling options including bold,
-      # italic, underline, and other visual effects.
-      #
-      # @return [Hash<Symbol, Integer>] mapping of mode names to ANSI codes
       MODE_CODES = {
         default: 0,
         bold: 1,
@@ -101,42 +46,21 @@ module CMDx
 
       module_function
 
-      # Apply ANSI color and mode formatting to text.
-      #
-      # Wraps the provided text with ANSI escape codes to apply the specified
-      # color and formatting mode. The resulting string will display with the
-      # requested styling in ANSI-compatible terminals and will gracefully
-      # degrade in non-ANSI environments.
-      #
-      # @param value [String] text to colorize
-      # @param color [Symbol] color name from COLOR_CODES
-      # @param mode [Symbol] text mode from MODE_CODES (defaults to :default)
-      # @return [String] text wrapped with ANSI escape codes
-      # @raise [KeyError] if color or mode is not found in the respective code maps
-      #
-      # @example Success message with green bold text
-      #   AnsiColor.call("Success", color: :green, mode: :bold)
-      #   # => "\e[1;32;49mSuccess\e[0m"
+      # Applies ANSI color and formatting to the given text value.
       #
-      # @example Error message with red text
-      #   AnsiColor.call("Error", color: :red)
-      #   # => "\e[0;31;49mError\e[0m"
+      # @param value [String] the text to format with ANSI codes
+      # @param color [Symbol] the color to apply (must be a key in COLOR_CODES)
+      # @param mode [Symbol] the formatting mode to apply (must be a key in MODE_CODES)
       #
-      # @example Warning with yellow underlined text
-      #   AnsiColor.call("Warning", color: :yellow, mode: :underline)
-      #   # => "\e[4;33;49mWarning\e[0m"
+      # @return [String] the formatted text with ANSI escape sequences
       #
-      # @example Debug info with dimmed light text
-      #   AnsiColor.call("Debug info", color: :light_black, mode: :dim)
-      #   # => "\e[2;90;49mDebug info\e[0m"
+      # @raise [KeyError] if the specified color or mode is not found in the respective code maps
       #
-      # @example Invalid color raises KeyError
-      #   AnsiColor.call("Text", color: :invalid_color)
-      #   # => KeyError: key not found: :invalid_color
+      # @example Basic color application
+      #   AnsiColor.call("Hello", color: :red) #=> "\e[0;31;49mHello\e[0m"
       #
-      # @note The escape sequence format is: \e[{mode};{color};49m{text}\e[0m
-      # @note The "49" represents the default background color
-      # @note The final "\e[0m" resets all formatting to default
+      # @example Color with formatting mode
+      #   AnsiColor.call("Warning", color: :yellow, mode: :bold) #=> "\e[1;33;49mWarning\e[0m"
       def call(value, color:, mode: :default)
         color_code = COLOR_CODES.fetch(color)
         mode_code  = MODE_CODES.fetch(mode)

data/lib/cmdx/utils/log_timestamp.rb

@@ -2,60 +2,31 @@
 
 module CMDx
   module Utils
-    # Utility for formatting timestamps in CMDx log entries.
+    # Utility module for formatting timestamps into standardized string representations.
     #
-    # LogTimestamp provides consistent timestamp formatting across all CMDx
-    # log formatters, ensuring uniform time representation in logs regardless
-    # of the chosen output format. Uses ISO 8601 format with microsecond precision.
-    #
-    # @example Basic timestamp formatting
-    #   Utils::LogTimestamp.call(Time.now)
-    #   # => "2022-07-17T18:43:15.123456"
-    #
-    # @example Usage in log formatters
-    #   timestamp = Utils::LogTimestamp.call(time.utc)
-    #   log_entry = "#{severity} [#{timestamp}] #{message}"
-    #
-    # @example Consistent formatting across formatters
-    #   # JSON formatter
-    #   { "timestamp": Utils::LogTimestamp.call(time.utc) }
-    #
-    #   # Line formatter
-    #   "[#{Utils::LogTimestamp.call(time.utc)} ##{Process.pid}]"
-    #
-    # @see CMDx::LogFormatters::Json Uses this for JSON timestamp field
-    # @see CMDx::LogFormatters::Line Uses this for traditional log format
-    # @see CMDx::LogFormatters::Logstash Uses this for @timestamp field
+    # This module provides functionality to convert Time objects into consistent
+    # ISO 8601-like formatted strings with microsecond precision, suitable for
+    # logging and timestamp display purposes.
     module LogTimestamp
 
-      # ISO 8601 datetime format with microsecond precision
-      # @return [String] strftime format string for consistent timestamp formatting
       DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%6N"
 
       module_function
 
-      # Formats a Time object as an ISO 8601 timestamp string.
+      # Formats a Time object into a standardized timestamp string.
       #
-      # Converts the given time to a standardized string representation
-      # using ISO 8601 format with microsecond precision. This ensures
-      # consistent timestamp formatting across all CMDx log outputs.
+      # @param time [Time] the time object to format
       #
-      # @param time [Time] Time object to format
-      # @return [String] ISO 8601 formatted timestamp with microseconds
+      # @return [String] the formatted timestamp string in ISO 8601-like format
       #
-      # @example Current time formatting
-      #   LogTimestamp.call(Time.now)
-      #   # => "2022-07-17T18:43:15.123456"
+      # @raise [NoMethodError] if the time object doesn't respond to strftime
       #
-      # @example UTC time formatting for logs
-      #   LogTimestamp.call(Time.now.utc)
-      #   # => "2022-07-17T18:43:15.123456"
+      # @example Basic timestamp formatting
+      #   LogTimestamp.call(Time.now) #=> "2023-12-25T10:30:45.123456"
       #
-      # @example Integration with log formatters
-      #   def format_log_entry(severity, time, message)
-      #     timestamp = LogTimestamp.call(time.utc)
-      #     "#{severity} [#{timestamp}] #{message}"
-      #   end
+      # @example With specific time
+      #   time = Time.new(2023, 12, 25, 10, 30, 45, 123456)
+      #   LogTimestamp.call(time) #=> "2023-12-25T10:30:45.123456"
       def call(time)
         time.strftime(DATETIME_FORMAT)
       end