state_gate 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c914825dceae121cfabc62d93c48e952d0d1ae4995bc0e477d1e2aa2e0cf9107
-  data.tar.gz: e49f5d7fd2517d88a7ae8c225baa452c75aa6cba94828e2e182fcb3462ffccec
+  metadata.gz: a4ac3088aa966d3650145f5294d93731291dcd39397597dbb7d35eb69adb5a17
+  data.tar.gz: 4e8d593dd1facb0757146b580f3f05c6cfb335c2b163cfa0f09f12d5b072e55d
 SHA512:
-  metadata.gz: 1042ce00609a2501647803fce1a41b689c45084726011c6f0f36e2498b9ca48110cf7d99160311eed74204f939255332be79894056098ccf2c1883dd88d0e6da
-  data.tar.gz: ba89c3bd3d36181c109ab56d5d9a6d8f68f735bfc645075d3dd16f2e8c7f829ff82746ef1db093f76743d05532159b864e75f78a4e960389d22c8ad818d76f84
+  metadata.gz: 90471292a3c2be72e97274785d6934104ce2b3014d424bb4b91517de0d1ccade7f735c2ff6ca4ddfadcfae716d985708b3eb106466b9a0d8eb2c8ed59ab42a6b
+  data.tar.gz: 9afb2f7c2d284cf6456a61637403bb513c20bf2a93a37229059ae81c97e11731f0a2c5746b8ea4a2d797bbb7b8ad745b0d4c491b16746b64ec12d75df5c984a9

