statecraft 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55f4ecb6760d01b042ad158351ec8735c3962c70c3a674d3af9d6ba2ecf26fd9
-  data.tar.gz: ecc0c3ac410d67431226ccc8b361ac5d2708c276425153561b0f732ef3aefa53
+  metadata.gz: 4689cea0dee40236473975f52ea5ccd2ecd303783edebd7626ab1518a1f8c8bd
+  data.tar.gz: b3713ea5d55ea4881b55b10ceccb38847f2f85aa971d29326fd26e97412d0620
 SHA512:
-  metadata.gz: caf25d1b5349c441aa79573e1994b2298ef64fcc4b4b9f6e6b5958827ca03a9bf8275366cf1b128a4cf39f690e6ba9bcad0327b040a51effcf42f5fff9853098
-  data.tar.gz: 7acc79611c73b980a2a932c53d87723068adb1da7ddc61b590477cf84540a904750e9fa7d550d126aa9626f9edcc34538f6aed4aacb611894907148d80e07b63
+  metadata.gz: 9690fff2fb62feaaea147a53c63113a77dc93103432ad3f5aa63b5593173d513d2abf83d5d53decf0d6eed7347d94509197f5bb0d03077cdbd5a98f1f20cefd4
+  data.tar.gz: cbd7e8d84af570a4c2cb1e51582262860b2d6d0cd7d87ed0304528413ca1d34720dbe6c9b4186fab5a68639c6814243ed2fed32f9774d4985a5f4f5408b45ede

data/README.md

@@ -260,6 +260,51 @@ belong to the application's presentation layer, not to the machine.
 A guard that reads metadata makes `may_*?` depend on the metadata you pass —
 pass the same metadata to `may_*?` that you will collect for `fire!`.
 
+## RSpec matchers
+
+One opt-in require gives your specs matchers over the whole introspection
+surface — RSpec never becomes a runtime dependency of the gem:
+
+<!-- illustrative -->
+```ruby
+# spec_helper.rb, after rspec itself is loaded
+require "statecraft/rspec"
+```
+
+<!-- illustrative -->
+```ruby
+# The record-level questions consult the guards, with the same metadata
+# your production call will carry:
+expect(order).to allow_event(:pay).with_metadata("amount" => 100)
+expect(order).to allow_transition_to(:cancelled).via(:cancel)
+expect(order).to allow_transition_to(:archived).directly
+expect(order).to have_transitioned_to(:paid)  # strictly log-based
+
+# The refusal with its reason — guard names come from refusals_for:
+expect(order).to refuse_event(:cancel).because_of(:customer_cancellable?)
+
+# The class-level pair answers the graph's shape; guards stay untouched:
+expect(OrderFlow).to have_edge(:pending, :cancelled).via(:cancel)
+expect(OrderFlow).to have_initial_state(:pending)
+
+# The transition itself: the state move AND the appended log row,
+# asserted in one expression around fire!/transition_to!:
+expect { order.fire!(:pay, metadata: { "amount" => 100 }) }
+  .to transition(order).from(:pending).to(:paid)
+      .via_event(:pay).with_metadata("amount" => 100)
+```
+
+A failing matcher explains itself with the same introspection the pipeline
+consults: the current state, the edges reachable from it, and the refusing
+guard with its layer. A non-bang call that returned `false` fails the
+`transition` matcher the same way; exceptions of the bang forms fly through
+like with `change` — assert refusals with `refuse_event` or `raise_error`,
+not with the block matcher.
+
+`because_of` carries the same honest limit as `refusals_for` underneath it:
+it names record-layer guards only. An input-reading `guard:` has no name
+there, and the failure message says so instead of guessing.
+
 ## Metadata
 
 Metadata is normalized on pipeline entry with a full JSON round-trip —

