light-services 3.1.1 → 3.2.0

data/docs/configuration.md

@@ -8,8 +8,9 @@ Configure Light Services globally using an initializer. For Rails applications,
 
 ```ruby
 Light::Services.configure do |config|
-# Type enforcement
-  config.require_type = true            # Require type option for all arguments and outputs
+  # Type enforcement
+  config.require_arg_type = true        # Require type option for all arguments
+  config.require_output_type = true     # Require type option for all outputs
 
   # Transaction settings
   config.use_transactions = true        # Wrap each service in a database transaction
@@ -32,7 +33,8 @@ end
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `require_type` | `true` | Raises `Light::Services::MissingTypeError` when defining arguments or outputs without a `type` option |
+| `require_arg_type` | `true` | Raises `Light::Services::MissingTypeError` when defining arguments without a `type` option |
+| `require_output_type` | `true` | Raises `Light::Services::MissingTypeError` when defining outputs without a `type` option |
 | `use_transactions` | `true` | Wraps service execution in `ActiveRecord::Base.transaction` |
 | `load_errors` | `true` | Propagates errors to parent service when using `.with(self)` |
 | `break_on_error` | `true` | Stops executing remaining steps when an error is added |
@@ -159,7 +161,8 @@ To disable type enforcement globally (not recommended):
 
 ```ruby
 Light::Services.configure do |config|
-  config.require_type = false
+  config.require_arg_type = false     # Disable for arguments
+  config.require_output_type = false  # Disable for outputs
 end
 ```
 
@@ -167,10 +170,22 @@ Or disable for specific services:
 
 ```ruby
 class LegacyService < ApplicationService
-  config require_type: false
+  config require_arg_type: false, require_output_type: false
   
-  arg :data              # Allowed when require_type is disabled
-  output :result         # Allowed when require_type is disabled
+  arg :data              # Allowed when require_arg_type is disabled
+  output :result         # Allowed when require_output_type is disabled
+end
+```
+
+You can also control them independently:
+
+```ruby
+class StrictInputService < ApplicationService
+  # Require types for arguments but not outputs
+  config require_arg_type: true, require_output_type: false
+  
+  arg :data, type: Hash  # Type required
+  output :result         # Type not required
 end
 ```
 

data/docs/errors.md

@@ -44,6 +44,24 @@ class ParsePage < ApplicationService
 end
 ```
 
+## Quick Error with `fail!`
+
+The `fail!` method is a shortcut for adding an error to the `:base` key:
+
+```ruby
+class ParsePage < ApplicationService
+  def validate
+    fail!("URL is required") if url.blank?
+  end
+end
+```
+
+This is equivalent to:
+
+```ruby
+errors.add(:base, "URL is required")
+```
+
 ## Reading Errors
 
 To check if a service has errors, you can use the `#failed?` method. You can also use methods like `errors.any?` to inspect errors.
@@ -205,11 +223,13 @@ Light Services defines several exception classes for different error scenarios:
 | `Light::Services::ReservedNameError` | Raised when using a reserved name for arguments, outputs, or steps |
 | `Light::Services::InvalidNameError` | Raised when using an invalid name format |
 | `Light::Services::NoStepsError` | Raised when a service has no steps defined and no `run` method |
-| `Light::Services::MissingTypeError` | Raised when defining an argument or output without a `type` option when `require_type` is enabled |
+| `Light::Services::MissingTypeError` | Raised when defining an argument or output without a `type` option when `require_arg_type` or `require_output_type` is enabled |
+| `Light::Services::StopExecution` | Control flow exception raised by `stop_immediately!` to halt execution without rollback |
+| `Light::Services::FailExecution` | Control flow exception raised by `fail_immediately!` to halt execution and rollback transactions |
 
 ### MissingTypeError
 
