cmdx 1.21.0 → 2.0.0

data/lib/cmdx/middlewares.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Ordered list of middlewares wrapping a task's lifecycle. Each middleware
+  # is a callable with the signature `call(task) { next_link.call }`; Runtime
+  # builds a nested chain and requires each middleware to yield to the next.
+  class Middlewares
+
+    attr_reader :registry
+
+    def initialize
+      @registry = []
+    end
+
+    # @param source [Middlewares] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.dup
+    end
+
+    # Inserts a middleware. With no `:at`, appends. With `:at`, inserts at
+    # the given (clamped) index — supports negative indexing. `:if`/`:unless`
+    # gates evaluated against the task at process time.
+    #
+    # @param callable [#call, nil] provide either this or a block
+    # @param block [#call, nil] middleware callable when `callable` is omitted
+    # @param options [Hash{Symbol => Object}]
+    # @option options [Symbol, Proc, #call] :if   gate that must evaluate truthy
+    # @option options [Symbol, Proc, #call] :unless gate that must evaluate falsy
+    # @option options [Integer] :at insertion index (see implementation)
+    # @return [Middlewares] self for chaining
+    # @raise [ArgumentError] when both or neither of `callable`/block are given,
+    #   when the callable doesn't respond to `#call`, or when `:at` isn't an Integer
+    # @yield the middleware body, receiving `(task)` and `next_link` via block
+    def register(callable = nil, **options, &block)
+      middleware = callable || block
+      at = options.delete(:at)
+
+      if callable && block
+        raise ArgumentError, "provide either a callable or a block, not both"
+      elsif !middleware.respond_to?(:call)
+        raise ArgumentError, "middleware must respond to #call"
+      elsif !at.nil? && !at.is_a?(Integer)
+        raise ArgumentError, "at must be an Integer"
+      end
+
+      entry = [middleware, options.freeze]
+
+      if at.nil?
+        registry << entry
+      else
+        at = [at.clamp(-registry.size - 1, registry.size), registry.size].min
+        registry.insert(at, entry)
+      end
+
+      self
+    end
+
+    # Removes a middleware by reference or by index.
+    #
+    # @param middleware [#call, nil] the exact middleware to remove
+    # @param at [Integer, nil] index to remove
+    # @return [Middlewares] self for chaining
+    # @raise [ArgumentError] when neither or both of `middleware`/`:at` are given,
+    #   or when `:at` isn't an Integer
+    def deregister(middleware = nil, at: nil)
+      if at.nil? && middleware.nil?
+        raise ArgumentError, "provide either a middleware or an at: index"
+      elsif !at.nil? && !middleware.nil?
+        raise ArgumentError, "provide either a middleware or an at: index, not both"
+      elsif !at.nil? && !at.is_a?(Integer)
+        raise ArgumentError, "at must be an Integer"
+      end
+
+      if at.nil?
+        registry.reject! { |mw, _opts| mw == middleware }
+      else
+        registry.delete_at(at)
+      end
+
+      self
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer]
+    def size
+      registry.size
+    end
+
+    # Walks the middleware chain around `task`'s lifecycle. The final link
+    # yields to `block`, which is expected to run the actual lifecycle.
+    #
+    # @param task [Task]
+    # @yield the innermost link — the task's lifecycle body
+    # @return [void]
+    # @raise [MiddlewareError] when a middleware forgets to yield to `next_link`,
+    #   which would otherwise silently skip the task
+    def process(task)
+      processed = false
+      count = registry.size
+
+      chain = lambda do |i|
+        if i == count
+          processed = true
+          yield
+        else
+          mw, opts = registry[i]
+
+          if Util.satisfied?(opts[:if], opts[:unless], task)
+            mw.call(task) { chain.call(i + 1) }
+          else
+            chain.call(i + 1)
+          end
+        end
+      end
+      chain.call(0)
+
+      processed || begin
+        raise MiddlewareError, "middleware did not yield the next_link"
+      end
+    end
+
+  end
+end

