cmdx 1.18.0 → 1.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80c55fa1f758dc69cebff57fa5dd770b4bd7692f4a37768c320b6813d28cc9fb
-  data.tar.gz: babf14b98faa436de370d039cc2b6c796f2d0c43d9e408137ccdd1f666f4abe3
+  metadata.gz: 34ebd45d6a27296d5960995fc1b313b808f1d3835df82ce688ae1a6dc4faa313
+  data.tar.gz: 01ccc099ffd40950e4085c850ba3959db59bddbb5df39e8b540a6310607f7a59
 SHA512:
-  metadata.gz: cbcb58370126bc18aec53218930b11a7c6a3194b4b1e1c6247ae2d6e693ef16f84cc4dbf90a7dbd816e900f421e625cac3ca227aca7ce4898fa711c1451230e0
-  data.tar.gz: de88ce41eacbf4f843803f84055d46dcfb7774aa5532396c820112a5ca3d80d68deb9dbc296f8b782d990122ed6ccc082bbc582f93d3714373c2705c55a936fe
+  metadata.gz: 9cadc2e6c98e819512a62eb484c7ffb5ed2ea29bf135851441cb78fa4bb64421b844337d489976c4148c0e471144159640257dc20d574a802e90619d833c2316
+  data.tar.gz: 3edd420426ccc2ed48b1bc3f972984111eb10ec1f41bd835de478318cb5dba169cb440c5ff24b202533a942040a62aaf9897d88f03229cc97285ea69af11a377

data/CHANGELOG.md

@@ -6,14 +6,76 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [UNRELEASED]
 
-## [1.18.0] - 2025-03-09
+## [1.20.0] - 2026-03-12
+
+### Added
+- Add `CallbackRegistry#empty?` for fast callback presence checking
+- Add `Parallelizer` class for bounded thread pool execution
+- Add `Configuration#default_locale` setting (defaults to `"en"`)
+- Add `Task.type` to return task mechanics
+- Add `Utils::Normalize` module for exception and status normalization
+- Add `Utils::Wrap` module for array value normalization
+- Add `Retry` class for retry logic, state tracking, and jitter computation
+- Add `Settings` object with method-based access
+- Add `freeze_results` configuration option to replace `SKIP_CMDX_FREEZING` env var
+- Add `any?`, `clear`, and `size` delegators to `Errors`
+- Add `Context#respond_to_missing?` for setter methods
+- Add `Attribute#clear_task_tree!` to prevent stale task instance retention
+- Add thread-safe `Chain#push` and `Chain#index` via `Mutex`
+- Add identity-aware `Executor#clear_chain!` for parallel execution safety
+- Add `Executor#verify_middleware_yield!` to detect non-yielding middlewares
+- Add copy-on-write semantics to `MiddlewareRegistry`, `CallbackRegistry`, `CoercionRegistry`, and `ValidatorRegistry`
+- Add `Attribute#allocation_name` for task-free reader name resolution
+- Add `AttributeRegistry#define_readers_on!` and `#undefine_readers_on!` for eager reader definition
+
+### Changed
+- Short-circuit `Executor#post_execution!` when callback registry is empty
+- Optimize `Context#method_missing` to avoid `String` allocation on getter path
+- Replace `parallel` gem with native `Parallelizer` thread pool
+- Rename `in_threads` option to `pool_size`
+- Move `TimeoutError` to `exception.rb` for Zeitwerk autoloading
+- Update Rails initializer install script
+- Dup attributes in `AttributeRegistry#define_and_verify` for thread-safe concurrent execution
+- Default `retry_on` to `[StandardError, CMDx::TimeoutError]`
+- Replace hash-based `settings[:]` with method-based `settings.` access
+- Lazy-load locale translations instead of eager-loading
+- Use compile-time method definition for `Identifier#generate` and `Chain`/`Correlate` `thread_or_fiber`
+- Use `define_method` on task class for attribute readers
+- Tighten `Deprecator` regex to exact word boundaries
+- Use `public_send` instead of `send` in `Result` for state/status checks
+
+### Fixed
+- Fix `Attribute#source` and `#method_name` memoization without a task
+- Fix `execute!` to call `executed!` before `post_execution!` on non-halt path
+- Clear `task.errors` before each retry attempt
+- Fix `Pipeline#execute_tasks_in_parallel` to snapshot context per thread
+- Reject `in_processes` and `in_reactors` options in parallel tasks
+
+### Removed
+- Remove `SKIP_CMDX_FREEZING` env var in favor of `CMDx.configuration.freeze_results`
+
+## [1.19.0] - 2026-03-09
+
+### Changed
+- Fall back attribute `source` to `:context` when no task is given
+- Improve falsy attribute derived hash value lookup
+- Freeze chain results
+- Use `to_date`, `to_time`, `to_datetime` for date/time coercion checks
+
+### Fixed
+- Fix missing fault cause `NoMethodError`
+- Fix validator `allow_nil` inverted logic
+- Fix array coercion JSON parse error to return `CoercionError`
+- Fix boolean coercions to return `false` for `nil` and `""`
+
+## [1.18.0] - 2026-03-09
 
 ### Changed
 - Use `Fiber.storage` instead of `Thread.current` for `Chain` and `Correlate` storage, with fallback to `Thread.current` for Ruby < 3.2, making them thread and fiber safe
 - Clone shared logger in `Task#logger` when `log_level` or `log_formatter` is customized to prevent mutation of the shared instance
 - Derive attribute values from source objects that respond to the attribute name (via `send`) as fallback when the source is not callable
 
