statesman 13.1.0 → 13.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f93bd968475f6cfd090311f9998a2350993df852aa3796fab5d3b52f962d6147
-  data.tar.gz: 3789c10d55df44ee6e921f9d2297d7d0e0767f42521309ac14aed8e49a0986a8
+  metadata.gz: ffe7ee5f3aa4787fccd4c325c42bd892dc475edaaabc45a4a67155ebe41d41c1
+  data.tar.gz: 1794e00cf99c34e3d84a680f409a92d2430d0ed4964d3145f7f0539d7c54ec09
 SHA512:
-  metadata.gz: 13b9e129ec5bb984066a05c408ee99c9965861775269bab232e6aac86ee75b5c5485a14ccc8476b3b96d0bc383cc68a1f67d32cf9d3eea575478e25ed0245d56
-  data.tar.gz: d88507f263405847ea99f8a7cc88ec4e63c3a82addcef3a20e9c0e1c83372df38868278459702c0855e535d7ebca031e18ddaee32031b0beb162932963156325
+  metadata.gz: 7fc095f7cdfec543802c1e367af567d63e8abea8e57c01bc0b1fc1a6d661ea3b187e0d9ed91457c2eecf109286879ef7bd5bf45e3fa80a44777cb326486f9007
+  data.tar.gz: e3c342d10b68eccd5d4f145079c70537582f7923cf5cf7a9c0724fb58553476ca3d4e319c993929840e7ee2d2dbfedf1634e40160647429ea7cf194574275b79

data/.github/workflows/tests.yml

@@ -25,12 +25,15 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ["3.2", "3.3", "3.4", "3.5"]
+        ruby-version: ["3.3", "3.4", "4.0"]
         rails-version:
-          - "7.1"
           - "7.2"
           - "8.0"
+          - "8.1"
           - "main"
+        exclude:
+          - ruby-version: "3.2"
+            rails-version: "main"
     runs-on: ubuntu-latest
     env:
       RAILS_VERSION: ${{ matrix.rails-version }}
@@ -49,13 +52,16 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ["3.2", "3.3", "3.4", "3.5"]
+        ruby-version: ["3.3", "3.4", "4.0"]
         rails-version:
-          - "7.1"
           - "7.2"
           - "8.0"
+          - "8.1"
           - "main"
         postgres-version: ["14", "15", "16", "17"]
+        exclude:
+          - ruby-version: "3.2"
+            rails-version: "main"
     runs-on: ubuntu-latest
     services:
       postgres:
@@ -90,13 +96,16 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ["3.2", "3.3", "3.4", "3.5"]
+        ruby-version: ["3.3", "3.4", "4.0"]
         rails-version:
-          - "7.1"
           - "7.2"
           - "8.0"
+          - "8.1"
           - "main"
         mysql-version: ["8.0", "8.4", "9.4"]
+        exclude:
+          - ruby-version: "3.2"
+            rails-version: "main"
 
     runs-on: ubuntu-latest
     services:

data/.rubocop.yml

@@ -4,7 +4,7 @@ inherit_gem:
   gc_ruboconfig: rubocop.yml
 
 AllCops:
-  TargetRubyVersion: 3.2
+  TargetRubyVersion: 3.3
   NewCops: enable
 
 Metrics/AbcSize:

data/CHANGELOG.md

