cmdx 1.1.2 → 1.5.0

data/lib/cmdx/configuration.rb

@@ -2,141 +2,94 @@
 
 module CMDx
 
-  # Global configuration class for CMDx framework settings.
-  #
-  # 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.
-  #
-  # The configuration system supports both global and per-task customization, allowing
-  # fine-grained control over framework behavior while maintaining sensible defaults.
+  # Configuration class that manages global settings for CMDx including middlewares,
+  # callbacks, coercions, validators, breakpoints, and logging.
   class Configuration
 
-    DEFAULT_HALT = "failed"
-
-    # @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
+    DEFAULT_BREAKPOINTS = %w[failed].freeze
 
-    # @return [CoercionRegistry] Global coercion registry for custom parameter types
-    attr_accessor :coercions
+    attr_accessor :middlewares, :callbacks, :coercions, :validators,
+                  :task_breakpoints, :workflow_breakpoints, :logger
 
-    # @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 a new Configuration instance with default values.
     #
-    # 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.
+    # Creates new registry instances for middlewares, callbacks, coercions, and
+    # validators. Sets default breakpoints and configures a basic logger.
     #
-    # @return [Configuration] a new configuration instance with default settings
+    # @return [Configuration] a new Configuration instance
     #
-    # @example Create a new configuration
+    # @example
     #   config = Configuration.new
-    #   config.logger.class #=> Logger
-    #   config.task_halt #=> "failed"
+    #   config.middlewares.class # => MiddlewareRegistry
+    #   config.task_breakpoints # => ["failed"]
     def initialize
-      @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
+      @middlewares = MiddlewareRegistry.new
+      @callbacks = CallbackRegistry.new
+      @coercions = CoercionRegistry.new
+      @validators = ValidatorRegistry.new
+
+      @task_breakpoints = DEFAULT_BREAKPOINTS
+      @workflow_breakpoints = DEFAULT_BREAKPOINTS
+
+      @logger = Logger.new(
+        $stdout,
+        progname: "cmdx",
+        formatter: LogFormatters::Line.new,
+        level: Logger::INFO
+      )
     end
 
     # 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<Symbol, Object>] hash containing all configuration values
     #
-    # @example Convert configuration to hash
+    # @example
     #   config = Configuration.new
-    #   hash = config.to_h
-    #   hash[:logger].class #=> Logger
-    #   hash[:task_halt] #=> "failed"
+    #   config.to_h
+    #   # => { middlewares: #<MiddlewareRegistry>, callbacks: #<CallbackRegistry>, ... }
     def to_h
       {
-        logger: @logger,
         middlewares: @middlewares,
         callbacks: @callbacks,
         coercions: @coercions,
         validators: @validators,
-        task_halt: @task_halt,
-        workflow_halt: @workflow_halt
+        task_breakpoints: @task_breakpoints,
+        workflow_breakpoints: @workflow_breakpoints,
+        logger: @logger
       }
     end
 
   end
 
-  module_function
+  extend self
 
-  # Returns the current global configuration instance.
+  # Returns the global configuration instance, creating it if it doesn't exist.
   #
-  # 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 global configuration instance
   #
-  # @return [Configuration] the current global configuration instance
-  #
-  # @example Access global configuration
+  # @example
   #   config = CMDx.configuration
-  #   config.logger.level = Logger::DEBUG
-  #   config.task_halt = ["failed", "skipped"]
+  #   config.middlewares # => #<MiddlewareRegistry>
   def configuration
     return @configuration if @configuration
 
     @configuration ||= Configuration.new
   end
 
-  # Configures the global CMDx settings using a block.
+  # Configures CMDx using a block that receives the configuration instance.
   #
-  # 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.
+  # @param block [Proc] the configuration block
   #
-  # @param block [Proc] configuration block that receives the configuration instance
+  # @yield [Configuration] the configuration instance to configure
   #
   # @return [Configuration] the configured configuration instance
   #
-  # @raise [ArgumentError] if no block is provided
-  #
-  # @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
+  # @raise [ArgumentError] when no block is provided
   #
