cmdx 1.21.0 → 2.0.1

data/lib/cmdx/telemetry.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Pub/sub for runtime lifecycle events (see {EVENTS}). Subscribers are
+  # callables receiving an {Event} data object. Runtime emits events only when
+  # subscribers are registered so telemetry has zero cost when unused.
+  class Telemetry
+
+    # Immutable event payload passed to subscribers.
+    Event = Data.define(:xid, :cid, :root, :type, :task, :tid, :name, :payload, :timestamp) do
+      def self.build(task, name, root: false, payload: EMPTY_HASH)
+        new(
+          xid: Chain.current.xid,
+          cid: Chain.current.id,
+          root:,
+          type: task.class.type,
+          task: task.class,
+          tid: task.tid,
+          name:,
+          payload:,
+          timestamp: Time.now.utc
+        )
+      end
+    end
+
+    # Lifecycle event names Runtime emits.
+    EVENTS = %i[
+      task_started
+      task_deprecated
+      task_retried
+      task_rolled_back
+      task_executed
+    ].freeze
+
+    attr_reader :registry
+
+    def initialize
+      @registry = {}
+    end
+
+    # @param source [Telemetry] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.transform_values(&:dup)
+    end
+
+    # Registers a subscriber for `event`.
+    #
+    # @param event [Symbol] one of {EVENTS}
+    # @param callable [#call, nil] subscriber callable; pass either this or a block
+    # @param block [#call, nil] subscriber when `callable` is omitted
+    # @yieldparam evt [Event]
+    # @return [Telemetry] self for chaining
+    # @raise [ArgumentError] when both `callable` and a block are provided, when
+    #   the subscriber isn't callable, or when `event` is unknown
+    def subscribe(event, callable = nil, &block)
+      subscriber = callable || block
+
+      if callable && block
+        raise ArgumentError, "provide either a callable or a block, not both"
+      elsif !subscriber.respond_to?(:call)
+        raise ArgumentError, "subscriber must respond to #call"
+      elsif !EVENTS.include?(event)
+        raise ArgumentError, "unknown event #{event.inspect}, must be one of #{EVENTS.join(', ')}"
+      end
+
+      (registry[event] ||= []) << subscriber
+      self
+    end
+
+    # Removes a previously registered subscriber. Drops the event entry
+    # entirely when no subscribers remain.
+    #
+    # @param event [Symbol] one of {EVENTS}
+    # @param callable [#call] the subscriber to remove
+    # @return [Telemetry] self for chaining
+    # @raise [ArgumentError] when `event` is unknown
+    def unsubscribe(event, callable)
+      raise ArgumentError, "unknown event #{event.inspect}, must be one of #{EVENTS.join(', ')}" unless EVENTS.include?(event)
+
+      return self unless subscribed?(event)
+
+      registry[event].delete(callable)
+      registry.delete(event) if registry[event].empty?
+      self
+    end
+
+    # @param event [Symbol]
+    # @return [Boolean] true when at least one subscriber exists for `event`
+    def subscribed?(event)
+      registry.key?(event)
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer] number of subscribed events
+    def size
+      registry.size
+    end
+
+    # @return [Integer] total subscribers across all events
+    def count
+      registry.each_value.sum(&:size)
+    end
+
+    # Dispatches `payload` to every subscriber of `event`. No-op when there
+    # are no subscribers.
+    #
+    # @param event [Symbol]
+    # @param payload [Event]
+    # @return [void]
+    def emit(event, payload)
+      return unless (subscribers = registry[event])
+
+      subscribers.each { |s| s.call(payload) }
+    end
+
+  end
+end

