cmdx 1.0.0 → 1.1.0

data/lib/cmdx/logger_ansi.rb

@@ -1,41 +1,13 @@
 # frozen_string_literal: true
 
 module CMDx
-  # ANSI color formatting module for logger severity levels.
+  # ANSI color formatting utilities for log severity levels.
   #
-  # 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
+  # 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.
   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 +18,32 @@ module CMDx
 
     module_function
 
-    # Applies ANSI color formatting to a severity string.
-    #
-    # 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.
+    # Applies ANSI color formatting to a log message based on its severity level.
     #
-    # @param s [String] The severity string to colorize
-    # @return [String] The string with ANSI color codes applied
+    # @param s [String] the log message string to format
     #
-    # @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)
+    # @return [String] the formatted message with ANSI color codes applied
     #
-    # @example Unknown severity level
-    #   LoggerAnsi.call("CUSTOM") # => "\e[1;39mCUSTOM\e[0m" (default color bold)
+    # @example Format a debug message
+    #   CMDx::LoggerAnsi.call("DEBUG: Starting process") #=> "\e[1;34;49mDEBUG: Starting process\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 an error message
+    #   CMDx::LoggerAnsi.call("ERROR: Connection failed") #=> "\e[1;31;49mERROR: Connection failed\e[0m"
     def call(s)
       Utils::AnsiColor.call(s, color: color(s), mode: :bold)
     end
 
-    # Determines the appropriate color for a severity string.
-    #
-    # 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.
-    #
-    # @param s [String] The severity string to determine color for
-    # @return [Symbol] The color symbol for the severity level
+    # Determines the appropriate color for a log message based on its severity level.
     #
-    # @example Mapping severity levels to colors
-    #   color("DEBUG")    # => :blue
-    #   color("INFO")     # => :green
-    #   color("WARN")     # => :yellow
-    #   color("ERROR")    # => :red
-    #   color("FATAL")    # => :magenta
+    # @param s [String] the log message string to analyze
     #
-    # @example Unknown severity level
-    #   color("CUSTOM")   # => :default
-    #   color("TRACE")    # => :default
+    # @return [Symbol] the color symbol corresponding to the severity level
     #
-    # @example Case sensitivity
-    #   color("debug")    # => :default (lowercase 'd' not mapped)
-    #   color("Debug")    # => :blue (uppercase 'D' is mapped)
+    # @example Get color for debug message
+    #   CMDx::LoggerAnsi.color("DEBUG: message") #=> :blue
     #
-    # @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
+    #   CMDx::LoggerAnsi.color("UNKNOWN: message") #=> :default
     def color(s)
       SEVERITY_COLORS[s[0]] || :default
     end

data/lib/cmdx/logger_serializer.rb

@@ -1,140 +1,50 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Logger message serialization module for structured log output.
+  # Serializes log messages for structured logging output.
   #
-  # 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
+  # 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.
   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.
+    # Converts a log message into a structured hash format.
     #
-    # 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.
+    # 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.
     #
-    # @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
+    # @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
     #
-    # @example Plain message serialization
-    #   LoggerSerializer.call(:info, Time.now, task, "Task started")
-    #   # => {
-    #   #   origin: "CMDx",
-    #   #   index: 0,
-    #   #   chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   type: "Task",
-    #   #   class: "MyTask",
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   tags: [],
-    #   #   message: "Task started"
-    #   # }
+    # @return [Hash] A structured hash representation of the log message with origin set to "CMDx"
     #
-    # @example Result object serialization
+    # @example Serializing a Result object with colorization
     #   result = CMDx::Result.new(task)
-    #   result.complete!
-    #
-    #   LoggerSerializer.call(:info, Time.now, task, result)
-    #   # => {
-    #   #   origin: "CMDx",
-    #   #   state: "complete",
-    #   #   status: "success",
-    #   #   outcome: "success",
-    #   #   metadata: {},
-    #   #   runtime: 0.001,
-    #   #   index: 0,
-    #   #   chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   type: "Task",
-    #   #   class: "MyTask",
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   tags: []
-    #   # }
-    #
-    # @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", ... }
+    #   LoggerSerializer.call("info", Time.now, task, result, ansi_colorize: true)
+    #   # => { state: "\e[32msuccess\e[0m", status: "complete", origin: "CMDx", ... }
     #
