cmdx 2.0.0 → 2.1.0

data/lib/cmdx/context.rb

@@ -47,10 +47,25 @@ module CMDx
         elsif context.respond_to?(:to_h)
           context.to_h
         else
-          raise ArgumentError, "must respond to `to_h` or `to_hash`"
+          raise ArgumentError, <<~MSG.chomp
+            Context.build expected a Hash or an object responding to #to_h/#to_hash (got #{context.class}).
+            See https://drexed.github.io/cmdx/basics/context/#assigning-data
+          MSG
         end.transform_keys(&:to_sym)
     end
 
+    # Ensures `#dup` / `#clone` produce a context with an independent backing
+    # hash so mutations on the copy do not leak into the original. `@strict`
+    # is preserved on the copy.
+    #
+    # @param source [Context]
+    # @return [void]
+    def initialize_copy(source)
+      super
+      @table  = source.instance_variable_get(:@table).dup
+      @strict = source.strict?
+    end
+
     # @return [Boolean] whether dynamic reads for unknown keys raise instead
     #   of returning `nil`
     def strict?
@@ -87,7 +102,7 @@ module CMDx
     # @return [Context] self for chaining
     def deep_merge(context = EMPTY_HASH)
       other = self.class.build(context)
-      @table = compute_deep_merge(@table, other.to_h)
+      @table = Util.deep_merge(@table, other.to_h)
       self
     end
 
@@ -202,9 +217,11 @@ module CMDx
       @table.hash
     end
 
-    # @return [Hash{Symbol => Object}] the underlying table (not a copy)
+    # @return [Hash{Symbol => Object}] a shallow copy of the underlying table.
+    #   Frozen contexts return the frozen table directly to preserve
+    #   `Hash#frozen?` semantics for serialization callers.
     def to_h
-      @table
+      @table.frozen? ? @table : @table.dup
     end
 
     # JSON-friendly hash view. Aliases {#to_h} for conventional `as_json`
@@ -227,7 +244,14 @@ module CMDx
 
     # @return [String] space-separated `key=value.inspect` pairs
     def to_s
-      @table.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+      buf = String.new(capacity: 256)
+
+      @table.each do |k, v|
+        buf << " " unless buf.empty?
+        buf << k.to_s << "=" << v.inspect
+      end
+
+      buf
     end
 
     # Pattern-matching support for `case context in {...}`.
@@ -247,12 +271,13 @@ module CMDx
 
     # Returns a deep copy. Non-mutable scalars are shared; Hashes/Arrays are
     # recursively duplicated; other objects fall back to `#dup` (and then
-    # to the original on `StandardError`).
+    # to the original on `StandardError`). `@strict` is preserved on the copy.
     #
     # @return [Context]
     def deep_dup
       ctx = self.class.allocate
-      ctx.instance_variable_set(:@table, compute_deep_dup(@table))
+      ctx.instance_variable_set(:@table, Util.deep_dup(@table))
+      ctx.instance_variable_set(:@strict, @strict)
       ctx
     end
 
@@ -267,65 +292,24 @@ module CMDx
 
     private
 
-    # Provides dynamic read/write/predicate access to context keys.
-    #
-    # - `ctx.name` — reads `@table[name]`, `nil` when absent (raises
-    #   `NoMethodError` when {#strict?} is true and the key is absent).
-    # - `ctx.name = val` — stores `val` under `:name`.
-    # - `ctx.name?` — truthy check for `@table[:name]`.
-    #
-    # @param method_name [Symbol] dynamic reader/writer/predicate name
-    # @param args [Array<Object>] stores RHS for writers (`name=` → `[value]`)
-    # @param _kwargs [Hash{Symbol => Object}] ignored (accepted for Ruby keyword forwarding)
-    # @option _kwargs [Object] ignored
-    # @raise [NoMethodError] when {#strict?} is true and the key is missing
-    # @api private
     def method_missing(method_name, *args, **_kwargs, &)
-      if method_name.end_with?("=")
+      if @table.key?(method_name)
+        @table[method_name]
+      elsif method_name.end_with?("=")
         @table[method_name[..-2].to_sym] = args.first
       elsif method_name.end_with?("?")
         !!@table[method_name[..-2].to_sym]