-This exception is raised when you define an argument or output without a `type` option. Since `require_type` is enabled by default, all arguments and outputs must have a type.
+This exception is raised when you define an argument or output without a `type` option. Since `require_arg_type` and `require_output_type` are enabled by default, all arguments and outputs must have a type.
 
 ```ruby
 class MyService < ApplicationService
@@ -230,9 +250,10 @@ If you need to disable type enforcement for legacy services, you can use the `co
 
 ```ruby
 class LegacyService < ApplicationService
-  config require_type: false
+  config require_arg_type: false, require_output_type: false
   
-  arg :data              # Allowed when require_type is disabled
+  arg :data              # Allowed when require_arg_type is disabled
+  output :result         # Allowed when require_output_type is disabled
 end
 ```
 

data/docs/generators.md

@@ -216,7 +216,7 @@ RSpec.describe User::Create do
   describe ".run" do
     it "creates a user" do
       service = described_class.run(...)
-      expect(service).to be_success
+      expect(service).to be_successful
     end
   end
 end

data/docs/outputs.md

@@ -89,13 +89,13 @@ class MyService < ApplicationService
 end
 ```
 
-To disable type enforcement for a specific service:
+To disable type enforcement for outputs in a specific service:
 
 ```ruby
 class LegacyService < ApplicationService
-  config require_type: false
+  config require_output_type: false
   
-  output :data             # Allowed when require_type is disabled
+  output :data             # Allowed when require_output_type is disabled
 end
 ```
 

data/docs/pundit-authorization.md

@@ -252,7 +252,7 @@ RSpec.describe Post::Update do
         attributes: { title: "New Title" }
       )
 
-      expect(service).to be_success
+      expect(service).to be_successful
       expect(post.reload.title).to eq("New Title")
     end
   end

data/docs/rubocop.md

@@ -232,6 +232,47 @@ LightServices/DeprecatedMethods:
   ServicePattern: 'Service$'  # default: matches classes ending with "Service"
 ```
 
+### LightServices/PreferFailMethod
+
+Detects `errors.add(:base, "message")` calls and suggests using the `fail!("message")` helper instead. Includes autocorrection.
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :process
+
+  private
+
+  def process
+    errors.add(:base, "user is required")
+    errors.add(:base, "invalid input", rollback: false)
+  end
+end
+
+# good
+class MyService < ApplicationService
+  step :process
+
+  private
+
+  def process
+    fail!("user is required")
+    fail!("invalid input", rollback: false)
+  end
+end
+```
+
+The cop only detects `errors.add(:base, ...)` calls. It does not flag `errors.add(:field_name, ...)` calls for specific fields, as those should not use `fail!`.
+
+**Configuration:** Customize the base service classes to check:
+
+```yaml
+LightServices/PreferFailMethod:
+  BaseServiceClasses:
+    - ApplicationService
+    - BaseCreator
+```
+
 ## Configuration
 
 Full configuration example:
@@ -267,6 +308,11 @@ LightServices/NoDirectInstantiation:
 LightServices/DeprecatedMethods:
   Enabled: true
   ServicePattern: 'Service$'
+
+LightServices/PreferFailMethod:
+  Enabled: true
+  BaseServiceClasses:
+    - ApplicationService
 ```
 
 To disable a cop for specific files:

data/docs/steps.md

@@ -292,6 +292,58 @@ end
 **Database Transactions:** Calling `stop_immediately!` does NOT rollback database transactions. All database changes made before `stop_immediately!` was called will be committed.
 {% endhint %}
 
