cmdx 1.0.1 → 1.1.1

data/lib/cmdx/parameter_evaluator.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Parameter evaluation system for task execution context.
+  #
+  # ParameterEvaluator processes parameter definitions by extracting values from
+  # task context sources, applying type coercions, performing validations, and
+  # handling optional parameters with default values. It ensures parameter values
+  # meet the requirements defined in parameter specifications before task execution.
+  class ParameterEvaluator
+
+    cmdx_attr_delegator :parent, :method_source, :name, :options, :required?, :optional?, :type,
+                        to: :parameter,
+                        private: true
+
+    # @return [CMDx::Task] The task instance being processed
+    attr_reader :task
+
+    # @return [CMDx::Parameter] The parameter definition being processed
+    attr_reader :parameter
+
+    # Creates a new parameter evaluator instance.
+    #
+    # @param task [CMDx::Task] the task instance containing parameter context
+    # @param parameter [CMDx::Parameter] the parameter definition to evaluate
+    #
+    # @example Create evaluator for a task parameter
+    #   evaluator = ParameterEvaluator.new(task, parameter)
+    def initialize(task, parameter)
+      @task      = task
+      @parameter = parameter
+    end
+
+    # Evaluates a parameter by creating a new evaluator instance and calling it.
+    #
+    # @param task [CMDx::Task] the task instance containing parameter context
+    # @param parameter [CMDx::Parameter] the parameter definition to evaluate
+    #
+    # @return [Object] the coerced and validated parameter value
+    #
+    # @raise [ValidationError] when parameter source is undefined or required parameter is missing
+    # @raise [CoercionError] when parameter value cannot be coerced to expected type
+    #
+    # @example Evaluate a parameter value
+    #   value = ParameterEvaluator.call(task, parameter)
+    def self.call(task, parameter)
+      new(task, parameter).call
+    end
+
+    # Evaluates the parameter by applying coercion and validation.
+    #
+    # @return [Object] the coerced and validated parameter value
+    #
+    # @raise [ValidationError] when parameter source is undefined or required parameter is missing
+    # @raise [CoercionError] when parameter value cannot be coerced to expected type
+    #
+    # @example Evaluate parameter with coercion and validation
+    #   evaluator = ParameterEvaluator.new(task, parameter)
+    #   value = evaluator.call
+    def call
+      coerce!.tap { validate! }
+    end
+
+    private
+
+    # Checks if the parameter source method is defined on the task.
+    #
+    # @return [Boolean] true if the source method exists, false otherwise
+    #
+    # @example Check if parameter source is defined
+    #   evaluator.send(:source_defined?) #=> true
+    def source_defined?
+      task.respond_to?(method_source, true) || task.cmdx_try(method_source)
+    end
+
+    # Retrieves the parameter source object from the task.
+    #
+    # @return [Object] the source object containing parameter values
+    #
+    # @raise [ValidationError] when the source method is not defined on the task
+    #
+    # @example Get parameter source
+    #   evaluator.send(:source) #=> #<Context:...>
+    def source
+      return @source if defined?(@source)
+
+      unless source_defined?
+        raise ValidationError, I18n.t(
+          "cmdx.parameters.undefined",
+          default: "delegates to undefined method #{method_source}",
+          source: method_source
+        )
+      end
+
+      @source = task.cmdx_try(method_source)
+    end
+
+    # Checks if the parameter value exists in the source object.
+    #
+    # @return [Boolean] true if the parameter value exists, false otherwise
+    #
+    # @example Check if parameter value exists
+    #   evaluator.send(:source_value?) #=> true
+    def source_value?
+      return false if source.nil?
+
+      source.cmdx_respond_to?(name, true)
+    end
+
+    # Checks if a required parameter value is missing from the source.
+    #
+    # @return [Boolean] true if required parameter is missing, false otherwise
+    #
+    # @example Check if required parameter is missing
+    #   evaluator.send(:source_value_required?) #=> false
+    def source_value_required?
+      return false if parent&.optional? && source.nil?
+
+      required? && !source_value?
+    end
+
+    # Extracts the parameter value from the source with default handling.
+    #
+    # @return [Object] the parameter value or default value
+    #
+    # @raise [ValidationError] when a required parameter is missing
+    #
+    # @example Get parameter value with default
+    #   evaluator.send(:value) #=> "default_value"
+    def value
+      return @value if defined?(@value)
+
+      if source_value_required?
+        raise ValidationError, I18n.t(
+          "cmdx.parameters.required",
+          default: "is a required parameter"
+        )
+      end
+
+      @value = source.cmdx_try(name)
+      return @value unless @value.nil? && options.key?(:default)
+
+      @value = task.cmdx_yield(options[:default])
+    end
+
+    # Applies type coercion to the parameter value.
+    #
+    # @return [Object] the coerced parameter value
+    #
+    # @raise [CoercionError] when value cannot be coerced to expected type
+    #
+    # @example Coerce parameter value
+    #   evaluator.send(:coerce!) #=> 42
+    def coerce!
+      types = Array(type)
+      tsize = types.size - 1
+
+      types.each_with_index do |key, i|
+        break CMDx.configuration.coercions.call(task, key, value, options)
+      rescue CoercionError => e
+        next if tsize != i
+
+        raise(e) if tsize.zero?
+
+        values = types.map(&:to_s).join(", ")
+        raise CoercionError, I18n.t(
+          "cmdx.coercions.into_any",
+          values:,
+          default: "could not coerce into one of: #{values}"
+        )
+      end
+    end
+
+    # Checks if validations should be skipped for optional missing arguments.
+    #
+    # @return [Boolean] true if validations should be skipped, false otherwise
+    #
+    # @example Check if validations should be skipped
+    #   evaluator.send(:skip_validations_due_to_optional_missing_argument?) #=> false
+    def skip_validations_due_to_optional_missing_argument?
+      optional? && value.nil? && !source.nil? && !source.cmdx_respond_to?(name, true)
+    end
+
+    # Checks if validator should be skipped due to conditional options.
+    #
+    # @param opts [Hash] the validator options
+    #
+    # @return [Boolean] true if validator should be skipped, false otherwise
+    #
+    # @example Check if validator should be skipped
+    #   evaluator.send(:skip_validator_due_to_conditional?, :presence) #=> false
+    def skip_validator_due_to_conditional?(opts)
+      opts.is_a?(Hash) && !task.cmdx_eval(opts)
+    end
+
+    # Checks if validator should be skipped due to allow_nil option.
+    #
+    # @param opts [Symbol] the validator options
+    #
+    # @return [Boolean] true if validator should be skipped, false otherwise
+    #
+    # @example Check if validator should be skipped for nil
+    #   evaluator.send(:skip_validator_due_to_allow_nil?, :presence) #=> true
+    def skip_validator_due_to_allow_nil?(opts)
+      opts.is_a?(Hash) && opts[:allow_nil] && value.nil?
+    end
+
+    # Applies all configured validations to the parameter value.
+    #
+    # @return [void]
+    #
+    # @raise [ValidationError] when parameter value fails validation
+    #
+    # @example Validate parameter value
+    #   evaluator.send(:validate!)
+    def validate!
+      return if skip_validations_due_to_optional_missing_argument?
+
+      types = CMDx.configuration.validators.registry.keys
+
+      options.slice(*types).each_key do |key|
+        opts = options[key]
+        next if skip_validator_due_to_allow_nil?(opts)
+        next if skip_validator_due_to_conditional?(opts)
+
+        CMDx.configuration.validators.call(task, key, value, opts)
+      end
+    end
+
+  end
+end

