cmdx 1.19.0 → 1.21.0

data/lib/cmdx/settings.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Value object encapsulating all per-task configuration. Registries are
+  # deep-duped on inheritance; scalar settings delegate to a parent Settings
+  # or to the global Configuration rather than eagerly copying values.
+  class Settings
+
+    class << self
+
+      private
+
+      # Defines a reader that delegates to the parent Settings chain,
+      # falling through to Configuration when no parent exists.
+      #
+      # @param names [Array<Symbol>] Setting names to define
+      #
+      # @rbs (*Symbol names) -> void
+      def delegate_to_configuration(*names)
+        names.each do |name|
+          ivar = :"@#{name}"
+
+          attr_writer(name)
+
+          define_method(name) do
+            return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+            value = @parent ? @parent.public_send(name) : CMDx.configuration.public_send(name)
+            instance_variable_set(ivar, value)
+
+            value
+          end
+        end
+      end
+
+      # Defines a reader that delegates to the parent Settings only.
+      # Returns nil when the chain is exhausted.
+      #
+      # @param names [Array<Symbol>] Setting names to define
+      # @param with_fallback [Boolean] Whether to fall back to Configuration
+      #
+      # @rbs (*Symbol names, with_fallback: bool) -> void
+      def delegate_to_parent(*names, with_fallback: false)
+        names.each do |name|
+          ivar = :"@#{name}"
+
+          attr_writer(name)
+
+          define_method(name) do
+            return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+            value = @parent&.public_send(name)
+            value ||= CMDx.configuration.public_send(name) if with_fallback
+            instance_variable_set(ivar, value)
+
+            value
+          end
+        end
+      end
+
+    end
+
+    # Returns the attribute registry for task parameters.
+    #
+    # @return [AttributeRegistry] The attribute registry
+    #
+    # @rbs @attributes: AttributeRegistry
+    attr_accessor :attributes
+
+    # Returns the callback registry for task lifecycle hooks.
+    #
+    # @return [CallbackRegistry] The callback registry
+    #
+    # @rbs @callbacks: CallbackRegistry
+    attr_accessor :callbacks
+
+    # Returns the coercion registry for type conversions.
+    #
+    # @return [CoercionRegistry] The coercion registry
+    #
+    # @rbs @coercions: CoercionRegistry
+    attr_accessor :coercions
+
+    # Returns the middleware registry for task execution.
+    #
+    # @return [MiddlewareRegistry] The middleware registry
+    #
+    # @rbs @middlewares: MiddlewareRegistry
+    attr_accessor :middlewares
+
+    # Returns the validator registry for attribute validation.
+    #
+    # @return [ValidatorRegistry] The validator registry
+    #
+    # @rbs @validators: ValidatorRegistry
+    attr_accessor :validators
+
+    # Returns the expected return keys after execution.
+    #
+    # @return [Array<Symbol>] Expected return keys after execution
+    #
+    # @rbs @returns: Array[Symbol]
+    attr_accessor :returns
+
+    # Returns the tags for task categorization.
+    #
+    # @return [Array<Symbol>] Tags for categorization
+    #
+    # @rbs @tags: Array[Symbol]
+    attr_accessor :tags
+
+    # @!attribute [rw] backtrace
+    #   @return [Boolean] true if backtraces should be logged
+    delegate_to_configuration :backtrace
+
+    # @!attribute [rw] dump_context
+    #   @return [Boolean] true if context should be included in Task#to_h
+    delegate_to_configuration :dump_context
+
+    # @!attribute [rw] rollback_on
+    #   @return [Array<String>] Statuses that trigger rollback
+    delegate_to_configuration :rollback_on
+
+    # @!attribute [rw] task_breakpoints
+    #   @return [Array<String>] Default task breakpoint statuses
+    delegate_to_configuration :task_breakpoints
+
+    # @!attribute [rw] workflow_breakpoints
+    #   @return [Array<String>] Default workflow breakpoint statuses
+    delegate_to_configuration :workflow_breakpoints
+
+    # @!attribute [rw] backtrace_cleaner
+    #   @return [Proc, nil] The backtrace cleaner proc
+    delegate_to_parent :backtrace_cleaner, with_fallback: true
+
+    # @!attribute [rw] breakpoints
+    #   @return [Array<String>, nil] Per-task breakpoints override
+    delegate_to_parent :breakpoints
+
+    # @!attribute [rw] deprecate
+    #   @return [Symbol, Proc, Boolean, nil] Deprecation behavior
+    delegate_to_parent :deprecate
+
+    # @!attribute [rw] exception_handler
+    #   @return [Proc, nil] The exception handler proc
+    delegate_to_parent :exception_handler, with_fallback: true
+
+    # @!attribute [rw] logger
+    #   @return [Logger] The logger instance
+    delegate_to_parent :logger, with_fallback: true
+
+    # @!attribute [rw] log_formatter
+    #   @return [Proc, nil] Per-task log formatter override
+    delegate_to_parent :log_formatter
+
+    # @!attribute [rw] log_level
+    #   @return [Integer, nil] Per-task log level override
+    delegate_to_parent :log_level
+
+    # @!attribute [rw] retries
+    #   @return [Integer, nil] Number of retries on failure
+    delegate_to_parent :retries
+
+    # @!attribute [rw] retry_jitter
+    #   @return [Numeric, Symbol, Proc, nil] Jitter between retries
+    delegate_to_parent :retry_jitter
+
+    # @!attribute [rw] retry_on
+    #   @return [Array<Class>, Class, nil] Exception classes to retry on
+    delegate_to_parent :retry_on
+
+    # Creates a new Settings instance, inheriting registries from a parent
+    # Settings or the global Configuration. Scalar settings are resolved
+    # lazily via delegation rather than eagerly copied.
+    #
+    # @param parent [Settings, nil] Parent settings to inherit from
+    # @param overrides [Hash] Field values to override after inheritance
+    #
+    # @example
+    #   Settings.new(parent: ParentTask.settings, deprecate: true)
+    #
+    # @rbs (?parent: Settings?, **untyped overrides) -> void
+    def initialize(parent: nil, **overrides)
+      @parent = parent
+
+      init_registries
+      init_collections
+
+      overrides.each { |key, value| public_send(:"#{key}=", value) }
+    end
+
+    private
+
+    # Dups registries from the parent Settings or global Configuration
+    # so each task class gets its own mutable copy.
+    #
+    # @rbs () -> void
+    def init_registries
+      if @parent
+        @middlewares = @parent.middlewares.dup
+        @callbacks = @parent.callbacks.dup
+        @coercions = @parent.coercions.dup
+        @validators = @parent.validators.dup
+        @attributes = @parent.attributes.dup
+      else
+        config = CMDx.configuration
+
+        @middlewares = config.middlewares.dup
+        @callbacks = config.callbacks.dup
+        @coercions = config.coercions.dup
+        @validators = config.validators.dup
+        @attributes = AttributeRegistry.new
+      end
+    end
+
+    # Initializes array-valued settings that need their own copy
+    # to avoid cross-class mutation.
+    #
+    # @rbs () -> void
+    def init_collections
+      @returns = @parent&.returns&.dup || EMPTY_ARRAY
+      @tags = @parent&.tags&.dup || EMPTY_ARRAY
+    end
+
+  end
+end

