cmdx 1.20.0 → 2.0.0

data/lib/cmdx/validators/presence.rb

@@ -1,47 +1,19 @@
 # frozen_string_literal: true
 
 module CMDx
-  module Validators
-    # Validates that a value is present and not empty
-    #
-    # This validator ensures that the given value exists and contains meaningful content.
-    # It handles different value types appropriately:
-    # - Strings: checks for non-whitespace characters
-    # - Collections: checks for non-empty collections
-    # - Other objects: checks for non-nil values
+  class Validators
+    # Validates that a value is present: non-`nil`, non-empty, and (for
+    # strings) not whitespace-only.
     module Presence
 
       extend self
 
-      # Validates that a value is present and not empty
-      #
-      # @param value [Object] The value to validate for presence
-      # @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 empty, nil, or contains only whitespace
-      #
-      # @example Validate string presence
-      #   Presence.call("hello world")
-      #   # => nil (validation passes)
-      # @example Validate empty string
-      #   Presence.call("   ")
-      #   # => raises ValidationError
-      # @example Validate array presence
-      #   Presence.call([1, 2, 3])
-      #   # => nil (validation passes)
-      # @example Validate empty array
-      #   Presence.call([])
-      #   # => raises ValidationError
-      # @example Validate with custom message
-      #   Presence.call(nil, message: "Value cannot be blank")
-      #   # => 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 if match
+        return if present
 
-        message = options[:message] if options.is_a?(Hash)
-        raise ValidationError, message || Locale.t("cmdx.validators.presence")
+        Failure.new(options[:message] || I18nProxy.t("cmdx.validators.presence"))
       end
 
     end

data/lib/cmdx/validators/validate.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Validators
+    # Invokes an inline `:validate` handler. Used by {Validators#validate}
+    # for each handler passed under the `:validate` option.
+    module Validate
+
+      extend self
+
+      # @param task [Task] receiver for Symbol/Proc handlers, also passed to callable handlers
+      # @param value [Object]
+      # @param handler [Symbol, Proc, #call]
+      # @return [Validators::Failure, nil, Object] handler's return value
+      # @raise [ArgumentError] when `handler` isn't a supported type
+      def call(task, value, handler)
+        case handler
+        when Symbol
+          task.send(handler, value)
+        when Proc
+          task.instance_exec(value, &handler)
+        else
+          return handler.call(value, task) if handler.respond_to?(:call)
+
+          raise ArgumentError, "validate handler must be a Symbol, Proc, or respond to #call"
+        end
+      end
+
+    end
+  end
+end

