light-services 3.0.0 → 3.1.1

data/lib/light/services/dsl/validation.rb

@@ -126,6 +126,36 @@ module Light
             # Check inherited steps
             (service_class.superclass.respond_to?(:steps) && service_class.superclass.steps.key?(name_sym))
         end
+
+        # Validate that the type option is provided when require_type is enabled
+        #
+        # @param name [Symbol] the field name
+        # @param field_type [Symbol] the type of field (:argument, :output)
+        # @param service_class [Class] the service class for error messages
+        # @param opts [Hash] the options hash to check for type
+        def self.validate_type_required!(name, field_type, service_class, opts)
+          return if opts.key?(:type)
+          return unless require_type_enabled?(service_class)
+
+          raise Light::Services::MissingTypeError,
+                "#{field_type.to_s.capitalize} `#{name}` in #{service_class} must have a type specified " \
+                "(require_type is enabled)"
+        end
+
+        # Check if require_type is enabled for the service class
+        def self.require_type_enabled?(service_class)
+          # Check class-level config in the inheritance chain, then fall back to global config
+          klass = service_class
+          while klass.respond_to?(:class_config)
+            class_config = klass.class_config
+
+            return class_config[:require_type] if class_config&.key?(:require_type)
+
+            klass = klass.superclass
+          end
+
+          Light::Services.config.require_type
+        end
       end
     end
   end

data/lib/light/services/exceptions.rb

@@ -2,14 +2,32 @@
 
 module Light
   module Services
+    # Base exception class for all Light::Services errors.
     class Error < StandardError; end
+
+    # Raised when an argument or output value doesn't match the expected type.
     class ArgTypeError < Error; end
+
+    # Raised when using a reserved name for an argument, output, or step.
     class ReservedNameError < Error; end
+
+    # Raised when a name is invalid (e.g., not a Symbol).
     class InvalidNameError < Error; end
+
+    # Raised when a service has no steps defined and no run method.
     class NoStepsError < Error; end
 
-    # Backwards compatibility aliases (deprecated)
+    # Raised when type is required but not specified for an argument or output.
+    class MissingTypeError < Error; end
+
+    # Control flow exception for stop_immediately!
+    # Not an error - used to halt execution gracefully.
+    class StopExecution < StandardError; end
+
+    # @deprecated Use {Error} instead
     NoStepError = Error
+
+    # @deprecated Use {Error} instead
     TwoConditions = Error
   end
 end

data/lib/light/services/message.rb

@@ -1,26 +1,51 @@
 # frozen_string_literal: true
 
-# This class stores errors and warnings
 module Light
   module Services
+    # Represents a single error or warning message.
+    #
+    # @example Creating a message
+    #   message = Message.new(:name, "can't be blank", break: true)
+    #   message.key    # => :name
+    #   message.text   # => "can't be blank"
+    #   message.break? # => true
     class Message
-      # Getters
-      attr_reader :key, :text
+      # @return [Symbol] the key/field this message belongs to
+      attr_reader :key
 
+      # @return [String] the message text
+      attr_reader :text
+
+      # Create a new message.
+      #
+      # @param key [Symbol] the key/field this message belongs to
+      # @param text [String] the message text
+      # @param opts [Hash] additional options
+      # @option opts [Boolean] :break whether to stop step execution
+      # @option opts [Boolean] :rollback whether to rollback the transaction
       def initialize(key, text, opts = {})
         @key = key
         @text = text
         @opts = opts
       end
 
+      # Check if this message should stop step execution.
+      #
+      # @return [Boolean] true if break option was set
       def break?
         @opts[:break]
       end
 
+      # Check if this message should trigger a transaction rollback.
+      #
+      # @return [Boolean] true if rollback option was set
       def rollback?
         @opts[:rollback]
       end
 
+      # Return the message text.
+      #
+      # @return [String] the message text
       def to_s
         text
       end

data/lib/light/services/messages.rb

@@ -1,25 +1,79 @@
 # frozen_string_literal: true
 
