cmdx 1.0.1 → 1.1.1

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.1
 platform: ruby
 authors:
 - Juan Gomez
@@ -186,6 +186,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".DS_Store"
+- ".cursor/prompts/docs.md"
+- ".cursor/prompts/rspec.md"
+- ".cursor/prompts/yardoc.md"
 - ".cursor/rules/cursor-instructions.mdc"
 - ".rspec"
 - ".rubocop.yml"
@@ -202,6 +205,7 @@ files:
 - docs/basics/setup.md
 - docs/callbacks.md
 - docs/configuration.md
+- docs/deprecation.md
 - docs/getting_started.md
 - docs/internationalization.md
 - docs/interruptions/exceptions.md
@@ -227,6 +231,8 @@ files:
 - lib/cmdx/chain.rb
 - lib/cmdx/chain_inspector.rb
 - lib/cmdx/chain_serializer.rb
+- lib/cmdx/coercion.rb
+- lib/cmdx/coercion_registry.rb
 - lib/cmdx/coercions/array.rb
 - lib/cmdx/coercions/big_decimal.rb
 - lib/cmdx/coercions/boolean.rb
@@ -268,28 +274,50 @@ files:
 - lib/cmdx/middlewares/correlate.rb
 - lib/cmdx/middlewares/timeout.rb
 - lib/cmdx/parameter.rb
+- lib/cmdx/parameter_evaluator.rb
 - lib/cmdx/parameter_inspector.rb
 - lib/cmdx/parameter_registry.rb
 - lib/cmdx/parameter_serializer.rb
-- lib/cmdx/parameter_validator.rb
-- lib/cmdx/parameter_value.rb
-- lib/cmdx/parameters_inspector.rb
-- lib/cmdx/parameters_serializer.rb
 - lib/cmdx/railtie.rb
 - lib/cmdx/result.rb
 - lib/cmdx/result_ansi.rb
 - lib/cmdx/result_inspector.rb
 - lib/cmdx/result_logger.rb
 - lib/cmdx/result_serializer.rb
-- lib/cmdx/rspec/result_matchers.rb
-- lib/cmdx/rspec/task_matchers.rb
+- lib/cmdx/rspec/matchers.rb
+- lib/cmdx/rspec/result_matchers/be_executed.rb
+- lib/cmdx/rspec/result_matchers/be_failed_task.rb
+- lib/cmdx/rspec/result_matchers/be_skipped_task.rb
+- lib/cmdx/rspec/result_matchers/be_state_matchers.rb
+- lib/cmdx/rspec/result_matchers/be_status_matchers.rb
+- lib/cmdx/rspec/result_matchers/be_successful_task.rb
+- lib/cmdx/rspec/result_matchers/have_bad_outcome.rb
+- lib/cmdx/rspec/result_matchers/have_caused_failure.rb
+- lib/cmdx/rspec/result_matchers/have_chain_index.rb
+- lib/cmdx/rspec/result_matchers/have_context.rb
+- lib/cmdx/rspec/result_matchers/have_empty_metadata.rb
+- lib/cmdx/rspec/result_matchers/have_good_outcome.rb
+- lib/cmdx/rspec/result_matchers/have_metadata.rb
+- lib/cmdx/rspec/result_matchers/have_preserved_context.rb
+- lib/cmdx/rspec/result_matchers/have_received_thrown_failure.rb
+- lib/cmdx/rspec/result_matchers/have_runtime.rb
+- lib/cmdx/rspec/result_matchers/have_thrown_failure.rb
+- lib/cmdx/rspec/task_matchers/be_well_formed_task.rb
+- lib/cmdx/rspec/task_matchers/have_callback.rb
+- lib/cmdx/rspec/task_matchers/have_cmd_setting.rb
+- lib/cmdx/rspec/task_matchers/have_executed_callbacks.rb
+- lib/cmdx/rspec/task_matchers/have_middleware.rb
+- lib/cmdx/rspec/task_matchers/have_parameter.rb
 - lib/cmdx/task.rb
