cmdx 0.5.0 → 1.0.0

data/lib/cmdx/utils/ansi_color.rb

@@ -2,8 +2,59 @@
 
 module CMDx
   module Utils
+    # Utility for adding ANSI color codes to terminal output.
+    #
+    # 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
     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,
@@ -23,6 +74,14 @@ 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,
@@ -42,6 +101,42 @@ 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"
+      #
+      # @example Error message with red text
+      #   AnsiColor.call("Error", color: :red)
+      #   # => "\e[0;31;49mError\e[0m"
+      #
+      # @example Warning with yellow underlined text
+      #   AnsiColor.call("Warning", color: :yellow, mode: :underline)
+      #   # => "\e[4;33;49mWarning\e[0m"
+      #
+      # @example Debug info with dimmed light text
+      #   AnsiColor.call("Debug info", color: :light_black, mode: :dim)
+      #   # => "\e[2;90;49mDebug info\e[0m"
+      #
+      # @example Invalid color raises KeyError
+      #   AnsiColor.call("Text", color: :invalid_color)
+      #   # => KeyError: key not found: :invalid_color
+      #
+      # @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
       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,12 +2,60 @@
 
 module CMDx
   module Utils
+    # Utility for formatting timestamps in CMDx log entries.
+    #
+    # 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
     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.
+      #
+      # 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] Time object to format
+      # @return [String] ISO 8601 formatted timestamp with microseconds
+      #
+      # @example Current time formatting
+      #   LogTimestamp.call(Time.now)
+      #   # => "2022-07-17T18:43:15.123456"
+      #
+      # @example UTC time formatting for logs
+      #   LogTimestamp.call(Time.now.utc)
+      #   # => "2022-07-17T18:43:15.123456"
+      #
+      # @example Integration with log formatters
+      #   def format_log_entry(severity, time, message)
+      #     timestamp = LogTimestamp.call(time.utc)
+      #     "#{severity} [#{timestamp}] #{message}"
+      #   end
       def call(time)
         time.strftime(DATETIME_FORMAT)
       end

data/lib/cmdx/utils/monotonic_runtime.rb

@@ -2,16 +2,83 @@
 
 module CMDx
   module Utils
+    # Utility for measuring execution time using monotonic clock.
+    #
+    # MonotonicRuntime provides accurate execution time measurement that is
+    # unaffected by system clock adjustments, leap seconds, or other time
+    # synchronization events. Uses Ruby's Process.clock_gettime with
+    # CLOCK_MONOTONIC for reliable performance measurements.
+    #
+    # @example Basic runtime measurement
+    #   runtime = Utils::MonotonicRuntime.call do
+    #     sleep(1.5)
+    #     # ... task execution code ...
+    #   end
+    #   # => 1500 (milliseconds)
+    #
+    # @example Task execution timing
+    #   class ProcessOrderTask < CMDx::Task
+    #     def call
+    #       runtime = Utils::MonotonicRuntime.call do
+    #         # Complex business logic
+    #         process_payment
+    #         update_inventory
+    #         send_confirmation
+    #       end
+    #       logger.info "Order processed in #{runtime}ms"
+    #     end
+    #   end
+    #
+    # @example Performance benchmarking
+    #   fast_time = Utils::MonotonicRuntime.call { fast_algorithm }
+    #   slow_time = Utils::MonotonicRuntime.call { slow_algorithm }
+    #   puts "Fast algorithm is #{slow_time / fast_time}x faster"
+    #
+    # @see CMDx::Task Uses this internally to measure task execution time
+    # @see CMDx::Result#runtime Contains the measured execution time
     module MonotonicRuntime
 
       module_function
 