-# This class stores errors and warnings
 module Light
   module Services
+    # Collection of error or warning messages, organized by key.
+    #
+    # @example Adding and accessing errors
+    #   errors.add(:name, "can't be blank")
+    #   errors.add(:email, "is invalid")
+    #   errors[:name]  # => [#<Message key: :name, text: "can't be blank">]
+    #   errors.to_h    # => { name: ["can't be blank"], email: ["is invalid"] }
     class Messages
       extend Forwardable
 
+      # @!method [](key)
+      #   Get messages for a specific key.
+      #   @param key [Symbol] the key to look up
+      #   @return [Array<Message>, nil] array of messages or nil
+
+      # @!method any?
+      #   Check if there are any messages.
+      #   @return [Boolean] true if messages exist
+
+      # @!method empty?
+      #   Check if the collection is empty.
+      #   @return [Boolean] true if no messages
+
+      # @!method size
+      #   Get number of keys with messages.
+      #   @return [Integer] number of keys
+
+      # @!method keys
+      #   Get all keys with messages.
+      #   @return [Array<Symbol>] array of keys
+
+      # @!method key?(key)
+      #   Check if a key has messages.
+      #   @param key [Symbol] the key to check
+      #   @return [Boolean] true if key has messages
       def_delegators :@messages, :[], :any?, :empty?, :size, :keys, :values, :each, :each_with_index, :key?
       alias has_key? key?
 
+      # Initialize a new messages collection.
+      #
+      # @param config [Hash] configuration options
+      # @option config [Boolean] :break_on_add stop execution when message added
+      # @option config [Boolean] :raise_on_add raise exception when message added
+      # @option config [Boolean] :rollback_on_add rollback transaction when message added
       def initialize(config)
         @break = false
         @config = config
         @messages = {}
       end
 
-      # Returns total count of all messages across all keys
+      # Get total count of all messages across all keys.
+      #
+      # @return [Integer] total number of messages
       def count
         @messages.values.sum(&:size)
       end
 
+      # Add a message to the collection.
+      #
+      # @param key [Symbol] the key/field for this message
+      # @param texts [String, Array<String>, Message] the message text(s) to add
+      # @param opts [Hash] additional options
+      # @option opts [Boolean] :break override break behavior for this message
+      # @option opts [Boolean] :rollback override rollback behavior for this message
+      # @return [void]
+      # @raise [Error] if text is nil or empty
+      #
+      # @example Add a single error
+      #   errors.add(:name, "can't be blank")
+      #
+      # @example Add multiple errors
+      #   errors.add(:email, ["is invalid", "is already taken"])
       def add(key, texts, opts = {})
         raise Light::Services::Error, "Error must be a non-empty string" unless texts
 
@@ -39,10 +93,25 @@ module Light
         rollback!(opts.key?(:rollback) ? opts[:rollback] : message.rollback?) if !opts.key?(:last) || opts[:last]
       end
 
+      # Check if step execution should stop.
+      #
+      # @return [Boolean] true if a message triggered a break
       def break?
         @break
       end
 
+      # Copy messages from another source.
+      #
+      # @param entity [ActiveRecord::Base, Base, Hash, #each] source to copy from
+      # @param opts [Hash] options to pass to each added message
+      # @return [void]
+      # @raise [Error] if entity type is not supported
+      #
+      # @example Copy from ActiveRecord model
+      #   errors.copy_from(user) # copies user.errors
+      #
+      # @example Copy from another service
+      #   errors.copy_from(child_service)
       def copy_from(entity, opts = {})
         if defined?(ActiveRecord::Base) && entity.is_a?(ActiveRecord::Base)
           copy_from(entity.errors.messages, opts)
@@ -60,6 +129,9 @@ module Light
       end
       alias from_record copy_from
 
+      # Convert messages to a hash with string values.
+      #
+      # @return [Hash{Symbol => Array<String>}] messages as hash
       def to_h
         @messages.to_h.transform_values { |value| value.map(&:to_s) }
       end

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