state_gate 1.2.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a3a28a8136472a91cd7c75616e189dd2c92a7b57a0bc18645395a46c55ff906
-  data.tar.gz: c909cd3d3a1101056ff1fe33ea6b94e38008f26a093476d7aaeb4ac17847b1ad
+  metadata.gz: a4ac3088aa966d3650145f5294d93731291dcd39397597dbb7d35eb69adb5a17
+  data.tar.gz: 4e8d593dd1facb0757146b580f3f05c6cfb335c2b163cfa0f09f12d5b072e55d
 SHA512:
-  metadata.gz: 6b9cae6865505456fafa9da807e8472eb148f8af294c7631690b28ebba7b01c20e93f27b2bbe3ccf16c7ec27ea872e604726323bebb7639c7e7db726eb4bdd34
-  data.tar.gz: 7c104de800820cedee61c177a44504e2e1f052aaf529fd4990d3407ae337a4004c925f12162762f2db66b34a96ecda327e06e0c96c4dfc299feef63885b0e6f6
+  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/builder/conflict_detection_methods.rb

@@ -14,54 +14,73 @@ module StateGate
       # ======================================================================
       private
 
+      ##
       # Check if a class method is already defined. Checks are made:
       # 1 --> is it an ActiveRecord dangerous method?
       # 2 --> is it an ActiveRecord defined class method?
       # 3 --> is it a singleton method of the klass?
       # 4 --> is it defined within any of the klass ancestors?
       #
-      # If found, raise an error giving a guide to where the method has been defined
+      # @param [Symbol] method_name
+      #   the class method name to test for conclict
       #
-      def detect_class_method_conflict!(method_name)
+      # @raise [ConflictError]
+      #   if the method name has already been defined
+      #
+      def _detect_class_method_conflict!(method_name)
         defining_klass = _active_record_protected_method?(method_name) ||
                          _klass_singleton_method?(method_name) ||
                          _klass_ancestor_singleton_method?(method_name)
 
         return unless defining_klass
 
-        raise_conflict_error method_name, type: 'a class', source: defining_klass
+        _raise_conflict_error method_name, type: 'a class', source: defining_klass
       end
 
 
 
+      ##
       # Check an instance method is already defined. Checks are made:
       # 1 --> is it an ActiveRecord dangerous method?
       # 2 --> is it an ActiveRecord defined instance method?
       # 3 --> is it an instance method of the klass?
       # 4 --> is it defined within any of the klass ancestors?
       #
-      # If found, raise an error giving a guide to where the method has been defined
+      # @param [Symbol] method_name
+      #   the instance method name to test for conclict
+      #
+      # @raise [ConflictError]
+      #   if the method name has already been defined
       #
-      def detect_instance_method_conflict!(method_name)
+      def _detect_instance_method_conflict!(method_name)
         defining_klass = _active_record_protected_method?(method_name) ||
                          _klass_instance_method?(method_name) ||
                          _klass_ancestor_instance_method?(method_name)
 
         return unless defining_klass
 
-        raise_conflict_error method_name, source: defining_klass
+        _raise_conflict_error method_name, source: defining_klass
       end
 
 
 
       # Raise a StateGate::ConflictError with a details message of the problem
       #
-      # = Message
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      # @param [String] type
+      #   the optional definition of which type of errors this is: instance or class
       #
-      #           StateGate for Klass#attribute will generate a class
-      #           method 'statuses', which is already defined by ActiveRecord.
+      # @param [String] source
+      #   the optional class name
       #
