cmdx 1.0.1 → 1.1.0

data/lib/cmdx/parameter_inspector.rb

@@ -1,75 +1,44 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter inspection utility for generating human-readable parameter descriptions.
+  # Parameter inspection and formatting utilities for readable parameter representation.
   #
-  # 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 provides functionality to format parameter metadata into human-readable
+  # strings for debugging, logging, and introspection purposes. It handles nested
+  # parameter structures with proper indentation and displays essential parameter
+  # information in a structured format.
   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 parameter data into a structured string with proper ordering
-    # and indentation for nested parameters. Child parameters are displayed
-    # with increased indentation and arrow prefixes.
+    # Formats a parameter hash into a human-readable string representation.
     #
-    # @param parameter [Hash] The parameter hash to inspect
-    # @param depth [Integer] The current nesting depth for indentation (default: 1)
-    # @return [String] Formatted parameter description
+    # This method converts parameter metadata into a structured string format
+    # that displays key parameter information in a consistent order. For parameters
+    # with nested children, it recursively formats child parameters with proper
+    # indentation to show the hierarchical structure.
     #
-    # @example Single parameter inspection
-    #   ParameterInspector.call(param_hash)
-    #   # => "Parameter: name=user_id type=integer source=context required=true"
+    # @param parameter [Hash] the parameter hash to format
+    # @param depth [Integer] the current nesting depth for indentation (default: 1)
     #
-    # @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"
+    # @return [String] a formatted string representation of the parameter
     #
-    # @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 nested children
+    #   param = {
+    #     name: :user, type: :hash, source: :context, required: false, options: {},
+    #     children: [
+    #       { name: :name, type: :string, source: :user, required: true, options: {}, children: [] },
+    #       { name: :age, type: :integer, source: :user, required: false, options: {}, children: [] }
+    #     ]
+    #   }
+    #   ParameterInspector.call(param)
+    #   # => "Parameter: name=user type=hash source=context required=false options={}
+    #   #      ↳ Parameter: name=name type=string source=user required=true options={}
+    #   #      ↳ Parameter: name=age type=integer source=user required=false options={}"
     def call(parameter, depth = 1)
       ORDERED_KEYS.filter_map do |key|
         value = parameter[key]

data/lib/cmdx/parameter_registry.rb

@@ -1,124 +1,99 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter collection class for managing multiple parameter definitions.
+  # Registry for managing parameter definitions and validation 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 handles the storage and validation of parameter definitions,
+  # including nested parameter structures and recursive validation logic.
+  class ParameterRegistry
 
-    # Checks if any parameters in the collection are invalid.
+    # The internal array storing parameter definitions.
     #
-    # @return [Boolean] true if any parameter has validation errors, false otherwise
+    # @return [Array] array containing parameter definition objects
+    attr_reader :registry
+
+    # Initializes a new parameter registry.
+    #
+    # @return [ParameterRegistry] a new parameter registry instance
     #
-    # @example
-    #   parameter_registry.invalid?  # => true if validation errors exist
-    def invalid?
-      !valid?
+    # @example Creating an empty registry
+    #   ParameterRegistry.new
+    def initialize
+      @registry = []
     end
 
-    # Checks if all parameters in the collection are valid.
+    # Creates a deep copy of the parameter registry.
+    #
+    # @return [ParameterRegistry] a new registry instance with duplicated parameters
+    #
+    # @example Duplicating a registry
+    #   original = ParameterRegistry.new
+    #   copy = original.dup
+    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 Checking 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.
+    # @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
-    #
-    # @example Validation with nested parameters
-    #   # Validates parent parameters and all nested child parameters
-    #   parameter_registry.validate!(task_with_nested_params)
+    #   registry.validate!(task)
     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: []
-    #   #   },
-    #   #   { ... }
-    #   # ]
+    # Returns a hash representation of the registry.
+    #
+    # @return [Hash] serialized hash representation of all parameters
+    #
+    # @example Getting registry hash
+    #   registry.to_h
+    #   # => { name: { type: :string, required: true }, age: { type: :integer } }
     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.
+    # Returns a string representation of the registry.
     #
-    # @return [String] Multi-line parameter descriptions
+    # @return [String] formatted string representation of all parameters
     #
