light-services 3.1.2 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c9112f92c81696cc02f0d3440b848abca3a501f503b9bf95e645296d0a122dc
-  data.tar.gz: 22c0672f290fc82f843d55f31060941dceedae0a991eb25697010ffd12b5fae9
+  metadata.gz: c2d31f74eaaa7add84302e90f4d2748c5c099f34ea44e1be0d8eb6faa286ec37
+  data.tar.gz: 7bb83450e6be42ab27938df758644820476138684712f7d015694b4d1f675d92
 SHA512:
-  metadata.gz: 4b851d34f2c6a89a63a2d2f747db12b75f50741aabcbb3cbda4d8154a1ba65560894c2cabe4ac94f7f50f4ffc8fcdeb6280b83aa61a53888f76dd691c3cf1770
-  data.tar.gz: 1e2ca16aaf58aee4d8adcda2d83ea881761a3f1c09543461edf5ad2516d91ee76b639eae20477c66c94619437b51a7e717932d5cc9750d18a0d6b2bd9e0e4036
+  metadata.gz: e2cf4be4b70f330c77d53b104b4f4c36686a6a1aaeba1cee0478d25941c06c5ff7e31d9bc0d4998710dd8a4b811e06f39794d54b9102663480d5d32adfbca45a
+  data.tar.gz: 56134a214344e9a3c7448b4cca8becdb05d03df864962faa5c1f9412cf65ce774a5245ac1a5eda2127e86bdc5b41d01a5ab2893109b401d8259f3dc704420220

data/.cursor/rules/services/RULE.md

