cmdx 1.8.0 → 1.9.1

data/lib/cmdx/result.rb

@@ -11,18 +11,22 @@ module CMDx
 
     extend Forwardable
 
+    # @rbs STATES: Array[String]
     STATES = [
       INITIALIZED = "initialized",  # Initial state before execution
       EXECUTING = "executing",      # Currently executing task logic
       COMPLETE = "complete",        # Successfully completed execution
       INTERRUPTED = "interrupted"   # Execution was halted due to failure
     ].freeze
+
+    # @rbs STATUSES: Array[String]
     STATUSES = [
       SUCCESS = "success",  # Task completed successfully
       SKIPPED = "skipped",  # Task was skipped intentionally
       FAILED = "failed"     # Task failed due to error or validation
     ].freeze
 
+    # @rbs STRIP_FAILURE: Proc
     STRIP_FAILURE = proc do |hash, result, key|
       unless result.send(:"#{key}?")
         # Strip caused/threw failures since its the same info as the log line
@@ -31,7 +35,65 @@ module CMDx
     end.freeze
     private_constant :STRIP_FAILURE
 
-    attr_reader :task, :state, :status, :metadata, :reason, :cause
+    # Returns the task instance associated with this result.
+    #
+    # @return [CMDx::Task] The task instance
+    #
+    # @example
+    #   result.task.id # => "users/create"
+    #
+    # @rbs @task: Task
+    attr_reader :task
+
+    # Returns the current execution state of the result.
+    #
+    # @return [String] One of: "initialized", "executing", "complete", "interrupted"
+    #
+    # @example
+    #   result.state # => "complete"
+    #
+    # @rbs @state: String
+    attr_reader :state
+
+    # Returns the execution status of the result.
+    #
+    # @return [String] One of: "success", "skipped", "failed"
+    #
+    # @example
+    #   result.status # => "success"
+    #
+    # @rbs @status: String
+    attr_reader :status
+
+    # Returns additional metadata about the result.
+    #
+    # @return [Hash{Symbol => Object}] Metadata hash
+    #
+    # @example
+    #   result.metadata # => { duration: 1.5, retries: 2 }
+    #
+    # @rbs @metadata: Hash[Symbol, untyped]
+    attr_reader :metadata
+
+    # Returns the reason for interruption (skip or failure).
+    #
+    # @return [String, nil] The reason message, or nil if not interrupted
+    #
+    # @example
+    #   result.reason # => "Validation failed"
+    #
+    # @rbs @reason: (String | nil)
+    attr_reader :reason
+
+    # Returns the exception that caused the interruption.
+    #
+    # @return [Exception, nil] The causing exception, or nil if not interrupted
+    #
+    # @example
+    #   result.cause # => #<StandardError: Connection timeout>
+    #
+    # @rbs @cause: (Exception | nil)
+    attr_reader :cause
 
     def_delegators :task, :context, :chain, :errors
     alias ctx context
@@ -45,6 +107,8 @@ module CMDx
     # @example
     #   result = CMDx::Result.new(my_task)
     #   result.state # => "initialized"
+    #
+    # @rbs (Task) -> void
     def initialize(task)
       raise TypeError, "must be a CMDx::Task" unless task.is_a?(CMDx::Task)
 
@@ -62,6 +126,8 @@ module CMDx
       # @example
       #   result.initialized? # => true
       #   result.executing?   # => false
+      #
+      # @rbs () -> bool
       define_method(:"#{s}?") { state == s }
 
       # @param block [Proc] Block to execute conditionally
@@ -75,6 +141,8 @@ module CMDx
       # @example
       #   result.handle_initialized { |r| puts "Starting execution" }
       #   result.handle_complete { |r| puts "Task completed" }
+      #
+      # @rbs () { (Result) -> void } -> self
       define_method(:"handle_#{s}") do |&block|
         raise ArgumentError, "block required" unless block
 
@@ -87,6 +155,8 @@ module CMDx
     #
     # @example
     #   result.executed! # Transitions to complete or interrupted
+    #
+    # @rbs () -> self
     def executed!
       success? ? complete! : interrupt!
     end
@@ -95,6 +165,8 @@ module CMDx
     #
     # @example
     #   result.executed? # => true if complete? || interrupted?
+    #
+    # @rbs () -> bool
     def executed?
       complete? || interrupted?
     end
@@ -109,6 +181,8 @@ module CMDx
     #
     # @example
     #   result.handle_executed { |r| puts "Task finished: #{r.outcome}" }
