operandi 5.0.0

data/lib/operandi/rspec/matchers/have_error_on.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Operandi
+  module RSpec
+    module Matchers
+      # Matcher for testing errors on a service instance
+      #
+      # @example Basic usage
+      #   expect(service).to have_error_on(:name)
+      #
+      # @example With specific message
+      #   expect(service).to have_error_on(:name).with_message("can't be blank")
+      #
+      # @example With message matching regex
+      #   expect(service).to have_error_on(:base).with_message(/invalid/)
+      #
+      # @example Check multiple error keys
+      #   expect(service).to have_errors_on(:name, :email)
+      def have_error_on(key)
+        HaveErrorOnMatcher.new(key)
+      end
+
+      def have_errors_on(*keys)
+        HaveErrorsOnMatcher.new(keys)
+      end
+
+      class HaveErrorOnMatcher
+        def initialize(key)
+          @key = key
+          @expected_message = nil
+        end
+
+        def with_message(message)
+          @expected_message = message
+          self
+        end
+
+        def matches?(service)
+          @service = service
+
+          return false unless has_error_key?
+          return false unless message_matches?
+
+          true
+        end
+
+        def failure_message
+          return "expected service to have error on :#{@key}, but errors were: #{errors_summary}" unless has_error_key?
+          return message_failure_message unless message_matches?
+
+          ""
+        end
+
+        def failure_message_when_negated
+          if @expected_message
+            "expected service not to have error on :#{@key} with message #{@expected_message.inspect}"
+          else
+            "expected service not to have error on :#{@key}"
+          end
+        end
+
+        def description
+          desc = "have error on :#{@key}"
+          desc += " with message #{@expected_message.inspect}" if @expected_message
+          desc
+        end
+
+        private
+
+        def has_error_key?
+          @service.errors.key?(@key)
+        end
+
+        def message_matches?
+          return true if @expected_message.nil?
+
+          error_messages = @service.errors[@key].map(&:to_s)
+
+          case @expected_message
+          when Regexp
+            error_messages.any? { |msg| msg.match?(@expected_message) }
+          else
+            error_messages.include?(@expected_message.to_s)
+          end
+        end
+
+        def message_failure_message
+          actual_messages = @service.errors[@key].map(&:to_s)
+          "expected service error on :#{@key} to include message #{@expected_message.inspect}, " \
+            "but messages were: #{actual_messages.inspect}"
+        end
+
+        def errors_summary
+          if @service.errors.empty?
+            "empty"
+          else
+            @service.errors.to_h.inspect
+          end
+        end
+      end
+
+      class HaveErrorsOnMatcher
+        def initialize(keys)
+          @keys = keys
+        end
+
+        def matches?(service)
+          @service = service
+          @missing_keys = []
+
+          @keys.each do |key|
+            @missing_keys << key unless @service.errors.key?(key)
+          end
+
+          @missing_keys.empty?
+        end
+
+        def failure_message
+          "expected service to have errors on #{@keys.inspect}, " \
+            "but missing errors on: #{@missing_keys.inspect}. " \
+            "Actual errors: #{errors_summary}"
+        end
+
+        def failure_message_when_negated
+          "expected service not to have errors on #{@keys.inspect}"
+        end
+
+        def description
+          "have errors on #{@keys.inspect}"
+        end
+
+        private
+
+        def errors_summary
+          if @service.errors.empty?
+            "empty"
+          else
+            @service.errors.to_h.inspect
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operandi/rspec/matchers/have_warning_on.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Operandi
+  module RSpec
+    module Matchers
+      # Matcher for testing warnings on a service instance
+      #
+      # @example Basic usage
+      #   expect(service).to have_warning_on(:name)
+      #
+      # @example With specific message
+      #   expect(service).to have_warning_on(:name).with_message("was replaced")
+      #
+      # @example With message matching regex
+      #   expect(service).to have_warning_on(:base).with_message(/deprecated/)
+      #
+      # @example Check multiple warning keys
+      #   expect(service).to have_warnings_on(:name, :email)
+      def have_warning_on(key)
+        HaveWarningOnMatcher.new(key)
+      end
+
+      def have_warnings_on(*keys)
+        HaveWarningsOnMatcher.new(keys)
+      end
+
+      class HaveWarningOnMatcher
+        def initialize(key)
+          @key = key
+          @expected_message = nil
+        end
+
+        def with_message(message)
+          @expected_message = message
+          self
+        end
+
+        def matches?(service)
+          @service = service
+
+          return false unless has_warning_key?
+          return false unless message_matches?
+
+          true
+        end
+
+        def failure_message
+          unless has_warning_key?
+            return "expected service to have warning on :#{@key}, but warnings were: #{warnings_summary}"
+          end
+          return message_failure_message unless message_matches?
+
+          ""
+        end
+
+        def failure_message_when_negated
+          if @expected_message
+            "expected service not to have warning on :#{@key} with message #{@expected_message.inspect}"
+          else
+            "expected service not to have warning on :#{@key}"
+          end
+        end
+
+        def description
+          desc = "have warning on :#{@key}"
+          desc += " with message #{@expected_message.inspect}" if @expected_message
+          desc
+        end
+
+        private
+
+        def has_warning_key?
+          @service.warnings.key?(@key)
+        end
+
+        def message_matches?
+          return true if @expected_message.nil?
+
+          warning_messages = @service.warnings[@key].map(&:to_s)
+
+          case @expected_message
+          when Regexp
+            warning_messages.any? { |msg| msg.match?(@expected_message) }
+          else
+            warning_messages.include?(@expected_message.to_s)
+          end
+        end
+
+        def message_failure_message
+          actual_messages = @service.warnings[@key].map(&:to_s)
+          "expected service warning on :#{@key} to include message #{@expected_message.inspect}, " \
+            "but messages were: #{actual_messages.inspect}"
+        end
+
+        def warnings_summary
+          if @service.warnings.empty?
+            "empty"
+          else
+            @service.warnings.to_h.inspect
+          end
+        end
+      end
+
+      class HaveWarningsOnMatcher
+        def initialize(keys)
+          @keys = keys
+        end
+
+        def matches?(service)
+          @service = service
+          @missing_keys = []
+
+          @keys.each do |key|
+            @missing_keys << key unless @service.warnings.key?(key)
+          end
+
+          @missing_keys.empty?
+        end
+
+        def failure_message
+          "expected service to have warnings on #{@keys.inspect}, " \
+            "but missing warnings on: #{@missing_keys.inspect}. " \
+            "Actual warnings: #{warnings_summary}"
+        end
+
+        def failure_message_when_negated
+          "expected service not to have warnings on #{@keys.inspect}"
+        end
+
+        def description
+          "have warnings on #{@keys.inspect}"
+        end
+
+        private
+
+        def warnings_summary
+          if @service.warnings.empty?
+            "empty"
+          else
+            @service.warnings.to_h.inspect
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operandi/rspec/matchers/trigger_callback.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Operandi
+  module RSpec
+    module Matchers
+      # Matcher for testing callback execution on a service instance
+      # NOTE: This matcher requires the service to track callback execution.
+      # Add tracking in your callbacks:
+      #
+      #   before_service_run do |service|
+      #     service.callback_log << :before_service_run
+      #   end
+      #
+      #   after_step_run do |service, step_name|
+      #     service.callback_log << [:after_step_run, step_name]
+      #   end
+      #
+      # @example Basic callback check (requires callback_log tracking)
+      #   expect(service).to trigger_callback(:before_service_run)
+      #
+      # @example Step-specific callback
+      #   expect(service).to trigger_callback(:after_step_run).for_step(:validate)
+      #
+      # @example Check callback was not triggered
+      #   expect(service).not_to trigger_callback(:on_service_failure)
+      def trigger_callback(callback_name)
+        TriggerCallbackMatcher.new(callback_name)
+      end
+
+      class TriggerCallbackMatcher
+        VALID_CALLBACKS = [
+          :before_service_run,
+          :after_service_run,
+          :around_service_run,
+          :on_service_success,
+          :on_service_failure,
+          :before_step_run,
+          :after_step_run,
+          :around_step_run,
+          :on_step_success,
+          :on_step_failure,
+          :on_step_crash,
+        ].freeze
+
+        STEP_CALLBACKS = [
+          :before_step_run,
+          :after_step_run,
+          :around_step_run,
+          :on_step_success,
+          :on_step_failure,
+          :on_step_crash,
+        ].freeze
+
+        def initialize(callback_name)
+          @callback_name = callback_name
+          @step_name = nil
+        end
+
+        def for_step(step_name)
+          @step_name = step_name
+          self
+        end
+
+        def matches?(service)
+          @service = service
+
+          return false unless service_tracks_callbacks?
+          return false unless callback_triggered?
+
+          true
+        end
+
+        def failure_message
+          return tracking_not_available_message unless service_tracks_callbacks?
+
+          if @step_name
+            "expected service to trigger callback :#{@callback_name} for step :#{@step_name}, " \
+              "but callback log was: #{callback_log.inspect}"
+          else
+            "expected service to trigger callback :#{@callback_name}, " \
+              "but callback log was: #{callback_log.inspect}"
+          end
+        end
+
+        def failure_message_when_negated
+          if @step_name
+            "expected service not to trigger callback :#{@callback_name} for step :#{@step_name}"
+          else
+            "expected service not to trigger callback :#{@callback_name}"
+          end
+        end
+
+        def description
+          desc = "trigger callback :#{@callback_name}"
+          desc += " for step :#{@step_name}" if @step_name
+          desc
+        end
+
+        private
+
+        def service_tracks_callbacks?
+          @service.respond_to?(:callback_log)
+        end
+
+        def callback_log
+          @service.callback_log
+        end
+
+        def callback_triggered?
+          if @step_name
+            # Look for step-specific callback entry like [:after_step_run, :validate]
+            callback_log.include?([@callback_name, @step_name])
+          else
+            # Look for service-level callback or any occurrence of the callback name
+            callback_log.any? do |entry|
+              case entry
+              when Symbol
+                entry == @callback_name
+              when Array
+                entry.first == @callback_name
+              else
+                false
+              end
+            end
+          end
+        end
+
+        def tracking_not_available_message
+          "cannot verify callback execution because service does not track callbacks. " \
+            "Add callback tracking to your service, e.g.: " \
+            "`before_service_run { |service| service.callback_log << :before_service_run }`"
+        end
+      end
+    end
+  end
+end

