light-services 2.2.1 → 3.1.0

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+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
+        # @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
+          @field_type = opts.delete(:field_type) || :argument
+
+          @type = opts.delete(:type)
+          @context = opts.delete(:context)
+          @default_exists = opts.key?(:default)
+          @default = opts.delete(:default)
+          @optional = opts.delete(:optional)
+
+          define_methods
+        end
+
+        # 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
+
+          if dry_type?(@type)
+            coerce_and_validate_dry_type!(value)
+          else
+            validate_ruby_type!(value)
+            value
+          end
+        end
+
+        private
+
+        # Check if the type is a dry-types type
+        def dry_type?(type)
+          return false unless defined?(Dry::Types::Type)
+
+          type.is_a?(Dry::Types::Type)
+        end
+
+        # Validate and coerce value against dry-types
+        # Returns the coerced value
+        def coerce_and_validate_dry_type!(value)
+          @type[value]
+        rescue Dry::Types::ConstraintError, Dry::Types::CoercionError => e
+          raise Light::Services::ArgTypeError,
+                "#{@service_class} #{@field_type} `#{@name}` #{e.message}"
+        end
+
+        # Validate value against Ruby class types
+        def validate_ruby_type!(value)
+          return if [*@type].any? { |type| value.is_a?(type) }
+
+          raise Light::Services::ArgTypeError, type_error_message(value)
+        end
+
+        def type_error_message(value)
+          expected_types = [*@type].map(&:to_s).join(" or ")
+          "#{@service_class} #{@field_type} `#{@name}` must be #{expected_types}, \" \\
+            \"but got #{value.class} with value: #{value.inspect}"
+        end
+
+        def define_methods
+          name = @name
+          collection_instance_var = :"@#{@field_type}s"
+
+          @service_class.define_method(@name) { instance_variable_get(collection_instance_var).get(name) }
+          @service_class.define_method(:"#{@name}?") { !!instance_variable_get(collection_instance_var).get(name) }
+          @service_class.define_method(:"#{@name}=") do |value|
+            instance_variable_get(collection_instance_var).set(name, value)
+          end
+          @service_class.send(:private, "#{@name}=")
+        end
+      end
+
+      # Aliases for backwards compatibility
+      Argument = Field
+      Output = Field
+    end
+  end
+end

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

@@ -1,13 +1,26 @@
 # frozen_string_literal: true
 
-# This class defines settings for step
 module Light
   module Services
     module Settings
+      # Stores configuration for a single service step.
+      # Created automatically when using the `step` DSL method.
       class Step
-        # Getters
-        attr_reader :name, :always
+        # @return [Symbol] the step name (method to call)
+        attr_reader :name
 
+        # @return [Boolean, nil] true if step runs even after errors/warnings
+        attr_reader :always
+
+        # Initialize a new step definition.
+        #
+        # @param name [Symbol] the step name (must match a method)
+        # @param service_class [Class] the service class this step belongs to
+        # @param opts [Hash] step options
+        # @option opts [Symbol, Proc] :if condition to run the step
+        # @option opts [Symbol, Proc] :unless condition to skip the step
+        # @option opts [Boolean] :always run even after errors/warnings
+        # @raise [Error] if both :if and :unless are specified
         def initialize(name, service_class, opts = {})
           @name = name
           @service_class = service_class
@@ -17,35 +30,55 @@ module Light
           @always = opts[:always]
 
           if @if && @unless
-            raise Light::Services::TwoConditions, "#{service_class} `if` and `unless` cannot be specified " \
-                                                  "for the step `#{name}` at the same time"
+            raise Light::Services::Error, "#{service_class} `if` and `unless` cannot be specified " \
+                                          "for the step `#{name}` at the same time"
           end
         end
 
-        def run(instance, benchmark: false)
+        # Execute the step on the given service instance.
+        #
+        # @param instance [Base] the service instance
+        # @return [Boolean] true if the step was executed, false if skipped
+        # @raise [Error] if the step method is not defined
+        def run(instance) # rubocop:disable Naming/PredicateMethod
           return false unless run?(instance)
 