data/lib/cmdx/validators.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry of named validators applied to resolved input/output values.
+  # Ships with built-ins for `:absence`, `:exclusion`, `:format`,
+  # `:inclusion`, `:length`, `:numeric`, `:presence`. Validators return a
+  # {Failure} on invalid input (recorded on `task.errors`) or `nil` on
+  # success. The `:validate` key supports inline callables.
+  class Validators
+
+    # Sentinel returned by a validator to signal invalid input. Runtime
+    # records its `message` on the task's errors.
+    Failure = Data.define(:message)
+
+    attr_reader :registry
+
+    def initialize
+      @registry = {
+        absence: Validators::Absence,
+        exclusion: Validators::Exclusion,
+        format: Validators::Format,
+        inclusion: Validators::Inclusion,
+        length: Validators::Length,
+        numeric: Validators::Numeric,
+        presence: Validators::Presence
+      }
+    end
+
+    # @param source [Validators] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.dup
+    end
+
+    # Registers a named validator, overwriting any existing entry.
+    #
+    # @param name [Symbol]
+    # @param callable [#call, nil] pass either this or a block
+    # @param block [#call, nil] validator callable when `callable` is omitted
+    # @yield validator body — `call(value, options = {})`
+    # @return [Validators] self for chaining
+    # @raise [ArgumentError] when both `callable` and a block are given, or
+    #   when the resolved validator isn't callable
+    def register(name, callable = nil, &block)
+      validator = callable || block
+
+      if callable && block
+        raise ArgumentError, "provide either a callable or a block, not both"
+      elsif !validator.respond_to?(:call)
+        raise ArgumentError, "validator must respond to #call"
+      end
+
+      registry[name.to_sym] = validator
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [Validators] self for chaining
+    def deregister(name)
+      registry.delete(name.to_sym)
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [#call]
+    # @raise [ArgumentError] when `name` isn't registered
+    def lookup(name)
+      registry[name] || begin
+        raise ArgumentError, "unknown validator: #{name}"
+      end
+    end
+
+    # Picks registered-validator keys out of a declaration's options and
+    # appends `:validate` (inline callable(s)) when present.
+    #
+    # @param options [Hash{Symbol => Object}] declaration options
+    # @option options [Object] :presence payload for the presence validator (`call`)
+    # @option options [Object] :absence payload for the absence validator (`call`)
+    # @option options [Object] :format payload for the format validator (`call`)
+    # @option options [Object] :inclusion payload for the inclusion validator (`call`)
+    # @option options [Object] :exclusion payload for the exclusion validator (`call`)
+    # @option options [Object] :length payload for the length validator (`call`)
+    # @option options [Object] :numeric payload for the numeric validator (`call`)
+    # @option options [Object, Array<Object>] :validate inline callable(s) (`Validators::Validate`)
+    # @return [Hash{Symbol => Object}] validator rules to run
+    def extract(options)
+      return EMPTY_HASH if options.empty?
+
+      rules = options.slice(*registry.keys)
+      rules = rules.merge(validate: options[:validate]) if options.key?(:validate)
+      rules
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer]
+    def size
+      registry.size
+    end
+
+    # Runs every rule against `value`, recording a failure message on
+    # `task.errors` under `name` for each failure. Respects `:allow_nil`
+    # and `:if`/`:unless` per-rule.
+    #
+    # @param task [Task]
+    # @param name [Symbol] attribute name for error reporting
+    # @param value [Object] value being validated
+    # @param rules [Hash{Symbol => Object}] from {#extract}
+    # @return [void]
+    def validate(task, name, value, rules)
+      return if rules.empty?
+
+      rules.each do |type, raw_options|
+        if type == :validate
+          Array(raw_options).each do |handler|
+            result = Validators::Validate.call(task, value, handler)
+            task.errors.add(name, result.message) if result.is_a?(Failure)
+          end
+          next
+        end
+
+        options = normalize_options(raw_options)
+        next if options.nil?
+
+        next if options[:allow_nil] && value.nil?
+        next unless Util.satisfied?(options[:if], options[:unless], task, value)
+
+        result = lookup(type).call(value, options)
+        next unless result.is_a?(Failure)
+
+        task.errors.add(name, result.message)
+      end
+    end
+
+    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
+        nil
+      when TrueClass
+        EMPTY_HASH
+      when Hash
+        raw_options
+      when Array
+        { in: raw_options }
+      when Regexp
+        { with: raw_options }
+      else
+        raise ArgumentError, "unsupported validator option format: #{raw_options.inspect}"
+      end
+    end
+
+  end
+end

data/lib/cmdx/version.rb

@@ -2,9 +2,7 @@
 
 module CMDx
 
-  # @return [String] the version of the CMDx gem
-  #
-  # @rbs return: String
-  VERSION = "1.20.0"
+  # Gem version. Bumped on release; mirrored in the gemspec.
+  VERSION = "2.0.0"
 
 end

data/lib/cmdx/workflow.rb

@@ -1,115 +1,107 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Provides workflow execution capabilities by organizing tasks into execution groups.
-  # Workflows allow you to define sequences of tasks that can be executed conditionally
-  # with breakpoint handling and context management.
+  # Mixin that turns a {Task} subclass into a workflow: a pipeline of
+  # ordered task groups run sequentially or in parallel. Defining `#work`
+  # on a workflow is forbidden — `#work` is auto-generated to delegate to
+  # {Pipeline}. Subclasses inherit the parent's pipeline (via dup).
+  #
+  # @see Pipeline
   module Workflow
 
     module ClassMethods
 
-      # Prevents redefinition of the work method to maintain workflow integrity.
-      #
-      # @param method_name [Symbol] The name of the method being added
-      #
-      # @raise [RuntimeError] If attempting to redefine the work method
-      #
-      # @example
-      #   class MyWorkflow
-      #     include CMDx::Workflow
-      #     # This would raise an error:
-      #     # def work; end
-      #   end
-      #
-      # @rbs (Symbol method_name) -> void
-      def method_added(method_name)
-        raise "cannot redefine #{name}##{method_name} method" if method_name == :work
-
+      # @api private
+      # @param subclass [Class] newly defined workflow subclass
+      # @return [void]
+      def inherited(subclass)
         super