data/lib/cmdx/output.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module CMDx
+  # A single declared output. Runtime calls {#verify} after `work` to enforce
+  # presence on `task.context[name]` (every declared output is implicitly
+  # required) and to apply `:default`. `:if`/`:unless` gate verification entirely.
+  class Output
+
+    attr_reader :name
+
+    # @param name [Symbol, String] output key (symbolized)
+    # @param options [Hash{Symbol => Object}] declaration options
+    # @option options [String] :description (also accepts `:desc`)
+    # @option options [Symbol, Proc, #call] :if
+    # @option options [Symbol, Proc, #call] :unless
+    # @option options [Object, Symbol, Proc, #call] :default
+    def initialize(name, **options)
+      @name    = name.to_sym
+      @options = options.freeze
+    end
+
+    # @return [String, nil]
+    def description
+      @options[:description] || @options[:desc]
+    end
+
+    # @return [Object, Symbol, Proc, #call, nil]
+    def default
+      @options[:default]
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def condition_if
+      @options[:if]
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def condition_unless
+      @options[:unless]
+    end
+
+    # @return [Hash{Symbol => Object}] serialized schema for `outputs_schema`
+    def to_h
+      {
+        name:,
+        description:,
+        options: @options
+      }
+    end
+
+    # JSON-friendly hash view. Aliases {#to_h} for conventional `as_json`
+    # callers (e.g. Rails).
+    #
+    # @return [Hash{Symbol => Object}]
+    def as_json(*)
+      to_h
+    end
+
+    # Serializes the output schema to a JSON string. Non-primitive entries in
+    # `:options` (Procs, arbitrary callables) emit via their stdlib `to_json`
+    # defaults.
+    #
+    # @param args [Array] forwarded to `Hash#to_json`
+    # @return [String]
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Enforces the output contract against `task.context[name]` after `work` runs.
+    #
+    # Steps, in order:
+    # 1. Skips entirely when `:if`/`:unless` excludes it.
+    # 2. Reads the value from `task.context` and falls back to `:default` when nil.
+    # 3. Adds a `cmdx.outputs.missing` error when neither the key nor a default
+    #    supplied a value (every declared output is implicitly required).
+    # 4. Writes the resolved value back to `task.context[name]`.
+    #
+    # @param task [Task] the running task whose context is inspected and mutated
+    # @return [void]
+    def verify(task)
+      return unless Util.satisfied?(condition_if, condition_unless, task)
+
+      key_provided = task.context.key?(name)
+      value        = task.context[name]
+      value        = apply_default(task) if value.nil?
+
+      if !key_provided && value.nil?
+        task.errors.add(name, I18nProxy.t("cmdx.outputs.missing"))
+        return
+      end
+
+      task.context[name] = value
+    end
+
+    private
+
+    # @param task [Task]
+    # @return [Object, nil]
+    def apply_default(task)
+      return if default.nil?
+
+      case default
+      when Symbol
+        task.send(default)
+      when Proc
+        task.instance_exec(&default)
+      else
+        return default unless default.respond_to?(:call)
+
+        default.call(task)
+      end
+    end
+
+  end
+end

data/lib/cmdx/outputs.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry of declared task outputs. Runtime verifies each output after
+  # `work` completes: presence and defaults run against values the task wrote
+  # to context.
+  class Outputs
+
+    attr_reader :registry
+
+    def initialize
+      @registry = {}
+    end
+
+    # @param source [Outputs] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.dup
+    end
+
+    # Declares one or more output keys. All share the same `options`.
+    #
+    # @param keys [Array<Symbol>]
+    # @param options [Hash{Symbol => Object}] passed through to {Output#initialize}
+    # @option options [String] :description (also accepts `:desc`)
+    # @option options [Symbol, Proc, #call] :if
+    # @option options [Symbol, Proc, #call] :unless
+    # @option options [Object, Symbol, Proc, #call] :default
+    # @return [Outputs] self for chaining
+    def register(*keys, **options)
+      keys.each do |key|
+        output = Output.new(key, **options)
+        registry[output.name] = output
+      end
+
+      self
+    end
+
+    # @param keys [Array<Symbol>]
+    # @return [Outputs] self for chaining
+    def deregister(*keys)
+      keys.each { |key| registry.delete(key.to_sym) }
+      self
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer]
+    def size
+      registry.size
+    end
+
+    # Verifies every declared output against `task.context`. Adds any failures
+    # to `task.errors`.
+    #
+    # @param task [Task]
+    # @return [void]
+    def verify(task)
+      registry.each_value { |output| output.verify(task) }
+    end
+
+  end
+end

