operandi 5.0.0

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Ensures that all `output` declarations in Operandi include a `type:` option.
+      #
+      # @example
+      #   # bad
+      #   output :result
+      #   output :data, optional: true
+      #   output :count, default: 0
+      #
+      #   # good
+      #   output :result, type: Hash
+      #   output :data, type: Hash, optional: true
+      #   output :count, type: Integer, default: 0
+      #
+      class OutputTypeRequired < Base
+        MSG = "Output `%<name>s` must have a `type:` option."
+
+        RESTRICT_ON_SEND = [:output].freeze
+
+        # @!method output_call?(node)
+        def_node_matcher :output_call?, <<~PATTERN
+          (send nil? :output (sym $_) ...)
+        PATTERN
+
+        def on_send(node)
+          output_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)
+          # output :name (no options)
+          return false if node.arguments.size == 1
+
+          # output :name, type: Foo or output :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/prefer_fail_method.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Detects `errors.add(:base, "message")` and suggests using `fail!("message")` 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 `fail!` is a wrapper method
+      #   that calls `errors.add(:base, message)` internally.
+      #
+      # @example
+      #   # bad
+      #   class User::Create < ApplicationService
+      #     step :process
+      #
+      #     private
+      #
+      #     def process
+      #       errors.add(:base, "user is required")
+      #     end
+      #   end
+      #
+      #   # good
+      #   class User::Create < ApplicationService
+      #     step :process
+      #
+      #     private
+      #
+      #     def process
+      #       fail!("user is required")
+      #     end
+      #   end
+      #
+      class PreferFailMethod < Base
+        extend AutoCorrector
+
+        MSG = "Use `fail!(...)` instead of `errors.add(:base, ...)`."
+
+        def_node_matcher :errors_add_base?, <<~PATTERN
+          (send
+            (send nil? :errors) :add
+            (sym :base)
+            ...)
+        PATTERN
+
+        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 node.method_name == :add
+
+          return unless errors_add_base?(node)
+
+          # Only flag if there's a message argument after :base
+          # errors.add(:base) without a message is invalid Operandi syntax
+          message_args = node.arguments[1..]
+          return if message_args.empty?
+
+          add_offense(node, message: MSG) do |corrector|
+            autocorrect(corrector, node, message_args)
+          end
+        end
+
+        private
+
+        def autocorrect(corrector, node, message_args)
+          # Get the source code for all arguments after the :base symbol
+          args_source = message_args.map(&:source).join(", ")
+          replacement = "fail!(#{args_source})"
+
+          corrector.replace(node, replacement)
+        end
+
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Detects when `default: nil` is used instead of `optional: true`.
+      # Using `optional: true` is the preferred way to indicate an optional field
+      # with no default value.
+      #
+      # @safety
+      #   This cop is safe to autocorrect.
+      #
+      # @example
+      #   # bad
+      #   arg :user, type: User, default: nil
+      #   output :result, type: Hash, default: nil
+      #
+      #   # good
+      #   arg :user, type: User, optional: true
+      #   output :result, type: Hash, optional: true
+      #
+      #   # bad - redundant default: nil with optional: true
+      #   arg :user, type: User, optional: true, default: nil
+      #
+      #   # good
+      #   arg :user, type: User, optional: true
+      #
+      class PreferOptionalOverDefaultNil < Base
+        extend AutoCorrector
+
+        MSG = "Prefer `optional: true` over `default: nil` for `%<name>s`."
+        MSG_REDUNDANT = "`default: nil` is redundant when `optional: true` is specified for `%<name>s`."
+
+        RESTRICT_ON_SEND = [:arg, :output].freeze
+
+        # @!method field_call?(node)
+        def_node_matcher :field_call?, <<~PATTERN
+          (send nil? {:arg :output} (sym $_) ...)
+        PATTERN
+
+        def on_send(node)
+          field_call?(node) do |name|
+            default_nil_pair = find_default_nil_pair(node)
+            return unless default_nil_pair
+
+            optional_pair = find_optional_true_pair(node)
+
+            if optional_pair
+              # Both optional: true and default: nil - remove default: nil
+              add_offense(node, message: format(MSG_REDUNDANT, name: name)) do |corrector|
+                remove_hash_pair(corrector, node.arguments[1], default_nil_pair)
+              end
+            else
+              # Only default: nil - replace with optional: true
+              add_offense(node, message: format(MSG, name: name)) do |corrector|
+                corrector.replace(default_nil_pair.source_range, "optional: true")
+              end
+            end
+          end
+        end
+
+        private
+
+        def options_hash(node)
+          return nil if node.arguments.size == 1
+
+          opts = node.arguments[1]
+          opts if opts&.hash_type?
+        end
+
+        def find_default_nil_pair(node)
+          opts = options_hash(node)
+          return nil unless opts
+
+          opts.pairs.find { |pair| default_nil_pair?(pair) }
+        end
+
+        def default_nil_pair?(pair)
+          pair.key.sym_type? && pair.key.value == :default && pair.value.nil_type?
+        end
+
+        def find_optional_true_pair(node)
+          opts = options_hash(node)
+          return nil unless opts
+
+          opts.pairs.find { |pair| optional_true_pair?(pair) }
+        end
+
+        def optional_true_pair?(pair)
+          pair.key.sym_type? && pair.key.value == :optional && pair.value.true_type?
+        end
+
+        def remove_hash_pair(corrector, hash_node, pair_to_remove)
+          pairs = hash_node.pairs
+          pair_index = pairs.index(pair_to_remove)
+
+          if last_pair?(pairs, pair_index)
+            remove_last_pair(corrector, pairs, pair_index, pair_to_remove)
+          else
+            remove_non_last_pair(corrector, pairs, pair_index, pair_to_remove)
+          end
+        end
+
+        def last_pair?(pairs, pair_index)
+          pair_index == pairs.size - 1
+        end
+
+        def remove_last_pair(corrector, pairs, pair_index, pair_to_remove)
+          prev_pair = pairs[pair_index - 1]
+          corrector.remove(range_between(prev_pair.source_range.end_pos, pair_to_remove.source_range.end_pos))
+        end
+
+        def remove_non_last_pair(corrector, pairs, pair_index, pair_to_remove)
+          next_pair = pairs[pair_index + 1]
+          corrector.remove(range_between(pair_to_remove.source_range.begin_pos, next_pair.source_range.begin_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/redundant_optional.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Detects when `optional: true` is used together with `default:` option.
+      # Having a default value implies the argument/output is optional, making
+      # `optional: true` redundant.
+      #
+      # @safety
+      #   This cop is safe to autocorrect.
+      #
+      # @example
+      #   # bad
+      #   arg :name, type: String, optional: true, default: "guest"
+      #   output :count, type: Integer, optional: true, default: 0
+      #
+      #   # good
+      #   arg :name, type: String, default: "guest"
+      #   output :count, type: Integer, default: 0
+      #
+      class RedundantOptional < Base
+        extend AutoCorrector
+
+        MSG = "`optional: true` is redundant when `default:` is specified for `%<name>s`."
+
+        RESTRICT_ON_SEND = [:arg, :output].freeze
+
+        # @!method field_call?(node)
+        def_node_matcher :field_call?, <<~PATTERN
+          (send nil? {:arg :output} (sym $_) ...)
+        PATTERN
+
+        def on_send(node)
+          field_call?(node) do |name|
+            optional_pair = find_optional_true_pair(node)
+            return unless optional_pair && has_default_option?(node)
+
+            add_offense(node, message: format(MSG, name: name)) do |corrector|
+              remove_hash_pair(corrector, node.arguments[1], optional_pair)
+            end
+          end
+        end
+
+        private
+
+        def options_hash(node)
+          return nil if node.arguments.size == 1
+
+          opts = node.arguments[1]
+          opts if opts&.hash_type?
+        end
+
+        def find_optional_true_pair(node)
+          opts = options_hash(node)
+          return nil unless opts
+
+          opts.pairs.find { |pair| optional_true_pair?(pair) }
+        end
+
+        def optional_true_pair?(pair)
+          pair.key.sym_type? && pair.key.value == :optional && pair.value.true_type?
+        end
+
+        def has_default_option?(node)
+          opts = options_hash(node)
+          return false unless opts
+
+          opts.pairs.any? { |pair| pair.key.sym_type? && pair.key.value == :default }
+        end
+
+        def remove_hash_pair(corrector, hash_node, pair_to_remove)
+          pairs = hash_node.pairs
+          pair_index = pairs.index(pair_to_remove)
+
+          if last_pair?(pairs, pair_index)
+            remove_last_pair(corrector, pairs, pair_index, pair_to_remove)
+          else
+            remove_non_last_pair(corrector, pairs, pair_index, pair_to_remove)
+          end
+        end
+
+        def last_pair?(pairs, pair_index)
+          pair_index == pairs.size - 1
+        end
+
+        def remove_last_pair(corrector, pairs, pair_index, pair_to_remove)
+          prev_pair = pairs[pair_index - 1]
+          corrector.remove(range_between(prev_pair.source_range.end_pos, pair_to_remove.source_range.end_pos))
+        end
+
+        def remove_non_last_pair(corrector, pairs, pair_index, pair_to_remove)
+          next_pair = pairs[pair_index + 1]
+          corrector.remove(range_between(pair_to_remove.source_range.begin_pos, next_pair.source_range.begin_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/reserved_name.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../../../../operandi/constants"
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Ensures that `arg`, `step`, and `output` declarations do not use reserved names
+      # that would conflict with Operandi methods.
+      #
+      # @example
+      #   # bad
+      #   arg :errors, type: Array
+      #   arg :output, type: Hash
+      #   step :call
+      #   output :success?, type: [TrueClass, FalseClass]
+      #
+      #   # good
+      #   arg :validation_errors, type: Array
+      #   arg :result_output, type: Hash
+      #   step :execute
+      #   output :succeeded, type: [TrueClass, FalseClass]
+      #
+      class ReservedName < Base
+        include RuboCop::Cop::RangeHelp
+
+        MSG = "`%<name>s` is a reserved name and cannot be used as %<field_type>s. " \
+              "It conflicts with Operandi methods."
+
+        SEVERITY = :error
+
+        RESTRICT_ON_SEND = [:arg, :step, :output].freeze
+
+        FIELD_TYPE_NAMES = {
+          arg: "an argument",
+          step: "a step",
+          output: "an output",
+        }.freeze
+
+        # @!method dsl_call?(node)
+        def_node_matcher :dsl_call?, <<~PATTERN
+          (send nil? ${:arg :step :output} (sym $_) ...)
+        PATTERN
+
+        def on_send(node)
+          dsl_call?(node) do |method_name, name|
+            return unless ::Operandi::ReservedNames::ALL.include?(name)
+
+            field_type = FIELD_TYPE_NAMES[method_name]
+            add_offense(node, message: format(MSG, name: name, field_type: field_type), severity: SEVERITY)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Operandi
+      # Ensures that all `step` declarations have a corresponding method defined in the same class.
+      #
+      # Note: This cop only checks for methods defined in the same file/class. It cannot detect
+      # methods inherited from parent classes. Use `parent: true`, the `ExcludedSteps` option,
+      # or `rubocop:disable` comments for inherited steps.
+      #
+      # @example
+      #   # bad
+      #   class MyService < ApplicationService
+      #     step :validate
+      #     step :process
+      #
+      #     private
+      #
+      #     def validate
+      #       # only validate is defined, process is missing
+      #     end
+      #   end
+      #
+      #   # good
+      #   class MyService < ApplicationService
+      #     step :validate
+      #     step :process
+      #
+      #     private
+      #
+      #     def validate
+      #       # validation logic
+      #     end
+      #
+      #     def process
+      #       # processing logic
+      #     end
+      #   end
+      #
+      # @example parent: true - step method is defined in a parent class
+      #   # good - step method is inherited from the parent class
+      #   class User::Create < CreateService
+      #     step :initialize_entity, parent: true
+      #     step :assign_attributes, parent: true
+      #     step :send_welcome_email
+      #
+      #     private
+      #
+      #     def send_welcome_email
+      #       # only this method needs to be defined
+      #     end
+      #   end
+      #
+      # @example ExcludedSteps: ['initialize_entity', 'assign_attributes'] (default: [])
+      #   # good - these steps are excluded from checking
+      #   class User::Create < CreateService
+      #     step :initialize_entity
+      #     step :assign_attributes
+      #     step :send_welcome_email
+      #
+      #     private
+      #
+      #     def send_welcome_email
+      #       # only this method needs to be defined
+      #     end
+      #   end
+      #
+      class StepMethodExists < Base
+        MSG = "Step `%<name>s` has no corresponding method. " \
+              "For inherited steps, use `parent: true`, disable this line, or add to ExcludedSteps."
+
+        def on_class(_node)
+          @step_calls = []
+          @defined_methods = []
+        end
+
+        def on_send(node)
+          return unless step_call?(node)
+
+          step_name = node.arguments.first&.value
+          return unless step_name
+          return if parent_step?(node)
+
+          @step_calls ||= []
+          @step_calls << { name: step_name, node: node }
+        end
+
+        def on_def(node)
+          @defined_methods ||= []
+          @defined_methods << node.method_name
+        end
+
+        def after_class(_node)
+          return unless @step_calls&.any?
+
+          @step_calls.each do |step|
+            next if @defined_methods&.include?(step[:name])
+            next if excluded_step?(step[:name])
+
+            add_offense(step[:node], message: format(MSG, name: step[: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 parent_step?(node)
+          opts = node.arguments[1]
+          return false unless opts&.hash_type?
+
+          opts.pairs.any? do |pair|
+            pair.key.sym_type? && pair.key.value == :parent &&
+              pair.value.true_type?
+          end
+        end
+
+        def excluded_step?(step_name)
+          excluded_steps.include?(step_name.to_s)
+        end
+
+        def excluded_steps
+          cop_config.fetch("ExcludedSteps", [])
+        end
+      end
+    end
+  end
+end

data/lib/operandi/rubocop.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+# Inject default configuration
+default_config = File.expand_path("../../config/default.yml", __dir__)
+RuboCop::ConfigLoader.inject_defaults!(default_config)
+
+require_relative "rubocop/cop/operandi/argument_type_required"
+require_relative "rubocop/cop/operandi/condition_method_exists"
+require_relative "rubocop/cop/operandi/deprecated_accessors"
+require_relative "rubocop/cop/operandi/deprecated_methods"
+require_relative "rubocop/cop/operandi/dsl_order"
+require_relative "rubocop/cop/operandi/no_hash_argument"
+require_relative "rubocop/cop/operandi/missing_private_keyword"
+require_relative "rubocop/cop/operandi/no_direct_instantiation"
+require_relative "rubocop/cop/operandi/output_type_required"
+require_relative "rubocop/cop/operandi/prefer_optional_over_default_nil"
+require_relative "rubocop/cop/operandi/prefer_fail_method"
+require_relative "rubocop/cop/operandi/redundant_optional"
+require_relative "rubocop/cop/operandi/reserved_name"
+require_relative "rubocop/cop/operandi/step_method_exists"