+    #
+    # @rbs () { (Result) -> void } -> self
     def handle_executed(&)
       raise ArgumentError, "block required" unless block_given?
 
@@ -120,6 +194,8 @@ module CMDx
     #
     # @example
     #   result.executing! # Transitions from initialized to executing
+    #
+    # @rbs () -> void
     def executing!
       return if executing?
 
@@ -132,6 +208,8 @@ module CMDx
     #
     # @example
     #   result.complete! # Transitions from executing to complete
+    #
+    # @rbs () -> void
     def complete!
       return if complete?
 
@@ -144,6 +222,8 @@ module CMDx
     #
     # @example
     #   result.interrupt! # Transitions from executing to interrupted
+    #
+    # @rbs () -> void
     def interrupt!
       return if interrupted?
 
@@ -158,6 +238,8 @@ module CMDx
       # @example
       #   result.success? # => true
       #   result.failed?  # => false
+      #
+      # @rbs () -> bool
       define_method(:"#{s}?") { status == s }
 
       # @param block [Proc] Block to execute conditionally
@@ -171,6 +253,8 @@ module CMDx
       # @example
       #   result.handle_success { |r| puts "Task succeeded" }
       #   result.handle_failed { |r| puts "Task failed: #{r.reason}" }
+      #
+      # @rbs () { (Result) -> void } -> self
       define_method(:"handle_#{s}") do |&block|
         raise ArgumentError, "block required" unless block
 
@@ -183,6 +267,8 @@ module CMDx
     #
     # @example
     #   result.good? # => true if !failed?
+    #
+    # @rbs () -> bool
     def good?
       !failed?
     end
@@ -198,6 +284,8 @@ module CMDx
     #
     # @example
     #   result.handle_good { |r| puts "Task completed successfully" }
+    #
+    # @rbs () { (Result) -> void } -> self
     def handle_good(&)
       raise ArgumentError, "block required" unless block_given?
 
@@ -209,6 +297,8 @@ module CMDx
     #
     # @example
     #   result.bad? # => true if !success?
+    #
+    # @rbs () -> bool
     def bad?
       !success?
     end
@@ -223,6 +313,8 @@ module CMDx
     #
     # @example
     #   result.handle_bad { |r| puts "Task had issues: #{r.reason}" }
+    #
+    # @rbs () { (Result) -> void } -> self
     def handle_bad(&)
       raise ArgumentError, "block required" unless block_given?
 
@@ -240,6 +332,8 @@ module CMDx
     # @example
     #   result.skip!("Dependencies not met", cause: dependency_error)
     #   result.skip!("Already processed", halt: false)
+    #
+    # @rbs (?String? reason, halt: bool, cause: Exception?, **untyped metadata) -> void
     def skip!(reason = nil, halt: true, cause: nil, **metadata)
       return if skipped?
 
@@ -264,6 +358,8 @@ module CMDx
     # @example
     #   result.fail!("Validation failed", cause: validation_error)
     #   result.fail!("Network timeout", halt: false, timeout: 30)
+    #
+    # @rbs (?String? reason, halt: bool, cause: Exception?, **untyped metadata) -> void
     def fail!(reason = nil, halt: true, cause: nil, **metadata)
       return if failed?
 
@@ -283,6 +379,8 @@ module CMDx
     #
     # @example
     #   result.halt! # Raises appropriate fault based on status
+    #
+    # @rbs () -> void
     def halt!
       return if success?
 
@@ -291,7 +389,16 @@ module CMDx
 
       # Strip the first two frames (this method and the delegator)
       frames = caller_locations(3..-1)
-      fault.set_backtrace(frames.map(&:to_s)) unless frames.empty?
+
+      unless frames.empty?
+        frames = frames.map(&:to_s)
+
+        if (cleaner = task.class.settings[:backtrace_cleaner])
+          cleaner.call(frames)
+        end
+
+        fault.set_backtrace(frames)
+      end
 
       raise(fault)
     end
@@ -306,6 +413,8 @@ module CMDx
     # @example
     #   other_result = OtherTask.execute
     #   result.throw!(other_result, cause: upstream_error)
+    #
+    # @rbs (Result result, halt: bool, cause: Exception?, **untyped metadata) -> void
     def throw!(result, halt: true, cause: nil, **metadata)
       raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)
 
@@ -323,6 +432,8 @@ module CMDx
     # @example
     #   cause = result.caused_failure
     #   puts "Caused by: #{cause.task.id}" if cause