+        subclass.instance_variable_set(:@pipeline, pipeline.dup)
       end
 
-      # Returns the collection of execution groups for this workflow.
-      #
-      # @return [Array<ExecutionGroup>] Array of execution groups
-      #
-      # @example
-      #   class MyWorkflow
-      #     include CMDx::Workflow
-      #     task Task1
-      #     task Task2
-      #     puts pipeline.size # => 2
-      #   end
-      #
-      # @rbs () -> Array[ExecutionGroup]
+      # @return [Array<ExecutionGroup>] declared groups, in order
       def pipeline
         @pipeline ||= []
       end
 
-      # Adds multiple tasks to the workflow with optional configuration.
-      #
-      # @param tasks [Array<Class>] Array of task classes to add
-      # @param options [Hash] Configuration options for the task execution
-      # @option options [Hash] :breakpoints Breakpoints that trigger workflow interruption
-      # @option options [Hash] :conditions Conditional logic for task execution
-      #
-      # @raise [TypeError] If any task is not a CMDx::Task subclass
-      #
-      # @example
-      #   class MyWorkflow
-      #     include CMDx::Workflow
-      #     tasks ValidateTask, ProcessTask, NotifyTask, breakpoints: [:failure, :halt]
-      #   end
+      # Declares a task group. With no arguments, returns the pipeline.
+      # Tasks must be `Task` subclasses.
       #
-      # @rbs (*untyped tasks, **untyped options) -> void
+      # @param tasks [Array<Class<Task>>]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [:sequential, :parallel] :strategy (:sequential)
+      # @option options [Integer] :pool_size parallel worker/fiber count
+      # @option options [:threads, :fibers, #call] :executor (:threads) parallel
+      #   dispatch backend. `:fibers` requires a `Fiber.scheduler` to be
+      #   installed (e.g. `Async { ... }`). A custom callable accepting
+      #   `jobs:, concurrency:, on_job:` may also be passed.
+      # @option options [:last_write_wins, :deep_merge, :no_merge, #call] :merger
+      #   (:last_write_wins) how successful parallel contexts are folded back
+      #   into the workflow context. Merging happens in declaration order. A
+      #   callable `->(workflow_context, result) { ... }` may be passed to
+      #   implement custom behavior (e.g. namespacing by task name).
+      # @option options [Boolean] :continue_on_failure (false) when `true`,
+      #   run every task in the group to completion (even after a failure)
+      #   and aggregate all failures into the workflow's `errors`. Each
+      #   failed result's `errors` are merged in with keys namespaced as
+      #   `"TaskClass.input"`; failures with no errors entries (bare
+      #   `fail!("reason")`) record under `"TaskClass.<status>"` (e.g.
+      #   `"MyTask.failed"`) with `result.reason` as the message (falling
+      #   back to the localized `cmdx.reasons.unspecified` string when
+      #   `reason` is nil). The pipeline still halts after the group with
+      #   the first failure (declaration order) as the signal origin.
+      #   Applies to both `:sequential` and `:parallel` strategies. When
+      #   `false` (default), `:sequential` halts on the first failure and
+      #   `: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
+      # @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?
+
         pipeline << ExecutionGroup.new(
-          tasks.map do |task|
-            next task if task.is_a?(Class) && (task <= Task)
+          tasks:
+            tasks.map do |task|
+              next task if task.is_a?(Class) && (task <= Task)
 
-            raise TypeError, "must be a CMDx::Task"
-          end,
-          options
+              raise TypeError, "#{task.inspect} is not a Task"
+            end,
+          options:
         )
       end
       alias task tasks
 
+      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"
+      end
+
     end
 
-    # Represents a group of tasks with shared execution options.
-    # @attr tasks [Array<Class>] Array of task classes in this group
-    # @attr options [Hash] Configuration options for the group
-    ExecutionGroup = Struct.new(:tasks, :options)
+    # Immutable declaration of a task group.
+    ExecutionGroup = Data.define(:tasks, :options)
 