+- lib/cmdx/task_deprecator.rb
+- lib/cmdx/task_processor.rb
 - lib/cmdx/task_serializer.rb
 - lib/cmdx/utils/ansi_color.rb
 - lib/cmdx/utils/log_timestamp.rb
 - lib/cmdx/utils/monotonic_runtime.rb
 - lib/cmdx/utils/name_affix.rb
-- lib/cmdx/validators/custom.rb
+- lib/cmdx/validator.rb
+- lib/cmdx/validator_registry.rb
 - lib/cmdx/validators/exclusion.rb
 - lib/cmdx/validators/format.rb
 - lib/cmdx/validators/inclusion.rb

data/lib/cmdx/parameter_validator.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Parameter validation orchestration module for CMDx tasks.
-  #
-  # The ParameterValidator module provides high-level parameter validation
-  # coordination for task instances. It triggers validation of all task
-  # parameters and handles validation failure by setting task failure state
-  # with appropriate error messages.
-  #
-  # @example Basic parameter validation
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :order_id, type: :integer
-  #     required :email, type: :string, format: { with: /@/ }
-  #   end
-  #
-  #   task = ProcessOrderTask.new
-  #   ParameterValidator.call(task)  # Validates all parameters
-  #   # If validation fails, task.failed? => true
-  #
-  # @example Validation with error handling
-  #   task = ProcessOrderTask.new
-  #   ParameterValidator.call(task)
-  #
-  #   if task.failed?
-  #     puts task.result.metadata[:reason] # => "order_id is a required parameter. email is invalid"
-  #     puts task.errors.messages          # => { order_id: ["is a required parameter"], email: ["is invalid"] }
-  #   end
-  #
-  # @example Successful validation
-  #   task = ProcessOrderTask.call(order_id: 123, email: "user@example.com")
-  #   # ParameterValidator runs automatically and validation passes
-  #   task.success?  # => true
-  #
-  # @see CMDx::Parameters Parameter collection validation
-  # @see CMDx::Parameter Individual parameter definitions
-  # @see CMDx::Task Task execution and parameter integration
-  module ParameterValidator
-
-    module_function
-
-    # Validates all parameters for a task instance.
-    #
-    # Triggers validation of all task parameters through the Parameters collection.
-    # If any validation errors occur, sets the task to failed state with a
-    # comprehensive error message and detailed error information.
-    #
-    # @param task [CMDx::Task] The task instance to validate parameters for
-    # @return [void]
-    #
-    # @example Validating task parameters
-    #   task = MyTask.new
-    #   ParameterValidator.call(task)
-    #
-    #   # If validation fails:
-    #   task.failed?                  # => true
-    #   task.result.metadata[:reason] # => "Combined error messages from all failed parameters"
-    #   task.errors.empty?            # => false
-    #
-    # @example Validation success
-    #   task = MyTask.new  # with valid parameters
-    #   ParameterValidator.call(task)
-    #
-    #   task.errors.empty?  # => true
-    #   # Task continues normal execution
-    #
-    # @note This method is typically called automatically during task execution
-    #   before the main task logic runs, ensuring parameter validation occurs
-    #   early in the task lifecycle.
-    def call(task)
-      task.class.cmd_parameters.validate!(task)
-      return if task.errors.empty?
-
-      task.fail!(
-        reason: task.errors.full_messages.join(". "),
-        messages: task.errors.messages
-      )
-    end
-
-  end
-end

data/lib/cmdx/parameter_value.rb