data/lib/cmdx/util.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Shared helpers for resolving `:if` / `:unless` conditional options across
+  # tasks, callbacks, inputs, outputs, validators, and deprecations. Normalizes
+  # booleans, symbols (method names), procs, and call-ables into a truth value.
+  module Util
+
+    extend self
+
+    # Evaluates a condition against `receiver`, dispatching by type.
+    #
+    # @param condition [Boolean, nil, Symbol, Proc, #call] `:if`/`:unless`-style gate, method name, or callable evaluated against `receiver`
+    # @param receiver [Object] object the condition runs against (usually a Task)
+    # @param args [Array<Object>] extra arguments forwarded to the condition
+    # @return [Boolean, Object] truthiness result (Procs `instance_exec` on receiver)
+    # @raise [ArgumentError] when the condition is not a supported type
+    def evaluate(condition, receiver, *args)
+      case condition
+      when FalseClass, NilClass
+        false
+      when TrueClass
+        true
+      when Symbol
+        receiver.send(condition, *args)
+      when Proc
+        receiver.instance_exec(*args, &condition)
+      else
+        return condition.call(receiver, *args) if condition.respond_to?(:call)
+
+        raise ArgumentError, "condition must be a Symbol, Proc, or respond to #call"
+      end
+    end
+
+    # Evaluates an `:if`-style condition. `nil` is treated as "always true".
+    #
+    # @param condition [Boolean, nil, Symbol, Proc, #call] gate to check
+    # @param receiver [Object] object the condition runs against
+    # @param args [Array<Object>] extra arguments forwarded to the condition
+    # @return [Boolean] true when `condition` is nil or evaluates truthy
+    def if?(condition, receiver, *args)
+      return true if condition.nil?
+
+      evaluate(condition, receiver, *args)
+    end
+
+    # Evaluates an `:unless`-style condition. `nil` is treated as "always true".
+    #
+    # @param condition [Boolean, nil, Symbol, Proc, #call] gate to check
+    # @param receiver [Object] object the condition runs against
+    # @param args [Array<Object>] extra arguments forwarded to the condition
+    # @return [Boolean] true when `condition` is nil or evaluates falsy
+    def unless?(condition, receiver, *args)
+      return true if condition.nil?
+
+      !evaluate(condition, receiver, *args)
+    end
+
+    # Combines `:if` and `:unless` gates. Used across the framework to decide
+    # whether a conditional feature (callback, retry, validator, etc.) should run.
+    #
+    # @param condition_if [Boolean, nil, Symbol, Proc, #call] `:if` gate
+    # @param condition_unless [Boolean, nil, Symbol, Proc, #call] `:unless` gate
+    # @param receiver [Object] object the conditions run against
+    # @param args [Array<Object>] extra arguments forwarded to both conditions
+    # @return [Boolean] true only when both gates pass
+    def satisfied?(condition_if, condition_unless, receiver, *args)
+      if?(condition_if, receiver, *args) &&
+        unless?(condition_unless, receiver, *args)
+    end
+
+  end
+end

data/lib/cmdx/validators/absence.rb

@@ -1,47 +1,19 @@
 # frozen_string_literal: true
 
 module CMDx
-  module Validators
-    # Validates that a value is absent or empty
-    #
-    # This validator ensures that the given value is nil, empty, or consists only of whitespace.
-    # It handles different value types appropriately:
-    # - Strings: checks for absence of non-whitespace characters
-    # - Collections: checks for empty collections
-    # - Other objects: checks for nil values
+  class Validators
+    # Validates that a value is blank: `nil`, whitespace-only string, or
+    # empty collection.
     module Absence
 
       extend self
 
-      # Validates that a value is absent or empty
-      #
-      # @param value [Object] The value to validate for absence
-      # @param options [Hash] Validation configuration options
-      # @option options [String] :message Custom error message
-      #
-      # @return [nil] Returns nil if validation passes
-      #
-      # @raise [ValidationError] When the value is present, not empty, or contains non-whitespace characters
-      #
-      # @example Validate string absence
-      #   Absence.call("")
-      #   # => nil (validation passes)
-      # @example Validate non-empty string
-      #   Absence.call("hello")
-      #   # => raises ValidationError
-      # @example Validate array absence
-      #   Absence.call([])
-      #   # => nil (validation passes)
-      # @example Validate non-empty array
-      #   Absence.call([1, 2, 3])
-      #   # => raises ValidationError
-      # @example Validate with custom message
-      #   Absence.call("hello", message: "Value must be empty")
-      #   # => raises ValidationError with custom message
-      #
-      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> nil
+      # @param value [Object]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [String] :message override for the failure message
+      # @return [Validators::Failure, nil]
       def call(value, options = EMPTY_HASH)
-        match =
+        present =
           if value.is_a?(String)
             /\S/.match?(value)
           elsif value.respond_to?(:empty?)
@@ -50,10 +22,9 @@ module CMDx
             !value.nil?
           end
 
-        return unless match
+        return unless present
 