data/lib/operandi/rspec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "operandi"
+
+require_relative "rspec/matchers/define_argument"
+require_relative "rspec/matchers/define_output"
+require_relative "rspec/matchers/define_step"
+require_relative "rspec/matchers/have_error_on"
+require_relative "rspec/matchers/have_warning_on"
+require_relative "rspec/matchers/execute_step"
+require_relative "rspec/matchers/trigger_callback"
+
+RSpec.configure do |config|
+  config.include Operandi::RSpec::Matchers
+end

data/lib/operandi/rubocop/cop/operandi/argument_type_required.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Ensures that all `arg` declarations in Operandi include a `type:` option.
+      #
+      # @example
+      #   # bad
+      #   arg :user_id
+      #   arg :params, default: {}
+      #   arg :name, optional: true
+      #
+      #   # good
+      #   arg :user_id, type: Integer
+      #   arg :params, type: Hash, default: {}
+      #   arg :name, type: String, optional: true
+      #
+      class ArgumentTypeRequired < Base
+        MSG = "Argument `%<name>s` must have a `type:` option."
+
+        RESTRICT_ON_SEND = [:arg].freeze
+
+        # @!method arg_call?(node)
+        def_node_matcher :arg_call?, <<~PATTERN
+          (send nil? :arg (sym $_) ...)
+        PATTERN
+
+        def on_send(node)
+          arg_call?(node) do |name|
+            return if has_type_option?(node)
+
+            add_offense(node, message: format(MSG, name: name))
+          end
+        end
+
+        private
+
+        def has_type_option?(node)
+          # arg :name (no options)
+          return false if node.arguments.size == 1
+
+          # arg :name, type: Foo or arg :name, { type: Foo }
+          opts_node = node.arguments[1]
+          return false unless opts_node&.hash_type?
+
+          opts_node.pairs.any? { |pair| pair.key.sym_type? && pair.key.value == :type }
+        end
+      end
+    end
+  end
+end

