operandi 5.0.0

data/.gitignore

@@ -0,0 +1,25 @@
+# Common
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.idea/
+
+# RSpec failure tracking
+.rspec_status
+
+# Ignore IDE files
+/.idea
+*.iml
+.vscode/settings.json
+
+# Ignore gem files
+*.gem
+
+# Ignore mac files
+*.DS_Store
+

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,134 @@
+plugins:
+  - rubocop-rake
+  - rubocop-rspec
+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 3.1
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+  NewCops: enable
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Layout/SpaceInsideArrayLiteralBrackets:
+  EnforcedStyle: no_space
+
+Layout/FirstMethodArgumentLineBreak:
+  Enabled: true
+  AllowMultilineFinalElement: true
+
+Layout/MultilineMethodArgumentLineBreaks:
+  Enabled: true
+  AllowMultilineFinalElement: true
+
+Layout/FirstMethodParameterLineBreak:
+  Enabled: true
+  AllowMultilineFinalElement: true
+
+Layout/MultilineMethodParameterLineBreaks:
+  Enabled: true
+  AllowMultilineFinalElement: true
+
+Layout/MultilineHashKeyLineBreaks:
+  Enabled: true
+  AllowMultilineFinalElement: true
+
+Layout/MultilineArrayLineBreaks:
+  Enabled: true
+  AllowMultilineFinalElement: true
+
+Lint/EmptyFile:
+  Enabled: true
+
+Metrics/AbcSize:
+  Exclude:
+    - lib/operandi/dsl/steps_dsl.rb
+    - lib/operandi/messages.rb
+  Max: 20
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*_spec.rb
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleDescribes:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Max: 10
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+RSpec/NestedGroups:
+  Max: 5
+
+Security/Eval:
+  Exclude:
+    - spec/operandi/error_spec.rb
+
+Style/ClassAndModuleChildren:
+  Exclude:
+    - spec/data/services/**/*.rb
+
+Style/ClassVars:
+  Enabled: false
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/OptionalBooleanParameter:
+  Exclude:
+    - lib/operandi/rspec/matchers/**/*.rb
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: diff_comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/WordArray:
+  EnforcedStyle: brackets
+
+Style/NumericPredicate:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+4.0.3

data/.vscode/cspell.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
+  "version": "0.2",
+  "dictionaryDefinitions": [
+    {
+      "name": "project-words",
+      "path": "./project-words.txt",
+      "addWords": true
+    }
+  ],
+  "dictionaries": [
+    "project-words"
+  ],
+  "ignorePaths": [
+    ".idea",
+    ".vscode"
+  ]
+}

data/.vscode/project-words.txt

@@ -0,0 +1,12 @@
+activerecord
+andrewmcodes
+bindir
+delegators
+Hanami
+IVAR
+Kodkod
+kwargs
+libsqlite
+nilable
+noreturn
+rubocop

data/AGENTS.md