data/lib/cmdx/task.rb

@@ -70,72 +70,63 @@ module CMDx
     # @rbs @chain: Chain
     attr_reader :chain
 
-    def_delegators :result, :skip!, :fail!, :throw!
+    def_delegators :result, :success!, :skip!, :fail!, :throw!
     def_delegators :chain, :dry_run?
 
-    # @param context [Hash, Context] The initial context for the task
-    #
-    # @option context [Object] :* Any key-value pairs to initialize the context
+    # @param context [Hash, Context, nil] The initial context for the task
     #
     # @return [Task] A new task instance
     #
     # @raise [DeprecationError] If the task class is deprecated
     #
     # @example
+    #   task = MyTask.new
     #   task = MyTask.new(name: "example", priority: :high)
     #   task = MyTask.new(Context.build(name: "example"))
     #
     # @rbs (untyped context) -> void
-    def initialize(context = {})
+    def initialize(context = nil)
       Deprecator.restrict(self)
 
-      @attributes = {}
-      @errors = Errors.new
-
       @id = Identifier.generate
       @context = Context.build(context)
+      @errors = Errors.new
       @result = Result.new(self)
+      @chain = Chain.build(@result, dry_run: @context.delete(:dry_run))
 
-      dry_run = @context.delete(:dry_run)
-      @chain = Chain.build(@result, dry_run:)
+      @attributes = {}
     end
 
     class << self
 
-      # @param options [Hash] Configuration options to merge with existing settings
-      # @option options [Object] :* Any configuration option key-value pairs
+      # Returns the cached task type string for this class.
+      #
+      # @return [String] "Workflow" or "Task"
+      #
+      # @rbs () -> String
+      def type
+        @type ||= include?(Workflow) ? "Workflow" : "Task"
+      end
+
+      # Returns (and lazily creates) the task-level Settings object.
+      # On first access, inherits from the superclass settings or
+      # the global Configuration. Optional overrides are applied once.
+      #
+      # @param overrides [Hash] Configuration overrides applied on first access
+      # @option overrides [Object] :* Any configuration override key-value pairs
       #
