cmdx 1.9.0 → 1.9.1

data/lib/cmdx/executor.rb

@@ -8,6 +8,14 @@ module CMDx
   # and proper error handling for different types of failures.
   class Executor
 
+    # Returns the task being executed.
+    #
+    # @return [Task] The task instance
+    #
+    # @example
+    #   executor.task.id # => "abc123"
+    #
+    # @rbs @task: Task
     attr_reader :task
 
     # @param task [CMDx::Task] The task to execute
@@ -16,6 +24,8 @@ module CMDx
     #
     # @example
     #   executor = CMDx::Executor.new(my_task)
+    #
+    # @rbs (Task task) -> void
     def initialize(task)
       @task = task
     end
@@ -32,6 +42,8 @@ module CMDx
     # @example
     #   CMDx::Executor.execute(my_task)
     #   CMDx::Executor.execute(my_task, raise: true)
+    #
+    # @rbs (Task task, raise: bool) -> Result
     def self.execute(task, raise: false)
       instance = new(task)
       raise ? instance.execute! : instance.execute
@@ -44,6 +56,8 @@ module CMDx
     # @example
     #   executor = CMDx::Executor.new(my_task)
     #   result = executor.execute
+    #
+    # @rbs () -> Result
     def execute
       task.class.settings[:middlewares].call!(task) do
         pre_execution! unless @pre_execution
@@ -73,6 +87,8 @@ module CMDx
     # @example
     #   executor = CMDx::Executor.new(my_task)
     #   result = executor.execute!
+    #
+    # @rbs () -> Result
     def execute!
       task.class.settings[:middlewares].call!(task) do
         pre_execution! unless @pre_execution
@@ -104,6 +120,8 @@ module CMDx
     #
     # @example
     #   halt_execution?(fault_exception)
+    #
+    # @rbs (Exception exception) -> bool
     def halt_execution?(exception)
       breakpoints = task.class.settings[:breakpoints] || task.class.settings[:task_breakpoints]
       breakpoints = Array(breakpoints).map(&:to_s).uniq
@@ -119,6 +137,8 @@ module CMDx
     #
     # @example
     #   retry_execution?(standard_error)
+    #
+    # @rbs (Exception exception) -> bool
     def retry_execution?(exception)
       available_retries = (task.class.settings[:retries] || 0).to_i
       return false unless available_retries.positive?
@@ -151,6 +171,8 @@ module CMDx
     #
     # @example
     #   raise_exception(standard_error)
+    #
+    # @rbs (Exception exception) -> void
     def raise_exception(exception)
       Chain.clear
 
@@ -165,6 +187,8 @@ module CMDx
     #
     # @example
     #   invoke_callbacks(:before_execution)
+    #
+    # @rbs (Symbol type) -> void
     def invoke_callbacks(type)
       task.class.settings[:callbacks].invoke(type, task)
     end
@@ -172,11 +196,15 @@ module CMDx
     private
 
     # Lazy loaded repeator instance to handle retries.
+    #
+    # @rbs () -> untyped
     def repeator
       @repeator ||= Repeator.new(task)
     end
 
     # Performs pre-execution tasks including validation and attribute verification.
+    #
+    # @rbs () -> void
     def pre_execution!
       @pre_execution = true
 
@@ -195,6 +223,8 @@ module CMDx
     end
 
     # Executes the main task logic.
+    #
+    # @rbs () -> void
     def execution!
       invoke_callbacks(:before_execution)
 
@@ -203,6 +233,8 @@ module CMDx
     end
 
     # Performs post-execution tasks including callback invocation.
+    #
+    # @rbs () -> void
     def post_execution!
       invoke_callbacks(:"on_#{task.result.state}")
       invoke_callbacks(:on_executed) if task.result.executed?
@@ -213,6 +245,8 @@ module CMDx
     end
 
     # Finalizes execution by freezing the task and logging results.
+    #
+    # @rbs () -> Result
     def finalize_execution!
       log_execution!
       log_backtrace! if task.class.settings[:backtrace]
@@ -222,11 +256,15 @@ module CMDx
     end
 
     # Logs the execution result at the configured log level.
+    #
+    # @rbs () -> void
     def log_execution!
       task.logger.info { task.result.to_h }
     end
 
     # Logs the backtrace of the exception if the task failed.
+    #
+    # @rbs () -> void
     def log_backtrace!
       return unless task.result.failed?
 
@@ -244,6 +282,8 @@ module CMDx
     end
 
     # Freezes the task and its associated objects to prevent modifications.
+    #
+    # @rbs () -> void
     def freeze_execution!
       # Stubbing on frozen objects is not allowed in most test environments.
       skip_freezing = ENV.fetch("SKIP_CMDX_FREEZING", false)
