cmdx 1.0.1 → 1.1.1

data/lib/cmdx/logger_ansi.rb

@@ -1,41 +1,14 @@
 # frozen_string_literal: true
 
 module CMDx
-  # ANSI color formatting module for logger severity levels.
+  # ANSI color formatting for logger severity levels and text output.
   #
-  # The LoggerAnsi module provides ANSI color formatting for log severity levels
-  # to enhance readability in terminal output. Each severity level is assigned
-  # a specific color and bold formatting to make log messages more visually
-  # distinguishable.
-  #
-  # @example Basic severity colorization
-  #   LoggerAnsi.call("DEBUG message")    # => Blue bold text
-  #   LoggerAnsi.call("INFO message")     # => Green bold text
-  #   LoggerAnsi.call("WARN message")     # => Yellow bold text
-  #   LoggerAnsi.call("ERROR message")    # => Red bold text
-  #   LoggerAnsi.call("FATAL message")    # => Magenta bold text
-  #
-  # @example Usage in log formatters
-  #   class CustomFormatter
-  #     def call(severity, time, progname, msg)
-  #       colored_severity = LoggerAnsi.call(severity)
-  #       "#{colored_severity} #{msg}"
-  #     end
-  #   end
-  #
-  # @example Integration with pretty formatters
-  #   # Used internally by PrettyLine, PrettyJson, PrettyKeyValue formatters
-  #   formatted_severity = LoggerAnsi.call("ERROR")  # => Red bold "ERROR"
-  #
-  # @see CMDx::Utils::AnsiColor ANSI color utility functions
-  # @see CMDx::LogFormatters::PrettyLine Pretty line formatter with colors
-  # @see CMDx::LogFormatters::PrettyJson Pretty JSON formatter with colors
+  # 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
 
