cmdx 0.5.0 → 1.0.1

data/lib/cmdx/configuration.rb

@@ -2,24 +2,232 @@
 
 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.
+  #
+  # 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.
+  #
+  # ## 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
+  class Configuration
+
+    # Default configuration values
+    DEFAULT_HALT = "failed"
+
+    # Configuration attributes
+    attr_accessor :logger, :middlewares, :callbacks, :task_halt, :workflow_halt
+
+    ##
+    # Initializes a new configuration with default values.
+    #
+    # @example
+    #   config = CMDx::Configuration.new
+    def initialize
+      @logger      = ::Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
+      @middlewares = MiddlewareRegistry.new
+      @callbacks   = CallbackRegistry.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.
+    #
+    # @return [Hash] configuration attributes as a hash
+    # @example
+    #   config = CMDx.configuration
+    #   config.to_h  #=> { logger: ..., task_halt: "failed", ... }
+    def to_h
+      {
+        logger: @logger,
+        middlewares: @middlewares,
+        callbacks: @callbacks,
+        task_halt: @task_halt,
+        workflow_halt: @workflow_halt
+      }
+    end
+
+  end
+
   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.
+  #
+  # @return [Configuration] the current configuration object
+  #
+  # @example Accessing configuration values
+  #   CMDx.configuration.logger          #=> <Logger instance>
+  #   CMDx.configuration.task_halt       #=> "failed"
+  #
+  # @example Checking configuration state
+  #   config = CMDx.configuration
+  #   config.logger.class                #=> Logger
   def configuration
-    @configuration || reset_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.
+  #
+  # The configuration block yields the current configuration object,
+  # allowing you to set multiple options in a single, organized block.
+  #
+  # @yieldparam config [Configuration] the configuration object to modify
+  # @return [Configuration] the updated configuration object
+  # @raise [ArgumentError] if no block is provided
+  #
+  # @example Basic configuration
+  #   CMDx.configure do |config|
+  #     config.task_halt = ["failed", "skipped"]
+  #   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
+  #   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
+  #   end
   def configure
-    yield(configuration)
+    raise ArgumentError, "block required" unless block_given?
+
+    config = configuration
+    yield(config)
+    config
   end
 
+  ##
+  # Resets the configuration to default values.
+  # This method creates a fresh configuration object with framework defaults,
+  # discarding any previously set custom values.
+  #
+  # @return [Configuration] the newly created configuration with default values
+  #
+  # @example Resetting configuration
+  #   # After custom configuration
+  #   CMDx.configure { |c| c.task_halt = ["failed"] }
+  #   CMDx.configuration.task_halt  #=> ["failed"]
+  #
+  #   # Reset to defaults
+  #   CMDx.reset_configuration!
+  #   CMDx.configuration.task_halt  #=> "failed"
+  #
+  # @example Testing with clean configuration
+  #   # In test setup
+  #   def setup
+  #     CMDx.reset_configuration!  # Start with clean defaults
+  #   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 = LazyStruct.new(
-      logger: ::Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new),
-      task_halt: CMDx::Result::FAILED,
-      task_timeout: nil,
-      batch_halt: CMDx::Result::FAILED,
-      batch_timeout: nil
-    )
+    @configuration = Configuration.new
   end
 
 end

data/lib/cmdx/context.rb

@@ -1,10 +1,181 @@
 # 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
   class Context < LazyStruct
 
-    attr_reader :run
-
+    ##
+    # Builds a Context instance from the given input, with intelligent handling
+    # of existing Context objects to avoid unnecessary object creation.
+    #
+    # 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
+    #
+    # @param context [Hash, Context, #to_h] input data for context creation
+    # @return [Context] a Context instance ready for task execution
+    #
+    # @example Creating context from hash
+    #   context = Context.build(name: "John", age: 30)
+    #   context.name  #=> "John"
+    #   context.age   #=> 30
+    #
+    # @example Reusing unfrozen context
+    #   original = Context.build(data: "test")
+    #   reused = Context.build(original)
+    #   original.object_id == reused.object_id  #=> true
+    #
+    # @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 Converting ActionController::Parameters
+    #   # In Rails controllers
+    #   params = ActionController::Parameters.new(user: { name: "John" })
+    #   context = Context.build(params.permit(:user))
+    #   context.user  #=> { name: "John" }
+    #
+    # @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
     def self.build(context = {})
       return context if context.is_a?(self) && !context.frozen?
 