-  # @example Configure with custom logger
+  # @example
   #   CMDx.configure do |config|
-  #     config.logger = Rails.logger
-  #     config.logger.formatter = CMDx::LogFormatters::JSON.new
+  #     config.task_breakpoints = ["failed", "skipped"]
+  #     config.logger.level = Logger::DEBUG
   #   end
   def configure
     raise ArgumentError, "block required" unless block_given?
@@ -146,25 +99,13 @@ module CMDx
     config
   end
 
-  # Resets the global configuration to default settings.
+  # Resets the global configuration to a new instance with default values.
   #
-  # 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] a new configuration instance with default settings
-  #
-  # @example Reset to defaults
-  #   CMDx.configure { |c| c.task_halt = ["failed", "skipped"] }
-  #   CMDx.configuration.task_halt #=> ["failed", "skipped"]
+  # @return [Configuration] the new configuration instance
   #
+  # @example
   #   CMDx.reset_configuration!
-  #   CMDx.configuration.task_halt #=> "failed"
-  #
-  # @example Use in test setup
-  #   RSpec.configure do |config|
-  #     config.before(:each) { CMDx.reset_configuration! }
-  #   end
+  #   # Configuration is now reset to defaults
   def reset_configuration!
     @configuration = Configuration.new
   end

data/lib/cmdx/context.rb

@@ -1,53 +1,231 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Execution context container for task parameter storage and access.
+  # A hash-like context object that provides a flexible way to store and access
+  # key-value pairs during task execution. Keys are automatically converted to
+  # symbols for consistency.
   #
-  # 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
-
-    # Creates or returns a Context instance from the provided input.
-    #
-    # 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, Object] input data to convert to Context
-    # @option context [Object] any any attribute keys and values for context initialization
-    #
-    # @return [Context] a Context instance containing the provided data
-    #
-    # @example Create context from hash
-    #   context = Context.build(user_id: 123, action: "process")
-    #   context.user_id #=> 123
-    #   context.action #=> "process"
-    #
-    # @example Return existing unfrozen context
-    #   existing = Context.new(status: "active")
-    #   result = Context.build(existing)
-    #   result.equal?(existing) #=> true
-    #
-    # @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 Create context from empty input
-    #   context = Context.build
-    #   context.class #=> CMDx::Context
-    #   context.to_h #=> {}
+  # The Context class extends Forwardable to delegate common hash methods and
+  # provides additional convenience methods for working with context data.
+  class Context
+
+    extend Forwardable
+
+    attr_reader :table
+    alias to_h table
+
+    def_delegators :table, :each, :map
+
+    # Creates a new Context instance from the given arguments.
+    #
+    # @param args [Hash, Object] arguments to initialize the context with
+    # @option args [Object] :key the key-value pairs to store in the context
+    #
+    # @return [Context] a new Context instance
+    #
+    # @raise [ArgumentError] when args doesn't respond to `to_h` or `to_hash`
+    #
+    # @example
+    #   context = Context.new(name: "John", age: 30)
+    #   context[:name] # => "John"
+    def initialize(args = {})
+      @table =
+        if args.respond_to?(:to_hash)
+          args.to_hash
+        elsif args.respond_to?(:to_h)
+          args.to_h
+        else
+          raise ArgumentError, "must respond to `to_h` or `to_hash`"
+        end.transform_keys(&:to_sym)
+    end
+
+    # Builds a Context instance, reusing existing unfrozen contexts when possible.
+    #
+    # @param context [Context, Object] the context to build from
+    # @option context [Object] :key the key-value pairs to store in the context
+    #
+    # @return [Context] a Context instance, either new or reused
+    #
+    # @example
+    #   existing = Context.new(name: "John")
+    #   built = Context.build(existing) # reuses existing context
+    #   built.object_id == existing.object_id # => true
     def self.build(context = {})
