cmdx 1.1.0 → 1.1.1

data/lib/cmdx/logger.rb

@@ -1,33 +1,38 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Logger configuration and retrieval utilities for task execution.
+  # Logger management module for configuring and retrieving task-specific loggers.
   #
-  # This module provides functionality to configure and retrieve logger instances
-  # for task execution, applying task-specific settings such as formatter, level,
-  # and program name when available.
+  # This module provides functionality to extract and configure logger instances
+  # from task settings, applying formatter, level, and progname configurations
+  # when available. It serves as a central point for logger setup during task execution.
   module Logger
 
     module_function
 
     # Configures and returns a logger instance for the given task.
     #
-    # This method retrieves the logger from task settings and applies any
-    # available configuration options including formatter, level, and program name.
-    # The task itself is set as the logger's program name for identification.
+    # Extracts the logger from task settings and applies additional configuration
+    # such as formatter, log level, and progname if they are specified in the
+    # task's command settings. The progname is set to the task instance itself
+    # for better log traceability.
     #
-    # @param task [Task] the task instance to configure logging for
+    # @param task [Task] the task instance containing logger configuration settings
     #
-    # @return [Logger, nil] the configured logger instance or nil if no logger is set
+    # @return [Logger, nil] the configured logger instance, or nil if no logger is set
     #
     # @example Configure logger for a task
-    #   logger = CMDx::Logger.call(task)
-    #   logger.info("Task started")
+    #   class MyTask < CMDx::Task
+    #     cmd setting!(
+    #       logger: Logger.new($stdout),
+    #       log_level: Logger::DEBUG,
+    #       log_formatter: CMDx::LogFormatters::JSON.new
+    #     )
+    #   end
     #
-    # @example Logger with custom formatter
-    #   task.set_cmd_setting(:log_formatter, custom_formatter)
+    #   task = MyTask.call
     #   logger = CMDx::Logger.call(task)
-    #   logger.debug("Debug message")
+    #   #=> Returns configured logger with DEBUG level and JSON formatter
     def call(task)
       logger = task.cmd_setting(:logger)
 

data/lib/cmdx/logger_ansi.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 module CMDx
-  # ANSI color formatting utilities for log severity levels.
+  # ANSI color formatting for logger severity levels and text output.
   #