-      elsif strict? && !@table.key?(method_name)
-        raise NoMethodError, "unknown context key #{method_name.inspect} (strict mode)"
-      else
-        @table[method_name]
+      elsif strict?
+        raise UnknownAccessorError, <<~MSG.chomp
+          unknown context key #{method_name.inspect} (strict mode); declared keys: #{@table.keys.inspect}.
+          See https://drexed.github.io/cmdx/basics/context/#strict-mode
+        MSG
       end
     end
 
-    # @param method_name [Symbol]
-    # @param include_private [Boolean] forwarded to Ruby's `respond_to?` lookup
-    # @return [Boolean]
     def respond_to_missing?(method_name, include_private = false)
       @table.key?(method_name) || method_name.end_with?("=", "?") || super
     end
 
-    # @param value [Object] nested value from the context table
-    # @return [Object] recursively duplicated scalar/collection snapshot
-    def compute_deep_dup(value)
-      case value
-      when Numeric, Symbol, TrueClass, FalseClass, NilClass
-        value
-      when Hash
-        value.each_with_object({}) { |(k, v), acc| acc[k] = compute_deep_dup(v) }
-      when Array
-        value.map { |e| compute_deep_dup(e) }
-      else
-        begin
-          value.dup
-        rescue StandardError
-          value
-        end
-      end
-    end
-
-    # @param lhs [Hash]
-    # @param rhs [Hash]
-    # @return [Hash] merged hash (recursive for nested `{Hash => Hash}` pairs)
-    def compute_deep_merge(lhs, rhs)
-      lhs.merge(rhs) do |_key, l, r|
-        l.is_a?(Hash) && r.is_a?(Hash) ? compute_deep_merge(l, r) : r
-      end
-    end
-
   end
 end

data/lib/cmdx/deprecation.rb

@@ -43,18 +43,15 @@ module CMDx
       else
         return @value.call(task) if @value.respond_to?(:call)
 
-        raise ArgumentError, "deprecation must be a Symbol, Proc, or respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          deprecation must be a Symbol, Proc, or respond to #call (got #{@value.class}).
+          See https://drexed.github.io/cmdx/deprecation/#declarations
+        MSG
       end
     end
 
     private
 
-    # Resolves the deprecators registry to consult for built-in actions.
-    # Prefers the task class's registry (so per-task `register(:deprecator, ...)`
-    # overrides take effect) and falls back to the global configuration.
-    #
-    # @param task [Task]
-    # @return [Deprecators]
     def deprecators_registry(task)
       if task.class.respond_to?(:deprecators)
         task.class.deprecators

data/lib/cmdx/deprecators/error.rb

@@ -14,7 +14,10 @@ module CMDx
       # @return [void]
       # @raise [DeprecationError]
       def call(task)
-        raise DeprecationError, "#{task.class} usage prohibited"
+        raise DeprecationError, <<~MSG.chomp
+          #{task.class} is deprecated and prohibited from execution.
+          See https://drexed.github.io/cmdx/deprecation/#error
+        MSG
       end
 
     end

data/lib/cmdx/deprecators.rb

@@ -36,9 +36,12 @@ module CMDx
       deprecator = callable || block
 
       if callable && block
-        raise ArgumentError, "provide either a callable or a block, not both"
+        raise ArgumentError, "deprecator: provide either a callable or a block, not both"
       elsif !deprecator.respond_to?(:call)
-        raise ArgumentError, "deprecator must respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          deprecator must respond to #call (got #{deprecator.class}).
+          See https://drexed.github.io/cmdx/deprecation/#custom-actions-via-the-deprecators-registry
+        MSG
       end
 
       registry[name.to_sym] = deprecator
@@ -48,22 +51,25 @@ module CMDx
     # @param name [Symbol]
     # @return [Deprecators] self for chaining
     def deregister(name)
-      registry.delete(name.to_sym)
+      registry.delete(name)
       self
     end
 
     # @param name [Symbol]
     # @return [Boolean] whether a deprecator is registered under `name`
     def key?(name)
-      registry.key?(name.to_sym)
+      registry.key?(name)
     end
 
     # @param name [Symbol]
     # @return [#call] the registered deprecator
-    # @raise [ArgumentError] when `name` isn't registered
+    # @raise [UnknownEntryError] when `name` isn't registered
     def lookup(name)
       registry[name] || begin
