cmdx 0.4.0 → 1.0.0

data/lib/cmdx/result_ansi.rb

@@ -1,26 +1,122 @@
 # frozen_string_literal: true
 
 module CMDx
+  # ANSI color formatting module for result states and statuses.
+  #
+  # The ResultAnsi module provides ANSI color formatting for result state and
+  # status values to enhance readability in terminal output. It maps different
+  # result states and statuses to appropriate colors for visual distinction.
+  #
+  # @example Basic result colorization
+  #   ResultAnsi.call("complete")     # => Green colored text
+  #   ResultAnsi.call("success")      # => Green colored text
+  #   ResultAnsi.call("failed")       # => Red colored text
+  #   ResultAnsi.call("interrupted")  # => Red colored text
+  #
+  # @example Usage in log formatters
+  #   result_data = { state: "complete", status: "success" }
+  #   colored_state = ResultAnsi.call(result_data[:state])
+  #   colored_status = ResultAnsi.call(result_data[:status])
+  #
+  # @example Integration with pretty formatters
+  #   # Used internally by PrettyLine, PrettyJson, PrettyKeyValue formatters
+  #   formatted_status = ResultAnsi.call("failed")  # => Red "failed"
+  #
+  # @see CMDx::Result Result states and statuses
+  # @see CMDx::Utils::AnsiColor ANSI color utility functions
+  # @see CMDx::LogFormatters::PrettyLine Pretty line formatter with colors
   module ResultAnsi
 
+    # Mapping of result states to ANSI colors.
+    #
+    # Maps Result state constants to their corresponding color codes
+    # for consistent visual representation of execution states.
     STATE_COLORS = {
-      Result::INITIALIZED => :blue,
-      Result::EXECUTING => :yellow,
-      Result::COMPLETE => :green,
-      Result::INTERRUPTED => :red
+      Result::INITIALIZED => :blue,     # Initial state - blue
+      Result::EXECUTING => :yellow,     # Currently executing - yellow
+      Result::COMPLETE => :green,       # Successfully completed - green
+      Result::INTERRUPTED => :red       # Execution interrupted - red
     }.freeze
+
+    # Mapping of result statuses to ANSI colors.
+    #
+    # Maps Result status constants to their corresponding color codes
+    # for consistent visual representation of execution outcomes.
     STATUS_COLORS = {
-      Result::SUCCESS => :green,
-      Result::SKIPPED => :yellow,
-      Result::FAILED => :red
+      Result::SUCCESS => :green,        # Successful completion - green
+      Result::SKIPPED => :yellow,       # Intentionally skipped - yellow
+      Result::FAILED => :red            # Failed execution - red
     }.freeze
 
     module_function
 
+    # Applies ANSI color formatting to a result state or status string.
+    #
+    # Formats the input string with appropriate ANSI color codes based on
+    # whether it matches a known result state or status value. Falls back
+    # to default color for unknown values.
+    #
+    # @param s [String] The state or status string to colorize
+    # @return [String] The string with ANSI color codes applied
+    #
+    # @example Colorizing result states
+    #   ResultAnsi.call("initialized")  # => "\e[34minitialized\e[0m" (blue)
+    #   ResultAnsi.call("executing")    # => "\e[33mexecuting\e[0m" (yellow)
+    #   ResultAnsi.call("complete")     # => "\e[32mcomplete\e[0m" (green)
+    #   ResultAnsi.call("interrupted")  # => "\e[31minterrupted\e[0m" (red)
+    #
+    # @example Colorizing result statuses
+    #   ResultAnsi.call("success")      # => "\e[32msuccess\e[0m" (green)
+    #   ResultAnsi.call("skipped")      # => "\e[33mskipped\e[0m" (yellow)
+    #   ResultAnsi.call("failed")       # => "\e[31mfailed\e[0m" (red)
+    #
+    # @example Unknown value
+    #   ResultAnsi.call("unknown")      # => "\e[39munknown\e[0m" (default color)
+    #
+    # @example Usage in result formatting
+    #   result = ProcessOrderTask.call
+    #   colored_state = ResultAnsi.call(result.state)
+    #   colored_status = ResultAnsi.call(result.status)
+    #   puts "Task #{colored_state} with #{colored_status}"
+    #   # => "Task complete with success" (with appropriate colors)
     def call(s)
-      color = STATE_COLORS[s] || STATUS_COLORS[s] || :default
+      Utils::AnsiColor.call(s, color: color(s))
+    end
 
