From e4e90ef612146a8130da661a74bad1c308a96562 Mon Sep 17 00:00:00 2001 From: Jijo Bose Date: Tue, 23 Jun 2026 10:47:07 +0530 Subject: [PATCH] Custom actions --- CHANGELOG.md | 32 ++++- README.md | 72 +++++++++- lib/signoff/definition.rb | 97 +++++++++++-- lib/signoff/dsl.rb | 20 ++- lib/signoff/model.rb | 61 +++++++- lib/signoff/version.rb | 2 +- sig/signoff.rbs | 9 ++ spec/signoff/custom_actions_spec.rb | 209 ++++++++++++++++++++++++++++ spec/support/factories.rb | 4 + spec/support/models.rb | 24 ++++ spec/support/schema.rb | 6 + 11 files changed, 514 insertions(+), 22 deletions(-) create mode 100644 spec/signoff/custom_actions_spec.rb diff --git a/CHANGELOG.md b/CHANGELOG.md index cdca3a6..c9486c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.0] - 2026-06-23 + +### Added + +- **Custom action verbs.** Declare a named action inside the `signoff` block — + `action(name, to:, from: nil)` — to model any workflow verb beyond the built-in + `submit`/`approve`/`reject`. Each declared action generates a `name!` transition + method (accepting the usual `user:`, `comment:`, `metadata:`, `ip_address:`, + `user_agent:` keywords) and a non-raising `can_name?(user = nil)` predicate, and + records a `Signoff::Event` whose `action` is the verb name verbatim — so the + audit trail stays semantically truthful (e.g. `request_changes`, `cancel`, + `escalate`). Like `reject`, a custom action is a guarded *side transition*: its + target is never a forward edge, so it cannot make `approve!` ambiguous. `from:` + limits the permitted source states (single state or array) and defaults to every + non-finalized state except the action's own target. Custom actions reuse the + source state's `allow_transition` guard. +- **Multi-source forward transitions.** `transition` now accepts an array for + `from` as well as `to`, so several states can share one forward edge — + `transition [:draft, :rejected, :changes_requested], to: :review`. + +### Changed + +- `approved?` / the `.approved` scope now exclude custom-action target states, and + `pending?` / the `.pending` scope treat a *terminal* custom-action target (e.g. + `cancelled`) as finalized while a *looping* target (e.g. `changes_requested`, + which re-submits) stays in flight. Workflows without custom actions are + unaffected — the finalized set remains exactly the approval terminals plus the + reject state. + ## [0.1.0] - 2026-06-05 Initial public release. `signoff` adds concurrency-safe approval workflows @@ -75,5 +104,6 @@ and 8.x, backed by PostgreSQL — no external services required. `MissingColumnError`. - **Rails 7.x and 8.x support** on Ruby >= 3.2 with PostgreSQL. -[Unreleased]: https://github.com/JijoBose/Signoff/compare/v0.1.0...HEAD +[Unreleased]: https://github.com/JijoBose/Signoff/compare/v0.2.0...HEAD +[0.2.0]: https://github.com/JijoBose/Signoff/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/JijoBose/Signoff/releases/tag/v0.1.0 diff --git a/README.md b/README.md index a36114c..6a69bcc 100644 --- a/README.md +++ b/README.md @@ -471,15 +471,71 @@ the state column for a single model (e.g. `signoff(column: :workflow_state) do`) | `state(name, initial: false)` | Declare a state. `initial: true` marks the start state. | | `states(*names)` | Declare several states at once. | | `initial_state(name)` | Set the start state explicitly (defaults to the first declared). | -| `transition(from, to:)` | Declare a forward transition. `to:` accepts a symbol or an array. | +| `transition(from, to:)` | Declare a forward transition. Both `from` and `to:` accept a symbol or an array. | | `reject_to(state)` | The state `reject!` moves a record into. | +| `action(name, to:, from: nil)` | Declare a custom verb (e.g. `:request_changes`). Generates `name!` / `can_name?` and records `action` verbatim. A guarded side transition — never a forward edge. `from:` limits sources (defaults to any non-finalized state). | | `allow_transition(from) { \|user[, record]\| ... }` | Authorize transitions **out of** `from`. | | `before_transition { \|record, from, to\| ... }` | Run inside the transaction, before the state is written. | | `after_transition { \|record, event\| ... }` | Run after the transaction commits (great for jobs/mail). | Definitions are validated when the class loads. You'll get a descriptive `Signoff::DefinitionError` for duplicate states, transitions to/from -undeclared states, a missing initial state, or an undeclared reject state. +undeclared states, a missing initial state, an undeclared reject state, or a +custom `action` that is named after a built-in verb or targets an undeclared +state. + +### Custom actions + +`submit`, `approve`, and `reject` cover the common path, but real workflows have +more verbs — request changes, escalate, cancel, return-to-sender. Declare them +with `action` and the audit trail stays truthful (the recorded `action` is the +verb name, not a repurposed `"reject"`): + +```ruby +class Post < ApplicationRecord + include Signoff + + signoff do + states :draft, :in_review, :approved, :rejected, :changes_requested, :cancelled + + # Several states share one forward edge (re-submission re-enters review): + transition %i[draft rejected changes_requested], to: :in_review + transition :in_review, to: :approved + + reject_to :rejected + + # A looping off-ramp — re-submission brings it back into review: + action :request_changes, from: :in_review, to: :changes_requested + # A terminal off-ramp from any in-flight state (no :from given): + action :cancel, to: :cancelled + + allow_transition :in_review do |user| + user.editor? + end + end +end + +post.request_changes!(user: current_user, comment: "Tighten the intro") +post.current_state # => :changes_requested +post.workflow_history.last.action # => "request_changes" (truthful) +post.can_request_changes?(other) # => true / false (never raises) +post.submit! # changes_requested -> in_review again +post.cancel!(user: current_user) # -> cancelled +``` + +A custom action behaves like a first-class `reject`: + +- It is a **guarded side transition** — its target is never a forward edge, so a + state can offer `approve!` *and* `request_changes!`/`cancel!` without making + `approve!` ambiguous. +- It reuses the **source state's `allow_transition` guard**. Unauthorized calls + raise `Signoff::UnauthorizedError`; the generated `can_?` predicate reports + permission without raising. +- `from:` limits the permitted source states (a symbol or array). Omit it and the + action is allowed from any non-finalized state except its own target. +- Targets that **loop back** into the flow (like `changes_requested`) count as + *in flight* (`pending?` / `.pending`); targets with no way out (like + `cancelled`) count as *finalized* — and neither is ever reported as `approved?`. ## Instance API @@ -491,6 +547,9 @@ Including `Signoff` and declaring a workflow generates: report.submit!(user: nil, comment: nil, metadata: {}, to: nil) report.approve!(user: nil, comment: nil, metadata: {}, to: nil) report.reject!(user: nil, comment: nil, metadata: {}) + +# Plus one method per declared custom action, e.g.: +report.request_changes!(user: nil, comment: nil, metadata: {}) ``` - `submit!` and `approve!` both advance the **single forward transition** from the @@ -499,6 +558,8 @@ report.reject!(user: nil, comment: nil, metadata: {}) - When a state has **more than one** forward transition, pass `to:` to disambiguate (`report.approve!(to: :finance_review)`). - `reject!` moves the record to the `reject_to` state. +- Each custom `action :name` generates a `name!` method that records `"name"` as + the audit `action` (see [Custom actions](#custom-actions)). - All accept `ip_address:` and `user_agent:` keyword overrides (see [Configuration](#configuration)). - Each returns the created `Signoff::Event`. @@ -521,11 +582,12 @@ report.finance_review? ### Authorization predicates ```ruby -report.can_approve?(current_user) # => true / false (never raises) -report.can_reject?(current_user) # => true / false +report.can_approve?(current_user) # => true / false (never raises) +report.can_reject?(current_user) # => true / false +report.can_request_changes?(current_user) # => one per custom action ``` -Both fall back to `Signoff::Current.user` when no argument is given. +All fall back to `Signoff::Current.user` when no argument is given. ### Audit helpers diff --git a/lib/signoff/definition.rb b/lib/signoff/definition.rb index 74647e2..2854342 100644 --- a/lib/signoff/definition.rb +++ b/lib/signoff/definition.rb @@ -6,14 +6,19 @@ module Signoff # lifecycle callbacks. Built by Signoff::DSL and stored on the model # class as +signoff_definition+. class Definition + # Built-in verbs that own their own transition methods on the model; a + # custom +action+ may not reuse these names. + RESERVED_ACTIONS = %i[submit approve reject].freeze + attr_reader :states, :transitions, :authorizations, - :before_callbacks, :after_callbacks, :state_column + :before_callbacks, :after_callbacks, :state_column, :actions attr_writer :initial_state def initialize(state_column: :approval_state) @states = [] @transitions = {} # from(Symbol) => [to(Symbol), ...] @authorizations = {} # from(Symbol) => callable guard + @actions = {} # name(Symbol) => { to: Symbol, from: [Symbol]|nil } @before_callbacks = [] @after_callbacks = [] @initial_state = nil @@ -31,11 +36,13 @@ def add_state(name) end def add_transition(from, to) - from = from.to_sym - Array(to).each do |target| - target = target.to_sym - @transitions[from] ||= [] - @transitions[from] << target unless @transitions[from].include?(target) + Array(from).each do |source| + source = source.to_sym + Array(to).each do |target| + target = target.to_sym + @transitions[source] ||= [] + @transitions[source] << target unless @transitions[source].include?(target) + end end end @@ -43,6 +50,22 @@ def add_authorization(from, guard) @authorizations[from.to_sym] = guard end + # Register a named custom action: a guarded "side transition" that moves a + # record to +to+ and records an event whose +action+ is the name verbatim. + # Like +reject+, the target is NOT a forward transition, so it never makes + # +approve!+ ambiguous. +from+ limits the source states (defaults to every + # non-finalized state except the target itself). + def add_action(name, to:, from: nil) + name = name.to_sym + raise DefinitionError, "duplicate action #{name.inspect}" if @actions.key?(name) + raise DefinitionError, "action #{name.inspect} requires a :to state" if to.nil? + + @actions[name] = { + to: to.to_sym, + from: from.nil? ? nil : Array(from).map(&:to_sym) + } + end + def reject_state=(name) @reject_state = name&.to_sym end @@ -65,10 +88,42 @@ def terminal_states @states.reject { |s| forward_targets(s).any? } end - # Terminal states that represent successful completion (everything that is - # terminal except the reject state). + # Terminal states that represent successful completion: terminal via the + # forward flow and not reachable only as an off-ramp (reject or a custom + # action target). This keeps +approved?+ true for genuine end states only. def approval_terminal_states - terminal_states - [reject_state].compact + terminal_states - [reject_state].compact - action_target_states + end + + # Every state that ends the workflow: successful terminals, the reject + # state, and any custom-action target that has no forward transition out + # (e.g. a +cancel+ action's +cancelled+ state). Off-ramp targets that loop + # back (e.g. +changes_requested+ -> re-submit) stay in flight, not finalized. + def finalized_states + terminal_action_targets = action_target_states.select { |s| forward_targets(s).empty? } + (approval_terminal_states + [reject_state].compact + terminal_action_targets).uniq + end + + # The distinct set of states reachable via custom actions. + def action_target_states + @actions.values.map { |spec| spec[:to] }.uniq + end + + def action_names + @actions.keys + end + + def action_for(name) + @actions[name.to_sym] + end + + # States a custom action may be invoked from. An explicit +from:+ wins; + # otherwise any non-finalized state except the action's own target. + def action_allowed_from(name) + spec = @actions.fetch(name.to_sym) + return spec[:from] if spec[:from] + + states - finalized_states - [spec[:to]] end def guard_for(state) @@ -111,6 +166,7 @@ def validate! validate_transitions! validate_reject_state! validate_authorizations! + validate_actions! self end @@ -155,5 +211,28 @@ def validate_authorizations! "allow_transition references undeclared state #{state.inspect}" end end + + def validate_actions! + @actions.each do |name, spec| + if RESERVED_ACTIONS.include?(name) + raise DefinitionError, + "action #{name.inspect} is reserved; #{name}! is a built-in verb" + end + + unless @states.include?(spec[:to]) + raise DefinitionError, + "action #{name.inspect} targets undeclared state #{spec[:to].inspect}" + end + + next unless spec[:from] + + spec[:from].each do |from| + next if @states.include?(from) + + raise DefinitionError, + "action #{name.inspect} references undeclared from-state #{from.inspect}" + end + end + end end end diff --git a/lib/signoff/dsl.rb b/lib/signoff/dsl.rb index babf5ea..1f4747c 100644 --- a/lib/signoff/dsl.rb +++ b/lib/signoff/dsl.rb @@ -47,7 +47,9 @@ def initial_state(name) @definition.initial_state = name end - # Declare a forward transition. +to+ accepts a single state or an array. + # Declare a forward transition. Both +from+ and +to+ accept a single state + # or an array, so several source states can share one forward edge + # (e.g. +transition [:draft, :rejected], to: :review+). def transition(from, to:) @definition.add_transition(from, to) end @@ -57,6 +59,22 @@ def reject_to(state) @definition.reject_state = state end + # Declare a named custom action. It generates a +name!+ transition method + # and a +can_name?+ predicate on the model, records an event whose +action+ + # is the name verbatim, and is authorized by the same +allow_transition+ + # guard as the source state. Like +reject+, the target is a side-transition + # (never a forward edge), so +approve!+ stays unambiguous. This is the + # extension point for modelling any workflow verb beyond submit/approve/reject. + # + # action :request_changes, from: :pending_review, to: :changes_requested + # action :cancel, to: :cancelled # from any in-flight state + # + # +from+ is optional and may be a single state or an array; when omitted the + # action is allowed from every non-finalized state except its own target. + def action(name, to:, from: nil) + @definition.add_action(name, to: to, from: from) + end + # Authorize transitions out of +from_state+. The block receives the acting # user (and optionally the record) and must return a truthy value to allow # the transition. diff --git a/lib/signoff/model.rb b/lib/signoff/model.rb index b78da68..e994405 100644 --- a/lib/signoff/model.rb +++ b/lib/signoff/model.rb @@ -47,6 +47,7 @@ def signoff(column: nil, &block) dependent: Signoff.configuration.dependent _define_signoff_predicates(definition) + _define_signoff_actions(definition) definition end @@ -84,11 +85,11 @@ def rejected reject_state ? in_state(reject_state) : none end - # Records that are neither approved nor rejected (still in flight). + # Records that are neither approved nor rejected (still in flight). A + # custom-action off-ramp that loops back (e.g. +changes_requested+) counts + # as in flight; one that terminates (e.g. +cancelled+) counts as finalized. def pending - definition = signoff_definition! - finalized = (definition.approval_terminal_states + - [definition.reject_state].compact).map(&:to_s) + finalized = signoff_definition!.finalized_states.map(&:to_s) finalized.empty? ? all : where.not(signoff_column => finalized) end @@ -103,6 +104,26 @@ def _define_signoff_predicates(definition) define_method(predicate) { current_state == state } end end + + # For each declared custom action, generate a +name!+ transition method + # and a +can_name?+ predicate, mirroring the built-in approve!/can_approve?. + def _define_signoff_actions(definition) + definition.action_names.each do |name| + bang = "#{name}!" + unless method_defined?(bang) || private_method_defined?(bang) + define_method(bang) do |user: nil, comment: nil, metadata: {}, + ip_address: nil, user_agent: nil| + _perform_action!(name, user: user, comment: comment, metadata: metadata, + ip_address: ip_address, user_agent: user_agent) + end + end + + predicate = "can_#{name}?" + next if method_defined?(predicate) || private_method_defined?(predicate) + + define_method(predicate) { |user = nil| _can_perform_action?(name, user) } + end + end end # --- state ----------------------------------------------------------- @@ -125,7 +146,7 @@ def rejected? end def pending? - !approved? && !rejected? + !self.class.signoff_definition!.finalized_states.include?(current_state) end # --- transitions ----------------------------------------------------- @@ -241,6 +262,36 @@ def _advance!(action:, to:, user:, comment:, metadata:, ip_address:, user_agent: ip_address: ip_address, user_agent: user_agent) end + # Drive a declared custom action: validate the current state is a permitted + # source, then record an event whose action is the verb name verbatim. + def _perform_action!(name, user:, comment:, metadata:, ip_address:, user_agent:) + definition = self.class.signoff_definition! + spec = definition.action_for(name) + unless spec + raise InvalidTransitionError, "no action #{name.inspect} declared for #{self.class.name}" + end + + from = current_state + allowed = definition.action_allowed_from(name) + unless allowed.include?(from) + raise InvalidTransitionError, + "cannot #{name} from #{from.inspect} " \ + "(allowed from: #{allowed.inspect})" + end + + _perform_transition!(action: name.to_s, from: from, to: spec[:to], user: user, + comment: comment, metadata: metadata, + ip_address: ip_address, user_agent: user_agent) + end + + def _can_perform_action?(name, user) + definition = self.class.signoff_definition! + return false unless definition.action_for(name) + return false unless definition.action_allowed_from(name).include?(current_state) + + _guard_satisfied?(current_state, user || Signoff::Current.user) + end + def _perform_transition!(action:, from:, to:, user:, comment:, metadata:, ip_address:, user_agent:) if new_record? diff --git a/lib/signoff/version.rb b/lib/signoff/version.rb index 8d2f0af..69f18e6 100644 --- a/lib/signoff/version.rb +++ b/lib/signoff/version.rb @@ -1,5 +1,5 @@ # frozen_string_literal: true module Signoff - VERSION = "0.1.0" + VERSION = "0.2.0" end diff --git a/sig/signoff.rbs b/sig/signoff.rbs index 6fc3c46..e2e8a0a 100644 --- a/sig/signoff.rbs +++ b/sig/signoff.rbs @@ -38,8 +38,11 @@ module Signoff end class Definition + RESERVED_ACTIONS: Array[Symbol] + attr_reader states: Array[Symbol] attr_reader transitions: Hash[Symbol, Array[Symbol]] + attr_reader actions: Hash[Symbol, Hash[Symbol, untyped]] attr_reader reject_state: Symbol? attr_reader state_column: Symbol @@ -47,6 +50,12 @@ module Signoff def forward_targets: (Symbol | String) -> Array[Symbol] def terminal_states: () -> Array[Symbol] def approval_terminal_states: () -> Array[Symbol] + def finalized_states: () -> Array[Symbol] + def action_target_states: () -> Array[Symbol] + def action_names: () -> Array[Symbol] + def action_for: (Symbol | String) -> Hash[Symbol, untyped]? + def action_allowed_from: (Symbol | String) -> Array[Symbol] + def add_action: (Symbol | String, to: (Symbol | String), ?from: (Symbol | String | Array[Symbol | String])?) -> void def next_state: (Symbol | String, ?to: (Symbol | String)?) -> Symbol def validate!: () -> Definition end diff --git a/spec/signoff/custom_actions_spec.rb b/spec/signoff/custom_actions_spec.rb new file mode 100644 index 0000000..0e89da5 --- /dev/null +++ b/spec/signoff/custom_actions_spec.rb @@ -0,0 +1,209 @@ +# frozen_string_literal: true + +RSpec.describe "custom actions" do + let(:manager) { create(:manager) } + let(:employee) { create(:user) } + + def in_review_article + article = create(:article) + article.submit! # draft -> in_review (no guard on draft) + article + end + + describe "definition validation" do + def build(&block) + definition = Signoff::Definition.new + Signoff::DSL.new(definition).instance_eval(&block) + definition.validate! + end + + it "rejects a reserved action name" do + expect do + build do + state :a + state :b + action :approve, to: :b + end + end.to raise_error(Signoff::DefinitionError, /reserved/) + end + + it "rejects an action targeting an undeclared state" do + expect do + build do + state :a + action :archive, to: :nowhere + end + end.to raise_error(Signoff::DefinitionError, /undeclared state :nowhere/) + end + + it "rejects an action with an undeclared from-state" do + expect do + build do + state :a + state :b + action :archive, from: :ghost, to: :b + end + end.to raise_error(Signoff::DefinitionError, /undeclared from-state :ghost/) + end + + it "rejects a duplicate action" do + expect do + build do + state :a + state :b + action :archive, to: :b + action :archive, to: :b + end + end.to raise_error(Signoff::DefinitionError, /duplicate action :archive/) + end + + it "rejects an action with no target state" do + definition = Signoff::Definition.new + expect { definition.add_action(:archive, to: nil) } + .to raise_error(Signoff::DefinitionError, /requires a :to state/) + end + end + + describe "generated transition method" do + it "moves to the target and records the verb verbatim as the action" do + article = in_review_article + event = article.request_changes!(user: manager, comment: "tighten the intro") + + expect(article.current_state).to eq(:changes_requested) + expect(article).to be_changes_requested + expect(event.action).to eq("request_changes") + expect(event.from_state).to eq("in_review") + expect(event.to_state).to eq("changes_requested") + expect(event.comment).to eq("tighten the intro") + end + + it "stores metadata on the event" do + article = in_review_article + event = article.request_changes!(user: manager, metadata: { round: 2 }) + expect(event.metadata).to eq("round" => 2) + end + + it "does not make a single forward transition ambiguous" do + # in_review has one forward edge (-> approved); request_changes/cancel are + # side transitions, so approve! must still work without an explicit to:. + article = in_review_article + expect { article.approve!(user: manager) }.not_to raise_error + expect(article.current_state).to eq(:approved) + end + + it "loops back into the workflow via re-submission" do + article = in_review_article + article.request_changes!(user: manager) + event = article.submit! # changes_requested -> in_review again + + expect(article.current_state).to eq(:in_review) + expect(event.action).to eq("submit") + expect(event.from_state).to eq("changes_requested") + end + + it "raises InvalidTransitionError from a disallowed source state" do + article = create(:article) # draft; request_changes is from: :in_review only + expect { article.request_changes!(user: manager) } + .to raise_error(Signoff::InvalidTransitionError, /cannot request_changes from :draft/) + end + + it "is governed by the source state's allow_transition guard" do + article = in_review_article + expect { article.request_changes!(user: employee) } + .to raise_error(Signoff::UnauthorizedError) + expect(article.reload.current_state).to eq(:in_review) + end + + it "requires a user when the source state is guarded" do + article = in_review_article + expect { article.request_changes! } + .to raise_error(Signoff::UnauthorizedError, /user is required/) + end + + it "guards against the internal driver being called with an unknown action" do + expect do + create(:article).send(:_perform_action!, :nope, user: nil, comment: nil, + metadata: {}, ip_address: nil, + user_agent: nil) + end.to raise_error(Signoff::InvalidTransitionError, /no action :nope declared/) + end + end + + describe "generated can_? predicate" do + it "is true from an allowed, authorized state" do + expect(in_review_article.can_request_changes?(manager)).to be(true) + end + + it "is false when the guard rejects the user" do + expect(in_review_article.can_request_changes?(employee)).to be(false) + end + + it "is false from a disallowed source state" do + expect(create(:article).can_request_changes?(manager)).to be(false) + end + + it "never raises" do + expect { create(:article).can_request_changes?(nil) }.not_to raise_error + end + end + + describe "implicit allowed-from (no :from given)" do + it "permits the action from any non-finalized state" do + article = create(:article) # draft -> no guard for cancel from draft + event = article.cancel! + expect(article.current_state).to eq(:cancelled) + expect(event.action).to eq("cancel") + end + + it "inherits the source state's guard when one exists" do + article = in_review_article # cancel from in_review is guarded + expect { article.cancel!(user: employee) } + .to raise_error(Signoff::UnauthorizedError) + expect(article.cancel!(user: manager).action).to eq("cancel") + end + + it "refuses to act on a finalized record" do + article = in_review_article + article.approve!(user: manager) # -> approved (finalized) + expect { article.cancel!(user: manager) } + .to raise_error(Signoff::InvalidTransitionError, /cannot cancel from :approved/) + end + end + + describe "state classification" do + it "treats a looping off-ramp target as in-flight, not approved/rejected" do + article = in_review_article + article.request_changes!(user: manager) + + expect(article).to be_pending + expect(article).not_to be_approved + expect(article).not_to be_rejected + end + + it "treats a terminal off-ramp target as finalized, not approved/pending" do + article = create(:article) + article.cancel! + + expect(article).not_to be_pending + expect(article).not_to be_approved + expect(article).not_to be_rejected + end + + it "excludes custom-action targets from the approved scope" do + approved = in_review_article.tap { |a| a.approve!(user: manager) } + cancelled = create(:article).tap(&:cancel!) + changes = in_review_article.tap { |a| a.request_changes!(user: manager) } + + expect(Article.approved).to contain_exactly(approved) + expect(Article.approved).not_to include(cancelled, changes) + end + + it "keeps looping off-ramps in the pending scope but excludes terminal ones" do + changes = in_review_article.tap { |a| a.request_changes!(user: manager) } + cancelled = create(:article).tap(&:cancel!) + + expect(Article.pending).to include(changes) + expect(Article.pending).not_to include(cancelled) + end + end +end diff --git a/spec/support/factories.rb b/spec/support/factories.rb index 7a5ee5b..569ad7f 100644 --- a/spec/support/factories.rb +++ b/spec/support/factories.rb @@ -28,4 +28,8 @@ factory :document do sequence(:title) { |n| "Document ##{n}" } end + + factory :article do + sequence(:title) { |n| "Article ##{n}" } + end end diff --git a/spec/support/models.rb b/spec/support/models.rb index f3ea537..c26d8cc 100644 --- a/spec/support/models.rb +++ b/spec/support/models.rb @@ -85,6 +85,30 @@ class Document < ActiveRecord::Base end end +# Custom actions: a three-way decision (approve / reject / request_changes) +# whose off-ramp loops back via re-submission, plus a terminal off-ramp +# (cancel) to exercise finalized-state classification and the implicit +# (no +from:+) allowed-source default. +class Article < ActiveRecord::Base + include Signoff + + signoff do + states :draft, :in_review, :approved, :rejected, :changes_requested, :cancelled + + transition %i[draft rejected changes_requested], to: :in_review + transition :in_review, to: :approved + + reject_to :rejected + + action :request_changes, from: :in_review, to: :changes_requested + action :cancel, to: :cancelled + + allow_transition :in_review do |user| + user.manager? + end + end +end + # Has a validation; used to exercise validate_on_transition and rollback. class StrictReport < ActiveRecord::Base include Signoff diff --git a/spec/support/schema.rb b/spec/support/schema.rb index e7f72c4..e38e6f4 100644 --- a/spec/support/schema.rb +++ b/spec/support/schema.rb @@ -30,6 +30,12 @@ t.timestamps end + create_table :articles, force: true do |t| + t.string :title + t.string :approval_state + t.timestamps + end + create_table :strict_reports, force: true do |t| t.string :title t.string :approval_state