-          if instance.respond_to?(name, true)
-            if benchmark
-              time = Benchmark.ms do
-                instance.send(name)
-              end
+          unless instance.respond_to?(name, true)
+            available_steps = @service_class.steps.keys.join(", ")
+            raise Light::Services::Error,
+                  "Step method `#{name}` is not defined in #{@service_class}. " \
+                  "Defined steps: [#{available_steps}]"
+          end
 
-              instance.log "⏱️ Step #{name} took #{time}ms"
-            else
-              instance.send(name)
-            end
+          execute_with_callbacks(instance)
+          true
+        end
 
-            true
+        private
+
+        def execute_with_callbacks(instance)
+          errors_count_before = instance.errors.count
+
+          instance.run_callbacks(:before_step_run, instance, name)
+
+          instance.run_callbacks(:around_step_run, instance, name) do
+            instance.send(name)
+          end
+
+          instance.run_callbacks(:after_step_run, instance, name)
+
+          if instance.errors.count > errors_count_before
+            instance.run_callbacks(:on_step_failure, instance, name)
           else
-            raise Light::Services::NoStepError, "Cannot find step `#{name}` in service `#{@service_class}`"
+            instance.run_callbacks(:on_step_success, instance, name)
           end
+        rescue StandardError => e
+          instance.run_callbacks(:on_step_crash, instance, name, e)
+          raise e
         end
 
-        private
-
         def run?(instance)
-          return false if instance.done?
+          return false if instance.stopped?
 
           if @if
             check_condition(@if, instance)

data/lib/light/services/utils.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Light
+  module Services
+    # Utility module providing helper methods for the Light Services library
+    module Utils
+      module_function
+
+      # Creates a deep copy of an object to prevent mutation of shared references.
+      #
+      # @param object [Object] the object to duplicate
+      # @return [Object] a deep copy of the object
+      #
+      # @example Deep duping a hash
+      #   original = { a: { b: 1 } }
+      #   copy = Utils.deep_dup(original)
+      #   copy[:a][:b] = 2
+      #   original[:a][:b] # => 1
+      #
+      # @example Deep duping an array
+      #   original = [[1, 2], [3, 4]]
+      #   copy = Utils.deep_dup(original)
+      #   copy[0] << 5
+      #   original[0] # => [1, 2]
+      #
+      def deep_dup(object)
+        # Use ActiveSupport's deep_dup if available (preferred for Rails apps)
+        return object.deep_dup if object.respond_to?(:deep_dup)
+
+        # Fallback to Marshal for objects that support serialization
+        Marshal.load(Marshal.dump(object))
+      rescue TypeError
+        # Last resort: use dup if available, otherwise return original
+        object.respond_to?(:dup) ? object.dup : object
+      end
+    end
+  end
+end

data/lib/light/services/version.rb

@@ -2,6 +2,6 @@
 
 module Light
   module Services
-    VERSION = "2.2.1"
+    VERSION = "3.1.0"
   end
 end

data/lib/light/services.rb

@@ -3,6 +3,8 @@
 require "light/services/config"
 require "light/services/version"
 require "light/services/exceptions"
+require "light/services/utils"
+require "light/services/callbacks"
 require "light/services/base"
 
 module Light

data/lib/ruby_lsp/light_services/addon.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "indexing_enhancement"
+require_relative "definition"
+
+# Declare version compatibility without runtime dependency on ruby-lsp
+RubyLsp::Addon.depend_on_ruby_lsp!("~> 0.26")
+
+module RubyLsp
+  module LightServices
+    class Addon < ::RubyLsp::Addon
+      def activate(global_state, message_queue)
+        @global_state = global_state
+        @message_queue = message_queue
+      end
+
+      def deactivate; end
+
+      def name
+        "Ruby LSP Light Services"
+      end
+
+      def version
+        Light::Services::VERSION
+      end
+
+      # Called on every "go to definition" request
+      # Provides navigation from step DSL symbols to their method definitions
+      def create_definition_listener(response_builder, uri, node_context, dispatcher)
+        return unless @global_state
+
+        Definition.new(response_builder, uri, node_context, @global_state.index, dispatcher)
+      end
+    end
+  end
+end