data/lib/cmdx/core_ext/hash.rb

@@ -2,8 +2,50 @@
 
 module CMDx
   module CoreExt
+    # Extensions to Hash that provide CMDx-specific key access methods.
+    #
+    # HashExtensions adds flexible key access that works with both
+    # string and symbol keys interchangeably. These methods are prefixed
+    # with `__cmdx_` to avoid conflicts with existing Hash methods.
+    #
+    # @example Flexible key access
+    #   hash = {name: "John", "age" => 30}
+    #   hash.__cmdx_fetch(:name)      # => "John" (symbol key)
+    #   hash.__cmdx_fetch("name")     # => "John" (tries symbol fallback)
+    #   hash.__cmdx_fetch(:age)       # => 30 (string fallback)
+    #
+    # @example Key checking
+    #   hash.__cmdx_key?(:name)       # => true (checks both symbol and string)
+    #   hash.__cmdx_key?("age")       # => true (checks both string and symbol)
+    #
+    # @example Method response checking
+    #   hash.__cmdx_respond_to?(:name)   # => true (considers key as method)
+    #
+    # @see Context Context objects that use hash extensions
+    # @see LazyStruct Structs that leverage hash-like behavior
     module HashExtensions
 
+      # Fetch a value with automatic symbol/string key conversion.
+      #
+      # This method provides flexible key access by trying both the original
+      # key and its converted form (symbol to string or string to symbol).
+      # This is particularly useful for parameter hashes that might use
+      # either format.
+      #
+      # @param key [Symbol, String, Object] key to fetch
+      # @return [Object] value for the key or its converted equivalent
+      #
+      # @example Symbol to string conversion
+      #   hash = {"name" => "John"}
+      #   hash.__cmdx_fetch(:name)        # => "John" (tries :name, then "name")
+      #
+      # @example String to symbol conversion
+      #   hash = {name: "John"}
+      #   hash.__cmdx_fetch("name")       # => "John" (tries "name", then :name)
+      #
+      # @example Direct key access
+      #   hash = {id: 123}
+      #   hash.__cmdx_fetch(:id)          # => 123 (direct match)
       def __cmdx_fetch(key)
         case key
         when Symbol then fetch(key) { self[key.to_s] }
@@ -12,6 +54,20 @@ module CMDx
         end
       end
 