@@ -1,244 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Parameter value resolution and processing class for CMDx tasks.
-  #
-  # The ParameterValue class handles the complete lifecycle of parameter value
-  # processing including source resolution, type coercion, validation, and error
-  # handling. It serves as the bridge between parameter definitions and their
-  # actual values during task execution.
-  #
-  # @example Basic parameter value processing
-  #   task = ProcessOrderTask.new
-  #   parameter = Parameter.new(:order_id, klass: ProcessOrderTask, type: :integer)
-  #   value_processor = ParameterValue.new(task, parameter)
-  #   processed_value = value_processor.call  # Resolves, coerces, and validates
-  #
-  # @example Parameter value with validation
-  #   parameter = Parameter.new(:email, klass: Task, type: :string,
-  #                           format: { with: /@/ }, presence: true)
-  #   value_processor = ParameterValue.new(task, parameter)
-  #   value_processor.call  # Validates email format and presence
-  #
-  # @example Parameter value with default
-  #   parameter = Parameter.new(:priority, klass: Task, default: "normal")
-  #   value_processor = ParameterValue.new(task, parameter)
-  #   value_processor.call  # Returns "normal" if not provided
-  #
-  # @see CMDx::Parameter Parameter definition and configuration
-  # @see CMDx::Coercions Type coercion modules
-  # @see CMDx::Validators Parameter validation modules
-  class ParameterValue
-
-    __cmdx_attr_delegator :parent, :method_source, :name, :options, :required?, :optional?, :type,
-                          to: :parameter,
-                          private: true
-
-    # @return [CMDx::Task] The task instance being processed
-    # @return [CMDx::Parameter] The parameter definition being processed
-    attr_reader :task, :parameter
-
-    # Initializes a new ParameterValue processor.
-    #
-    # Creates a parameter value processor for resolving, coercing, and validating
-    # a specific parameter value within the context of a task instance.
-    #
-    # @param task [CMDx::Task] The task instance containing the parameter source
-    # @param parameter [CMDx::Parameter] The parameter definition to process
-    #
-    # @example Creating a parameter value processor
-    #   processor = ParameterValue.new(task_instance, parameter_definition)
-    def initialize(task, parameter)
-      @task      = task
-      @parameter = parameter
-    end
-
-    # Processes the parameter value through coercion and validation.
-    #
-    # Executes the complete parameter value processing pipeline:
-    # 1. Resolves the raw value from the source
-    # 2. Applies type coercion based on parameter type
-    # 3. Runs all configured validations
-    # 4. Returns the final processed value
-    #
-    # @return [Object] The processed and validated parameter value
-    # @raise [CoercionError] If type coercion fails
-    # @raise [ValidationError] If validation fails
-    #
-    # @example Processing a simple parameter
-    #   processor.call  # => 42 (after coercion and validation)
-    #
-    # @example Processing with validation failure
-    #   processor.call  # => raises ValidationError: "is not valid"
-    def call
-      coerce!.tap { validate! }
-    end
-
-    private
-
-    # Checks if the parameter source method is defined on the task.
-    #
-    # @return [Boolean] true if source method exists, false otherwise
-    def source_defined?
-      task.respond_to?(method_source, true) || task.__cmdx_try(method_source)
-    end
-
-    # Resolves the source object that contains the parameter value.
-    #
-    # Gets the source object by calling the method_source on the task instance.
-    # Raises ValidationError if the source method is not defined.
-    #
-    # @return [Object] The source object containing parameter values
-    # @raise [ValidationError] If source method is undefined
-    def source
-      return @source if defined?(@source)
-
-      unless source_defined?
-        raise ValidationError, I18n.t(
-          "cmdx.parameters.undefined",
-          default: "delegates to undefined method #{method_source}",
-          source: method_source
-        )
-      end
-
-      @source = task.__cmdx_try(method_source)
-    end
-
-    # Checks if the source object has the parameter value.
-    #
-    # @return [Boolean] true if source responds to parameter name, false otherwise
-    def source_value?
-      return false if source.nil?
-
-      source.__cmdx_respond_to?(name, true)
-    end
-
-    # Checks if a required parameter value is missing from the source.
-    #
-    # @return [Boolean] true if required parameter is missing, false otherwise
-    def source_value_required?
-      return false if parent&.optional? && source.nil?
-
-      required? && !source_value?
-    end
-
-    # Resolves the raw parameter value from the source.
-    #
-    # Gets the parameter value from the source object, handling required
-    # parameter validation and default value resolution.
-    #
-    # @return [Object] The raw parameter value
-    # @raise [ValidationError] If required parameter is missing
-    def value
-      return @value if defined?(@value)
-
-      if source_value_required?
-        raise ValidationError, I18n.t(
-          "cmdx.parameters.required",
-          default: "is a required parameter"
-        )
-      end
-
-      @value = source.__cmdx_try(name)
-      return @value unless @value.nil? && options.key?(:default)
-
-      @value = task.__cmdx_yield(options[:default])
-    end
-
-    # Applies type coercion to the parameter value.
-    #
-    # Attempts to coerce the value to each specified type in order,
-    # supporting multiple type fallbacks for flexible coercion.
-    #
-    # @return [Object] The coerced parameter value
-    # @raise [CoercionError] If all coercion attempts fail
-    # @raise [UnknownCoercionError] If an unknown type is specified
-    def coerce!
-      types = Array(type)
-      tsize = types.size - 1
-
-      types.each_with_index do |t, i|
-        break case t.to_sym
-              when :array then Coercions::Array
-              when :big_decimal then Coercions::BigDecimal
-              when :boolean then Coercions::Boolean
-              when :complex then Coercions::Complex
-              when :date then Coercions::Date
-              when :datetime then Coercions::DateTime
-              when :float then Coercions::Float
-              when :hash then Coercions::Hash
-              when :integer then Coercions::Integer
-              when :rational then Coercions::Rational
-              when :string then Coercions::String
-              when :time then Coercion::Time
-              when :virtual then Coercions::Virtual
-              else raise UnknownCoercionError, "unknown coercion #{t}"
-              end.call(value, options)
-      rescue CoercionError => e
-        next if tsize != i
-
-        raise(e) if tsize.zero?
-
-        values = types.map(&:to_s).join(", ")
-        raise CoercionError, I18n.t(
-          "cmdx.coercions.into_any",
-          values:,
-          default: "could not coerce into one of: #{values}"
-        )
-      end
-    end
-
-    # Checks if validations should be skipped for optional missing arguments.
-    #
-    # @return [Boolean] true if validations should be skipped, false otherwise
-    def skip_validations_due_to_optional_missing_argument?
-      optional? && value.nil? && !source.nil? && !source.__cmdx_respond_to?(name, true)
-    end
-
-    # Checks if a specific validator should be skipped due to conditional logic.
-    #
-    # @param key [Symbol] The validator key to check
-    # @return [Boolean] true if validator should be skipped, false otherwise
-    def skip_validator_due_to_conditional?(key)
-      opts = options[key]
-      opts.is_a?(Hash) && !task.__cmdx_eval(opts)
-    end
-
-    # Checks if a specific validator should be skipped due to allow_nil option.
-    #
-    # @param key [Symbol] The validator key to check
-    # @return [Boolean] true if validator should be skipped, false otherwise
-    def skip_validator_due_to_allow_nil?(key)
-      opts = options[key]
-      opts.is_a?(Hash) && opts[:allow_nil] && value.nil?
-    end
-
-    # Runs all configured validations on the parameter value.
-    #
-    # Iterates through all validation options and applies the appropriate
-    # validators, respecting skip conditions for optional parameters,
-    # conditional validations, and allow_nil settings.
-    #
-    # @return [void]
-    # @raise [ValidationError] If any validation fails
-    def validate!
-      return if skip_validations_due_to_optional_missing_argument?
-
-      options.each_key do |key|
-        next if skip_validator_due_to_allow_nil?(key)
-        next if skip_validator_due_to_conditional?(key)
-
-        case key.to_sym
-        when :custom then Validators::Custom
-        when :exclusion then Validators::Exclusion
-        when :format then Validators::Format
-        when :inclusion then Validators::Inclusion
-        when :length then Validators::Length
-        when :numeric then Validators::Numeric
-        when :presence then Validators::Presence
-        end&.call(value, options)
-      end
-    end
-
-  end
-end

