cmdx 1.20.0 → 2.0.0

data/lib/cmdx/deprecators/log.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Deprecators
+    # Writes a `warn`-level entry to the task's logger noting the deprecation.
+    # Execution proceeds; useful for gradual migration where you want
+    # observability without breaking callers.
+    #
+    # @api private
+    module Log
+
+      extend self
+
+      # @param task [Task]
+      # @return [void]
+      def call(task)
+        task.logger.warn { "DEPRECATED: #{task.class} - migrate to a replacement or discontinue use" }
+      end
+
+    end
+  end
+end

data/lib/cmdx/deprecators/warn.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Deprecators
+    # Emits a Ruby warning to stderr via `Kernel.warn`. Visible during
+    # development and testing without polluting structured production logs.
+    #
+    # @api private
+    module Warn
+
+      extend self
+
+      # @param task [Task]
+      # @return [void]
+      def call(task)
+        Kernel.warn("[#{task.class}] DEPRECATED: migrate to a replacement or discontinue use")
+      end
+
+    end
+  end
+end

data/lib/cmdx/deprecators.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry of named deprecation actions consulted by `Deprecation#execute`
+  # to dispatch a task class's deprecation. Ships with built-ins for
+  # `:log`, `:warn`, and `:error`. A deprecator is any callable accepting
+  # `call(task)`; the return value is discarded.
+  class Deprecators
+
+    attr_reader :registry
+
+    def initialize
+      @registry = {
+        log: Deprecators::Log,
+        warn: Deprecators::Warn,
+        error: Deprecators::Error
+      }
+    end
+
+    # @param source [Deprecators] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.dup
+    end
+
+    # Registers a named deprecator, overwriting any existing entry.
+    #
+    # @param name [Symbol]
+    # @param callable [#call, nil] pass either this or a block
+    # @param block [#call, nil] deprecator callable when `callable` is omitted
+    # @yield deprecator body — `call(task)`
+    # @return [Deprecators] self for chaining
+    # @raise [ArgumentError] when both `callable` and a block are given, or
+    #   when the resolved deprecator isn't callable
+    def register(name, callable = nil, &block)
+      deprecator = callable || block
+
+      if callable && block
+        raise ArgumentError, "provide either a callable or a block, not both"
+      elsif !deprecator.respond_to?(:call)
+        raise ArgumentError, "deprecator must respond to #call"
+      end
+
+      registry[name.to_sym] = deprecator
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [Deprecators] self for chaining
+    def deregister(name)
+      registry.delete(name.to_sym)
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [Boolean] whether a deprecator is registered under `name`
+    def key?(name)
+      registry.key?(name.to_sym)
+    end
+
+    # @param name [Symbol]
+    # @return [#call] the registered deprecator
+    # @raise [ArgumentError] when `name` isn't registered
+    def lookup(name)
+      registry[name] || begin
+        raise ArgumentError, "unknown deprecator: #{name.inspect}"
+      end
+    end
+
+    # Resolves a `deprecation` declaration's value to a concrete callable.
+    # Accepts a Symbol (registry lookup) or any object responding to `#call`.
+    # `nil` resolves to `nil` so callers can short-circuit.
+    #
+    # @param spec [Symbol, #call, nil]
+    # @return [#call, nil]
+    # @raise [ArgumentError] when `spec` is an unknown symbol or not callable
+    def resolve(spec)
+      case spec
+      when NilClass
+        nil
+      when Symbol
+        lookup(spec)
+      else
+        return spec if spec.respond_to?(:call)
+
+        raise ArgumentError, "unknown deprecator: #{spec.inspect}"
+      end
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer]
+    def size
+      registry.size
+    end
+
+  end
+end

data/lib/cmdx/errors.rb

@@ -1,117 +1,183 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Collection of validation and execution errors organized by attribute.
-  # Provides methods to add, query, and format error messages for different
-  # attributes in a task or workflow execution.
+  # Per-task container of validation / coercion / output errors. Each key maps
+  # to a deduplicating Set of messages. A non-empty Errors forces Runtime to
+  # throw a failed signal (`signal_errors!`). Frozen on teardown by Runtime.
   class Errors
 
-    extend Forwardable
+    include Enumerable
 