-## [1.17.0] - 2025-02-23
+## [1.17.0] - 2026-02-23
 
 ### Added
 - Add `returns` macro for context output validation after task execution
@@ -22,26 +84,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Add hash coercion for JSON `"null"` string as empty hash
 - Add attribute sourcing to support both string and symbol keys when sourcing/deriving from Hash
 
-## Changed
-- Do not fail coercion if nil on optional attributes
+### Changed
 - Include the source method in the required attribute error message
 
-## [1.16.0] - 2025-02-06
+### Fixed
+- Fix coercion to not fail on `nil` for optional attributes
+
+## [1.16.0] - 2026-02-06
 
 ### Added
 - Add `CMDx::Exception` alias for `CMDx::Error`
 
 ### Changed
-- Renamed `exceptions.rb` file to `exception.rb` (zeitwerk issue)
-- Renamed `faults.rb` file to `fault.rb` (zeitwerk issue)
+- Rename `exceptions.rb` file to `exception.rb` (zeitwerk compatibility)
+- Rename `faults.rb` file to `fault.rb` (zeitwerk compatibility)
 
-## [1.15.0] - 2025-01-21
+## [1.15.0] - 2026-01-21
 
 ### Added
 - Add attribute `Absence` validator
 - Add attribute `:description` option
 
-## [1.14.0] - 2025-01-09
+## [1.14.0] - 2026-01-09
 
 ### Added
 - Add Ruby 4.0 compatibility

data/README.md