+## Immediate Failure with `fail_immediately!`
+
+Use `fail_immediately!` when you need to halt execution immediately AND rollback any database transactions. Unlike `stop_immediately!`, this method adds an error and causes transaction rollback.
+
+```ruby
+class Payment::Process < ApplicationService
+  arg :amount, type: Integer
+  arg :card_token, type: String
+
+  step :validate_card
+  step :charge_card
+  step :send_receipt
+
+  output :transaction_id, type: String
+
+  private
+
+  def validate_card
+    unless valid_card?(card_token)
+      fail_immediately!("Card validation failed")
+    end
+    
+    # This code won't run if card is invalid
+    log_validation_success
+  end
+
+  def charge_card
+    # This step won't run if fail_immediately! was called
+    self.transaction_id = PaymentGateway.charge(amount, card_token)
+  end
+end
+```
+
+{% hint style="info" %}
+`fail_immediately!` raises an internal exception to halt execution. Steps marked with `always: true` will still run when `fail_immediately!` is called, allowing for cleanup operations.
+{% endhint %}
+
+{% hint style="danger" %}
+**Database Transactions:** Calling `fail_immediately!` DOES rollback database transactions. All database changes made before `fail_immediately!` was called will be rolled back.
+{% endhint %}
+
+### Comparison Table
+
+| Method | Adds Error | Stops Execution | Transaction Rollback |
+|--------|------------|-----------------|---------------------|
+| `stop!` | No | After current step | No |
+| `stop_immediately!` | No | Immediately | No |
+| `fail!(msg)` | Yes (:base) | After current step* | No |
+| `fail_immediately!(msg)` | Yes (:base) | Immediately | Yes |
+
+*By default, adding an error stops subsequent steps from running due to `break_on_add` configuration.
+
 ## Removing Inherited Steps
 
 When inheriting from a parent service, you can remove steps using `remove_step`:

data/docs/testing.md

@@ -30,7 +30,7 @@ RSpec.describe GreetService do
     it "returns a greeting message" do
       service = described_class.run(name: "John")
 
-      expect(service).to be_success
+      expect(service).to be_successful
       expect(service.message).to eq("Hello, John!")
     end
   end
@@ -48,7 +48,7 @@ RSpec.describe User::Create do
       it "creates a user" do
         service = described_class.run(attributes: attributes)
 
-        expect(service).to be_success
+        expect(service).to be_successful
         expect(service.user).to be_persisted
         expect(service.user.email).to eq("test@example.com")
       end
@@ -86,7 +86,7 @@ RSpec.describe Comment::Create do
           text: "Great post!"
         )
 
-        expect(service).to be_success
+        expect(service).to be_successful
         expect(service.comment.user).to eq(current_user)
       end
     end
@@ -122,7 +122,7 @@ RSpec.describe Order::Create do
       items: [{ product_id: product.id, quantity: 2 }]
     )
 
-    expect(service).to be_success
+    expect(service).to be_successful
     expect(service.order.order_items.count).to eq(1)
     expect(service.order.total).to eq(200)
   end
@@ -252,7 +252,7 @@ RSpec.describe DataImport do
   it "completes with warnings for skipped records" do
     service = described_class.run(data: mixed_valid_invalid_data)
 
-    expect(service).to be_success # Warnings don't fail the service
+    expect(service).to be_successful # Warnings don't fail the service
     expect(service.warnings?).to be true
     expect(service.warnings[:skipped]).to include("Row 3: invalid format")
   end
@@ -273,7 +273,7 @@ RSpec.describe Payment::Charge do
   it "processes payment successfully" do
     service = described_class.run(amount: 1000, card_token: "tok_visa")
 
-    expect(service).to be_success
+    expect(service).to be_successful
     expect(service.payment_intent_id).to eq("pi_123")
   end
 
@@ -312,7 +312,7 @@ RSpec.describe MyService do
 
     it "accepts optional arguments as nil" do
       service = described_class.run(name: "John", nickname: nil)
-      expect(service).to be_success
+      expect(service).to be_successful
     end
   end
 end
@@ -353,7 +353,7 @@ Create a helper module for common service testing patterns:
 # spec/support/service_helpers.rb
 module ServiceHelpers
   def expect_service_success(service)
-    expect(service).to be_success, -> { "Expected success but got errors: #{service.errors.to_h}" }
+    expect(service).to be_successful, -> { "Expected success but got errors: #{service.errors.to_h}" }
   end
 
   def expect_service_failure(service, key = nil)

data/lib/generators/light_services/service/templates/service_spec.rb.tt