-      return context if context.is_a?(self) && !context.frozen?
+      if context.is_a?(self) && !context.frozen?
+        context
+      elsif context.respond_to?(:context)
+        build(context.context)
+      else
+        new(context)
+      end
+    end
+
+    # Retrieves a value from the context by key.
+    #
+    # @param key [String, Symbol] the key to retrieve
+    #
+    # @return [Object, nil] the value associated with the key, or nil if not found
+    #
+    # @example
+    #   context = Context.new(name: "John")
+    #   context[:name] # => "John"
+    #   context["name"] # => "John" (automatically converted to symbol)
+    def [](key)
+      table[key.to_sym]
+    end
+
+    # Stores a key-value pair in the context.
+    #
+    # @param key [String, Symbol] the key to store
+    # @param value [Object] the value to store
+    #
+    # @return [Object] the stored value
+    #
+    # @example
+    #   context = Context.new
+    #   context.store(:name, "John")
+    #   context[:name] # => "John"
+    def store(key, value)
+      table[key.to_sym] = value
+    end
+    alias []= store
+
+    # Fetches a value from the context by key, with optional default value.
+    #
+    # @param key [String, Symbol] the key to fetch
+    # @param default [Object] the default value if key is not found
+    #
+    # @yield [key] a block to compute the default value
+    #
+    # @return [Object] the value associated with the key, or the default/default block result
+    #
+    # @example
+    #   context = Context.new(name: "John")
+    #   context.fetch(:name) # => "John"
+    #   context.fetch(:age, 25) # => 25
+    #   context.fetch(:city) { |key| "Unknown #{key}" } # => "Unknown city"
+    def fetch(key, ...)
+      table.fetch(key.to_sym, ...)
+    end
+
+    # Merges the given arguments into the current context, modifying it in place.
+    #
+    # @param args [Hash, Object] arguments to merge into the context
+    # @option args [Object] :key the key-value pairs to merge
+    #
+    # @return [Context] self for method chaining
+    #
+    # @example
+    #   context = Context.new(name: "John")
+    #   context.merge!(age: 30, city: "NYC")
+    #   context.to_h # => {name: "John", age: 30, city: "NYC"}
+    def merge!(args = {})
+      args.to_h.each { |key, value| self[key.to_sym] = value }
+      self
+    end
 
-      new(context)
+    # Deletes a key-value pair from the context.
+    #
+    # @param key [String, Symbol] the key to delete
+    #
+    # @yield [key] a block to handle the case when key is not found
+    #
+    # @return [Object, nil] the deleted value, or the block result if key not found
+    #
+    # @example
+    #   context = Context.new(name: "John", age: 30)
+    #   context.delete!(:age) # => 30
+    #   context.delete!(:city) { |key| "Key #{key} not found" } # => "Key city not found"
+    def delete!(key, &)
+      table.delete(key.to_sym, &)
+    end
+
+    # Compares this context with another object for equality.
+    #
+    # @param other [Object] the object to compare with
+    #
+    # @return [Boolean] true if other is a Context with the same data
+    #
+    # @example
+    #   context1 = Context.new(name: "John")
+    #   context2 = Context.new(name: "John")
+    #   context1 == context2 # => true
+    def eql?(other)
+      other.is_a?(self.class) && (to_h == other.to_h)
+    end
+    alias == eql?
+
+    # Checks if the context contains a specific key.
+    #
+    # @param key [String, Symbol] the key to check
+    #
+    # @return [Boolean] true if the key exists in the context
+    #
+    # @example
+    #   context = Context.new(name: "John")
+    #   context.key?(:name) # => true
+    #   context.key?(:age) # => false
+    def key?(key)
+      table.key?(key.to_sym)
+    end
+
+    # Digs into nested structures using the given keys.
+    #
+    # @param key [String, Symbol] the first key to dig with
+    # @param keys [Array<String, Symbol>] additional keys for deeper digging
+    #
+    # @return [Object, nil] the value found by digging, or nil if not found
+    #
+    # @example
+    #   context = Context.new(user: {profile: {name: "John"}})
+    #   context.dig(:user, :profile, :name) # => "John"
+    #   context.dig(:user, :profile, :age) # => nil
+    def dig(key, *keys)
+      table.dig(key.to_sym, *keys)
+    end
+
+    # Converts the context to a string representation.
+    #
+    # @return [String] a formatted string representation of the context data
+    #
+    # @example
+    #   context = Context.new(name: "John", age: 30)
+    #   context.to_s # => "name: John, age: 30"
+    def to_s
+      Utils::Format.to_str(to_h)
+    end
+
+    private
+
+    # Handles method calls that don't match defined methods.
+    # Supports assignment-style calls (e.g., `name=`) and key access.
+    #
+    # @param method_name [Symbol] the method name that was called
+    # @param args [Array<Object>] arguments passed to the method
+    # @param _kwargs [Hash] keyword arguments (unused)
+    #
+    # @yield [Object] optional block
+    #
+    # @return [Object] the result of the method call
+    def method_missing(method_name, *args, **_kwargs, &)
+      fetch(method_name) do
+        store(method_name[0..-2], args.first) if method_name.end_with?("=")
+      end
+    end
+
+    # Checks if the object responds to a given method.
+    #
+    # @param method_name [Symbol] the method name to check
+    # @param include_private [Boolean] whether to include private methods
+    #
+    # @return [Boolean] true if the method can be called
+    #
+    # @example
+    #   context = Context.new(name: "John")
+    #   context.respond_to?(:name) # => true
+    #   context.respond_to?(:age) # => false
+    def respond_to_missing?(method_name, include_private = false)
+      key?(method_name) || super
     end
 
   end

