cmdx 1.0.1 → 1.1.1

data/lib/cmdx/configuration.rb

@@ -2,119 +2,90 @@
 
 module CMDx
 
-  ##
-  # Provides global configuration management for CMDx framework settings.
-  # The configuration system allows customization of default behaviors for tasks,
-  # workflows, logging, and error handling across the entire application.
+  # Global configuration class for CMDx framework settings.
   #
-  # Configuration settings are stored as instance variables with explicit accessors
-  # and can be modified through the configure block pattern. These settings serve
-  # as defaults that can be overridden at the task or workflow level when needed.
+  # Manages logging, middleware, callbacks, coercions, validators, and halt conditions
+  # for the entire CMDx framework. The Configuration class provides centralized control
+  # over framework behavior including task execution flow, error handling, and component
+  # registration. All settings configured here become defaults for tasks and workflows
+  # unless explicitly overridden at the task or workflow level.
   #
-  # ## Available Configuration Options
-  #
-  # - **logger**: Logger instance for task execution logging
-  # - **task_halt**: Result statuses that cause `call!` to raise faults
-  # - **workflow_halt**: Result statuses that halt workflow execution
-  # - **middlewares**: Global middleware registry applied to all tasks
-  # - **callbacks**: Global callback registry applied to all tasks
-  #
-  # ## Configuration Hierarchy
-  #
-  # CMDx follows a configuration hierarchy where settings can be overridden:
-  # 1. **Global Configuration**: Framework-wide defaults (this module)
-  # 2. **Task Settings**: Class-level overrides via `task_settings!`
-  # 3. **Runtime Parameters**: Instance-specific overrides during execution
-  #
-  # @example Basic configuration setup
-  #   CMDx.configure do |config|
-  #     config.logger = Logger.new($stdout)
-  #     config.task_halt = ["failed"] # Only halt on failures
-  #     config.middlewares.use CMDx::Middlewares::Timeout, 30
-  #   end
-  #
-  # @example Rails initializer configuration
-  #   # config/initializers/cmdx.rb
-  #   CMDx.configure do |config|
-  #     config.logger = Logger.new($stdout)
-  #     config.task_halt = CMDx::Result::FAILED
-  #     config.workflow_halt = [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
-  #
-  #     # Add global middlewares
-  #     config.middlewares.use CMDx::Middlewares::Timeout, 30
-  #     config.middlewares.use AuthenticationMiddleware if Rails.env.production?
-  #
-  #     # Add global callbacks
-  #     config.callbacks.register :before_execution, :log_task_start
-  #     config.callbacks.register :on_success, NotificationCallback.new([:slack])
-  #     config.callbacks.register :on_failure, :alert_admin, if: :production?
-  #   end
-  #
-  # @example Custom logger configuration
-  #   CMDx.configure do |config|
-  #     config.logger = Logger.new(
-  #       Rails.root.join('log', 'cmdx.log'),
-  #       formatter: CMDx::LogFormatters::Json.new
-  #     )
-  #   end
-  #
-  # @example Environment-specific configuration
-  #   CMDx.configure do |config|
-  #     case Rails.env
-  #     when 'development'
-  #       config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::PrettyLine.new)
-  #     when 'test'
-  #       config.logger = Logger.new('/dev/null')  # Silent logging
-  #     when 'production'
-  #       config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Json.new)
-  #     end
-  #   end
-  #
-  # @see Task Task-level configuration overrides
-  # @see Workflow Workflow-level configuration overrides
-  # @see LogFormatters Available logging formatters
-  # @see Result Result statuses for halt configuration
-  # @since 1.0.0
-
-  ##
-  # Configuration class that manages CMDx framework settings.
-  # Provides explicit attribute accessors for all configuration options.
-  #
-  # @since 1.0.0
+  # The configuration system supports both global and per-task customization, allowing
+  # fine-grained control over framework behavior while maintaining sensible defaults.
   class Configuration
 
-    # Default configuration values
     DEFAULT_HALT = "failed"
 
-    # Configuration attributes
-    attr_accessor :logger, :middlewares, :callbacks, :task_halt, :workflow_halt
+    # @return [Logger] Logger instance for task execution logging
+    attr_accessor :logger
+
+    # @return [MiddlewareRegistry] Global middleware registry applied to all tasks
+    attr_accessor :middlewares
+
+    # @return [CallbackRegistry] Global callback registry applied to all tasks
+    attr_accessor :callbacks
 