data/lib/ruby_lsp/light_services/definition.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module RubyLsp
+  module LightServices
+    class Definition
+      # Condition options that reference methods
+      CONDITION_OPTIONS = [:if, :unless].freeze
+
+      def initialize(response_builder, uri, node_context, index, dispatcher)
+        @response_builder = response_builder
+        @uri = uri
+        @node_context = node_context
+        @index = index
+
+        # Register for symbol nodes - this is what gets triggered when user clicks on :method_name
+        dispatcher.register(self, :on_symbol_node_enter)
+      end
+
+      # Called when cursor is on a symbol node (e.g., :validate in `step :validate`)
+      def on_symbol_node_enter(node)
+        # Check if this symbol is part of a step call by examining the call context
+        call_node = find_parent_step_call
+        return unless call_node
+
+        method_name = determine_method_name(node, call_node)
+        return unless method_name
+
+        find_and_append_method_location(method_name)
+      end
+
+      private
+
+      # Find the parent step call node from the node context
+      # The node_context.call_node returns the enclosing call if cursor is on an argument
+      def find_parent_step_call
+        call_node = @node_context.call_node
+        return unless call_node
+        return unless call_node.name == :step
+
+        call_node
+      end
+
+      # Determine which method name to look up based on where the symbol appears
+      # Returns nil if this symbol is not a method reference we should handle
+      def determine_method_name(symbol_node, call_node)
+        symbol_value = symbol_node.value.to_sym
+
+        # Check if this is the first argument (step method name)
+        first_arg = call_node.arguments&.arguments&.first
+        if first_arg.is_a?(Prism::SymbolNode) && first_arg.value.to_sym == symbol_value && same_location?(first_arg,
+                                                                                                          symbol_node)
+          # Verify the symbol node location matches (same node, not just same value)
+          return symbol_value.to_s
+        end
+
+        # Check if this is a condition option (if: or unless:)
+        keyword_hash = find_keyword_hash(call_node)
+        return unless keyword_hash
+
+        CONDITION_OPTIONS.each do |option_name|
+          condition_symbol = find_symbol_option(keyword_hash, option_name)
+          next unless condition_symbol
+          next unless same_location?(condition_symbol, symbol_node)
+
+          return condition_symbol.value.to_s
+        end
+
+        nil
+      end
+
+      # Check if two nodes have the same location (are the same node)
+      def same_location?(node1, node2)
+        node1.location.start_offset == node2.location.start_offset &&
+          node1.location.end_offset == node2.location.end_offset
+      end
+
+      # Find the keyword hash in call arguments
+      def find_keyword_hash(node)
+        node.arguments&.arguments&.find { |arg| arg.is_a?(Prism::KeywordHashNode) }
+      end
+
+      # Find a symbol value for a specific option in the keyword hash
+      # Returns the SymbolNode if found and value is a symbol, nil otherwise
+      def find_symbol_option(keyword_hash, option_name)
+        element = keyword_hash.elements.find do |elem|
+          elem.is_a?(Prism::AssocNode) &&
+            elem.key.is_a?(Prism::SymbolNode) &&
+            elem.key.value.to_sym == option_name
+        end
+
+        return unless element
+        return unless element.value.is_a?(Prism::SymbolNode)
+
+        element.value
+      end
+
+      # Find method definition in index and append location to response
+      def find_and_append_method_location(method_name)
+        owner_name = @node_context.nesting.join("::")
+        return if owner_name.empty?
+
+        # Look up method entries in the index
+        method_entries = @index.resolve_method(method_name, owner_name)
+        return unless method_entries&.any?
+
+        method_entries.each { |entry| append_location(entry) }
+
+        true
+      end
+
+      def append_location(entry)
+        @response_builder << Interface::Location.new(
+          uri: URI::Generic.from_path(path: entry.file_path).to_s,
+          range: build_range(entry.location),
+        )
+      end
+
+      def build_range(location)
+        Interface::Range.new(
+          start: Interface::Position.new(
+            line: location.start_line - 1,
+            character: location.start_column,
+          ),
+          end: Interface::Position.new(
+            line: location.end_line - 1,
+            character: location.end_column,
+          ),
+        )
+      end
+    end
+  end
+end