-    # @example Hash-like message object
-    #   custom_message = OpenStruct.new(action: "process", item_id: 123)
-    #   LoggerSerializer.call(:debug, Time.now, task, custom_message)
-    #   # => {
-    #   #   origin: "CMDx",
-    #   #   action: "process",
-    #   #   item_id: 123,
-    #   #   index: 0,
-    #   #   chain_id: "...",
-    #   #   type: "Task",
-    #   #   class: "MyTask",
-    #   #   id: "...",
-    #   #   tags: []
-    #   # }
+    # @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)
-      m = message.respond_to?(:to_h) ? message.to_h : {}
+      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,49 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Base class for CMDx middleware that follows Rack-style interface.
+  # Base class for implementing middleware functionality in task execution.
   #
-  # 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 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.
   class Middleware
 
-    ##
-    # Executes the middleware logic.
+    # 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
+    #
+    # @return [Object] the result of the middleware execution
+    #
+    # @raise [UndefinedCallError] when the middleware subclass doesn't implement call
+    #
+    # @example Execute middleware on a task
+    #   MyMiddleware.call(task, -> { 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.
+    #
+    # @param _task [Task] the task instance being wrapped by the middleware
+    # @param _callable [Proc] the callable object to execute within the middleware
+    #
+    # @return [Object] the result of the middleware execution
     #
-    # 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 in a subclass
+    #   def call(task, callable)
+    #     puts "Before #{task.class.name} execution"
+    #     result = callable.call
+    #     puts "After #{task.class.name} execution"
+    #     result
+    #   end
     def call(_task, _callable)
       raise UndefinedCallError, "call method not defined in #{self.class.name}"
     end

data/lib/cmdx/middleware_registry.rb

@@ -1,103 +1,107 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # The MiddlewareRegistry collection provides a Rack-style middleware chain that wraps
-  # task execution with cross-cutting concerns like logging, authentication,
-  # caching, and more. Middleware can short-circuit execution by returning
-  # early without calling the next middleware in the chain.
+  # Registry for managing middleware definitions and execution within tasks.
   #
-  # The MiddlewareRegistry collection extends Array to provide specialized functionality for
-  # managing collections of middleware definitions within CMDx tasks. It handles
-  # middleware execution coordination, chaining, and inspection.
-  #
-  # @example Basic middleware usage
-  #   middleware_registry = MiddlewareRegistry.new
-  #   middleware_registry.use(LoggingMiddleware)
-  #   middleware_registry.use(AuthenticationMiddleware, required_role: :admin)
-  #   middleware_registry.use(CachingMiddleware, ttl: 300)
-  #
-  #   result = middleware_registry.call(task) do |t|
-  #     t.call
-  #     t.result
-  #   end
-  #
-  # @example Array-like operations
-  #   middleware_registry << [LoggingMiddleware, [], nil]
-  #   middleware_registry.size  # => 1
-  #   middleware_registry.empty?  # => false
-  #   middleware_registry.each { |middleware| puts middleware.inspect }
-  #
-  # @example Using proc middleware
-  #   middleware_registry.use(proc do |task, callable|
-  #     puts "Before task execution"
-  #     result = callable.call(task)
-  #     puts "After task execution"
-  #     result
-  #   end)
-  #
-  # @see Middleware Base middleware class
-  # @since 1.0.0
-  class MiddlewareRegistry < Array
+  # This registry handles the registration and execution of middleware that can
+  # wrap task execution, providing cross-cutting concerns like logging, timing,
+  # 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
+
+    # Initializes a new middleware registry.
+    #
+    # @param registry [Hash] optional hash of initial middleware configurations
+    #
+    # @return [MiddlewareRegistry] a new middleware registry instance
+    #
+    # @example Creating an empty registry
+    #   MiddlewareRegistry.new
+    #
+    # @example Creating a registry with initial middleware
+    #   MiddlewareRegistry.new(TimeoutMiddleware => [[], {timeout: 30}, nil])
+    def initialize(registry = {})
+      @registry = registry.to_h
+    end
 