data/lib/cmdx/pipeline.rb

@@ -1,168 +1,181 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Executes workflows by processing task groups with conditional logic and breakpoint handling.
-  # The Pipeline class manages the execution flow of workflow tasks, evaluating conditions
-  # and handling breakpoints that can interrupt execution at specific task statuses.
+  # Runs a Workflow's declared task groups. Each group selects a strategy
+  # (`:sequential` by default, or `:parallel`). A group failure halts the
+  # pipeline by echoing the failed result's signal through `throw!`, which
+  # bubbles up through Runtime as the workflow's own failure.
+  #
+  # Groups may opt into batch semantics with `continue_on_failure: true`,
+  # in which case every task in the group runs to completion and all
+  # failures are aggregated into the workflow's `errors` (keyed as
+  # `"TaskClass.input"` for input/validation errors and `"TaskClass.<status>"`
+  # for bare `fail!` reasons) before the pipeline halts on the first
+  # failure (declaration order).
+  #
+  # @see Workflow
   class Pipeline
 
-    # @rbs SEQUENTIAL_REGEXP: Regexp
-    SEQUENTIAL_REGEXP = /\Asequential\z/
-    private_constant :SEQUENTIAL_REGEXP
+    class << self
 
-    # @rbs PARALLEL_REGEXP: Regexp
-    PARALLEL_REGEXP = /\Aparallel\z/
-    private_constant :PARALLEL_REGEXP
+      # @param workflow [Task] workflow instance whose class includes {Workflow}
+      # @return [void]
+      def execute(workflow)
+        new(workflow).execute
+      end
 
-    # 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
+    end
 
-    # @param workflow [Workflow] The workflow to execute
-    #
-    # @return [Pipeline] A new pipeline instance
-    #
-    # @example
-    #   pipeline = Pipeline.new(my_workflow)
-    #
-    # @rbs (Workflow workflow) -> void
+    # @param workflow [Task] workflow instance whose class includes {Workflow}
     def initialize(workflow)
       @workflow = workflow
+      @executed = []
     end
 
-    # Executes a workflow using a new pipeline instance.
+    # Iterates every group in the workflow's pipeline, respecting
+    # `:if`/`:unless` and the `:strategy` key. Any group that produces a
+    # failed result halts execution by throwing through the workflow.
     #
-    # @param workflow [Workflow] The workflow to execute
+    # On halt, every previously executed task instance whose result is
+    # `success?` is sent `#rollback` (when defined) in reverse execution
+    # order, providing saga-style compensation. Each compensated result
+    # has its `:rolled_back` option flipped to `true`. Skipped tasks are
+    # excluded; the failing task itself is rolled back by {Runtime} and
+    # is not re-invoked here. Exceptions raised inside a compensator
+    # propagate — handling them is the developer's responsibility.
     #
     # @return [void]
-    #
-    # @example
-    #   Pipeline.execute(my_workflow)
-    #
-    # @rbs (Workflow workflow) -> void
-    def self.execute(workflow)
-      new(workflow).execute
-    end
-
-    # Executes the workflow by processing all task groups in sequence.
-    # Each group is evaluated against its conditions, and breakpoints are checked
-    # after each task execution to determine if workflow should continue or halt.
-    #
-    # @return [void]
-    #
-    # @example
-    #   pipeline = Pipeline.new(my_workflow)
-    #   pipeline.execute
-    #
-    # @rbs () -> void
+    # @raise [ArgumentError] for an unknown strategy
+    # @raise [StandardError] anything raised by a task's `#rollback`
     def execute