+      # Measures the execution time of a given block using monotonic clock.
+      #
+      # Executes the provided block and returns the elapsed time in milliseconds.
+      # Uses Process.clock_gettime with CLOCK_MONOTONIC to ensure accurate
+      # timing that is immune to system clock changes.
+      #
+      # @yield Block of code to measure execution time for
+      # @return [Integer] Execution time in milliseconds
+      #
+      # @example Simple timing measurement
+      #   time_taken = MonotonicRuntime.call do
+      #     expensive_operation
+      #   end
+      #   puts "Operation took #{time_taken}ms"
+      #
+      # @example Database query timing
+      #   query_time = MonotonicRuntime.call do
+      #     User.joins(:orders).where(active: true).count
+      #   end
+      #   logger.debug "Query executed in #{query_time}ms"
+      #
+      # @example API call timing with error handling
+      #   api_time = MonotonicRuntime.call do
+      #     begin
+      #       external_api.fetch_data
+      #     rescue => e
+      #       logger.error "API call failed: #{e.message}"
+      #       raise
+      #     end
+      #   end
+      #   # Time is measured even if an exception occurs
+      #
+      # @note The block's return value is discarded; only execution time is returned
+      # @note Uses millisecond precision for practical performance monitoring
+      # @note Monotonic clock ensures accurate timing regardless of system clock changes
       def call(&)
-        start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
         yield
-        finish = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
-
-        finish - start
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - now
       end
 
     end

data/lib/cmdx/utils/name_affix.rb

@@ -2,14 +2,92 @@
 
 module CMDx
   module Utils
+    # Utility for generating method names with prefixes and suffixes.
+    #
+    # NameAffix provides flexible method name generation for dynamic method
+    # creation, delegation, and metaprogramming scenarios. Supports custom
+    # prefixes, suffixes, and complete name overrides for method naming
+    # conventions in CMDx's parameter and delegation systems.
+    #
+    # @example Basic prefix and suffix usage
+    #   Utils::NameAffix.call(:name, "user", prefix: true, suffix: true)
+    #   # => :user_name_user
+    #
+    # @example Custom prefix
+    #   Utils::NameAffix.call(:email, "admin", prefix: "get_")
+    #   # => :get_email
+    #
+    # @example Custom suffix
+    #   Utils::NameAffix.call(:count, "items", suffix: "_total")
+    #   # => :count_total
+    #
+    # @example Complete name override
+    #   Utils::NameAffix.call(:original, "source", as: :custom_method)
+    #   # => :custom_method
+    #
+    # @example Parameter delegation usage
+    #   class MyTask < CMDx::Task
+    #     required :user_id
+    #
+    #     # Internally uses NameAffix for method generation
+    #     # Creates methods like user_id, user_id?, etc.
+    #   end
+    #
+    # @see CMDx::Parameter Uses this for parameter method name generation
+    # @see CMDx::CoreExt::Module Uses this for delegation method naming
     module NameAffix
 
+      # Proc for handling affix logic with boolean or custom values
+      # @return [Proc] processor for affix options that handles true/false and custom strings
       AFFIX = proc do |o, &block|
         o == true ? block.call : o
       end.freeze
 
       module_function
 
+      # Generates a method name with optional prefix and suffix.
+      #
+      # Creates a method name by combining the base method name with optional
+      # prefixes and suffixes. Supports boolean flags for default affixes or
+      # custom string values for specific naming patterns.
+      #
+      # @param method_name [Symbol, String] Base method name to transform
+      # @param source [String] Source identifier used for default prefix/suffix generation
+      # @param options [Hash] Configuration options for name generation
+      # @option options [Boolean, String] :prefix (false) Add prefix - true for "#{source}_", string for custom
+      # @option options [Boolean, String] :suffix (false) Add suffix - true for "_#{source}", string for custom
+      # @option options [Symbol] :as Override the entire generated name
+      #
+      # @return [Symbol] Generated method name with applied affixes
+      #
+      # @example Default prefix generation
+      #   NameAffix.call(:method, "user", prefix: true)
+      #   # => :user_method
+      #
+      # @example Custom prefix
+      #   NameAffix.call(:method, "user", prefix: "get_")
+      #   # => :get_method
+      #
+      # @example Default suffix generation
+      #   NameAffix.call(:method, "user", suffix: true)
+      #   # => :method_user
+      #
+      # @example Custom suffix
+      #   NameAffix.call(:method, "user", suffix: "_count")
+      #   # => :method_count
+      #
+      # @example Combined prefix and suffix
+      #   NameAffix.call(:name, "user", prefix: "get_", suffix: "_value")
+      #   # => :get_name_value
+      #
+      # @example Complete name override (ignores prefix/suffix)
+      #   NameAffix.call(:original, "user", prefix: true, as: :custom)
+      #   # => :custom
+      #
+      # @example Parameter method generation
+      #   # CMDx internally uses this for parameter methods:
+      #   NameAffix.call(:email, "user", suffix: "?")  # => :email?
+      #   NameAffix.call(:process, "order", prefix: "can_")  # => :can_process
       def call(method_name, source, options = {})
         options[:as] || begin
           prefix = AFFIX.call(options[:prefix]) { "#{source}_" }