-    # Adds middleware to the registry.
+    # Registers a middleware with the registry.
+    #
+    # @param middleware [Class, Object] the middleware class or instance to register
+    # @param args [Array] positional arguments to pass to middleware initialization
+    # @param kwargs [Hash] keyword arguments to pass to middleware initialization
+    # @param block [Proc] optional block to pass to middleware initialization
     #
-    # @param middleware [Class, Object, Proc] The middleware to add
-    # @param args [Array] Arguments to pass to middleware constructor
-    # @param block [Proc] Block to pass to middleware constructor
     # @return [MiddlewareRegistry] self for method chaining
     #
-    # @example Add middleware class
-    #   registry.use(LoggingMiddleware, log_level: :info)
+    # @example Register a middleware class
+    #   registry.register(TimeoutMiddleware, 30)
     #
-    # @example Add middleware instance
-    #   registry.use(LoggingMiddleware.new(log_level: :info))
+    # @example Register a middleware with keyword arguments
+    #   registry.register(LoggingMiddleware, level: :info)
     #
-    # @example Add proc middleware
-    #   registry.use(proc { |task, callable| callable.call(task) })
-    def use(middleware, *args, &block)
-      self << [middleware, args, block]
+    # @example Register a middleware with a block
+    #   registry.register(CustomMiddleware) { |task| puts "Processing #{task.id}" }
+    def register(middleware, *args, **kwargs, &block)
+      registry[middleware] = [args, kwargs, block]
       self
     end
 
-    # Executes the middleware chain around the given block.
-    #
-    # @param task [Task] The task instance to pass through middleware
-    # @yield [Task] The task instance for final execution
-    # @yieldreturn [Object] The result of task execution
-    # @return [Object] The result from the middleware chain
-    #
-    # @example Execute with middleware
-    #   result = registry.call(task) do |t|
-    #     t.call
-    #     t.result
-    #   end
+    # Executes all registered middleware around the provided task.
+    #
+    # @param task [Task] the task instance to execute middleware around
+    # @param block [Proc] the block to execute after all middleware processing
+    #
+    # @return [Object] the result of the middleware chain execution
+    #
+    # @raise [ArgumentError] if no block is provided
+    #
+    # @example Execute middleware around a task
+    #   registry.call(task) { |task| task.process }
+    #
+    # @example Execute with early return if no middleware
+    #   registry.call(task) { |task| puts "No middleware to execute" }
     def call(task, &)
-      return yield(task) if empty?
+      raise ArgumentError, "block required" unless block_given?
+
+      return yield(task) if registry.empty?
 
       build_chain(&).call(task)
     end
 
+    # Returns a hash representation of the registry.
+    #
+    # @return [Hash] deep copy of registry with duplicated configuration arrays
+    #
+    # @example Getting registry hash
+    #   registry.to_h
+    #   # => { TimeoutMiddleware => [[30], {}, nil] }
+    def to_h
+      registry.transform_values do |config|
+        args, kwargs, block = config
+        [args.dup, kwargs.dup, block]
+      end
+    end
+
     private
 
-    # Builds the middleware call chain.
+    # Builds the middleware execution chain by wrapping middleware around the call block.
+    #
+    # @param call_block [Proc] the final block to execute after all middleware
     #
-    # Creates a nested chain of callables where each middleware wraps the next,
-    # with the provided block as the innermost callable.
+    # @return [Proc] the complete middleware chain as a callable proc
     #
-    # @param block [Proc] The final block to execute
-    # @return [Proc] The middleware chain as a callable
-    def build_chain(&block)
-      reverse.reduce(block) do |next_callable, (middleware, args, middleware_block)|
+    # @example Building a middleware chain (internal use)
+    #   build_chain { |task| task.process }
+    def build_chain(&call_block)
+      registry.reverse_each.reduce(call_block) do |next_callable, (middleware, config)|
         proc do |task|
-          if middleware.respond_to?(:call) && !middleware.respond_to?(:new)
-            # Proc middleware
-            middleware.call(task, next_callable)
-          else
-            # Class or instance middleware
-            instance = middleware.respond_to?(:new) ? middleware.new(*args, &middleware_block) : middleware
-            instance.call(task, next_callable)
-          end
+          args, kwargs, block = config
+          instance = middleware.respond_to?(:new) ? middleware.new(*args, **kwargs, &block) : middleware
+          instance.call(task, next_callable)
         end
       end
     end