-      default_breakpoints = Utils::Normalize.statuses(
-        workflow.class.settings.breakpoints ||
-        workflow.class.settings.workflow_breakpoints
-      )
-
-      workflow.class.pipeline.each do |group|
-        next unless Utils::Condition.evaluate(workflow, group.options)
-
-        breakpoints =
-          if group.options.key?(:breakpoints)
-            Utils::Normalize.statuses(group.options[:breakpoints])
+      @workflow.class.pipeline.each do |group|
+        next unless Util.satisfied?(group.options[:if], group.options[:unless], @workflow)
+
+        halt =
+          case strategy = group.options[:strategy]
+          when :sequential, NilClass
+            run_sequential(group)
+          when :parallel
+            run_parallel(group)
           else
-            default_breakpoints
+            raise ArgumentError, "invalid strategy: #{strategy.inspect}"
           end
 
-        execute_group_tasks(group, breakpoints)
+        next unless halt
+
+        rollback_executed!
+        @workflow.send(:throw!, halt)
       end
     end
 
     private
 
-    # Executes a group of tasks using the specified execution strategy.
-    #
-    # @param group [CMDx::Group] The task group to execute
-    # @param breakpoints [Array<Symbol>] Status values that trigger execution breaks
-    # @option group.options [Symbol, String] :strategy Execution strategy (:sequential, :parallel, or nil for default)
-    #
-    # @return [void]
-    #
-    # @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_REGEXP then execute_tasks_in_sequence(group, breakpoints)
-      when PARALLEL_REGEXP then execute_tasks_in_parallel(group, breakpoints)
-      else raise "unknown execution strategy #{strategy.inspect}"
+    # @param group [Workflow::ExecutionGroup]
+    # @return [Result, nil] failed result to halt on, or nil when the group succeeds
+    def run_sequential(group)
+      continue = group.options[:continue_on_failure]
+      failures = group.tasks.each_with_object([]) do |task_class, bucket|
+        instance = task_class.new(@workflow.context)
+        result   = instance.execute(strict: false)
+        @executed << [instance, result]
+        next unless result.failed?
+
+        bucket << result
+        break bucket unless continue
       end
+
+      aggregate(failures, continue:)
     end
 
-    # Executes tasks sequentially within a group, checking breakpoints after each task.
-    # If a task result status matches a breakpoint, the workflow is interrupted.
-    #
-    # @param group [ExecutionGroup] The group of tasks to execute
-    # @param breakpoints [Array<String>] Breakpoint statuses that trigger workflow interruption
-    #
-    # @return [void]
-    #
-    # @raise [HaltError] When a task result status matches a breakpoint
-    #
-    # @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)
-        next unless breakpoints.include?(task_result.status)
+    # @param group [Workflow::ExecutionGroup]
+    # @return [Result, nil] failed result to halt on, or nil when the group succeeds
+    def run_parallel(group)
+      tasks     = group.tasks
+      chain     = Chain.current
+      size      = group.options[:pool_size] || tasks.size
+      continue  = group.options[:continue_on_failure]
+      entries   = Array.new(tasks.size)
+      mutex     = Mutex.new
+      seen_fail = false
+      cancelled = false
+
+      jobs = tasks.each_with_index.to_a
+
+      on_job = lambda do |(task_class, index)|
+        mutex.synchronize { return if cancelled }
+
+        Fiber[Chain::STORAGE_KEY] ||= chain
+        ctx_copy = @workflow.context.deep_dup
+        instance = task_class.new(ctx_copy)
+        result   = instance.execute(strict: false)
+
+        mutex.synchronize do
+          entries[index] = [instance, result]
+
+          if result.failed? && !continue && !seen_fail
+            seen_fail = true
+            cancelled = true
+          end
+        end
+      end
+
+      executor = @workflow.class.executors.resolve(group.options[:executor])
+      merger   = @workflow.class.mergers.resolve(group.options[:merger])
+
+      executor.call(jobs:, concurrency: size, on_job:)
 
-        workflow.throw!(task_result)
+      failures = []
+      entries.each do |entry|
+        next if entry.nil?
+
+        @executed << entry
+        _instance, result = entry
+
+        if result.failed?
+          failures << result
+        else
+          merger.call(@workflow.context, result)
+        end
       end
+
+      aggregate(failures, continue:)
     end
 