-    # Mapping of log severity levels to ANSI colors.
-    #
-    # Maps the first character of severity levels to their corresponding
-    # color codes for consistent visual representation across log output.
     SEVERITY_COLORS = {
       "D" => :blue,      # DEBUG
       "I" => :green,     # INFO
@@ -46,61 +19,47 @@ module CMDx
 
     module_function
 
-    # Applies ANSI color formatting to a severity string.
+    # Applies ANSI color formatting to text based on severity level indication.
+    #
+    # 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.
     #
-    # Formats the input string with appropriate ANSI color codes based on
-    # the first character of the string, which typically represents the
-    # log severity level. All formatted text is rendered in bold.
+    # @param s [String] the text to format, typically starting with a severity indicator
     #
-    # @param s [String] The severity string to colorize
-    # @return [String] The string with ANSI color codes applied
+    # @return [String] the formatted text with ANSI color and bold styling applied
     #
-    # @example Colorizing different severity levels
-    #   LoggerAnsi.call("DEBUG")  # => "\e[1;34mDEBUG\e[0m" (blue bold)
-    #   LoggerAnsi.call("INFO")   # => "\e[1;32mINFO\e[0m" (green bold)
-    #   LoggerAnsi.call("WARN")   # => "\e[1;33mWARN\e[0m" (yellow bold)
-    #   LoggerAnsi.call("ERROR")  # => "\e[1;31mERROR\e[0m" (red bold)
-    #   LoggerAnsi.call("FATAL")  # => "\e[1;35mFATAL\e[0m" (magenta bold)
+    # @example Format debug severity text
+    #   LoggerAnsi.call("DEBUG: Starting process") #=> "\e[1;34;49mDEBUG: Starting process\e[0m"
     #
-    # @example Unknown severity level
-    #   LoggerAnsi.call("CUSTOM") # => "\e[1;39mCUSTOM\e[0m" (default color bold)
+    # @example Format error severity text
+    #   LoggerAnsi.call("ERROR: Operation failed") #=> "\e[1;31;49mERROR: Operation failed\e[0m"
     #
-    # @example Full log message formatting
-    #   severity = "ERROR"
-    #   message = "Task failed with validation errors"
-    #   colored_severity = LoggerAnsi.call(severity)
-    #   log_line = "#{colored_severity}: #{message}"
-    #   # => "\e[1;31mERROR\e[0m: Task failed with validation errors"
+    # @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 severity string.
+    # Determines the appropriate color for text based on its severity indicator.
     #
-    # Extracts the first character from the severity string and maps it to
-    # the corresponding color symbol using the SEVERITY_COLORS hash. If no
-    # mapping is found for the first character, returns the default color.
+    # 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 severity string to determine color for
-    # @return [Symbol] The color symbol for the severity level
+    # @param s [String] the text to analyze, typically starting with a severity indicator
     #
-    # @example Mapping severity levels to colors
-    #   color("DEBUG")    # => :blue
-    #   color("INFO")     # => :green
-    #   color("WARN")     # => :yellow
-    #   color("ERROR")    # => :red
-    #   color("FATAL")    # => :magenta
+    # @return [Symbol] the color symbol corresponding to the severity level, or :default if not found
     #
-    # @example Unknown severity level
-    #   color("CUSTOM")   # => :default
-    #   color("TRACE")    # => :default
+    # @example Get color for debug severity
+    #   LoggerAnsi.color("DEBUG: Message") #=> :blue
     #
-    # @example Case sensitivity
-    #   color("debug")    # => :default (lowercase 'd' not mapped)
-    #   color("Debug")    # => :blue (uppercase 'D' is mapped)
+    # @example Get color for error severity
+    #   LoggerAnsi.color("ERROR: Failed") #=> :red
     #
-    # @note This method only considers the first character of the input string
-    # @see SEVERITY_COLORS The mapping hash used for color determination
+    # @example Get color for unknown severity
+    #   LoggerAnsi.color("UNKNOWN: Text") #=> :default
     def color(s)
       SEVERITY_COLORS[s[0]] || :default
     end

data/lib/cmdx/logger_serializer.rb

@@ -1,140 +1,111 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Logger message serialization module for structured log output.
+  # Logger serialization module for converting messages and task data into structured log format.
   #
-  # The LoggerSerializer module provides functionality to serialize log messages
-  # into structured hash format suitable for various log formatters. It handles
-  # different message types including Result objects and plain messages, with
-  # optional ANSI colorization for terminal output.
-  #
-  # @example Basic message serialization
-  #   task = ProcessOrderTask.new
-  #   message = "Processing order 123"
-  #
-  #   LoggerSerializer.call(:info, Time.now, task, message)
-  #   # => {
-  #   #   origin: "CMDx",
-  #   #   index: 0,
-  #   #   chain_id: "...",
-  #   #   type: "Task",
-  #   #   class: "ProcessOrderTask",
-  #   #   id: "...",
-  #   #   tags: [],
-  #   #   message: "Processing order 123"
-  #   # }
-  #
-  # @example Result object serialization
-  #   result = task.result  # CMDx::Result instance
-  #
-  #   LoggerSerializer.call(:info, Time.now, task, result)
-  #   # => {
-  #   #   origin: "CMDx",
-  #   #   state: "complete",
-  #   #   status: "success",
-  #   #   outcome: "success",
-  #   #   metadata: {},
-  #   #   runtime: 0.5,
-  #   #   index: 0,
-  #   #   chain_id: "...",
-  #   #   # ... other result data
-  #   # }
-  #
-  # @example Colorized result serialization
-  #   LoggerSerializer.call(:info, Time.now, task, result, ansi_colorize: true)
-  #   # => Same as above but with ANSI color codes in state/status/outcome values
-  #
-  # @see CMDx::Result Result object structure and data
-  # @see CMDx::TaskSerializer Task serialization functionality
-  # @see CMDx::ResultAnsi Result ANSI colorization
+  # 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
 
-    # Keys that should be colorized when ANSI colorization is enabled.
-    #
-    # These keys represent result state information that benefits from
-    # color coding in terminal output for better visual distinction.
     COLORED_KEYS = %i[
       state status outcome
     ].freeze
 
     module_function
 
-    # Serializes a log message into a structured hash format.
+    # Serializes a log message with task context into structured hash format.
+    #
+    # 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 [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
     #
-    # Converts log messages into hash format suitable for structured logging.
-    # Handles both Result objects and plain messages differently, with optional
-    # ANSI colorization for terminal-friendly output.
+    # @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)
     #
-    # @param _severity [Symbol] Log severity level (not used in current implementation)
-    # @param _time [Time] Log timestamp (not used in current implementation)
-    # @param task [CMDx::Task] The task instance generating the log message
-    # @param message [Object] The message to serialize (Result object or other)
-    # @param options [Hash] Serialization options
-    # @option options [Boolean] :ansi_colorize (false) Whether to apply ANSI colors
-    # @return [Hash] Structured hash representation of the log message
+    # @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 Plain message serialization
-    #   LoggerSerializer.call(:info, Time.now, task, "Task started")
-    #   # => {
+    # @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: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   chain_id: "abc123",
     #   #   type: "Task",
-    #   #   class: "MyTask",
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   class: "ProcessDataTask",
+    #   #   id: "def456",
     #   #   tags: [],
-    #   #   message: "Task started"
+    #   #   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 Result object serialization
-    #   result = CMDx::Result.new(task)
-    #   result.complete!
-    #
-    #   LoggerSerializer.call(:info, Time.now, task, result)
-    #   # => {
+    # @example Serialize a string message with task context
+    #   task = MyTask.new(context: {data: "test"})
+    #   LoggerSerializer.call(:warn, Time.now, task, "Processing started")
+    #   #=> {
     #   #   origin: "CMDx",
-    #   #   state: "complete",
-    #   #   status: "success",
-    #   #   outcome: "success",
-    #   #   metadata: {},
-    #   #   runtime: 0.001,
     #   #   index: 0,
-    #   #   chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   chain_id: "abc123",
     #   #   type: "Task",
     #   #   class: "MyTask",
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   tags: []
+    #   #   id: "def456",
+    #   #   tags: [],
+    #   #   message: "Processing started"
     #   # }
     #
-    # @example Colorized result serialization
-    #   LoggerSerializer.call(:info, Time.now, task, result, ansi_colorize: true)
-    #   # => Same as above but state/status/outcome values contain ANSI color codes
-    #   # => { state: "\e[32mcomplete\e[0m", status: "\e[32msuccess\e[0m", ... }
-    #
-    # @example Hash-like message object
-    #   custom_message = OpenStruct.new(action: "process", item_id: 123)
-    #   LoggerSerializer.call(:debug, Time.now, task, custom_message)
-    #   # => {
+    # @example Serialize a result message without colors
+    #   task = ValidationTask.call(email: "invalid")
+    #   LoggerSerializer.call(:error, Time.now, task, task.result)
+    #   #=> {
     #   #   origin: "CMDx",
-    #   #   action: "process",
-    #   #   item_id: 123,
-    #   #   index: 0,
-    #   #   chain_id: "...",
+    #   #   index: 1,
+    #   #   chain_id: "xyz789",
     #   #   type: "Task",
-    #   #   class: "MyTask",
-    #   #   id: "...",
-    #   #   tags: []
+    #   #   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)
-      m = message.respond_to?(:to_h) ? message.to_h : {}
+    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)
         COLORED_KEYS.each { |k| m[k] = ResultAnsi.call(m[k]) if m.key?(k) }
       elsif !message.is_a?(Result)
