light-services 3.0.0 → 3.1.0

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

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

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

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+require_relative "rubocop/cop/light_services/argument_type_required"
+require_relative "rubocop/cop/light_services/condition_method_exists"
+require_relative "rubocop/cop/light_services/deprecated_methods"
+require_relative "rubocop/cop/light_services/dsl_order"
+require_relative "rubocop/cop/light_services/missing_private_keyword"
+require_relative "rubocop/cop/light_services/no_direct_instantiation"
+require_relative "rubocop/cop/light_services/output_type_required"
+require_relative "rubocop/cop/light_services/step_method_exists"

data/lib/light/services/settings/field.rb

@@ -1,12 +1,36 @@
 # frozen_string_literal: true
 
-# Unified settings class for arguments and outputs
 module Light
   module Services
     module Settings
+      # Stores configuration for a single argument or output field.
+      # Created automatically when using the `arg` or `output` DSL methods.
       class Field
-        attr_reader :name, :default_exists, :default, :context, :optional
-
+        # @return [Symbol] the field name
+        attr_reader :name
+
+        # @return [Boolean] true if a default value was specified
+        attr_reader :default_exists
+
+        # @return [Object, Proc, nil] the default value or proc
+        attr_reader :default
+
+        # @return [Boolean, nil] true if this is a context argument
+        attr_reader :context
+
+        # @return [Boolean, nil] true if nil values are allowed
+        attr_reader :optional
+
+        # Initialize a new field definition.
+        #
+        # @param name [Symbol] the field name
+        # @param service_class [Class] the service class this field belongs to
+        # @param opts [Hash] field options
+        # @option opts [Class, Array<Class>] :type type(s) to validate against
+        # @option opts [Boolean] :optional whether nil is allowed
+        # @option opts [Object, Proc] :default default value or proc
+        # @option opts [Boolean] :context whether to pass to child services
+        # @option opts [Symbol] :field_type :argument or :output
         def initialize(name, service_class, opts = {})
           @name = name
           @service_class = service_class
@@ -21,8 +45,12 @@ module Light
           define_methods
         end
 
-        # Validate and optionally coerce the value
-        # Returns the (possibly coerced) value
+        # Validate a value against the field's type definition.
+        # Supports both Ruby class types and dry-types.
+        #
+        # @param value [Object] the value to validate
+        # @return [Object] the value (possibly coerced by dry-types)
+        # @raise [ArgTypeError] if the value doesn't match the expected type
         def validate_type!(value)
           return value unless @type