data/lib/statecraft/rspec/allow_event.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to allow_event(:pay).with_metadata("amount" => 5)
+    #
+    # The can_fire? question, asked with the same metadata the production
+    # call will carry. The failure message walks the layers the pipeline
+    # walks: is the event declared from this state, and if so, which
+    # guards said no.
+    class AllowEvent
+      def initialize(event_name)
+        @event_name = event_name.to_sym
+        @metadata = {}
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def matches?(record)
+        @record = record
+        record.can_fire?(@event_name, metadata: @metadata)
+      end
+
+      def failure_message
+        lines = ["expected #{StateReport.standing(@record)} to allow event #{@event_name.inspect}, but it was refused"]
+        if StateReport.event_declared?(@record, @event_name)
+          lines << StateReport.refusal(@record, @event_name, @metadata)
+        else
+          lines << "event #{@event_name.inspect} is not declared from #{StateReport.current_state(@record).inspect}"
+          lines << StateReport.declared_shape_of(@record)
+        end
+        lines.join("\n  ")
+      end
+
+      def failure_message_when_negated
+        "expected #{StateReport.standing(@record)} not to allow event #{@event_name.inspect}, " \
+          "but the guards passed with metadata #{@metadata.inspect}"
+      end
+
+      def description
+        "allow event #{@event_name.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/allow_transition_to.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to allow_transition_to(:paid).via(:pay)
+    # expect(record).to allow_transition_to(:archived).directly
+    #
+    # The available_transitions prediction for one target: not only
+    # whether the record can go there, but HOW — via lists the events
+    # whose guards pass, directly asserts the guard-free direct way.
+    class AllowTransitionTo
+      def initialize(target_state)
+        @target_state = target_state.to_sym
+        @expected_via = []
+        @directly = false
+        @metadata = {}
+      end
+
+      def via(*event_names)
+        @expected_via = event_names.map(&:to_sym)
+        self
+      end
+
+      def directly
+        @directly = true
+        self
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def matches?(record)
+        @record = record
+        @availability = record.available_transitions(metadata: @metadata)
+                              .find { |availability| availability.to == @target_state }
+        return false unless @availability
+
+        missing_ways.empty?
+      end
+
+      def failure_message
+        unless @availability
+          return ["expected #{StateReport.standing(@record)} to reach #{@target_state.inspect}, but it cannot",
+                  StateReport.reachable(@record, @metadata),
+                  StateReport.declared_shape_of(@record)].join("\n  ")
+        end
+
+        "expected the way to #{@target_state.inspect} to include #{missing_ways.map(&:inspect).join(", ")}, " \
+          "but it is reachable via #{@availability.via.inspect}"
+      end
+
+      def failure_message_when_negated
+        "expected #{StateReport.standing(@record)} not to reach #{@target_state.inspect}, " \
+          "but it is reachable via #{@availability.via.inspect}"
+      end
+
+      def description
+        "allow a transition to #{@target_state.inspect}"
+      end
+
+      private
+
+      def missing_ways
+        expected = @expected_via + (@directly ? [:direct] : [])
+        expected - @availability.via
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/have_edge.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(OrderFlow).to have_edge(:pending, :cancelled).via(:cancel)
+    #
+    # The class-level shape question of transitions_from: no guards are
+    # consulted, exactly like the method itself. via asserts that the
+    # named events ride the edge; a bare edge simply has none.
+    class HaveEdge
+      def initialize(from_state, to_state)
+        @from_state = from_state.to_sym
+        @to_state = to_state.to_sym
+        @expected_events = []
+      end
+
+      def via(*event_names)
+        @expected_events = event_names.map(&:to_sym)
+        self
+      end
+
+      def matches?(machine_class)
+        @machine_class = machine_class
+        @edge = machine_class.transitions_from(@from_state)
+                             .find { |descriptor| descriptor[:to] == @to_state }
+        @edge && (@expected_events - @edge[:events]).empty?
+      end
+
+      def failure_message
+        unless @edge
+          return ["expected #{@machine_class.name} to declare an edge #{@from_state.inspect} -> #{@to_state.inspect}",
+                  StateReport.declared_shape(@machine_class, @from_state)].join("\n  ")
+        end
+
+        missing = (@expected_events - @edge[:events]).map(&:inspect).join(", ")
+        "expected the edge #{@from_state.inspect} -> #{@to_state.inspect} to carry #{missing}, " \
+          "but its events are #{@edge[:events].inspect}"
+      end
+
+      def failure_message_when_negated
+        "expected #{@machine_class.name} not to declare the edge #{@from_state.inspect} -> #{@to_state.inspect}, " \
+          "but it does (events: #{@edge[:events].inspect})"
+      end
+
+      def description
+        "have an edge #{@from_state.inspect} -> #{@to_state.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/have_initial_state.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(OrderFlow).to have_initial_state(:pending)
+    class HaveInitialState
+      def initialize(state_name)
+        @state_name = state_name.to_sym
+      end
+
+      def matches?(machine_class)
+        @machine_class = machine_class
+        machine_class.initial_state == @state_name
+      end
+
+      def failure_message
+        "expected the initial state of #{@machine_class.name} to be #{@state_name.inspect}, " \
+          "but it is #{@machine_class.initial_state.inspect}"
+      end
+
+      def failure_message_when_negated
+        "expected the initial state of #{@machine_class.name} not to be #{@state_name.inspect}, but it is"
+      end
+
+      def description
+        "have the initial state #{@state_name.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/have_transitioned_to.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to have_transitioned_to(:paid)
+    #
+    # Strictly log-based, like transitioned_to? itself: the question is
+    # about history, never about the current state. The failure message
+    # shows what the log actually holds.
+    class HaveTransitionedTo
+      def initialize(state_name)
+        @state_name = state_name.to_sym
+      end
+
+      def matches?(record)
+        @record = record
+        record.transitioned_to?(@state_name)
+      end
+
+      def failure_message
+        "expected the log of #{StateReport.standing(@record)} to hold a transition to #{@state_name.inspect}, " \
+          "but #{log_contents}"
+      end
+
+      def failure_message_when_negated
+        "expected the log of #{StateReport.standing(@record)} to hold no transition to #{@state_name.inspect}, " \
+          "but it does"
+      end
+
+      def description
+        "have transitioned to #{@state_name.inspect}"
+      end
+
+      private
+
+      def log_contents
+        to_states = @record.history.map(&:to_state)
+        return "the log is empty" if to_states.empty?
+
+        "the log holds transitions to: #{to_states.join(", ")}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/matchers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # The example-facing surface: requiring statecraft/rspec includes this
+    # module into every example group, so specs call the factories bare.
+    # Record-level matchers consult guards (a prediction with the metadata
+    # you pass); class-level matchers answer the graph's shape only.
+    # rubocop:disable Naming/PredicatePrefix -- have_* is RSpec's matcher idiom, not a predicate
+    module Matchers
+      def allow_event(event_name)
+        AllowEvent.new(event_name)
+      end
+
+      def refuse_event(event_name)
+        RefuseEvent.new(event_name)
+      end
+
+      def allow_transition_to(target_state)
+        AllowTransitionTo.new(target_state)
+      end
+
+      def have_transitioned_to(state_name)
+        HaveTransitionedTo.new(state_name)
+      end
+
+      def have_edge(from_state, to_state)
+        HaveEdge.new(from_state, to_state)
+      end
+
+      def have_initial_state(state_name)
+        HaveInitialState.new(state_name)
+      end
+
+      def transition(record)
+        Transition.new(record)
+      end
+    end
+    # rubocop:enable Naming/PredicatePrefix
+  end
+end