-        m.merge!(
-          TaskSerializer.call(task),
-          message: message
-        )
+        m.merge!(TaskSerializer.call(task), message: message)
       end
 
       m[:origin] ||= "CMDx"

data/lib/cmdx/middleware.rb

@@ -1,71 +1,67 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Base class for CMDx middleware that follows Rack-style interface.
+  # Base class for implementing middleware functionality in task processing pipelines.
   #
-  # Middleware components can wrap task execution to provide cross-cutting
-  # concerns like logging, authentication, caching, or error handling.
-  # Each middleware must implement the `call` method which receives the
-  # task instance and a callable that represents the next middleware
-  # in the chain.
-  #
-  # @example Basic middleware implementation
-  #   class LoggingMiddleware < CMDx::Middleware
-  #     def call(task, callable)
-  #       puts "Before executing #{task.class.name}"
-  #       result = callable.call(task)
-  #       puts "After executing #{task.class.name}"
-  #       result
-  #     end
-  #   end
-  #
-  # @example Middleware with initialization parameters
-  #   class AuthenticationMiddleware < CMDx::Middleware
-  #     def initialize(required_role)
-  #       @required_role = required_role
-  #     end
-  #
-  #     def call(task, callable)
-  #       unless task.context.user&.has_role?(@required_role)
-  #         task.fail!(reason: "Insufficient permissions")
-  #         return task.result
-  #       end
-  #       callable.call(task)
-  #     end
-  #   end
-  #
-  # @example Short-circuiting middleware
-  #   class CachingMiddleware < CMDx::Middleware
-  #     def call(task, callable)
-  #       cache_key = "#{task.class.name}:#{task.context.to_h.hash}"
-  #
-  #       if cached_result = Rails.cache.read(cache_key)
-  #         task.result.merge!(cached_result)
-  #         return task.result
-  #       end
-  #
-  #       result = callable.call(task)
-  #       Rails.cache.write(cache_key, result.to_h) if result.success?
-  #       result
-  #     end
-  #   end
-  #
-  # @see MiddlewareRegistry management
-  # @see Task middleware integration
+  # 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 the middleware logic.
+    # Executes middleware by creating a new instance and calling it.
+    #
+    # 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.
+    #
+    # @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
+    #   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 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 [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 processing
     #
-    # This method must be implemented by subclasses to define the middleware
-    # behavior. The method receives the task instance and a callable that
-    # represents the next middleware in the chain or the final task execution.
+    # @raise [UndefinedCallError] always raised in the base class
     #
-    # @param task [Task] the task instance being executed
-    # @param callable [#call] the next middleware or task execution callable
-    # @return [Result] the task execution result
-    # @abstract Subclasses must implement this method
+    # @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}"
     end