cmdx 1.0.1 → 1.1.1

data/lib/cmdx/result_ansi.rb

@@ -1,47 +1,20 @@
 # frozen_string_literal: true
 
 module CMDx
-  # ANSI color formatting module for result states and statuses.
+  # ANSI color formatting utilities 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
+  # This module provides functionality to apply appropriate ANSI colors to
+  # result states and statuses for enhanced terminal output visibility.
+  # It maps different execution states and statuses to their corresponding
+  # colors and delegates the actual color application to the AnsiColor utility.
   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,     # 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,        # Successful completion - green
       Result::SKIPPED => :yellow,       # Intentionally skipped - yellow
@@ -52,69 +25,44 @@ module CMDx
 
     # 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.
+    # Takes a result state or status string and applies the appropriate ANSI
+    # color formatting using the predefined color mappings. This provides
+    # visual distinction for different execution outcomes in terminal output.
     #
-    # @param s [String] The state or status string to colorize
-    # @return [String] The string with ANSI color codes applied
+    # @param s [String] the result state or status string to colorize
     #
-    # @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)
+    # @return [String] the input string with ANSI color codes applied
     #
-    # @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 Colorize a success status
+    #   ResultAnsi.call("success") #=> "\e[0;32;49msuccess\e[0m" (green)
     #
-    # @example Unknown value
-    #   ResultAnsi.call("unknown")      # => "\e[39munknown\e[0m" (default color)
+    # @example Colorize a failed status
+    #   ResultAnsi.call("failed") #=> "\e[0;31;49mfailed\e[0m" (red)
     #
-    # @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)
+    # @example Colorize an executing state
+    #   ResultAnsi.call("executing") #=> "\e[0;33;49mexecuting\e[0m" (yellow)
     def call(s)
       Utils::AnsiColor.call(s, color: color(s))
     end
 
-    # 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.
+    # Determines the appropriate color for a result state or status.
     #
-    # @param s [String] The state or status string to determine color for
-    # @return [Symbol] The color symbol for the state or status
+    # Looks up the color mapping for the given state or status string,
+    # returning the corresponding color symbol or :default if no specific
+    # mapping is found.
     #
-    # @example Result state color mapping
-    #   color("initialized")  # => :blue
-    #   color("executing")    # => :yellow
-    #   color("complete")     # => :green
-    #   color("interrupted")  # => :red
+    # @param s [String] the result state or status string to find color for
     #
-    # @example Result status color mapping
-    #   color("success")      # => :green
-    #   color("skipped")      # => :yellow
-    #   color("failed")       # => :red
+    # @return [Symbol] the color symbol (:blue, :yellow, :green, :red, or :default)
     #
-    # @example Unknown state or status
-    #   color("unknown")      # => :default
-    #   color("pending")      # => :default
+    # @example Get color for success status
+    #   ResultAnsi.color("success") #=> :green
     #
-    # @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
+    # @example Get color for unknown value
+    #   ResultAnsi.color("unknown") #=> :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
+    # @example Get color for executing state
+    #   ResultAnsi.color("executing") #=> :yellow
     def color(s)
       STATE_COLORS[s] || STATUS_COLORS[s] || :default
     end

data/lib/cmdx/result_inspector.rb

@@ -1,53 +1,14 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Result inspection utility for generating human-readable result descriptions.
+  # Result inspection and formatting utilities for readable result representation.
   #
-  # 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
+  # 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 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
@@ -55,37 +16,40 @@ 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.
+    # Formats a result hash into a human-readable string representation.
     #
-    # @param result [Hash] The result hash to inspect
-    # @return [String] Formatted result description
+    # 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.
     #
-    # @example Simple result inspection
-    #   ResultInspector.call(result_hash)
-    #   # => "ProcessOrderTask: type=Task index=0 id=018c2b95... state=complete status=success"
+    # @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
     #
-    # @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}"
+    # @return [String] a formatted string representation of the result with key information
     #
-    # @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 Format a successful task result
+    #   result = MyTask.call
+    #   ResultInspector.call(result)
+    #   #=> "MyTask: type=Task index=0 id=abc123 state=executed status=success outcome=good"
     #
-    # @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"
+    # @example Format a result with failure reference
+    #   result = MyTask.call
+    #   ResultInspector.call(result)
+    #   #=> "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

@@ -1,47 +1,15 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Result-specific logging module for task execution outcomes.
+  # Logger utilities for task execution results.
   #
-  # 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
+  # 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
 
-    # 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,   # Successful task completion
       Result::SKIPPED => :warn,   # Task was skipped
@@ -50,54 +18,32 @@ module CMDx
 
     module_function
 
