cmdx 1.21.0 → 2.0.0

data/lib/cmdx/attribute_registry.rb

@@ -1,185 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Manages a collection of attributes for task definition and verification.
-  # The registry provides methods to register, deregister, and process attributes
-  # in a hierarchical structure, supporting nested attribute definitions.
-  class AttributeRegistry
-
-    # Returns the collection of registered attributes.
-    #
-    # @return [Array<Attribute>] Array of registered attributes
-    #
-    # @example
-    #   registry.registry # => [#<Attribute @name=:name>, #<Attribute @name=:email>]
-    #
-    # @rbs @registry: Array[Attribute]
-    attr_reader :registry
-    alias to_a registry
-
-    # Creates a new attribute registry with an optional initial collection.
-    #
-    # @param registry [Array<Attribute>] Initial attributes to register
-    #
-    # @return [AttributeRegistry] A new registry instance
-    #
-    # @example
-    #   registry = AttributeRegistry.new
-    #   registry = AttributeRegistry.new([attr1, attr2])
-    #
-    # @rbs (?Array[Attribute] registry) -> void
-    def initialize(registry = [])
-      @registry = registry
-    end
-
-    # Creates a duplicate of this registry with copied attributes.
-    #
-    # @return [AttributeRegistry] A new registry with duplicated attributes
-    #
-    # @example
-    #   new_registry = registry.dup
-    #
-    # @rbs () -> AttributeRegistry
-    def dup
-      self.class.new(registry.dup)
-    end
-
-    # Registers one or more attributes to the registry.
-    #
-    # @param attributes [Attribute, Array<Attribute>] Attribute(s) to register
-    #
-    # @return [AttributeRegistry] Self for method chaining
-    #
-    # @example
-    #   registry.register(attribute)
-    #   registry.register([attr1, attr2])
-    #
-    # @rbs (Attribute | Array[Attribute] attributes) -> self
-    def register(attributes)
-      @registry.concat(Utils::Wrap.array(attributes))
-      self
-    end
-
-    # Removes attributes from the registry by name.
-    # Supports hierarchical attribute removal by matching the entire attribute tree.
-    #
-    # @param names [Symbol, String, Array<Symbol, String>] Name(s) of attributes to remove
-    #
-    # @return [AttributeRegistry] Self for method chaining
-    #
-    # @example
-    #   registry.deregister(:name)
-    #   registry.deregister(['name1', 'name2'])
-    #
-    # @rbs ((Symbol | String | Array[Symbol | String]) names) -> self
-    def deregister(names)
-      Utils::Wrap.array(names).each do |name|
-        @registry.reject! { |attribute| matches_attribute_tree?(attribute, name.to_sym) }
-      end
-
-      self
-    end
-
-    # 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_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|
-        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
-    # @param name [Symbol] The name to match against
-    #
-    # @return [Boolean] True if the attribute or any child matches the name
-    #
-    # @rbs (Attribute attribute, Symbol name) -> bool
-    def matches_attribute_tree?(attribute, name)
-      return true if attribute.method_name == name
-
-      attribute.children.any? { |child| matches_attribute_tree?(child, name) }
-    end
-
-  end
-end

data/lib/cmdx/attribute_value.rb