data/lib/statecraft/rspec/refuse_event.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to refuse_event(:cancel).because_of(:customer_cancellable?)
+    #
+    # The named negation of allow_event: the refusal itself, and — through
+    # because_of — WHO refused. Guard names come from refusals_for, so
+    # because_of sees record-layer guards only; an input-reading guard:
+    # has no name there, and the failure message says so instead of
+    # pretending otherwise.
+    class RefuseEvent
+      def initialize(event_name)
+        @event_name = event_name.to_sym
+        @expected_guards = []
+        @metadata = {}
+      end
+
+      def because_of(*guard_names)
+        @expected_guards = guard_names.map(&:to_sym)
+        self
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def matches?(record)
+        @record = record
+        @allowed = record.can_fire?(@event_name, metadata: @metadata)
+        return false if @allowed
+
+        @refusing_guards = record.refusals_for(@event_name).map(&:guard)
+        (@expected_guards - @refusing_guards).empty?
+      end
+
+      def failure_message
+        if @allowed
+          return "expected #{StateReport.standing(@record)} to refuse event #{@event_name.inspect}, " \
+                 "but the guards passed with metadata #{@metadata.inspect}"
+        end
+
+        missing = (@expected_guards - @refusing_guards).map(&:inspect).join(", ")
+        "expected the refusal of #{@event_name.inspect} to come from #{missing}\n  #{actual_refusers}"
+      end
+
+      def failure_message_when_negated
+        "expected #{StateReport.standing(@record)} to allow event #{@event_name.inspect}, but it was refused\n  " +
+          StateReport.refusal(@record, @event_name, @metadata)
+      end
+
+      def description
+        "refuse event #{@event_name.inspect}"
+      end
+
+      private
+
+      def actual_refusers
+        if @refusing_guards.empty?
+          "but no record-layer guard refused: refusals_for names record-layer guards only, " \
+            "and this refusal came from an input-reading guard: or an undeclared branch"
+        else
+          "but the refusing record-layer guards were: #{@refusing_guards.map(&:inspect).join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/state_report.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # The shared sentences of every failure message: where the record
+    # stands, what the graph declares from there, what is reachable right
+    # now, and which guards refused. Built strictly on the public
+    # introspection surface — the matchers add words, never new answers.
+    module StateReport
+      module_function
+
+      def current_state(record)
+        record[record.class.statecraft_mounting.column]&.to_sym
+      end
+
+      def standing(record)
+        "#{record.class.name} in state #{current_state(record).inspect}"
+      end
+
+      def machine(record)
+        record.class.statecraft_mounting.machine_class
+      end
+
+      def event_declared?(record, event_name)
+        machine(record).transitions_from(current_state(record))
+                       .any? { |descriptor| descriptor[:events].include?(event_name) }
+      end
+
+      def declared_shape(machine_class, state)
+        descriptors = machine_class.transitions_from(state)
+        return "no edges are declared from #{state.inspect}" if descriptors.empty?
+
+        rendered = descriptors.map do |descriptor|
+          if descriptor[:events].empty?
+            "to #{descriptor[:to].inspect} (direct)"
+          else
+            "to #{descriptor[:to].inspect} via #{descriptor[:events].inspect}"
+          end
+        end
+        "declared from #{state.inspect}: #{rendered.join("; ")}"
+      end
+
+      def declared_shape_of(record)
+        declared_shape(machine(record), current_state(record))
+      end
+
+      def reachable(record, metadata)
+        transitions = record.available_transitions(metadata: metadata)
+        state = current_state(record).inspect
+        return "nothing is reachable from #{state} right now" if transitions.empty?
+
+        rendered = transitions.map { |availability| "to #{availability.to.inspect} via #{availability.via.inspect}" }
+        "reachable from #{state}: #{rendered.join("; ")}"
+      end
+
+      def refusal(record, event_name, metadata)
+        refusals = record.refusals_for(event_name)
+        if refusals.empty?
+          "no record-layer guard refused — an input-reading guard: said no to metadata #{metadata.inspect}"
+        else
+          named = refusals.map { |entry| "#{entry.guard.inspect} (#{entry.layer})" }
+          "refused by record-layer guards: #{named.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/transition.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect { order.fire!(:pay) }.to transition(order)
+    #   .from(:pending).to(:paid).via_event(:pay).with_metadata("k" => "v")
+    #
+    # The transition through the eyes of a test: the state column moved to
+    # the target AND exactly one log row was appended with the matching
+    # from/to/event/metadata. A non-bang call that returned false leaves
+    # both untouched — the matcher fails and explains why, from the same
+    # introspection the pipeline consulted. Exceptions of the bang forms
+    # fly through, like with the change matcher: refusals are asserted
+    # with refuse_event or raise_error, not here.
+    class Transition
+      def initialize(record)
+        @record = record
+        @failures = []
+      end
+
+      def from(state_name)
+        @from_state = state_name.to_sym
+        self
+      end
+
+      def to(state_name)
+        @to_state = state_name.to_sym
+        self
+      end
+
+      def via_event(event_name)
+        @event_name = event_name.to_sym
+        self
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def matches?(block)
+        raise ArgumentError, "transition(record).to(:state) — the .to target is required" unless @to_state
+
+        @before_state = StateReport.current_state(@record)
+        appended_before = @record.history.count
+        block.call
+        @after_state = StateReport.current_state(@record)
+        @appended = @record.history.offset(appended_before).to_a
+        collect_failures
+        @failures.empty?
+      end
+
+      def failure_message
+        expected_event = " via event #{@event_name.inspect}" if @event_name
+        header = "expected the block to transition #{@record.class.name} " \
+                 "#{@before_state.inspect} -> #{@to_state.inspect}#{expected_event}"
+        ([header] + @failures).join("\n  ")
+      end
+
+      def failure_message_when_negated
+        row = @appended.last
+        written_by = " by event #{row.event.inspect}" if row.event
+        "expected the block not to transition #{@record.class.name} to #{@to_state.inspect}, " \
+          "but it did: #{row.from_state.inspect} -> #{row.to_state.inspect}#{written_by}"
+      end
+
+      def description
+        "transition #{@record.class.name} to #{@to_state.inspect}"
+      end
+
+      private
+
+      def collect_failures
+        return collect_missing_transition if @appended.empty?
+
+        if @appended.size > 1
+          @failures << "expected exactly one appended log row, but the block appended #{@appended.size}"
+        end
+        if @after_state != @to_state
+          @failures << "the record ended in #{@after_state.inspect}, not #{@to_state.inspect}"
+        end
+        collect_row_mismatches(@appended.last)
+      end
+
+      def collect_row_mismatches(row)
+        if row.to_state != @to_state.to_s
+          @failures << "the log row went to #{row.to_state.inspect}, not #{@to_state.inspect}"
+        end
+        if @from_state && row.from_state != @from_state.to_s
+          @failures << "the transition started from #{row.from_state.inspect}, not #{@from_state.inspect}"
+        end
+        if @event_name && row.event != @event_name.to_s
+          @failures << "the transition was written by event #{row.event.inspect}, not #{@event_name.inspect}"
+        end
+        collect_metadata_mismatch(row)
+      end
+
+      def collect_missing_transition
+        @failures << "no transition happened: the record stayed in #{@after_state.inspect}"
+        @failures << StateReport.reachable(@record, @metadata || {})
+        return unless @event_name && StateReport.event_declared?(@record, @event_name)
+
+        @failures << StateReport.refusal(@record, @event_name, @metadata || {})
+      end
+
+      def collect_metadata_mismatch(row)
+        return unless @metadata
+
+        expected = @metadata.deep_stringify_keys
+        return if row.metadata == expected
+
+        @failures << "the log row carries metadata #{row.metadata.inspect}, not #{expected.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "statecraft"
+
+# Deliberately not required by lib/statecraft.rb: the matchers exist only
+# where RSpec does, and the gem's runtime must not know about test
+# frameworks. This file is the one opt-in door.
+unless defined?(RSpec)
+  raise Statecraft::Error,
+        "statecraft/rspec builds RSpec matchers, so RSpec must be loaded first: " \
+        "require statecraft/rspec from your spec helper, after rspec itself"
+end
+
+require_relative "rspec/state_report"
+require_relative "rspec/allow_event"
+require_relative "rspec/refuse_event"
+require_relative "rspec/allow_transition_to"
+require_relative "rspec/have_transitioned_to"
+require_relative "rspec/have_edge"
+require_relative "rspec/have_initial_state"
+require_relative "rspec/transition"
+require_relative "rspec/matchers"
+
+RSpec.configure { |config| config.include Statecraft::RSpec::Matchers }

data/lib/statecraft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statecraft
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Igor Pugachev
@@ -87,6 +87,16 @@ files:
 - lib/statecraft/pipeline.rb
 - lib/statecraft/pipeline/edge_resolution.rb
 - lib/statecraft/pipeline/surface.rb
+- lib/statecraft/rspec.rb
+- lib/statecraft/rspec/allow_event.rb
+- lib/statecraft/rspec/allow_transition_to.rb
+- lib/statecraft/rspec/have_edge.rb
+- lib/statecraft/rspec/have_initial_state.rb
+- lib/statecraft/rspec/have_transitioned_to.rb
+- lib/statecraft/rspec/matchers.rb
+- lib/statecraft/rspec/refuse_event.rb
+- lib/statecraft/rspec/state_report.rb
+- lib/statecraft/rspec/transition.rb
 - lib/statecraft/version.rb
 - lib/statecraft/warnings.rb
 homepage: https://supostat.github.io/statecraft/