cmdx 1.1.2 → 1.5.0

data/lib/cmdx/rspec/task_matchers/be_well_formed_task.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task class is well-formed.
-#
-# This matcher checks if a task class meets all the requirements to be a properly
-# structured CMDx::Task. A well-formed task must inherit from CMDx::Task, implement
-# the call method, and have properly initialized registries for parameters, callbacks,
-# and middlewares. This is essential for ensuring task classes will function correctly
-# within the CMDx framework and can be used in workflows.
-#
-# @return [Boolean] true if the task class is well-formed with all required components
-#
-# @example Testing a basic task class
-#   class MyTask < CMDx::Task
-#     def call; end
-#   end
-#   expect(MyTask).to be_well_formed_task
-#
-# @example Testing a task with parameters, callbacks and middlewares
-#   class ComplexTask < CMDx::Task
-#     before_validation :refresh_cache
-#     use :middleware, CMDx::Middlewares::Timeout, timeout: 10
-#     required :data
-#     def call; end
-#   end
-#   expect(ComplexTask).to be_well_formed_task
-#
-# @example Testing generated task classes
-#   task_class = Class.new(CMDx::Task) { def call; end }
-#   expect(task_class).to be_well_formed_task
-#
-# @example Negative assertion for malformed tasks
-#   class BrokenTask; end  # Missing inheritance
-#   expect(BrokenTask).not_to be_well_formed_task
-RSpec::Matchers.define :be_well_formed_task do
-  match do |task_class|
-    (task_class < CMDx::Task) &&
-      task_class.instance_methods.include?(:call) &&
-      task_class.cmd_parameters.is_a?(CMDx::ParameterRegistry) &&
-      task_class.cmd_callbacks.is_a?(CMDx::CallbackRegistry) &&
-      task_class.cmd_middlewares.is_a?(CMDx::MiddlewareRegistry)
-  end
-
-  failure_message do |task_class|
-    issues = []
-    issues << "does not inherit from CMDx::Task" unless task_class < CMDx::Task
-    issues << "does not implement call method" unless task_class.instance_methods.include?(:call)
-    issues << "does not have parameter registry" unless task_class.cmd_parameters.is_a?(CMDx::ParameterRegistry)
-    issues << "does not have callback registry" unless task_class.cmd_callbacks.is_a?(CMDx::CallbackRegistry)
-    issues << "does not have middleware registry" unless task_class.cmd_middlewares.is_a?(CMDx::MiddlewareRegistry)
-
-    "expected task to be well-formed, but #{issues.join(', ')}"
-  end
-
-  failure_message_when_negated do |_task_class|
-    "expected task not to be well-formed, but it was"
-  end
-
-  description do
-    "be a well-formed task"
-  end
-end

data/lib/cmdx/rspec/task_matchers/have_callback.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task class has a specific callback.
-#
-# This matcher checks if a CMDx::Task class has registered a callback with the
-# specified name. Callbacks are methods that execute before, after, or around
-# the main task logic. The matcher can optionally verify that the callback has
-# a specific callable (method name, proc, or lambda) using the `with_callable`
-# chain method for more precise callback validation.
-#
-# @param callback_name [Symbol, String] the name of the callback to check for
-#
-# @return [Boolean] true if the task has the specified callback and optionally the expected callable
-#
-# @example Testing basic callback presence
-#   class MyTask < CMDx::Task
-#     before_execution :validate_input
-#     def call; end
-#   end
-#   expect(MyTask).to have_callback(:before_execution)
-#
-# @example Testing callback with specific callable
-#   class ProcessTask < CMDx::Task
-#     after_execution :log_completion
-#     def call; end
-#   end
-#   expect(ProcessTask).to have_callback(:after_execution).with_callable(:log_completion)
-#
-# @example Testing callbacks with procs
-#   class CustomTask < CMDx::Task
-#     before_execution -> { puts "Starting" }
-#     def call; end
-#   end
-#   expect(CustomTask).to have_callback(:before_execution)
-#
-# @example Negative assertion
-#   class SimpleTask < CMDx::Task
-#     def call; end
-#   end
-#   expect(SimpleTask).not_to have_callback(:before_execution)
-RSpec::Matchers.define :have_callback do |callback_name|
-  match do |task_class|
-    task_class.cmd_callbacks.registered?(callback_name)
-  end
-
-  chain :with_callable do |callable|
-    @expected_callable = callable
-  end
-
-  match do |task_class|
-    callbacks_registered = task_class.cmd_callbacks.registered?(callback_name)
-    return false unless callbacks_registered
-
-    if @expected_callable
-      task_class.cmd_callbacks.find(callback_name).any? do |callback|
-        callback.callable == @expected_callable
-      end
-    else
-      true
-    end
-  end
-
-  failure_message do |task_class|
-    if @expected_callable
-      "expected task to have callback #{callback_name} with callable #{@expected_callable}, but it didn't"
-    else
-      registered_callbacks = task_class.cmd_callbacks.registered_callbacks
-      "expected task to have callback #{callback_name}, but had #{registered_callbacks}"
-    end
-  end
-
-  failure_message_when_negated do |_task_class|
-    if @expected_callable
-      "expected task not to have callback #{callback_name} with callable #{@expected_callable}, but it did"
-    else
-      "expected task not to have callback #{callback_name}, but it did"
-    end
-  end
-
-  description do
-    desc = "have callback #{callback_name}"
-    desc += " with callable #{@expected_callable}" if @expected_callable
-    desc
-  end
-end