+    #
+    # @rbs () -> Result?
     def caused_failure
       return unless failed?
 
@@ -335,6 +446,8 @@ module CMDx
     #   if result.caused_failure?
     #     puts "This task caused the failure"
     #   end
+    #
+    # @rbs () -> bool
     def caused_failure?
       return false unless failed?
 
@@ -346,6 +459,8 @@ module CMDx
     # @example
     #   thrown = result.threw_failure
     #   puts "Thrown by: #{thrown.task.id}" if thrown
+    #
+    # @rbs () -> Result?
     def threw_failure
       return unless failed?
 
@@ -360,6 +475,8 @@ module CMDx
     #   if result.threw_failure?
     #     puts "This task threw the failure"
     #   end
+    #
+    # @rbs () -> bool
     def threw_failure?
       return false unless failed?
 
@@ -372,6 +489,8 @@ module CMDx
     #   if result.thrown_failure?
     #     puts "This failure was thrown from another task"
     #   end
+    #
+    # @rbs () -> bool
     def thrown_failure?
       failed? && !caused_failure?
     end
@@ -381,6 +500,8 @@ module CMDx
     # @example
     #   position = result.index
     #   puts "Task #{position + 1} of #{chain.results.count}"
+    #
+    # @rbs () -> Integer
     def index
       chain.index(self)
     end
@@ -389,6 +510,8 @@ module CMDx
     #
     # @example
     #   result.outcome # => "success" or "interrupted"
+    #
+    # @rbs () -> String
     def outcome
       initialized? || thrown_failure? ? state : status
     end
@@ -398,6 +521,8 @@ module CMDx
     # @example
     #   result.to_h
     #   # => {state: "complete", status: "success", outcome: "success", metadata: {}}