-    # Returns the internal hash of error messages by attribute.
-    #
-    # @return [Hash{Symbol => Set<String>}] Hash mapping attribute names to error message sets
-    #
-    # @example
-    #   errors.messages # => { email: #<Set: ["must be valid", "is required"]> }
-    #
-    # @rbs @messages: Hash[Symbol, Set[String]]
     attr_reader :messages
 
-    def_delegators :messages, :any?, :clear, :empty?, :size
-
-    # Initialize a new error collection.
-    #
-    # @rbs () -> void
     def initialize
       @messages = {}
     end
 
-    # Add an error message for a specific attribute.
-    #
-    # @param attribute [Symbol] The attribute name associated with the error
-    # @param message [String] The error message to add
-    #
-    # @example
-    #   errors = CMDx::Errors.new
-    #   errors.add(:email, "must be valid format")
-    #   errors.add(:email, "cannot be blank")
+    # Adds `message` under `key`. Duplicate messages are silently dropped.
     #
-    # @rbs (Symbol attribute, String message) -> void
-    def add(attribute, message)
-      return if message.empty?
+    # @param key [Symbol]
+    # @param message [String]
+    # @return [Set<String>] the set of messages now stored under `key`
+    def add(key, message)
+      (messages[key] ||= Set.new) << message
+    end
+    alias []= add
 
-      messages[attribute] ||= Set.new
-      messages[attribute] << message
+    # Copies every message from `other` into self. Existing messages are
+    # preserved and duplicates (same key + message) are silently dropped by
+    # the underlying Set. Accepts any object that responds to `#to_hash`
+    # returning `Hash{Symbol => Enumerable<String>}` — typically another
+    # {Errors} instance.
+    #
+    # @param other [Errors, #to_hash]
+    # @return [void]
+    # @example Combine validation errors from a nested task
+    #   parent.errors.merge!(child.result.errors)
+    def merge!(other)
+      other.to_hash.each do |key, messages|
+        messages.each { |message| add(key, message) }
+      end
     end
 
-    # Check if there are any errors for a specific attribute.
-    #
-    # @param attribute [Symbol] The attribute name to check for errors
-    #
-    # @return [Boolean] true if the attribute has errors, false otherwise
-    #
-    # @example
-    #   errors.for?(:email) # => true
-    #   errors.for?(:name)  # => false
-    #
-    # @rbs (Symbol attribute) -> bool
-    def for?(attribute)
-      set = messages[attribute]
-      !set.nil? && !set.empty?
+    # @param key [Symbol]
+    # @return [Array<String>] messages for `key`, or a frozen empty array
+    def [](key)
+      messages[key]&.to_a || EMPTY_ARRAY
     end
 
-    # Convert errors to a hash format with arrays of full messages.
-    #
-    # @return [Hash{Symbol => Array<String>}] Hash with attribute keys and message arrays
-    #
-    # @example
-    #   errors.full_messages # => { email: ["email must be valid format", "email cannot be blank"] }
-    #
-    # @rbs () -> Hash[Symbol, Array[String]]
+    # @param key [Symbol]
+    # @param message [String]
+    # @return [Boolean] true when `message` is recorded under `key`
+    def added?(key, message)
+      !!messages[key]&.include?(message)
+    end
+
+    # @param key [Symbol]
+    # @return [Boolean]
+    def key?(key)
+      messages.key?(key)
+    end
+    alias for? key?
+
+    # @return [Array<Symbol>] keys with at least one message
+    def keys
+      messages.keys
+    end
+
+    # @return [Boolean]
+    def empty?
+      messages.empty?
+    end
+
+    # @return [Integer] number of keyed entries
+    def size
+      messages.size
+    end
+
+    # @return [Integer] total messages across all keys
+    def count
+      messages.each_value.sum(&:size)
+    end
+
+    # @yield [key, set] each `[key, Set<String>]` pair
+    # @return [Errors, Enumerator]
+    def each(&)
+      messages.each(&)
+    end
+
+    # @yield [Symbol]
+    # @return [Errors, Enumerator]
+    def each_key(&)
+      messages.each_key(&)
+    end
+
+    # @yield [Set<String>]
+    # @return [Errors, Enumerator]
+    def each_value(&)
+      messages.each_value(&)
+    end
+
+    # @param key [Symbol]
+    # @return [Set<String>, nil] the removed set, or nil when absent
+    def delete(key)
+      messages.delete(key)
+    end
+
+    # @return [Hash{Symbol => Set<String>}] empties the container
+    def clear
+      messages.clear
+    end
+
+    # @return [Hash{Symbol => Array<String>}] messages prefixed with their key
+    #   (e.g. `{ name: ["name is required"] }`)
     def full_messages