data/lib/cmdx/rspec/task_matchers/have_cmd_setting.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task class has a specific task setting.
-#
-# This matcher checks if a CMDx::Task class has registered a task setting with the
-# specified name. Task settings are configuration options that control task behavior
-# such as execution timeouts, retry policies, or custom flags. The matcher can
-# optionally verify that the setting has a specific value for more precise validation.
-#
-# @param setting_name [Symbol, String] the name of the task setting to check for
-# @param expected_value [Object, nil] the expected value of the setting (optional)
-#
-# @return [Boolean] true if the task has the specified setting and optionally the expected value
-#
-# @example Testing basic task setting presence
-#   class MyTask < CMDx::Task
-#     cmd_setting tags: ["admin"]
-#     def call; end
-#   end
-#   expect(MyTask).to have_cmd_setting(:tags)
-#
-# @example Testing task setting with specific value
-#   class ProcessTask < CMDx::Task
-#     cmd_setting tags: ["admin"]
-#     def call; end
-#   end
-#   expect(ProcessTask).to have_cmd_setting(:tags, ["admin"])
-#
-# @example Negative assertion
-#   class SimpleTask < CMDx::Task
-#     def call; end
-#   end
-#   expect(SimpleTask).not_to have_cmd_setting(:tags)
-RSpec::Matchers.define :have_cmd_setting do |setting_name, expected_value = nil|
-  match do |task_class|
-    return false unless task_class.cmd_setting?(setting_name)
-
-    if expected_value
-      task_class.cmd_setting(setting_name) == expected_value
-    else
-      true
-    end
-  end
-
-  failure_message do |task_class|
-    if expected_value
-      actual_value = task_class.cmd_setting(setting_name)
-      "expected task to have setting #{setting_name} with value #{expected_value}, but was #{actual_value}"
-    else
-      available_settings = task_class.cmd_settings.keys
-      "expected task to have setting #{setting_name}, but had #{available_settings}"
-    end
-  end
-
-  failure_message_when_negated do |_task_class|
-    if expected_value
-      "expected task not to have setting #{setting_name} with value #{expected_value}, but it did"
-    else
-      "expected task not to have setting #{setting_name}, but it did"
-    end
-  end
-
-  description do
-    desc = "have task setting #{setting_name}"
-    desc += " with value #{expected_value}" if expected_value
-    desc
-  end
-end

