cmdx 1.1.0 → 1.1.1

data/lib/cmdx/result_inspector.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Provides formatted inspection functionality for task execution results.
+  # Result inspection and formatting utilities for readable result representation.
   #
-  # This module formats result hash data into a human-readable string representation
-  # with ordered key-value pairs. It handles special formatting for specific keys
-  # like failure references and applies consistent ordering to result attributes.
+  # This module provides functionality to format result metadata into human-readable
+  # strings for debugging, logging, and introspection purposes. It processes result
+  # hashes and displays essential result information in a structured, ordered format
+  # that emphasizes the most important attributes first.
   module ResultInspector
 
     ORDERED_KEYS = %i[
@@ -15,36 +16,40 @@ module CMDx
 
     module_function
 
-    # Formats a result hash into a human-readable inspection string.
+    # Formats a result hash into a human-readable string representation.
     #
-    # Creates a formatted string representation of a result hash with ordered
-    # key-value pairs. Special keys like :class, :caused_failure, and :threw_failure
-    # receive custom formatting for better readability and debugging.
+    # This method converts result metadata into a structured string format that
+    # displays key result information in a predefined order. It handles special
+    # formatting for class names, failure references, and standard key-value pairs.
+    # The method filters the result hash to only include keys defined in ORDERED_KEYS
+    # and applies appropriate formatting based on the key type.
     #
-    # @param result [Hash] the result hash to format and inspect
+    # @param result [Hash] the result hash to format
+    # @option result [String] :class the class name of the task or workflow
+    # @option result [String] :type the type identifier (e.g., "Task", "Workflow")
+    # @option result [Integer] :index the position index in the execution chain
+    # @option result [String] :id the unique identifier of the result
+    # @option result [String] :state the execution state (e.g., "executed", "skipped")
+    # @option result [String] :status the execution status (e.g., "success", "failure")
+    # @option result [String] :outcome the overall outcome (e.g., "good", "bad")
+    # @option result [Hash] :metadata additional metadata associated with the result
+    # @option result [Array] :tags the tags associated with the result
+    # @option result [Integer] :pid the process ID if applicable
+    # @option result [Float] :runtime the execution runtime in seconds
+    # @option result [Hash] :caused_failure reference to a failure this result caused
+    # @option result [Hash] :threw_failure reference to a failure this result threw
     #
-    # @return [String] formatted string with space-separated key-value pairs
+    # @return [String] a formatted string representation of the result with key information
     #
-    # @raise [NoMethodError] if result doesn't respond to key? or []
-    #
-    # @example Formatting a basic result
-    #   result = { class: "MyTask", state: "complete", status: "success" }
-    #   ResultInspector.call(result)
-    #   # => "MyTask: state=complete status=success"
-    #
-    # @example Formatting result with failure information
-    #   result = {
-    #     class: "ProcessTask",
-    #     state: "interrupted",
-    #     caused_failure: { index: 2, class: "ValidationError", id: "val_123" }
-    #   }
+    # @example Format a successful task result
+    #   result = MyTask.call
     #   ResultInspector.call(result)
-    #   # => "ProcessTask: state=interrupted caused_failure=<[2] ValidationError: val_123>"
+    #   #=> "MyTask: type=Task index=0 id=abc123 state=executed status=success outcome=good"
     #
-    # @example Formatting empty or minimal result
-    #   result = { id: "task_456" }
+    # @example Format a result with failure reference
+    #   result = MyTask.call
     #   ResultInspector.call(result)
-    #   # => "id=task_456"
+    #   #=> "MyTask: index=1 state=executed status=failure caused_failure=<[2] ValidationError: def456>"
     def call(result)
       ORDERED_KEYS.filter_map do |key|
         next unless result.key?(key)

data/lib/cmdx/result_logger.rb

@@ -3,9 +3,11 @@
 module CMDx
   # Logger utilities for task execution results.
   #
-  # This module provides functionality to log task execution results with appropriate
-  # severity levels based on the result status. It automatically maps result statuses
-  # to corresponding log levels and delegates to the task's configured logger.
+  # This module provides functionality to log task execution results with
+  # appropriate severity levels based on the result status. It automatically
+  # determines the correct log level (info, warn, error) based on whether
+  # the task succeeded, was skipped, or failed, and delegates to the task's
+  # configured logger instance.
   module ResultLogger
 
     STATUS_TO_SEVERITY = {
@@ -16,25 +18,32 @@ module CMDx
 
     module_function
 
-    # Logs the task execution result with appropriate severity level.
+    # Logs a task execution result with the appropriate severity level.
     #
-    # This method retrieves the logger from the task and logs the result using
-    # the severity level mapped from the result's status. If no logger is configured
-    # for the task, the method returns early without logging.
+    # Retrieves the logger from the task instance and logs the result object
+    # using the severity level determined by the result's status. If no logger
+    # is configured for the task, the method returns early without logging.
+    # The logger level is temporarily set to match the severity to ensure
+    # the message is captured regardless of current log level configuration.
     #
-    # @param result [Result] the task execution result to log
+    # @param result [CMDx::Result] the task execution result to log
     #
     # @return [void]
     #
     # @example Log a successful task result
-    #   result = task.process
-    #   CMDx::ResultLogger.call(result)
-    #   # => logs at info level: "Task completed successfully"
+    #   task = ProcessDataTask.call(data: "input")
+    #   ResultLogger.call(task.result)
+    #   # Logs at :info level: "Result: ProcessDataTask completed successfully"
     #
     # @example Log a failed task result
-    #   result = failing_task.process
-    #   CMDx::ResultLogger.call(result)
-    #   # => logs at error level: "Task failed with error"
+    #   task = ValidateDataTask.call(data: "invalid")
+    #   ResultLogger.call(task.result)
+    #   # Logs at :error level: "Result: ValidateDataTask failed with error"
+    #
+    # @example Log a skipped task result
+    #   task = ConditionalTask.call(condition: false)
+    #   ResultLogger.call(task.result)
+    #   # Logs at :warn level: "Result: ConditionalTask was skipped"
     def call(result)
       logger = result.task.send(:logger)
       return if logger.nil?

data/lib/cmdx/result_serializer.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Provides serialization functionality for CMDx::Result objects,
-  # converting them into structured hash representations suitable for
-  # logging, storage, or transmission.
+  # Result serialization module for converting result objects to hash format.
+  #
+  # This module provides functionality to serialize result objects into a
+  # standardized hash representation that includes essential metadata about
+  # the result such as task information, execution state, status, outcome,
+  # metadata, and runtime. For failed results, it intelligently strips
+  # redundant failure information to avoid duplication in serialized output.
   module ResultSerializer
 
-    # A proc that removes failure-related metadata from the hash representation
-    # when the result hasn't actually failed in the specified way.
-    # This prevents duplicate failure information from appearing in logs.
+    # Proc for stripping failure information from serialized results.
+    # Removes caused_failure and threw_failure keys when the result doesn't
+    # have the corresponding failure state, avoiding redundant information.
     STRIP_FAILURE = proc do |h, r, k|
       unless r.send(:"#{k}?")
         # Strip caused/threw failures since its the same info as the log line
@@ -18,33 +22,67 @@ module CMDx
 
     module_function
 
-    # Converts a Result object into a structured hash representation.
-    # Combines task serialization data with result-specific information
-    # including execution state, status, outcome, metadata, and runtime.
+    # Serializes a result object into a hash representation.
+    #
+    # Converts a result instance into a standardized hash format containing
+    # task metadata and execution information. For failed results, applies
+    # intelligent failure stripping to remove redundant caused_failure and
+    # threw_failure information that would duplicate log output.
     #
     # @param result [CMDx::Result] the result object to serialize
     #
-    # @return [Hash] a structured hash containing task information and result details
-    #   including :state, :status, :outcome, :metadata, :runtime, and optionally
-    #   :caused_failure and :threw_failure if the result failed
+    # @return [Hash] a hash containing the result's metadata and execution information
+    # @option return [Integer] :index the result's position index in the execution chain
+    # @option return [String] :chain_id the unique identifier of the result's execution chain
+    # @option return [String] :type the task type, either "Task" or "Workflow"
+    # @option return [String] :class the full class name of the task
+    # @option return [String] :id the unique identifier of the task instance
+    # @option return [Array] :tags the tags associated with the task from cmd settings
+    # @option return [Symbol] :state the execution state (:executing, :complete, :interrupted)
+    # @option return [Symbol] :status the execution status (:success, :failed, :skipped)
+    # @option return [Symbol] :outcome the execution outcome (:good, :bad)
+    # @option return [Hash] :metadata additional metadata collected during execution
+    # @option return [Float] :runtime the execution runtime in seconds
+    # @option return [Hash] :caused_failure failure information if result caused a failure (stripped for non-failed results)
+    # @option return [Hash] :threw_failure failure information if result threw a failure (stripped for non-failed results)
     #
-    # @raise [NoMethodError] if result doesn't respond to expected methods
-    # @raise [TypeError] if result.task is invalid for TaskSerializer
+    # @raise [NoMethodError] if the result doesn't respond to required methods
     #
-    # @example Serializing a successful result
-    #   result = task.call
-    #   CMDx::ResultSerializer.call(result)
-    #   #=> { index: 0, chain_id: "abc123", type: "Task", class: "MyTask",
-    #   #     id: "def456", tags: [], state: "complete", status: "success",
-    #   #     outcome: "good", metadata: {}, runtime: 0.05 }
+    # @example Serialize a successful result
+    #   task = SuccessfulTask.new(data: "test")
+    #   ResultSerializer.call(result)
+    #   #=> {
+    #   #   index: 0,
+    #   #   chain_id: "abc123",
+    #   #   type: "Task",
+    #   #   class: "SuccessfulTask",
+    #   #   id: "def456",
+    #   #   tags: [],
+    #   #   state: :complete,
+    #   #   status: :success,
+    #   #   outcome: :good,
+    #   #   metadata: {},
+    #   #   runtime: 0.045
+    #   # }
     #
-    # @example Serializing a failed result
-    #   result = task.call
-    #   CMDx::ResultSerializer.call(result)
-    #   #=> { index: 0, chain_id: "abc123", type: "Task", class: "MyTask",
-    #   #     id: "def456", tags: [], state: "interrupted", status: "failed",
-    #   #     outcome: "bad", metadata: { error: "Something went wrong" },
-    #   #     runtime: 0.02, caused_failure: {...}, threw_failure: {...} }
+    # @example Serialize a failed result with failure stripping
+    #   task = FailingTask.call
+    #   ResultSerializer.call(task.result)
+    #   #=> {
+    #   #   index: 1,
+    #   #   chain_id: "xyz789",
+    #   #   type: "Task",
+    #   #   class: "FailingTask",
+    #   #   id: "ghi012",
+    #   #   tags: [],
+    #   #   state: :interrupted,
+    #   #   status: :failed,
+    #   #   outcome: :bad,
+    #   #   metadata: { reason: "Database connection failed" },
+    #   #   runtime: 0.012,
+    #   #   caused_failure: { message: "Task failed", ... },
+    #   #   threw_failure: { message: "Validation error", ... },
+    #   # }
     def call(result)
       TaskSerializer.call(result.task).tap do |hash|
         hash.merge!(