operandi 5.0.0

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Detects deprecated `arguments` and `outputs` accessor calls and suggests
+      # using `arg` and `output` instead.
+      #
+      # This cop checks calls inside service classes that inherit from
+      # Operandi::Base or any configured base service classes.
+      #
+      # @safety
+      #   This cop's autocorrection is safe as `arguments` and `outputs` are
+      #   direct wrappers for `arg` and `output`.
+      #
+      # @example
+      #   # bad
+      #   class User::Create < ApplicationService
+      #     step :process
+      #
+      #     private
+      #
+      #     def process
+      #       arguments[:name]
+      #       outputs[:result]
+      #     end
+      #   end
+      #
+      #   # good
+      #   class User::Create < ApplicationService
+      #     step :process
+      #
+      #     private
+      #
+      #     def process
+      #       arg[:name]
+      #       output[:result]
+      #     end
+      #   end
+      #
+      class DeprecatedAccessors < Base
+        extend AutoCorrector
+
+        MSG_ARGUMENTS = "Use `arg` instead of deprecated `arguments`."
+        MSG_OUTPUTS = "Use `output` instead of deprecated `outputs`."
+
+        RESTRICT_ON_SEND = [:arguments, :outputs].freeze
+
+        REPLACEMENTS = {
+          arguments: :arg,
+          outputs: :output,
+        }.freeze
+
+        DEFAULT_BASE_CLASSES = ["ApplicationService"].freeze
+
+        def on_class(node)
+          @in_service_class = service_class?(node)
+        end
+
+        def after_class(_node)
+          @in_service_class = false
+        end
+
+        def on_send(node)
+          return unless @in_service_class
+          return unless RESTRICT_ON_SEND.include?(node.method_name)
+          return if node.receiver && !self_receiver?(node)
+
+          message = node.method_name == :arguments ? MSG_ARGUMENTS : MSG_OUTPUTS
+          replacement = REPLACEMENTS[node.method_name]
+
+          add_offense(node, message: message) do |corrector|
+            if node.receiver
+              corrector.replace(node, "self.#{replacement}")
+            else
+              corrector.replace(node, replacement.to_s)
+            end
+          end
+        end
+
+        private
+
+        def service_class?(node)
+          return false unless node.parent_class
+
+          parent_class_name = extract_class_name(node.parent_class)
+          return false unless parent_class_name
+
+          # Check for direct Operandi::Base inheritance
+          return true if parent_class_name == "Operandi::Base"
+
+          # Check against configured base service classes
+          base_classes = cop_config.fetch("BaseServiceClasses", DEFAULT_BASE_CLASSES)
+          base_classes.include?(parent_class_name)
+        end
+
+        def extract_class_name(node)
+          case node.type
+          when :const
+            node.const_name
+          when :send
+            # For namespaced constants like Operandi::Base
+            node.source
+          end
+        end
+
+        def self_receiver?(node)
+          node.receiver&.self_type?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Detects deprecated `done!` and `done?` method calls and suggests
+      # using `stop!` and `stopped?` instead.
+      #
+      # This cop checks calls inside service classes that inherit from
+      # Operandi::Base or any configured base service classes.
+      #
+      # @safety
+      #   This cop's autocorrection is safe as `done!` and `done?` are
+      #   direct aliases for `stop!` and `stopped?`.
+      #
+      # @example
+      #   # bad
+      #   class User::Create < ApplicationService
+      #     step :process
+      #
+      #     private
+      #
+      #     def process
+      #       done! if condition_met?
+      #       return if done?
+      #     end
+      #   end
+      #
+      #   # good
+      #   class User::Create < ApplicationService
+      #     step :process
+      #
+      #     private
+      #
+      #     def process
+      #       stop! if condition_met?
+      #       return if stopped?
+      #     end
+      #   end
+      #
+      class DeprecatedMethods < Base
+        extend AutoCorrector
+
+        MSG_DONE_BANG = "Use `stop!` instead of deprecated `done!`."
+        MSG_DONE_QUERY = "Use `stopped?` instead of deprecated `done?`."
+
+        RESTRICT_ON_SEND = [:done!, :done?].freeze
+
+        REPLACEMENTS = {
+          done!: :stop!,
+          done?: :stopped?,
+        }.freeze
+
+        DEFAULT_BASE_CLASSES = ["ApplicationService"].freeze
+
+        def on_class(node)
+          @in_service_class = service_class?(node)
+        end
+
+        def after_class(_node)
+          @in_service_class = false
+        end
+
+        def on_send(node)
+          return unless @in_service_class
+          return unless RESTRICT_ON_SEND.include?(node.method_name)
+          return if node.receiver && !self_receiver?(node)
+
+          message = node.method_name == :done! ? MSG_DONE_BANG : MSG_DONE_QUERY
+          replacement = REPLACEMENTS[node.method_name]
+
+          add_offense(node, message: message) do |corrector|
+            if node.receiver
+              corrector.replace(node, "self.#{replacement}")
+            else
+              corrector.replace(node, replacement.to_s)
+            end
+          end
+        end
+
+        private
+
+        def service_class?(node)
+          return false unless node.parent_class
+
+          parent_class_name = extract_class_name(node.parent_class)
+          return false unless parent_class_name
+
+          # Check for direct Operandi::Base inheritance
+          return true if parent_class_name == "Operandi::Base"
+
+          # Check against configured base service classes
+          base_classes = cop_config.fetch("BaseServiceClasses", DEFAULT_BASE_CLASSES)
+          base_classes.include?(parent_class_name)
+        end
+
+        def extract_class_name(node)
+          case node.type
+          when :const
+            node.const_name
+          when :send
+            # For namespaced constants like Operandi::Base
+            node.source
+          end
+        end
+
+        def self_receiver?(node)
+          node.receiver&.self_type?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Enforces a consistent order for DSL declarations in service classes.
+      #
+      # The expected order is: `config` → `arg` → `step` → `output`
+      #
+      # @safety
+      #   This cop's autocorrection is safe but may change the visual grouping of your code.
+      #
+      # @example
+      #   # bad
+      #   class MyService < ApplicationService
+      #     step :process
+      #     arg :name, type: String
+      #     output :result, type: Hash
+      #     config raise_on_error: true
+      #   end
+      #
+      #   # good
+      #   class MyService < ApplicationService
+      #     config raise_on_error: true
+      #
+      #     arg :name, type: String
+      #
+      #     step :process
+      #
+      #     output :result, type: Hash
+      #   end
+      #
+      class DslOrder < Base
+        extend AutoCorrector
+
+        MSG = "`%<current>s` should come before `%<previous>s`. " \
+              "Expected order: config → arg → step → output."
+
+        DSL_METHODS = [:config, :arg, :step, :output].freeze
+        DSL_ORDER = { config: 0, arg: 1, step: 2, output: 3 }.freeze
+
+        def on_class(node)
+          @dsl_calls = []
+          @class_node = node
+        end
+
+        def on_send(node)
+          return unless dsl_call?(node)
+
+          @dsl_calls ||= []
+          @dsl_calls << { method: node.method_name, node: node }
+        end
+
+        def after_class(_node)
+          return unless @dsl_calls&.any?
+
+          check_order
+        end
+
+        private
+
+        def dsl_call?(node)
+          node.send_type? &&
+            node.receiver.nil? &&
+            DSL_METHODS.include?(node.method_name) &&
+            class_level?(node)
+        end
+
+        def class_level?(node)
+          node.each_ancestor(:def, :defs, :block).none?
+        end
+
+        def check_order
+          highest_order_seen = -1
+          highest_method_seen = nil
+          has_offense = false
+
+          @dsl_calls.each do |call|
+            current_order = DSL_ORDER[call[:method]]
+
+            if current_order < highest_order_seen
+              has_offense = true
+              add_offense(
+                call[:node],
+                message: format(MSG, current: call[:method], previous: highest_method_seen),
+              ) do |corrector|
+                reorder_dsl_declarations(corrector) unless @corrected
+                @corrected = true
+              end
+            elsif current_order > highest_order_seen
+              highest_order_seen = current_order
+              highest_method_seen = call[:method]
+            end
+          end
+
+          @corrected = false if has_offense
+        end
+
+        def reorder_dsl_declarations(corrector) # rubocop:disable Metrics/AbcSize
+          # Collect all DSL nodes with their source including leading comments
+          dsl_sources = @dsl_calls.map do |call|
+            {
+              method: call[:method],
+              node: call[:node],
+              source: source_with_leading_comment(call[:node]),
+            }
+          end
+
+          # Sort by expected order
+          sorted_sources = dsl_sources.sort_by { |item| DSL_ORDER[item[:method]] }
+
+          # Group by type to add blank lines between groups
+          grouped_source = build_grouped_source(sorted_sources)
+
+          # Calculate the range to replace (from first DSL to last DSL)
+          first_node = @dsl_calls.min_by { |c| c[:node].loc.expression.begin_pos }[:node]
+          last_node = @dsl_calls.max_by { |c| c[:node].loc.expression.end_pos }[:node]
+
+          # Get the range including leading comments of first node
+          start_pos = first_node.loc.expression.begin_pos
+          leading_comment = leading_comment_for(first_node)
+          start_pos = leading_comment.loc.expression.begin_pos if leading_comment
+
+          # Find the beginning of the line for proper replacement
+          start_pos = beginning_of_line(start_pos)
+          end_pos = end_of_line(last_node.loc.expression.end_pos)
+
+          range = range_between(start_pos, end_pos)
+          corrector.replace(range, grouped_source)
+        end
+
+        def source_with_leading_comment(node)
+          comment = leading_comment_for(node)
+          indent = " " * node.loc.column
+
+          if comment
+            "#{indent}#{comment.text}\n#{indent}#{node.source}"
+          else
+            "#{indent}#{node.source}"
+          end
+        end
+
+        def leading_comment_for(node)
+          processed_source.comments.find do |comment|
+            comment.loc.line == node.loc.line - 1
+          end
+        end
+
+        def build_grouped_source(sorted_sources)
+          result = []
+          current_type = nil
+
+          sorted_sources.each do |item|
+            # Add blank line when switching to a new DSL type
+            result << "" if current_type && current_type != item[:method]
+            current_type = item[:method]
+            result << item[:source]
+          end
+
+          result.join("\n")
+        end
+
+        def beginning_of_line(pos)
+          source = processed_source.buffer.source
+          pos -= 1 while pos > 0 && source[pos - 1] != "\n"
+          pos
+        end
+
+        def end_of_line(pos)
+          source = processed_source.buffer.source
+          pos += 1 while pos < source.length && source[pos] != "\n"
+          pos
+        end
+
+        def range_between(start_pos, end_pos)
+          Parser::Source::Range.new(processed_source.buffer, start_pos, end_pos)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Ensures that step methods are defined as private.
+      # Step methods are implementation details and should not be part of the public API.
+      #
+      # @example
+      #   # bad
+      #   class MyService < ApplicationService
+      #     step :process
+      #     step :notify
+      #
+      #     def process
+      #       # This should be private
+      #     end
+      #
+      #     def notify
+      #       # This should be private
+      #     end
+      #   end
+      #
+      #   # good
+      #   class MyService < ApplicationService
+      #     step :process
+      #     step :notify
+      #
+      #     private
+      #
+      #     def process
+      #       # Now private
+      #     end
+      #
+      #     def notify
+      #       # Now private
+      #     end
+      #   end
+      #
+      class MissingPrivateKeyword < Base
+        MSG = "Step method `%<name>s` should be private."
+
+        def on_class(_node)
+          @step_names = []
+          @private_section_started = false
+          @public_step_methods = []
+        end
+
+        def on_send(node)
+          if step_call?(node)
+            step_name = node.arguments.first&.value
+            @step_names ||= []
+            @step_names << step_name if step_name
+          elsif private_declaration?(node)
+            @private_section_started = true
+          elsif public_declaration?(node)
+            @private_section_started = false
+          end
+        end
+
+        def on_def(node)
+          return unless @step_names&.include?(node.method_name)
+          return if @private_section_started
+
+          @public_step_methods ||= []
+          @public_step_methods << node
+        end
+
+        def after_class(_node)
+          return unless @public_step_methods&.any?
+
+          @public_step_methods.each do |node|
+            add_offense(node, message: format(MSG, name: node.method_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 private_declaration?(node)
+          node.send_type? &&
+            node.method_name == :private &&
+            node.receiver.nil? &&
+            node.arguments.empty?
+        end
+
+        def public_declaration?(node)
+          node.send_type? &&
+            node.method_name == :public &&
+            node.receiver.nil? &&
+            node.arguments.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Prevents direct instantiation of service classes with `.new`.
+      # Services should be called using `.run`, `.run!`, or `.call`.
+      #
+      # @example
+      #   # bad
+      #   UserService.new(name: "John")
+      #   User::Create.new(params: {})
+      #
+      #   # good
+      #   UserService.run(name: "John")
+      #   UserService.run!(name: "John")
+      #   UserService.call(name: "John")
+      #   User::Create.run(params: {})
+      #
+      # @example ServicePattern: 'Service$' (default)
+      #   # Matches class names ending with "Service"
+      #   UserService.new  # offense
+      #   UserCreator.new  # no offense (doesn't match pattern)
+      #
+      # @example ServicePattern: '(Service|Creator)$'
+      #   # Matches class names ending with "Service" or "Creator"
+      #   UserService.new  # offense
+      #   UserCreator.new  # offense
+      #
+      class NoDirectInstantiation < Base
+        MSG = "Use `.run`, `.run!`, or `.call` instead of `.new` for service classes."
+
+        RESTRICT_ON_SEND = [:new].freeze
+
+        def on_send(node)
+          return unless node.method_name == :new
+          return unless service_class?(node.receiver)
+
+          add_offense(node)
+        end
+
+        private
+
+        def service_class?(node)
+          return false unless node
+
+          class_name = extract_class_name(node)
+          return false unless class_name
+
+          pattern = cop_config.fetch("ServicePattern", "Service$")
+          class_name.match?(Regexp.new(pattern))
+        end
+
+        def extract_class_name(node)
+          case node.type
+          when :const
+            node.const_name
+          when :send
+            # For chained constants like User::Create
+            node.source
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Detects when `.run` or `.run!` is called with a hash argument instead of keyword arguments.
+      #
+      # Since Operandi services now only accept keyword arguments, passing a hash variable
+      # or hash expression will cause an error. Use keyword splatting (`**`) to convert
+      # hash arguments to keyword arguments.
+      #
+      # @safety
+      #   This cop is disabled by default because it may produce false positives
+      #   when `.run` is called on non-Operandi classes.
+      #
+      # @example
+      #   # bad
+      #   UserService.run(args)
+      #   UserService.run!(params)
+      #   UserService.run(args.merge(new: true))
+      #   UserService.run({ name: "John" })
+      #   Auth::SignIn.run(service_args)
+      #
+      #   # good
+      #   UserService.run(name: "John")
+      #   UserService.run(**args)
+      #   UserService.run(**args.merge(new: true))
+      #   UserService.run(**args, new: true)
+      #   Auth::SignIn.run(**service_args)
+      #
+      # @example ServicePattern: nil (default - checks all classes)
+      #   # Checks all .run and .run! calls
+      #   UserService.run(args)       # offense
+      #   Auth::SignIn.run(args)      # offense
+      #   SomeClass.run(args)         # offense
+      #
+      # @example ServicePattern: 'Service$'
+      #   # Only matches class names ending with "Service"
+      #   UserService.run(args)       # offense
+      #   Auth::SignIn.run(args)      # no offense (doesn't match pattern)
+      #
+      class NoHashArgument < Base
+        MSG = "Use keyword arguments or `**` splat instead of hash argument for `.%<method>s`."
+
+        RESTRICT_ON_SEND = [:run, :run!].freeze
+
+        def on_send(node)
+          return unless RESTRICT_ON_SEND.include?(node.method_name)
+          return unless service_class?(node.receiver)
+          return if node.arguments.empty?
+          return if valid_arguments?(node.arguments)
+
+          add_offense(node, message: format(MSG, method: node.method_name), severity: :fatal)
+        end
+
+        private
+
+        def valid_arguments?(arguments)
+          arguments.all? do |arg|
+            case arg.type
+            when :block_pass
+              # Block pass (&block) is always valid
+              true
+            when :hash
+              # Hash node can be:
+              # - Implicit hash for keyword args: run(foo: bar) - braces? returns false
+              # - Explicit hash literal: run({ foo: bar }) - braces? returns true
+              # Only implicit hash (keyword args) is valid
+              !arg.braces?
+            else
+              # Any other type (lvar, send, ivar, etc.) is a hash variable - invalid
+              false
+            end
+          end
+        end
+
+        def service_class?(node)
+          return false unless node
+
+          class_name = extract_class_name(node)
+          return false unless class_name
+
+          pattern = cop_config["ServicePattern"]
+          return true if pattern.nil? || pattern.empty?
+
+          class_name.match?(Regexp.new(pattern))
+        end
+
+        def extract_class_name(node)
+          case node.type
+          when :const
+            node.const_name
+          when :send
+            # For chained constants like User::Create or method calls
+            node.source
+          end
+        end
+      end
+    end
+  end
+end