data/lib/cmdx/rspec/task_matchers/have_executed_callbacks.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task has executed specific callbacks.
-#
-# This matcher verifies that callbacks were actually invoked during task execution,
-# not just registered. It works by mocking the callback execution to track which
-# callbacks are called, then executing the task and checking that the expected
-# callbacks were invoked. This is useful for testing that callback logic is properly
-# triggered during task execution rather than just checking callback registration.
-#
-# @param callback_names [Array<Symbol, String>] the names of callbacks expected to execute
-#
-# @return [Boolean] true if all specified callbacks were executed during task execution
-#
-# @example Testing basic callback execution
-#   class MyTask < CMDx::Task
-#     before_execution :setup
-#     def call; end
-#   end
-#   expect(MyTask.new).to have_executed_callbacks(:before_execution)
-#
-# @example Testing callback execution with specific callable
-#   class ProcessTask < CMDx::Task
-#     after_execution :log_completion
-#     def call; end
-#   end
-#   expect(ProcessTask).to have_callback(:after_execution).with_callable(:log_completion)
-#
-# @example Testing callback execution with result
-#   result = MyTask.call(data: "test")
-#   expect(result).to have_executed_callbacks(:before_execution, :after_execution)
-#
-# @example Negative assertion
-#   class SimpleTask < CMDx::Task
-#     def call; end
-#   end
-#   expect(SimpleTask.new).not_to have_executed_callbacks(:before_execution)
-RSpec::Matchers.define :have_executed_callbacks do |*callback_names|
-  match do |task_or_result|
-    @executed_callbacks = []
-
-    # Mock the callback execution to track what gets called
-    if task_or_result.is_a?(CMDx::Task)
-      task = task_or_result
-      original_callback_call = task.cmd_callbacks.method(:call)
-
-      allow(task.cmd_callbacks).to receive(:call) do |task_instance, callback_name|
-        @executed_callbacks << callback_name
-        original_callback_call.call(task_instance, callback_name)
-      end
-
-      task.process
-    else
-      # If it's a result, check if callbacks were executed during task execution
-      result = task_or_result
-      # This would require the callbacks to be tracked during execution
-      # For now, assume callbacks were executed based on result state
-      @executed_callbacks = infer_executed_callbacks(result)
-    end
-
-    callback_names.all? { |callback_name| @executed_callbacks.include?(callback_name) }
-  end
-
-  failure_message do |_task_or_result|
-    missing_callbacks = callback_names - @executed_callbacks
-    "expected to execute callbacks #{callback_names}, but missing #{missing_callbacks}. Executed: #{@executed_callbacks}"
-  end
-
-  failure_message_when_negated do |_task_or_result|
-    "expected not to execute callbacks #{callback_names}, but executed #{@executed_callbacks & callback_names}"
-  end
-
-  description do
-    "execute callbacks #{callback_names}"
-  end
-
-  private
-
-  def infer_executed_callbacks(result)
-    callbacks = []
-    callbacks << :before_validation if result.executed?
-    callbacks << :after_validation if result.executed?
-    callbacks << :before_execution if result.executed?
-    callbacks << :after_execution if result.executed?
-    callbacks << :on_executed if result.executed?
-    callbacks << :"on_#{result.status}" if result.executed?
-    callbacks << :on_good if result.good?
-    callbacks << :on_bad if result.bad?
-    callbacks << :"on_#{result.state}" if result.executed?
-    callbacks
-  end
-end

data/lib/cmdx/rspec/task_matchers/have_middleware.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task class has a specific middleware.
-#
-# This matcher checks if a CMDx::Task class has registered a middleware of the
-# specified class. Middlewares are components that wrap around task execution to
-# provide cross-cutting concerns like logging, timing, error handling, or other
-# aspects. The matcher verifies that the middleware is properly registered and
-# available for execution during task performance.
-#
-# @param middleware_class [Class] the middleware class to check for
-#
-# @return [Boolean] true if the task has the specified middleware class registered
-#
-# @example Testing middleware registration
-#   class MyTask < CMDx::Task
-#     use :middleware, CMDx::Middlewares::Timeout, timeout: 10
-#     def call; end
-#   end
-#   expect(MyTask).to have_middleware(TimeoutMiddleware)
-#
-# @example Negative assertion
-#   class SimpleTask < CMDx::Task
-#     def call; end
-#   end
-#   expect(SimpleTask).not_to have_middleware(TimeoutMiddleware)
-RSpec::Matchers.define :have_middleware do |middleware_class|
-  match do |task_class|
-    task_class.cmd_middlewares.any? do |middleware|
-      middleware.is_a?(middleware_class) || middleware.instance_of?(middleware_class)
-    end
-  end
-
-  failure_message do |task_class|
-    middleware_classes = task_class.cmd_middlewares.map(&:class)
-    "expected task to have middleware #{middleware_class}, but had #{middleware_classes}"
-  end
-
-  failure_message_when_negated do |_task_class|
-    "expected task not to have middleware #{middleware_class}, but it did"
-  end
-
-  description do
-    "have middleware #{middleware_class}"
-  end
-end