-  # This module provides functionality to apply ANSI color codes to log messages
-  # based on their severity level. It maps standard log severity indicators to
-  # appropriate colors for enhanced readability in terminal output.
+  # LoggerAnsi provides utility methods for applying ANSI color codes to logger
+  # severity indicators and general text formatting. It maps standard logger
+  # severity levels to appropriate colors for enhanced readability in terminal output,
+  # delegating actual color application to the AnsiColor utility module.
   module LoggerAnsi
 
     SEVERITY_COLORS = {
@@ -18,32 +19,47 @@ module CMDx
 
     module_function
 
-    # Applies ANSI color formatting to a log message based on its severity level.
+    # Applies ANSI color formatting to text based on severity level indication.
     #
-    # @param s [String] the log message string to format
+    # This method extracts the color for the given text based on its first character
+    # (typically a severity indicator) and applies both the determined color and bold
+    # formatting using the AnsiColor utility. The method provides consistent color
+    # formatting for logger output across the CMDx framework.
     #
-    # @return [String] the formatted message with ANSI color codes applied
+    # @param s [String] the text to format, typically starting with a severity indicator
     #
-    # @example Format a debug message
-    #   CMDx::LoggerAnsi.call("DEBUG: Starting process") #=> "\e[1;34;49mDEBUG: Starting process\e[0m"
+    # @return [String] the formatted text with ANSI color and bold styling applied
     #
-    # @example Format an error message
-    #   CMDx::LoggerAnsi.call("ERROR: Connection failed") #=> "\e[1;31;49mERROR: Connection failed\e[0m"
+    # @example Format debug severity text
+    #   LoggerAnsi.call("DEBUG: Starting process") #=> "\e[1;34;49mDEBUG: Starting process\e[0m"
+    #
+    # @example Format error severity text
+    #   LoggerAnsi.call("ERROR: Operation failed") #=> "\e[1;31;49mERROR: Operation failed\e[0m"
+    #
+    # @example Format text with unknown severity
+    #   LoggerAnsi.call("CUSTOM: Message") #=> "\e[1;39;49mCUSTOM: Message\e[0m"
     def call(s)
       Utils::AnsiColor.call(s, color: color(s), mode: :bold)
     end
 
-    # Determines the appropriate color for a log message based on its severity level.
+    # Determines the appropriate color for text based on its severity indicator.
+    #
+    # This method extracts the first character from the provided text and maps it
+    # to a corresponding color defined in SEVERITY_COLORS. If no matching severity
+    # is found, it returns the default color to ensure consistent formatting behavior.
+    #
+    # @param s [String] the text to analyze, typically starting with a severity indicator
     #
-    # @param s [String] the log message string to analyze
+    # @return [Symbol] the color symbol corresponding to the severity level, or :default if not found
     #
-    # @return [Symbol] the color symbol corresponding to the severity level
+    # @example Get color for debug severity
+    #   LoggerAnsi.color("DEBUG: Message") #=> :blue
     #
-    # @example Get color for debug message
-    #   CMDx::LoggerAnsi.color("DEBUG: message") #=> :blue
+    # @example Get color for error severity
+    #   LoggerAnsi.color("ERROR: Failed") #=> :red
     #
     # @example Get color for unknown severity
-    #   CMDx::LoggerAnsi.color("UNKNOWN: message") #=> :default
+    #   LoggerAnsi.color("UNKNOWN: Text") #=> :default
     def color(s)
       SEVERITY_COLORS[s[0]] || :default
     end

data/lib/cmdx/logger_serializer.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Serializes log messages for structured logging output.
+  # Logger serialization module for converting messages and task data into structured log format.
   #
-  # This module provides functionality to convert log messages into a structured
-  # hash format suitable for various logging formatters. It handles special
-  # processing for Result objects, including optional ANSI colorization of
-  # specific keys and merging of task serialization data.
+  # LoggerSerializer provides functionality to serialize task execution messages into a
+  # standardized hash representation suitable for logging systems. It handles both result
+  # objects and arbitrary messages, applying consistent formatting with optional ANSI
+  # colorization for terminal output. The serializer intelligently processes different
+  # message types and enriches log data with task metadata and origin information.
   module LoggerSerializer
 
     COLORED_KEYS = %i[
@@ -15,30 +16,90 @@ module CMDx
 
     module_function
 
-    # Converts a log message into a structured hash format.
+    # Serializes a log message with task context into structured hash format.
     #
-    # Processes the message based on its type - if it's a Result object,
-    # optionally colorizes specific keys. For non-Result messages, merges
-    # task serialization data and the original message.
+    # Converts log messages into a standardized hash representation suitable for
+    # various logging systems and output formats. When the message is a Result object,
+    # it extracts the result's hash representation and optionally applies ANSI colors
+    # to specific keys for enhanced terminal visibility. For non-result messages,
+    # it enriches the log entry with task metadata from TaskSerializer. All log
+    # entries are tagged with CMDx origin for source identification.
     #
-    # @param _severity [String] The log severity level (unused but kept for compatibility)
-    # @param _time [Time] The log timestamp (unused but kept for compatibility)
-    # @param task [CMDx::Task] The task instance associated with the log message
-    # @param message [Object] The message to be serialized (can be a Result or any object)
-    # @param options [Hash] Additional options for serialization
-    # @option options [Boolean] :ansi_colorize Whether to apply ANSI colorization to Result objects
+    # @param severity [Symbol] the log severity level (not used in current implementation)
+    # @param time [Time] the timestamp of the log entry (not used in current implementation)
+    # @param task [CMDx::Task, CMDx::Workflow] the task or workflow instance providing context
+    # @param message [CMDx::Result, Object] the primary message content to serialize
+    # @param options [Hash] additional options for serialization behavior
+    # @option options [Boolean] :ansi_colorize whether to apply ANSI colors to result keys
     #
-    # @return [Hash] A structured hash representation of the log message with origin set to "CMDx"
+    # @return [Hash] a structured hash containing the serialized log message and metadata
+    # @option return [String] :origin always set to "CMDx" for source identification
+    # @option return [Integer] :index the task's position index in the execution chain (when message is not Result)
+    # @option return [String] :chain_id the unique identifier of the task's execution chain (when message is not Result)
+    # @option return [String] :type the task type, either "Task" or "Workflow" (when message is not Result)
+    # @option return [String] :class the full class name of the task (when message is not Result)
+    # @option return [String] :id the unique identifier of the task instance (when message is not Result)
+    # @option return [Array] :tags the tags associated with the task from cmd settings (when message is not Result)
+    # @option return [Object] :message the original message content (when message is not Result)
+    # @option return [Symbol] :state the execution state with optional ANSI colors (when message is Result)
+    # @option return [Symbol] :status the execution status with optional ANSI colors (when message is Result)
+    # @option return [Symbol] :outcome the execution outcome with optional ANSI colors (when message is Result)
+    # @option return [Hash] :metadata additional metadata from result (when message is Result)
+    # @option return [Float] :runtime execution runtime in seconds (when message is Result)
     #
-    # @example Serializing a Result object with colorization
-    #   result = CMDx::Result.new(task)
-    #   LoggerSerializer.call("info", Time.now, task, result, ansi_colorize: true)
-    #   # => { state: "\e[32msuccess\e[0m", status: "complete", origin: "CMDx", ... }
+    # @raise [NoMethodError] if task doesn't respond to required methods for TaskSerializer
+    # @raise [NoMethodError] if result message doesn't respond to to_h method
     #
-    # @example Serializing a plain message
-    #   LoggerSerializer.call("info", Time.now, task, "Processing user data")
-    #   # => { index: 1, chain_id: "abc123", type: "Task", message: "Processing user data", origin: "CMDx", ... }
-    def call(_severity, _time, task, message, **options)
+    # @example Serialize a result message with ANSI colors
+    #   task = ProcessDataTask.call(data: "test")
+    #   LoggerSerializer.call(:info, Time.now, task, task.result, ansi_colorize: true)
+    #   #=> {
+    #   #   origin: "CMDx",
+    #   #   index: 0,
+    #   #   chain_id: "abc123",
+    #   #   type: "Task",
+    #   #   class: "ProcessDataTask",
+    #   #   id: "def456",
+    #   #   tags: [],
+    #   #   state: "\e[0;32;49mcomplete\e[0m",
+    #   #   status: "\e[0;32;49msuccess\e[0m",
+    #   #   outcome: "\e[0;32;49mgood\e[0m",
+    #   #   metadata: {},
+    #   #   runtime: 0.045
+    #   # }
+    #
+    # @example Serialize a string message with task context
+    #   task = MyTask.new(context: {data: "test"})
+    #   LoggerSerializer.call(:warn, Time.now, task, "Processing started")
+    #   #=> {
+    #   #   origin: "CMDx",
+    #   #   index: 0,
+    #   #   chain_id: "abc123",
+    #   #   type: "Task",
+    #   #   class: "MyTask",
+    #   #   id: "def456",
+    #   #   tags: [],
+    #   #   message: "Processing started"
+    #   # }
+    #
+    # @example Serialize a result message without colors
+    #   task = ValidationTask.call(email: "invalid")
+    #   LoggerSerializer.call(:error, Time.now, task, task.result)
+    #   #=> {
+    #   #   origin: "CMDx",
+    #   #   index: 1,
+    #   #   chain_id: "xyz789",
+    #   #   type: "Task",
+    #   #   class: "ValidationTask",
+    #   #   id: "ghi012",
+    #   #   tags: [],
+    #   #   state: :interrupted,
+    #   #   status: :failed,
+    #   #   outcome: :bad,
+    #   #   metadata: { reason: "Invalid email format" },
+    #   #   runtime: 0.012
+    #   # }
+    def call(severity, time, task, message, **options) # rubocop:disable Lint/UnusedMethodArgument
       m = message.is_a?(Result) ? message.to_h : {}
 
       if options.delete(:ansi_colorize) && message.is_a?(Result)

data/lib/cmdx/middleware.rb

@@ -1,48 +1,66 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Base class for implementing middleware functionality in task execution.
+  # Base class for implementing middleware functionality in task processing pipelines.
   #
-  # Middleware provides a way to wrap task execution with custom behavior
-  # such as logging, timing, authentication, or other cross-cutting concerns.
-  # All middleware implementations must inherit from this class and implement
-  # the abstract call method.
+  # Middleware provides a way to wrap task execution with custom logic that runs before
+  # and after task processing. Middleware can be used for cross-cutting concerns such as
+  # logging, authentication, caching, error handling, and other aspects that should be
+  # applied consistently across multiple tasks. All middleware implementations must
+  # inherit from this class and implement the abstract call method.
   class Middleware
 
     # Executes middleware by creating a new instance and calling it.
     #
-    # @param task [Task] the task instance being wrapped by the middleware
-    # @param callable [Proc] the callable object to execute within the middleware
+    # This class method provides a convenient way to execute middleware without
+    # manually instantiating the middleware class. It creates a new instance
+    # and delegates to the instance call method with the provided arguments.
     #
-    # @return [Object] the result of the middleware execution
+    # @param task [CMDx::Task] the task instance being processed
+    # @param callable [Proc] the callable that executes the next middleware or task logic
+    #
+    # @return [Object] the result returned by the middleware implementation
     #
     # @raise [UndefinedCallError] when the middleware subclass doesn't implement call
     #
     # @example Execute middleware on a task
-    #   MyMiddleware.call(task, -> { task.process })
+    #   class LoggingMiddleware < CMDx::Middleware
+    #     def call(task, callable)
+    #       task.logger.info "Starting #{task.class.name}"
+    #       result = callable.call
+    #       task.logger.info "Completed #{task.class.name}"
+    #       result
+    #     end
+    #   end
+    #
+    #   LoggingMiddleware.call(my_task, -> { my_task.process })
     def self.call(task, callable)
       new.call(task, callable)
     end
 
     # Abstract method that must be implemented by middleware subclasses.
     #
-    # This method contains the actual middleware logic to be executed.
-    # Subclasses must override this method to provide their specific
-    # middleware implementation that wraps the callable execution.
+    # This method contains the actual middleware logic that wraps task execution.
+    # Subclasses must override this method to provide their specific middleware
+    # implementation. The method should call the provided callable to continue
+    # the middleware chain or execute the task logic.
     #
-    # @param _task [Task] the task instance being wrapped by the middleware
-    # @param _callable [Proc] the callable object to execute within the middleware
+    # @param _task [CMDx::Task] the task instance being processed
+    # @param _callable [Proc] the callable that executes the next middleware or task logic
     #
-    # @return [Object] the result of the middleware execution
+    # @return [Object] the result of the middleware processing
     #
     # @raise [UndefinedCallError] always raised in the base class
     #
-    # @example Implement in a subclass
-    #   def call(task, callable)
-    #     puts "Before #{task.class.name} execution"
-    #     result = callable.call
-    #     puts "After #{task.class.name} execution"
-    #     result
+    # @example Implement middleware in a subclass
+    #   class TimingMiddleware < CMDx::Middleware
+    #     def call(task, callable)
+    #       start_time = Time.now
+    #       result = callable.call
+    #       duration = Time.now - start_time
+    #       task.logger.info "Task completed in #{duration}s"
+    #       result
+    #     end
     #   end
     def call(_task, _callable)
       raise UndefinedCallError, "call method not defined in #{self.class.name}"

data/lib/cmdx/middleware_registry.rb

@@ -8,8 +8,6 @@ module CMDx
   # authentication, and error handling.
   class MiddlewareRegistry
 
-    # The internal hash storing middleware definitions and their configurations.
-    #
     # @return [Hash] hash containing middleware classes/objects and their configurations
     attr_reader :registry
 
@@ -75,10 +73,13 @@ module CMDx
     # Returns a hash representation of the registry.
     #
     # @return [Hash] deep copy of registry with duplicated configuration arrays
+    # @option return [Array] args duplicated positional arguments array
+    # @option return [Hash] kwargs duplicated keyword arguments hash
+    # @option return [Proc, nil] block the original block reference (not duplicated)
     #
     # @example Getting registry hash
     #   registry.to_h
-    #   # => { TimeoutMiddleware => [[30], {}, nil] }
+    #   #=> { TimeoutMiddleware => [[30], {}, nil] }
     def to_h
       registry.transform_values do |config|
         args, kwargs, block = config