-        message = options[:message] if options.is_a?(Hash)
-        raise ValidationError, message || Locale.t("cmdx.validators.absence")
+        Failure.new(options[:message] || I18nProxy.t("cmdx.validators.absence"))
       end
 
     end

data/lib/cmdx/validators/exclusion.rb

@@ -1,79 +1,60 @@
 # frozen_string_literal: true
 
 module CMDx
-  module Validators
-    # Validates that a value is not included in a specified set or range
-    #
-    # This validator ensures that the given value is excluded from a collection
-    # of forbidden values or falls outside a specified range. It supports both
-    # discrete value lists and range-based exclusions.
+  class Validators
+    # Inverse of {Inclusion}: the value must not be within the given
+    # enumerable or `Range`.
     module Exclusion
 
       extend self
 
-      # Validates that a value is excluded from the specified options
-      #
-      # @param value [Object] The value to validate for exclusion
-      # @param options [Hash] Validation configuration options
-      # @option options [Array, Range] :in The collection of forbidden values or range
-      # @option options [Array, Range] :within Alias for :in option
-      # @option options [String] :message Custom error message template
-      # @option options [String] :of_message Custom message for discrete value exclusions
-      # @option options [String] :in_message Custom message for range-based exclusions
-      # @option options [String] :within_message Custom message for range-based exclusions
-      #
-      # @raise [ValidationError] When the value is found in the forbidden collection
-      #
-      # @example Exclude specific values
-      #   Exclusion.call("admin", in: ["admin", "root", "superuser"])
-      #   # => raises ValidationError if value is "admin"
-      # @example Exclude values within a range
-      #   Exclusion.call(5, in: 1..10)
-      #   # => raises ValidationError if value is 5 (within 1..10)
-      # @example Exclude with custom message
-      #   Exclusion.call("test", in: ["test", "demo"], message: "value %{values} is forbidden")
-      #
-      # @rbs (untyped value, Hash[Symbol, untyped] options) -> nil
+      # @param value [Object]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [Range, Array, Set, Enumerable] :in disallowed values
+      # @option options [Range, Array, Set, Enumerable] :within alias for `:in`
+      # @option options [String] :message global failure-message override
+      # @option options [String] :of_message override for enumerable failures
+      # @option options [String] :in_message, :within_message overrides for range failures
+      # @return [Validators::Failure, nil]
+      # @raise [ArgumentError] when neither `:in` nor `:within` is given
       def call(value, options = EMPTY_HASH)
         values = options[:in] || options[:within]
+        raise ArgumentError, "exclusion validator requires :in or :within option" if values.nil?
 
         if values.is_a?(Range)
-          raise_within_validation_error!(values.begin, values.end, options) if values.cover?(value)
-        elsif Utils::Wrap.array(values).any? { |v| v === value }
-          raise_of_validation_error!(values, options)
+          within_failure(values.begin, values.end, options) if values.cover?(value)
+        elsif Array(values).any? { |v| v === value }
+          of_failure(values, options)
         end
       end
 
       private
 
-      # Raises validation error for discrete value exclusions
-      #
-      # @param values [Array] The forbidden values that caused the error
-      # @param options [Hash] Validation options containing custom messages
-      # @option options [Object] :* Any validation option key-value pairs
-      #
-      # @raise [ValidationError] With appropriate error message
-      def raise_of_validation_error!(values, options)
-        values = values.map(&:inspect).join(", ") unless values.nil?
+      # @param values [Enumerable] collection rendered into the failure message
+      # @param options [Hash{Symbol => Object}]
+      # @option options [String] :of_message
+      # @option options [String] :message
+      # @return [Validators::Failure]
+      def of_failure(values, options)
+        values = values.map(&:inspect).join(", ")
         message = options[:of_message] || options[:message]
         message %= { values: } unless message.nil?
 
-        raise ValidationError, message || Locale.t("cmdx.validators.exclusion.of", values:)
+        Failure.new(message || I18nProxy.t("cmdx.validators.exclusion.of", values:))
       end
 