data/lib/cmdx/parameter_inspector.rb

@@ -1,75 +1,57 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter inspection utility for generating human-readable parameter descriptions.
+  # Provides formatted inspection and display functionality for parameter objects.
   #
-  # The ParameterInspector module provides functionality to convert parameter
-  # hash representations into formatted, human-readable strings. It handles
-  # nested parameter structures with proper indentation and ordering.
-  #
-  # @example Basic parameter inspection
-  #   parameter_hash = {
-  #     name: :user_id,
-  #     type: :integer,
-  #     source: :context,
-  #     required: true,
-  #     options: { numeric: { min: 1 } },
-  #     children: []
-  #   }
-  #   ParameterInspector.call(parameter_hash)
-  #   # => "Parameter: name=user_id type=integer source=context required=true options={numeric: {min: 1}}"
-  #
-  # @example Nested parameter inspection
-  #   nested_parameter = {
-  #     name: :address,
-  #     type: :virtual,
-  #     source: :context,
-  #     required: true,
-  #     options: {},
-  #     children: [
-  #       { name: :street, type: :string, source: :address, required: true, options: {}, children: [] }
-  #     ]
-  #   }
-  #   ParameterInspector.call(nested_parameter)
-  #   # => "Parameter: name=address type=virtual source=context required=true options={}
-  #   #       ↳ Parameter: name=street type=string source=address required=true options={}"
-  #
-  # @see CMDx::Parameter Parameter hash serialization via to_h
-  # @see CMDx::ParameterSerializer Parameter-to-hash conversion
+  # This module formats parameter information into human-readable string representations,
+  # including nested parameter structures with proper indentation. It processes parameter
+  # hashes in a consistent order and handles child parameter relationships for complex
+  # parameter hierarchies.
   module ParameterInspector
 