data/lib/state_gate/assertions.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module StateGate
+  ##
+  # = Description
+  #
+  # Minitest assertions to verify StateGate defined states and transitions.
+  #
+  # The Minitest equivalent of the StateGate RSpec +have_states+ and
+  # +allow_transitions_on+ matchers.
+  #
+  # [:source_obj]
+  #   The Class or Instance to be tested.
+  #
+  # [:attribute]
+  #   The attribute being tested.
+  #
+  # [:states]
+  #   The expected states as Symbols or Strings.
+  #
+  # [:from]
+  #   The state being transitioned from.
+  #
+  # [:to]
+  #   The states being transitioned to, as a Symbol, String or Array.
+  #
+  #   assert_has_states Sysop, :status, :pending, :active
+  #   refute_has_states Sysop, :status, :deleted
+  #
+  #   assert_allows_transitions Sysop, :status, from: :active, to: [:locked, :archived]
+  #   refute_allows_transitions Sysop, :status, from: :active, to: :pending
+  #
+  # +assert_has_states+ fails if an existing state is missing, or if given
+  # states are not defined for the attribute.
+  #
+  # +refute_has_states+ fails if any of the given states are defined for
+  # the attribute.
+  #
+  # +assert_allows_transitions+ fails if an allowed transition is missing, or
+  # if a given transition is not allowed.
+  #
+  # +refute_allows_transitions+ fails if any of the given transitions are
+  # allowed for the state.
+  #
+  module Assertions
+  
+    #  States
+    # ======================================================================
+  
+    ##
+    # Asserts the given states are exactly the states defined for the attribute.
+    #
+    #   assert_has_states Sysop, :status, :pending, :active, :locked
+    #   assert_has_states sysop, :status, %w[pending active locked]
+    #
+    def assert_has_states(source_obj, attribute, *states)
+      engine   = state_gate_engine(source_obj, attribute)
+      key      = StateGate.symbolize(attribute)
+      expected = state_gate_symbolize_states(states)
+  
+      missing  = engine.states - expected
+      extra    = expected      - engine.states
+  
+      return pass if missing.empty? && extra.empty?
+  
+      messages = []
+      messages << state_gate_also_valid_message(missing, key) if missing.any?
+      messages << state_gate_not_valid_message(extra, key)    if extra.any?
+  
+      flunk messages.join(' ')
+    end
+  
+  
+    ##
+    # Asserts none of the given states are defined for the attribute.
+    #
+    #   refute_has_states Sysop, :status, :deleted, :banned
+    #
+    def refute_has_states(source_obj, attribute, *states)
+      engine   = state_gate_engine(source_obj, attribute)
+      key      = StateGate.symbolize(attribute)
+      expected = state_gate_symbolize_states(states)
+  
+      found    = expected.select { |s| engine.states.include?(s) }
+  
+      return pass if found.empty?
+  
+      if found.one?
+        flunk "#{state_gate_list(found)} is a valid state for ##{key}."
+      else
+        flunk "#{state_gate_list(found)} are valid states for ##{key}."
+      end
+    end
+  
+  
+    #  Transitions
+    # ======================================================================
+  
+    ##
+    # Asserts the given states are exactly the transitions allowed from the
+    # +:from+ state.
+    #
+    #   assert_allows_transitions Sysop, :status, from: :active,
+    #                                             to: [:locked, :suspended, :archived]
+    #   assert_allows_transitions sysop, :status, from: :pending, to: :active
+    #
+    def assert_allows_transitions(source_obj, attribute, from: nil, to: nil)
+      key, engine, state, expected = state_gate_transition_setup(source_obj, attribute, from, to)
+  
+      allowed = engine.transitions_for_state(state)
+      missing = allowed  - expected
+      extra   = expected - allowed
+  
+      return pass if missing.empty? && extra.empty?
+  
+      messages = []
+      if missing.any?
+        messages << "##{key} also transitions from :#{state} to #{state_gate_list(missing)}."
+      end
+      if extra.any?
+        messages << "##{key} does not transition from :#{state} to #{state_gate_list(extra)}."
+      end
+  
+      flunk messages.join(' ')
+    end
+  
+  
+    ##
+    # Asserts none of the given states are transitions allowed from the
+    # +:from+ state.
+    #
+    #   refute_allows_transitions Sysop, :status, from: :archived, to: [:locked, :suspended]
+    #
+    def refute_allows_transitions(source_obj, attribute, from: nil, to: nil)
+      _key, engine, state, expected = state_gate_transition_setup(source_obj, attribute, from, to)
+  
+      found = expected & engine.transitions_for_state(state)
+  
+      return pass if found.empty?
+  
+      flunk ":#{state} is allowed to transition to #{state_gate_list(found)}."
+    end
+  
+  
+    #  Helpers
+    # ======================================================================
+  
+    private
+  
+    ##
+    # Returns the StateGate engine for the attribute, flunking with the
+    # relevant message when the setup is incomplete or incorrect.
+    #
+    def state_gate_engine(source_obj, attribute) # :nodoc:
+      key = StateGate.symbolize(attribute)
+  
+      flunk 'missing the <attribute> to be tested.' if key.blank?
+  
+      unless source_obj.respond_to?(:stateables)
+        flunk "no state machines are defined for #{state_gate_source_name(source_obj)}."
+      end
+  
+      engine = source_obj.stateables[key]
+      flunk "no state machine is defined for ##{key}." if engine.blank?
+  
+      engine
+    end
+  
+  
+    ##
+    # Validates the transition parameters, returning the attribute key, the
+    # engine, the +:from+ state and the expected +:to+ states.
+    #
+    def state_gate_transition_setup(source_obj, attribute, from, to) # :nodoc:
+      engine = state_gate_engine(source_obj, attribute)
+      key    = StateGate.symbolize(attribute)
+  
+      flunk 'missing the <from:> state.' if from.blank?
+      flunk 'missing the <to:> states.'  if to.nil?
+  
+      state = state_gate_symbolize_states([from]).first
+      unless engine.states.include?(state)
+        flunk ":#{state} is not a valid state for #{state_gate_source_name(source_obj)}##{key}."
+      end
+  
+      expected = state_gate_symbolize_states(Array(to))
+      invalid  = expected.reject { |s| engine.states.include?(s) }
+  
+      if invalid.one?
+        flunk "#{state_gate_list(invalid)} is not a valid ##{key} state."
+      elsif invalid.any?
+        flunk "#{state_gate_list(invalid)} are not valid ##{key} states."
+      end
+  
+      [key, engine, state, expected]
+    end
+  
+  
+    ##
+    # The name of the Class or Instance being tested.
+    #
+    def state_gate_source_name(source_obj) # :nodoc:
+      source_obj.is_a?(Class) ? source_obj.name : source_obj.class.name
+    end
+  
+  
+    ##
+    # Flattens and symbolizes the given state names.
+    #
+    def state_gate_symbolize_states(states) # :nodoc:
+      states.flatten.map do |state|
+        StateGate.symbolize(state) || flunk("\"#{state}\" is not a valid state name.")
+      end
+    end
+  
+  
+    # ":pending, :active, and :locked"
+    #
+    def state_gate_list(states) # :nodoc:
+      states.map { |s| ":#{s}" }.to_sentence
+    end
+  
+  
+    # "...is also a valid state for #status."
+    #
+    def state_gate_also_valid_message(missing, key) # :nodoc:
+      if missing.one?
+        "#{state_gate_list(missing)} is also a valid state for ##{key}."
+      else
+        "#{state_gate_list(missing)} are also valid states for ##{key}."
+      end
+    end
+  
+  
+    # "...is not a valid state for #status."
+    #
+    def state_gate_not_valid_message(extra, key) # :nodoc:
+      if extra.one?
+        "#{state_gate_list(extra)} is not a valid state for ##{key}."
+      else
+        "#{state_gate_list(extra)} are not valid states for ##{key}."
+      end
+    end
+  
+  end # Assertions
+end # StateGate