data/lib/cmdx/rspec/task_matchers/have_parameter.rb

@@ -1,181 +0,0 @@
-# frozen_string_literal: true
-
-# RSpec matcher for asserting that a task class has a specific parameter.
-#
-# This matcher checks if a CMDx::Task class has registered a parameter with the
-# specified name. Parameters are inputs to task execution that can be required
-# or optional, typed with coercions, validated, and have default values. The
-# matcher supports various chain methods for precise parameter validation.
-#
-# @param parameter_name [Symbol, String] the name of the parameter to check for
-#
-# @return [Boolean] true if the task has the specified parameter and optionally matches all criteria
-#
-# @example Testing basic parameter presence
-#   class MyTask < CMDx::Task
-#     optional :input_file, type: :string
-#     def call; end
-#   end
-#   expect(MyTask).to have_parameter(:input_file)
-#
-# @example Testing required parameter
-#   class ProcessTask < CMDx::Task
-#     required data, type: :string
-#     def call; end
-#   end
-#   expect(ProcessTask).to have_parameter(:data).that_is_required
-#
-# @example Testing optional parameter with default
-#   class ConfigTask < CMDx::Task
-#     optional timeout, type: :integer, default: 30
-#     def call; end
-#   end
-#   expect(ConfigTask).to have_parameter(:timeout).that_is_optional.with_default(30)
-#
-# @example Testing parameter with type coercion
-#   class ImportTask < CMDx::Task
-#     optional csv_file, type: :string
-#     optional batch_size, type: :integer
-#     def call; end
-#   end
-#   expect(ImportTask).to have_parameter(:csv_file).with_type(:string)
-#   expect(ImportTask).to have_parameter(:batch_size).with_coercion(:integer)
-#
-# @example Testing parameter with validations
-#   class UserTask < CMDx::Task
-#     optional email, type: :string, format: /@/, presence: true
-#     def call; end
-#   end
-#   expect(UserTask).to have_parameter(:email).with_validations(:format, :presence)
-#
-# @example Negative assertion
-#   class SimpleTask < CMDx::Task
-#     def call; end
-#   end
-#   expect(SimpleTask).not_to have_parameter(:nonexistent)
-RSpec::Matchers.define :have_parameter do |parameter_name|
-  match do |task_class|
-    @parameter = task_class.cmd_parameters.registry.find { |p| p.method_name == parameter_name }
-    return false unless @parameter
-
-    # Check if parameter exists
-    parameter_exists = !@parameter.nil?
-    return false unless parameter_exists
-
-    # Check required/optional if specified
-    unless @expected_required.nil?
-      required_matches = @parameter.required? == @expected_required
-      return false unless required_matches
-    end
-
-    # Check type/coercion if specified
-    if @expected_type
-      type_matches = @parameter.type == @expected_type
-      return false unless type_matches
-    end
-
-    # Check validations if specified
-    if @expected_validations&.any?
-      validations_match = @expected_validations.all? do |validation_type|
-        @parameter.options.key?(validation_type)
-      end
-      return false unless validations_match
-    end
-
-    # Check default value if specified
-    if @expected_default_value != :__not_specified__
-      default_matches = @parameter.options[:default] == @expected_default_value
-      return false unless default_matches
-    end
-
-    true
-  end
-
-  chain :that_is_required do
-    @expected_required = true
-  end
-
-  chain :that_is_optional do
-    @expected_required = false
-  end
-
-  chain :with_type do |type|
-    @expected_type = type
-  end
-
-  chain :with_coercion do |type|
-    @expected_type = type
-  end
-
-  chain :with_validations do |*validations|
-    @expected_validations = validations
-  end
-
-  chain :with_validation do |validation|
-    @expected_validations = [@expected_validations, validation].flatten.compact
-  end
-
-  chain :with_default do |default_value|
-    @expected_default_value = default_value
-  end
-
-  define_method :initialize do |parameter_name|
-    @parameter_name = parameter_name
-    @expected_required = nil
-    @expected_type = nil
-    @expected_validations = []
-    @expected_default_value = :__not_specified__
-  end
-
-  failure_message do |task_class|
-    if @parameter.nil?
-      available_parameters = task_class.cmd_parameters.registry.map(&:method_name)
-      "expected task to have parameter #{@parameter_name}, but had parameters: #{available_parameters}"
-    else
-      issues = []
-
-      if !@expected_required.nil? && @parameter.required? != @expected_required
-        expected_req_text = @expected_required ? "required" : "optional"
-        actual_req_text = @parameter.required? ? "required" : "optional"
-        issues << "expected parameter to be #{expected_req_text}, but was #{actual_req_text}"
-      end
-
-      if @expected_type
-        actual_type = @parameter.type
-        issues << "expected parameter type to be #{@expected_type}, but was #{actual_type}" unless actual_type == @expected_type
-      end
-
-      if @expected_validations&.any?
-        missing_validations = @expected_validations.reject do |validation_type|
-          @parameter.options.key?(validation_type)
-        end
-
-        if missing_validations.any?
-          actual_validations = @parameter.options.keys
-          issues << "expected parameter to have validations #{missing_validations}, but had #{actual_validations}"
-        end
-      end
-
-      issues << "expected parameter default to be #{@expected_default_value}, but was #{@parameter.options[:default]}" if (@expected_default_value != :__not_specified__) && @parameter.options[:default] != @expected_default_value
-
-      if issues.any?
-        "expected parameter #{@parameter_name} to match criteria, but #{issues.join(', ')}"
-      else
-        "expected parameter #{@parameter_name} to match all criteria, but something didn't match"
-      end
-    end
-  end
-
-  failure_message_when_negated do |_task_class|
-    "expected task not to have parameter #{@parameter_name}, but it did"
-  end
-
-  description do
-    desc = "have parameter #{@parameter_name}"
-    desc += " that is #{@expected_required ? 'required' : 'optional'}" unless @expected_required.nil?
-    desc += " with type #{@expected_type}" if @expected_type
-    desc += " with validations #{@expected_validations}" if @expected_validations&.any?
-    desc += " with default #{@expected_default_value}" if @expected_default_value != :__not_specified__
-    desc
-  end
-end