data/lib/cmdx/parameters_inspector.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Parameter collection inspection utility for generating human-readable descriptions.
-  #
-  # The ParametersInspector module provides functionality to convert collections
-  # of parameters into formatted, human-readable string representations. It
-  # coordinates with ParameterInspector to format individual parameters and
-  # combines them into a cohesive multi-parameter description.
-  #
-  # @example Basic parameters collection inspection
-  #   parameter_registry = ParameterRegistry.new
-  #   parameter_registry << Parameter.new(:user_id, klass: Task, type: :integer, required: true)
-  #   parameter_registry << Parameter.new(:email, klass: Task, type: :string, required: false)
-  #
-  #   ParametersInspector.call(parameter_registry)
-  #   # => "Parameter: name=user_id type=integer source=context required=true options={}
-  #   #     Parameter: name=email type=string source=context required=false options={}"
-  #
-  # @example Empty parameters collection
-  #   empty_parameter_registry = ParameterRegistry.new
-  #   ParametersInspector.call(empty_parameter_registry)
-  #   # => ""
-  #
-  # @example Parameters with validation options
-  #   parameter_registry = ParameterRegistry.new
-  #   parameter_registry << Parameter.new(:age, klass: Task, type: :integer,
-  #                              numeric: { within: 18..120 }, required: true)
-  #   parameter_registry << Parameter.new(:website, klass: Task, type: :string,
-  #                              format: { with: /^https?:\/\// }, required: false)
-  #
-  #   ParametersInspector.call(parameter_registry)
-  #   # => "Parameter: name=age type=integer source=context required=true options={numeric: {within: 18..120}}
-  #   #     Parameter: name=website type=string source=context required=false options={format: {with: /^https?:\/\//}}"
-  #
-  # @see CMDx::ParameterRegistry Parameter collection management
-  # @see CMDx::ParameterInspector Individual parameter inspection
-  # @see CMDx::Parameter Parameter definition and configuration
-  module ParametersInspector
-
-    module_function
-
-    # Converts a Parameters collection to a human-readable string representation.
-    #
-    # Iterates through all parameters in the collection and formats each one
-    # using ParameterInspector, then joins them with newlines to create a
-    # comprehensive multi-parameter description.
-    #
-    # @param parameters [CMDx::ParameterRegistry] The parameters collection to inspect
-    # @return [String] Multi-line formatted parameter descriptions
-    #
-    # @example Inspecting multiple parameters
-    #   ParametersInspector.call(parameters_collection)
-    #   # => "Parameter: name=user_id type=integer source=context required=true
-    #   #     Parameter: name=email type=string source=context required=false
-    #   #     Parameter: name=age type=integer source=context required=true"
-    #
-    # @example Inspecting empty collection
-    #   ParametersInspector.call(ParameterRegistry.new)
-    #   # => ""
-    #
-    # @example Inspecting single parameter collection
-    #   single_param_collection = ParameterRegistry.new
-    #   single_param_collection << Parameter.new(:name, klass: Task)
-    #   ParametersInspector.call(single_param_collection)
-    #   # => "Parameter: name=name type=virtual source=context required=false options={}"
-    def call(parameters)
-      parameters.map(&:to_s).join("\n")
-    end
-
-  end
-end