-    ##
-    # Initializes a new configuration with default values.
+    # @return [CoercionRegistry] Global coercion registry for custom parameter types
+    attr_accessor :coercions
+
+    # @return [ValidatorRegistry] Global validator registry for custom parameter validation
+    attr_accessor :validators
+
+    # @return [String, Array<String>] Result statuses that cause `call!` to raise faults
+    attr_accessor :task_halt
+
+    # @return [String, Array<String>] Result statuses that halt workflow execution
+    attr_accessor :workflow_halt
+
+    # Creates a new configuration instance with default settings.
+    #
+    # Initializes all configuration attributes with sensible defaults including
+    # a stdout logger with line formatting, empty registries for extensibility
+    # components, and default halt conditions for both tasks and workflows.
     #
-    # @example
-    #   config = CMDx::Configuration.new
+    # @return [Configuration] a new configuration instance with default settings
+    #
+    # @example Create a new configuration
+    #   config = Configuration.new
+    #   config.logger.class #=> Logger
+    #   config.task_halt #=> "failed"
     def initialize
-      @logger      = ::Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
-      @middlewares = MiddlewareRegistry.new
-      @callbacks   = CallbackRegistry.new
-      @task_halt   = DEFAULT_HALT
+      @logger        = ::Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
+      @middlewares   = MiddlewareRegistry.new
+      @callbacks     = CallbackRegistry.new
+      @coercions     = CoercionRegistry.new
+      @validators    = ValidatorRegistry.new
+      @task_halt     = DEFAULT_HALT
       @workflow_halt = DEFAULT_HALT
     end
 
-    ##
-    # Returns a hash representation of the configuration.
-    # Used internally by the framework for configuration merging.
+    # Converts the configuration to a hash representation.
+    #
+    # Creates a hash containing all configuration attributes for serialization,
+    # inspection, or transfer between processes. The hash includes all registries
+    # and settings in their current state.
+    #
+    # @return [Hash] hash representation of the configuration
+    # @option return [Logger] :logger the configured logger instance
+    # @option return [MiddlewareRegistry] :middlewares the middleware registry
+    # @option return [CallbackRegistry] :callbacks the callback registry
+    # @option return [CoercionRegistry] :coercions the coercion registry
+    # @option return [ValidatorRegistry] :validators the validator registry
+    # @option return [String, Array<String>] :task_halt the task halt configuration
+    # @option return [String, Array<String>] :workflow_halt the workflow halt configuration
     #
-    # @return [Hash] configuration attributes as a hash
-    # @example
-    #   config = CMDx.configuration
-    #   config.to_h  #=> { logger: ..., task_halt: "failed", ... }
+    # @example Convert configuration to hash
+    #   config = Configuration.new
+    #   hash = config.to_h
+    #   hash[:logger].class #=> Logger
+    #   hash[:task_halt] #=> "failed"
     def to_h
       {
         logger: @logger,
         middlewares: @middlewares,
         callbacks: @callbacks,
+        coercions: @coercions,
+        validators: @validators,
         task_halt: @task_halt,
         workflow_halt: @workflow_halt
       }
@@ -124,71 +95,48 @@ module CMDx
 
   module_function
 
-  ##
   # Returns the current global configuration instance.
-  # Creates a new configuration with default values if none exists.
   #
-  # The configuration is stored as a module-level variable and persists
-  # throughout the application lifecycle. It uses lazy initialization,
-  # creating the configuration only when first accessed.
+  # Provides access to the singleton configuration instance used by the entire
+  # CMDx framework. Creates a new configuration with default settings if none
+  # exists. This method is thread-safe and ensures only one configuration
+  # instance exists per process.
   #
-  # @return [Configuration] the current configuration object
+  # @return [Configuration] the current global configuration instance
   #
-  # @example Accessing configuration values
-  #   CMDx.configuration.logger          #=> <Logger instance>
-  #   CMDx.configuration.task_halt       #=> "failed"
-  #
-  # @example Checking configuration state
+  # @example Access global configuration
   #   config = CMDx.configuration