-      Utils::AnsiColor.call(s, color:)
+    # Determines the appropriate color for a result state or status string.
+    #
+    # Looks up the input string in both the STATE_COLORS and STATUS_COLORS
+    # mapping hashes to find the corresponding color symbol. First checks
+    # STATE_COLORS, then STATUS_COLORS, and falls back to the default color
+    # if no mapping is found in either hash.
+    #
+    # @param s [String] The state or status string to determine color for
+    # @return [Symbol] The color symbol for the state or status
+    #
+    # @example Result state color mapping
+    #   color("initialized")  # => :blue
+    #   color("executing")    # => :yellow
+    #   color("complete")     # => :green
+    #   color("interrupted")  # => :red
+    #
+    # @example Result status color mapping
+    #   color("success")      # => :green
+    #   color("skipped")      # => :yellow
+    #   color("failed")       # => :red
+    #
+    # @example Unknown state or status
+    #   color("unknown")      # => :default
+    #   color("pending")      # => :default
+    #
+    # @example Precedence behavior
+    #   # If a string exists in both hashes, STATE_COLORS takes precedence
+    #   color("some_value")   # => STATE_COLORS["some_value"] || STATUS_COLORS["some_value"] || :default
+    #
+    # @note STATE_COLORS mapping is checked before STATUS_COLORS mapping
+    # @see STATE_COLORS The mapping hash for result states
+    # @see STATUS_COLORS The mapping hash for result statuses
+    def color(s)
+      STATE_COLORS[s] || STATUS_COLORS[s] || :default
     end
 
   end

data/lib/cmdx/result_inspector.rb

@@ -1,8 +1,53 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Result inspection utility for generating human-readable result descriptions.
+  #
+  # The ResultInspector module provides functionality to convert result hash
+  # representations into formatted, human-readable strings. It handles special
+  # formatting for different result attributes and provides consistent ordering
+  # of result information.
+  #
+  # @example Basic result inspection
+  #   result_hash = {
+  #     class: "ProcessOrderTask",
+  #     type: "Task",
+  #     index: 0,
+  #     id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+  #     state: "complete",
+  #     status: "success",
+  #     outcome: "success",
+  #     metadata: { order_id: 123 },
+  #     runtime: 0.5
+  #   }
+  #
+  #   ResultInspector.call(result_hash)
+  #   # => "ProcessOrderTask: type=Task index=0 id=018c2b95-b764-7615-a924-cc5b910ed1e5 state=complete status=success outcome=success metadata={order_id: 123} runtime=0.5"
+  #
+  # @example Result with failure information
+  #   failed_result = {
+  #     class: "ProcessOrderTask",
+  #     type: "Task",
+  #     index: 1,
+  #     id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+  #     state: "interrupted",
+  #     status: "failed",
+  #     outcome: "failed",
+  #     caused_failure: { index: 0, class: "ValidationTask", id: "018c2b95..." },
+  #     threw_failure: { index: 0, class: "ValidationTask", id: "018c2b95..." }
+  #   }
+  #
+  #   ResultInspector.call(failed_result)
+  #   # => "ProcessOrderTask: type=Task index=1 id=018c2b95... state=interrupted status=failed outcome=failed caused_failure=<[0] ValidationTask: 018c2b95...> threw_failure=<[0] ValidationTask: 018c2b95...>"
+  #
+  # @see CMDx::Result Result hash serialization via to_h
+  # @see CMDx::ResultSerializer Result-to-hash conversion
   module ResultInspector
 