-    # Extends the including class with workflow capabilities.
-    #
-    # @param base [Class] The class including this module
-    #
-    # @example
-    #   class MyWorkflow
-    #     include CMDx::Workflow
-    #     # Now has access to task, tasks, and work methods
-    #   end
-    #
-    # @rbs (Class base) -> void
+    # @api private
+    # @param base [Class] task class including this mixin
+    # @return [void]
     def self.included(base)
       base.extend(ClassMethods)
     end
 
-    # Executes the workflow by processing all tasks in the pipeline.
-    # This method delegates execution to the Pipeline class which handles
-    # the processing of tasks with proper error handling and context management.
-    #
-    # @example
-    #   class MyWorkflow
-    #     include CMDx::Workflow
-    #     task ValidateTask
-    #     task ProcessTask
-    #   end
-    #
-    #   workflow = MyWorkflow.new
-    #   result = workflow.work
+    # Runs the workflow's pipeline. Not meant to be overridden.
     #
-    # @rbs () -> void
+    # @return [void]
     def work
       Pipeline.execute(self)
     end

data/lib/cmdx.rb

@@ -2,78 +2,147 @@
 
 require "bigdecimal"
 require "date"
-require "forwardable"
 require "json"
 require "logger"
-require "pathname"
 require "securerandom"
-require "set"
 require "time"
-require "timeout"
 require "yaml"
-require "zeitwerk"
 
 module CMDx
 
-  # @rbs EMPTY_ARRAY: Array[untyped]
+  # Frozen empty array reused as a sentinel return value to avoid per-call
+  # allocations on hot paths.
+  #
+  # @api private
   EMPTY_ARRAY = [].freeze
   private_constant :EMPTY_ARRAY
 
-  # @rbs EMPTY_HASH: Hash[untyped, untyped]
+  # Frozen empty hash reused as a sentinel return value to avoid per-call
+  # allocations on hot paths.
+  #
+  # @api private
   EMPTY_HASH = {}.freeze
   private_constant :EMPTY_HASH
 
-  # @rbs EMPTY_STRING: String
+  # Shared empty string constant used as a sentinel default. Intentionally
+  # not frozen so callers may treat it as a mutable seed when needed.
+  #
+  # @api private
   EMPTY_STRING = ""
   private_constant :EMPTY_STRING
 
-  extend self
+  # Root exception type for the library. Every CMDx-raised exception inherits
+  # from this class, so `rescue CMDx::Error` (or its alias `CMDx::Exception`)
+  # catches anything thrown by the framework without trapping unrelated
+  # `StandardError` descendants. {Fault} is the notable subclass propagated
+  # by `execute!`.
+  Error = Exception = Class.new(StandardError)
 
-  # Returns the path to the CMDx gem.
-  #
-  # @return [Pathname] the path to the CMDx gem
-  #
-  # @example
-  #   CMDx.gem_path # => Pathname.new("/path/to/cmdx")
-  #
-  # @rbs return: Pathname
-  def gem_path
-    @gem_path ||= Pathname.new(__dir__).parent
-  end
+  # Raised when an `around_execution` callback fails to invoke its
+  # continuation, which would otherwise silently skip the task body.
+  CallbackError = Class.new(Error)
 
-end
+  # Raised when a task or workflow attempts to define an input where an
+  # accessor with the same name already exists.
+  DefinitionError = Class.new(Error)
 
-# Set up Zeitwerk loader for the CMDx gem
-loader = Zeitwerk::Loader.for_gem
-loader.inflector.inflect("cmdx" => "CMDx", "json" => "JSON")
-loader.ignore("#{__dir__}/cmdx/configuration")
-loader.ignore("#{__dir__}/cmdx/exception")
-loader.ignore("#{__dir__}/cmdx/fault")
-loader.ignore("#{__dir__}/cmdx/railtie")
-loader.ignore("#{__dir__}/generators")
-loader.ignore("#{__dir__}/locales")
-loader.setup
+  # Raised by {Deprecation} when a task configured with `deprecation(:error)`
+  # is executed. Signals that the caller must migrate off the deprecated task
+  # before continuing.
+  DeprecationError = Class.new(Error)
 
-# Pre-load configuration to make module methods available
-# This is acceptable since configuration is fundamental to the framework
-require_relative "cmdx/configuration"
+  # 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.
+  ImplementationError = Class.new(Error)
 