@@ -260,6 +300,9 @@ module CMDx
       task.chain.freeze
     end
 
+    # Clears the chain if the task is the outermost (top-level) task.
+    #
+    # @rbs () -> void
     def clear_chain!
       return unless task.result.index.zero?
 

data/lib/cmdx/faults.rb

@@ -11,6 +11,14 @@ module CMDx
 
     extend Forwardable
 
+    # Returns the result that caused this fault.
+    #
+    # @return [Result] The result instance
+    #
+    # @example
+    #   fault.result.reason # => "Validation failed"
+    #
+    # @rbs @result: Result
     attr_reader :result
 
     def_delegators :result, :task, :context, :chain
@@ -24,6 +32,8 @@ module CMDx
     # @example
     #   fault = Fault.new(task_result)
     #   fault.result.reason # => "Task validation failed"
+    #
+    # @rbs (Result result) -> void
     def initialize(result)
       @result = result
 
@@ -41,6 +51,8 @@ module CMDx
       # @example
       #   Fault.for?(UserTask, AdminUserTask)
       #   # => true if fault.task is a UserTask or AdminUserTask
+      #
+      # @rbs (*Class tasks) -> Class
       def for?(*tasks)
         temp_fault = Class.new(self) do
           def self.===(other)
@@ -62,6 +74,8 @@ module CMDx
       # @example
       #   Fault.matches? { |fault| fault.result.metadata[:critical] }
       #   # => true if fault has critical metadata
+      #
+      # @rbs () { (Fault) -> bool } -> Class
       def matches?(&block)
         raise ArgumentError, "block required" unless block_given?
 

data/lib/cmdx/identifier.rb

@@ -18,6 +18,8 @@ module CMDx
     # @example Generate a unique identifier
     #   CMDx::Identifier.generate
     #   # => "01890b2c-1234-5678-9abc-def123456789"
+    #
+    # @rbs () -> String
     def generate
       if SecureRandom.respond_to?(:uuid_v7)
         SecureRandom.uuid_v7

data/lib/cmdx/locale.rb

@@ -8,6 +8,7 @@ module CMDx
 
     extend self
 
+    # @rbs EN: Hash[String, untyped]
     EN = YAML.load_file(CMDx.gem_path.join("lib/locales/en.yml")).freeze
     private_constant :EN
 
@@ -34,6 +35,8 @@ module CMDx
     # @example With fallback
     #   Locale.translate("missing.key", default: "Custom fallback message")
     #   # => "Custom fallback message"
+    #
+    # @rbs ((String | Symbol) key, **untyped options) -> String
     def translate(key, **options)
       options[:default] ||= EN.dig("en", *key.to_s.split("."))
       return ::I18n.t(key, **options) if defined?(::I18n)

data/lib/cmdx/log_formatters/json.rb

@@ -21,6 +21,8 @@ module CMDx
       # @example Basic usage
       #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
       #   # => '{"severity":"INFO","timestamp":"2024-01-15T10:30:45.123456Z","progname":"MyApp","pid":12345,"message":"User logged in"}\n'