-        raise ArgumentError, "unknown deprecator: #{name.inspect}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown deprecator #{name.inspect}; registered: #{registry.keys.inspect}.
+          See https://drexed.github.io/cmdx/deprecation/#custom-actions-via-the-deprecators-registry
+        MSG
       end
     end
 
@@ -73,7 +79,7 @@ module CMDx
     #
     # @param spec [Symbol, #call, nil]
     # @return [#call, nil]
-    # @raise [ArgumentError] when `spec` is an unknown symbol or not callable
+    # @raise [UnknownEntryError] when `spec` is an unknown symbol or not callable
     def resolve(spec)
       case spec
       when NilClass
@@ -83,7 +89,10 @@ module CMDx
       else
         return spec if spec.respond_to?(:call)
 
-        raise ArgumentError, "unknown deprecator: #{spec.inspect}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown deprecator #{spec.inspect}; expected a Symbol from #{registry.keys.inspect} or a callable.
+          See https://drexed.github.io/cmdx/deprecation/#custom-actions-via-the-deprecators-registry
+        MSG
       end
     end
 

data/lib/cmdx/errors.rb

@@ -15,12 +15,13 @@ module CMDx
     end
 
     # Adds `message` under `key`. Duplicate messages are silently dropped.
+    # `key` is coerced to a Symbol to match {Context}'s key normalization.
     #
-    # @param key [Symbol]
+    # @param key [Symbol, String]
     # @param message [String]
     # @return [Set<String>] the set of messages now stored under `key`
     def add(key, message)
-      (messages[key] ||= Set.new) << message
+      (messages[key.to_sym] ||= Set.new) << message
     end
     alias []= add
 
@@ -40,23 +41,23 @@ module CMDx
       end
     end
 
-    # @param key [Symbol]
+    # @param key [Symbol, String]
     # @return [Array<String>] messages for `key`, or a frozen empty array
     def [](key)
-      messages[key]&.to_a || EMPTY_ARRAY
+      messages[key.to_sym]&.to_a || EMPTY_ARRAY
     end
 
-    # @param key [Symbol]
+    # @param key [Symbol, String]
     # @param message [String]
     # @return [Boolean] true when `message` is recorded under `key`
     def added?(key, message)
-      !!messages[key]&.include?(message)
+      !!messages[key.to_sym]&.include?(message)
     end
 
-    # @param key [Symbol]
+    # @param key [Symbol, String]
     # @return [Boolean]
     def key?(key)
-      messages.key?(key)
+      messages.key?(key.to_sym)
     end
     alias for? key?
 
@@ -98,10 +99,10 @@ module CMDx
       messages.each_value(&)
     end
 
-    # @param key [Symbol]
+    # @param key [Symbol, String]
     # @return [Set<String>, nil] the removed set, or nil when absent
     def delete(key)
-      messages.delete(key)
+      messages.delete(key.to_sym)
     end
 
     # @return [Hash{Symbol => Set<String>}] empties the container
@@ -113,7 +114,10 @@ module CMDx
     #   (e.g. `{ name: ["name is required"] }`)
     def full_messages
       messages.each_with_object({}) do |(key, set), hash|
-        hash[key] = set.map { |message| "#{key} #{message}" }
+        hash[key] = set.map do |message|
+          i18n_message = I18nProxy.t(message, default: message)
+          "#{key} #{i18n_message}"
+        end
       end
     end
 

data/lib/cmdx/executors/fiber.rb

@@ -5,7 +5,8 @@ module CMDx
     # 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.
+    # `async` gem). `pool_size` caps in-flight fibers. Exceptions raised inside
+    # `on_job` are captured and re-raised once every fiber has completed.
     #
     # @api private
     module Fiber
@@ -13,21 +14,30 @@ module CMDx
       extend self
 
       # @param jobs [Array]
-      # @param concurrency [Integer] max in-flight fibers
+      # @param concurrency [Integer] max in-flight fibers (must be >= 1)
       # @param on_job [#call]
       # @return [void]
+      # @raise [ArgumentError] when `concurrency` is not a positive Integer
       # @raise [RuntimeError] when no `Fiber.scheduler` is installed
+      # @raise [StandardError] re-raises the first exception captured from any fiber
       def call(jobs:, concurrency:, on_job:)
