operandi 5.0.0

data/docs/rubocop.md

@@ -0,0 +1,430 @@
+# RuboCop Integration
+
+Operandi provides custom RuboCop cops to help enforce best practices in your service definitions.
+
+## Setup
+
+Add this to your `.rubocop.yml`:
+
+```yaml
+require:
+  - operandi/rubocop
+```
+
+## Available Cops
+
+### Operandi/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: {}
+```
+
+### Operandi/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
+```
+
+### Operandi/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
+Operandi/StepMethodExists:
+  ExcludedSteps:
+    - initialize_entity
+    - assign_attributes
+```
+
+### Operandi/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
+Operandi/ConditionMethodExists:
+  ExcludedMethods:
+    - admin?
+    - guest?
+```
+
+### Operandi/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
+```
+
+### Operandi/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
+```
+
+### Operandi/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
+Operandi/NoDirectInstantiation:
+  ServicePattern: 'Service$'  # default: matches classes ending with "Service"
+```
+
+### Operandi/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
+Operandi/DeprecatedMethods:
+  ServicePattern: 'Service$'  # default: matches classes ending with "Service"
+```
+
+### Operandi/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
+Operandi/PreferFailMethod:
+  BaseServiceClasses:
+    - ApplicationService
+    - BaseCreator
+```
+
+### Operandi/PreferOptionalOverDefaultNil
+
+Detects `default: nil` usage and suggests using `optional: true` instead. Includes autocorrection.
+
+```ruby
+# bad
+class MyService < ApplicationService
+  arg :user, type: User, default: nil
+  output :result, type: Hash, default: nil
+end
+
+# good
+class MyService < ApplicationService
+  arg :user, type: User, optional: true
+  output :result, type: Hash, optional: true
+end
+
+# bad - redundant default: nil
+class MyService < ApplicationService
+  arg :user, type: User, optional: true, default: nil
+end
+
+# good
+class MyService < ApplicationService
+  arg :user, type: User, optional: true
+end
+```
+
+### Operandi/RedundantOptional
+
+Detects redundant `optional: true` when a `default:` value is provided. Includes autocorrection.
+
+```ruby
+# bad
+class MyService < ApplicationService
+  arg :name, type: String, optional: true, default: "guest"
+end
+
+# good
+class MyService < ApplicationService
+  arg :name, type: String, default: "guest"
+end
+```
+
+### Operandi/ReservedName
+
+Detects reserved argument and output names that conflict with Operandi internals.
+
+```ruby
+# bad
+class MyService < ApplicationService
+  arg :errors, type: Array
+  arg :warnings, type: Array
+  output :context, type: Hash
+end
+
+# good
+class MyService < ApplicationService
+  arg :validation_errors, type: Array
+  arg :user_warnings, type: Array
+  output :result_context, type: Hash
+end
+```
+
+### Operandi/NoHashArgument
+
+Detects hash arguments passed to `.run` or `.run!` instead of keyword arguments. Disabled by default.
+
+```ruby
+# bad
+UserService.run({ name: "John", age: 30 })
+UserService.run!(options)
+
+# good
+UserService.run(name: "John", age: 30)
+UserService.run!(**options)
+```
+
+**Configuration:** Customize the pattern for service class detection:
+
+```yaml
+Operandi/NoHashArgument:
+  Enabled: true
+  ServicePattern: 'Service$'  # default: matches classes ending with "Service"
+```
+
+## Configuration
+
+Full configuration example:
+
+```yaml
+require:
+  - operandi/rubocop
+
+Operandi/ArgumentTypeRequired:
+  Enabled: true
+
+Operandi/OutputTypeRequired:
+  Enabled: true
+
+Operandi/StepMethodExists:
+  Enabled: true
+  ExcludedSteps: []
+
+Operandi/ConditionMethodExists:
+  Enabled: true
+  ExcludedMethods: []
+
+Operandi/DslOrder:
+  Enabled: true
+
+Operandi/MissingPrivateKeyword:
+  Enabled: true
+
+Operandi/NoDirectInstantiation:
+  Enabled: true
+  ServicePattern: 'Service$'
+
+Operandi/DeprecatedMethods:
+  Enabled: true
+  ServicePattern: 'Service$'
+
+Operandi/PreferFailMethod:
+  Enabled: true
+  BaseServiceClasses:
+    - ApplicationService
+
+Operandi/PreferOptionalOverDefaultNil:
+  Enabled: true
+
+Operandi/RedundantOptional:
+  Enabled: true
+
+Operandi/ReservedName:
+  Enabled: true
+
+Operandi/NoHashArgument:
+  Enabled: false
+  ServicePattern: 'Service$'
+```
+
+To disable a cop for specific files:
+
+```yaml
+Operandi/ArgumentTypeRequired:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+```
+
+## What's Next?
+
+Learn more about testing your services:
+
+[Next: Testing](testing.md)

data/docs/ruby-lsp.md

@@ -0,0 +1,121 @@
+# Ruby LSP Integration
+
+Operandi provides a Ruby LSP add-on that enhances your editor experience by informing the language server about methods generated by the `arg` and `output` DSL keywords.
+
+## Features
+
+When you use the `arg` or `output` keywords, Operandi dynamically generates methods at runtime:
+
+```ruby
+class MyService < ApplicationService
+  arg :user, type: User
+  output :result, type: Hash
+end
+```
+
+This generates the following methods:
+- `user` - getter method (returns `User`)
+- `user?` - predicate method (returns boolean)
+- `user=` - setter method (private, accepts `User`)
+- `result` - getter method (returns `Hash`)
+- `result?` - predicate method (returns boolean)
+- `result=` - setter method (private, accepts `Hash`)
+
+The Ruby LSP add-on teaches the language server about these generated methods, enabling:
+
+- **Go to Definition** - Navigate to the `arg`/`output` declaration
+- **Completion** - Autocomplete generated method names
+- **Hover** - See information about generated methods, including return types
+- **Signature Help** - Get parameter hints for setter methods
+- **Workspace Symbol** - Find generated methods in symbol search
+
+## Setup
+
+The add-on is automatically discovered by Ruby LSP when Operandi is in your project's dependencies. No additional configuration is required.
+
+### Requirements
+
+- Ruby LSP `~> 0.26` or later
+- Operandi gem installed in your project
+
+### Verification
+
+To verify the add-on is loaded, check the Ruby LSP output in your editor. You should see "Ruby LSP Operandi" listed among the active add-ons.
+
+## How It Works
+
+The add-on uses Ruby LSP's **indexing enhancement** system to register generated methods during code indexing. When the indexer encounters an `arg` or `output` call with a symbol argument, it automatically registers the three generated methods (getter, predicate, setter) in the index.
+
+This is a static analysis approach - the add-on analyzes your source code without executing it. This means:
+
+- Methods are recognized immediately as you type
+- No running application is required
+- Works with any editor that supports Ruby LSP
+
+## Type Inference
+
+The add-on extracts type information from the `type:` option and includes it as YARD-style documentation comments. This enables hover information to display return types for generated methods.
+
+### Simple Ruby Types
+
+```ruby
+arg :user, type: User      # → User
+arg :items, type: Array    # → Array
+arg :name, type: String    # → String
+```
+
+### Namespaced Types
+
+```ruby
+arg :payment, type: Stripe::Charge      # → Stripe::Charge
+arg :config, type: MyApp::Configuration # → MyApp::Configuration
+```
+
+### Sorbet Runtime Types
+
+Sorbet runtime types are resolved to their underlying Ruby types:
+
+| Sorbet Type | Ruby Type |
+|-------------|-----------|
+| `T::Boolean` | `TrueClass \| FalseClass` |
+| `T.nilable(String)` | `String \| NilClass` |
+| `T::Array[String]` | `Array` |
+| `T::Hash[Symbol, String]` | `Hash` |
+| `T.any(String, Integer)` | `String \| Integer` |
+
+### Custom Type Mappings
+
+You can add custom type mappings through the Operandi configuration:
+
+```ruby
+# config/initializers/operandi.rb
+Operandi.configure do |config|
+  config.ruby_lsp_type_mappings = {
+    "Types::UUID" => "String",
+    "Types::Money" => "BigDecimal",
+    "Types::JSON" => "Hash",
+    "CustomTypes::Email" => "String",
+    "MyApp::Types::PhoneNumber" => "String",
+  }
+end
+```
+
+Custom mappings allow you to:
+
+- Add mappings for your own custom types
+- Override default mappings if needed
+- Support domain-specific type modules
+
+## Limitations
+
+- Only `arg` and `output` declarations with a symbol as the first argument are recognized
+- The add-on cannot detect dynamically computed argument names (e.g., `arg some_variable`)
+- Inherited arguments/outputs from parent classes are not automatically discovered
+- Parameterized types like `T::Array[String]` resolve to the container type (`Array`), not the full generic type
+
+## What's Next?
+
+Learn more about other integrations:
+
+- [RuboCop Integration](rubocop.md) - Static analysis cops for services
+- [Testing](testing.md) - Testing your services with RSpec matchers