-# Pre-load exceptions to make them available at the top level
-# This ensures CMDx::Error and its descendants are always available
-require_relative "cmdx/exception"
+  # Raised by the middleware chain when a registered middleware fails to
+  # yield to `next_link`, which would otherwise silently skip the task body.
+  MiddlewareError = Class.new(Error)
 
-# Pre-load fault classes to make them available at the top level
-# This ensures CMDx::FailFault and CMDx::SkipFault are always available
+end
+
+require_relative "cmdx/version"
 require_relative "cmdx/fault"
+require_relative "cmdx/util"
+require_relative "cmdx/i18n_proxy"
+require_relative "cmdx/logger_proxy"
+require_relative "cmdx/log_formatters/json"
+require_relative "cmdx/log_formatters/key_value"
+require_relative "cmdx/log_formatters/line"
+require_relative "cmdx/log_formatters/logstash"
+require_relative "cmdx/log_formatters/raw"
+require_relative "cmdx/coercions/array"
+require_relative "cmdx/coercions/big_decimal"
+require_relative "cmdx/coercions/boolean"
+require_relative "cmdx/coercions/complex"
+require_relative "cmdx/coercions/date"
+require_relative "cmdx/coercions/date_time"
+require_relative "cmdx/coercions/float"
+require_relative "cmdx/coercions/hash"
+require_relative "cmdx/coercions/integer"
+require_relative "cmdx/coercions/rational"
+require_relative "cmdx/coercions/string"
+require_relative "cmdx/coercions/symbol"
+require_relative "cmdx/coercions/time"
+require_relative "cmdx/coercions/coerce"
+require_relative "cmdx/coercions"
+require_relative "cmdx/validators/absence"
+require_relative "cmdx/validators/exclusion"
+require_relative "cmdx/validators/format"
+require_relative "cmdx/validators/inclusion"
+require_relative "cmdx/validators/length"
+require_relative "cmdx/validators/numeric"
+require_relative "cmdx/validators/presence"
+require_relative "cmdx/validators/validate"
+require_relative "cmdx/validators"
+require_relative "cmdx/executors/thread"
+require_relative "cmdx/executors/fiber"
+require_relative "cmdx/executors"
+require_relative "cmdx/mergers/last_write_wins"
+require_relative "cmdx/mergers/deep_merge"
+require_relative "cmdx/mergers/no_merge"
+require_relative "cmdx/mergers"
+require_relative "cmdx/retriers/exponential"
+require_relative "cmdx/retriers/half_random"
+require_relative "cmdx/retriers/full_random"
+require_relative "cmdx/retriers/bounded_random"
+require_relative "cmdx/retriers/linear"
+require_relative "cmdx/retriers/fibonacci"
+require_relative "cmdx/retriers/decorrelated_jitter"
+require_relative "cmdx/retriers"
+require_relative "cmdx/deprecators/log"
+require_relative "cmdx/deprecators/warn"
+require_relative "cmdx/deprecators/error"
+require_relative "cmdx/deprecators"
+require_relative "cmdx/input"
+require_relative "cmdx/inputs"
+require_relative "cmdx/output"
+require_relative "cmdx/outputs"
+require_relative "cmdx/callbacks"
+require_relative "cmdx/middlewares"
+require_relative "cmdx/telemetry"
+require_relative "cmdx/settings"
+require_relative "cmdx/retry"
+require_relative "cmdx/deprecation"
+require_relative "cmdx/context"
+require_relative "cmdx/chain"
+require_relative "cmdx/signal"
+require_relative "cmdx/result"
+require_relative "cmdx/pipeline"
+require_relative "cmdx/runtime"
+require_relative "cmdx/errors"
+require_relative "cmdx/task"
+require_relative "cmdx/workflow"
+require_relative "cmdx/configuration"
 
 # Conditionally load Rails components if Rails is available
 if defined?(Rails::Generators)
   require_relative "generators/cmdx/install_generator"
-  require_relative "generators/cmdx/locale_generator"
   require_relative "generators/cmdx/task_generator"
   require_relative "generators/cmdx/workflow_generator"
 end
 
-# Load the Railtie last after everything else is required so we don't
-# need to load any CMDx components when we use this Railtie.
+# Load the Railtie last after everything else is required so
+# we don't load any CMDx components when we use this Railtie.
 require_relative "cmdx/railtie" if defined?(Rails::Railtie)