cmdx 0.5.0 → 1.0.0

data/lib/cmdx/parameter_registry.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Parameter collection class for managing multiple parameter definitions.
+  #
+  # 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
+
+    # Checks if any parameters in the collection are invalid.
+    #
+    # @return [Boolean] true if any parameter has validation errors, false otherwise
+    #
+    # @example
+    #   parameter_registry.invalid?  # => true if validation errors exist
+    def invalid?
+      !valid?
+    end
+
+    # Checks if all parameters in the collection are valid.
+    #
+    # @return [Boolean] true if all parameters are valid, false otherwise
+    #
+    # @example
+    #   parameter_registry.valid?  # => true if no validation errors exist
+    def valid?
+      all?(&:valid?)
+    end
+
+    # Validates all parameters in the collection 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.
+    #
+    # @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
+    #
+    # @example Validation with nested parameters
+    #   # Validates parent parameters and all nested child parameters
+    #   parameter_registry.validate!(task_with_nested_params)
+    def validate!(task)
+      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: []
+    #   #   },
+    #   #   { ... }
+    #   # ]
+    def to_h
+      ParametersSerializer.call(self)
+    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.
+    #
+    # @return [String] Multi-line parameter descriptions
+    #
+    # @example
+    #   parameter_registry.to_s
+    #   # => "Parameter: name=user_id type=integer source=context required=true
+    #   #     Parameter: name=email type=string source=context required=false"
+    def to_s
+      ParametersInspector.call(self)
+    end
+
+    private
+
+    # Recursively validates a parameter and all its children.
+    #
+    # Calls the parameter accessor method on the task to trigger validation,
+    # then recursively validates all child parameters for nested parameter
+    # structures.
+    #
+    # @param task [CMDx::Task] The task instance to validate against
+    # @param parameter [CMDx::Parameter] The parameter to validate
+    # @return [void]
+    def recursive_validate!(task, parameter)
+      task.send(parameter.method_name)
+      parameter.children.each { |cp| recursive_validate!(task, cp) }
+    end
+
+  end
+end

data/lib/cmdx/parameter_serializer.rb

@@ -1,10 +1,93 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Parameter serialization utility 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
   module ParameterSerializer
 
     module_function
 
