cmdx 1.0.1 → 1.1.1

data/lib/cmdx/task_deprecator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Task deprecation system for CMDx tasks.
+  #
+  # This module provides a centralized system for handling task deprecation
+  # warnings and errors. It supports multiple deprecation modes including
+  # raising exceptions, logging warnings, or issuing Ruby warnings based
+  # on task configuration settings.
+  module TaskDeprecator
+
+    module_function
+
+    # Processes task deprecation based on the task's deprecated setting.
+    #
+    # @param task [CMDx::Task] the task instance to check for deprecation
+    # @return [void]
+    # @raise [DeprecationError] when task's deprecated setting is :error
+    #
+    # @example Handle task with raise deprecation
+    #   class MyTask < CMDx::Task
+    #     cmd_setting!(deprecated: :error)
+    #   end
+    #   task = MyTask.new
+    #   TaskDeprecator.call(task) # raises DeprecationError
+    #
+    # @example Handle task with log deprecation
+    #   class MyTask < CMDx::Task
+    #     cmd_setting!(deprecated: :log)
+    #   end
+    #   task = MyTask.new
+    #   TaskDeprecator.call(task) # logs warning via task.logger
+    #
+    # @example Handle task with warn deprecation
+    #   class MyTask < CMDx::Task
+    #     cmd_setting!(deprecated: :warning)
+    #   end
+    #   task = MyTask.new
+    #   TaskDeprecator.call(task) # issues Ruby warning
+    def call(task)
+      case task.cmd_setting(:deprecated)
+      when :error
+        raise(DeprecationError, "#{task.class.name} usage prohibited")
+      when :log, true
+        task.logger.warn { "DEPRECATED: migrate to replacement or discontinue use" }
+      when :warning
+        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,246 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Core task execution processor handling the complete task lifecycle.
+  #
+  # 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 task processor for the specified task instance.
+    #
+    # @param task [CMDx::Task] the task instance to process
+    #
+    # @return [TaskProcessor] a new processor instance for the task
+    #
+    # @example Create a processor for a task
+    #   task = MyTask.new(user_id: 123)
+    #   processor = TaskProcessor.new(task)
+    def initialize(task)
+      @task = task
+    end
+
+    class << self
+
+      # Executes the specified task and returns the result without raising exceptions.
+      #
+      # 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 [CMDx::Result] the execution result containing state and status information
+      #
+      # @example Execute a task safely
+      #   task = ProcessDataTask.new(data: raw_data)
+      #   result = TaskProcessor.call(task)
+      #   puts result.status #=> "success", "failed", or "skipped"
+      def call(task)
+        new(task).call
+      end
+
+      # Executes the specified task and raises exceptions on failure.
+      #
+      # 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 [CMDx::Result] the execution result on success
+      #
+      # @raise [CMDx::Fault] when a fault occurs with status matching task halt configuration
+      # @raise [StandardError] when unexpected errors occur during execution
+      #
+      # @example Execute a task with exception raising
+      #   task = CriticalTask.new(operation: "delete")
+      #   begin
+      #     result = TaskProcessor.call!(task)
+      #     puts "Success: #{result.status}"
+      #   rescue CMDx::Fault => e
+      #     puts "Task failed: #{e.message}"
+      #   end
+      def call!(task)
+        new(task).call!
+      end
+
+    end
+
+    # Executes the task with safe error handling and returns the result.
+    #
+    # 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.
+    #
+    # @return [CMDx::Result] the execution result with captured state and status
+    #
+    # @example Safe task execution
+    #   processor = TaskProcessor.new(task)
+    #   result = processor.call
+    #   if result.success?
+    #     puts "Task completed successfully"
+    #   else
+    #     puts "Task failed: #{result.metadata[:reason]}"
+    #   end
+    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 exception raising on halt conditions.
+    #
+    # 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 [CMDx::Result] the execution result on successful completion
+    #
+    # @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 Task execution with exception raising
+    #   processor = TaskProcessor.new(critical_task)
+    #   begin
+    #     result = processor.call!
+    #     puts "Task succeeded"
+    #   rescue CMDx::Fault => e
+    #     puts "Critical failure: #{e.message}"
+    #     # Chain is cleared, execution stops
+    #   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 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
+      task.cmd_callbacks.call(task, :before_execution)
+
+      task.result.executing!
+      task.cmd_callbacks.call(task, :on_executing)
+    end
+
+    # Validates task parameters and handles validation failures.
+    #
+    # 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]
+    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 raises the specified exception.
+    #
+    # 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.
+    #
+    # @param exception [Exception] the exception to raise after clearing the chain
+    #
+    # @return [void]
+    #
+    # @raise [Exception] the provided exception after chain cleanup
+    def raise!(exception)
+      Chain.clear
+      raise(exception)
+    end
+
+    # 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
+      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 by freezing state and logging results.
+    #
+    # 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)
+    end
+
+  end
+end

data/lib/cmdx/task_serializer.rb

@@ -1,82 +1,47 @@
 # 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.
+  # Task serialization module for converting task objects to hash format.
   #
-  # 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
+  # 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
 
-    ##
-    # Serializes a task instance into a hash representation containing
-    # essential metadata for identification and tracking.
+    # Serializes a task object into a hash representation.
+    #
+    # 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.
+    #
+    # @param task [CMDx::Task, CMDx::Workflow] the task or workflow object to serialize
     #
-    # @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
+    # @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 = MyTask.call(param: "value")
-    #   data = TaskSerializer.call(task)
-    #   data[:class] #=> "MyTask"
-    #   data[:type] #=> "Task"
-    #   data[:id] #=> "550e8400-e29b-41d4-a716-446655440000"
+    # @raise [NoMethodError] if the 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 Serialize a basic task
+    #   task = ProcessDataTask.new
+    #   TaskSerializer.call(task)
+    #   #=> {
+    #   #   index: 0,
+    #   #   chain_id: "abc123",
+    #   #   type: "Task",
+    #   #   class: "ProcessDataTask",
+    #   #   id: "def456",
+    #   #   tags: []
+    #   # }
     def call(task)
       {
         index: task.result.index,
@@ -84,7 +49,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