AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
4 
5## About Operandi
6 
7Operandi 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.
8 
9## Development Commands
10 
11### Testing
12```bash
13# Run all tests
14bundle exec rspec
15 
16# Run specific test file
17bundle exec rspec spec/path/to/file_spec.rb
18 
19# Run with coverage (uses SimpleCov)
20bundle exec rspec
21```
22 
23### Linting
24```bash
25# Run RuboCop linter
26bundle exec rubocop
27 
28# Auto-fix RuboCop issues
29bundle exec rubocop -a
30```
31 
32### Build and Release
33```bash
34# Build gem
35bundle exec rake build
36 
37# Default task (runs tests)
38bundle exec rake
39```
40 
41## Architecture
42 
43### Core Components
44 
451. **Base Service (`lib/operandi/base.rb:15`)**
46   - Main service class that all services inherit from
47   - Handles service lifecycle: initialization, execution, callbacks, error management
48   - Provides DSL for defining arguments, steps, and outputs
49   - Manages transactions and error propagation to parent services
50 
512. **Callbacks System (`lib/operandi/callbacks.rb:5`)**
52   - Supports service and step-level callbacks
53   - Events: `before_service_run`, `after_service_run`, `around_service_run`, `on_service_success`, `on_service_failure`
54   - Step events: `before_step_run`, `after_step_run`, `around_step_run`, `on_step_success`, `on_step_failure`
55 
563. **Settings**
57   - **Step (`lib/operandi/settings/step.rb:7`)**: Handles step execution with conditional logic (`if`, `unless`, `always`)
58   - **Field (`lib/operandi/settings/field.rb`)**: Manages argument and output validation and type checking
59 
604. **Messages System (`lib/operandi/messages.rb`)**
61   - Collects errors and warnings with options for breaking, raising, or rolling back
62   - Supports copying messages between parent and child services
63 
645. **Collection (`lib/operandi/collection.rb`)**
65   - Manages arguments and outputs as collections with validation and defaults
66   - Supports Sorbet runtime types for type validation
67 
68### Service DSL
69 
70Services use a declarative DSL:
71```ruby
72class ExampleService < Operandi::Base
73  # Define input arguments
74  arg :name, type: String
75  arg :age, type: Integer, optional: true, default: 25
76 
77  # Define execution steps
78  step :validate_input
79  step :process_data, if: :should_process?
80  step :cleanup, always: true
81 
82  # Define outputs
83  output :result, type: Hash
84 
85  private
86 
87  def validate_input
88    errors.add(:name, "required") if name.nil? || name.strip.empty?
89  end
90 
91  def process_data
92    self.result = { name: name, age: age }
93  end
94 
95  def cleanup
96    # Runs regardless of errors/warnings, unless stop! was called
97  end
98 
99  def should_process?
100    !(name.nil? || name.strip.empty?)
101  end
102end
103```
104 
105### Service Execution
106 
107- Services can be run with `.run(args)` or `.run!(args)` (raises on error)
108- Use `.with(service_or_context)` to chain services with shared context
109- Transactions automatically rollback on errors when `use_transactions: true`
110- Steps run sequentially, stopping on errors unless `always: true`
111 
112### Error Handling
113 
114- Errors collected in `@errors` message collection
115- Supports `break_on_error`, `raise_on_error`, `rollback_on_error` configuration
116- Warnings work similarly with `@warnings` collection
117- Parent services can inherit child errors/warnings based on configuration
118 
119### Testing Patterns
120 
121- Services are tested using RSpec with database transactions
122- Use `DatabaseCleaner` for test isolation
123- Mock database models and external dependencies
124- Test both success and failure scenarios
125- Validate arguments, outputs, and error conditions
126 
127## Configuration
128 
129### RuboCop Rules
130- Target Ruby version: 2.7+
131- Method length max: 20 lines
132- Uses double quotes for strings
133- Enables trailing commas for multiline structures
134- Disables documentation requirements and guard clauses
135 
136### Database Support
137- Optional ActiveRecord integration for transactions
138- Uses SQLite3 for testing
139- Database cleaner ensures test isolation