+    # Converts a Parameter object to a hash representation.
+    #
+    # Serializes a Parameter instance into a structured hash containing
+    # all relevant parameter information including source, name, type,
+    # requirement status, options, and recursively serialized children.
+    #
+    # @param parameter [CMDx::Parameter] The parameter object to serialize
+    # @return [Hash] Structured hash representation of the parameter
+    #
+    # @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: []
+    #   # }
+    #
+    # @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,
+    #   #   required: false,
+    #   #   options: { length: { min: 2 } },
+    #   #   children: []
+    #   # }
     def call(parameter)
       {
         source: parameter.method_source,

data/lib/cmdx/parameter_validator.rb

@@ -1,10 +1,72 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Parameter validation orchestration module for CMDx tasks.
+  #
+  # The ParameterValidator module provides high-level parameter validation
+  # coordination for task instances. It triggers validation of all task
+  # parameters and handles validation failure by setting task failure state
+  # with appropriate error messages.
+  #
+  # @example Basic parameter validation
+  #   class ProcessOrderTask < CMDx::Task
+  #     required :order_id, type: :integer
+  #     required :email, type: :string, format: { with: /@/ }
+  #   end
+  #
+  #   task = ProcessOrderTask.new
+  #   ParameterValidator.call(task)  # Validates all parameters
+  #   # If validation fails, task.failed? => true
+  #
+  # @example Validation with error handling
+  #   task = ProcessOrderTask.new
+  #   ParameterValidator.call(task)
+  #
+  #   if task.failed?
+  #     puts task.result.metadata[:reason] # => "order_id is a required parameter. email is invalid"
+  #     puts task.errors.messages          # => { order_id: ["is a required parameter"], email: ["is invalid"] }
+  #   end
+  #
+  # @example Successful validation
+  #   task = ProcessOrderTask.call(order_id: 123, email: "user@example.com")
+  #   # ParameterValidator runs automatically and validation passes
+  #   task.success?  # => true
+  #
+  # @see CMDx::Parameters Parameter collection validation
+  # @see CMDx::Parameter Individual parameter definitions
+  # @see CMDx::Task Task execution and parameter integration
   module ParameterValidator
 
     module_function
 
+    # Validates all parameters for a task instance.
+    #
+    # Triggers validation of all task parameters through the Parameters collection.
+    # If any validation errors occur, sets the task to failed state with a
+    # comprehensive error message and detailed error information.
+    #
+    # @param task [CMDx::Task] The task instance to validate parameters for
+    # @return [void]
+    #
+    # @example Validating task parameters
+    #   task = MyTask.new
+    #   ParameterValidator.call(task)
+    #
+    #   # If validation fails:
+    #   task.failed?                  # => true
+    #   task.result.metadata[:reason] # => "Combined error messages from all failed parameters"
+    #   task.errors.empty?            # => false
+    #
+    # @example Validation success
+    #   task = MyTask.new  # with valid parameters
+    #   ParameterValidator.call(task)
+    #
+    #   task.errors.empty?  # => true
+    #   # Task continues normal execution
+    #
+    # @note This method is typically called automatically during task execution
+    #   before the main task logic runs, ensuring parameter validation occurs
+    #   early in the task lifecycle.
     def call(task)
       task.class.cmd_parameters.validate!(task)
       return if task.errors.empty?

data/lib/cmdx/parameter_value.rb

@@ -1,27 +1,95 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Parameter value resolution and processing class for CMDx tasks.
+  #
+  # The ParameterValue class handles the complete lifecycle of parameter value
+  # processing including source resolution, type coercion, validation, and error
+  # handling. It serves as the bridge between parameter definitions and their
+  # actual values during task execution.
+  #
+  # @example Basic parameter value processing
+  #   task = ProcessOrderTask.new
+  #   parameter = Parameter.new(:order_id, klass: ProcessOrderTask, type: :integer)
+  #   value_processor = ParameterValue.new(task, parameter)
+  #   processed_value = value_processor.call  # Resolves, coerces, and validates
+  #
+  # @example Parameter value with validation
+  #   parameter = Parameter.new(:email, klass: Task, type: :string,
+  #                           format: { with: /@/ }, presence: true)
+  #   value_processor = ParameterValue.new(task, parameter)
+  #   value_processor.call  # Validates email format and presence
+  #
+  # @example Parameter value with default
+  #   parameter = Parameter.new(:priority, klass: Task, default: "normal")
+  #   value_processor = ParameterValue.new(task, parameter)
+  #   value_processor.call  # Returns "normal" if not provided
+  #
+  # @see CMDx::Parameter Parameter definition and configuration
+  # @see CMDx::Coercions Type coercion modules
+  # @see CMDx::Validators Parameter validation modules
   class ParameterValue
 
-    __cmdx_attr_delegator :parent, :method_source, :name, :options, :required?, :optional?, :type, to: :parameter, private: true
+    __cmdx_attr_delegator :parent, :method_source, :name, :options, :required?, :optional?, :type,
+                          to: :parameter,
+                          private: true
 
+    # @return [CMDx::Task] The task instance being processed
+    # @return [CMDx::Parameter] The parameter definition being processed
     attr_reader :task, :parameter
 
+    # Initializes a new ParameterValue processor.
+    #
+    # Creates a parameter value processor for resolving, coercing, and validating
+    # a specific parameter value within the context of a task instance.
+    #
+    # @param task [CMDx::Task] The task instance containing the parameter source
+    # @param parameter [CMDx::Parameter] The parameter definition to process
+    #
+    # @example Creating a parameter value processor
+    #   processor = ParameterValue.new(task_instance, parameter_definition)
     def initialize(task, parameter)
       @task      = task
       @parameter = parameter
     end
 
+    # Processes the parameter value through coercion and validation.
+    #
+    # Executes the complete parameter value processing pipeline:
+    # 1. Resolves the raw value from the source
+    # 2. Applies type coercion based on parameter type
+    # 3. Runs all configured validations
+    # 4. Returns the final processed value
+    #
+    # @return [Object] The processed and validated parameter value
+    # @raise [CoercionError] If type coercion fails
+    # @raise [ValidationError] If validation fails
+    #
+    # @example Processing a simple parameter
+    #   processor.call  # => 42 (after coercion and validation)
+    #
+    # @example Processing with validation failure
+    #   processor.call  # => raises ValidationError: "is not valid"
     def call
       coerce!.tap { validate! }
     end
 
     private
 
+    # Checks if the parameter source method is defined on the task.
+    #
+    # @return [Boolean] true if source method exists, false otherwise
     def source_defined?
       task.respond_to?(method_source, true) || task.__cmdx_try(method_source)
     end
 
+    # Resolves the source object that contains the parameter value.
+    #
+    # Gets the source object by calling the method_source on the task instance.
+    # Raises ValidationError if the source method is not defined.
+    #
+    # @return [Object] The source object containing parameter values
+    # @raise [ValidationError] If source method is undefined
     def source
       return @source if defined?(@source)
 
@@ -36,18 +104,31 @@ module CMDx
       @source = task.__cmdx_try(method_source)
     end
 
+    # Checks if the source object has the parameter value.
+    #
+    # @return [Boolean] true if source responds to parameter name, false otherwise
     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
     def source_value_required?
       return false if parent&.optional? && source.nil?
 
       required? && !source_value?
     end
 
+    # Resolves the raw parameter value from the source.
+    #
+    # Gets the parameter value from the source object, handling required
+    # parameter validation and default value resolution.
+    #
+    # @return [Object] The raw parameter value
+    # @raise [ValidationError] If required parameter is missing
     def value
       return @value if defined?(@value)
 
@@ -64,6 +145,14 @@ module CMDx
       @value = task.__cmdx_yield(options[:default])
     end
 
+    # Applies type coercion to the parameter value.
+    #
+    # Attempts to coerce the value to each specified type in order,
+    # supporting multiple type fallbacks for flexible coercion.
+    #
+    # @return [Object] The coerced parameter value
+    # @raise [CoercionError] If all coercion attempts fail
+    # @raise [UnknownCoercionError] If an unknown type is specified
     def coerce!
       types = Array(type)
       tsize = types.size - 1
@@ -99,20 +188,39 @@ module CMDx
       end
     end
 
+    # Checks if validations should be skipped for optional missing arguments.
+    #
+    # @return [Boolean] true if validations should be skipped, false otherwise
     def skip_validations_due_to_optional_missing_argument?
       optional? && value.nil? && !source.nil? && !source.__cmdx_respond_to?(name, true)
     end
 
+    # Checks if a specific validator should be skipped due to conditional logic.
+    #
+    # @param key [Symbol] The validator key to check
+    # @return [Boolean] true if validator should be skipped, false otherwise
     def skip_validator_due_to_conditional?(key)
       opts = options[key]
       opts.is_a?(Hash) && !task.__cmdx_eval(opts)
     end
 
+    # Checks if a specific validator should be skipped due to allow_nil option.
+    #
+    # @param key [Symbol] The validator key to check
+    # @return [Boolean] true if validator should be skipped, false otherwise
     def skip_validator_due_to_allow_nil?(key)
       opts = options[key]
       opts.is_a?(Hash) && opts[:allow_nil] && value.nil?
     end
 
+    # Runs all configured validations on the parameter value.
+    #
+    # Iterates through all validation options and applies the appropriate
+    # validators, respecting skip conditions for optional parameters,
+    # conditional validations, and allow_nil settings.
+    #
+    # @return [void]
+    # @raise [ValidationError] If any validation fails
     def validate!
       return if skip_validations_due_to_optional_missing_argument?
 

data/lib/cmdx/parameters_inspector.rb

@@ -1,10 +1,69 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Parameter collection inspection utility for generating human-readable descriptions.
+  #
+  # The ParametersInspector module provides functionality to convert collections
+  # of parameters into formatted, human-readable string representations. It
+  # coordinates with ParameterInspector to format individual parameters and
+  # combines them into a cohesive multi-parameter description.
+  #
+  # @example Basic parameters collection inspection
+  #   parameter_registry = ParameterRegistry.new
+  #   parameter_registry << Parameter.new(:user_id, klass: Task, type: :integer, required: true)
+  #   parameter_registry << Parameter.new(:email, klass: Task, type: :string, required: false)
+  #
+  #   ParametersInspector.call(parameter_registry)
+  #   # => "Parameter: name=user_id type=integer source=context required=true options={}
+  #   #     Parameter: name=email type=string source=context required=false options={}"
+  #
+  # @example Empty parameters collection
+  #   empty_parameter_registry = ParameterRegistry.new
+  #   ParametersInspector.call(empty_parameter_registry)
+  #   # => ""
+  #
+  # @example Parameters with validation options
+  #   parameter_registry = ParameterRegistry.new
+  #   parameter_registry << Parameter.new(:age, klass: Task, type: :integer,
+  #                              numeric: { within: 18..120 }, required: true)
+  #   parameter_registry << Parameter.new(:website, klass: Task, type: :string,
+  #                              format: { with: /^https?:\/\// }, required: false)
+  #
+  #   ParametersInspector.call(parameter_registry)
+  #   # => "Parameter: name=age type=integer source=context required=true options={numeric: {within: 18..120}}
+  #   #     Parameter: name=website type=string source=context required=false options={format: {with: /^https?:\/\//}}"
+  #
+  # @see CMDx::ParameterRegistry Parameter collection management
+  # @see CMDx::ParameterInspector Individual parameter inspection
+  # @see CMDx::Parameter Parameter definition and configuration
   module ParametersInspector
 
     module_function
 
+    # Converts a Parameters collection to a human-readable string representation.
+    #
+    # Iterates through all parameters in the collection and formats each one
+    # using ParameterInspector, then joins them with newlines to create a
+    # comprehensive multi-parameter description.
+    #
+    # @param parameters [CMDx::ParameterRegistry] The parameters collection to inspect
+    # @return [String] Multi-line formatted parameter descriptions
+    #
+    # @example Inspecting multiple parameters
+    #   ParametersInspector.call(parameters_collection)
+    #   # => "Parameter: name=user_id type=integer source=context required=true
+    #   #     Parameter: name=email type=string source=context required=false
+    #   #     Parameter: name=age type=integer source=context required=true"
+    #
+    # @example Inspecting empty collection
+    #   ParametersInspector.call(ParameterRegistry.new)
+    #   # => ""
+    #
+    # @example Inspecting single parameter collection
+    #   single_param_collection = ParameterRegistry.new
+    #   single_param_collection << Parameter.new(:name, klass: Task)
+    #   ParametersInspector.call(single_param_collection)
+    #   # => "Parameter: name=name type=virtual source=context required=false options={}"
     def call(parameters)
       parameters.map(&:to_s).join("\n")
     end

data/lib/cmdx/parameters_serializer.rb

@@ -1,10 +1,112 @@
 # frozen_string_literal: true
 
 module CMDx
+  # Parameter collection serialization utility for converting Parameters to hash arrays.
+  #
+  # The ParametersSerializer module provides functionality to serialize collections
+  # of Parameter instances into structured array representations. Each parameter
+  # in the collection is converted to its hash representation, creating a
+  # comprehensive data structure suitable for inspection, logging, and data interchange.
+  #
+  # @example Basic parameters collection serialization
+  #   parameter_registry = ParameterRegistry.new
+  #   parameter_registry << Parameter.new(:user_id, klass: Task, type: :integer, required: true)
+  #   parameters << Parameter.new(:email, klass: Task, type: :string, required: false)
+  #
+  #   ParametersSerializer.call(parameters)
+  #   # => [
+  #   #   {
+  #   #     source: :context,
+  #   #     name: :user_id,
+  #   #     type: :integer,
+  #   #     required: true,
+  #   #     options: {},
+  #   #     children: []
+  #   #   },
+  #   #   {
+  #   #     source: :context,
+  #   #     name: :email,
+  #   #     type: :string,
+  #   #     required: false,
+  #   #     options: {},
+  #   #     children: []
+  #   #   }
+  #   # ]
+  #
+  # @example Empty parameters collection
+  #   empty_parameter_registry = ParameterRegistry.new
+  #   ParametersSerializer.call(empty_parameter_registry)
+  #   # => []
+  #
+  # @example Parameters with validation and nested structures
+  #   parameter_registry = ParameterRegistry.new
+  #   parameter_registry << Parameter.new(:age, klass: Task, type: :integer,
+  #                              numeric: { within: 18..120 }, required: true)
+  #
+  #   address_param = Parameter.new(:address, klass: Task) do
+  #     required :street, :city
+  #     optional :apartment
+  #   end
+  #   parameter_registry << address_param
+  #
+  #   ParametersSerializer.call(parameter_registry)
+  #   # => [
+  #   #   {
+  #   #     source: :context,
+  #   #     name: :age,
+  #   #     type: :integer,
+  #   #     required: true,
+  #   #     options: { numeric: { within: 18..120 } },
+  #   #     children: []
+  #   #   },
+  #   #   {
+  #   #     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: [] },
+  #   #       { source: :address, name: :apartment, type: :virtual, required: false, options: {}, children: [] }
+  #   #     ]
+  #   #   }
+  #   # ]
+  #
+  # @see CMDx::ParameterRegistry Parameter collection management
+  # @see CMDx::ParameterSerializer Individual parameter serialization
+  # @see CMDx::Parameter Parameter definition and configuration
   module ParametersSerializer
 
     module_function
 
+    # Converts a Parameters collection to an array of hash representations.
+    #
+    # Iterates through all parameters in the collection and converts each one
+    # to its hash representation using the Parameter#to_h method, which delegates
+    # to ParameterSerializer.
+    #
+    # @param parameters [CMDx::ParameterRegistry] The parameters collection to serialize
+    # @return [Array<Hash>] Array of serialized parameter data structures
+    #
+    # @example Serializing multiple parameters
+    #   ParametersSerializer.call(parameters_collection)
+    #   # => [
+    #   #   { source: :context, name: :user_id, type: :integer, required: true, options: {}, children: [] },
+    #   #   { source: :context, name: :email, type: :string, required: false, options: {}, children: [] }
+    #   # ]
+    #
+    # @example Serializing empty collection
+    #   ParametersSerializer.call(ParameterRegistry.new)
+    #   # => []
+    #
+    # @example Serializing single parameter collection
+    #   single_param_collection = ParameterRegistry.new
+    #   single_param_collection << Parameter.new(:name, klass: Task, type: :string)
+    #   ParametersSerializer.call(single_param_collection)
+    #   # => [
+    #   #   { source: :context, name: :name, type: :string, required: false, options: {}, children: [] }
+    #   # ]
     def call(parameters)
       parameters.map(&:to_h)
     end