data/lib/operandi/rubocop/cop/operandi/condition_method_exists.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Ensures that symbol conditions in `step` declarations (`:if` and `:unless`)
+      # have corresponding methods defined in the same class.
+      #
+      # This cop automatically recognizes:
+      # - Methods defined with `def`
+      # - Predicate methods from `arg` and `output` (e.g., `arg :user` creates `user` and `user?`)
+      # - Methods from `attr_reader`, `attr_accessor`, and `attr_writer`
+      #
+      # @example
+      #   # bad
+      #   class MyService < ApplicationService
+      #     step :process, if: :should_process?
+      #
+      #     private
+      #
+      #     def process
+      #       # should_process? is missing
+      #     end
+      #   end
+      #
+      #   # good - explicit method
+      #   class MyService < ApplicationService
+      #     step :process, if: :should_process?
+      #
+      #     private
+      #
+      #     def process; end
+      #     def should_process?; true; end
+      #   end
+      #
+      #   # good - predicate from arg
+      #   class MyService < ApplicationService
+      #     arg :user, type: User, optional: true
+      #
+      #     step :greet, if: :user?  # user? is auto-generated by arg :user
+      #
+      #     private
+      #
+      #     def greet; end
+      #   end
+      #
+      #   # good - attr_reader
+      #   class MyService < ApplicationService
+      #     attr_reader :enabled
+      #
+      #     step :process, if: :enabled
+      #
+      #     private
+      #
+      #     def process; end
+      #   end
+      #
+      # @example ExcludedMethods: ['admin?', 'guest?'] (default: [])
+      #   # good - these methods are excluded from checking
+      #   class MyService < ApplicationService
+      #     step :admin_action, if: :admin?  # excluded via config
+      #   end
+      #
+      class ConditionMethodExists < Base
+        MSG = "Condition method `%<name>s` has no corresponding method. " \
+              "For inherited methods, disable this line or add to ExcludedMethods."
+
+        CONDITION_KEYS = [:if, :unless].freeze
+        ATTR_METHODS = [:attr_reader, :attr_accessor, :attr_writer].freeze
+
+        def on_class(_node)
+          @condition_methods = []
+          @defined_methods = []
+          @dsl_predicates = []
+        end
+
+        def on_send(node)
+          if step_call?(node)
+            collect_condition_methods(node)
+          elsif arg_or_output_call?(node)
+            collect_dsl_predicate(node)
+          elsif attr_method_call?(node)
+            collect_attr_methods(node)
+          end
+        end
+
+        def on_def(node)
+          @defined_methods ||= []
+          @defined_methods << node.method_name
+        end
+
+        def after_class(_node)
+          return unless @condition_methods&.any?
+
+          @condition_methods.each do |condition|
+            next if method_available?(condition[:name])
+            next if excluded_method?(condition[:name])
+
+            add_offense(condition[:node], message: format(MSG, name: condition[:name]))
+          end
+        end
+
+        private
+
+        def step_call?(node)
+          node.send_type? &&
+            node.method_name == :step &&
+            node.receiver.nil? &&
+            node.arguments.first&.sym_type?
+        end
+
+        def arg_or_output_call?(node)
+          node.send_type? &&
+            [:arg, :output].include?(node.method_name) &&
+            node.receiver.nil? &&
+            node.arguments.first&.sym_type?
+        end
+
+        def attr_method_call?(node)
+          node.send_type? &&
+            ATTR_METHODS.include?(node.method_name) &&
+            node.receiver.nil?
+        end
+
+        def collect_condition_methods(node)
+          @condition_methods ||= []
+
+          opts_node = node.arguments[1]
+          return unless opts_node&.hash_type?
+
+          opts_node.pairs.each do |pair|
+            key = pair.key
+            value = pair.value
+
+            next unless key.sym_type? && CONDITION_KEYS.include?(key.value)
+            next unless value.sym_type?
+
+            @condition_methods << { name: value.value, node: value }
+          end
+        end
+
+        def collect_dsl_predicate(node)
+          @dsl_predicates ||= []
+
+          field_name = node.arguments.first.value
+          @dsl_predicates += [field_name, :"#{field_name}?"]
+        end
+
+        def collect_attr_methods(node)
+          @defined_methods ||= []
+
+          node.arguments.each do |arg|
+            next unless arg.sym_type?
+
+            @defined_methods << arg.value
+          end
+        end
+
+        def method_available?(method_name)
+          @defined_methods&.include?(method_name) || @dsl_predicates&.include?(method_name)
+        end
+
+        def excluded_method?(method_name)
+          excluded_methods.include?(method_name.to_s)
+        end
+
+        def excluded_methods
+          cop_config.fetch("ExcludedMethods", [])
+        end
+      end
+    end
+  end
+end