data/lib/cmdx/deprecator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Handles deprecation warnings and restrictions for tasks.
+  #
+  # The Deprecator module provides functionality to restrict usage of deprecated
+  # tasks based on configuration settings. It supports different deprecation
+  # behaviors including warnings, logging, and errors.
+  module Deprecator
+
+    extend self
+
+    EVAL = proc do |target, callable|
+      case callable
+      when /raise|log|warn/ then callable
+      when NilClass, FalseClass, TrueClass then !!callable
+      when Symbol then target.send(callable)
+      when Proc then target.instance_eval(&callable)
+      else
+        raise "cannot evaluate #{callable.inspect}" unless callable.respond_to?(:call)
+
+        callable.call(target)
+      end
+    end.freeze
+    private_constant :EVAL
+
+    # Restricts task usage based on deprecation settings.
+    #
+    # @param task [Object] The task object to check for deprecation
+    # @option task.class.settings[:deprecate] [Symbol, Proc, String, Boolean]
+    #   The deprecation configuration for the task
+    # @option task.class.settings[:deprecate] :raise Raises DeprecationError
+    # @option task.class.settings[:deprecate] :log Logs deprecation warning
+    # @option task.class.settings[:deprecate] :warn Outputs warning to stderr
+    # @option task.class.settings[:deprecate] true Raises DeprecationError
+    # @option task.class.settings[:deprecate] false No action taken
+    # @option task.class.settings[:deprecate] nil No action taken
+    #
+    # @raise [DeprecationError] When deprecation type is :raise or true
+    # @raise [RuntimeError] When deprecation type is unknown
+    #
+    # @example
+    #   class MyTask
+    #     settings(deprecate: :warn)
+    #   end
+    #
+    #   MyTask.new # => [MyTask] DEPRECATED: migrate to replacement or discontinue use
+    def restrict(task)
+      type = EVAL.call(task, task.class.settings[:deprecate])
+
+      case type
+      when NilClass, FalseClass # Do nothing
+      when TrueClass, /raise/ then raise DeprecationError, "#{task.class.name} usage prohibited"
+      when /log/ then task.logger.warn { "DEPRECATED: migrate to replacement or discontinue use" }
+      when /warn/ then warn("[#{task.class.name}] DEPRECATED: migrate to replacement or discontinue use", category: :deprecated)
+      else raise "unknown deprecation type #{type.inspect}"
+      end
+    end
+
+  end
+end