light-services 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a45a0a0ba2e870c7188f55865004d697646da536e3cecb05b9b0eb30fda9651d
-  data.tar.gz: 4ad5df86f1a1ff129ac85f3f2ed1ecda11466d52c8639fbbfda410951e8dc8c5
+  metadata.gz: 14b80318915db3dc20bd40365dc9ad00160938bb6836c1cda14bfba5301c7d7a
+  data.tar.gz: 80515890786ed055972e5b52bbc6cdee8e79b85d4fa1227b217f4b746c9fb899
 SHA512:
-  metadata.gz: 75bbc704971352293401dfcfaf0191aceb3d19ebfd150ce4db1aac0140b4044ee65942ff205484379a7169342298a7164fb76f1fbbf1907d3bb33d99485d1b03
-  data.tar.gz: 231a847015fcabfa0373693c0f13ac31d2ea2d636aae355b5ec023838efd3a15ae0b4baba0d7604f3c8980272419078268d155cd9d5b4ca7ca9e22f976667c62
+  metadata.gz: 454b6f2cd8fdf8615bc29c6b69e16fe704a3b19abd8f7e48fbd1e848505038db013e41396399dd5caa721d7179ae1bc3a6a99989a3adfc0f6868e9fe49a63c85
+  data.tar.gz: 50dbf071f72a242c0c36daeb83db94db5826dca4e3e2bbe7a47f9c81006b4d2c2266731715e1948b6528df86633735839f6eee525abde302a76b7a046e484b72

data/.rubocop.yml

@@ -58,6 +58,9 @@ RSpec/MultipleDescribes:
 RSpec/MultipleExpectations:
   Max: 10
 
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
 RSpec/NestedGroups:
   Max: 5
 
@@ -101,4 +104,7 @@ Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: consistent_comma
 
 Style/WordArray:
-  EnforcedStyle: brackets
+  EnforcedStyle: brackets
+
+Style/NumericPredicate:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 3.1.0 (2025-12-13)
+
+### Breaking changes
+
+- Enforce arguments and output types by default. Add `config.require_type = false` to your config to disable this behavior.
+
+### Added
+
+- `stop!` and `stopped?` methods for early exit (renamed from `done!` and `done?`)
+- `stop_immediately!` method for immediate execution halt within the current step
+- `done!` and `done?` are deprecated, but remain available as aliases for backward compatibility
+- Ruby LSP support with step navigation and indexing
+- Rubocop cops `StepMethodExists`, `ConditionMethodExists`, `DslOrder`, `MissingPrivateKeyword`, `NoDirectInstantiation`, `ArgumentTypeRequired`, `OutputTypeRequired`, `DeprecatedMethods`
+- Comprehensive YARD documentation
+
 ## 3.0.0 (2025-12-12)
 
 ### Breaking changes

data/CLAUDE.md

@@ -93,7 +93,7 @@ class ExampleService < Light::Services::Base
   end
 
   def cleanup