@@ -34,7 +34,7 @@ RSpec.describe <%= class_name %>, type: :service do
     let(:args) { {} }
 
     it "succeeds" do
-      expect(service).to be_success
+      expect(service).to be_successful
     end
   end
 end

data/lib/light/services/base.rb

@@ -89,6 +89,7 @@ module Light
       def success?
         !errors?
       end
+      alias successful? success?
 
       # Check if the service completed with errors.
       #
@@ -136,6 +137,25 @@ module Light
         raise Light::Services::StopExecution
       end
 
+      # Add an error to the :base key.
+      #
+      # @param message [String] the error message
+      # @return [void]
+      def fail!(message)
+        errors.add(:base, message)
+      end
+
+      # Add an error and stop execution immediately, causing transaction rollback.
+      # Steps marked with `always: true` will still run after this method is called.
+      #
+      # @param message [String] the error message
+      # @raise [FailExecution] always raises to halt execution and rollback
+      # @return [void]
+      def fail_immediately!(message)
+        errors.add(:base, message, rollback: false)
+        raise Light::Services::FailExecution
+      end
+
       # Execute the service steps.
       #
       # @return [void]

data/lib/light/services/concerns/execution.rb

@@ -44,6 +44,9 @@ module Light
             # Gracefully handle stop_immediately! inside transaction to prevent rollback
             @stopped = true
           end
+        rescue Light::Services::FailExecution
+          # FailExecution bubbles out of transaction (causing rollback) but is caught here
+          nil
         end
 
         # Run steps with parameter `always` if they weren't launched because of errors/warnings

data/lib/light/services/config.rb

@@ -10,7 +10,8 @@ module Light
       #
       # @example
       #   Light::Services.configure do |config|
-      #     config.require_type = true
+      #     config.require_arg_type = true
+      #     config.require_output_type = true
       #     config.use_transactions = false
       #   end
       def configure
@@ -28,13 +29,16 @@ module Light
     # Configuration class for Light::Services global settings.
     #
     # @example Accessing configuration
-    #   Light::Services.config.require_type # => true
+    #   Light::Services.config.require_arg_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 arguments must have a type specified
+      attr_reader :require_arg_type
+
+      # @return [Boolean] whether outputs must have a type specified
+      attr_reader :require_output_type
 
       # @return [Boolean] whether to wrap service execution in a database transaction
       attr_reader :use_transactions