-      # @return [Hash] The merged settings hash
+      # @return [Settings] The settings instance for this task class
       #
       # @example
       #   class MyTask < Task
       #     settings deprecate: true, tags: [:experimental]
       #   end
       #
-      # @rbs (**untyped options) -> Hash[Symbol, untyped]
-      def settings(**options)
+      # @rbs (**untyped overrides) -> Settings
+      def settings(**overrides)
         @settings ||= begin
-          hash =
-            if superclass.respond_to?(:settings)
-              parent = superclass.settings
-              parent
-                .except(:backtrace_cleaner, :exception_handler, :logger, :deprecate)
-                .transform_values!(&:dup)
-                .merge!(
-                  backtrace_cleaner: parent[:backtrace_cleaner] || CMDx.configuration.backtrace_cleaner,
-                  exception_handler: parent[:exception_handler] || CMDx.configuration.exception_handler,
-                  logger: parent[:logger] || CMDx.configuration.logger,
-                  deprecate: parent[:deprecate]
-                )
-            else
-              CMDx.configuration.to_h
-            end
-
-          hash[:attributes] ||= AttributeRegistry.new
-          hash[:returns] ||= []
-          hash[:tags] ||= []
-
-          hash.merge!(options)
+          parent = superclass.settings if superclass.respond_to?(:settings)
+          Settings.new(parent:, **overrides)
         end
       end
 
@@ -151,11 +142,13 @@ module CMDx
       # @rbs (Symbol type, untyped object, *untyped) -> void
       def register(type, object, ...)
         case type
-        when :attribute then settings[:attributes].register(object, ...)
-        when :callback then settings[:callbacks].register(object, ...)
-        when :coercion then settings[:coercions].register(object, ...)
-        when :middleware then settings[:middlewares].register(object, ...)
-        when :validator then settings[:validators].register(object, ...)
+        when :attribute
+          settings.attributes.register(object)
+          settings.attributes.define_readers_on!(self, Utils::Wrap.array(object))
+        when :callback then settings.callbacks.register(object, ...)
+        when :middleware then settings.middlewares.register(object, ...)
+        when :validator then settings.validators.register(object, ...)
+        when :coercion then settings.coercions.register(object, ...)
         else raise "unknown registry type #{type.inspect}"
         end
       end
@@ -172,11 +165,13 @@ module CMDx
       # @rbs (Symbol type, untyped object, *untyped) -> void
       def deregister(type, object, ...)
         case type
-        when :attribute then settings[:attributes].deregister(object, ...)
-        when :callback then settings[:callbacks].deregister(object, ...)
-        when :coercion then settings[:coercions].deregister(object, ...)
-        when :middleware then settings[:middlewares].deregister(object, ...)
-        when :validator then settings[:validators].deregister(object, ...)
+        when :attribute
+          settings.attributes.undefine_readers_on!(self, object)
+          settings.attributes.deregister(object)
+        when :callback then settings.callbacks.deregister(object, ...)
+        when :middleware then settings.middlewares.deregister(object, ...)
+        when :validator then settings.validators.deregister(object, ...)
+        when :coercion then settings.coercions.deregister(object, ...)
         else raise "unknown registry type #{type.inspect}"
         end
       end
@@ -231,7 +226,7 @@ module CMDx
       #
       # @rbs (*untyped names) -> void
       def returns(*names)
-        settings[:returns] |= names.map(&:to_sym)
+        settings.returns |= names.map(&:to_sym)
       end
 
       # Removes declared returns from the task.
@@ -243,7 +238,7 @@ module CMDx
       #
       # @rbs (*Symbol names) -> void
       def remove_returns(*names)
-        settings[:returns] -= names.map(&:to_sym)
+        settings.returns -= names.map(&:to_sym)
       end
       alias remove_return remove_returns
 
@@ -261,7 +256,7 @@ module CMDx
       #
       # @rbs () -> Hash[Symbol, Hash[Symbol, untyped]]
       def attributes_schema
-        Array(settings[:attributes]).to_h do |attr|
+        Utils::Wrap.array(settings.attributes).to_h do |attr|
           [attr.method_name, attr.to_h]
         end
       end
@@ -292,11 +287,8 @@ module CMDx
       #
       # @example
       #   result = MyTask.execute(name: "example")
-      #   if result.success?
-      #     puts "Task completed successfully"
-      #   end
       #