-    # Each task receives a snapshot of the workflow context to prevent
-    # unsynchronized concurrent writes to a shared Hash. Snapshots are
-    # merged back into the workflow context after all tasks complete.
-    #
-    # @param group [CMDx::Group] The task group to execute in parallel
-    # @param breakpoints [Array<String>] Status values that trigger execution breaks
-    # @option group.options [Integer] :pool_size Number of concurrent threads (defaults to task count)
-    #
-    # @return [void]
-    #
-    # @raise [Fault] When a task result status matches a breakpoint
-    #
-    # @example
-    #   execute_tasks_in_parallel(group, ["failed"])
-    #
-    # @rbs (untyped group, Array[String] breakpoints) -> void
-    def execute_tasks_in_parallel(group, breakpoints)
-      contexts = group.tasks.map { Context.new(workflow.context.to_h) }
-      ctx_pairs = group.tasks.zip(contexts)
-      pool_size = group.options.fetch(:pool_size, ctx_pairs.size)
-
-      results = Parallelizer.call(ctx_pairs, pool_size:) do |task, context|
-        Chain.current = workflow.chain
-        task.execute(context)
-      end
+    def rollback_executed!
+      @executed.reverse_each do |instance, result|
+        next unless result.success?
+        next unless instance.respond_to?(:rollback)
+
+        instance.rollback
 
-      contexts.each { |ctx| workflow.context.merge!(ctx) }
+        old_opts = result.instance_variable_get(:@options)
+        new_opts = old_opts.merge(rolled_back: true).freeze
+        result.instance_variable_set(:@options, new_opts)
+      end
+    end
 
-      faulted = results.select { |r| breakpoints.include?(r.status) }
-      return if faulted.empty?
+    # @param failures [Array<Result>]
+    # @param continue [Boolean] when true, merges failures into the workflow's errors
+    # @return [Result, nil] first failure (echoed upstream), or nil when `failures` is empty
+    def aggregate(failures, continue:)
+      return if failures.empty?
+      return failures.first unless continue
+
+      failures.each do |result|
+        prefix = result.task.name
+
+        if result.errors.empty?
+          message = I18nProxy.tr(result.reason)
+          @workflow.errors.add(:"#{prefix}.#{result.status}", message)
+        else
+          result.errors.each do |key, messages|
+            namespaced = :"#{prefix}.#{key}"
+            messages.each { |message| @workflow.errors.add(namespaced, message) }
+          end
+        end
+      end
 
-      workflow.public_send(
-        :"#{faulted.last.status}!",
-        Locale.t("cmdx.reasons.unspecified"),
-        source: :parallel,
-        faults: faulted.map(&:to_h)
-      )
+      failures.first
     end
 
   end

data/lib/cmdx/railtie.rb

@@ -1,47 +1,21 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Rails integration class that automatically configures CMDx when the Rails
-  # application initializes. Handles locale configuration and I18n setup.
+  # Rails integration. Loaded only when `Rails::Railtie` is defined. Wires the
+  # app's `I18n.load_path` so CMDx locale files for each available locale are
+  # available, and points the CMDx logger and backtrace cleaner at Rails.
   class Railtie < Rails::Railtie
 
     railtie_name :cmdx
 
-    # Configures CMDx locales during Rails application initialization.
-    #
-    # Iterates through available locales from the Rails configuration and loads
-    # corresponding CMDx locale files. Reloads the I18n system to ensure
-    # all locales are properly registered.
-    #
-    # @param app [Rails::Application] the Rails application instance
-    #
-    # @raise [LoadError] if locale files cannot be loaded
-    #
-    # @example
-    #   # 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|
-      Utils::Wrap.array(app.config.i18n.available_locales).each do |locale|
-        path = CMDx.gem_path.join("lib/locales/#{locale}.yml")
-        next unless File.file?(path)
+    initializer("cmdx.configure_rails") do |app|
+      available_locales = app.config.i18n.available_locales.join(",")
+      locale_path = File.expand_path("../locales/{#{available_locales}}.yml", __dir__)
+      ::I18n.load_path += Dir[locale_path]
 
-        ::I18n.load_path << path
-      end
-
-      ::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)
+      CMDx.configure do |config|
+        config.logger = Rails.logger
+        config.backtrace_cleaner = ->(bt) { Rails.backtrace_cleaner.clean(bt) }
       end
     end