data/lib/cmdx/parameters_serializer.rb

@@ -1,115 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Parameter collection serialization utility for converting Parameters to hash arrays.
-  #
-  # The ParametersSerializer module provides functionality to serialize collections
-  # of Parameter instances into structured array representations. Each parameter
-  # in the collection is converted to its hash representation, creating a
-  # comprehensive data structure suitable for inspection, logging, and data interchange.
-  #
-  # @example Basic parameters collection serialization
-  #   parameter_registry = ParameterRegistry.new
-  #   parameter_registry << Parameter.new(:user_id, klass: Task, type: :integer, required: true)
-  #   parameters << Parameter.new(:email, klass: Task, type: :string, required: false)
-  #
-  #   ParametersSerializer.call(parameters)
-  #   # => [
-  #   #   {
-  #   #     source: :context,
-  #   #     name: :user_id,
-  #   #     type: :integer,
-  #   #     required: true,
-  #   #     options: {},
-  #   #     children: []
-  #   #   },
-  #   #   {
-  #   #     source: :context,
-  #   #     name: :email,
-  #   #     type: :string,
-  #   #     required: false,
-  #   #     options: {},
-  #   #     children: []
-  #   #   }
-  #   # ]
-  #
-  # @example Empty parameters collection
-  #   empty_parameter_registry = ParameterRegistry.new
-  #   ParametersSerializer.call(empty_parameter_registry)
-  #   # => []
-  #
-  # @example Parameters with validation and nested structures
-  #   parameter_registry = ParameterRegistry.new
-  #   parameter_registry << Parameter.new(:age, klass: Task, type: :integer,
-  #                              numeric: { within: 18..120 }, required: true)
-  #
-  #   address_param = Parameter.new(:address, klass: Task) do
-  #     required :street, :city
-  #     optional :apartment
-  #   end
-  #   parameter_registry << address_param
-  #
-  #   ParametersSerializer.call(parameter_registry)
-  #   # => [
-  #   #   {
-  #   #     source: :context,
-  #   #     name: :age,
-  #   #     type: :integer,
-  #   #     required: true,
-  #   #     options: { numeric: { within: 18..120 } },
-  #   #     children: []
-  #   #   },
-  #   #   {
-  #   #     source: :context,
-  #   #     name: :address,
-  #   #     type: :virtual,
-  #   #     required: false,
-  #   #     options: {},
-  #   #     children: [
-  #   #       { source: :address, name: :street, type: :virtual, required: true, options: {}, children: [] },
-  #   #       { source: :address, name: :city, type: :virtual, required: true, options: {}, children: [] },
-  #   #       { source: :address, name: :apartment, type: :virtual, required: false, options: {}, children: [] }
-  #   #     ]
-  #   #   }
-  #   # ]
-  #
-  # @see CMDx::ParameterRegistry Parameter collection management
-  # @see CMDx::ParameterSerializer Individual parameter serialization
-  # @see CMDx::Parameter Parameter definition and configuration
-  module ParametersSerializer
-
-    module_function
-
-    # Converts a Parameters collection to an array of hash representations.
-    #
-    # Iterates through all parameters in the collection and converts each one
-    # to its hash representation using the Parameter#to_h method, which delegates
-    # to ParameterSerializer.
-    #
-    # @param parameters [CMDx::ParameterRegistry] The parameters collection to serialize
-    # @return [Array<Hash>] Array of serialized parameter data structures
-    #
-    # @example Serializing multiple parameters
-    #   ParametersSerializer.call(parameters_collection)
-    #   # => [
-    #   #   { source: :context, name: :user_id, type: :integer, required: true, options: {}, children: [] },
-    #   #   { source: :context, name: :email, type: :string, required: false, options: {}, children: [] }
-    #   # ]
-    #
-    # @example Serializing empty collection
-    #   ParametersSerializer.call(ParameterRegistry.new)
-    #   # => []
-    #
-    # @example Serializing single parameter collection
-    #   single_param_collection = ParameterRegistry.new
-    #   single_param_collection << Parameter.new(:name, klass: Task, type: :string)
-    #   ParametersSerializer.call(single_param_collection)
-    #   # => [
-    #   #   { source: :context, name: :name, type: :string, required: false, options: {}, children: [] }
-    #   # ]
-    def call(parameters)
-      parameters.map(&:to_h)
-    end
-
-  end
-end