-      # @rbs (*untyped args, **untyped kwargs) ?{ (Result) -> void } -> Result
+      # @rbs (*untyped args, dry_run: bool, **untyped kwargs) ?{ (Result) -> void } -> Result
       def execute(*args, **kwargs)
         task = new(*args, **kwargs)
         task.execute(raise: false)
@@ -313,9 +305,8 @@ module CMDx
       #
       # @example
       #   result = MyTask.execute!(name: "example")
-      #   # Will raise an exception if execution fails
       #
-      # @rbs (*untyped args, **untyped kwargs) ?{ (Result) -> void } -> Result
+      # @rbs (*untyped args, dry_run: bool, **untyped kwargs) ?{ (Result) -> void } -> Result
       def execute!(*args, **kwargs)
         task = new(*args, **kwargs)
         task.execute(raise: true)
@@ -366,14 +357,13 @@ module CMDx
     # @rbs () -> Logger
     def logger
       @logger ||= begin
-        log_instance = self.class.settings[:logger] || CMDx.configuration.logger
-        log_level = self.class.settings[:log_level]
-        log_formatter = self.class.settings[:log_formatter]
+        settings = self.class.settings
+        log_instance = settings.logger || CMDx.configuration.logger
 
-        if log_level || log_formatter
+        if settings.log_level || settings.log_formatter
           log_instance = log_instance.dup
-          log_instance.level = log_level if log_level
-          log_instance.formatter = log_formatter if log_formatter
+          log_instance.level = settings.log_level if settings.log_level
+          log_instance.formatter = settings.log_formatter if settings.log_formatter
         end
 
         log_instance
@@ -386,6 +376,7 @@ module CMDx
     # @option return [Array<Symbol>] :tags The task tags
     # @option return [String] :class The task class name
     # @option return [String] :id The task identifier
+    # @option return [Hash] :context The task context (when dump_context is true)
     #
     # @return [Hash] A hash representation of the task
     #
@@ -399,12 +390,18 @@ module CMDx
       {
         index: result.index,
         chain_id: chain.id,
-        type: self.class.include?(Workflow) ? "Workflow" : "Task",
-        tags: self.class.settings[:tags],
+        type: self.class.type,
         class: self.class.name,
+        id:,
         dry_run: dry_run?,
-        id:
-      }
+        tags: self.class.settings.tags
+      }.tap do |hash|
+        if self.class.settings.dump_context
+          # Large context can make dumps and logs very noisy,
+          # so only include it if explicitly enabled
+          hash[:context] = context.to_h
+        end
+      end
     end
 
     # @return [String] A string representation of the task

data/lib/cmdx/utils/format.rb

@@ -32,7 +32,7 @@ module CMDx
       #
       # @rbs (untyped message) -> untyped
       def to_log(message)
-        if message.respond_to?(:to_h) && message.class.ancestors.any? { |a| a.name&.start_with?("CMDx::") }
+        if message.respond_to?(:to_h) && cmdx_based_object?(message.class)
           message.to_h
         else
           message
@@ -61,6 +61,22 @@ module CMDx
         hash.map(&block).join(" ")
       end
 
+      private
+
+      # Checks if a class belongs to the CMDx namespace, caching per class.
+      #
+      # @param klass [Class] The class to check
+      #
+      # @return [Boolean] true if the class is in the CMDx namespace
+      #
+      # @rbs (Class klass) -> bool
+      def cmdx_based_object?(klass)
+        @cmdx_classes ||= {}
+        return @cmdx_classes[klass] if @cmdx_classes.key?(klass)
+
+        @cmdx_classes[klass] = klass.ancestors.any? { |a| a.name&.start_with?("CMDx::") }
+      end
+
     end
   end
 end

data/lib/cmdx/utils/normalize.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Utils
+    # Provides normalization utilities for a variety of objects
+    # into consistent formats.
+    module Normalize
+
+      extend self
+
+      # Normalizes an exception into a string representation.
+      #
+      # @param exception [Exception] The exception to normalize
+      #
+      # @return [String] The normalized exception string
+      #
+      # @example From exception
+      #   Normalize.exception(StandardError.new("test"))
+      #   # => "[StandardError] test"
+      #
+      # @rbs (Exception exception) -> String
+      def exception(exception)
+        "[#{exception.class}] #{exception.message}"
+      end
+
+      # Normalizes an object into an array of unique status strings.
+      #
+      # @param object [Object] The object to normalize into status strings
+      #
+      # @return [Array<String>] Unique status strings
+      #
+      # @example From array of symbols
+      #   Normalize.statuses([:success, :pending, :success])
+      #   # => ["success", "pending"]
+      # @example From single value
+      #   Normalize.statuses(:success)
+      #   # => ["success"]
+      # @example From nil
+      #   Normalize.statuses(nil)
+      #   # => []
+      #
+      # @rbs (untyped object) -> Array[String]
+      def statuses(object)
+        ary = Wrap.array(object)
+        return EMPTY_ARRAY if ary.empty?
+
+        ary.map(&:to_s).uniq
+      end
+
+    end
+  end
+end

