Skip to content
CAI
Software that uses CAICheck a score

gocardless/statesman

58.7

Adequate · 6 November 2026

1.5k

lines of production code

Ruby

primary language

4

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

This system is a Ruby gem that provides a robust state machine library for managing object transitions. It supports multiple storage backends, including ActiveRecord and in-memory adapters, with features for caching current states and handling database-specific constraints. The library includes generators for scaffolding transition models and migrations, along with comprehensive testing infrastructure for multi-database environments.

Features

Added db-agnostic backfill task for most\_recent column

A new Rake task \statesman:backfill\_most\_recent\ is introduced to populate the \most\_recent\ column on transition records. The task is designed to be database-agnostic: it detects whether the underlying database supports partial indexes and, if not, sets the column to \nil\ instead of \false\ for older transitions. It also ensures the \updated\_at\ timestamp is refreshed during the backfill process.

lib/tasks · high confidence

New ActiveRecord and Memory adapters with cached state support

The library now includes dedicated adapter implementations for ActiveRecord and in-memory storage, replacing the previous monolithic approach. The new ActiveRecord adapter introduces a \most\_recent\ column on transition records to efficiently track the current state, supports JSON/JSONB metadata serialization, and provides an optional cached current state column on the parent model for faster lookups. A new \Memory\ adapter is also added for testing or non-persistent use cases. Additionally, type-safe query helpers are provided to allow models to query their current state via \in\_state\ and \not\_in\_state\ scopes without requiring explicit association names.

lib/statesman/adapters · high confidence

New generators for transition models and migrations

Statesman now provides dedicated generators to scaffold state machine components. The new \ActiveRecordTransitionGenerator\ creates both the transition model file and its corresponding migration, while the \MigrationGenerator\ allows adding the required Statesman attributes to an existing transition model. These tools simplify setup by handling model structure, database schema creation, and database-specific configuration (such as JSON column types and default values) automatically.

lib/generators/statesman · high confidence

Behavioural changes

Generator templates now include a \`most\_recent\` column and configurable timestamps

The ActiveRecord transition model and migration generators have been updated to include a \most\_recent\ boolean column, which is marked as not null and indexed to efficiently identify the latest transition for a parent record. The generated migration templates now enforce \null: false\ constraints on core columns and timestamps, and conditionally apply partial index syntax for databases that support it. Additionally, the model template now supports configuring the \updated\_timestamp\_column\ and excludes \attr\_accessible\ declarations for Rails 5 and higher, ensuring compatibility with modern Rails versions.

lib/generators/statesman/templates · high confidence

Introduces global configuration and lazy loading for storage adapters

The library now supports global configuration via a new \Statesman.configure\ block, allowing users to set a default storage adapter (e.g., ActiveRecord) and enable MySQL gaplock protection at the application level. To improve startup performance, all core classes and adapters are now lazily loaded using Ruby's \autoload\ mechanism, replacing the previous eager \require\ statements. This change simplifies setup by providing a centralized configuration point while maintaining backward compatibility through a default in-memory adapter.

lib · high confidence

Project setup and configuration overhaul

The repository has been restructured with new configuration files: \.rspec\ sets RSpec to use \spec\_helper\ and \progress\ format; \.rubocop.yml\ inherits from \gc\_ruboconfig\ and sets the target Ruby version to 3.3 with specific complexity limits; \.rubocop\_todo.yml\ is auto-generated to suppress existing offenses; \.ruby-version\ is set to 3.4.5; \.gitignore\ is expanded to cover modern IDEs (VSCode, JetBrains) and build artifacts; \Guardfile\ adds live reloading for RSpec and RuboCop; \Rakefile\ is rewritten to run specs against SQLite, PostgreSQL, and MySQL in parallel using Testcontainers; \CONTRIBUTING.md\ documents the new test and style workflows; and \LICENSE.txt\ updates the copyright holder to GoCardless.

(repo-wide) · high confidence

Statesman state machine library updated to v13.3.0

The Statesman gem has been upgraded to version 13.3.0. This release introduces a refactored callback system with dedicated \Callback\ and \Guard\ classes, allowing for more granular control over state transitions via \before\_transition\, \after\_transition\, \after\_transition\_failure\, and \after\_guard\_failure\ hooks. It also adds specific error classes like \TransitionFailedError\ and \GuardFailedError\ to provide detailed context (from/to states, callback source) on failures, and includes configuration options for MySQL gaplock protection and storage adapters.

lib/statesman · high confidence

Test coverage

Added comprehensive test suite for state machine adapters; Added generator specs for ActiveRecord transition and migration generation; Added migration fixtures for the most\_recent column on bacon\_transitions; Added test coverage for core state machine components; Added test infrastructure for ActiveRecord and multi-database support; Establishes ActiveRecord test infrastructure with multi-database support.

Dependencies

Update dependencies and require Ruby 3.3+

The project now requires Ruby 3.3 or higher and updates its development dependencies to support testing against Rails 8.0 (default) or specific versions via environment variables. Key dependency updates include rspec-rails to \~\> 8.0, sqlite3 to \~\> 2.9.0, pg to \<= 1.7, and the introduction of testcontainers for MySQL and PostgreSQL integration testing. The gemspec also adds standard RubyGems metadata for better discoverability and issue tracking.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 58 → 59 (+1.2)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.

Lenses

  • Code Health 75 → 75 (+0.0)
  • Architecture 81 → 81 (+0.0)
  • Maturity 54 → 59 (+4.8)
  • Readiness 47 → 47 (+0.0)
  • Security 97 → 96 (-1.4)

Resolved (4)

  • Duplicate Capability Check: The check for database support of partial indexes is implemented in both the Adapter (ActiveRecord) and the Generator Helpers (GeneratorHelpers). This leads to potential drift if database capabilities change, as both locations must be updated.
  • Inconsistent Configuration API: configure implies setting up global state, while config implies retrieving it. However, Config class also has initialize(block) and storage_adapter. The top-level Statesman methods are ambiguous regarding whether they modify global state or just return a config object, especially since Config exists as a distinct type.
  • Inconsistent Error Handling Convention: Ruby/Rails conventions typically use ! to denote methods that raise exceptions on failure (e.g., save vs save!). Here, transition_to and transition_to! exist. However, Machine also has can_transition_to? which is a predicate. The distinction between transition_to (likely returning a result object or nil) and transition_to! (raising) is clear, but Machine also has allowed_transitions which is a query. The inconsistency lies in the fact that transition_to might not raise, but the error handling path is complex with execute_on_failure. It is a minor inconsistency but worth noting if transition_to is expected to be the 'safe' version.
  • Redundant Generator Classes: ActiveRecordTransitionGenerator and MigrationGenerator both expose create_migration_file. ActiveRecordTransitionGenerator also exposes create_model_file, suggesting it is a composite generator, while MigrationGenerator seems to be a specialized subset. This creates confusion about which generator to use for standard state machine setup.

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

gocardless/statesman was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 72aa3d3e5afeac51bee4bcc4d91ad45d124bb009 — the exact code this score is about.
  • Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.2+preprod-5c4e66d9318b.