+        raise ArgumentError, "executor concurrency must be a positive Integer (got #{concurrency.inspect})" unless concurrency.is_a?(Integer) && concurrency.positive?
+
         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
+        done   = Queue.new
+        errors = Queue.new
 
         jobs.each do |job|
           slots.pop
           ::Fiber.schedule do
-            on_job.call(job)
+            begin
+              on_job.call(job)
+            rescue StandardError => e
+              errors << e
+            end
           ensure
             slots << :slot
             done << true
@@ -35,6 +45,8 @@ module CMDx
         end
 
         jobs.size.times { done.pop }
+
+        raise errors.pop unless errors.empty?
       end
 
     end

data/lib/cmdx/executors/thread.rb

@@ -4,7 +4,9 @@ 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.
+    # fiber-local storage. Exceptions raised inside `on_job` are captured per
+    # worker and re-raised on the main thread once every worker has joined, so
+    # callers see failures instead of silently dropped jobs.
     #
     # @api private
     module Thread
@@ -12,23 +14,35 @@ module CMDx
       extend self
 
       # @param jobs [Array] opaque job objects forwarded to `on_job`
-      # @param concurrency [Integer] worker count
+      # @param concurrency [Integer] worker count (must be >= 1)
       # @param on_job [#call] unary callable invoked per job
       # @return [void]
+      # @raise [ArgumentError] when `concurrency` is not a positive Integer
+      # @raise [StandardError] re-raises the first exception captured from any worker
       def call(jobs:, concurrency:, on_job:)
-        queue = Queue.new
+        raise ArgumentError, "executor concurrency must be a positive Integer (got #{concurrency.inspect})" unless concurrency.is_a?(Integer) && concurrency.positive?
+
+        queue  = Queue.new
+        errors = 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)
+              begin
+                on_job.call(job)
+              rescue StandardError => e
+                errors << e
+              end
             end
           end
         end
 
         workers.each(&:join)
+
+        raise errors.pop unless errors.empty?
       end
 
     end

data/lib/cmdx/executors.rb

@@ -36,9 +36,12 @@ module CMDx
       executor = callable || block
 
       if callable && block
-        raise ArgumentError, "provide either a callable or a block, not both"
+        raise ArgumentError, "executor: provide either a callable or a block, not both"
       elsif !executor.respond_to?(:call)
-        raise ArgumentError, "executor must respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          executor must respond to #call (got #{executor.class}).
+          See https://drexed.github.io/cmdx/workflows/#executors
+        MSG
       end
 
       registry[name.to_sym] = executor
@@ -48,16 +51,25 @@ module CMDx
     # @param name [Symbol]
     # @return [Executors] self for chaining
     def deregister(name)
-      registry.delete(name.to_sym)
+      registry.delete(name)
       self
     end
 
+    # @param name [Symbol]
+    # @return [Boolean] whether an executor is registered under `name`
+    def key?(name)
+      registry.key?(name)
+    end
+
     # @param name [Symbol]
     # @return [#call] the registered executor
-    # @raise [ArgumentError] when `name` isn't registered
+    # @raise [UnknownEntryError] when `name` isn't registered
     def lookup(name)
       registry[name] || begin
-        raise ArgumentError, "unknown executor: #{name.inspect}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown executor #{name.inspect}; registered: #{registry.keys.inspect}.
+          See https://drexed.github.io/cmdx/workflows/#executors
+        MSG
       end
     end
 
@@ -67,7 +79,7 @@ module CMDx
     #
     # @param spec [Symbol, #call, nil]
     # @return [#call]
-    # @raise [ArgumentError] when `spec` is an unknown symbol or not callable
+    # @raise [UnknownEntryError] when `spec` is an unknown symbol or not callable
     def resolve(spec)
       case spec
       when NilClass
@@ -77,7 +89,10 @@ module CMDx
       else
         return spec if spec.respond_to?(:call)
 
-        raise ArgumentError, "unknown executor: #{spec.inspect}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown executor #{spec.inspect}; expected a Symbol from #{registry.keys.inspect} or a callable.
+          See https://drexed.github.io/cmdx/workflows/#executors
+        MSG
       end
     end
 

data/lib/cmdx/fault.rb

@@ -16,6 +16,10 @@ module CMDx
       # inherits from) any of the given task classes. Suitable for use in
       # `rescue`.
       #
