cmdx 0.5.0 → 1.0.1

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!(