-      # Raises validation error for range-based exclusions
-      #
-      # @param min [Object] The minimum value of the forbidden range
-      # @param max [Object] The maximum value of the forbidden range
-      # @param options [Hash] Validation options containing custom messages
-      # @option options [Object] :* Any validation option key-value pairs
-      #
-      # @raise [ValidationError] With appropriate error message
-      def raise_within_validation_error!(min, max, options)
+      # @param min [Object] range/exclusion lower bound
+      # @param max [Object] range/exclusion upper bound
+      # @param options [Hash{Symbol => Object}]
+      # @option options [String] :in_message
+      # @option options [String] :within_message
+      # @option options [String] :message
+      # @return [Validators::Failure]
+      def within_failure(min, max, options)
         message = options[:in_message] || options[:within_message] || options[:message]
         message %= { min:, max: } unless message.nil?
 
-        raise ValidationError, message || Locale.t("cmdx.validators.exclusion.within", min:, max:)
+        Failure.new(message || I18nProxy.t("cmdx.validators.exclusion.within", min:, max:))
       end
 
     end

data/lib/cmdx/validators/format.rb

@@ -1,66 +1,36 @@
 # frozen_string_literal: true
 
 module CMDx
-  module Validators
-    # Validates that a value matches a specified format pattern
-    #
-    # This validator ensures that the given value conforms to a specific format
-    # using regular expressions. It supports both direct regex matching and
-    # conditional matching with inclusion/exclusion patterns.
+  class Validators
+    # Validates that a value matches a `:with` regex and/or does not match a
+    # `:without` regex. Both may be combined; at least one is required.
     module Format
 
       extend self
 
-      # Validates that a value matches the specified format pattern
-      #
-      # @param value [Object] The value to validate for format compliance
-      # @param options [Hash, Regexp] Validation configuration options or direct regex pattern
-      # @option options [Regexp] :with Required pattern that the value must match
-      # @option options [Regexp] :without Pattern that the value must not match
-      # @option options [String] :message Custom error message
-      #
-      # @return [nil] Returns nil if validation passes
-      #
-      # @raise [ValidationError] When the value doesn't match the required format
-      #
-      # @example Direct regex validation
-      #   Format.call("user@example.com", /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
-      #   # => nil (validation passes)
-      # @example Validate with required pattern
-      #   Format.call("ABC123", with: /\A[A-Z]{3}\d{3}\z/)
-      #   # => nil (validation passes)
-      # @example Validate with exclusion pattern
-      #   Format.call("hello", without: /\d/)
-      #   # => nil (validation passes - no digits)
-      # @example Validate with both patterns
-      #   Format.call("test123", with: /\A\w+\z/, without: /\A\d+\z/)
-      #   # => nil (validation passes - alphanumeric but not all digits)
-      # @example Validate with custom message
-      #   Format.call("invalid", with: /\A\d+\z/, message: "Must contain only digits")
-      #   # => raises ValidationError with custom message
-      #
-      # @rbs (untyped value, (Hash[Symbol, untyped] | Regexp) options) -> nil
+      # @param value [String, nil]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [Regexp] :with must match
+      # @option options [Regexp] :without must not match
+      # @option options [String] :message override for the failure message
+      # @return [Validators::Failure, nil]
+      # @raise [ArgumentError] when neither `:with` nor `:without` is given
       def call(value, options = EMPTY_HASH)
         match =
-          if options.is_a?(Regexp)
-            value&.match?(options)
+          case options
+          in with:, without:
+            value&.match?(with) && !value&.match?(without)
+          in with:
+            value&.match?(with)
+          in without:
+            !value&.match?(without)
           else
-            case options
-            in with:, without:
-              value&.match?(with) && !value&.match?(without)
-            in with:
-              value&.match?(with)
-            in without:
-              !value&.match?(without)
-            else
-              false
-            end
+            raise ArgumentError, "format validator requires :with and/or :without option"
           end
 
         return if match
 
-        message = options[:message] if options.is_a?(Hash)
-        raise ValidationError, message || Locale.t("cmdx.validators.format")
+        Failure.new(options[:message] || I18nProxy.t("cmdx.validators.format"))
       end
 
     end

data/lib/cmdx/validators/inclusion.rb

@@ -1,81 +1,60 @@
 # frozen_string_literal: true
 
 module CMDx
-  module Validators
-    # Validates that a value is included in a specified set or range
-    #
-    # This validator ensures that the given value is present within a collection
-    # of allowed values or falls within a specified range. It supports both
-    # discrete value lists and range-based validations.
+  class Validators
+    # Validates that a value is within an enumerable or `Range`. Range uses
+    # `#cover?`; other enumerables use `===` (so regex/class matchers work).
     module Inclusion
 
       extend self
 