-      def raise_conflict_error(method_name, type: 'an instance', source: 'ActiveRecord')
+      # @raise [ConflictError]
+      #   with the message:
+      #     StateGate for Klass#attribute will generate a class
+      #     method 'statuses', which is already defined by ActiveRecord.
+      #
+      def _raise_conflict_error(method_name, type: 'an instance', source: 'ActiveRecord')
         fail StateGate::ConflictError, I18n.t('state_gate.builder.conflict_err',
                                               klass:       @klass,
                                               attribute:   @attribute,
@@ -72,25 +91,37 @@ module StateGate
 
 
 
+      ##
       # Check if the method is an ActiveRecord dangerous method name
       #
-      def _active_record_protected_method?(method_name) #:nodoc:
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      def _active_record_protected_method?(method_name)
         'ActiveRecord' if _dangerous_method_names.include?(method_name)
       end
 
 
 
+      ##
       # Check if the method is a singleton method of the klass
       #
-      def _klass_singleton_method?(method_name) #:nodoc:
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      def _klass_singleton_method?(method_name)
         @klass.name if @klass.singleton_methods(false).include?(method_name.to_sym)
       end
 
 
 
+      ##
       # Check if the method is an ancestral singleton method of the klass
       #
-      def _klass_ancestor_singleton_method?(method_name) #:nodoc:
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      def _klass_ancestor_singleton_method?(method_name)
         return nil unless @klass.respond_to?(method_name)
 
         @klass.singleton_class
@@ -101,17 +132,25 @@ module StateGate
 
 
 
+      ##
       # Check if the method an instance method of the klass
       #
-      def _klass_instance_method?(method_name) #:nodoc:
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      def _klass_instance_method?(method_name)
         @klass.instance_methods(false).include?(method_name.to_sym) ? @klass.name : nil
       end
 
 
 
+      ##
       # Check if the method is an ancestral singleton method of the klass
       #
-      def _klass_ancestor_instance_method?(method_name) #:nodoc:
+      # @param [Symbol] method_name
+      #   the method name
+      #
+      def _klass_ancestor_instance_method?(method_name)
         return nil unless @klass.instance_methods.include?(method_name.to_sym)
 
         @klass.ancestors
@@ -121,9 +160,11 @@ module StateGate
 
 
 
-      # returns an array of dagerous methods names found in
-      # ActiveRecord::AttributeMethods::RESTRICTED_CLASS_METHODS (which is called
-      # BLACKLISTED_CLASS_METHODS in 5.0 and 5.1)
+      ##
+      # @return [Array[Symbol]]
+      #   array of dagerous methods names found in
+      #   ActiveRecord::AttributeMethods::RESTRICTED_CLASS_METHODS (which is called
+      #   BLACKLISTED_CLASS_METHODS in 5.0 and 5.1)
       #
       def _dangerous_method_names
         %w[private public protected allocate new name parent superclass]

data/lib/state_gate/builder/dynamic_module_creation_methods.rb

@@ -19,14 +19,15 @@ module StateGate
       # = Dynamic Module Creation
       # ======================================================================
 
+      ##
       # Dynamically generated module to hold the StateGate helper methods. This
       # keeps a clear distinction between the state machine helper methods and the klass'
       # own methods.
       #
       # The module is named after the class and is created if needed, or reused if exisitng.
       #
-      # Note:
-      #       the module is named "<klass>::StateGate_HelperMethods"
+      # @note
+      #   the module is named "<klass>::StateGate_HelperMethods"
       #
       def _helper_methods_module
         @_helper_methods_module ||= begin
@@ -46,6 +47,7 @@ module StateGate
       # ======================================================================
 
 
+      ##
       # Adds the hook method :method_added to the Klass, detecting any new method
       # definitions for an attribute already defined as a StateGate.
       #
@@ -54,16 +56,15 @@ module StateGate
       #
       # method_name - the name of the newly defined method.
       #
-      # Note
+      # @note
+      #   This method is added last so it does not trigger when StateGate adds
+      #   the attribute methods.
       #
-      # This method is added last so it does not trigger when StateGate adds
-      # the attribute methods.
+      # meta
       #
-      #  meta
-      #
-      # * loop though each state machine attribute.
-      #   * does the new defined method use 'attr' or 'attr='?
-      #     * if so then record an error logger if denied, othewise use `puts`
+      # - loop though each state machine attribute.
+      #   - does the new defined method use 'attr' or 'attr='?
+      #     - if so then record an error logger if denied, othewise use `puts`
       #
       def _generate_method_redefine_detection # rubocop:disable Metrics/MethodLength
         @klass.instance_eval(%(
@@ -89,29 +90,42 @@ module StateGate
       #   Method Creation
       # ======================================================================
 
+      ##
       # Add an Class helper method to the _helper_methods_module
       #
-      # method_name - a String name for the method, needed to check for conflicts
-      # file        - a String file name for error reporting
-      # line        - a String or Integer line number for error reporting
-      # method_body - a String to bhe evaluates in the module
+      # @param [String] method_name
+      #   name for the method to check for conflicts
+      #
+      # @param [String] file
+      #   file name for error reporting
+      #
+      # @param [String,Integer] line
+      #   line number for error reporting
+      #
+      # @param [String] method_body
+      #   a String to be evaluated in the module
       #
-      def add__klass__helper_method(method_name, file, line, method_body)
-        detect_class_method_conflict!(method_name)
+      def _add__klass__helper_method(method_name, file, line, method_body)
+        _detect_class_method_conflict!(method_name)
         @klass.instance_eval(method_body, file, line)
       end
 
 
 
+      ##
       # Add an instance helper method to the _helper_methods_module
       #
-      # method_name - a String name for the method, needed to check for conflicts
-      # file        - a String file name for error reporting
-      # line        - a String or Integer line number for error reporting
-      # method_body - a String to bhe evaluates in the module
+      # @param [String] method_name
+      #   name for the method to check for conflicts
+      # @param [String] file
+      #   file name for error reporting
+      # @param [String] line
+      #   line number for error reporting
+      # @param [String] method_body
+      #   a String to bhe evaluates in the module
       #
-      def add__instance__helper_method(method_name, file, line, method_body)
-        detect_instance_method_conflict!(method_name)
+      def _add__instance__helper_method(method_name, file, line, method_body)
+        _detect_instance_method_conflict!(method_name)
         _helper_methods_module.module_eval(method_body, file, line)
       end
 

data/lib/state_gate/builder/scope_methods.rb

@@ -8,14 +8,14 @@ module StateGate
     # Multiple private methods enabling StateGate::Builder to generate
     # scopes for each state.
     #
-    # * fetch all records with the given state:
-    #     Klass.active # => Klass.where(state: :active)
+    # - fetch all records with the given state:
+    #     Klass.active #=> Klass.where(state: :active)
     #
-    # * fetch all records without the given state:
-    #     Klass.not_active # => Klass.where.not(state: :active)
+    # - fetch all records without the given state:
+    #     Klass.not_active #=> Klass.where.not(state: :active)
     #
-    # * fetch all records with the supplied states:
-    #     Klass.with_statuses(:pending, :active) # => Klass.where(state: [:pending, :active])
+    # - fetch all records with the supplied states:
+    #     Klass.with_statuses(:pending, :active) #=> Klass.where(state: [:pending, :active])
     #
     module ScopeMethods
 
@@ -24,12 +24,13 @@ module StateGate
       private
 
 
+      ##
       # Add scopes to the klass for filtering by state
       #
-      # Note:
-      #       The scope name is a concatenation of <prefix><state name><suffix>
+      # @note
+      #   The scope name is a concatenation of <prefix><state name><suffix>
       #
-      def generate_scope_methods
+      def _generate_scope_methods
         return unless @engine.include_scopes?
 
         _add__klass__state_scopes
@@ -45,49 +46,58 @@ module StateGate
       #  Klass methods
       # ======================================================================
 
+      ##
       # Add a klass method that scopes records to the specified state.
-      #   eg:
-      #       Klass.active         # => ActiveRecord::Relation
-      #       Klass.active_status  # => ActiveRecord::Relation
+      #
+      # @example
+      #   Klass.active         #=> ActiveRecord::Relation
+      #   Klass.active_status  #=> ActiveRecord::Relation
       #
       def _add__klass__state_scopes
         attr_name = @attribute
 
         @engine.states.each do |state|
           scope_name = @engine.scope_name_for_state(state)
-          detect_class_method_conflict! scope_name
+          _detect_class_method_conflict! scope_name
           @klass.scope(scope_name, -> { where(attr_name => state) })
         end # each state
       end # _add__klass__state_scopes
 
 
 
+      ##
       # Add a klass method that scopes records to those without the specified state.
-      #   eg:
-      #       Klass.not_active         # => ActiveRecord::Relation
-      #       Klass.not_active_status  # => ActiveRecord::Relation
+      #
+      # @example
+      #   Klass.not_active         #=> ActiveRecord::Relation
+      #   Klass.not_active_status  #=> ActiveRecord::Relation
       #
       def _add__klass__not_state_scopes
         attr_name = @attribute
 
         @engine.states.each do |state|
           scope_name = @engine.scope_name_for_state(state)
-          detect_class_method_conflict! "not_#{scope_name}"
+          _detect_class_method_conflict! "not_#{scope_name}"
           @klass.scope "not_#{scope_name}", -> { where.not(attr_name => state) }
         end # each state
       end # _add__klass__not_state_scopes
 
 
 
+      ##
       # Add a klass method that scopes records to the given states.
-      #   eg:
-      #       Klass.with_statuses(:active, :pending) # => ActiveRecord::Relation
+      #
+      # @param [Symbol] method_name
+      #   the method name for the new scope
+      #
+      # @example
+      #   Klass.with_statuses(:active, :pending) #=> ActiveRecord::Relation
       #
       def _add__klass__with_attrs_scope(method_name = @attribute)
         attr_name   = @attribute
         method_name = "with_#{method_name.to_s.pluralize}"
 
-        detect_class_method_conflict! method_name
+        _detect_class_method_conflict! method_name
         @klass.scope method_name, ->(states) { where(attr_name => Array(states)) }
       end # _add__klass__with_attrs_scope