data/lib/cmdx/task_deprecator.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Task deprecation system for CMDx tasks.
-  #
-  # This module provides a centralized system for handling task deprecation
-  # warnings and errors. It supports multiple deprecation modes including
-  # raising exceptions, logging warnings, or issuing Ruby warnings based
-  # on task configuration settings.
-  module TaskDeprecator
-
-    module_function
-
-    # Processes task deprecation based on the task's deprecated setting.
-    #
-    # @param task [CMDx::Task] the task instance to check for deprecation
-    # @return [void]
-    # @raise [DeprecationError] when task's deprecated setting is :error
-    #
-    # @example Handle task with raise deprecation
-    #   class MyTask < CMDx::Task
-    #     cmd_setting!(deprecated: :error)
-    #   end
-    #   task = MyTask.new
-    #   TaskDeprecator.call(task) # raises DeprecationError
-    #
-    # @example Handle task with log deprecation
-    #   class MyTask < CMDx::Task
-    #     cmd_setting!(deprecated: :log)
-    #   end
-    #   task = MyTask.new
-    #   TaskDeprecator.call(task) # logs warning via task.logger
-    #
-    # @example Handle task with warn deprecation
-    #   class MyTask < CMDx::Task
-    #     cmd_setting!(deprecated: :warning)
-    #   end
-    #   task = MyTask.new
-    #   TaskDeprecator.call(task) # issues Ruby warning
-    def call(task)
-      type = task.cmd_setting(:deprecated)
-
-      case type
-      when :error
-        raise DeprecationError, "#{task.class.name} usage prohibited"
-      when :log, true
-        task.logger.warn { "DEPRECATED: migrate to replacement or discontinue use" }
-      when :warning
-        warn("[#{task.class.name}] DEPRECATED: migrate to replacement or discontinue use", category: :deprecated)
-      when nil, false
-        # Do nothing
-      else
-        raise UnknownDeprecationError, "unknown deprecation type #{type}"
-      end
-    end
-
-  end
-end