operandi 5.0.0

data/Gemfile.lock

@@ -0,0 +1,149 @@
+PATH
+  remote: .
+  specs:
+    operandi (5.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (8.1.2)
+      activesupport (= 8.1.2)
+    activerecord (8.1.2)
+      activemodel (= 8.1.2)
+      activesupport (= 8.1.2)
+      timeout (>= 0.4.0)
+    activesupport (8.1.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark-malloc (0.2.0)
+    benchmark-perf (0.6.0)
+    benchmark-trend (0.4.0)
+    bigdecimal (4.0.1)
+    concurrent-ruby (1.3.6)
+    connection_pool (2.5.5)
+    database_cleaner-active_record (2.2.2)
+      activerecord (>= 5.a)
+      database_cleaner-core (~> 2.0)
+    database_cleaner-core (2.0.1)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    drb (2.2.3)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    mini_portile2 (2.8.9)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    openssl (3.3.2)
+    parallel (1.27.0)
+    parser (3.3.10.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.8.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-benchmark (0.6.0)
+      benchmark-malloc (~> 0.2)
+      benchmark-perf (~> 0.6)
+      benchmark-trend (~> 0.4)
+      rspec (>= 3.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.82.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-cobertura (3.1.0)
+      rexml
+      simplecov (~> 0.19)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    sorbet-runtime (0.6.12894)
+    sqlite3 (2.9.0)
+      mini_portile2 (~> 2.8.0)
+    timeout (0.6.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (>= 8)
+  connection_pool (< 3)
+  database_cleaner-active_record
+  openssl (= 3.3.2)
+  operandi!
+  rake
+  rspec
+  rspec-benchmark
+  rubocop
+  rubocop-performance
+  rubocop-rake
+  rubocop-rspec
+  simplecov
+  simplecov-cobertura
+  sorbet-runtime
+  sqlite3
+
+BUNDLED WITH
+   2.5.10

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Andrew Emelianenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,172 @@
+# 🚀 Operandi
+
+Operandi is a simple yet powerful way to organize business logic in Ruby applications. Build services that are easy to test, maintain, and understand.
+
+![GitHub CI](https://github.com/akodkod/operandi/actions/workflows/ci.yml/badge.svg)
+[![Codecov](https://codecov.io/gh/akodkod/operandi/graph/badge.svg?token=IGJNZ2BQ26)](https://codecov.io/gh/akodkod/operandi)
+
+[Get started with Quickstart](https://operandi.kodkod.me/quickstart)
+
+## Features
+
+- ✨ **Simple**: Define your service as a class with `arguments`, `steps`, and `outputs`
+- 📦 **No runtime dependencies**: Works stand-alone without requiring external gems at runtime
+- 🔄 **Transactions**: Automatically rollback database changes if any step fails
+- 🧬 **Inheritance**: Inherit from other services to reuse logic seamlessly
+- ⚠️ **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
+- 🌐 **Framework Agnostic**: Compatible with Rails, Hanami, or any Ruby framework
+- 🧩 **Modularity**: Isolate and test your services with ease
+- 🔷 **Sorbet & Tapioca**: Full support for Sorbet type checking and Tapioca DSL generation
+- ✅ **100% Test Coverage**: Thoroughly tested and reliable
+- ⚔️ **Battle-Tested**: In production use since 2017
+
+## Installation
+
+```ruby
+gem "operandi", "~> 5.0"
+```
+
+```bash
+rails generate operandi:install
+```
+
+## Simple Example
+
+```ruby
+class GreetService < Operandi::Base
+  # Arguments
+  arg :name, type: String
+  arg :age, type: Integer
+
+  # Steps
+  step :build_message
+  step :send_message
+
+  # Outputs
+  output :message, type: String
+
+  private
+
+  def build_message
+    self.message = "Hello, #{name}! You are #{age} years old."
+  end
+
+  def send_message
+    # Send logic goes here
+  end
+end
+```
+
+## Advanced Example (with Sorbet types and conditions)
+
+```ruby
+class User::ResetPassword < Operandi::Base
+  # Arguments with Sorbet types
+  arg :user, type: User, optional: true
+  arg :email, type: String, optional: true
+  arg :send_email, type: T::Boolean, default: true
+  arg :metadata, type: T::Hash[Symbol, String], default: {}
+  arg :notify_channels, type: T::Array[Symbol], default: [:email]
+
+  # Steps
+  step :validate
+  step :find_user, unless: :user?
+  step :generate_reset_token
+  step :save_reset_token
+  step :send_reset_email, if: :send_email?
+
+  # Outputs
+  output :user, type: User
+  output :reset_token, type: String
+  output :notifications_sent, type: T::Array[Symbol]
+
+  private
+
+  def validate
+    errors.add(:base, "user or email is required") if !user? && !email?
+  end
+
+  def find_user
+    self.user = User.find_by("LOWER(email) = ?", email.downcase)
+    errors.add(:email, "not found") unless user
+  end
+
+  def generate_reset_token
+    self.reset_token = SecureRandom.hex(32)
+  end
+
+  def save_reset_token
+    user.update!(
+      reset_password_token: reset_token,
+      reset_password_sent_at: Time.current,
+    )
+  rescue ActiveRecord::RecordInvalid => e
+    errors.from_record(e.record)
+  end
+
+  def send_reset_email
+    Mailer::SendEmail
+      .with(self) # Call sub-service with the same context
+      .run(template: :reset_password, user:, reset_token:)
+  end
+end
+```
+
+[Get started with Operandi](https://operandi.kodkod.me/quickstart)
+
+## Rails Generators
+
+Operandi includes Rails generators to help you quickly set up and create services in your Rails application.
+
+### Install Generator
+
+Set up Operandi in your Rails application:
+
+```bash
+bin/rails generate operandi:install
+```
+
+This creates:
+- `app/services/application_service.rb` - Base service class for your application
+- `config/initializers/operandi.rb` - Configuration file
+- `spec/services/application_service_spec.rb` - RSpec test file (if RSpec is detected)
+
+**Options:**
+- `--skip-initializer` - Skip creating the initializer file
+- `--skip-spec` - Skip creating the spec file
+
+### Service Generator
+
+Create a new service class:
+
+```bash
+# Basic service
+bin/rails generate operandi:service user/create
+
+# Service with predefined structure
+bin/rails generate operandi:service CreateOrder \
+  --args=user product \
+  --steps=validate process \
+  --outputs=order
+```
+
+This creates:
+- `app/services/user/create.rb` - Service class file
+- `spec/services/user/create_spec.rb` - RSpec test file (if RSpec is detected)
+
+**Options:**
+- `--args` - List of arguments for the service (e.g., `--args=user product`)
+- `--steps` - List of steps for the service (e.g., `--steps=validate process`)
+- `--outputs` - List of outputs for the service (e.g., `--outputs=result`)
+- `--skip-spec` - Skip creating the spec file
+- `--parent` - Parent class (default: ApplicationService)
+
+## Documentation
+
+You can find the full documentation at [operandi.kodkod.me](https://operandi.kodkod.me).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "operandi"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/config/default.yml

@@ -0,0 +1,57 @@
+Operandi/ArgumentTypeRequired:
+  Enabled: true
+  Description: "Requires a `type:` option for all arguments."
+
+Operandi/DeprecatedAccessors:
+  Enabled: true
+  Description: "Detects deprecated `arguments` and `outputs` accessors."
+
+Operandi/ConditionMethodExists:
+  Enabled: true
+  Description: "Ensures condition methods referenced in `if:` or `unless:` exist."
+
+Operandi/DeprecatedMethods:
+  Enabled: true
+  Description: "Detects usage of deprecated Operandi methods."
+
+Operandi/DslOrder:
+  Enabled: true
+  Description: "Enforces the order of DSL methods in Operandi services."
+
+Operandi/MissingPrivateKeyword:
+  Enabled: true
+  Description: "Ensures `private` keyword is present in Operandi services."
+
+Operandi/NoDirectInstantiation:
+  Enabled: true
+  Description: "Detects direct instantiation of Operandi services."
+
+Operandi/NoHashArgument:
+  Enabled: false
+  Description: "Detects hash arguments passed to `.run` or `.run!` instead of keyword arguments."
+  ServicePattern: ~
+
+Operandi/OutputTypeRequired:
+  Enabled: true
+  Description: "Requires a `type:` option for all outputs."
+
+Operandi/PreferOptionalOverDefaultNil:
+  Enabled: true
+  Description: "Prefers `optional: true` over `default: nil`."
+
+Operandi/PreferFailMethod:
+  Enabled: true
+  Description: "Prefers `fail!` over manual error handling."
+
+Operandi/RedundantOptional:
+  Enabled: true
+  Description: "Detects redundant `optional: true` when a default value is provided."
+
+Operandi/ReservedName:
+  Enabled: true
+  Description: "Detects reserved argument and output names."
+
+Operandi/StepMethodExists:
+  Enabled: true
+  Description: "Ensures step methods exist in Operandi services."
+  ExcludedSteps: []

data/docs/README.md

@@ -0,0 +1,105 @@
+# Operandi
+
+Operandi is a simple yet powerful way to organize business logic in Ruby applications. Build services that are easy to test, maintain, and understand.
+
+[Get started with Quickstart](quickstart.md)
+
+## Features
+
+- ✨ **Simple**: Define your service as a class with `arguments`, `steps`, and `outputs`
+- 📦 **No runtime dependencies**: Works stand-alone without requiring external gems at runtime
+- 🔄 **Transactions**: Automatically rollback database changes if any step fails
+- 🧬 **Inheritance**: Inherit from other services to reuse logic seamlessly
+- ⚠️ **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
+- 🔷 **Sorbet & Tapioca**: Full support for Sorbet type checking and Tapioca DSL generation
+- ✅ **100% Test Coverage**: Thoroughly tested and reliable
+- ⚔️ **Battle-Tested**: In production use since 2017
+
+## Simple Example
+
+```ruby
+class GreetService < Operandi::Base
+  # Arguments
+  arg :name, type: String
+  arg :age, type: Integer
+
+  # Steps
+  step :build_message
+  step :send_message
+
+  # Outputs
+  output :message, type: String
+
+  private
+
+  def build_message
+    self.message = "Hello, #{name}! You are #{age} years old."
+  end
+
+  def send_message
+    # Send logic goes here
+  end
+end
+```
+
+## Advanced Example (with Sorbet types and conditions)
+
+```ruby
+class User::ResetPassword < Operandi::Base
+  # Arguments with Sorbet types
+  arg :user, type: User, optional: true
+  arg :email, type: String, optional: true
+  arg :send_email, type: T::Boolean, default: true
+  arg :metadata, type: T::Hash[Symbol, String], default: {}
+  arg :notify_channels, type: T::Array[Symbol], default: [:email]
+
+  # Steps
+  step :validate
+  step :find_user, unless: :user?
+  step :generate_reset_token
+  step :save_reset_token
+  step :send_reset_email, if: :send_email?
+
+  # Outputs
+  output :user, type: User
+  output :reset_token, type: String
+  output :notifications_sent, type: T::Array[Symbol]
+
+  private
+
+  def validate
+    errors.add(:base, "user or email is required") if !user? && !email?
+  end
+
+  def find_user
+    self.user = User.find_by("LOWER(email) = ?", email.downcase)
+    errors.add(:email, "not found") unless user
+  end
+
+  def generate_reset_token
+    self.reset_token = SecureRandom.hex(32)
+  end
+
+  def save_reset_token
+    user.update!(
+      reset_password_token: reset_token,
+      reset_password_sent_at: Time.current,
+    )
+  rescue ActiveRecord::RecordInvalid => e
+    errors.from_record(e.record)
+  end
+
+  def send_reset_email
+    Mailer::SendEmail
+      .with(self) # Call sub-service with the same context
+      .run(template: :reset_password, user:, reset_token:)
+  end
+end
+```
+
+[Get started with Operandi](quickstart.md)

data/docs/SUMMARY.md

@@ -0,0 +1,31 @@
+# Summary​
+
+## Introduction
+
+* [Operandi](README.md)
+* [Quickstart](quickstart.md)
+* [Concepts](concepts.md)
+
+## Deep Dive
+
+* [Arguments](arguments.md)
+* [Steps](steps.md)
+* [Outputs](outputs.md)
+* [Context](context.md)
+* [Errors](errors.md)
+* [Callbacks](callbacks.md)
+* [Configuration](configuration.md)
+* [Testing](testing.md)
+* [Rails Generators](generators.md)
+* [RuboCop Integration](rubocop.md)
+* [Ruby LSP Integration](ruby-lsp.md)
+* [Sorbet Runtime Types](sorbet-runtime.md)
+* [Tapioca / Sorbet Integration](tapioca.md)
+
+## Examples
+
+* [Best Practices](best-practices.md)
+* [Recipes](recipes.md)
+  * [CRUD](crud.md)
+  * [Service Rendering](service-rendering.md)
+  * [Pundit Authorization](pundit-authorization.md)