-      messages.each_with_object({}) do |(attribute, messages), hash|
-        hash[attribute] = messages.map { |message| "#{attribute} #{message}" }
+      messages.each_with_object({}) do |(key, set), hash|
+        hash[key] = set.map { |message| "#{key} #{message}" }
       end
     end
 
-    # Convert errors to a hash format with arrays of messages.
-    #
-    # @return [Hash{Symbol => Array<String>}] Hash with attribute keys and message arrays
-    #
-    # @example
-    #   errors.to_h # => { email: ["must be valid format", "cannot be blank"] }
-    #
-    # @rbs () -> Hash[Symbol, Array[String]]
+    # @return [Hash{Symbol => Array<String>}] raw messages as arrays
     def to_h
       messages.transform_values(&:to_a)
     end
 
-    # Convert errors to a hash format with optional full messages.
-    #
-    # @param full [Boolean] Whether to include full messages with attribute names
-    # @return [Hash{Symbol => Array<String>}] Hash with attribute keys and message arrays
-    #
-    # @example
-    #   errors.to_hash # => { email: ["must be valid format", "cannot be blank"] }
-    #   errors.to_hash(true) # => { email: ["email must be valid format", "email cannot be blank"] }
-    #
-    # @rbs (?bool full) -> Hash[Symbol, Array[String]]
+    # @param full [Boolean] when true return {#full_messages}, otherwise {#to_h}
+    # @return [Hash{Symbol => Array<String>}]
     def to_hash(full = false)
       full ? full_messages : to_h
     end
 
-    # Convert errors to a human-readable string format.
-    #
-    # @return [String] Formatted error messages joined with periods
+    # JSON-friendly hash view. Aliases {#to_h} for conventional `as_json`
+    # callers (e.g. Rails).
     #
-    # @example
-    #   errors.to_s # => "email must be valid format. email cannot be blank"
+    # @return [Hash{Symbol => Array<String>}]
+    def as_json(*)
+      to_h
+    end
+
+    # Serializes the error messages to a JSON string. Symbol keys are
+    # emitted as strings by the `json` stdlib.
     #
-    # @rbs () -> String
+    # @param args [Array] forwarded to `Hash#to_json`
+    # @return [String]
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # @return [String] all full messages joined with `". "`, suitable as a
+    #   fail reason
     def to_s
       full_messages.values.flatten.join(". ")
     end
 
+    # Pattern-matching support for `case errors in {...}`.
+    #
+    # @param keys [Array<Symbol>, nil] restrict the returned hash to these keys
+    # @return [Hash{Symbol => Array<String>}]
+    #
+    # @example
+    #   case task.errors
+    #   in { name: [_, *] } then handle_name_errors(task)
+    #   end
+    def deconstruct_keys(keys)
+      keys.nil? ? to_h : to_h.slice(*keys)
+    end
+
+    # Pattern-matching support for `case errors in [...]`.
+    #
+    # @return [Array<Array(Symbol, Array<String>)>]
+    def deconstruct
+      to_h.to_a
+    end
+
+    # Freezes the container and every message set. Called by Runtime teardown.
+    #
+    # @return [Errors] self
+    def freeze
+      messages.each_value(&:freeze).freeze
+      super
+    end
+
   end
 end

