cmdx 1.18.0 → 1.20.0

data/lib/cmdx/task.rb

@@ -73,67 +73,60 @@ module CMDx
     def_delegators :result, :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))
+
+      @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 [Hash] The merged settings hash
+      # @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 [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
 
@@ -149,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
@@ -170,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
@@ -229,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.
@@ -241,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
 
@@ -259,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
@@ -290,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)
@@ -311,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)
@@ -364,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
@@ -397,11 +389,11 @@ 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
       }
     end
 

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,13 +108,13 @@ 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 =
         if options.is_a?(Hash)
           case options
-          in allow_nil: then allow_nil && value.nil?
+          in allow_nil: then !(allow_nil && value.nil?)
           else Utils::Condition.evaluate(task, options, value)
           end
         else
@@ -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

data/lib/cmdx/validators/absence.rb

@@ -40,7 +40,7 @@ module CMDx
       #   # => raises ValidationError with custom message
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> nil
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         match =
           if value.is_a?(String)
             /\S/.match?(value)

data/lib/cmdx/validators/exclusion.rb

@@ -34,12 +34,12 @@ module CMDx
       #   Exclusion.call("test", in: ["test", "demo"], message: "value %{values} is forbidden")
       #
       # @rbs (untyped value, Hash[Symbol, untyped] options) -> nil
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         values = options[:in] || options[:within]
 
         if values.is_a?(Range)
           raise_within_validation_error!(values.begin, values.end, options) if values.cover?(value)
-        elsif Array(values).any? { |v| v === value }
+        elsif Utils::Wrap.array(values).any? { |v| v === value }
           raise_of_validation_error!(values, options)
         end
       end

data/lib/cmdx/validators/format.rb

@@ -40,7 +40,7 @@ module CMDx
       #   # => raises ValidationError with custom message
       #
       # @rbs (untyped value, (Hash[Symbol, untyped] | Regexp) options) -> nil
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         match =
           if options.is_a?(Regexp)
             value&.match?(options)

data/lib/cmdx/validators/inclusion.rb

@@ -36,12 +36,12 @@ module CMDx
       #   Inclusion.call("test", in: ["admin", "user"], message: "must be one of: %{values}")
       #
       # @rbs (untyped value, Hash[Symbol, untyped] options) -> nil
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         values = options[:in] || options[:within]
 
         if values.is_a?(Range)
           raise_within_validation_error!(values.begin, values.end, options) unless values.cover?(value)
-        elsif Array(values).none? { |v| v === value }
+        elsif Utils::Wrap.array(values).none? { |v| v === value }
           raise_of_validation_error!(values, options)
         end
       end

data/lib/cmdx/validators/length.rb

@@ -53,7 +53,7 @@ module CMDx
       #   # => nil (validation passes - length 5 is not in excluded range)
       #
       # @rbs (untyped value, Hash[Symbol, untyped] options) -> nil
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         length = value&.length
 
         case options

data/lib/cmdx/validators/numeric.rb

@@ -50,7 +50,7 @@ module CMDx
       #   # => nil (validation passes - 5 is not in 1..10)
       #
       # @rbs (Numeric value, Hash[Symbol, untyped] options) -> nil
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         case options
         in within:
           raise_within_validation_error!(within.begin, within.end, options) unless within&.cover?(value)

data/lib/cmdx/validators/presence.rb

@@ -40,7 +40,7 @@ module CMDx
       #   # => raises ValidationError with custom message
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> nil
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         match =
           if value.is_a?(String)
             /\S/.match?(value)

data/lib/cmdx/version.rb

@@ -5,6 +5,6 @@ module CMDx
   # @return [String] the version of the CMDx gem
   #
   # @rbs return: String
-  VERSION = "1.18.0"
+  VERSION = "1.20.0"
 
 end

data/lib/cmdx.rb

@@ -15,6 +15,18 @@ require "zeitwerk"
 
 module CMDx
 
+  # @rbs EMPTY_ARRAY: Array[untyped]
+  EMPTY_ARRAY = [].freeze
+  private_constant :EMPTY_ARRAY
+
+  # @rbs EMPTY_HASH: Hash[untyped, untyped]
+  EMPTY_HASH = {}.freeze
+  private_constant :EMPTY_HASH
+
+  # @rbs EMPTY_STRING: String
+  EMPTY_STRING = ""
+  private_constant :EMPTY_STRING
+
   extend self
 
   # Returns the path to the CMDx gem.

data/lib/generators/cmdx/templates/install.rb

@@ -32,6 +32,17 @@ CMDx.configure do |config|
     level: Logger::INFO
   )
 
+  # Rollback configuration - controls which statuses trigger task rollback
+  # See https://github.com/drexed/cmdx/blob/main/docs/outcomes/statuses.md for more details
+  #
+  # Available statuses: "success", "skipped", "failed"
+  # If set to an empty array, task will never rollback
+  config.rollback_on = %w[failed]
+
+  # Default locale configuration - used for built-in translation lookups
+  # Must match the basename of a YAML file in lib/locales/ (e.g. "en", "es", "ja")
+  # config.default_locale = "en"
+
   # Backtrace configuration - controls whether to log backtraces on faults and exceptions
   # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#backtraces
   # config.backtrace = false

data/mkdocs.yml

@@ -144,6 +144,8 @@ plugins:
           - returns.md: Declaring expected context outputs that must be set after task execution
           - workflows.md: Composing multiple tasks into sequential pipelines with conditional execution
         More:
+          - testing.md: Best practices for testing CMDx tasks and workflows with RSpec
+          - exceptions.md: Complete exception hierarchy and error type reference
           - tips_and_tricks.md: Best practices, patterns, and techniques for maintainable CMDx applications
           - comparison.md: Comparison with other command/service object frameworks
 nav:
@@ -181,13 +183,15 @@ nav:
       - Returns: returns.md
       - Workflows: workflows.md
     - More:
+      - Testing: testing.md
+      - Exceptions: exceptions.md
       - Tips and Tricks: tips_and_tricks.md
       - Comparison: comparison.md
     - References:
       - API Documentation: https://drexed.github.io/cmdx/api/index.html
       - llms.txt: https://drexed.github.io/cmdx/llms.txt
       - llms-full.txt: https://drexed.github.io/cmdx/llms-full.txt
-      - SKILL.md: https://github.com/drexed/cmdx/blob/main/docs/SKILL.md
+      - AI Skills: https://github.com/drexed/cmdx/blob/main/skills
     - Ecosystem:
       - cmdx-rspec: https://github.com/drexed/cmdx-rspec
   - Blog: blog/index.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.18.0
+  version: 1.20.0
 platform: ruby
 authors:
 - Juan Gomez
@@ -93,20 +93,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: parallel
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -285,13 +271,18 @@ files:
 - lib/cmdx/middlewares/correlate.rb
 - lib/cmdx/middlewares/runtime.rb
 - lib/cmdx/middlewares/timeout.rb
+- lib/cmdx/parallelizer.rb
 - lib/cmdx/pipeline.rb
 - lib/cmdx/railtie.rb
 - lib/cmdx/result.rb
+- lib/cmdx/retry.rb
+- lib/cmdx/settings.rb
 - lib/cmdx/task.rb
 - lib/cmdx/utils/call.rb
 - lib/cmdx/utils/condition.rb
 - lib/cmdx/utils/format.rb
+- lib/cmdx/utils/normalize.rb
+- lib/cmdx/utils/wrap.rb
 - lib/cmdx/validator_registry.rb
 - lib/cmdx/validators/absence.rb
 - lib/cmdx/validators/exclusion.rb