cmdx 2.0.1 → 2.1.0

data/lib/cmdx/validators/format.rb

@@ -15,17 +15,25 @@ module CMDx
       # @option options [String] :message override for the failure message
       # @return [Validators::Failure, nil]
       # @raise [ArgumentError] when neither `:with` nor `:without` is given
+      # @note Non-String values that do not respond to `#match?` fail with the
+      #   regular format failure rather than raise `NoMethodError`. Coerce inputs
+      #   to String beforehand when format checks are required.
       def call(value, options = EMPTY_HASH)
+        str = value.nil? || value.respond_to?(:match?) ? value : value.to_s
+
         match =
           case options
           in with:, without:
-            value&.match?(with) && !value&.match?(without)
+            str&.match?(with) && !str&.match?(without)
           in with:
-            value&.match?(with)
+            str&.match?(with)
           in without:
-            !value&.match?(without)
+            !str&.match?(without)
           else
-            raise ArgumentError, "format validator requires :with and/or :without option"
+            raise ArgumentError, <<~MSG.chomp
+              format validator requires :with and/or :without (got #{options.keys.inspect}).
+              See https://drexed.github.io/cmdx/inputs/validations/#format
+            MSG
           end
 
         return if match

data/lib/cmdx/validators/inclusion.rb

@@ -19,22 +19,29 @@ module CMDx
       # @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.nil?
+          raise ArgumentError, <<~MSG.chomp
+            inclusion validator requires :in or :within (got #{options.keys.inspect}).
+            See https://drexed.github.io/cmdx/inputs/validations/#inclusion
+          MSG
+        elsif values.is_a?(Hash)
+          raise ArgumentError, <<~MSG.chomp
+            inclusion validator :in/:within does not accept a Hash; pass an Array,
+            Set, Range, or other Enumerable (e.g. `#{values.inspect}.keys`).
+            See https://drexed.github.io/cmdx/inputs/validations/#inclusion
+          MSG
+        end
 
         if values.is_a?(Range)
           within_failure(values.begin, values.end, options) unless values.cover?(value)
-        elsif Array(values).none? { |v| v === value }
-          of_failure(values, options)
+        else
+          enum = values.is_a?(Enumerable) ? values : [values]
+          of_failure(enum, options) if enum.none? { |v| v === value }
         end
       end
 
       private
 
-      # @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]
@@ -43,13 +50,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.inclusion.of", values:))
       end
 
-      # @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?

data/lib/cmdx/validators/length.rb

@@ -63,28 +63,21 @@ module CMDx
         in is_not:
           is_not_failure(is_not, options) if length == is_not
         else
-          raise ArgumentError, "unknown length validator options given"
+          raise ArgumentError, <<~MSG.chomp
+            unknown length validator options #{options.keys.inspect};
+            expected one of [:within, :not_within, :in, :not_in, :min, :max, :gt, :lt, :is, :is_not] (aliases: :gte, :lte, :eq, :not_eq).
+            See https://drexed.github.io/cmdx/inputs/validations/#length
+          MSG
         end
       end
 
       private
 
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :nil_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def nil_failure(options)
         message = options[:nil_message] || options[:message]
         Failure.new(message || I18nProxy.t("cmdx.validators.length.nil_value"))
       end
 
-      # @param min [Object]
-      # @param max [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :within_message
-      # @option options [String] :in_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def within_failure(min, max, options)
         message = options[:within_message] || options[:in_message] || options[:message]
         message %= { min:, max: } unless message.nil?
@@ -92,13 +85,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.length.within", min:, max:))
       end
 
-      # @param min [Object]
-      # @param max [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :not_within_message
-      # @option options [String] :not_in_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def not_within_failure(min, max, options)
         message = options[:not_within_message] || options[:not_in_message] || options[:message]
         message %= { min:, max: } unless message.nil?
@@ -106,11 +92,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.length.not_within", min:, max:))
       end
 
-      # @param min [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :min_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def min_failure(min, options)
         message = options[:min_message] || options[:message]
         message %= { min: } unless message.nil?
@@ -118,11 +99,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.length.min", min:))
       end
 
-      # @param max [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :max_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def max_failure(max, options)
         message = options[:max_message] || options[:message]
         message %= { max: } unless message.nil?
@@ -130,11 +106,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.length.max", max:))
       end
 
-      # @param gt [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :gt_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def gt_failure(gt, options)
         message = options[:gt_message] || options[:message]
         message %= { gt: } unless message.nil?
@@ -142,11 +113,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.length.gt", gt:))
       end
 
-      # @param lt [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :lt_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def lt_failure(lt, options)
         message = options[:lt_message] || options[:message]
         message %= { lt: } unless message.nil?
@@ -154,11 +120,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.length.lt", lt:))
       end
 
-      # @param is [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :is_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def is_failure(is, options) # rubocop:disable Naming/PredicatePrefix
         message = options[:is_message] || options[:message]
         message %= { is: } unless message.nil?
@@ -166,11 +127,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.length.is", is:))
       end
 
-      # @param is_not [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :is_not_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def is_not_failure(is_not, options) # rubocop:disable Naming/PredicatePrefix
         message = options[:is_not_message] || options[:message]
         message %= { is_not: } unless message.nil?

data/lib/cmdx/validators/numeric.rb

@@ -60,28 +60,21 @@ module CMDx
         in is_not:
           is_not_failure(is_not, options) if value == is_not
         else
-          raise ArgumentError, "unknown numeric validator options given"
+          raise ArgumentError, <<~MSG.chomp
+            unknown numeric validator options #{options.keys.inspect};
+            expected one of [:within, :not_within, :in, :not_in, :min, :max, :gt, :lt, :is, :is_not] (aliases: :gte, :lte, :eq, :not_eq).
+            See https://drexed.github.io/cmdx/inputs/validations/#numeric
+          MSG
         end
       end
 
       private
 
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :nil_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def nil_failure(options)
         message = options[:nil_message] || options[:message]
         Failure.new(message || I18nProxy.t("cmdx.validators.numeric.nil_value"))
       end
 
-      # @param min [Object]
-      # @param max [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :within_message
-      # @option options [String] :in_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def within_failure(min, max, options)
         message = options[:within_message] || options[:in_message] || options[:message]
         message %= { min:, max: } unless message.nil?
@@ -89,13 +82,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.numeric.within", min:, max:))
       end
 
-      # @param min [Object]
-      # @param max [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :not_within_message
-      # @option options [String] :not_in_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def not_within_failure(min, max, options)
         message = options[:not_within_message] || options[:not_in_message] || options[:message]
         message %= { min:, max: } unless message.nil?
@@ -103,11 +89,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.numeric.not_within", min:, max:))
       end
 
-      # @param min [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :min_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def min_failure(min, options)
         message = options[:min_message] || options[:message]
         message %= { min: } unless message.nil?
@@ -115,11 +96,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.numeric.min", min:))
       end
 
-      # @param max [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :max_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def max_failure(max, options)
         message = options[:max_message] || options[:message]
         message %= { max: } unless message.nil?
@@ -127,11 +103,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.numeric.max", max:))
       end
 
-      # @param gt [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :gt_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def gt_failure(gt, options)
         message = options[:gt_message] || options[:message]
         message %= { gt: } unless message.nil?
@@ -139,11 +110,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.numeric.gt", gt:))
       end
 
-      # @param lt [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :lt_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def lt_failure(lt, options)
         message = options[:lt_message] || options[:message]
         message %= { lt: } unless message.nil?
@@ -151,11 +117,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.numeric.lt", lt:))
       end
 
-      # @param is [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :is_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def is_failure(is, options) # rubocop:disable Naming/PredicatePrefix
         message = options[:is_message] || options[:message]
         message %= { is: } unless message.nil?
@@ -163,11 +124,6 @@ module CMDx
         Failure.new(message || I18nProxy.t("cmdx.validators.numeric.is", is:))
       end
 
-      # @param is_not [Object]
-      # @param options [Hash{Symbol => Object}]
-      # @option options [String] :is_not_message
-      # @option options [String] :message
-      # @return [Validators::Failure]
       def is_not_failure(is_not, options) # rubocop:disable Naming/PredicatePrefix
         message = options[:is_not_message] || options[:message]
         message %= { is_not: } unless message.nil?

data/lib/cmdx/validators/presence.rb

@@ -19,7 +19,7 @@ module CMDx
           elsif value.respond_to?(:empty?)
             !value.empty?
           else
-            !value.nil?
+            !!value
           end
 
         return if present

data/lib/cmdx/validators/validate.rb

@@ -13,6 +13,9 @@ module CMDx
       # @param handler [Symbol, Proc, #call]
       # @return [Validators::Failure, nil, Object] handler's return value
       # @raise [ArgumentError] when `handler` isn't a supported type
+      # @note Symbol handlers are dispatched via `send` so private helpers on
+      #   the task are reachable. Handlers are baked into class definitions;
+      #   never derive them from untrusted input.
       def call(task, value, handler)
         case handler
         when Symbol
@@ -22,7 +25,10 @@ module CMDx
         else
           return handler.call(value, task) if handler.respond_to?(:call)
 
-          raise ArgumentError, "validate handler must be a Symbol, Proc, or respond to #call"
+          raise ArgumentError, <<~MSG.chomp
+            validate handler must be a Symbol, Proc, or respond to #call (got #{handler.class}).
+            See https://drexed.github.io/cmdx/inputs/validations/#inline-validate-callable
+          MSG
         end
       end
 

data/lib/cmdx/validators.rb

@@ -45,9 +45,12 @@ module CMDx
       validator = callable || block
 
       if callable && block
-        raise ArgumentError, "provide either a callable or a block, not both"
+        raise ArgumentError, "validator: provide either a callable or a block, not both"
       elsif !validator.respond_to?(:call)
-        raise ArgumentError, "validator must respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          validator must respond to #call (got #{validator.class}).
+          See https://drexed.github.io/cmdx/inputs/validations/#declarations
+        MSG
       end
 
       registry[name.to_sym] = validator
@@ -57,16 +60,25 @@ module CMDx
     # @param name [Symbol]
     # @return [Validators] self for chaining
     def deregister(name)
-      registry.delete(name.to_sym)
+      registry.delete(name)
       self
     end
 
+    # @param name [Symbol]
+    # @return [Boolean] whether a validator is registered under `name`
+    def key?(name)
+      registry.key?(name)
+    end
+
     # @param name [Symbol]
     # @return [#call]
-    # @raise [ArgumentError] when `name` isn't registered
+    # @raise [UnknownEntryError] when `name` isn't registered
     def lookup(name)
       registry[name] || begin
-        raise ArgumentError, "unknown validator: #{name}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown validator #{name.inspect}; registered: #{registry.keys.inspect}.
+          See https://drexed.github.io/cmdx/inputs/validations/#built-in-validators
+        MSG
       end
     end
 
@@ -137,9 +149,6 @@ module CMDx
 
     private
 
-    # @param raw_options [Object] truthy flag, Hash, Array, Regexp, etc. from a declaration
-    # @return [Hash{Symbol => Object}, nil] normalized rule options, or nil when disabled
-    # @raise [ArgumentError] when `raw_options` has an unsupported shape
     def normalize_options(raw_options)
       case raw_options
       when FalseClass, NilClass
@@ -153,7 +162,10 @@ module CMDx
       when Regexp
         { with: raw_options }
       else
-        raise ArgumentError, "unsupported validator option format: #{raw_options.inspect}"
+        raise ArgumentError, <<~MSG.chomp
+          unsupported validator option format #{raw_options.inspect}; expected Boolean, Hash, Array, or Regexp.
+          See https://drexed.github.io/cmdx/inputs/validations/#common-options
+        MSG
       end
     end
 

data/lib/cmdx/version.rb

@@ -3,6 +3,6 @@
 module CMDx
 
   # Gem version. Bumped on release; mirrored in the gemspec.
-  VERSION = "2.0.1"
+  VERSION = "2.1.0"
 
 end

data/lib/cmdx/workflow.rb

@@ -24,10 +24,11 @@ module CMDx
         @pipeline ||= []
       end
 
-      # Declares a task group. With no arguments, returns the pipeline.
-      # Tasks must be `Task` subclasses.
+      # Declares a task group. At least one `Task` subclass is required —
+      # invoking with no arguments raises `DefinitionError`. Use {.pipeline}
+      # to read the existing group list.
       #
-      # @param tasks [Array<Class<Task>>]
+      # @param tasks [Array<Class<Task>>] one or more `Task` subclasses
       # @param options [Hash{Symbol => Object}]
       # @option options [:sequential, :parallel] :strategy (:sequential)
       # @option options [Integer] :pool_size parallel worker/fiber count
@@ -55,18 +56,26 @@ module CMDx
       #   `:parallel` cancels pending tasks (in-flight tasks still finish).
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
-      # @return [Array<ExecutionGroup>] the full pipeline
-      # @raise [DefinitionError] when called with options but no tasks
+      # @return [Array<ExecutionGroup>] the full pipeline (with the new group appended)
+      # @raise [DefinitionError] when called with no tasks
       # @raise [TypeError] when any element isn't a `Task` subclass
       def tasks(*tasks, **options)
-        raise DefinitionError, "#{name}: cannot declare an empty task group" if tasks.empty?
+        if tasks.empty?
+          raise DefinitionError, <<~MSG.chomp
+            #{name}: cannot declare an empty task group; pass at least one Task subclass.
+            See https://drexed.github.io/cmdx/workflows/#declarations
+          MSG
+        end
 
         pipeline << ExecutionGroup.new(
           tasks:
             tasks.map do |task|
               next task if task.is_a?(Class) && (task <= Task)
 
-              raise TypeError, "#{task.inspect} is not a Task"
+              raise TypeError, <<~MSG.chomp
+                #{task.inspect} is not a Task subclass.
+                See https://drexed.github.io/cmdx/workflows/#declarations
+              MSG
             end,
           options:
         )
@@ -75,16 +84,13 @@ module CMDx
 
       private
 
-      # Forbids user-defined `work` on workflows; `Workflow#work` delegates
-      # to {Pipeline}.
-      #
-      # @param method_name [Symbol] hook name reported by Ruby
-      # @return [void]
-      # @raise [ImplementationError] when a workflow defines `work`
       def method_added(method_name)
         return super unless method_name == :work
 
-        raise ImplementationError, "cannot define #{name}##{method_name} in a workflow"
+        raise ImplementationError, <<~MSG.chomp
+          cannot define #{name}##{method_name} in a workflow; #work is auto-generated to delegate to Pipeline.
+          See https://drexed.github.io/cmdx/workflows/#declarations
+        MSG
       end
 
     end
@@ -95,7 +101,15 @@ module CMDx
     # @api private
     # @param base [Class] task class including this mixin
     # @return [void]
+    # @raise [ImplementationError] when `base` is not a {Task} subclass
     def self.included(base)
+      unless base.is_a?(Class) && base <= Task
+        raise ImplementationError, <<~MSG.chomp
+          CMDx::Workflow can only be included in a CMDx::Task subclass (got #{base.inspect}).
+          See https://drexed.github.io/cmdx/workflows/#declarations
+        MSG
+      end
+
       base.extend(ClassMethods)
     end
 

data/lib/cmdx.rb

@@ -24,6 +24,13 @@ module CMDx
   EMPTY_HASH = {}.freeze
   private_constant :EMPTY_HASH
 
+  # Sentinel object used as a placeholder return value to avoid per-call
+  # allocations on hot paths.
+  #
+  # @api private
+  EMPTY_SENTINEL = Object.new.freeze
+  private_constant :EMPTY_SENTINEL
+
   # Shared empty string constant used as a sentinel default. Intentionally
   # not frozen so callers may treat it as a mutable seed when needed.
   #
@@ -51,6 +58,11 @@ module CMDx
   # before continuing.
   DeprecationError = Class.new(Error)
 
+  # Raised when a control-flow signal (e.g. `skip!`, `fail!`) is thrown against
+  # a task that has already completed and been frozen, making further state
+  # transitions impossible.
+  FrozenTaskError = Class.new(Error)
+
   # Raised when a subclass fails to fulfill an abstract contract — most
   # commonly when {Task} is invoked without overriding `#work`, or when a
   # {Workflow} attempts to define `#work` itself.
@@ -60,6 +72,18 @@ module CMDx
   # yield to `next_link`, which would otherwise silently skip the task body.
   MiddlewareError = Class.new(Error)
 
+  # Raised by {Context} in strict mode when accessing a key that was never
+  # assigned, preventing silent `nil` propagation across task boundaries.
+  UnknownAccessorError = Class.new(Error)
+
+  # Raised when a registry lookup (coercion, validator, middleware, etc.) is
+  # performed against a name that has not been registered.
+  UnknownEntryError = Class.new(Error)
+
+  # Raised when the configured locale cannot be resolved to a translation
+  # file on the i18n load path.
+  UnknownLocaleError = Class.new(Error)
+
 end
 
 require_relative "cmdx/version"