-  #   config.logger.class                #=> Logger
+  #   config.logger.level = Logger::DEBUG
+  #   config.task_halt = ["failed", "skipped"]
   def configuration
     return @configuration if @configuration
 
     @configuration ||= Configuration.new
   end
 
-  ##
-  # Configures CMDx settings using a block-based DSL.
-  # This is the preferred method for setting up CMDx configuration
-  # as it provides a clean, readable syntax for configuration management.
+  # Configures the global CMDx settings using a block.
+  #
+  # Yields the current configuration instance to the provided block for
+  # modification. This is the recommended way to configure CMDx as it
+  # provides a clean DSL-like interface for setting up the framework.
   #
-  # The configuration block yields the current configuration object,
-  # allowing you to set multiple options in a single, organized block.
+  # @param block [Proc] configuration block that receives the configuration instance
+  #
+  # @return [Configuration] the configured configuration instance
   #
-  # @yieldparam config [Configuration] the configuration object to modify
-  # @return [Configuration] the updated configuration object
   # @raise [ArgumentError] if no block is provided
   #
-  # @example Basic configuration
+  # @example Configure CMDx settings
   #   CMDx.configure do |config|
+  #     config.logger.level = Logger::INFO
   #     config.task_halt = ["failed", "skipped"]
+  #     config.middlewares.register(CMDx::Middlewares::Timeout.new(seconds: 30))
   #   end
   #
-  # @example Complex configuration with conditionals
-  #   CMDx.configure do |config|
-  #     config.logger = Rails.logger if defined?(Rails)
-  #
-  #     config.task_halt = if Rails.env.production?
-  #       "failed"  # Only halt on failures in production
-  #     else
-  #       ["failed", "skipped"]  # Halt on both in development
-  #     end
-  #
-
-  #   end
-  #
-  # @example Formatter configuration
+  # @example Configure with custom logger
   #   CMDx.configure do |config|
-  #     config.logger = Logger.new($stdout).tap do |logger|
-  #       logger.formatter = case ENV['LOG_FORMAT']
-  #       when 'json'
-  #         CMDx::LogFormatters::Json.new
-  #       when 'pretty'
-  #         CMDx::LogFormatters::PrettyLine.new
-  #       else
-  #         CMDx::LogFormatters::Line.new
-  #       end
-  #     end
+  #     config.logger = Rails.logger
+  #     config.logger.formatter = CMDx::LogFormatters::JSON.new
   #   end
   def configure
     raise ArgumentError, "block required" unless block_given?
@@ -198,34 +146,25 @@ module CMDx
     config
   end
 
-  ##
-  # Resets the configuration to default values.
-  # This method creates a fresh configuration object with framework defaults,
-  # discarding any previously set custom values.
+  # Resets the global configuration to default settings.
+  #
+  # Creates a new configuration instance with default settings, discarding
+  # any existing configuration. This is useful for testing scenarios or
+  # when you need to start with a clean configuration state.
   #
-  # @return [Configuration] the newly created configuration with default values
+  # @return [Configuration] a new configuration instance with default settings
   #
-  # @example Resetting configuration
-  #   # After custom configuration
-  #   CMDx.configure { |c| c.task_halt = ["failed"] }
-  #   CMDx.configuration.task_halt  #=> ["failed"]
+  # @example Reset to defaults
+  #   CMDx.configure { |c| c.task_halt = ["failed", "skipped"] }
+  #   CMDx.configuration.task_halt #=> ["failed", "skipped"]
   #
-  #   # Reset to defaults
   #   CMDx.reset_configuration!
-  #   CMDx.configuration.task_halt  #=> "failed"
+  #   CMDx.configuration.task_halt #=> "failed"
   #
-  # @example Testing with clean configuration
-  #   # In test setup
-  #   def setup
-  #     CMDx.reset_configuration!  # Start with clean defaults
+  # @example Use in test setup
+  #   RSpec.configure do |config|
+  #     config.before(:each) { CMDx.reset_configuration! }
   #   end
-  #
-  # @example Conditional reset
-  #   # Reset configuration in development for experimentation
-  #   CMDx.reset_configuration! if Rails.env.development?
-  #
-  # @note This method is primarily useful for testing or when you need
-  #   to return to a known default state.
   def reset_configuration!
     @configuration = Configuration.new
   end