-    # @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 Getting registry string
+    #   registry.to_s
+    #   # => "name (string, required), age (integer)"
     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 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]
+    #
+    # @example Recursive validation (internal use)
+    #   recursive_validate!(task, parameter)
     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,41 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter serialization utility for converting Parameter objects to hash representations.
+  # Parameter serialization module for converting parameter objects to hash format.
   #
-  # 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
+  # This module provides functionality to serialize parameter objects into a
+  # standardized hash representation that includes essential metadata about
+  # the parameter such as its source, name, type, required status, options,
+  # and child parameters. The serialized format is commonly used for debugging,
+  # logging, and introspection purposes.
   module ParameterSerializer
 
     module_function
 
-    # Converts a Parameter object to a hash representation.
+    # Serializes a parameter object into 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 [Parameter] the parameter object to serialize
     #
-    # @param parameter [CMDx::Parameter] The parameter object to serialize
-    # @return [Hash] Structured hash representation of the parameter
+    # @return [Hash] a hash containing the parameter's metadata
     #
-    # @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: []
-    #   # }
+    # @raise [NoMethodError] if the parameter doesn't respond to required methods
     #
-    # @example Parameter with custom source and options
-    #   param = Parameter.new(:name, klass: Task, source: :user,
-    #                        type: :string, length: { min: 2 })
+    # @example Serialize a parameter with nested children
+    #   param = Parameter.new(:user, klass: MyTask, type: :hash) do
+    #     required :name, type: :string
+    #     optional :age, type: :integer
+    #   end
     #   ParameterSerializer.call(param)
     #   # => {