+      #
+      # @rbs (String severity, Time time, String? progname, String message) -> String
       def call(severity, time, progname, message)
         hash = {
           severity:,

data/lib/cmdx/log_formatters/key_value.rb

@@ -21,6 +21,8 @@ module CMDx
       # @example Basic usage
       #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
       #   # => "severity=INFO timestamp=2024-01-15T10:30:45.123456Z progname=MyApp pid=12345 message=User logged in\n"
+      #
+      # @rbs (String severity, Time time, String? progname, String message) -> String
       def call(severity, time, progname, message)
         hash = {
           severity:,

data/lib/cmdx/log_formatters/line.rb

@@ -21,6 +21,8 @@ module CMDx
       # @example Basic usage
       #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
       #   # => "I, [2024-01-15T10:30:45.123456Z #12345] INFO -- MyApp: User logged in\n"
+      #
+      # @rbs (String severity, Time time, String? progname, String message) -> String
       def call(severity, time, progname, message)
         "#{severity[0]}, [#{time.utc.iso8601(6)} ##{Process.pid}] #{severity} -- #{progname}: #{message}\n"
       end

data/lib/cmdx/log_formatters/logstash.rb

@@ -22,6 +22,8 @@ module CMDx
       # @example Basic usage
       #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
       #   # => '{"severity":"INFO","progname":"MyApp","pid":12345,"message":"User logged in","@version":"1","@timestamp":"2024-01-15T10:30:45.123456Z"}\n'
+      #
+      # @rbs (String severity, Time time, String? progname, String message) -> String
       def call(severity, time, progname, message)
         hash = {
           severity:,

data/lib/cmdx/log_formatters/raw.rb

@@ -22,6 +22,8 @@ module CMDx
       # @example Basic usage
       #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
       #   # => "User logged in\n"
+      #
+      # @rbs (String severity, Time time, String? progname, String message) -> String
       def call(severity, time, progname, message)
         "#{message}\n"
       end

data/lib/cmdx/middleware_registry.rb

@@ -9,6 +9,14 @@ module CMDx
   # they were registered.
   class MiddlewareRegistry
 
+    # Returns the ordered collection of middleware entries.
+    #
+    # @return [Array<Array>] Array of middleware-options pairs
+    #
+    # @example
+    #   registry.registry # => [[LoggingMiddleware, {level: :debug}], [AuthMiddleware, {}]]
+    #
+    # @rbs @registry: Array[Array[untyped]]
     attr_reader :registry
     alias to_a registry
 
@@ -19,6 +27,8 @@ module CMDx
     # @example
     #   registry = MiddlewareRegistry.new
     #   registry = MiddlewareRegistry.new([[MyMiddleware, {option: 'value'}]])
+    #
+    # @rbs (?Array[Array[untyped]] registry) -> void
     def initialize(registry = [])
       @registry = registry
     end
@@ -29,6 +39,8 @@ module CMDx
     #
     # @example
     #   new_registry = registry.dup
+    #
+    # @rbs () -> MiddlewareRegistry
     def dup
       self.class.new(registry.map(&:dup))
     end
@@ -46,6 +58,8 @@ module CMDx
     # @example
     #   registry.register(LoggingMiddleware, at: 0, log_level: :debug)
     #   registry.register(AuthMiddleware, at: -1, timeout: 30)
+    #
+    # @rbs (untyped middleware, ?at: Integer, **untyped options) -> self
     def register(middleware, at: -1, **options)
       registry.insert(at, [middleware, options])
       self
@@ -59,6 +73,8 @@ module CMDx
     #
     # @example
     #   registry.deregister(LoggingMiddleware)
+    #
+    # @rbs (untyped middleware) -> self
     def deregister(middleware)
       registry.reject! { |mw, _opts| mw == middleware }
       self
@@ -79,6 +95,8 @@ module CMDx
     #   result = registry.call!(my_task) do |processed_task|
     #     processed_task.execute
     #   end
+    #
+    # @rbs (untyped task) { (untyped) -> untyped } -> untyped
     def call!(task, &)
       raise ArgumentError, "block required" unless block_given?
 
@@ -96,6 +114,8 @@ module CMDx
     # @yieldparam task [Object] The processed task object
     #
     # @return [Object] Result of the block execution or next middleware call
+    #
+    # @rbs (Integer index, untyped task) { (untyped) -> untyped } -> untyped
     def recursively_call_middleware(index, task, &block)
       return yield(task) if index >= registry.size
 

data/lib/cmdx/middlewares/correlate.rb

@@ -12,6 +12,7 @@ module CMDx
 
       extend self
 
+      # @rbs THREAD_KEY: Symbol
       THREAD_KEY = :cmdx_correlate
 
       # Retrieves the current correlation ID from thread-local storage.
@@ -20,6 +21,8 @@ module CMDx
       #
       # @example Get current correlation ID
       #   Correlate.id # => "550e8400-e29b-41d4-a716-446655440000"
+      #
+      # @rbs () -> String?
       def id
         Thread.current[THREAD_KEY]
       end
@@ -31,6 +34,8 @@ module CMDx
       #
       # @example Set correlation ID
       #   Correlate.id = "abc-123-def"
+      #
+      # @rbs (String id) -> String
       def id=(id)
         Thread.current[THREAD_KEY] = id
       end
@@ -41,6 +46,8 @@ module CMDx
       #
       # @example Clear correlation ID
       #   Correlate.clear
+      #
+      # @rbs () -> nil
       def clear
         Thread.current[THREAD_KEY] = nil
       end
@@ -58,6 +65,8 @@ module CMDx
       #     perform_operation
       #   end
       #   # Previous ID is restored
+      #
+      # @rbs (String new_id) { () -> untyped } -> untyped
       def use(new_id)
         old_id = id
         self.id = new_id
@@ -92,6 +101,8 @@ module CMDx
       #   Correlate.call(task, id: -> { "dynamic-#{Time.now.to_i}" }, &block)
       # @example Conditional correlation
       #   Correlate.call(task, if: :enable_correlation, &block)
+      #
+      # @rbs (Task task, **untyped options) { () -> untyped } -> untyped
       def call(task, **options, &)
         return yield unless Utils::Condition.evaluate(task, options)
 

data/lib/cmdx/middlewares/runtime.rb

@@ -32,6 +32,8 @@ module CMDx
       #   Runtime.call(task, if: :enable_profiling, &block)
       # @example Disable runtime measurement
       #   Runtime.call(task, unless: :skip_profiling, &block)
+      #
+      # @rbs (Task task, **untyped options) { () -> untyped } -> untyped
       def call(task, **options)
         return yield unless Utils::Condition.evaluate(task, options)
 
@@ -49,6 +51,8 @@ module CMDx
       # timing measurements that are not affected by system clock changes.
       #
       # @return [Integer] Current monotonic time in milliseconds
+      #
+      # @rbs () -> Integer
       def monotonic_time
         Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
       end

data/lib/cmdx/middlewares/timeout.rb

@@ -21,6 +21,8 @@ module CMDx
       extend self
 
       # Default timeout limit in seconds when none is specified.
+      #
+      # @rbs DEFAULT_LIMIT: Integer
       DEFAULT_LIMIT = 3
 
       # Middleware entry point that enforces execution time limits.
@@ -51,6 +53,8 @@ module CMDx
       #   Timeout.call(task, seconds: -> { calculate_timeout }, &block)
       # @example Conditional timeout control
       #   Timeout.call(task, if: :enable_timeout, &block)
+      #
+      # @rbs (Task task, **untyped options) { () -> untyped } -> untyped
       def call(task, **options, &)
         return yield unless Utils::Condition.evaluate(task, options)
 

data/lib/cmdx/pipeline.rb

@@ -6,7 +6,14 @@ module CMDx
   # and handling breakpoints that can interrupt execution at specific task statuses.
   class Pipeline
 
-    # @return [Workflow] The workflow instance being executed
+    # Returns the workflow being executed by this pipeline.
+    #
+    # @return [Workflow] The workflow instance
+    #
+    # @example
+    #   pipeline.workflow.context[:status] # => "processing"
+    #
+    # @rbs @workflow: Workflow
     attr_reader :workflow
 
     # @param workflow [Workflow] The workflow to execute
@@ -15,6 +22,8 @@ module CMDx
     #
     # @example
     #   pipeline = Pipeline.new(my_workflow)
+    #
+    # @rbs (Workflow workflow) -> void
     def initialize(workflow)
       @workflow = workflow
     end
@@ -27,6 +36,8 @@ module CMDx
     #
     # @example
     #   Pipeline.execute(my_workflow)
+    #
+    # @rbs (Workflow workflow) -> void
     def self.execute(workflow)
       new(workflow).execute
     end
@@ -40,6 +51,8 @@ module CMDx
     # @example
     #   pipeline = Pipeline.new(my_workflow)
     #   pipeline.execute
+    #
+    # @rbs () -> void
     def execute
       workflow.class.pipeline.each do |group|
         next unless Utils::Condition.evaluate(workflow, group.options)
@@ -65,6 +78,8 @@ module CMDx
     #
     # @example
     #   execute_group_tasks(group, ["failed", "skipped"])
+    #
+    # @rbs (untyped group, Array[String] breakpoints) -> void
     def execute_group_tasks(group, breakpoints)
       case strategy = group.options[:strategy]
       when NilClass, /sequential/ then execute_tasks_in_sequence(group, breakpoints)
@@ -85,6 +100,8 @@ module CMDx
     #
     # @example
     #   execute_tasks_in_sequence(group, ["failed", "skipped"])
+    #
+    # @rbs (untyped group, Array[String] breakpoints) -> void
     def execute_tasks_in_sequence(group, breakpoints)
       group.tasks.each do |task|
         task_result = task.execute(workflow.context)
@@ -107,6 +124,8 @@ module CMDx
     #
     # @example
     #   execute_tasks_in_parallel(group, ["failed"])
+    #
+    # @rbs (untyped group, Array[String] breakpoints) -> void
     def execute_tasks_in_parallel(group, breakpoints)
       raise "install the `parallel` gem to use this feature" unless defined?(Parallel)
 

data/lib/cmdx/railtie.rb

@@ -21,6 +21,8 @@ module CMDx
     #   # This initializer runs automatically when Rails starts
     #   # It will load locales like en.yml, es.yml, fr.yml if they exist
     #   # in the CMDx gem's locales directory
+    #
+    # @rbs (untyped app) -> void
     initializer("cmdx.configure_locales") do |app|
       Array(app.config.i18n.available_locales).each do |locale|
         path = CMDx.gem_path.join("lib/locales/#{locale}.yml")
@@ -35,6 +37,8 @@ module CMDx
     # Configures the backtrace cleaner for CMDx in a Rails environment.
     #
     # Sets the backtrace cleaner to the Rails backtrace cleaner.
+    #
+    # @rbs () -> void
     initializer("cmdx.backtrace_cleaner") do
       CMDx.configuration.backtrace_cleaner = lambda do |backtrace|
         Rails.backtrace_cleaner.clean(backtrace)