data/lib/cmdx/context.rb

@@ -1,181 +1,49 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Context provides a flexible parameter storage and data passing mechanism for CMDx tasks.
-  # It extends LazyStruct to offer dynamic attribute access with both hash-style and method-style
-  # syntax, serving as the primary interface for task input parameters and inter-task communication.
-  #
-  # Context objects act as the data container for task execution, holding input parameters,
-  # intermediate results, and any data that needs to be shared between tasks. They support
-  # dynamic attribute assignment and provide a convenient API for data manipulation throughout
-  # the task execution lifecycle.
-  #
-  #
-  # ## Usage Patterns
-  #
-  # Context is typically used in three main scenarios:
-  # 1. **Parameter Input**: Passing initial data to tasks
-  # 2. **Data Storage**: Storing intermediate results during task execution
-  # 3. **Task Communication**: Sharing data between multiple tasks
-  #
-  # @example Basic parameter input
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :order_id, type: :integer
-  #     optional :notify_customer, type: :boolean, default: true
-  #
-  #     def call
-  #       context.order = Order.find(order_id)
-  #       context.processed_at = Time.now
-  #
-  #       if notify_customer
-  #         context.notification_sent = send_notification
-  #       end
-  #     end
-  #   end
-  #
-  #   result = ProcessOrderTask.call(order_id: 123, notify_customer: false)
-  #   result.context.order         #=> <Order id: 123>
-  #   result.context.processed_at  #=> 2023-01-01 12:00:00 UTC
-  #   result.context.notification_sent #=> nil
-  #
-  # @example Dynamic attribute assignment
-  #   class DataProcessingTask < CMDx::Task
-  #     required :input_data, type: :hash
-  #
-  #     def call
-  #       # Method-style assignment
-  #       context.processed_data = transform(input_data)
-  #       context.validation_errors = validate(context.processed_data)
-  #
-  #       # Hash-style assignment
-  #       context[:metadata] = { processed_at: Time.now }
-  #       context["summary"] = generate_summary
-  #
-  #       # Workflow assignment
-  #       context.merge!(
-  #         status: "complete",
-  #         record_count: context.processed_data.size
-  #       )
-  #     end
-  #   end
-  #
-  # @example Inter-task communication
-  #   class OrderProcessingWorkflow < CMDx::Workflow
-  #     def call
-  #       # First task sets up context
-  #       ValidateOrderTask.call(context)
-  #
-  #       # Subsequent tasks use and modify context
-  #       ProcessPaymentTask.call(context)
-  #       UpdateInventoryTask.call(context)
-  #       SendConfirmationTask.call(context)
-  #     end
-  #   end
-  #
-  #   # Initial context with order data
-  #   result = OrderProcessingWorkflow.call(
-  #     order_id: 123,
-  #     payment_method: "credit_card",
-  #     customer_email: "customer@example.com"
-  #   )
-  #
-  #   # Context accumulates data from all tasks
-  #   result.context.order           #=> <Order> (from ValidateOrderTask)
-  #   result.context.payment_result  #=> <Payment> (from ProcessPaymentTask)
-  #   result.context.inventory_updated #=> true (from UpdateInventoryTask)
-  #   result.context.confirmation_sent #=> true (from SendConfirmationTask)
-  #
-  # @example Context passing between tasks
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :order_id, type: :integer
-  #
-  #     def call
-  #       context.order = Order.find(order_id)
-  #
-  #       # Pass context to subtasks
-  #       payment_result = ProcessPaymentTask.call(context)
-  #       email_result = SendEmailTask.call(context)
-  #
-  #       # Results maintain context continuity
-  #       context.payment_processed = payment_result.success?
-  #       context.email_sent = email_result.success?
-  #     end
-  #   end
-  #
-  #   # After execution, context contains accumulated data
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   result.context.order              #=> <Order>
-  #   result.context.payment_processed  #=> true
-  #   result.context.email_sent         #=> true
-  #
-  # @example Context with nested data structures
-  #   class AnalyticsTask < CMDx::Task
-  #     required :user_id, type: :integer
-  #
-  #     def call
-  #       context.user = User.find(user_id)
-  #       context.analytics = {
-  #         page_views: calculate_page_views,
-  #         session_duration: calculate_session_duration,
-  #         conversion_rate: calculate_conversion_rate
-  #       }
-  #
-  #       # Access nested data
-  #       context.dig(:analytics, :page_views)  #=> 150
-  #
-  #       # Add more nested data
-  #       context.analytics[:last_login] = context.user.last_login
-  #     end
-  #   end
-  #
-  # @see LazyStruct Base class providing dynamic attribute functionality
-  # @see Task Task base class that uses Context for parameter storage
-  # @see Chain Chain execution context that Context belongs to
-  # @see Parameter Parameter definitions that populate Context
-  # @since 1.0.0
+  # Execution context container for task parameter storage and access.
+  #
+  # Context provides normalized parameter storage for task execution, inheriting
+  # from LazyStruct to provide flexible attribute access patterns. It serves as
+  # the primary interface for storing and retrieving execution parameters, allowing
+  # both hash-style and method-style attribute access with automatic key normalization.
+  # Context instances are used throughout task execution to maintain parameter state
+  # and provide consistent data access across the task lifecycle.
   class Context < LazyStruct
 