-    # Runs regardless of errors/warnings, unless done! was called
+    # Runs regardless of errors/warnings, unless stop! was called
   end
 
   def should_process?

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    light-services (3.0.0)
+    light-services (3.1.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -36,15 +36,15 @@ rails generate light_services:install
 ```ruby
 class GreetService < Light::Services::Base
   # Arguments
-  arg :name
-  arg :age
+  arg :name, type: String
+  arg :age, type: Integer
 
   # Steps
   step :build_message
   step :send_message
 
   # Outputs
-  output :message
+  output :message, type: String
 
   private
 
@@ -58,14 +58,14 @@ class GreetService < Light::Services::Base
 end
 ```
 
-## Advanced Example
+## Advanced Example (with dry-types and conditions)
 
 ```ruby
 class User::ResetPassword < Light::Services::Base
-  # Arguments
-  arg :user, type: User, optional: true
-  arg :email, type: String, optional: true
-  arg :send_email, type: [TrueClass, FalseClass], default: true
+  # Arguments with dry-types for advanced validation and coercion
+  arg :user, type: Types.Instance(User), optional: true
+  arg :email, type: Types::Coercible::String, optional: true
+  arg :send_email, type: Types::Params::Bool, default: true
 
   # Steps
   step :validate
@@ -74,9 +74,9 @@ class User::ResetPassword < Light::Services::Base
   step :save_reset_token
   step :send_reset_email, if: :send_email?
 
-  # Outputs
-  output :user, type: User
-  output :reset_token, type: String
+  # Outputs with dry-types
+  output :user, type: Types.Instance(User)
+  output :reset_token, type: Types::Strict::String
 
   private
 

data/docs/arguments.md

@@ -55,6 +55,29 @@ class HappyBirthdayService < ApplicationService
 end
 ```
 
+### Type Enforcement (Enabled by Default)
+
+By default, all arguments must have a `type` option. This helps catch type-related bugs early and makes your services self-documenting.
+
+```ruby
+class MyService < ApplicationService
+  arg :name, type: String  # ✓ Valid
+  arg :age                 # ✗ Raises MissingTypeError
+end
+```
+
+To disable type enforcement for a specific service:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_type: false
+  
+  arg :name              # Allowed when require_type is disabled
+end
+```
+
+See the [Configuration documentation](configuration.md) for more details.
+
 ### dry-types Support
 
 Light Services supports [dry-types](https://dry-rb.org/gems/dry-types) for advanced type validation and coercion. When using dry-types, values are automatically coerced to the expected type.

data/docs/concepts.md

@@ -23,14 +23,14 @@ When you call `MyService.run(args)`, the following happens:
 │     │     - Run after_step_run / on_step_success          │ │
 │     │     - Skip if condition (if:/unless:) not met       │ │
 │     │     - Stop if errors.break? is true                 │ │
-│     │     - Stop if done! was called                      │ │
+│     │     - Stop if stop! was called                      │ │
 │     ├─────────────────────────────────────────────────────┤ │
 │     │  7. On error → Rollback transaction                 │ │
 │     │     On success → Commit transaction                 │ │
 │     └─────────────────────────────────────────────────────┘ │
 │  8. End around_service_run callback                          │
 ├─────────────────────────────────────────────────────────────┤
-│  9. Run steps marked with always: true (unless done! called) │
+│  9. Run steps marked with always: true (unless stop! called) │
 │ 10. Validate output types (if success)                       │
 │ 11. Copy errors/warnings to parent service (if in context)   │
 │ 12. Run after_service_run callback                           │

data/docs/configuration.md

@@ -8,6 +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
+
   # Transaction settings
   config.use_transactions = true        # Wrap each service in a database transaction
 
@@ -29,6 +32,7 @@ end
 
 | Option | Default | Description |
 |--------|---------|-------------|
+| `require_type` | `true` | Raises `Light::Services::MissingTypeError` when defining arguments or 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 |
@@ -138,6 +142,38 @@ class BackgroundTaskService < ApplicationService
 end
 ```
 
+### Type Enforcement (Enabled by Default)
+
+By default, all arguments and outputs must have a `type` option. This helps catch type-related bugs early and makes your services self-documenting.
+
+```ruby
+class User::Create < ApplicationService
+  arg :name, type: String        # ✓ Valid
+  arg :email                     # ✗ Raises MissingTypeError
+  output :user, type: User       # ✓ Valid
+  output :token                  # ✗ Raises MissingTypeError
+end
+```
+
+To disable type enforcement globally (not recommended):
+
+```ruby
+Light::Services.configure do |config|
+  config.require_type = false
+end
+```
+
+Or disable for specific services:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_type: false
+  
+  arg :data              # Allowed when require_type is disabled
+  output :result         # Allowed when require_type is disabled
+end
+```
+
 ## Disabling Transactions
 
 If you're not using ActiveRecord or want to manage transactions yourself:

data/docs/errors.md

@@ -201,10 +201,40 @@ Light Services defines several exception classes for different error scenarios:
 | Exception | Description |
 |-----------|-------------|
 | `Light::Services::Error` | Base exception class for all Light Services errors |
-| `Light::Services::ArgTypeError` | Raised when an argument type validation fails |
+| `Light::Services::ArgTypeError` | Raised when an argument or output type validation fails |
 | `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 |
+
+### 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.
+
+```ruby
+class MyService < ApplicationService
+  arg :name  # => raises Light::Services::MissingTypeError
+end
+```
+
+To fix this, add a `type` option to all arguments and outputs:
+
+```ruby
+class MyService < ApplicationService
+  arg :name, type: String
+  output :result, type: Hash
+end
+```
+
+If you need to disable type enforcement for legacy services, you can use the `config` method:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_type: false
+  
+  arg :data              # Allowed when require_type is disabled
+end
+```
 
 ### NoStepsError
 

data/docs/outputs.md

@@ -78,6 +78,29 @@ class AI::Chat < ApplicationService
 end
 ```
 
+### Type Enforcement (Enabled by Default)
+
+By default, all outputs must have a `type` option. This helps catch type-related bugs early and makes your services self-documenting.
+
+```ruby
+class MyService < ApplicationService
+  output :result, type: Hash  # ✓ Valid
+  output :data                # ✗ Raises MissingTypeError
+end
+```
+
+To disable type enforcement for a specific service:
+
+```ruby
+class LegacyService < ApplicationService
+  config require_type: false
+  
+  output :data             # Allowed when require_type is disabled
+end
+```
+
+See the [Configuration documentation](configuration.md) for more details.
+
 ### dry-types Support
 
 Outputs also support [dry-types](https://dry-rb.org/gems/dry-types) for advanced type validation and coercion.

data/docs/quickstart.md

@@ -74,7 +74,7 @@ class GreetService < ApplicationService
   step :greet
 
   # Outputs
-  output :greeted, default: false
+  output :greeted, type: [TrueClass, FalseClass], default: false
 
   private
 

data/docs/readme.md

@@ -13,6 +13,7 @@ Light Services is a simple yet powerful way to organize business logic in Ruby a
 - ⚠️ **Error Handling**: Collect errors from steps and handle them your way
 - 🔗 **Context**: Run multiple services sequentially within the same context
 - 🧪 **RSpec Matchers**: Built-in RSpec matchers for expressive service tests
+- 🔍 **RuboCop Integration**: Custom cops to enforce best practices at lint time
 - 🌐 **Framework Agnostic**: Compatible with Rails, Hanami, or any Ruby framework
 - 🧩 **Modularity**: Isolate and test your services with ease
 - ✅ **100% Test Coverage**: Thoroughly tested and reliable
@@ -23,15 +24,15 @@ Light Services is a simple yet powerful way to organize business logic in Ruby a
 ```ruby
 class GreetService < Light::Services::Base
   # Arguments
-  arg :name
-  arg :age
+  arg :name, type: String
+  arg :age, type: Integer
 
   # Steps
   step :build_message
   step :send_message
 
   # Outputs
-  output :message
+  output :message, type: String
 
   private
 
@@ -45,14 +46,14 @@ class GreetService < Light::Services::Base
 end
 ```
 
-## Advanced Example
+## Advanced Example (with dry-types and conditions)
 
 ```ruby
 class User::ResetPassword < Light::Services::Base
-  # Arguments
-  arg :user, type: User, optional: true
-  arg :email, type: String, optional: true
-  arg :send_email, type: [TrueClass, FalseClass], default: true
+  # Arguments with dry-types for advanced validation and coercion
+  arg :user, type: Types.Instance(User), optional: true
+  arg :email, type: Types::Coercible::String, optional: true
+  arg :send_email, type: Types::Params::Bool, default: true
 
   # Steps
   step :validate
@@ -61,9 +62,9 @@ class User::ResetPassword < Light::Services::Base
   step :save_reset_token
   step :send_reset_email, if: :send_email?
 
-  # Outputs
-  output :user, type: User
-  output :reset_token, type: String
+  # Outputs with dry-types
+  output :user, type: Types.Instance(User)
+  output :reset_token, type: Types::Strict::String
 
   private
 

data/docs/rubocop.md

@@ -0,0 +1,285 @@
+# RuboCop Integration
+
+Light Services provides custom RuboCop cops to help enforce best practices in your service definitions.
+
+## Setup
+
+Add this to your `.rubocop.yml`:
+
+```yaml
+require:
+  - light/services/rubocop
+```
+
+## Available Cops
+
+### LightServices/ArgumentTypeRequired
+
+Ensures all `arg` declarations include a `type:` option.
+
+```ruby
+# bad
+arg :user_id
+arg :params, default: {}
+
+# good
+arg :user_id, type: Integer
+arg :params, type: Hash, default: {}
+```
+
+### LightServices/OutputTypeRequired
+
+Ensures all `output` declarations include a `type:` option.
+
+```ruby
+# bad
+output :result
+output :data, optional: true
+
+# good
+output :result, type: Hash
+output :data, type: Hash, optional: true
+```
+
+### LightServices/StepMethodExists
+
+Ensures all `step` declarations have a corresponding method defined.
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :validate
+  step :process  # missing method
+
+  private
+
+  def validate; end
+end
+
+# good
+class MyService < ApplicationService
+  step :validate
+  step :process
+
+  private
+
+  def validate; end
+  def process; end
+end
+```
+
+**Configuration:** Use `ExcludedSteps` for inherited steps:
+
+```yaml
+LightServices/StepMethodExists:
+  ExcludedSteps:
+    - initialize_entity
+    - assign_attributes
+```
+
+### LightServices/ConditionMethodExists
+
+Ensures symbol conditions (`:if`, `:unless`) have corresponding methods defined.
+
+This cop automatically recognizes predicate methods generated by `arg` and `output` declarations (e.g., `arg :user` creates `user?`).
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :notify, if: :should_notify?  # missing method
+
+  private
+
+  def notify; end
+end
+
+# good - explicit method
+class MyService < ApplicationService
+  step :notify, if: :should_notify?
+
+  private
+
+  def notify; end
+  def should_notify?; true; end
+end
+
+# good - predicate from arg/output
+class MyService < ApplicationService
+  arg :user, type: User, optional: true
+
+  step :greet, if: :user?  # user? is auto-generated
+
+  private
+
+  def greet; end
+end
+```
+
+**Configuration:** Use `ExcludedMethods` for inherited condition methods:
+
+```yaml
+LightServices/ConditionMethodExists:
+  ExcludedMethods:
+    - admin?
+    - guest?
+```
+
+### LightServices/DslOrder
+
+Enforces consistent ordering of DSL declarations: `config` → `arg` → `step` → `output`
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :process
+  arg :name, type: String
+  config raise_on_error: true
+end
+
+# good
+class MyService < ApplicationService
+  config raise_on_error: true
+
+  arg :name, type: String
+
+  step :process
+
+  output :result, type: Hash
+end
+```
+
+### LightServices/MissingPrivateKeyword
+
+Ensures step methods are defined as private.
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :process
+
+  def process  # should be private
+    # implementation
+  end
+end
+
+# good
+class MyService < ApplicationService
+  step :process
+
+  private
+
+  def process
+    # implementation
+  end
+end
+```
+
+### LightServices/NoDirectInstantiation
+
+Prevents direct instantiation of service classes with `.new`.
+
+```ruby
+# bad
+UserService.new(name: "John")
+
+# good
+UserService.run(name: "John")
+UserService.run!(name: "John")
+UserService.call(name: "John")
+```
+
+**Configuration:** Customize the pattern for service class detection:
+
+```yaml
+LightServices/NoDirectInstantiation:
+  ServicePattern: 'Service$'  # default: matches classes ending with "Service"
+```
+
+### LightServices/DeprecatedMethods
+
+Detects deprecated `done!` and `done?` method calls and suggests using `stop!` and `stopped?` instead. Includes autocorrection.
+
+```ruby
+# bad
+class MyService < ApplicationService
+  step :process
+
+  private
+
+  def process
+    done! if condition_met?
+    return if done?
+  end
+end
+
+# good
+class MyService < ApplicationService
+  step :process
+
+  private
+
+  def process
+    stop! if condition_met?
+    return if stopped?
+  end
+end
+```
+
+**Configuration:** Customize the pattern for service class detection:
+
+```yaml
+LightServices/DeprecatedMethods:
+  ServicePattern: 'Service$'  # default: matches classes ending with "Service"
+```
+
+## Configuration
+
+Full configuration example:
+
+```yaml
+require:
+  - light/services/rubocop
+
+LightServices/ArgumentTypeRequired:
+  Enabled: true
+
+LightServices/OutputTypeRequired:
+  Enabled: true
+
+LightServices/StepMethodExists:
+  Enabled: true
+  ExcludedSteps: []
+
+LightServices/ConditionMethodExists:
+  Enabled: true
+  ExcludedMethods: []
+
+LightServices/DslOrder:
+  Enabled: true
+
+LightServices/MissingPrivateKeyword:
+  Enabled: true
+
+LightServices/NoDirectInstantiation:
+  Enabled: true
+  ServicePattern: 'Service$'
+
+LightServices/DeprecatedMethods:
+  Enabled: true
+  ServicePattern: 'Service$'
+```
+
+To disable a cop for specific files:
+
+```yaml
+LightServices/ArgumentTypeRequired:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+```
+
+## What's Next?
+
+Learn more about testing your services:
+
+[Next: Testing](testing.md)