data/lib/cmdx/validators/custom.rb

@@ -2,10 +2,92 @@
 
 module CMDx
   module Validators
+    # Custom validator for parameter validation using user-defined validation logic.
+    #
+    # The Custom validator allows you to implement your own validation logic by
+    # providing a callable validator class or object. This enables complex business
+    # rule validation that goes beyond the built-in validators.
+    #
+    # @example Basic custom validator
+    #   class EmailDomainValidator
+    #     def self.call(value, options)
+    #       allowed_domains = options.dig(:custom, :domains) || ['example.com']
+    #       domain = value.split('@').last
+    #       allowed_domains.include?(domain)
+    #     end
+    #   end
+    #
+    #   class ProcessUserTask < CMDx::Task
+    #     required :email, custom: { validator: EmailDomainValidator }
+    #   end
+    #
+    # @example Custom validator with options
+    #   class ProcessUserTask < CMDx::Task
+    #     required :email, custom: {
+    #       validator: EmailDomainValidator,
+    #       domains: ['company.com', 'partner.org'],
+    #       message: "must be from an approved domain"
+    #     }
+    #   end
+    #
+    # @example Complex business logic validator
+    #   class AgeValidator
+    #     def self.call(value, options)
+    #       min_age = options.dig(:custom, :min_age) || 18
+    #       max_age = options.dig(:custom, :max_age) || 120
+    #       value.between?(min_age, max_age)
+    #     end
+    #   end
+    #
+    # @example Proc-based validator
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :discount, custom: {
+    #       validator: ->(value, options) { value <= 50 },
+    #       message: "cannot exceed 50%"
+    #     }
+    #   end
+    #
+    # @see CMDx::Parameter Parameter validation integration
+    # @see CMDx::ValidationError Raised when validation fails
     module Custom
 
       module_function
 
+      # Validates a parameter value using a custom validator.
+      #
+      # Calls the provided validator with the value and options, expecting
+      # a truthy return value for successful validation. If validation fails,
+      # raises a ValidationError with the configured or default message.
+      #
+      # @param value [Object] The parameter value to validate
+      # @param options [Hash] Validation configuration options
+      # @option options [Hash] :custom Custom validation configuration
+      # @option options [#call] :custom.validator Callable validator object/class
+      # @option options [String] :custom.message Custom error message
+      # @option options [Hash] :custom Additional options passed to validator
+      #
+      # @return [void]
+      # @raise [ValidationError] If the custom validator returns falsy
+      #
+      # @example Successful validation
+      #   validator = ->(value, options) { value.length > 5 }
+      #   Custom.call("hello world", custom: { validator: validator })
+      #   # => passes without error
+      #
+      # @example Failed validation with default message
+      #   validator = ->(value, options) { value > 100 }
+      #   Custom.call(50, custom: { validator: validator })
+      #   # => raises ValidationError: "is not valid"
+      #
+      # @example Failed validation with custom message
+      #   validator = ->(value, options) { value.even? }
+      #   Custom.call(7, custom: { validator: validator, message: "must be even" })
+      #   # => raises ValidationError: "must be even"
+      #
+      # @example Validator with additional options
+      #   validator = ->(value, opts) { value >= opts.dig(:custom, :minimum) }
+      #   Custom.call(10, custom: { validator: validator, minimum: 5 })
+      #   # => passes without error
       def call(value, options = {})
         return if options.dig(:custom, :validator).call(value, options)
 

data/lib/cmdx/validators/exclusion.rb

@@ -2,10 +2,93 @@
 
 module CMDx
   module Validators
+    # Exclusion validator for parameter validation against forbidden values.
+    #
+    # The Exclusion validator ensures that parameter values are NOT within a
+    # specified set of forbidden values. It supports both array-based exclusion
+    # (specific values) and range-based exclusion (value ranges).
+    #
+    # @example Basic exclusion validation with array
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :status, exclusion: { in: ['cancelled', 'refunded'] }
+    #     required :priority, exclusion: { in: [0, -1] }
+    #   end
+    #
+    # @example Range-based exclusion
+    #   class ProcessUserTask < CMDx::Task
+    #     required :age, exclusion: { in: 0..17 }  # Must be 18 or older
+    #     required :score, exclusion: { within: 90..100 }  # Cannot be in top 10%
+    #   end
+    #
+    # @example Custom error messages
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :status, exclusion: {
+    #       in: ['cancelled', 'refunded'],
+    #       of_message: "cannot be cancelled or refunded"
+    #     }
+    #     required :age, exclusion: {
+    #       in: 0..17,
+    #       in_message: "must be %{min} or older"
+    #     }
+    #   end
+    #
+    # @example Exclusion validation behavior
+    #   # Array exclusion
+    #   Exclusion.call("active", exclusion: { in: ['cancelled'] })     # passes
+    #   Exclusion.call("cancelled", exclusion: { in: ['cancelled'] })  # raises ValidationError
+    #
+    #   # Range exclusion
+    #   Exclusion.call(25, exclusion: { in: 0..17 })  # passes
+    #   Exclusion.call(15, exclusion: { in: 0..17 })  # raises ValidationError
+    #
+    # @see CMDx::Validators::Inclusion For validating values must be in a set
+    # @see CMDx::Parameter Parameter validation integration
+    # @see CMDx::ValidationError Raised when validation fails
     module Exclusion
 
       extend self
 
+      # Validates that a parameter value is not in the excluded set.
+      #
+      # Checks that the value is not present in the specified array or range
+      # of forbidden values. Raises ValidationError if the value is found
+      # in the exclusion set.
+      #
+      # @param value [Object] The parameter value to validate
+      # @param options [Hash] Validation configuration options
+      # @option options [Hash] :exclusion Exclusion validation configuration
+      # @option options [Array, Range] :exclusion.in Values/range to exclude
+      # @option options [Array, Range] :exclusion.within Alias for :in
+      # @option options [String] :exclusion.of_message Error message for array exclusion
+      # @option options [String] :exclusion.in_message Error message for range exclusion
+      # @option options [String] :exclusion.within_message Alias for :in_message
+      # @option options [String] :exclusion.message General error message override
+      #
+      # @return [void]
+      # @raise [ValidationError] If value is found in the exclusion set
+      #
+      # @example Array exclusion validation
+      #   Exclusion.call("pending", exclusion: { in: ['cancelled', 'failed'] })
+      #   # => passes without error
+      #
+      # @example Failed array exclusion
+      #   Exclusion.call("cancelled", exclusion: { in: ['cancelled', 'failed'] })
+      #   # => raises ValidationError: "must not be one of: \"cancelled\", \"failed\""
+      #
+      # @example Range exclusion validation
+      #   Exclusion.call(25, exclusion: { in: 0..17 })
+      #   # => passes without error
+      #
+      # @example Failed range exclusion
+      #   Exclusion.call(15, exclusion: { in: 0..17 })
+      #   # => raises ValidationError: "must not be within 0 and 17"
+      #
+      # @example Custom error messages
+      #   Exclusion.call("admin", exclusion: {
+      #     in: ['admin', 'root'],
+      #     of_message: "role is restricted"
+      #   })
+      #   # => raises ValidationError: "role is restricted"
       def call(value, options = {})
         values = options.dig(:exclusion, :in) ||
                  options.dig(:exclusion, :within)
@@ -19,6 +102,11 @@ module CMDx
 
       private
 
+      # Raises validation error for array-based exclusion violations.
+      #
+      # @param values [Array] The excluded values array
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_of_validation_error!(values, options)
         values  = values.map(&:inspect).join(", ")
         message = options.dig(:exclusion, :of_message) ||
@@ -32,6 +120,12 @@ module CMDx
         )
       end
 
+      # Raises validation error for range-based exclusion violations.
+      #
+      # @param min [Object] Range minimum value
+      # @param max [Object] Range maximum value
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_within_validation_error!(min, max, options)
         message = options.dig(:exclusion, :in_message) ||
                   options.dig(:exclusion, :within_message) ||