-    # Ordered keys for consistent parameter inspection output.
-    #
-    # Defines the order in which parameter attributes are displayed
-    # in the inspection string, with children handled specially.
     ORDERED_KEYS = %i[
       name type source required options children
     ].freeze
 
     module_function
 
-    # Converts a parameter hash to a human-readable string representation.
+    # Formats a parameter hash into a human-readable inspection string.
     #
-    # Formats parameter data into a structured string with proper ordering
-    # and indentation for nested parameters. Child parameters are displayed
-    # with increased indentation and arrow prefixes.
+    # Creates a formatted string representation of parameter information,
+    # displaying attributes in a consistent order with proper indentation
+    # for nested child parameters. The method recursively processes child
+    # parameters with increased indentation depth for visual hierarchy.
     #
-    # @param parameter [Hash] The parameter hash to inspect
-    # @param depth [Integer] The current nesting depth for indentation (default: 1)
-    # @return [String] Formatted parameter description
+    # @param parameter [Hash] the parameter hash to format
+    # @option parameter [Symbol, String] :name the parameter name
+    # @option parameter [Symbol, Array<Symbol>] :type the parameter type(s)
+    # @option parameter [Symbol] :source the parameter source context
+    # @option parameter [Boolean] :required whether the parameter is required
+    # @option parameter [Hash] :options additional parameter configuration options
+    # @option parameter [Array<Hash>] :children nested child parameter definitions
+    # @param depth [Integer] the indentation depth for nested parameters (defaults to 1)
     #
-    # @example Single parameter inspection
-    #   ParameterInspector.call(param_hash)
-    #   # => "Parameter: name=user_id type=integer source=context required=true"
+    # @return [String] formatted multi-line string representation of the parameter
     #
-    # @example Nested parameter inspection with custom depth
-    #   ParameterInspector.call(param_hash, 2)
-    #   # => "Parameter: name=address type=virtual source=context required=true
-    #   #         ↳ Parameter: name=street type=string source=address required=true"
+    # @example Format a simple parameter
+    #   parameter = { name: :user_id, type: :integer, required: true }
+    #   ParameterInspector.call(parameter)
+    #   #=> "Parameter: name=user_id type=integer required=true"
     #
-    # @example Parameter with options
-    #   ParameterInspector.call(param_with_validation)
-    #   # => "Parameter: name=email type=string source=context required=true options={format: {with: /@/}}"
+    # @example Format a parameter with children
+    #   parameter = {
+    #     name: :payment,
+    #     type: :hash,
+    #     required: true,
+    #     children: [
+    #       { name: :amount, type: :big_decimal, required: true },
+    #       { name: :currency, type: :string, required: true }
+    #     ]
+    #   }
+    #   ParameterInspector.call(parameter)
+    #   #=> "Parameter: name=payment type=hash required=true
+    #   #       ↳ Parameter: name=amount type=big_decimal required=true
+    #   #       ↳ Parameter: name=currency type=string required=true"
     def call(parameter, depth = 1)
       ORDERED_KEYS.filter_map do |key|
         value = parameter[key]