-    #   #   source: :user,
-    #   #   name: :name,
-    #   #   type: :string,
+    #   #   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)
       {

data/lib/cmdx/railtie.rb

@@ -1,102 +1,29 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Railtie provides seamless integration between CMDx and Ruby on Rails applications.
-  # It automatically configures Rails-specific features including internationalization,
-  # autoloading paths, and directory structure conventions for CMDx tasks and workflows.
+  # Rails integration for CMDx framework.
   #
-  # The Railtie handles two main integration aspects:
-  # 1. **I18n Configuration**: Automatically loads CMDx locale files for available locales
-  # 2. **Autoloading Setup**: Configures Rails autoloaders for CMDx command objects
-  #
-  # ## Directory Structure
-  #
-  # The Railtie expects CMDx command objects to be organized in the following structure:
-  # ```
-  # app/
-  #   cmds/
-  #     workflows/          # Workflow command objects
-  #       order_processing_workflow.rb
-  #     tasks/            # Task command objects
-  #       process_order_task.rb
-  #       send_email_task.rb
-  # ```
-  #
-  # ## Automatic Features
-  #
-  # When CMDx is included in a Rails application, the Railtie automatically:
-  # - Adds `app/cmds` to Rails autoload paths
-  # - Configures autoloader to collapse `app/cmds/workflows` and `app/cmds/tasks` directories
-  # - Loads appropriate locale files from CMDx gem for error messages and validations
-  # - Reloads I18n configuration to include CMDx translations
-  #
-  # @example Rails application structure
-  #   # app/cmds/tasks/process_order_task.rb
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :order_id, type: :integer
-  #
-  #     def call
-  #       context.order = Order.find(order_id)
-  #       context.order.process!
-  #     end
-  #   end
-  #
-  # @example Using in Rails controllers
-  #   class OrdersController < ApplicationController
-  #     def process
-  #       result = ProcessOrderTask.call(order_id: params[:id])
-  #
-  #       if result.success?
-  #         redirect_to order_path(result.context.order), notice: 'Order processed!'
-  #       else
-  #         redirect_to order_path(params[:id]), alert: result.metadata[:reason]
-  #       end
-  #     end
-  #   end
-  #
-  # @example I18n integration
-  #   # CMDx automatically loads locale files for validation messages
-  #   # en.yml, es.yml, etc. are automatically available
-  #   result = MyTask.call(invalid_param: nil)
-  #   result.errors.full_messages # Uses localized error messages
-  #
-  # @see Configuration Configuration options for Rails integration
-  # @see Task Task base class for command objects
-  # @see Workflow Workflow base class for multi-task operations
-  # @since 1.0.0
+  # Provides Rails-specific configuration including internationalization
+  # locale loading and autoload path configuration for CMDx workflows and tasks.
   class Railtie < Rails::Railtie
 
     railtie_name :cmdx
 
-    ##
-    # Configures internationalization (I18n) for CMDx in Rails applications.
-    # Automatically loads locale files from the CMDx gem for all configured
-    # application locales, ensuring error messages and validations are properly localized.
+    # Configure internationalization locales for CMDx.
     #
-    # This initializer:
-    # 1. Iterates through all configured application locales
-    # 2. Checks for corresponding CMDx locale files
-    # 3. Adds found locale files to I18n load path
-    # 4. Reloads I18n configuration
+    # Loads available locale files from the CMDx locales directory
+    # and adds them to the I18n load path. Only loads locales that
+    # are configured as available in the Rails application.
     #
     # @param app [Rails::Application] the Rails application instance
-    # @return [void]
     #
-    # @example Available locales
-    #   # If Rails app has config.i18n.available_locales = [:en, :es]
-    #   # This will load:
-    #   # - lib/locales/en.yml (CMDx English translations)
-    #   # - lib/locales/es.yml (CMDx Spanish translations)
+    # @return [void]
     #
-    # @example Localized error messages
-    #   # With Spanish locale active
-    #   class MyTask < CMDx::Task
-    #     required :name, presence: true
-    #   end
+    # @raise [StandardError] if I18n reload fails
     #
-    #   result = MyTask.call(name: "")
-    #   result.errors.full_messages # Returns Spanish error messages
+    # @example Configure locales during Rails initialization
+    #   # This initializer runs automatically during Rails boot
+    #   # when CMDx is included in a Rails application
     initializer("cmdx.configure_locales") do |app|
       Array(app.config.i18n.available_locales).each do |locale|
         path = File.expand_path("../../../lib/locales/#{locale}.yml", __FILE__)
@@ -108,34 +35,24 @@ module CMDx
       I18n.reload!
     end
 
-    ##
-    # Configures Rails autoloading for CMDx command objects.
-    # Sets up proper autoloading paths and directory collapsing to ensure
-    # CMDx tasks and workflows are loaded correctly in Rails applications.
+    # Configure Rails autoload paths for CMDx components.
     #
-    # This initializer:
-    # 1. Adds `app/cmds` to Rails autoload paths
-    # 2. Configures all autoloaders to collapse concept directories
-    # 3. Ensures proper class name resolution for nested directories
-    #
-    # Directory collapsing means that files in `app/cmds/tasks/` will be loaded
-    # as if they were directly in `app/cmds/`, allowing for better organization
-    # without affecting class naming conventions.
+    # Adds the app/cmds directory to Rails autoload paths and configures
+    # autoloaders to collapse the workflows and tasks subdirectories.
+    # This enables Rails to automatically load CMDx workflows and tasks
+    # from the conventional directory structure.
     #
     # @param app [Rails::Application] the Rails application instance
-    # @return [void]
     #
-    # @example Directory structure and class loading
-    #   # File: app/cmds/tasks/process_order_task.rb
-    #   # Class: ProcessOrderTask (not Tasks::ProcessOrderTask)
+    # @return [void]
     #
-    #   # File: app/cmds/workflows/order_processing_workflow.rb
-    #   # Class: OrderProcessingWorkflow (not Workflows::OrderProcessingWorkflow)
+    # @raise [StandardError] if autoloader configuration fails
     #
-    # @example Autoloading in action
-    #   # Rails will automatically load these classes when referenced:
-    #   ProcessOrderTask.call(order_id: 123)      # Loads from app/cmds/tasks/
-    #   OrderProcessingWorkflow.call(orders: [...])  # Loads from app/cmds/workflows/
+    # @example Configure autoload paths during Rails initialization
+    #   # This initializer runs automatically during Rails boot
+    #   # Enables loading of:
+    #   # - app/cmds/workflows/my_workflow.rb
+    #   # - app/cmds/tasks/my_task.rb
     initializer("cmdx.configure_rails_auto_load_paths") do |app|
       app.config.autoload_paths += %w[app/cmds]