-      # Validates that a value is included in the specified options
-      #
-      # @param value [Object] The value to validate for inclusion
-      # @param options [Hash] Validation configuration options
-      # @option options [Array, Range] :in The collection of allowed values or range
-      # @option options [Array, Range] :within Alias for :in option
-      # @option options [String] :message Custom error message template
-      # @option options [String] :of_message Custom message for discrete value inclusions
-      # @option options [String] :in_message Custom message for range-based inclusions
-      # @option options [String] :within_message Custom message for range-based inclusions
-      #
-      # @return [nil] Returns nil if validation passes
-      #
-      # @raise [ValidationError] When the value is not found in the allowed collection
-      #
-      # @example Include specific values
-      #   Inclusion.call("admin", in: ["admin", "user", "guest"])
-      #   # => nil (validation passes)
-      # @example Include values within a range
-      #   Inclusion.call(5, in: 1..10)
-      #   # => nil (validation passes - 5 is within 1..10)
-      # @example Include with custom message
-      #   Inclusion.call("test", in: ["admin", "user"], message: "must be one of: %{values}")
-      #
-      # @rbs (untyped value, Hash[Symbol, untyped] options) -> nil
+      # @param value [Object]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [Range, Array, Set, Enumerable] :in allowed values
+      # @option options [Range, Array, Set, Enumerable] :within alias for `:in`
+      # @option options [String] :message global failure-message override
+      # @option options [String] :of_message override for enumerable failures
+      # @option options [String] :in_message, :within_message overrides for range failures
+      # @return [Validators::Failure, nil]
+      # @raise [ArgumentError] when neither `:in` nor `:within` is given
       def call(value, options = EMPTY_HASH)
         values = options[:in] || options[:within]
+        raise ArgumentError, "inclusion validator requires :in or :within option" if values.nil?
 
         if values.is_a?(Range)
-          raise_within_validation_error!(values.begin, values.end, options) unless values.cover?(value)
-        elsif Utils::Wrap.array(values).none? { |v| v === value }
-          raise_of_validation_error!(values, options)
+          within_failure(values.begin, values.end, options) unless values.cover?(value)
+        elsif Array(values).none? { |v| v === value }
+          of_failure(values, options)
         end
       end
 
       private
 
-      # Raises validation error for discrete value inclusions
-      #
-      # @param values [Array] The allowed values that caused the error
-      # @param options [Hash] Validation options containing custom messages
-      # @option options [Object] :* Any validation option key-value pairs
-      #
-      # @raise [ValidationError] With appropriate error message
-      def raise_of_validation_error!(values, options)
-        values = values.map(&:inspect).join(", ") unless values.nil?
+      # @param values [Enumerable] collection rendered into the failure message
+      # @param options [Hash{Symbol => Object}]
+      # @option options [String] :of_message
+      # @option options [String] :message
+      # @return [Validators::Failure]
+      def of_failure(values, options)
+        values = values.map(&:inspect).join(", ")
         message = options[:of_message] || options[:message]
         message %= { values: } unless message.nil?
 
-        raise ValidationError, message || Locale.t("cmdx.validators.inclusion.of", values:)
+        Failure.new(message || I18nProxy.t("cmdx.validators.inclusion.of", values:))
       end
 
-      # Raises validation error for range-based inclusions
-      #
-      # @param min [Object] The minimum value of the allowed range
-      # @param max [Object] The maximum value of the allowed range
-      # @param options [Hash] Validation options containing custom messages
-      # @option options [Object] :* Any validation option key-value pairs
-      #
-      # @raise [ValidationError] With appropriate error message
-      def raise_within_validation_error!(min, max, options)
+      # @param min [Object] range/inclusion lower bound
+      # @param max [Object] range/inclusion upper bound
+      # @param options [Hash{Symbol => Object}]
+      # @option options [String] :in_message
+      # @option options [String] :within_message
+      # @option options [String] :message
+      # @return [Validators::Failure]
+      def within_failure(min, max, options)
         message = options[:in_message] || options[:within_message] || options[:message]
         message %= { min:, max: } unless message.nil?
 
-        raise ValidationError, message || Locale.t("cmdx.validators.inclusion.within", min:, max:)
+        Failure.new(message || I18nProxy.t("cmdx.validators.inclusion.within", min:, max:))
       end
 
     end