data/lib/cmdx/parameter_registry.rb

@@ -1,124 +1,105 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter collection class for managing multiple parameter definitions.
+  # Registry for managing parameter definitions within tasks.
   #
-  # The ParameterRegistry class extends Array to provide specialized functionality for
-  # managing collections of Parameter instances within CMDx tasks. It handles
-  # validation coordination, serialization, and inspection of parameter groups.
-  #
-  # @example Basic parameter collection usage
-  #   parameter_registry = ParameterRegistry.new
-  #   parameter_registry << Parameter.new(:user_id, klass: Task, type: :integer)
-  #   parameter_registry << Parameter.new(:email, klass: Task, type: :string)
-  #   parameter_registry.valid?  # => true (if all parameters are valid)
-  #
-  # @example Parameter collection validation
-  #   parameter_registry.validate!(task_instance)  # Validates all parameters
-  #   parameter_registry.invalid?  # => true if any parameter failed validation
-  #
-  # @example Parameter collection serialization
-  #   parameter_registry.to_h  # => Array of parameter hash representations
-  #   parameter_registry.to_s  # => Human-readable parameter descriptions
-  #
-  # @see CMDx::Parameter Individual parameter definitions
-  # @see CMDx::Task Task parameter integration
-  class ParameterRegistry < Array
+  # This registry maintains a collection of parameter definitions and provides
+  # validation functionality to ensure all parameters are properly configured
+  # and accessible on their associated tasks. It supports both flat and nested
+  # parameter structures through recursive validation.
+  class ParameterRegistry
 
-    # Checks if any parameters in the collection are invalid.
+    # @return [Array<Parameter>] array containing parameter definition objects
+    attr_reader :registry
+
+    # Initializes a new parameter registry with an empty parameter collection.
     #
-    # @return [Boolean] true if any parameter has validation errors, false otherwise
+    # @return [ParameterRegistry] a new parameter registry instance
     #
-    # @example
-    #   parameter_registry.invalid?  # => true if validation errors exist
-    def invalid?
-      !valid?
+    # @example Creating a new registry
+    #   registry = ParameterRegistry.new
+    #   registry.registry #=> []
+    def initialize
+      @registry = []
     end
 
-    # Checks if all parameters in the collection are valid.
+    # Creates a duplicate of the parameter registry with deep-copied parameters.
+    #
+    # This method creates a new registry instance with duplicated parameter
+    # definitions, ensuring changes to the duplicate don't affect the original.
+    #
+    # @return [ParameterRegistry] a new registry instance with duplicated parameters
+    #
+    # @example Duplicate a registry
+    #   original = ParameterRegistry.new
+    #   duplicate = original.dup
+    #   duplicate.object_id != original.object_id #=> true
+    def dup
+      new_registry = self.class.new
+      new_registry.instance_variable_set(:@registry, registry.map(&:dup))
+      new_registry
+    end
+
+    # Checks if all parameters in the registry are valid.
     #
     # @return [Boolean] true if all parameters are valid, false otherwise
     #
-    # @example
-    #   parameter_registry.valid?  # => true if no validation errors exist
+    # @example Check registry validity
+    #   registry.valid? #=> true
     def valid?
-      all?(&:valid?)
+      registry.all?(&:valid?)
     end
 
-    # Validates all parameters in the collection against a task instance.
+    # Validates all parameters in the registry against a task instance.
     #
-    # Recursively validates each parameter and its children by calling the
-    # parameter accessor methods on the task instance, which triggers
-    # value resolution, coercion, and validation.
+    # This method ensures that each parameter is properly defined and accessible
+    # on the provided task, including nested parameters through recursive validation.
+    #
+    # @param task [Task] the task instance to validate parameters against
     #
-    # @param task [CMDx::Task] The task instance to validate parameters against
     # @return [void]
     #