@@ -12,9 +12,9 @@
   [Changelog](./CHANGELOG.md) ·
   [Report Bug](https://github.com/drexed/cmdx/issues) ·
   [Request Feature](https://github.com/drexed/cmdx/issues) ·
+  [AI Skills](https://github.com/drexed/cmdx/blob/main/skills) ·
   [llms.txt](https://drexed.github.io/cmdx/llms.txt) ·
   [llms-full.txt](https://drexed.github.io/cmdx/llms-full.txt) ·
-  [SKILL.md](https://github.com/drexed/cmdx/blob/main/docs/SKILL.md)
 
   <img alt="Version" src="https://img.shields.io/gem/v/cmdx">
   <img alt="Build" src="https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg">

data/lib/cmdx/attribute.rb

@@ -108,7 +108,7 @@ module CMDx
     def initialize(name, options = {}, &)
       @parent = options.delete(:parent)
       @required = options.delete(:required) || false
-      @types = Array(options.delete(:types) || options.delete(:type))
+      @types = Utils::Wrap.array(options.delete(:types) || options.delete(:type))
       @description = options.delete(:description) || options.delete(:desc)
 
       @name = name.to_sym
@@ -118,6 +118,21 @@ module CMDx
       instance_eval(&) if block_given?
     end
 
+    # Deep-copies children and clears task-dependent memoization so that
+    # duped attributes can be safely bound to a task without mutating the
+    # class-level originals. This makes concurrent execution thread-safe.
+    #
+    # @param source [Attribute] The attribute being duplicated
+    #
+    # @rbs (Attribute source) -> void
+    def initialize_dup(source)
+      super
+      @children = source.children.map(&:dup)
+      remove_instance_variable(:@source) if defined?(@source)
+      remove_instance_variable(:@method_name) if defined?(@method_name)
+      @task = nil
+    end
+
     class << self
 
       # Builds multiple attributes with the same configuration.
@@ -208,7 +223,8 @@ module CMDx
       !!@required
     end
 
-    # Determines the source of the attribute value.
+    # Determines the source of the attribute value. Returns :context
+    # as a safe fallback when task is not yet set (e.g., schema introspection).
     #
     # @return [Symbol] The source identifier for the attribute value
     #
@@ -217,15 +233,47 @@ module CMDx
     #
     # @rbs () -> untyped
     def source
-      @source ||= parent&.method_name || begin
+      return @source if defined?(@source)
+
+      parent&.method_name || begin
         value = options[:source]
 
         if value.is_a?(Proc)
-          task.instance_eval(&value)
+          task ? @source = task.instance_eval(&value) : :context
         elsif value.respond_to?(:call)
-          value.call(task)
+          task ? @source = value.call(task) : :context
         else
-          value || :context
+          @source = value || :context
+        end
+      end
+    end
+
+    # Returns the method name for this attribute when it can be resolved
+    # statically (without a task instance). Returns nil for Proc/callable
+    # sources whose method name depends on runtime evaluation.
+    #
+    # @return [Symbol, nil] The static method name, or nil if dynamic
+    #
+    # @example
+    #   attribute.allocation_name # => :user_name
+    #
+    # @rbs () -> Symbol?
+    def allocation_name
+      return @allocation_name if defined?(@allocation_name)
+
+      @allocation_name = options[:as] || begin
+        src = options[:source]
+        source_name =
+          if parent
+            parent.allocation_name
+          elsif !src.is_a?(Proc) && !src.respond_to?(:call)
+            src || :context
+          end
+
+        if source_name.is_a?(Symbol)
+          prefix = AFFIX.call(options[:prefix]) { "#{source_name}_" }
+          suffix = AFFIX.call(options[:suffix]) { "_#{source_name}" }
+          :"#{prefix}#{name}#{suffix}"
         end
       end
     end
@@ -239,12 +287,19 @@ module CMDx
     #
     # @rbs () -> Symbol
     def method_name
-      @method_name ||= options[:as] || begin
+      return @method_name if defined?(@method_name)
+
+      result = options[:as] || begin
         prefix = AFFIX.call(options[:prefix]) { "#{source}_" }
         suffix = AFFIX.call(options[:suffix]) { "_#{source}" }
-
         :"#{prefix}#{name}#{suffix}"
       end
+
+      # Only memoize if @source is defined to avoid memoizing method
+      # name when no task is present.
+      return result unless defined?(@source)
+
+      @method_name = result
     end
 
     # Defines and verifies the entire attribute tree including nested children.
@@ -259,6 +314,15 @@ module CMDx
       end
     end
 
+    # Recursively clears the task reference from this attribute and all children.
+    # Prevents the class-level attribute from retaining the last-executed task instance.
+    #
+    # @rbs () -> void
+    def clear_task_tree!
+      @task = nil
+      children.each(&:clear_task_tree!)
+    end
+
     # @return [Hash] A hash representation of the attribute
     #
     # @example
@@ -343,29 +407,33 @@ module CMDx
       attributes(*names, **options.merge(required: true), &)
     end
 
-    # Defines the attribute method on the task and validates the configuration.
+    # Defines the attribute reader on the task class (once) and
+    # generates/validates the per-instance value (every execution).
     #
     # @raise [RuntimeError] When the method name is already defined on the task
     #
     # @rbs () -> void
     def define_and_verify
-      if task.respond_to?(method_name, true)
-        raise <<~MESSAGE
-          The method #{method_name.inspect} is already defined on the #{task.class.name} task.
-          This may be due conflicts with one of the task's user defined or internal methods/attributes.
+      name_of_method = method_name
 
-          Use :as, :prefix, and/or :suffix attribute options to avoid conflicts with existing methods.
-        MESSAGE
+      unless task.class.method_defined?(name_of_method)
+        if task.respond_to?(name_of_method, true)
+          raise <<~MESSAGE
+            The method #{name_of_method.inspect} is already defined on the #{task.class.name} task.
+            This may be due conflicts with one of the task's user defined or internal methods/attributes.
+
+            Use :as, :prefix, and/or :suffix attribute options to avoid conflicts with existing methods.
+          MESSAGE
+        end
+
+        task.class.define_method(name_of_method) do
+          attributes[name_of_method]
+        end
       end
 
       attribute_value = AttributeValue.new(self)
       attribute_value.generate
       attribute_value.validate
-
-      name_of_method = method_name
-      task.define_singleton_method(name_of_method) do
-        attributes[name_of_method]
-      end
     end
 
   end

data/lib/cmdx/attribute_registry.rb

@@ -56,7 +56,7 @@ module CMDx
     #
     # @rbs (Attribute | Array[Attribute] attributes) -> self
     def register(attributes)
-      @registry.concat(Array(attributes))
+      @registry.concat(Utils::Wrap.array(attributes))
       self
     end
 
@@ -73,29 +73,100 @@ module CMDx
     #
     # @rbs ((Symbol | String | Array[Symbol | String]) names) -> self
     def deregister(names)
-      Array(names).each do |name|
+      Utils::Wrap.array(names).each do |name|
         @registry.reject! { |attribute| matches_attribute_tree?(attribute, name.to_sym) }
       end
 
       self
     end
 
-    # Associates all registered attributes with a task and verifies their definitions.
-    # This method is called during task setup to establish attribute-task relationships
-    # and validate the attribute hierarchy.
+    # Eagerly defines attribute reader methods on the task class for all
+    # attributes whose method names can be statically resolved. Called at
+    # class definition time so readers are defined once, not per-execution.
     #
-    # @param task [Task] The task to associate with all attributes
+    # @param task_class [Class] The task class to define readers on
+    # @param attrs [Array<Attribute>] Attributes to process (defaults to all)
+    #
+    # @rbs (Class task_class, ?Array[Attribute] attrs) -> void
+    def define_readers_on!(task_class, attrs = registry)
+      attrs.each { |attr| define_reader_tree!(task_class, attr) }
+    end
+
+    # Removes eagerly defined reader methods from the task class for
+    # attributes about to be deregistered. Must be called before {#deregister}.
+    #
+    # @param task_class [Class] The task class to undefine readers on
+    # @param names [Array<Symbol, String>] Attribute method names being removed
+    #
+    # @rbs (Class task_class, (Symbol | String | Array[Symbol | String]) names) -> void
+    def undefine_readers_on!(task_class, names)
+      Utils::Wrap.array(names).each do |name|
+        sym = name.to_sym
+
+        registry.each do |attribute|
+          next unless matches_attribute_tree?(attribute, sym)
+
+          undefine_reader_tree!(task_class, attribute)
+        end
+      end
+    end
+
+    # Verifies attribute definitions against a task instance.
+    # Each attribute is duped before binding so the class-level originals
+    # are never mutated — this eliminates the concurrency hazard of
+    # shared mutable @task, @source, and @method_name state.
+    #
+    # @param task [Task] The task to verify attributes against
     #
     # @rbs (Task task) -> void
     def define_and_verify(task)
       registry.each do |attribute|
-        attribute.task = task
-        attribute.define_and_verify_tree
+        duplicate = attribute.dup
+        duplicate.task = task
+        duplicate.define_and_verify_tree
       end
     end
 
     private
 
+    # Recursively defines reader methods for an attribute and its children
+    # when the method name is statically resolvable.
+    #
+    # @param task_class [Class] The task class to define readers on
+    # @param attribute [Attribute] The attribute to define a reader for
+    #
+    # @rbs (Class task_class, Attribute attribute) -> void
+    def define_reader_tree!(task_class, attribute)
+      name = attribute.allocation_name
+
+      if name && !task_class.method_defined?(name)
+        if task_class.private_method_defined?(name)
+          raise <<~MESSAGE
+            The method #{name.inspect} is already defined on the #{task_class.name} task.
+            This may be due conflicts with one of the task's user defined or internal methods/attributes.
+
+            Use :as, :prefix, and/or :suffix attribute options to avoid conflicts with existing methods.
+          MESSAGE
+        end
+
+        task_class.define_method(name) { attributes[name] }
+      end
+
+      attribute.children.each { |child| define_reader_tree!(task_class, child) }
+    end
+
+    # Recursively removes reader methods for an attribute and its children.
+    #
+    # @param task_class [Class] The task class to undefine readers on
+    # @param attribute [Attribute] The attribute whose readers to remove
+    #
+    # @rbs (Class task_class, Attribute attribute) -> void
+    def undefine_reader_tree!(task_class, attribute)
+      name = attribute.allocation_name
+      task_class.remove_method(name) if name && task_class.method_defined?(name, false)
+      attribute.children.each { |child| undefine_reader_tree!(task_class, child) }
+    end
+
     # Recursively checks if an attribute or any of its children match the given name.
     #
     # @param attribute [Attribute] The attribute to check

data/lib/cmdx/attribute_value.rb

@@ -81,7 +81,7 @@ module CMDx
     #
     # @rbs () -> void
     def validate
-      registry = task.class.settings[:validators]
+      registry = task.class.settings.validators
 
       options.slice(*registry.keys).each do |type, opts|
         registry.validate(type, task, value, opts)
@@ -166,7 +166,12 @@ module CMDx
       derived_value =
         case source_value
         when Context then source_value[name]
-        when Hash then source_value[name.to_s] || source_value[name.to_sym]
+        when Hash
+          if source_value.key?(name.to_s)
+            source_value[name.to_s]
+          elsif source_value.key?(name.to_sym)
+            source_value[name.to_sym]
+          end
         when Symbol then source_value.send(name)
         when Proc then task.instance_exec(name, &source_value)
         else
@@ -221,7 +226,7 @@ module CMDx
     def coerce_value(transformed_value)
       return transformed_value if types.empty?
 
-      registry = task.class.settings[:coercions]
+      registry = task.class.settings.coercions
       last_idx = types.size - 1
 
       types.find.with_index do |type, i|

data/lib/cmdx/callback_registry.rb

@@ -5,8 +5,13 @@ module CMDx
   #
   # Callbacks are organized by type and can be registered with optional conditions and options.
   # Each callback type represents a specific execution phase or outcome.
+  #
+  # Supports copy-on-write semantics: a duped registry shares the parent's
+  # data until a write operation triggers materialization.
   class CallbackRegistry
 
+    extend Forwardable
+
     # @rbs TYPES: Array[Symbol]
     TYPES = %i[
       before_validation
@@ -21,32 +26,43 @@ module CMDx
       on_bad
     ].freeze
 
-    # Returns the internal registry of callbacks organized by type.
-    #
-    # @return [Hash{Symbol => Set<Array>}] Hash mapping callback types to their registered callables
-    #
-    # @example
-    #   registry.registry # => { before_execution: #<Set: [[[:validate], {}]]> }
+    # @rbs TYPES_SET: Set[Symbol]
+    TYPES_SET = TYPES.to_set.freeze
+    private_constant :TYPES_SET
+
+    def_delegators :registry, :empty?
+
+    # @param registry [Hash, nil] Initial registry hash, defaults to empty
     #
-    # @rbs @registry: Hash[Symbol, Set[Array[untyped]]]
-    attr_reader :registry
-    alias to_h registry
+    # @rbs (?Hash[Symbol, Set[Array[untyped]]]? registry) -> void
+    def initialize(registry = nil)
+      @registry = registry || {}
+    end
 
-    # @param registry [Hash] Initial registry hash, defaults to empty
+    # Sets up copy-on-write state when duplicated via dup.
+    #
+    # @param source [CallbackRegistry] The registry being duplicated
     #
-    # @rbs (?Hash[Symbol, Set[Array[untyped]]] registry) -> void
-    def initialize(registry = {})
-      @registry = registry
+    # @rbs (CallbackRegistry source) -> void
+    def initialize_dup(source)
+      @parent = source
+      @registry = nil
+      super
     end
 
-    # Creates a deep copy of the registry with duplicated callable sets
+    # Returns the internal registry of callbacks organized by type.
+    # Delegates to the parent registry when not yet materialized.
     #
-    # @return [CallbackRegistry] A new instance with duplicated registry contents
+    # @return [Hash{Symbol => Set<Array>}] Hash mapping callback types to their registered callables
     #
-    # @rbs () -> CallbackRegistry
-    def dup
-      self.class.new(registry.transform_values(&:dup))
+    # @example
+    #   registry.registry # => { before_execution: #<Set: [[[:validate], {}]]> }
+    #
+    # @rbs () -> Hash[Symbol, Set[Array[untyped]]]
+    def registry
+      @registry || @parent.registry
     end
+    alias to_h registry
 
     # Registers one or more callables for a specific callback type
     #
@@ -70,10 +86,12 @@ module CMDx
     #
     # @rbs (Symbol type, *untyped callables, **untyped options) ?{ (Task) -> void } -> self
     def register(type, *callables, **options, &block)
+      materialize!
+
       callables << block if block_given?
 
-      registry[type] ||= Set.new
-      registry[type] << [callables, options]
+      @registry[type] ||= Set.new
+      @registry[type] << [callables, options]
       self
     end
 
@@ -92,11 +110,13 @@ module CMDx
     #
     # @rbs (Symbol type, *untyped callables, **untyped options) ?{ (Task) -> void } -> self
     def deregister(type, *callables, **options, &block)
+      materialize!
+
       callables << block if block_given?
-      return self unless registry[type]
+      return self unless @registry[type]
 
-      registry[type].delete([callables, options])
-      registry.delete(type) if registry[type].empty?
+      @registry[type].delete([callables, options])
+      @registry.delete(type) if @registry[type].empty?
       self
     end
 
@@ -112,12 +132,13 @@ module CMDx
     #
     # @rbs (Symbol type, Task task) -> void
     def invoke(type, task)
-      raise TypeError, "unknown callback type #{type.inspect}" unless TYPES.include?(type)
+      raise TypeError, "unknown callback type #{type.inspect}" unless TYPES_SET.include?(type)
+      return unless registry[type]
 
-      Array(registry[type]).each do |callables, options|
+      registry[type].each do |callables, options|
         next unless Utils::Condition.evaluate(task, options)
 
-        Array(callables).each do |callable|
+        Utils::Wrap.array(callables).each do |callable|
           if callable.is_a?(Symbol)
             task.send(callable)
           elsif callable.is_a?(Proc)
@@ -131,5 +152,18 @@ module CMDx
       end
     end
 
+    private
+
+    # Copies the parent's registry data into this instance,
+    # severing the copy-on-write link.
+    #
+    # @rbs () -> void
+    def materialize!
+      return if @registry
+
+      @registry = @parent.registry.transform_values(&:dup)
+      @parent = nil
+    end
+
   end
 end