@@ -69,7 +73,8 @@ module Light
       attr_reader :ruby_lsp_type_mappings
 
       DEFAULTS = {
-        require_type: true,
+        require_arg_type: true,
+        require_output_type: true,
         use_transactions: true,
 
         load_errors: true,
@@ -92,6 +97,16 @@ module Light
         end
       end
 
+      # Convenience setter for backward compatibility.
+      # Sets both require_arg_type and require_output_type.
+      #
+      # @param value [Boolean] whether to require types for arguments and outputs
+      # @return [void]
+      def require_type=(value)
+        self.require_arg_type = value
+        self.require_output_type = value
+      end
+
       # Initialize configuration with default values.
       def initialize
         reset_to_defaults!

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

@@ -135,26 +135,37 @@ module Light
         # @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)
+          return unless require_type_enabled_for?(field_type, service_class)
 
+          config_name = field_type == :argument ? "require_arg_type" : "require_output_type"
           raise Light::Services::MissingTypeError,
                 "#{field_type.to_s.capitalize} `#{name}` in #{service_class} must have a type specified " \
-                "(require_type is enabled)"
+                "(#{config_name} is enabled)"
         end
 
-        # Check if require_type is enabled for the service class
-        def self.require_type_enabled?(service_class)
+        # Check if require_type is enabled for the given field type and service class
+        #
+        # @param field_type [Symbol] the type of field (:argument, :output)
+        # @param service_class [Class] the service class to check
+        # @return [Boolean] whether type is required for the field type
+        def self.require_type_enabled_for?(field_type, service_class)
+          config_key = field_type == :argument ? :require_arg_type : :require_output_type
+
           # 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
 
+            # Check specific config first (require_arg_type or require_output_type)
+            return class_config[config_key] if class_config&.key?(config_key)
+
+            # Check convenience config (require_type) for backward compatibility
             return class_config[:require_type] if class_config&.key?(:require_type)
 
             klass = klass.superclass
           end
 
-          Light::Services.config.require_type
+          Light::Services.config.public_send(config_key)
         end
       end
     end

data/lib/light/services/exceptions.rb

@@ -24,6 +24,10 @@ module Light
     # Not an error - used to halt execution gracefully.
     class StopExecution < StandardError; end
 
+    # Control flow exception for fail_immediately!
+    # Unlike StopExecution, this exception causes transaction rollback.
+    class FailExecution < StandardError; end
+
     # @deprecated Use {Error} instead
     NoStepError = Error
 

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module LightServices
+      # Detects `errors.add(:base, "message")` and suggests using `fail!("message")` 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 `fail!` is a wrapper method
+      #   that calls `errors.add(:base, message)` internally.
+      #
+      # @example
+      #   # bad
+      #   class User::Create < ApplicationService
+      #     step :process
+      #
+      #     private
+      #
+      #     def process
+      #       errors.add(:base, "user is required")
+      #     end
+      #   end
+      #
+      #   # good
+      #   class User::Create < ApplicationService
+      #     step :process
+      #
+      #     private
+      #
+      #     def process
+      #       fail!("user is required")
+      #     end
+      #   end
+      #
+      class PreferFailMethod < Base
+        extend AutoCorrector
+
+        MSG = "Use `fail!(...)` instead of `errors.add(:base, ...)`."
+
+        def_node_matcher :errors_add_base?, <<~PATTERN
+          (send
+            (send nil? :errors) :add
+            (sym :base)
+            ...)
+        PATTERN
+
+        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 node.method_name == :add
+          return unless node.receiver&.method_name == :errors
+
+          return unless errors_add_base?(node)
+
+          # Only flag if there's a message argument after :base
+          # errors.add(:base) without a message is invalid Light Services syntax
+          message_args = node.arguments[1..]
+          return if message_args.empty?
+
+          add_offense(node, message: MSG) do |corrector|
+            autocorrect(corrector, node, message_args)
+          end
+        end
+
+        private
+
+        def autocorrect(corrector, node, message_args)
+          # Get the source code for all arguments after the :base symbol
+          args_source = message_args.map(&:source).join(", ")
+          replacement = "fail!(#{args_source})"
+
+          corrector.replace(node, replacement)
+        end
+
+        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
+      end
+    end
+  end
+end

data/lib/light/services/rubocop.rb

@@ -9,4 +9,5 @@ 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/prefer_fail_method"
 require_relative "rubocop/cop/light_services/step_method_exists"

data/lib/light/services/version.rb

@@ -2,6 +2,6 @@
 
 module Light
   module Services
-    VERSION = "3.1.1"
+    VERSION = "3.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: light-services
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.2.0
 platform: ruby
 authors:
 - Andrew Kodkod
@@ -17,6 +17,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".cursor/rules/services-rspec/RULE.md"
+- ".cursor/rules/services/RULE.md"
 - ".github/config/rubocop_linter_action.yml"
 - ".github/dependabot.yml"
 - ".github/workflows/ci.yml"
@@ -96,6 +98,7 @@ files:
 - lib/light/services/rubocop/cop/light_services/missing_private_keyword.rb
 - lib/light/services/rubocop/cop/light_services/no_direct_instantiation.rb
 - lib/light/services/rubocop/cop/light_services/output_type_required.rb
+- lib/light/services/rubocop/cop/light_services/prefer_fail_method.rb
 - lib/light/services/rubocop/cop/light_services/step_method_exists.rb
 - lib/light/services/settings/field.rb
 - lib/light/services/settings/step.rb