-    # @example Validating parameters
-    #   task = ProcessOrderTask.new
-    #   parameter_registry.validate!(task)  # Validates all parameters
+    # @raise [NoMethodError] if a parameter method is not defined on the task
     #
-    # @example Validation with nested parameters
-    #   # Validates parent parameters and all nested child parameters
-    #   parameter_registry.validate!(task_with_nested_params)
+    # @example Validate parameters against a task
+    #   registry.validate!(task_instance)
     def validate!(task)
-      each { |p| recursive_validate!(task, p) }
+      registry.each { |p| recursive_validate!(task, p) }
     end
 
-    # Converts the parameter collection to a hash representation.
-    #
-    # Serializes all parameters in the collection to their hash representations
-    # using the ParametersSerializer.
-    #
-    # @return [Array<Hash>] Array of serialized parameter data
-    #
-    # @example
-    #   parameter_registry.to_h
-    #   # => [
-    #   #   {
-    #   #     source: :context,
-    #   #     name: :user_id,
-    #   #     type: :integer,
-    #   #     required: true,
-    #   #     options: {},
-    #   #     children: []
-    #   #   },
-    #   #   { ... }
-    #   # ]
+    # Converts the parameter registry to a hash representation.
+    #
+    # @return [Array<Hash>] array of parameter hash representations
+    #
+    # @example Convert registry to hash
+    #   registry.to_h #=> [{name: :user_id, type: :integer}, {name: :email, type: :string}]
     def to_h
-      ParametersSerializer.call(self)
+      registry.map(&:to_h)
     end
-    alias to_a to_h
 
-    # Converts the parameter collection to a string representation.
-    #
-    # Creates a human-readable string representation of all parameters
-    # in the collection using the ParametersInspector.
+    # Converts the parameter registry to a string representation.
     #
-    # @return [String] Multi-line parameter descriptions
+    # @return [String] string representation of all parameters, joined by newlines
     #
-    # @example
-    #   parameter_registry.to_s
-    #   # => "Parameter: name=user_id type=integer source=context required=true
-    #   #     Parameter: name=email type=string source=context required=false"
+    # @example Convert registry to string
+    #   registry.to_s #=> "user_id: integer\nemail: string"
     def to_s
-      ParametersInspector.call(self)
+      registry.map(&:to_s).join("\n")
     end
 
     private
 
-    # Recursively validates a parameter and all its children.
+    # Recursively validates a parameter and its children against a task.
     #
-    # Calls the parameter accessor method on the task to trigger validation,
-    # then recursively validates all child parameters for nested parameter
-    # structures.
+    # @param task [Task] the task instance to validate the parameter against
+    # @param parameter [Parameter] the parameter to validate
     #
-    # @param task [CMDx::Task] The task instance to validate against
-    # @param parameter [CMDx::Parameter] The parameter to validate
     # @return [void]
+    #
+    # @raise [NoMethodError] if the parameter method is not defined on the task
     def recursive_validate!(task, parameter)
-      task.send(parameter.method_name)
-      parameter.children.each { |cp| recursive_validate!(task, cp) }
+      task.send(parameter.method_name) # Make sure parameter is defined on task
+      parameter.children.each { |child| recursive_validate!(task, child) }
     end
 
   end

data/lib/cmdx/parameter_serializer.rb

@@ -1,92 +1,48 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter serialization utility for converting Parameter objects to hash representations.
+  # Parameter serialization utilities for converting parameter objects to hash representations.
   #