@@ -1,252 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Manages the value lifecycle for a single attribute within a task.
-  # Handles value sourcing, derivation, coercion, and validation through
-  # a coordinated pipeline that ensures data integrity and type safety.
-  class AttributeValue
-
-    extend Forwardable
-
-    # Returns the attribute managed by this value handler.
-    #
-    # @return [Attribute] The attribute instance
-    #
-    # @example
-    #   attr_value.attribute.name # => :user_id
-    #
-    # @rbs @attribute: Attribute
-    attr_reader :attribute
-
-    def_delegators :attribute, :task, :parent, :name, :options, :types, :source, :method_name, :required?, :optional?
-    def_delegators :task, :attributes, :errors
-
-    # Creates a new attribute value manager for the given attribute.
-    #
-    # @param attribute [Attribute] The attribute to manage values for
-    #
-    # @example
-    #   attr = Attribute.new(:user_id, required: true)
-    #   attr_value = AttributeValue.new(attr)
-    #
-    # @rbs (Attribute attribute) -> void
-    def initialize(attribute)
-      @attribute = attribute
-    end
-
-    # Retrieves the current value for this attribute from the task's attributes.
-    #
-    # @return [Object, nil] The current attribute value or nil if not set
-    #
-    # @example
-    #   attr_value.value # => "john_doe"
-    #
-    # @rbs () -> untyped
-    def value
-      attributes[method_name]
-    end
-
-    # Generates the attribute value through the complete pipeline:
-    # sourcing, derivation, coercion, and storage.
-    #
-    # @return [Object, nil] The generated value or nil if generation failed
-    #
-    # @example
-    #   attr_value.generate # => 42
-    #
-    # @rbs () -> untyped
-    def generate
-      return value if attributes.key?(method_name)
-
-      sourced_value = source_value
-      return if errors.for?(method_name)
-
-      derived_value = derive_value(sourced_value)
-      return if errors.for?(method_name)
-
-      coerced_value = coerce_value(derived_value)
-      transformed_value = transform_value(coerced_value)
-      return if errors.for?(method_name)
-
-      attributes[method_name] = transformed_value
-    end
-
-    # Validates the current attribute value against configured validators.
-    #
-    # @raise [ValidationError] When validation fails (handled internally)
-    #
-    # @example
-    #   attr_value.validate
-    #   # Validates value against :presence, :format, etc.
-    #
-    # @rbs () -> void
-    def validate
-      registry = task.class.settings.validators
-
-      options.slice(*registry.keys).each do |type, opts|
-        registry.validate(type, task, value, opts)
-      rescue ValidationError => e
-        errors.add(method_name, e.message)
-        nil
-      end
-    end
-
-    private
-
-    # Retrieves the source value for this attribute from various sources.
-    #
-    # @return [Object, nil] The sourced value or nil if unavailable
-    #
-    # @raise [NoMethodError] When the source method doesn't exist
-    #
-    # @example
-    #   # Sources from task method, proc, or direct value
-    #   source_value # => "raw_value"
-    # @rbs () -> untyped
-    def source_value
-      sourced_value =
-        case source
-        when Symbol then task.send(source)
-        when Proc then task.instance_eval(&source)
-        else source.respond_to?(:call) ? source.call(task) : source
-        end
-
-      if required? && (parent.nil? || parent&.required?) && Utils::Condition.evaluate(task, options)
-        case sourced_value
-        when Context then sourced_value.key?(name)
-        when Hash then sourced_value.key?(name.to_s) || sourced_value.key?(name.to_sym)
-        when Proc then true # HACK: Cannot be determined so assume it will respond
-        else sourced_value.respond_to?(name, true)
-        end || errors.add(method_name, Locale.t("cmdx.attributes.required", method: source))
-      end
-
-      sourced_value
-    rescue NoMethodError
-      errors.add(method_name, Locale.t("cmdx.attributes.undefined", method: source))
-      nil
-    end
-
-    # Retrieves the default value for this attribute if configured.
-    #
-    # @return [Object, nil] The default value or nil if not configured
-    #
-    # @example
-    #   # Default can be symbol, proc, or direct value
-    #   -> { rand(100) } # => 23
-    #
-    # @rbs () -> untyped
-    def default_value
-      default = options[:default]
-
-      if default.is_a?(Symbol) && task.respond_to?(default, true)
-        task.send(default)
-      elsif default.is_a?(Proc)
-        task.instance_eval(&default)
-      elsif default.respond_to?(:call)
-        default.call(task)
-      else
-        default
-      end
-    end
-
-    # Derives the actual value from the source value using various strategies.
-    #
-    # @param source_value [Object] The source value to derive from
-    #
-    # @return [Object, nil] The derived value or nil if derivation failed
-    #
-    # @raise [NoMethodError] When the derivation method doesn't exist
-    #
-    # @example
-    #   # Derives from hash key, method call, or proc execution
-    #   context.user_id # => 42
-    #
-    # @rbs (untyped source_value) -> untyped
-    def derive_value(source_value)
-      derived_value =
-        case source_value
-        when Context then source_value[name]
-        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
-          if source_value.respond_to?(:call)
-            source_value.call(task, name)
-          elsif source_value.respond_to?(name, true)
-            source_value.send(name)
-          end
-        end
-
-      derived_value.nil? ? default_value : derived_value
-    rescue NoMethodError
-      errors.add(method_name, Locale.t("cmdx.attributes.undefined", method: name))
-      nil
-    end
-
-    # Transforms the derived value using the transform option.
-    #
-    # @param derived_value [Object] The value to transform
-    #
-    # @return [Object, nil] The transformed value or nil if transformation failed
-    #
-    # @example
-    #   :downcase # => "hello"
-    #
-    # @rbs (untyped derived_value) -> untyped
-    def transform_value(derived_value)
-      transform = options[:transform]
-
-      if transform.is_a?(Symbol) && derived_value.respond_to?(transform, true)
-        derived_value.send(transform)
-      elsif transform.respond_to?(:call)
-        transform.call(derived_value)
-      else
-        derived_value
-      end
-    end
-
-    # Coerces the derived value to the expected type(s) using the coercion registry.
-    #
-    # @param transformed_value [Object] The value to coerce
-    #
-    # @return [Object, nil] The coerced value or nil if coercion failed
-    #
-    # @raise [CoercionError] When coercion fails (handled internally)
-    #
-    # @example
-    #   # Coerces "42" to Integer, "true" to Boolean, etc.
-    #   coerce_value("42") # => 42
-    #
-    # @rbs (untyped transformed_value) -> untyped
-    def coerce_value(transformed_value)
-      return transformed_value if types.empty?
-
-      registry = task.class.settings.coercions
-      last_idx = types.size - 1
-
-      types.find.with_index do |type, i|
-        break registry.coerce(type, task, transformed_value, options)
-      rescue CoercionError => e
-        next if i != last_idx
-
-        unless optional? && transformed_value.nil?
-          message =
-            if last_idx.zero?
-              e.message
-            else
-              tl = types.map { |t| Locale.t("cmdx.types.#{t}") }.join(", ")
-              Locale.t("cmdx.coercions.into_any", types: tl)
-            end
-
-          errors.add(method_name, message)
-        end
-      end
-    end
-
-  end
-end