data/lib/state_gate/engine/configurator.rb

@@ -129,10 +129,14 @@ module StateGate
       # - verify all transitions lead to existing states
       # - verify each state, except the default, can be reached from a transition
       #
+      # @note
+      # - gsub both ways to account for ruby 3.4 message change
+      #
       def _exec_configuration(&config)
         instance_exec(&config)
       rescue NameError => e
         err_command = e.to_s.gsub('undefined local variable or method `', '')
+                       .to_s.gsub("undefined local variable or method '", '')
                        .split("'")
                        .first
         _cerr :bad_command, cmd: err_command

data/lib/state_gate/version.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+##
+# Version for StateGate
+#
+module StateGate
+
+  ##
+  # Returns the gem version.
+  #
+  # @return [Gem::Version]
+  #
+  def self.gem_version
+    Gem::Version.new VERSION::STRING
+  end
+
+  ##
+  # EncodedToken::VERSION
+  #
+  #   This module represent the current version.
+  #
+  module VERSION
+
+    MAJOR = 2
+    MINOR = 0
+    TINY  = 0
+    # MICRO = ''
+
+    STRING = [MAJOR, MINOR, TINY].compact.join(".")
+    # STRING = [MAJOR, MINOR, TINY, MICRO].compact.join(".")
+
+  end
+
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: state_gate
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.0.0
 platform: ruby
 authors:
 - CodeMeister
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-21 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -24,14 +23,15 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 5.0.0.beta1
-description: "     State management for ActiveRecord, with states; transitions; and
-  \    just the right amount of syntactic sugar.   "
+description: "     State Management for ActiveRecord, with strict states & transitions.
+  \  "
 email: state_gate@codemeister.dev
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/state_gate.rb
+- lib/state_gate/assertions.rb
 - lib/state_gate/builder.rb
 - lib/state_gate/builder/conflict_detection_methods.rb
 - lib/state_gate/builder/dynamic_module_creation_methods.rb
@@ -54,6 +54,7 @@ files:
 - lib/state_gate/rspec/allow_transitions_on.rb
 - lib/state_gate/rspec/have_states.rb
 - lib/state_gate/type.rb
+- lib/state_gate/version.rb
 homepage: https://github.com/Rubology/state_gate
 licenses:
 - MIT
@@ -61,7 +62,6 @@ metadata:
   homepage_uri: https://github.com/Rubology/state_gate
   source_code_uri: https://github.com/Rubology/state_gate
   changelog_uri: https://github.com/Rubology/state_gate/blob/master/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -69,15 +69,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
-signing_key:
+rubygems_version: 4.0.18
 specification_version: 4
-summary: State management for ActiveRecord.
+summary: State Management for ActiveRecord.
 test_files: []