+    #
+    # @rbs () -> Hash[Symbol, untyped]
     def to_h
       task.to_h.merge!(
         state:,
@@ -421,6 +546,8 @@ module CMDx
     #
     # @example
     #   result.to_s # => "task_id=my_task state=complete status=success"
+    #
+    # @rbs () -> String
     def to_s
       Utils::Format.to_str(to_h) do |key, value|
         case key
@@ -437,6 +564,8 @@ module CMDx
     # @example
     #   state, status = result.deconstruct
     #   puts "State: #{state}, Status: #{status}"
+    #
+    # @rbs (*untyped) -> Array[untyped]
     def deconstruct(*)
       [state, status, reason, cause, metadata]
     end
@@ -452,6 +581,8 @@ module CMDx
     #   in {bad: true}
     #     puts "Task had issues"
     #   end
+    #
+    # @rbs (*untyped) -> Hash[Symbol, untyped]
     def deconstruct_keys(*)
       {
         state: state,

data/lib/cmdx/task.rb

@@ -8,10 +8,68 @@ module CMDx
 
     extend Forwardable
 
-    attr_reader :attributes, :errors, :id, :context, :result, :chain
+    # Returns the hash of processed attribute values for this task.
+    #
+    # @return [Hash{Symbol => Object}] Hash of attribute names to their values
+    #
+    # @example
+    #   task.attributes # => { user_id: 42, user_name: "John" }
+    #
+    # @rbs @attributes: Hash[Symbol, untyped]
+    attr_reader :attributes
+
+    # Returns the collection of validation and execution errors.
+    #
+    # @return [Errors] The errors collection
+    #
+    # @example
+    #   task.errors.to_h # => { email: ["must be valid"] }
+    #
+    # @rbs @errors: Errors
+    attr_reader :errors
+
+    # Returns the unique identifier for this task instance.
+    #
+    # @return [String] The task identifier
+    #
+    # @example
+    #   task.id # => "abc123xyz"
+    #
+    # @rbs @id: String
+    attr_reader :id
+
+    # Returns the execution context for this task.
+    #
+    # @return [Context] The context instance
+    #
+    # @example
+    #   task.context[:user_id] # => 42
+    #
+    # @rbs @context: Context
+    attr_reader :context
     alias ctx context
+
+    # Returns the execution result for this task.
+    #
+    # @return [Result] The result instance
+    #
+    # @example
+    #   task.result.status # => "success"
+    #
+    # @rbs @result: Result
+    attr_reader :result
     alias res result
 
+    # Returns the execution chain containing all task results.
+    #
+    # @return [Chain] The chain instance
+    #
+    # @example
+    #   task.chain.results.size # => 3
+    #
+    # @rbs @chain: Chain
+    attr_reader :chain
+
     def_delegators :result, :skip!, :fail!, :throw!
 
     # @param context [Hash, Context] The initial context for the task
@@ -25,6 +83,8 @@ module CMDx
     # @example
     #   task = MyTask.new(name: "example", priority: :high)
     #   task = MyTask.new(Context.build(name: "example"))
+    #
+    # @rbs (untyped context) -> void
     def initialize(context = {})
       Deprecator.restrict(self)
 
@@ -40,9 +100,6 @@ module CMDx
     class << self
 
       # @param options [Hash] Configuration options to merge with existing settings
-      # @option options [AttributeRegistry] :attributes Registry for task attributes
-      # @option options [Boolean] :deprecate Whether the task is deprecated
-      # @option options [Array<Symbol>] :tags Tags associated with the task
       #
       # @return [Hash] The merged settings hash
       #
@@ -50,17 +107,27 @@ module CMDx
       #   class MyTask < Task
       #     settings deprecate: true, tags: [:experimental]
       #   end
+      #
+      # @rbs (**untyped options) -> Hash[Symbol, untyped]
       def settings(**options)
         @settings ||= begin
           hash =
             if superclass.respond_to?(:settings)
-              superclass.settings
+              parent = superclass.settings
+              parent
+                .except(:backtrace_cleaner, :exception_handler, :logger, :deprecate)
+                .transform_values!(&:dup)
+                .merge!(
+                  backtrace_cleaner: parent[:backtrace_cleaner] || CMDx.configuration.backtrace_cleaner,
+                  exception_handler: parent[:exception_handler] || CMDx.configuration.exception_handler,
+                  logger: parent[:logger] || CMDx.configuration.logger,
+                  deprecate: parent[:deprecate]
+                )
             else
-              CMDx.configuration.to_h.except(:logger)
-            end.transform_values(&:dup)
+              CMDx.configuration.to_h
+            end
 
           hash[:attributes] ||= AttributeRegistry.new
-          hash[:deprecate] ||= false
           hash[:tags] ||= []
 
           hash.merge!(options)
@@ -76,6 +143,8 @@ module CMDx
       # @example
       #   register(:attribute, MyAttribute.new)
       #   register(:callback, :before, -> { puts "before" })
+      #
+      # @rbs (Symbol type, untyped object, *untyped) -> void
       def register(type, object, ...)
         case type
         when :attribute then settings[:attributes].register(object, ...)
@@ -96,6 +165,8 @@ module CMDx
       # @example
       #   deregister(:attribute, :name)
       #   deregister(:callback, :before, MyCallback)
+      #
+      # @rbs (Symbol type, untyped object, *untyped) -> void
       def deregister(type, object, ...)
         case type
         when :attribute then settings[:attributes].deregister(object, ...)
@@ -112,6 +183,8 @@ module CMDx
       # @example
       #   attributes :name, :email
       #   attributes :age, type: Integer, default: 18
+      #
+      # @rbs (*untyped) -> void
       def attributes(...)
         register(:attribute, Attribute.build(...))
       end
@@ -122,6 +195,8 @@ module CMDx
       # @example
       #   optional :description, :notes
       #   optional :priority, type: Symbol, default: :normal
+      #
+      # @rbs (*untyped) -> void
       def optional(...)
         register(:attribute, Attribute.optional(...))
       end
@@ -131,6 +206,8 @@ module CMDx
       # @example
       #   required :name, :email
       #   required :age, type: Integer, min: 0
+      #
+      # @rbs (*untyped) -> void
       def required(...)
         register(:attribute, Attribute.required(...))
       end
@@ -139,6 +216,8 @@ module CMDx
       #
       # @example
       #   remove_attributes :old_field, :deprecated_field
+      #
+      # @rbs (*Symbol names) -> void
       def remove_attributes(*names)
         deregister(:attribute, names)
       end
@@ -155,6 +234,8 @@ module CMDx
         #   before { puts "before execution" }
         #   after :cleanup, priority: :high
         #   around ->(task) { task.logger.info("starting") }
+        #
+        # @rbs (*untyped callables, **untyped options) ?{ () -> void } -> void
         define_method(callback) do |*callables, **options, &block|
           register(:callback, callback, *callables, **options, &block)
         end
@@ -169,6 +250,8 @@ module CMDx
       #   if result.success?
       #     puts "Task completed successfully"
       #   end
+      #
+      # @rbs (*untyped args, **untyped kwargs) ?{ (Result) -> void } -> Result
       def execute(*args, **kwargs)
         task = new(*args, **kwargs)
         task.execute(raise: false)
@@ -184,6 +267,8 @@ module CMDx
       # @example
       #   result = MyTask.execute!(name: "example")
       #   # Will raise an exception if execution fails
+      #
+      # @rbs (*untyped args, **untyped kwargs) ?{ (Result) -> void } -> Result
       def execute!(*args, **kwargs)
         task = new(*args, **kwargs)
         task.execute(raise: true)
@@ -199,6 +284,8 @@ module CMDx
     # @example
     #   result = task.execute
     #   result = task.execute(raise: true)
+    #
+    # @rbs (raise: bool) ?{ (Result) -> void } -> Result
     def execute(raise: false)
       Executor.execute(self, raise:)
       block_given? ? yield(result) : result
@@ -213,6 +300,8 @@ module CMDx
     #       puts "Performing work..."
     #     end
     #   end
+    #
+    # @rbs () -> void
     def work
       raise UndefinedMethodError, "undefined method #{self.class.name}#work"
     end
@@ -222,6 +311,8 @@ module CMDx
     # @example
     #   logger.info "Starting task execution"
     #   logger.error "Task failed", error: exception
+    #
+    # @rbs () -> Logger
     def logger
       @logger ||= begin
         logger = self.class.settings[:logger] || CMDx.configuration.logger
@@ -244,6 +335,8 @@ module CMDx
     #   task_hash = task.to_h
     #   puts "Task type: #{task_hash[:type]}"
     #   puts "Task tags: #{task_hash[:tags].join(', ')}"
+    #
+    # @rbs () -> Hash[Symbol, untyped]
     def to_h
       {
         index: result.index,
@@ -260,6 +353,8 @@ module CMDx
     # @example
     #   puts task.to_s
     #   # Output: "Task[MyTask] tags: [:important] id: abc123"
+    #
+    # @rbs () -> String
     def to_s
       Utils::Format.to_str(to_h)
     end

data/lib/cmdx/utils/call.rb

@@ -32,6 +32,8 @@ module CMDx
       # @example Invoking a callable object
       #   callable = MyCallable.new
       #   Call.invoke(user, callable, 'data')
+      #
+      # @rbs (untyped target, (Symbol | Proc | untyped) callable, *untyped args, **untyped kwargs) ?{ () -> untyped } -> untyped
       def invoke(target, callable, *args, **kwargs, &)
         if callable.is_a?(Symbol)
           target.send(callable, *args, **kwargs, &)

data/lib/cmdx/utils/condition.rb

@@ -11,6 +11,7 @@ module CMDx
 
       extend self
 
+      # @rbs EVAL: Proc
       EVAL = proc do |target, callable, *args, **kwargs, &block|
         case callable
         when NilClass, FalseClass, TrueClass then !!callable
@@ -53,6 +54,8 @@ module CMDx
       # @example With arguments and block
       #   Condition.evaluate(user, if: ->(u) { u.has_permission?(:admin) }, :admin)
       #   # => true if the proc returns true when called with user and :admin
+      #
+      # @rbs (untyped target, Hash[Symbol, untyped] options, *untyped) ?{ () -> untyped } -> bool
       def evaluate(target, options, ...)
         case options
         in if: if_cond, unless: unless_cond

data/lib/cmdx/utils/format.rb

@@ -8,6 +8,7 @@ module CMDx
 
       extend self
 
+      # @rbs FORMATTER: Proc
       FORMATTER = proc do |key, value|
         "#{key}=#{value.inspect}"
       end.freeze
@@ -28,6 +29,8 @@ module CMDx
       # @example CMDx object
       #   Format.to_log(CMDx::Task.new(name: "task1"))
       #   # => {name: "task1"}
+      #
+      # @rbs (untyped message) -> untyped
       def to_log(message)
         if message.respond_to?(:to_h) && message.class.ancestors.any? { |a| a.to_s.start_with?("CMDx") }
           message.to_h
@@ -51,6 +54,8 @@ module CMDx
       # @example Custom formatter
       #   Format.to_str({count: 5, total: 100}) { |k, v| "#{k}:#{v}" }
       #   # => "count:5 total:100"
+      #
+      # @rbs (Hash[untyped, untyped] hash) ?{ (untyped, untyped) -> String } -> String
       def to_str(hash, &block)
         block ||= FORMATTER
         hash.map(&block).join(" ")