data/lib/cmdx/callback_registry.rb

@@ -1,169 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Registry for managing callbacks that can be executed at various points during task execution.
-  #
-  # 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
-      before_execution
-      on_complete
-      on_interrupted
-      on_executed
-      on_success
-      on_skipped
-      on_failed
-      on_good
-      on_bad
-    ].freeze
-
-    # @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 (?Hash[Symbol, Set[Array[untyped]]]? registry) -> void
-    def initialize(registry = nil)
-      @registry = registry || {}
-    end
-
-    # Sets up copy-on-write state when duplicated via dup.
-    #
-    # @param source [CallbackRegistry] The registry being duplicated
-    #
-    # @rbs (CallbackRegistry source) -> void
-    def initialize_dup(source)
-      @parent = source
-      @registry = nil
-      super
-    end
-
-    # Returns the internal registry of callbacks organized by type.
-    # Delegates to the parent registry when not yet materialized.
-    #
-    # @return [Hash{Symbol => Set<Array>}] Hash mapping callback types to their registered callables
-    #
-    # @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
-    #
-    # @param type [Symbol] The callback type from TYPES
-    # @param callables [Array<#call>] Callable objects to register
-    # @param options [Hash] Options to pass to the callback
-    # @param block [Proc] Optional block to register as a callable
-    # @option options [Hash] :if Condition hash for conditional execution
-    # @option options [Hash] :unless Inverse condition hash for conditional execution
-    #
-    # @return [CallbackRegistry] self for method chaining
-    #
-    # @raise [ArgumentError] When type is not a valid callback type
-    #
-    # @example Register a method callback
-    #   registry.register(:before_execution, :validate_inputs)
-    # @example Register a block with conditions
-    #   registry.register(:on_success, if: { status: :completed }) do |task|
-    #     task.log("Success callback executed")
-    #   end
-    #
-    # @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]
-      self
-    end
-
-    # Removes one or more callables for a specific callback type
-    #
-    # @param type [Symbol] The callback type from TYPES
-    # @param callables [Array<#call>] Callable objects to remove
-    # @param options [Hash] Options that were used during registration
-    # @param block [Proc] Optional block to remove
-    # @option options [Object] :* Any option key-value pairs
-    #
-    # @return [CallbackRegistry] self for method chaining
-    #
-    # @example Remove a specific callback
-    #   registry.deregister(:before_execution, :validate_inputs)
-    #
-    # @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]
-
-      @registry[type].delete([callables, options])
-      @registry.delete(type) if @registry[type].empty?
-      self
-    end
-
-    # Invokes all registered callbacks for a given type
-    #
-    # @param type [Symbol] The callback type to invoke
-    # @param task [Task] The task instance to pass to callbacks
-    #
-    # @raise [TypeError] When type is not a valid callback type
-    #
-    # @example Invoke all before_execution callbacks
-    #   registry.invoke(:before_execution, task)
-    #
-    # @rbs (Symbol type, Task task) -> void
-    def invoke(type, task)
-      raise TypeError, "unknown callback type #{type.inspect}" unless TYPES_SET.include?(type)
-      return unless registry[type]
-
-      registry[type].each do |callables, options|
-        next unless Utils::Condition.evaluate(task, options)
-
-        Utils::Wrap.array(callables).each do |callable|
-          if callable.is_a?(Symbol)
-            task.send(callable)
-          elsif callable.is_a?(Proc)
-            task.instance_exec(&callable)
-          elsif callable.respond_to?(:call)
-            callable.call(task)
-          else
-            raise "cannot invoke #{callable}"
-          end
-        end
-      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