light-services 3.0.0 → 3.1.0

data/lib/light/services/config.rb

@@ -3,17 +3,73 @@
 module Light
   module Services
     class << self
+      # Configure Light::Services with a block.
+      #
+      # @yield [Config] the configuration object
+      # @return [void]
+      #
+      # @example
+      #   Light::Services.configure do |config|
+      #     config.require_type = true
+      #     config.use_transactions = false
+      #   end
       def configure
         yield config
       end
 
+      # Get the global configuration object.
+      #
+      # @return [Config] the configuration instance
       def config
         @config ||= Config.new
       end
     end
 
+    # Configuration class for Light::Services global settings.
+    #
+    # @example Accessing configuration
+    #   Light::Services.config.require_type # => true
+    #
+    # @example Modifying configuration
+    #   Light::Services.config.use_transactions = false
     class Config
+      # @return [Boolean] whether arguments and outputs must have a type specified
+      attr_reader :require_type
+
+      # @return [Boolean] whether to wrap service execution in a database transaction
+      attr_reader :use_transactions
+
+      # @return [Boolean] whether to copy errors to parent service in chain
+      attr_reader :load_errors
+
+      # @return [Boolean] whether to stop executing steps when an error is added
+      attr_reader :break_on_error
+
+      # @return [Boolean] whether to raise Light::Services::Error when service fails
+      attr_reader :raise_on_error
+
+      # @return [Boolean] whether to rollback the transaction when an error is added
+      attr_reader :rollback_on_error
+
+      # @return [Boolean] whether to copy warnings to parent service in chain
+      attr_reader :load_warnings
+
+      # @return [Boolean] whether to stop executing steps when a warning is added
+      attr_reader :break_on_warning
+
+      # @return [Boolean] whether to raise Light::Services::Error when service has warnings
+      attr_reader :raise_on_warning
+
+      # @return [Boolean] whether to rollback the transaction when a warning is added
+      attr_reader :rollback_on_warning
+
+      # @return [Hash{String => String}] custom type mappings for Ruby LSP addon.
+      #   Maps dry-types or custom types to Ruby types for hover/completion.
+      #   @example { "Types::UUID" => "String", "CustomTypes::Money" => "BigDecimal" }
+      attr_reader :ruby_lsp_type_mappings
+
       DEFAULTS = {
+        require_type: true,
         use_transactions: true,
 
         load_errors: true,
@@ -25,22 +81,46 @@ module Light
         break_on_warning: false,
         raise_on_warning: false,
         rollback_on_warning: false,
+
+        ruby_lsp_type_mappings: {}.freeze,
       }.freeze
 
-      attr_accessor(*DEFAULTS.keys)
+      DEFAULTS.each_key do |name|
+        define_method(:"#{name}=") do |value|
+          instance_variable_set(:"@#{name}", value)
+          @to_h = nil # Invalidate memoized hash
+        end
+      end
 
+      # Initialize configuration with default values.
       def initialize
         reset_to_defaults!
       end
 
+      # Reset all configuration options to their default values.
+      #
+      # @return [void]
       def reset_to_defaults!
-        DEFAULTS.each { |key, value| public_send(:"#{key}=", value) }
+        DEFAULTS.each do |key, value|
+          instance_variable_set(:"@#{key}", value)
+        end
+
+        @to_h = nil # Invalidate memoized hash
       end
 
+      # Convert configuration to a hash.
+      #
+      # @return [Hash{Symbol => Object}] all configuration options as a hash
       def to_h
-        DEFAULTS.keys.to_h { |key| [key, public_send(key)] }
+        @to_h ||= DEFAULTS.keys.to_h do |key|
+          [key, public_send(key)]
+        end
       end
 
+      # Merge configuration with additional options.
+      #
+      # @param config [Hash] options to merge
+      # @return [Hash] merged configuration hash
       def merge(config)
         to_h.merge(config)
       end

data/lib/light/services/constants.rb

@@ -31,6 +31,9 @@ module Light
         :failed?,
         :errors?,
         :warnings?,
+        :stop!,
+        :stopped?,
+        :stop_immediately!,
         :done!,
         :done?,
         :call,

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

@@ -41,6 +41,7 @@ module Light
             Validation.validate_symbol_name!(name, :argument, self)
             Validation.validate_reserved_name!(name, :argument, self)
             Validation.validate_name_conflicts!(name, :argument, self)
+            Validation.validate_type_required!(name, :argument, self, opts)
 
             own_arguments[name] = Settings::Field.new(name, self, opts.merge(field_type: FieldTypes::ARGUMENT))
             @arguments = nil # Clear memoized arguments since we're modifying them

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

@@ -37,6 +37,7 @@ module Light
             Validation.validate_symbol_name!(name, :output, self)
             Validation.validate_reserved_name!(name, :output, self)
             Validation.validate_name_conflicts!(name, :output, self)
+            Validation.validate_type_required!(name, :output, self, opts)
 
             own_outputs[name] = Settings::Field.new(name, self, opts.merge(field_type: FieldTypes::OUTPUT))
             @outputs = nil # Clear memoized outputs since we're modifying them

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