@@ -0,0 +1,265 @@
+---
+description: "Rules for managing Light Services - Ruby service objects with arguments, steps, and outputs"
+globs: "**/services/**/*.rb"
+alwaysApply: false
+---
+
+# Light Services Creation Rules
+
+When creating or modifying services that inherit from `Light::Services::Base` or `ApplicationService`, follow these patterns.
+
+## Service Structure
+
+Always structure services in this order:
+1. Configuration (`config`) if needed
+2. Arguments (`arg`)
+3. Steps (`step`)
+4. Outputs (`output`)
+5. Private methods implementing steps
+
+```ruby
+class ModelName::ActionName < ApplicationService
+  # Arguments
+  arg :required_param, type: String
+  arg :optional_param, type: Integer, optional: true, default: 0
+
+  # Steps
+  step :validate
+  step :perform
+  step :cleanup, always: true
+
+  # Outputs
+  output :result, type: Hash
+
+  private
+
+  def validate
+    errors.add(:required_param, "can't be blank") if required_param.blank?
+  end
+
+  def perform
+    self.result = { success: true }
+  end
+
+  def cleanup
+    # Always runs
+  end
+end
+```
+
+## Naming Conventions
+
+- **Class name**: `ModelName::ActionVerb` (e.g., `User::Create`, `Order::Process`)
+- **File path**: `app/services/model_name/action_verb.rb`
+- **Step methods**: Use descriptive verbs (`validate`, `authorize`, `build_record`, `save`)
+
+## Arguments
+
+```ruby
+# Required with type
+arg :user_id, type: Integer
+
+# Optional with default
+arg :notify, type: [TrueClass, FalseClass], default: true
+
+# Context argument (auto-passed to child services)
+arg :current_user, type: User, optional: true, context: true
+
+# Multiple allowed types
+arg :id, type: [String, Integer]
+
+# Proc default (evaluated at runtime)
+arg :created_at, type: Time, default: -> { Time.current }
+```
+
+## Steps
+
+```ruby
+# Basic step
+step :process
+
+# Conditional execution
+step :send_email, if: :should_notify?
+step :skip_audit, unless: :production?
+
+# Always run (even after errors, unless stop! or stop_immediately! are called)
+step :cleanup, always: true
+
+# Insertion points (for inheritance)
+step :log_action, before: :save
+step :broadcast, after: :save
+```
+
+## Outputs
+
+```ruby
+# Required output
+output :user, type: User
+
+# Optional output
+output :metadata, type: Hash, optional: true
+
+# With default
+output :status, type: String, default: "completed"
+```
+
+## Error Handling
+
+```ruby
+# Add error (stops execution of next steps by default)
+errors.add(:email, "is invalid")
+
+# Add to base
+errors.add(:base, "Something went wrong")
+fail!("Something went wrong")  # Shorthand
+
+# Copy from ActiveRecord model
+errors.copy_from(user)
+
+# Stop next steps without error (commits transaction)
+stop!
+
+# Stop with rollback
+fail_immediately!("Critical error")
+```
+
+## Service Chaining
+
+```ruby
+# Run in same context (shared arguments, errors propagate, rollback propagate)
+ChildService.with(self).run(param: value)
+
+# Independent service (separate transaction)
+OtherService.run(param: value)
+```
+
+## Configuration
+
+```ruby
+config use_transactions: true      # Wrap in DB transaction (default)
+config raise_on_error: false       # Raise exception on error
+config break_on_error: true        # Stop on error (default)
+config rollback_on_error: true     # Rollback on error (default)
+```
+
+## Testing Pattern
+
+```ruby
+RSpec.describe ModelName::ActionName do
+  describe ".run" do
+    subject(:service) { described_class.run(params) }
+    let(:params) { { required_param: "value" } }
+
+    context "when successful" do
+      it { is_expected.to be_successful }
+      it { expect(service.result).to eq(expected) }
+    end
+
+    context "when validation fails" do
+      let(:params) { { required_param: "" } }
+
+      it { is_expected.to be_failed }
+      it { is_expected.to have_error_on(:required_param) }
+    end
+  end
+end
+```
+
+## Common Patterns
+
+### CRUD Create
+```ruby
+class User::Create < CreateRecordService
+  private
+
+  def entity_class
+    User
+  end
+
+  def filtered_params
+    params.slice(:name, :email, :role)
+  end
+end
+```
+
+### With Authorization
+```ruby
+step :authorize
+step :perform
+
+def authorize
+  fail!("Not authorized") unless current_user&.admin?
+end
+```
+
+### With Callbacks
+```ruby
+before_service_run :log_start
+after_service_run :log_finish
+on_service_failure :notify_error
+```
+
+## Using dry-types
+
+Light Services supports [dry-types](https://dry-rb.org/gems/dry-types) for advanced type validation and coercion.
+
+### Arguments with dry-types
+
+```ruby
+class User::Create < ApplicationService
+  # Strict types - must match exactly
+  arg :name, type: Types::Strict::String
+  
+  # Coercible types - automatically convert values
+  arg :age, type: Types::Coercible::Integer
+  
+  # Constrained types - add validation rules
+  arg :email, type: Types::String.constrained(format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i)
+  
+  # Enum types - restrict to specific values
+  arg :status, type: Types::String.enum("active", "inactive", "pending"), default: "pending"
+  
+  # Array types with element validation
+  arg :tags, type: Types::Array.of(Types::String), optional: true
+  
+  # Hash schemas with key transformation
+  arg :metadata, type: Types::Hash.schema(key: Types::String).with_key_transform(&:to_sym), optional: true
+end
+```
+
+### Outputs with dry-types
+
+```ruby
+class AI::Chat < ApplicationService
+  # Strict type validation
+  output :messages, type: Types::Strict::Array.of(Types::Hash)
+  
+  # Coercible types
+  output :total_tokens, type: Types::Coercible::Integer
+  
+  # Constrained types (must be >= 0)
+  output :cost, type: Types::Float.constrained(gteq: 0)
+end
+```
+
+### Coercion Behavior
+
+With coercible types, values are automatically converted:
+
+```ruby
+# String "25" is automatically converted to integer 25
+service = User::Create.run(name: "John", age: "25")
+service.age # => 25 (Integer, not String)
+```
+
+### Common dry-types Patterns
+
+| Type | Description |
+|------|-------------|
+| `Types::Strict::String` | Must be a String, no coercion |
+| `Types::Coercible::Integer` | Coerces to Integer (e.g., "25" → 25) |
+| `Types::String.optional` | String or nil |
+| `Types::String.enum("a", "b")` | Must be one of the listed values |
+| `Types::Array.of(Types::String)` | Array where all elements are Strings |
+| `Types::Hash.schema(key: Type)` | Hash with typed schema |
+| `Types::Float.constrained(gteq: 0)` | Float >= 0 |

data/.cursor/rules/services-rspec/RULE.md

@@ -0,0 +1,354 @@
+---
+description: "Rules for writing RSpec tests for Light Services - testing arguments, steps, outputs, and behavior"
+globs: "**/spec/services/*_spec.rb"
+alwaysApply: false
+---
+
+# Light Services RSpec Testing Rules
+
+When writing RSpec tests for services that inherit from `Light::Services::Base` or `ApplicationService`, follow these patterns.
+
+## Setup
+
+Add to `spec/spec_helper.rb` or `spec/rails_helper.rb`:
+
+```ruby
+require "light/services/rspec"
+```
+
+## Test Structure
+
+Always structure test files in this order:
+1. Describe block with service class
+2. DSL definition tests (arguments, outputs, steps)
+3. Behavior tests (`.run` scenarios)
+4. Edge cases and error handling
+
+```ruby
+# spec/services/model_name/action_name_spec.rb
+RSpec.describe ModelName::ActionName do
+  # DSL Definition Tests
+  describe "arguments" do
+    it { expect(described_class).to define_argument(:required_param).with_type(String) }
+    it { expect(described_class).to define_argument(:optional_param).with_type(Integer).optional.with_default(0) }
+  end
+
+  describe "outputs" do
+    it { expect(described_class).to define_output(:result).with_type(Hash) }
+  end
+
+  describe "steps" do
+    it { expect(described_class).to define_steps_in_order(:validate, :perform, :cleanup) }
+    it { expect(described_class).to define_step(:cleanup).with_always(true) }
+  end
+
+  # Behavior Tests
+  describe ".run" do
+    subject(:service) { described_class.run(params) }
+    let(:params) { { required_param: "value" } }
+
+    context "when successful" do
+      it { is_expected.to be_successful }
+      it { expect(service.result).to eq(expected_result) }
+    end
+
+    context "when validation fails" do
+      let(:params) { { required_param: "" } }
+      it { is_expected.to be_failed }
+      it { is_expected.to have_error_on(:required_param) }
+    end
+  end
+end
+```
+
+## Naming Conventions
+
+- **File path**: `spec/services/model_name/action_name_spec.rb`
+- **Describe block**: Use the service class name directly
+- **Context blocks**: Start with "when" or "with" to describe conditions
+- **It blocks**: Be specific about what is being tested
+
+## DSL Matchers
+
+### Arguments
+
+```ruby
+# Basic argument
+it { expect(described_class).to define_argument(:id) }
+
+# With type (single or multiple)
+it { expect(described_class).to define_argument(:id).with_type([String, Integer]) }
+
+# Optional with default
+it { expect(described_class).to define_argument(:status).optional.with_default("pending") }
+
+# Context argument
+it { expect(described_class).to define_argument(:current_user).with_context }
+```
+
+### Outputs
+
+```ruby
+# Basic output
+it { expect(described_class).to define_output(:user) }
+
+# With type
+it { expect(described_class).to define_output(:user).with_type(User) }
+
+# Optional with default
+it { expect(described_class).to define_output(:count).optional.with_default(0) }
+```
+
+### Steps
+
+```ruby
+# Basic step
+it { expect(described_class).to define_step(:validate) }
+
+# With always flag
+it { expect(described_class).to define_step(:cleanup).with_always(true) }
+
+# Conditional steps
+it { expect(described_class).to define_step(:notify).with_if(:should_notify?) }
+it { expect(described_class).to define_step(:skip_audit).with_unless(:production?) }
+
+# Multiple steps in order
+it { expect(described_class).to define_steps_in_order(:validate, :process, :save) }
+```
+
+## Behavior Testing
+
+### Success Cases
+
+```ruby
+describe ".run" do
+  subject(:service) { described_class.run(params) }
+  let(:params) { { name: "John", email: "john@example.com" } }
+
+  it { is_expected.to be_successful }
+  it { expect(service.user).to be_persisted }
+  it { expect(service.user.name).to eq("John") }
+end
+```
+
+### Failure Cases
+
+```ruby
+context "when validation fails" do
+  let(:params) { { name: "", email: "" } }
+
+  it { is_expected.to be_failed }
+  it { is_expected.to have_error_on(:name) }
+  it { is_expected.to have_error_on(:email).with_message("can't be blank") }
+  it { is_expected.to have_errors_on(:name, :email) }
+end
+```
+
+### Warnings
+
+```ruby
+it { expect(service.warnings?).to be true }
+it { is_expected.to have_warning_on(:format).with_message("format is deprecated") }
+```
+
+### run! vs run
+
+```ruby
+# .run returns failed service
+it { expect(described_class.run(amount: -100)).to be_failed }
+
+# .run! raises exception
+it { expect { described_class.run!(amount: -100) }.to raise_error(Light::Services::Error, /must be positive/) }
+```
+
+### Config Overrides
+
+```ruby
+# With raise_on_error
+expect { described_class.run({ invalid: true }, { raise_on_error: true }) }
+  .to raise_error(Light::Services::Error)
+
+# With use_transactions: false
+service = described_class.with(use_transactions: false).run(params)
+```
+
+## Database Testing
+
+```ruby
+# Record creation
+expect { described_class.run(params) }.to change(User, :count).by(1)
+expect(service.user).to be_persisted
+
+# Transaction rollback on failure
+allow_any_instance_of(ChildService).to receive(:perform) do |svc|
+  svc.errors.add(:base, "Simulated failure")
+end
+expect { described_class.run(params) }.not_to change(Order, :count)
+```
+
+## Service Chaining
+
+```ruby
+# Verify context sharing
+expect(ChildService).to receive(:with).and_call_original
+described_class.run(current_user: current_user, data: data)
+
+# Error propagation from child
+allow_any_instance_of(ChildService).to receive(:validate) { |svc| svc.fail!("Child error") }
+expect(described_class.run(current_user: current_user, data: data))
+  .to have_error_on(:base).with_message("Child error")
+```
+
+## Conditional Steps
+
+```ruby
+# When condition is true
+expect { described_class.run(send_notification: true, email: "x@example.com") }
+  .to have_enqueued_mail(UserMailer, :notification)
+
+# When condition is false
+expect { described_class.run(send_notification: false, email: "x@example.com") }
+  .not_to have_enqueued_mail(UserMailer, :notification)
+```
+
+## Early Exit (stop!)
+
+```ruby
+existing_user = create(:user, email: "exists@example.com")
+service = described_class.run(email: existing_user.email)
+
+expect { service }.not_to change(User, :count)
+expect(service.user).to eq(existing_user)
+expect(service).to be_successful
+expect(service.stopped?).to be true
+```
+
+## Argument Validation
+
+```ruby
+# Required argument nil
+expect { described_class.run(name: nil) }.to raise_error(Light::Services::ArgTypeError)
+
+# Wrong type
+expect { described_class.run(name: 123) }.to raise_error(Light::Services::ArgTypeError, /must be a String/)
+
+# Optional accepts nil
+expect(described_class.run(name: "John", nickname: nil)).to be_successful
+
+# Default values
+expect(described_class.run(name: "John").status).to eq("pending")
+```
+
+## External Services
+
+```ruby
+let(:stripe_client) { instance_double(Stripe::PaymentIntent, id: "pi_123") }
+
+before { allow(Stripe::PaymentIntent).to receive(:create).and_return(stripe_client) }
+
+it "processes payment" do
+  service = described_class.run(amount: 1000, card_token: "tok_visa")
+  expect(service).to be_successful
+  expect(service.payment_intent_id).to eq("pi_123")
+end
+
+context "when external fails" do
+  before { allow(Stripe::PaymentIntent).to receive(:create).and_raise(Stripe::CardError.new("Card declined", nil, nil)) }
+
+  it { expect(service).to be_failed }
+  it { expect(service).to have_error_on(:payment).with_message("Card declined") }
+end
+```
+
+## Optional Tracking
+
+### Step Execution
+
+```ruby
+# app/services/application_service.rb
+class ApplicationService < Light::Services::Base
+  output :executed_steps, type: Array, default: -> { [] }
+  after_step_run { |service, step| service.executed_steps << step }
+end
+```
+
+### Callback Tracking
+
+```ruby
+class ApplicationService < Light::Services::Base
+  output :callback_log, type: Array, default: -> { [] }
+  before_service_run { |s| s.callback_log << :before_service_run }
+  after_service_run  { |s| s.callback_log << :after_service_run }
+  on_service_success { |s| s.callback_log << :on_service_success }
+  on_service_failure { |s| s.callback_log << :on_service_failure }
+end
+```
+
+## Shared Examples
+
+### Create Service
+
+```ruby
+RSpec.shared_examples "a create service" do |model_class|
+  let(:valid_attributes) { attributes_for(model_class.name.underscore.to_sym) }
+  let(:current_user) { create(:user) }
+
+  it { expect { described_class.run(current_user: current_user, attributes: valid_attributes) }.to change(model_class, :count).by(1) }
+  it { expect(described_class.run(current_user: current_user, attributes: valid_attributes).record).to be_persisted }
+  it { expect(described_class.run(current_user: current_user, attributes: valid_attributes)).to be_successful }
+end
+```
+
+### Authorized Service
+
+```ruby
+RSpec.shared_examples "an authorized service" do
+  context "without current_user" do
+    let(:current_user) { nil }
+    it { is_expected.to be_failed }
+    it { is_expected.to have_error_on(:authorization) }
+  end
+
+  context "with unauthorized user" do
+    let(:current_user) { create(:user, role: :guest) }
+    it { is_expected.to be_failed }
+    it { is_expected.to have_error_on(:authorization) }
+  end
+end
+```
+
+## Test Helpers
+
+```ruby
+module ServiceHelpers
+  def expect_service_success(service)
+    expect(service).to be_successful, -> { "Expected success but got errors: #{service.errors.to_h}" }
+  end
+
+  def expect_service_failure(service, key = nil)
+    expect(service).to be_failed
+    expect(service.errors[key]).to be_present if key
+  end
+end
+
+RSpec.configure { |config| config.include ServiceHelpers, type: :service }
+```
+
+## Common Matchers Reference
+
+| Matcher | Description |
+|---------|-------------|
+| `be_successful` | Service completed without errors |
+| `be_failed` | Service has errors |
+| `have_error_on(:key)` | Has error on specific key |
+| `have_error_on(:key).with_message(msg)` | Error with specific message |
+| `have_errors_on(:key1, :key2)` | Has errors on multiple keys |
+| `have_warning_on(:key)` | Has warning on specific key |
+| `define_argument(:name)` | Service defines argument |
+| `define_output(:name)` | Service defines output |
+| `define_step(:name)` | Service defines step |
+| `define_steps(:a, :b, :c)` | Service defines all steps (any order) |
+| `define_steps_in_order(:a, :b, :c)` | Service defines steps in order |
+| `execute_step(:name)` | Step was executed (tracking required) |
+| `skip_step(:name)` | Step was skipped (tracking required) |
+| `trigger_callback(:name)` | Callback was triggered (tracking required) |

data/CHANGELOG.md

@@ -1,6 +1,24 @@
 # Changelog
 
-## 3.1.2 (2025-12-13)
+## 3.2.1 (2025-12-15)
+
+### Added
+
+- Add RuboCop cop `ReservedName`
+
+## 3.2.0 (2025-12-15)
+
+### Added
+
+- Add Cursor rules
+- Add `successful?` as an alias for `success?`
+- Add RuboCop cop `PreferFailMethod` to detect `errors.add(:base, "message")` and suggest using `fail!("message")` instead
+
+### Breaking changes
+
+- Service runs steps with `always: true` after `fail_immediately!` was called
+
+## 3.1.2 (2025-12-14)
 
 ### Added
 
@@ -10,7 +28,7 @@
 
 - Split `config.require_type` into `config.require_arg_type` and `config.require_output_type`
 
-## 3.1.1 (2025-12-13)
+## 3.1.1 (2025-12-14)
 
 ### Added
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    light-services (3.1.1)
+    light-services (3.2.1)
 
 GEM
   remote: https://rubygems.org/
@@ -33,7 +33,7 @@ GEM
     bigdecimal (3.3.1)
     codecov (0.6.0)
       simplecov (>= 0.15, < 0.22)
-    concurrent-ruby (1.3.5)
+    concurrent-ruby (1.3.6)
     connection_pool (2.5.5)
     database_cleaner-active_record (2.2.2)
       activerecord (>= 5.a)

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/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

@@ -325,8 +325,8 @@ class Payment::Process < ApplicationService
 end
 ```
 
-{% hint style="warning" %}
-`fail_immediately!` raises an internal exception to halt execution. Steps marked with `always: true` will NOT run when `fail_immediately!` is called.
+{% 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" %}

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.
       #
@@ -145,12 +146,12 @@ module Light
       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)
-        @stopped = true
         errors.add(:base, message, rollback: false)
         raise Light::Services::FailExecution
       end

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

@@ -46,7 +46,6 @@ module Light
           end
         rescue Light::Services::FailExecution
           # FailExecution bubbles out of transaction (causing rollback) but is caught here
-          # @stopped is already set by fail_immediately!
           nil
         end
 

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/cop/light_services/reserved_name.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../../../../../light/services/constants"
+
+module RuboCop
+  module Cop
+    module LightServices
+      # Ensures that `arg`, `step`, and `output` declarations do not use reserved names
+      # that would conflict with Light::Services methods.
+      #
+      # @example
+      #   # bad
+      #   arg :errors, type: Array
+      #   arg :outputs, type: Hash
+      #   step :call
+      #   output :success?, type: [TrueClass, FalseClass]
+      #
+      #   # good
+      #   arg :validation_errors, type: Array
+      #   arg :result_outputs, type: Hash
+      #   step :execute
+      #   output :succeeded, type: [TrueClass, FalseClass]
+      #
+      class ReservedName < Base
+        include RuboCop::Cop::RangeHelp
+
+        MSG = "`%<name>s` is a reserved name and cannot be used as %<field_type>s. " \
+              "It conflicts with Light::Services methods."
+
+        SEVERITY = :error
+
+        RESTRICT_ON_SEND = [:arg, :step, :output].freeze
+
+        FIELD_TYPE_NAMES = {
+          arg: "an argument",
+          step: "a step",
+          output: "an output",
+        }.freeze
+
+        # @!method dsl_call?(node)
+        def_node_matcher :dsl_call?, <<~PATTERN
+          (send nil? ${:arg :step :output} (sym $_) ...)
+        PATTERN
+
+        def on_send(node)
+          dsl_call?(node) do |method_name, name|
+            return unless Light::Services::ReservedNames::ALL.include?(name)
+
+            field_type = FIELD_TYPE_NAMES[method_name]
+            add_offense(node, message: format(MSG, name: name, field_type: field_type), severity: SEVERITY)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/light/services/rubocop.rb

@@ -9,4 +9,6 @@ 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/reserved_name"
 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.2"
+    VERSION = "3.2.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: light-services
 version: !ruby/object:Gem::Version
-  version: 3.1.2
+  version: 3.2.1
 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,8 @@ 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/reserved_name.rb
 - lib/light/services/rubocop/cop/light_services/step_method_exists.rb
 - lib/light/services/settings/field.rb
 - lib/light/services/settings/step.rb