@@ -5,6 +5,12 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v13.2.0 29th July 2026
+
+### Added
+
+- Expose the transitioning object on `GuardFailedError` via `#object` [#566](https://github.com/gocardless/statesman/pull/566)
+
 ## v13.1.0 9th October 2025
 
 ### Added

data/Gemfile

@@ -14,17 +14,16 @@ end
 
 group :development, :test do
   gem "ammeter", "~> 1.1"
-  gem "bundler", "~> 2"
-  gem "gc_ruboconfig", "~> 5.0.0"
+  gem "gc_ruboconfig", "~> 6.0.0"
   gem "mysql2", ">= 0.4", "< 0.6"
   gem "pg", ">= 0.18", "<= 1.7"
   gem "pry"
-  gem "rake", "~> 13.3.0"
+  gem "rake", "~> 13.4.1"
   gem "rspec", "~> 3.1"
   gem "rspec-github", "~> 3.0.0"
   gem "rspec-its", "~> 2.0"
   gem "rspec-rails", "~> 8.0"
-  gem "sqlite3", "~> 2.7.3"
+  gem "sqlite3", "~> 2.9.0"
   gem "test-unit", "~> 3.3"
   gem "timecop", "~> 0.9.1"
 end

data/README.md

@@ -539,6 +539,16 @@ Raised if:
 
 - A guard callback between `from` and `to` state returned a falsey value.
 
+The model object that failed to transition is available via `object`:
+
+```ruby
+begin
+  my_model.transition_to!(:some_state)
+rescue Statesman::GuardFailedError => e
+  logger.error("Guard failed for #{e.object.class}##{e.object.id}: #{e.message}")
+end
+```
+
 #### TransitionFailedError
 
 Raised if:

data/lib/statesman/exceptions.rb

@@ -30,15 +30,16 @@ module Statesman
   end
 
   class GuardFailedError < StandardError
-    def initialize(from, to, callback)
+    def initialize(from, to, callback, object = nil)
       @from = from
       @to = to
       @callback = callback
+      @object = object
       super(_message)
       set_backtrace(callback.source_location.join(":")) if callback&.source_location
     end
 
-    attr_reader :from, :to, :callback
+    attr_reader :from, :to, :callback, :object
 
     private
 

data/lib/statesman/guard.rb

@@ -5,8 +5,8 @@ require_relative "exceptions"
 
 module Statesman
   class Guard < Callback
-    def call(*args)
-      raise GuardFailedError.new(from, to, callback) unless super
+    def call(object = nil, last_transition = nil, metadata = nil)
+      raise GuardFailedError.new(from, to, callback, object) unless super
     end
   end
 end

data/lib/statesman/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statesman
-  VERSION = "13.1.0"
+  VERSION = "13.2.0"
 end

data/spec/spec_helper.rb

@@ -28,7 +28,7 @@ RSpec.configure do |config|
   end
 
   if config.exclusion_filter[:active_record]
-    puts "Skipping ActiveRecord tests"
+    warn "Skipping ActiveRecord tests"
   else
     current_env = ActiveRecord::ConnectionHandling::DEFAULT_ENV.call
 
@@ -57,7 +57,7 @@ RSpec.configure do |config|
     ActiveRecord::Base.establish_connection(:primary)
 
     db_adapter = ActiveRecord::Base.connection.adapter_name
-    puts "Running with database adapter '#{db_adapter}'"
+    warn "Running with database adapter '#{db_adapter}'"
 
     # Silence migration output
     ActiveRecord::Migration.verbose = false

data/spec/statesman/exceptions_spec.rb

@@ -84,15 +84,25 @@ describe "Exceptions" do
       is_expected.to eq([callback.source_location.join(":")])
     end
 
+    its(:object) { is_expected.to be_nil }
+
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
     end
+
+    context "when an object is passed" do
+      subject(:error) { Statesman::GuardFailedError.new("from", "to", callback, object) }
+
+      let(:object) { Object.new }
+
+      its(:object) { is_expected.to eq(object) }
+    end
   end
 
   describe "UnserializedMetadataError" do
     subject(:error) { Statesman::UnserializedMetadataError.new("foo") }
 
-    its(:message) { is_expected.to match(/foo#metadata is not serialized/) }
+    its(:message) { is_expected.to include("foo#metadata is not serialized") }
 
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)
@@ -102,7 +112,7 @@ describe "Exceptions" do
   describe "IncompatibleSerializationError" do
     subject(:error) { Statesman::IncompatibleSerializationError.new("foo") }
 
-    its(:message) { is_expected.to match(/foo#metadata column type cannot be json/) }
+    its(:message) { is_expected.to include("foo#metadata column type cannot be json") }
 
     its "string matches its message" do
       expect(error.to_s).to eq(error.message)

data/spec/statesman/guard_spec.rb

@@ -10,15 +10,27 @@ describe Statesman::Guard do
     subject(:call) { guard.call }
 
     context "success" do
-      let(:callback) { -> { true } }
+      let(:callback) { ->(*) { true } }
 
       specify { expect { call }.to_not raise_error }
     end
 
     context "error" do
-      let(:callback) { -> { false } }
+      let(:callback) { ->(*) { false } }
 
       specify { expect { call }.to raise_error(Statesman::GuardFailedError) }
+
+      context "when called with an object" do
+        subject(:call) { guard.call(object) }
+
+        let(:object) { Object.new }
+
+        specify do
+          expect { call }.to raise_error(
+            an_instance_of(Statesman::GuardFailedError).and(having_attributes(object: object)),
+          )
+        end
+      end
     end
   end
 end

data/spec/statesman/machine_spec.rb

@@ -966,7 +966,7 @@ describe Statesman::Machine do
             expect { instance.transition_to!(:y) }.
               to raise_error(
                 an_instance_of(Statesman::GuardFailedError).
-                and(having_attributes(from: "x", to: ["y"])),
+                and(having_attributes(from: "x", to: ["y"], object: my_model)),
               )
           end
         end

data/statesman.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 3.2"
+  spec.required_ruby_version = ">= 3.3"
 
   spec.metadata = {
     "bug_tracker_uri" => "#{GITHUB_URL}/issues",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statesman
 version: !ruby/object:Gem::Version
-  version: 13.1.0
+  version: 13.2.0
 platform: ruby
 authors:
 - GoCardless
@@ -95,7 +95,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="