data/lib/cmdx/executors/fiber.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Executors
+    # Fiber-scheduler backed executor. Spawns one fiber per job, bounded by
+    # `concurrency` via a `SizedQueue` semaphore. Requires a Fiber scheduler to
+    # be installed on the current thread (e.g. inside `Async { ... }` from the
+    # `async` gem). `pool_size` caps in-flight fibers.
+    #
+    # @api private
+    module Fiber
+
+      extend self
+
+      # @param jobs [Array]
+      # @param concurrency [Integer] max in-flight fibers
+      # @param on_job [#call]
+      # @return [void]
+      # @raise [RuntimeError] when no `Fiber.scheduler` is installed
+      def call(jobs:, concurrency:, on_job:)
+        raise "executor: :fibers requires Fiber.scheduler; run the workflow inside a scheduler block (e.g. Async { ... })" unless ::Fiber.scheduler
+
+        slots = SizedQueue.new(concurrency)
+        concurrency.times { slots << :slot }
+        done = Queue.new
+
+        jobs.each do |job|
+          slots.pop
+          ::Fiber.schedule do
+            on_job.call(job)
+          ensure
+            slots << :slot
+            done << true
+          end
+        end
+
+        jobs.size.times { done.pop }
+      end
+
+    end
+  end
+end

data/lib/cmdx/executors/thread.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Executors
+    # Default executor. Uses a fixed-size `Thread` pool drained via a `Queue`;
+    # sentinel `nil`s terminate workers. Workers inherit the parent's chain via
+    # fiber-local storage.
+    #
+    # @api private
+    module Thread
+
+      extend self
+
+      # @param jobs [Array] opaque job objects forwarded to `on_job`
+      # @param concurrency [Integer] worker count
+      # @param on_job [#call] unary callable invoked per job
+      # @return [void]
+      def call(jobs:, concurrency:, on_job:)
+        queue = Queue.new
+        jobs.each { |job| queue << job }
+        concurrency.times { queue << nil }
+
+        workers = Array.new(concurrency) do
+          ::Thread.new do
+            while (job = queue.pop)
+              on_job.call(job)
+            end
+          end
+        end
+
+        workers.each(&:join)
+      end
+
+    end
+  end
+end

data/lib/cmdx/executors.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry of named executors used by `:parallel` workflow groups to
+  # dispatch tasks concurrently. Ships with built-ins for `:threads` and
+  # `:fibers`. Executors are any callable accepting
+  # `call(jobs:, concurrency:, on_job:)` and must invoke `on_job.call(job)`
+  # for each job, blocking until every job is done.
+  class Executors
+
+    attr_reader :registry
+
+    def initialize
+      @registry = {
+        threads: Executors::Thread,
+        fibers: Executors::Fiber
+      }
+    end
+
+    # @param source [Executors] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.dup
+    end
+
+    # Registers a named executor, overwriting any existing entry.
+    #
+    # @param name [Symbol]
+    # @param callable [#call, nil] pass either this or a block
+    # @param block [#call, nil] executor callable when `callable` is omitted
+    # @yield executor body — `call(jobs:, concurrency:, on_job:)`
+    # @return [Executors] self for chaining
+    # @raise [ArgumentError] when both `callable` and a block are given, or
+    #   when the resolved executor isn't callable
+    def register(name, callable = nil, &block)
+      executor = callable || block
+
+      if callable && block
+        raise ArgumentError, "provide either a callable or a block, not both"
+      elsif !executor.respond_to?(:call)
+        raise ArgumentError, "executor must respond to #call"
+      end
+
+      registry[name.to_sym] = executor
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [Executors] self for chaining
+    def deregister(name)
+      registry.delete(name.to_sym)
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [#call] the registered executor
+    # @raise [ArgumentError] when `name` isn't registered
+    def lookup(name)
+      registry[name] || begin
+        raise ArgumentError, "unknown executor: #{name.inspect}"
+      end
+    end
+
+    # Resolves a declaration's `:executor` option to a concrete callable.
+    # Accepts `nil` (default `:threads`), a Symbol (registry lookup), or any
+    # object responding to `#call`.
+    #
+    # @param spec [Symbol, #call, nil]
+    # @return [#call]
+    # @raise [ArgumentError] when `spec` is an unknown symbol or not callable
+    def resolve(spec)
+      case spec
+      when NilClass
+        lookup(:threads)
+      when Symbol
+        lookup(spec)
+      else
+        return spec if spec.respond_to?(:call)
+
+        raise ArgumentError, "unknown executor: #{spec.inspect}"
+      end
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer]
+    def size
+      registry.size
+    end
+
+  end
+end