cmdx 1.8.0 → 1.9.1

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,9 +51,11 @@ 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, workflow)
+        next unless Utils::Condition.evaluate(workflow, group.options)
 
         breakpoints = group.options[:breakpoints] ||
                       workflow.class.settings[:breakpoints] ||
@@ -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,19 +124,21 @@ 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)
+      raise "install the `parallel` gem to use this feature" unless defined?(Parallel)
 
       parallel_options = group.options.slice(:in_threads, :in_processes)
       throwable_result = nil
 
-      ::Parallel.each(group.tasks, **parallel_options) do |task|
+      Parallel.each(group.tasks, **parallel_options) do |task|
         Chain.current = workflow.chain
 
         task_result = task.execute(workflow.context)
         next unless breakpoints.include?(task_result.status)
 
-        raise ::Parallel::Break, throwable_result = task_result
+        raise Parallel::Break, throwable_result = task_result
       end
 
       return if throwable_result.nil?

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")
@@ -32,5 +34,16 @@ module CMDx
       ::I18n.reload!
     end
 
+    # 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)
+      end
+    end
+
   end
 end