+      # Check if a key exists with automatic symbol/string conversion.
+      #
+      # This method checks for key existence by trying both the original
+      # key and its converted form. Returns true if either variant exists.
+      #
+      # @param key [Symbol, String, Object] key to check
+      # @return [Boolean] true if key exists in either format
+      #
+      # @example Symbol/string checking
+      #   hash = {name: "John", "age" => 30}
+      #   hash.__cmdx_key?(:name)         # => true
+      #   hash.__cmdx_key?("name")        # => true (checks :name fallback)
+      #   hash.__cmdx_key?(:age)          # => true (checks "age" fallback)
+      #   hash.__cmdx_key?(:missing)      # => false
       def __cmdx_key?(key)
         key?(key) || key?(
           case key
@@ -23,6 +79,21 @@ module CMDx
         false
       end
 
+      # Check if hash responds to a method or contains a key.
+      #
+      # This method extends respond_to? behavior to also check if the
+      # hash contains a key that matches the method name. This enables
+      # hash keys to be treated as virtual methods.
+      #
+      # @param key [Symbol, String] method name to check
+      # @param include_private [Boolean] whether to include private methods
+      # @return [Boolean] true if responds to method or contains key
+      #
+      # @example Method response checking
+      #   hash = {name: "John"}
+      #   hash.__cmdx_respond_to?(:name)     # => true (has key :name)
+      #   hash.__cmdx_respond_to?(:keys)     # => true (real Hash method)
+      #   hash.__cmdx_respond_to?(:missing)  # => false
       def __cmdx_respond_to?(key, include_private = false)
         respond_to?(key.to_sym, include_private) || __cmdx_key?(key)
       rescue NoMethodError
@@ -33,4 +104,5 @@ module CMDx
   end
 end
 
+# Extend all hashes with CMDx utility methods
 Hash.include(CMDx::CoreExt::HashExtensions)

data/lib/cmdx/core_ext/module.rb

@@ -2,8 +2,64 @@
 
 module CMDx
   module CoreExt
+    # Extensions to Module that provide CMDx-specific metaprogramming capabilities.
+    #
+    # ModuleExtensions adds method delegation and attribute setting functionality
+    # used throughout the CMDx framework. These methods enable declarative
+    # programming patterns and automatic method generation.
+    #
+    # @example Method delegation
+    #   class Task
+    #     __cmdx_attr_delegator :name, :email, to: :user
+    #     __cmdx_attr_delegator :save, to: :record, private: true
+    #   end
+    #
+    # @example Attribute settings
+    #   class Task
+    #     __cmdx_attr_setting :default_options, default: -> { {} }
+    #     __cmdx_attr_setting :configuration, default: {}
+    #   end
+    #
+    # @see Task Tasks that use module extensions for delegation
+    # @see Parameter Parameters that use attribute settings
     module ModuleExtensions
 
+      # Create delegator methods that forward calls to another object.
+      #
+      # This method generates instance methods that delegate to methods on
+      # another object. It supports method visibility controls and optional
+      # missing method handling.
+      #
+      # @param methods [Array<Symbol>] method names to delegate
+      # @param options [Hash] delegation options
+      # @option options [Symbol] :to target object method name (required)
+      # @option options [Boolean] :allow_missing whether to allow missing methods
+      # @option options [Boolean] :private make delegated methods private
+      # @option options [Boolean] :protected make delegated methods protected
+      # @return [void]
+      #
+      # @example Basic delegation
+      #   class User
+      #     __cmdx_attr_delegator :first_name, :last_name, to: :profile
+      #     # Creates: def first_name; profile.first_name; end
+      #   end
+      #
+      # @example Private delegation
+      #   class Task
+      #     __cmdx_attr_delegator :validate, to: :validator, private: true
+      #   end
+      #
+      # @example Class delegation
+      #   class Task
+      #     __cmdx_attr_delegator :configuration, to: :class
+      #   end
+      #
+      # @example With missing method handling
+      #   class Task
+      #     __cmdx_attr_delegator :optional_method, to: :service, allow_missing: true
+      #   end
+      #
+      # @raise [NoMethodError] if target object doesn't respond to method and allow_missing is false
       def __cmdx_attr_delegator(*methods, **options)
         methods.each do |method|
           method_name = Utils::NameAffix.call(method, options.fetch(:to), options)
@@ -27,6 +83,43 @@ module CMDx
         end
       end
 
+      # Create class-level attribute accessor with lazy evaluation and inheritance.
+      #
+      # This method generates a class method that provides lazy-loaded attribute
+      # access with inheritance support. Values are cached and can be initialized
+      # with default values or procs.
+      #
+      # @param method [Symbol] name of the attribute method
+      # @param options [Hash] attribute options
+      # @option options [Object, Proc] :default default value or proc to generate value
+      # @return [void]
+      #
+      # @example Simple attribute setting
+      #   class Task
+      #     __cmdx_attr_setting :timeout, default: 30
+      #   end
+      #   # Task.timeout => 30
+      #
+      # @example Dynamic default with proc
+      #   class Task
+      #     __cmdx_attr_setting :timestamp, default: -> { Time.now }
+      #   end
+      #   # Task.timestamp => current time (evaluated lazily)
+      #
+      # @example Inherited settings
+      #   class BaseTask
+      #     __cmdx_attr_setting :options, default: {retry: 3}
+      #   end
+      #
+      #   class ProcessTask < BaseTask
+      #   end
+      #   # ProcessTask.options => {retry: 3} (inherited from BaseTask)
+      #
+      # @example Hash settings (automatically duplicated)
+      #   class Task
+      #     __cmdx_attr_setting :config, default: {}
+      #   end
+      #   # Each class gets its own copy of the hash
       def __cmdx_attr_setting(method, **options)
         define_singleton_method(method) do
           @cmd_facets ||= {}
@@ -45,4 +138,5 @@ module CMDx
   end
 end
 
+# Extend all modules with CMDx utility methods
 Module.include(CMDx::CoreExt::ModuleExtensions)