-    ##
-    # Builds a Context instance from the given input, with intelligent handling
-    # of existing Context objects to avoid unnecessary object creation.
+    # Creates or returns a Context instance from the provided input.
     #
-    # This factory method provides optimized Context creation by:
-    # - Returning existing Context objects if they're unfrozen (reusable)
-    # - Creating new Context objects for frozen contexts (immutable)
-    # - Converting hash-like objects into new Context instances
+    # This factory method normalizes various input types into a proper Context instance,
+    # ensuring consistent context handling throughout the framework. If the input is
+    # already a Context instance and not frozen, it returns the input unchanged to
+    # avoid unnecessary object creation. Otherwise, it creates a new Context instance
+    # with the provided data.
     #
-    # @param context [Hash, Context, #to_h] input data for context creation
-    # @return [Context] a Context instance ready for task execution
+    # @param context [Hash, Context, Object] input data to convert to Context
+    # @option context [Object] any any attribute keys and values for context initialization
     #
-    # @example Creating context from hash
-    #   context = Context.build(name: "John", age: 30)
-    #   context.name  #=> "John"
-    #   context.age   #=> 30
+    # @return [Context] a Context instance containing the provided data
     #
-    # @example Reusing unfrozen context
-    #   original = Context.build(data: "test")
-    #   reused = Context.build(original)
-    #   original.object_id == reused.object_id  #=> true
+    # @example Create context from hash
+    #   context = Context.build(user_id: 123, action: "process")
+    #   context.user_id #=> 123
+    #   context.action #=> "process"
     #
-    # @example Creating new context from frozen context
-    #   original = Context.build(data: "test")
-    #   original.freeze
-    #   new_context = Context.build(original)
-    #   original.object_id == new_context.object_id  #=> false
+    # @example Return existing unfrozen context
+    #   existing = Context.new(status: "active")
+    #   result = Context.build(existing)
+    #   result.equal?(existing) #=> true
     #
-    # @example Converting ActionController::Parameters
-    #   # In Rails controllers
-    #   params = ActionController::Parameters.new(user: { name: "John" })
-    #   context = Context.build(params.permit(:user))
-    #   context.user  #=> { name: "John" }
+    # @example Create new context from frozen context
+    #   frozen_context = Context.new(data: "test").freeze
+    #   new_context = Context.build(frozen_context)
+    #   new_context.equal?(frozen_context) #=> false
+    #   new_context.data #=> "test"
     #
-    # @example Task execution with built context
-    #   # CMDx automatically uses Context.build for task parameters
-    #   result = ProcessOrderTask.call(order_id: 123, priority: "high")
-    #   # Equivalent to:
-    #   # context = Context.build(order_id: 123, priority: "high")
-    #   # ProcessOrderTask.new(context).call
+    # @example Create context from empty input
+    #   context = Context.build
+    #   context.class #=> CMDx::Context
+    #   context.to_h #=> {}
     def self.build(context = {})
       return context if context.is_a?(self) && !context.frozen?