@@ -0,0 +1,139 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## About Operandi
+
+Operandi is a Ruby gem providing a service architecture pattern for organizing business logic. Services are defined as classes with `arguments`, `steps`, and `outputs`, featuring transactions, inheritance, error handling, and context sharing.
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/path/to/file_spec.rb
+
+# Run with coverage (uses SimpleCov)
+bundle exec rspec
+```
+
+### Linting
+```bash
+# Run RuboCop linter
+bundle exec rubocop
+
+# Auto-fix RuboCop issues
+bundle exec rubocop -a
+```
+
+### Build and Release
+```bash
+# Build gem
+bundle exec rake build
+
+# Default task (runs tests)
+bundle exec rake
+```
+
+## Architecture
+
+### Core Components
+
+1. **Base Service (`lib/operandi/base.rb:15`)**
+   - Main service class that all services inherit from
+   - Handles service lifecycle: initialization, execution, callbacks, error management
+   - Provides DSL for defining arguments, steps, and outputs
+   - Manages transactions and error propagation to parent services
+
+2. **Callbacks System (`lib/operandi/callbacks.rb:5`)**
+   - Supports service and step-level callbacks
+   - Events: `before_service_run`, `after_service_run`, `around_service_run`, `on_service_success`, `on_service_failure`
+   - Step events: `before_step_run`, `after_step_run`, `around_step_run`, `on_step_success`, `on_step_failure`
+
+3. **Settings**
+   - **Step (`lib/operandi/settings/step.rb:7`)**: Handles step execution with conditional logic (`if`, `unless`, `always`)
+   - **Field (`lib/operandi/settings/field.rb`)**: Manages argument and output validation and type checking
+
+4. **Messages System (`lib/operandi/messages.rb`)**
+   - Collects errors and warnings with options for breaking, raising, or rolling back
+   - Supports copying messages between parent and child services
+
+5. **Collection (`lib/operandi/collection.rb`)**
+   - Manages arguments and outputs as collections with validation and defaults
+   - Supports Sorbet runtime types for type validation
+
+### Service DSL
+
+Services use a declarative DSL:
+```ruby
+class ExampleService < Operandi::Base
+  # Define input arguments
+  arg :name, type: String
+  arg :age, type: Integer, optional: true, default: 25
+
+  # Define execution steps
+  step :validate_input
+  step :process_data, if: :should_process?
+  step :cleanup, always: true
+
+  # Define outputs
+  output :result, type: Hash
+
+  private
+
+  def validate_input
+    errors.add(:name, "required") if name.nil? || name.strip.empty?
+  end
+
+  def process_data
+    self.result = { name: name, age: age }
+  end
+
+  def cleanup
+    # Runs regardless of errors/warnings, unless stop! was called
+  end
+
+  def should_process?
+    !(name.nil? || name.strip.empty?)
+  end
+end
+```
+
+### Service Execution
+
+- Services can be run with `.run(args)` or `.run!(args)` (raises on error)
+- Use `.with(service_or_context)` to chain services with shared context
+- Transactions automatically rollback on errors when `use_transactions: true`
+- Steps run sequentially, stopping on errors unless `always: true`
+
+### Error Handling
+
+- Errors collected in `@errors` message collection
+- Supports `break_on_error`, `raise_on_error`, `rollback_on_error` configuration
+- Warnings work similarly with `@warnings` collection
+- Parent services can inherit child errors/warnings based on configuration
+
+### Testing Patterns
+
+- Services are tested using RSpec with database transactions
+- Use `DatabaseCleaner` for test isolation
+- Mock database models and external dependencies
+- Test both success and failure scenarios
+- Validate arguments, outputs, and error conditions
+
+## Configuration
+
+### RuboCop Rules
+- Target Ruby version: 2.7+
+- Method length max: 20 lines
+- Uses double quotes for strings
+- Enables trailing commas for multiline structures
+- Disables documentation requirements and guard clauses
+
+### Database Support
+- Optional ActiveRecord integration for transactions
+- Uses SQLite3 for testing
+- Database cleaner ensures test isolation

data/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- Add `Operandi::RuntimeError` with access to the failed service instance
+- Add the associated service class to `Operandi::ArgTypeError`
+
+### Breaking changes
+
+- Remove deprecated methods: `done!`, `done?`, `arguments` and `outputs` methods
+
+## 4.0.0 (2026-01-01)
+
+### Added
+
+- Allow to specify `parent: true` for `step` to skip `StepMethodExists` Rubocop cop
+
+### Breaking changes
+
+- Rename gem from `light-services to `operandi`
+  Reason: No folder nesting. The gem isn't really "light" anymore anyway.
+
+- Removed dry-types support. Sorbet runtime types are now the recommended type system for advanced type validation. Plain Ruby class types continue to work as before.
+ 
+- The `run` and `run!` methods now accept only keyword arguments, passing a hash as the first argument is no longer supported.
+
+## 3.3.1 (2025-12-16)
+
+### Added
+
+- Sorbet runtime type support for `arg` and `output` (validation only, no coercion)
+
+## 3.3.0 (2025-12-15)
+
+### Added
+
+- Sorbet and Tapioca support for `arg` and `output`
+
+## 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
+
+- Add `fail!` and `fail_immediately!` helpers
+
+### Changed
+
+- Split `config.require_type` into `config.require_arg_type` and `config.require_output_type`
+
+## 3.1.1 (2025-12-14)
+
+### Added
+
+- Better IDE support for callbacks DSL
+
+## 3.1.0 (2025-12-13)
+
+### Breaking changes
+
+- Enforce arguments and output types by default. Use `config.require_arg_type = false` and `config.require_output_type = false` to disable this behavior. The convenience setter `config.require_type = false` sets both options at once for backward compatibility.
+
+### 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
+
+- Removed support for symbol types (e.g., `:array`, `:hash`, `:boolean`). Use Ruby classes (e.g., `Array`, `Hash`, `[TrueClass, FalseClass]`) or dry-types
+- Removed `benchmark: true` option
+- Removed `verbose: true` option
+- Bumped minimum supported Ruby version to **3.0**.
+- Removed `errors.copy_to`
+
+### Added
+
+- Output type validation
+- dry-types support for arguments and outputs (with coercion and constraints)
+- Callback system (service + step callbacks)
+- Built-in RSpec matchers for services
+- Name validation for arguments, steps, and outputs
+- `run` method fallback when no steps are defined
+
+### Documentation
+
+- Documentation moved into this repository and refreshed to match v3 behavior

data/CLAUDE.md