-  # The ParameterSerializer module provides functionality to serialize Parameter
-  # instances into structured hash representations suitable for inspection,
-  # logging, debugging, and data interchange.
-  #
-  # @example Basic parameter serialization
-  #   parameter = Parameter.new(:user_id, klass: Task, type: :integer, required: true)
-  #   ParameterSerializer.call(parameter)
-  #   # => {
-  #   #   source: :context,
-  #   #   name: :user_id,
-  #   #   type: :integer,
-  #   #   required: true,
-  #   #   options: {},
-  #   #   children: []
-  #   # }
-  #
-  # @example Parameter with validation options
-  #   parameter = Parameter.new(:email, klass: Task, type: :string,
-  #                           format: { with: /@/ }, presence: true)
-  #   ParameterSerializer.call(parameter)
-  #   # => {
-  #   #   source: :context,
-  #   #   name: :email,
-  #   #   type: :string,
-  #   #   required: false,
-  #   #   options: { format: { with: /@/ }, presence: true },
-  #   #   children: []
-  #   # }
-  #
-  # @example Nested parameter serialization
-  #   parent = Parameter.new(:address, klass: Task) do
-  #     required :street, :city
-  #   end
-  #   ParameterSerializer.call(parent)
-  #   # => {
-  #   #   source: :context,
-  #   #   name: :address,
-  #   #   type: :virtual,
-  #   #   required: false,
-  #   #   options: {},
-  #   #   children: [
-  #   #     { source: :address, name: :street, type: :virtual, required: true, options: {}, children: [] },
-  #   #     { source: :address, name: :city, type: :virtual, required: true, options: {}, children: [] }
-  #   #   ]
-  #   # }
-  #
-  # @see CMDx::Parameter Parameter object creation and configuration
-  # @see CMDx::ParameterInspector Human-readable parameter formatting
+  # ParameterSerializer provides functionality to convert parameter definition objects
+  # into structured hash format for serialization, introspection, and data exchange.
+  # It extracts essential parameter metadata including source context, method names,
+  # type information, requirement status, options, and nested child parameters.
   module ParameterSerializer
 
     module_function
 
-    # Converts a Parameter object to a hash representation.
+    # Converts a parameter object into a hash representation for serialization.
     #
-    # Serializes a Parameter instance into a structured hash containing
-    # all relevant parameter information including source, name, type,
-    # requirement status, options, and recursively serialized children.
+    # This method extracts key metadata from a parameter definition and structures
+    # it into a hash format suitable for serialization, storage, or transmission.
+    # Child parameters are recursively serialized to maintain nested structure.
     #
-    # @param parameter [CMDx::Parameter] The parameter object to serialize
-    # @return [Hash] Structured hash representation of the parameter
+    # @param parameter [CMDx::Parameter] the parameter object to serialize
     #
-    # @example Simple parameter serialization
-    #   param = Parameter.new(:age, klass: Task, type: :integer, required: true)
-    #   ParameterSerializer.call(param)
-    #   # => {
-    #   #   source: :context,
-    #   #   name: :age,
-    #   #   type: :integer,
-    #   #   required: true,
-    #   #   options: {},
-    #   #   children: []
-    #   # }
+    # @return [Hash] a hash containing the parameter's metadata and configuration
+    # @option return [Symbol] :source the source context for parameter resolution
+    # @option return [Symbol] :name the method name generated for this parameter
+    # @option return [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+    # @option return [Boolean] :required whether the parameter is required for execution
+    # @option return [Hash] :options the parameter configuration options
+    # @option return [Array<Hash>] :children serialized child parameters for nested structures
     #
-    # @example Parameter with custom source and options
-    #   param = Parameter.new(:name, klass: Task, source: :user,
-    #                        type: :string, length: { min: 2 })
-    #   ParameterSerializer.call(param)
-    #   # => {
-    #   #   source: :user,
-    #   #   name: :name,
-    #   #   type: :string,
+    # @example Serialize a nested parameter with children
+    #   user_param = Parameter.new(:user, klass: MyTask, type: :hash) do
+    #     required :name, type: :string
+    #     optional :age, type: :integer
+    #   end
+    #   ParameterSerializer.call(user_param)
+    #   #=> {
+    #   #   source: :context,
+    #   #   name: :user,
+    #   #   type: :hash,
     #   #   required: false,
-    #   #   options: { length: { min: 2 } },
-    #   #   children: []
+    #   #   options: {},
+    #   #   children: [
+    #   #     { source: :user, name: :name, type: :string, required: true, options: {}, children: [] },
+    #   #     { source: :user, name: :age, type: :integer, required: false, options: {}, children: [] }
+    #   #   ]
     #   # }
     def call(parameter)
       {