data/lib/cmdx/utils/wrap.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Utils
+    # Provides array wrapping utilities for normalizing input values
+    # into consistent array structures.
+    module Wrap
+
+      extend self
+
+      # Wraps an object in an array if it is not already an array.
+      #
+      # @param object [Object] The object to wrap in an array
+      #
+      # @return [Array] The wrapped array
+      #
+      # @example Already an array
+      #   Wrap.array([1, 2, 3])
+      #   # => [1, 2, 3]
+      # @example Single value
+      #   Wrap.array(1)
+      #   # => [1]
+      # @example Nil value
+      #   Wrap.array(nil)
+      #   # => []
+      #
+      # @rbs (untyped object) -> Array[untyped]
+      def array(object)
+        case object
+        when Array then object
+        when NilClass then EMPTY_ARRAY
+        else Array(object)
+        end
+      end
+
+    end
+  end
+end

data/lib/cmdx/validator_registry.rb

@@ -3,21 +3,13 @@
 module CMDx
   # Registry for managing validation rules and their corresponding validator classes.
   # Provides methods to register, deregister, and execute validators against task values.
+  #
+  # Supports copy-on-write semantics: a duped registry shares the parent's
+  # data until a write operation triggers materialization.
   class ValidatorRegistry
 
     extend Forwardable
 
-    # Returns the internal registry mapping validator types to classes.
-    #
-    # @return [Hash{Symbol => Class}] Hash of validator type names to validator classes
-    #
-    # @example
-    #   registry.registry # => { presence: Validators::Presence, format: Validators::Format }
-    #
-    # @rbs @registry: Hash[Symbol, Class]
-    attr_reader :registry
-    alias to_h registry
-
     def_delegators :registry, :keys
 
     # Initialize a new validator registry with default validators.
@@ -39,14 +31,30 @@ module CMDx
       }
     end
 
-    # Create a duplicate of the registry with copied internal state.
+    # Sets up copy-on-write state when duplicated via dup.
+    #
+    # @param source [ValidatorRegistry] The registry being duplicated
+    #
+    # @rbs (ValidatorRegistry source) -> void
+    def initialize_dup(source)
+      @parent = source
+      @registry = nil
+      super
+    end
+
+    # Returns the internal registry mapping validator types to classes.
+    # Delegates to the parent registry when not yet materialized.
     #
-    # @return [ValidatorRegistry] A new validator registry with duplicated registry hash
+    # @return [Hash{Symbol => Class}] Hash of validator type names to validator classes
     #
-    # @rbs () -> ValidatorRegistry
-    def dup
-      self.class.new(registry.dup)
+    # @example
+    #   registry.registry # => { presence: Validators::Presence, format: Validators::Format }
+    #
+    # @rbs () -> Hash[Symbol, Class]
+    def registry
+      @registry || @parent.registry
     end
+    alias to_h registry
 
     # Register a new validator class with the given name.
     #
@@ -61,7 +69,9 @@ module CMDx
     #
     # @rbs ((String | Symbol) name, Class validator) -> self
     def register(name, validator)
-      registry[name.to_sym] = validator
+      materialize!
+
+      @registry[name.to_sym] = validator
       self
     end
 
@@ -77,7 +87,9 @@ module CMDx
     #
     # @rbs ((String | Symbol) name) -> self
     def deregister(name)
-      registry.delete(name.to_sym)
+      materialize!
+
+      @registry.delete(name.to_sym)
       self
     end
 
@@ -96,7 +108,7 @@ module CMDx
     #   registry.validate(:length, task, password, { min: 8, allow_nil: false })
     #
     # @rbs (Symbol type, Task task, untyped value, untyped options) -> untyped
-    def validate(type, task, value, options = {})
+    def validate(type, task, value, options = EMPTY_HASH)
       raise TypeError, "unknown validator type #{type.inspect}" unless registry.key?(type)
 
       match =
@@ -114,5 +126,18 @@ module CMDx
       Utils::Call.invoke(task, registry[type], value, options)
     end
 
+    private
+
+    # Copies the parent's registry data into this instance,
+    # severing the copy-on-write link.
+    #
+    # @rbs () -> void
+    def materialize!
+      return if @registry
+
+      @registry = @parent.registry.dup
+      @parent = nil
+    end
+
   end
 end