@@ -0,0 +1,139 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## About Operandi
+
+Operandi is a Ruby gem providing a service architecture pattern for organizing business logic. Services are defined as classes with `arguments`, `steps`, and `outputs`, featuring transactions, inheritance, error handling, and context sharing.
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/path/to/file_spec.rb
+
+# Run with coverage (uses SimpleCov)
+bundle exec rspec
+```
+
+### Linting
+```bash
+# Run RuboCop linter
+bundle exec rubocop
+
+# Auto-fix RuboCop issues
+bundle exec rubocop -a
+```
+
+### Build and Release
+```bash
+# Build gem
+bundle exec rake build
+
+# Default task (runs tests)
+bundle exec rake
+```
+
+## Architecture
+
+### Core Components
+
+1. **Base Service (`lib/operandi/base.rb:15`)**
+   - Main service class that all services inherit from
+   - Handles service lifecycle: initialization, execution, callbacks, error management
+   - Provides DSL for defining arguments, steps, and outputs
+   - Manages transactions and error propagation to parent services
+
+2. **Callbacks System (`lib/operandi/callbacks.rb:5`)**
+   - Supports service and step-level callbacks
+   - Events: `before_service_run`, `after_service_run`, `around_service_run`, `on_service_success`, `on_service_failure`
+   - Step events: `before_step_run`, `after_step_run`, `around_step_run`, `on_step_success`, `on_step_failure`
+
+3. **Settings**
+   - **Step (`lib/operandi/settings/step.rb:7`)**: Handles step execution with conditional logic (`if`, `unless`, `always`)
+   - **Field (`lib/operandi/settings/field.rb`)**: Manages argument and output validation and type checking
+
+4. **Messages System (`lib/operandi/messages.rb`)**
+   - Collects errors and warnings with options for breaking, raising, or rolling back
+   - Supports copying messages between parent and child services
+
+5. **Collection (`lib/operandi/collection.rb`)**
+   - Manages arguments and outputs as collections with validation and defaults
+   - Supports Sorbet runtime types for type validation
+
+### Service DSL
+
+Services use a declarative DSL:
+```ruby
+class ExampleService < Operandi::Base
+  # Define input arguments
+  arg :name, type: String
+  arg :age, type: Integer, optional: true, default: 25
+
+  # Define execution steps
+  step :validate_input
+  step :process_data, if: :should_process?
+  step :cleanup, always: true
+
+  # Define outputs
+  output :result, type: Hash
+
+  private
+
+  def validate_input
+    errors.add(:name, "required") if name.nil? || name.strip.empty?
+  end
+
+  def process_data
+    self.result = { name: name, age: age }
+  end
+
+  def cleanup
+    # Runs regardless of errors/warnings, unless stop! was called
+  end
+
+  def should_process?
+    !(name.nil? || name.strip.empty?)
+  end
+end
+```
+
+### Service Execution
+
+- Services can be run with `.run(args)` or `.run!(args)` (raises on error)
+- Use `.with(service_or_context)` to chain services with shared context
+- Transactions automatically rollback on errors when `use_transactions: true`
+- Steps run sequentially, stopping on errors unless `always: true`
+
+### Error Handling
+
+- Errors collected in `@errors` message collection
+- Supports `break_on_error`, `raise_on_error`, `rollback_on_error` configuration
+- Warnings work similarly with `@warnings` collection
+- Parent services can inherit child errors/warnings based on configuration
+
+### Testing Patterns
+
+- Services are tested using RSpec with database transactions
+- Use `DatabaseCleaner` for test isolation
+- Mock database models and external dependencies
+- Test both success and failure scenarios
+- Validate arguments, outputs, and error conditions
+
+## Configuration
+
+### RuboCop Rules
+- Target Ruby version: 2.7+
+- Method length max: 20 lines
+- Uses double quotes for strings
+- Enables trailing commas for multiline structures
+- Disables documentation requirements and guard clauses
+
+### Database Support
+- Optional ActiveRecord integration for transactions
+- Uses SQLite3 for testing
+- Database cleaner ensures test isolation

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at emelianenko.web@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :test do
+  gem "sorbet-runtime"
+
+  gem "activerecord", ">= 8"
+  gem "connection_pool", "< 3"
+  gem "database_cleaner-active_record"
+  gem "sqlite3"
+
+  gem "rake"
+  gem "rspec"
+  gem "rspec-benchmark"
+  gem "simplecov"
+  gem "simplecov-cobertura"
+
+  gem "rubocop"
+  gem "rubocop-performance"
+  gem "rubocop-rake"
+  gem "rubocop-rspec"
+
+  # Fix OpenSSL 3.x CRL verification issues
+  gem "openssl", "3.3.2"
+end