-    # Logs a task result at the appropriate severity level.
+    # Logs a task execution result with 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.
+    # 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 [CMDx::Result] the task execution result to log
     #
-    # @param result [CMDx::Result] The task result to log
     # @return [void]
     #
-    # @example Logging a successful result
-    #   task = ProcessOrderTask.call(order_id: 123)
+    # @example Log a successful task result
+    #   task = ProcessDataTask.call(data: "input")
     #   ResultLogger.call(task.result)
-    #   # Logs at INFO level with result details
+    #   # Logs at :info level: "Result: ProcessDataTask completed successfully"
     #
-    # @example Logging a failed result
-    #   task = ProcessOrderTask.new
-    #   task.fail!(reason: "Invalid order ID")
+    # @example Log a failed task result
+    #   task = ValidateDataTask.call(data: "invalid")
     #   ResultLogger.call(task.result)
-    #   # Logs at ERROR level with failure details
+    #   # Logs at :error level: "Result: ValidateDataTask failed with error"
     #
-    # @example Logging a skipped result
-    #   task = ProcessOrderTask.new
-    #   task.skip!(reason: "Order already processed")
+    # @example Log a skipped task result
+    #   task = ConditionalTask.call(condition: false)
     #   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.
+    #   # 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,84 +1,18 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Result serialization utility for converting Result objects to hash representations.
+  # Result serialization module for converting result objects to hash format.
   #
-  # 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
+  # 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
 
-    # 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.
+    # 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
@@ -88,66 +22,66 @@ module CMDx
 
     module_function
 
-    # Converts a Result object to a hash representation.
+    # Serializes a result object into 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.
+    # 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] Structured hash representation of the result
+    # @param result [CMDx::Result] the result object to serialize
     #
-    # @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
-    #   # }
+    # @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)
     #
-    # @example Failed result with metadata
-    #   task = ProcessOrderTask.new
-    #   task.fail!(reason: "Validation failed", errors: ["Invalid email"])
-    #   result = task.result
+    # @raise [NoMethodError] if the result doesn't respond to required methods
     #
+    # @example Serialize a successful result
+    #   task = SuccessfulTask.new(data: "test")
     #   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
+    #   #   chain_id: "abc123",
+    #   #   type: "Task",
+    #   #   class: "SuccessfulTask",
+    #   #   id: "def456",
+    #   #   tags: [],
+    #   #   state: :complete,
+    #   #   status: :success,
+    #   #   outcome: :good,
+    #   #   metadata: {},
+    #   #   runtime: 0.045
     #   # }
     #
-    # @example Skipped result serialization
-    #   task = ProcessOrderTask.new
-    #   task.skip!(reason: "Order already processed")
-    #   result = task.result
-    #
-    #   ResultSerializer.call(result)
-    #   # => {
-    #   #   class: "ProcessOrderTask",
+    # @example Serialize a failed result with failure stripping
+    #   task = FailingTask.call
+    #   ResultSerializer.call(task.result)
+    #   #=> {
+    #   #   index: 1,
+    #   #   chain_id: "xyz789",
     #   #   type: "Task",
-    #   #   index: 0,
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   state: "interrupted",
-    #   #   status: "skipped",
-    #   #   outcome: "skipped",
-    #   #   metadata: { reason: "Order already processed" },
-    #   #   runtime: 0.05
+    #   #   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|

data/lib/cmdx/rspec/matchers.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Result matchers
+require_relative "result_matchers/be_successful_task"
+require_relative "result_matchers/be_failed_task"
+require_relative "result_matchers/be_skipped_task"
+require_relative "result_matchers/be_executed"
+require_relative "result_matchers/be_state_matchers"
+require_relative "result_matchers/be_status_matchers"
+require_relative "result_matchers/have_good_outcome"
+require_relative "result_matchers/have_bad_outcome"
+require_relative "result_matchers/have_runtime"
+require_relative "result_matchers/have_metadata"
+require_relative "result_matchers/have_empty_metadata"
+require_relative "result_matchers/have_context"
+require_relative "result_matchers/have_preserved_context"
+require_relative "result_matchers/have_caused_failure"
+require_relative "result_matchers/have_thrown_failure"
+require_relative "result_matchers/have_received_thrown_failure"
+require_relative "result_matchers/have_chain_index"
+
+# Task matchers
+require_relative "task_matchers/be_well_formed_task"
+require_relative "task_matchers/have_cmd_setting"
+require_relative "task_matchers/have_middleware"
+require_relative "task_matchers/have_callback"
+require_relative "task_matchers/have_parameter"
+require_relative "task_matchers/have_executed_callbacks"