light-services 2.2.1 → 3.1.0

data/lib/light/services/rubocop/cop/light_services/argument_type_required.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module LightServices
+      # Ensures that all `arg` declarations in Light::Services 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/light/services/rubocop/cop/light_services/condition_method_exists.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module LightServices
+      # 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

data/lib/light/services/rubocop/cop/light_services/deprecated_methods.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module LightServices
+      # Detects deprecated `done!` and `done?` method calls and suggests
+      # using `stop!` and `stopped?` instead.
+      #
+      # This cop checks calls inside service classes that inherit from
+      # Light::Services::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 Light::Services::Base inheritance
+          return true if parent_class_name == "Light::Services::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 Light::Services::Base
+            node.source
+          end
+        end
+
+        def self_receiver?(node)
+          node.receiver&.self_type?
+        end
+      end
+    end
+  end
+end

data/lib/light/services/rubocop/cop/light_services/dsl_order.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module LightServices
+      # 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)
+        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/light/services/rubocop/cop/light_services/missing_private_keyword.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module LightServices
+      # 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/light/services/rubocop/cop/light_services/no_direct_instantiation.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module LightServices
+      # 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