+      # @note Each call allocates a new anonymous subclass. Hoist the matcher
+      #   to module scope (`MY_FAULT = CMDx::Fault.for?(MyTask)`) when used
+      #   on hot paths to avoid class allocation churn over time.
+      #
       # @param tasks [Array<Class>] one or more Task classes
       # @return [Class<Fault>] anonymous matcher subclass
       # @raise [ArgumentError] when no tasks are given
@@ -28,7 +32,7 @@ module CMDx
       #   end
       def for?(*tasks)
         tasks = tasks.flatten
-        raise ArgumentError, "at least one task required" if tasks.empty?
+        raise ArgumentError, "Fault.for? requires at least one Task class" if tasks.empty?
 
         matcher do |other|
           tasks.any? { |task| other.task <= task }
@@ -38,6 +42,10 @@ module CMDx
       # Returns a matcher subclass that matches Faults whose `result.reason`
       # is equal to the given string. Suitable for use in `rescue`.
       #
+      # @note Each call allocates a new anonymous subclass. Hoist the matcher
+      #   to module scope (`PAYMENT_FAULT = CMDx::Fault.reason?("Payment failed")`)
+      #   when used on hot paths to avoid class allocation churn.
+      #
       # @param reason [String] the reason to match
       # @return [Class<Fault>] anonymous matcher subclass
       # @raise [ArgumentError] when no reason is given
@@ -49,7 +57,7 @@ module CMDx
       #     Alert.for_fault(fault)
       #   end
       def reason?(reason)
-        raise ArgumentError, "reason required" unless reason
+        raise ArgumentError, "Fault.reason? requires a reason" unless reason
 
         matcher do |other|
           other.result.reason == reason
@@ -58,13 +66,17 @@ module CMDx
 
       # Returns a matcher subclass whose `===` runs `block` against the fault.
       #
+      # @note Each call allocates a new anonymous subclass. Hoist the matcher
+      #   to module scope when used on hot paths to avoid class allocation
+      #   churn.
+      #
       # @param block [#call] `(fault) -> Boolean` matcher body
       # @yieldparam fault [Fault]
       # @yieldreturn [Boolean]
       # @return [Class<Fault>] anonymous matcher subclass
       # @raise [ArgumentError] when no block is given
       def matches?(&block)
-        raise ArgumentError, "block required" unless block
+        raise ArgumentError, "Fault.matches? requires a block" unless block
 
         matcher(&block)
       end

data/lib/cmdx/i18n_proxy.rb

@@ -62,7 +62,7 @@ module CMDx
     # @option options [Hash{Symbol => Object}] extra keys interpolated via `String#%` for bundled translations
     # @return [String, Object] the translated/interpolated message
     def translate(key, **options)
-      return ::I18n.translate(key, **options) if defined?(::I18n) && ::I18n.respond_to?(:translate)
+      return ::I18n.translate(key, **options) if defined?(::I18n)
 
       message = translation_default(key) || options[:default]
 
@@ -79,8 +79,6 @@ module CMDx
 
     private
 
-    # @param key [String, Symbol] lookup key (without locale prefix)
-    # @return [Object, nil] message template from bundled YAML, when present
     def translation_default(key)
       default_locale  = CMDx.configuration.default_locale || "en"
       translation_key = "#{default_locale}.#{key}"
@@ -92,9 +90,15 @@ module CMDx
       @translations[default_locale] ||= begin
         file = "#{default_locale}.yml"
         paths = self.class.locale_paths.map { |dir| File.join(dir, file) }.select { |p| File.exist?(p) }
-        raise LoadError, "unable to load #{default_locale} translations" if paths.empty?
-
-        paths.reduce({}) { |hash, path| hash.merge(YAML.safe_load_file(path)) }.freeze
+        if paths.empty?
+          raise UnknownLocaleError, <<~MSG.chomp
+            unable to load #{default_locale.inspect} translations;
+            searched: #{self.class.locale_paths.map { |dir| File.join(dir, file) }.inspect}.
+            See https://drexed.github.io/cmdx/internationalization/#custom-locale-paths
+          MSG
+        end
+
+        paths.reduce({}) { |acc, path| Util.deep_merge(acc, YAML.safe_load_file(path)) }.freeze
       end
 
       @defaults[translation_key] = @translations[default_locale].dig(*translation_key.split("."))