+    # Ordered keys for consistent result inspection output.
+    #
+    # Defines the order in which result attributes are displayed in the
+    # inspection string, ensuring consistent and logical presentation.
     ORDERED_KEYS = %i[
       class type index id state status outcome metadata
       tags pid runtime caused_failure threw_failure
@@ -10,6 +55,37 @@ module CMDx
 
     module_function
 
+    # Converts a result hash to a human-readable string representation.
+    #
+    # Formats result data into a structured string with proper ordering and
+    # special handling for different attribute types. The class name appears
+    # first followed by a colon, and failure references are specially formatted.
+    #
+    # @param result [Hash] The result hash to inspect
+    # @return [String] Formatted result description
+    #
+    # @example Simple result inspection
+    #   ResultInspector.call(result_hash)
+    #   # => "ProcessOrderTask: type=Task index=0 id=018c2b95... state=complete status=success"
+    #
+    # @example Result with metadata
+    #   result_with_metadata = { class: "MyTask", metadata: { user_id: 123, action: "create" } }
+    #   ResultInspector.call(result_with_metadata)
+    #   # => "MyTask: metadata={user_id: 123, action: create}"
+    #
+    # @example Result with failure references
+    #   result_with_failures = {
+    #     class: "MainTask",
+    #     caused_failure: { index: 2, class: "SubTask", id: "abc123" },
+    #     threw_failure: { index: 1, class: "HelperTask", id: "def456" }
+    #   }
+    #   ResultInspector.call(result_with_failures)
+    #   # => "MainTask: caused_failure=<[2] SubTask: abc123> threw_failure=<[1] HelperTask: def456>"
+    #
+    # @example Result with runtime information
+    #   result_with_runtime = { class: "SlowTask", runtime: 2.5, pid: 1234 }
+    #   ResultInspector.call(result_with_runtime)
+    #   # => "SlowTask: runtime=2.5 pid=1234"
     def call(result)
       ORDERED_KEYS.filter_map do |key|
         next unless result.key?(key)

data/lib/cmdx/result_logger.rb

@@ -1,16 +1,103 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Result-specific logging module for task execution outcomes.
+  #
+  # The ResultLogger module provides specialized logging functionality for
+  # CMDx task results. It automatically maps result statuses to appropriate
+  # log severity levels and handles conditional logging based on logger
+  # availability and configuration.
+  #
+  # @example Successful task result logging
+  #   task = ProcessOrderTask.call(order_id: 123)
+  #   ResultLogger.call(task.result)
+  #   # Logs at INFO level: "ProcessOrderTask completed successfully"
+  #
+  # @example Failed task result logging
+  #   task = ProcessOrderTask.call(invalid_params)
+  #   ResultLogger.call(task.result)
+  #   # Logs at ERROR level: "ProcessOrderTask failed with errors"
+  #
+  # @example Skipped task result logging
+  #   task = ProcessOrderTask.new
+  #   task.skip!(reason: "Order already processed")
+  #   ResultLogger.call(task.result)
+  #   # Logs at WARN level: "ProcessOrderTask was skipped"
+  #
+  # @example Integration with task execution
+  #   class ProcessOrderTask < CMDx::Task
+  #     def call
+  #       # Task logic here
+  #     end
+  #
+  #     # ResultLogger.call is automatically invoked after task execution
+  #   end
+  #
+  # @see CMDx::Result Result object status and state management
+  # @see CMDx::Logger Logger configuration and setup
+  # @see CMDx::Task Task execution and result handling
   module ResultLogger
 
+    # Mapping of result statuses to corresponding log severity levels.
+    #
+    # Maps CMDx result status constants to Ruby Logger severity levels
+    # to ensure appropriate logging levels for different task outcomes.
     STATUS_TO_SEVERITY = {
-      Result::SUCCESS => :info,
-      Result::SKIPPED => :warn,
-      Result::FAILED => :error
+      Result::SUCCESS => :info,   # Successful task completion
+      Result::SKIPPED => :warn,   # Task was skipped
+      Result::FAILED => :error    # Task execution failed
     }.freeze
 
     module_function
 
+    # Logs a task result at the appropriate severity level.
+    #
+    # Determines the appropriate log severity based on the result status
+    # and logs the result object using the task's configured logger.
+    # Does nothing if no logger is configured for the task.
+    #
+    # @param result [CMDx::Result] The task result to log
+    # @return [void]
+    #
+    # @example Logging a successful result
+    #   task = ProcessOrderTask.call(order_id: 123)
+    #   ResultLogger.call(task.result)
+    #   # Logs at INFO level with result details
+    #
+    # @example Logging a failed result
+    #   task = ProcessOrderTask.new
+    #   task.fail!(reason: "Invalid order ID")
+    #   ResultLogger.call(task.result)
+    #   # Logs at ERROR level with failure details
+    #
+    # @example Logging a skipped result
+    #   task = ProcessOrderTask.new
+    #   task.skip!(reason: "Order already processed")
+    #   ResultLogger.call(task.result)
+    #   # Logs at WARN level with skip reason
+    #
+    # @example No logger configured
+    #   class SimpleTask < CMDx::Task
+    #     # No logger setting
+    #   end
+    #
+    #   task = SimpleTask.call
+    #   ResultLogger.call(task.result)  # Does nothing - no logger available
+    #
+    # @example Custom logger configuration
+    #   class MyTask < CMDx::Task
+    #     task_settings!(
+    #       logger: Logger.new(STDOUT),
+    #       log_formatter: CMDx::LogFormatters::Json.new
+    #     )
+    #   end
+    #
+    #   task = MyTask.call
+    #   ResultLogger.call(task.result)  # Logs in JSON format to STDOUT
+    #
+    # @note This method is typically called automatically by the CMDx framework
+    #   after task execution completes, ensuring that all task results are
+    #   properly logged according to their outcome.
     def call(result)
       logger = result.task.send(:logger)
       return if logger.nil?

data/lib/cmdx/result_serializer.rb

@@ -1,8 +1,84 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Result serialization utility for converting Result objects to hash representations.
+  #
+  # The ResultSerializer module provides functionality to serialize Result instances
+  # into structured hash representations suitable for inspection, logging, debugging,
+  # and data interchange. It handles failure chain information and integrates with
+  # TaskSerializer for comprehensive result data.
+  #
+  # @example Basic result serialization
+  #   task = ProcessOrderTask.call(order_id: 123)
+  #   result = task.result
+  #
+  #   ResultSerializer.call(result)
+  #   # => {
+  #   #   class: "ProcessOrderTask",
+  #   #   type: "Task",
+  #   #   index: 0,
+  #   #   chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+  #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+  #   #   tags: [],
+  #   #   state: "complete",
+  #   #   status: "success",
+  #   #   outcome: "success",
+  #   #   metadata: {},
+  #   #   runtime: 0.5
+  #   # }
+  #
+  # @example Failed result serialization
+  #   task = ProcessOrderTask.new
+  #   task.fail!(reason: "Invalid order data", code: 422)
+  #   result = task.result
+  #
+  #   ResultSerializer.call(result)
+  #   # => {
+  #   #   class: "ProcessOrderTask",
+  #   #   type: "Task",
+  #   #   index: 0,
+  #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+  #   #   state: "interrupted",
+  #   #   status: "failed",
+  #   #   outcome: "failed",
+  #   #   metadata: { reason: "Invalid order data", code: 422 },
+  #   #   runtime: 0.1,
+  #   #   caused_failure: { ... },  # Failure chain information
+  #   #   threw_failure: { ... }
+  #   # }
+  #
+  # @example Result with failure chain
+  #   # When a result has failure chain information, it's included but
+  #   # stripped of recursive caused_failure/threw_failure to prevent cycles
+  #   ResultSerializer.call(result_with_failures)
+  #   # => {
+  #   #   # ... standard result data ...
+  #   #   caused_failure: {
+  #   #     class: "ValidationTask",
+  #   #     index: 1,
+  #   #     state: "interrupted",
+  #   #     status: "failed"
+  #   #     # caused_failure and threw_failure are stripped to prevent recursion
+  #   #   },
+  #   #   threw_failure: {
+  #   #     class: "ProcessingTask",
+  #   #     index: 2,
+  #   #     state: "interrupted",
+  #   #     status: "failed"
+  #   #     # caused_failure and threw_failure are stripped to prevent recursion
+  #   #   }
+  #   # }
+  #
+  # @see CMDx::Result Result object creation and state management
+  # @see CMDx::TaskSerializer Task serialization functionality
+  # @see CMDx::ResultInspector Human-readable result formatting
   module ResultSerializer
 
+    # Proc for stripping failure chain information to prevent recursion.
+    #
+    # This proc is used to include failure chain information (caused_failure
+    # and threw_failure) while preventing infinite recursion by stripping
+    # the same fields from nested failure objects.
     STRIP_FAILURE = proc do |h, r, k|
       unless r.send(:"#{k}?")
         # Strip caused/threw failures since its the same info as the log line
@@ -12,6 +88,67 @@ module CMDx
 
     module_function
 
+    # Converts a Result object to a hash representation.
+    #
+    # Serializes a Result instance into a structured hash containing all
+    # relevant result information including task data, execution state,
+    # status, metadata, runtime, and failure chain information.
+    #
+    # @param result [CMDx::Result] The result object to serialize
+    # @return [Hash] Structured hash representation of the result
+    #
+    # @example Successful result serialization
+    #   result = ProcessOrderTask.call(order_id: 123).result
+    #   ResultSerializer.call(result)
+    #   # => {
+    #   #   class: "ProcessOrderTask",
+    #   #   type: "Task",
+    #   #   index: 0,
+    #   #   chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   tags: [],
+    #   #   state: "complete",
+    #   #   status: "success",
+    #   #   outcome: "success",
+    #   #   metadata: {},
+    #   #   runtime: 0.5
+    #   # }
+    #
+    # @example Failed result with metadata
+    #   task = ProcessOrderTask.new
+    #   task.fail!(reason: "Validation failed", errors: ["Invalid email"])
+    #   result = task.result
+    #
+    #   ResultSerializer.call(result)
+    #   # => {
+    #   #   class: "ProcessOrderTask",
+    #   #   type: "Task",
+    #   #   index: 0,
+    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   state: "interrupted",
+    #   #   status: "failed",
+    #   #   outcome: "failed",
+    #   #   metadata: { reason: "Validation failed", errors: ["Invalid email"] },
+    #   #   runtime: 0.1
+    #   # }
+    #
+    # @example Skipped result serialization
+    #   task = ProcessOrderTask.new
+    #   task.skip!(reason: "Order already processed")
+    #   result = task.result
+    #
+    #   ResultSerializer.call(result)
+    #   # => {
+    #   #   class: "ProcessOrderTask",
+    #   #   type: "Task",
+    #   #   index: 0,
+    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    #   #   state: "interrupted",
+    #   #   status: "skipped",
+    #   #   outcome: "skipped",
+    #   #   metadata: { reason: "Order already processed" },
+    #   #   runtime: 0.05
+    #   # }
     def call(result)
       TaskSerializer.call(result.task).tap do |hash|
         hash.merge!(