state_machines 0.20.0 → 0.31.0

data/lib/state_machines/machine/state_methods.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module StateMethods
+      # Gets the initial state of the machine for the given object. If a dynamic
+      # initial state was configured for this machine, then the object will be
+      # passed into the lambda block to help determine the actual state.
+      def initial_state(object)
+        states.fetch(dynamic_initial_state? ? evaluate_method(object, @initial_state) : @initial_state) if instance_variable_defined?(:@initial_state)
+      end
+
+      # Whether a dynamic initial state is being used in the machine
+      def dynamic_initial_state?
+        instance_variable_defined?(:@initial_state) && @initial_state.is_a?(Proc)
+      end
+
+      # Initializes the state on the given object.  Initial values are only set if
+      # the machine's attribute hasn't been previously initialized.
+      #
+      # Configuration options:
+      # * <tt>:force</tt> - Whether to initialize the state regardless of its
+      #   current value
+      # * <tt>:to</tt> - A hash to set the initial value in instead of writing
+      #   directly to the object
+      def initialize_state(object, options = {})
+        state = initial_state(object)
+        return unless state && (options[:force] || initialize_state?(object))
+
+        value = state.value
+
+        if (hash = options[:to])
+          hash[attribute.to_s] = value
+        else
+          write(object, :state, value)
+        end
+      end
+
+      # Customizes the definition of one or more states in the machine.
+      def state(*names, &)
+        options = names.last.is_a?(Hash) ? names.pop : {}
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :value, :cache, :if, :human_name)
+
+        # Store the context so that it can be used for / matched against any state
+        # that gets added
+        @states.context(names, &) if block_given?
+
+        if names.first.is_a?(Matcher)
+          # Add any states referenced in the matcher.  When matchers are used,
+          # states are not allowed to be configured.
+          raise ArgumentError, "Cannot configure states when using matchers (using #{options.inspect})" if options.any?
+
+          states = add_states(names.first.values)
+        else
+          states = add_states(names)
+
+          # Update the configuration for the state(s)
+          states.each do |state|
+            if options.include?(:value)
+              state.value = options[:value]
+              self.states.update(state)
+            end
+
+            state.human_name = options[:human_name] if options.include?(:human_name)
+            state.cache = options[:cache] if options.include?(:cache)
+            state.matcher = options[:if] if options.include?(:if)
+          end
+        end
+
+        states.length == 1 ? states.first : states
+      end
+
+      alias other_states state
+
+      # Gets the current value stored in the given object's attribute.
+      def read(object, attribute, ivar = false)
+        attribute = self.attribute(attribute)
+        if ivar
+          object.instance_variable_defined?(:"@#{attribute}") ? object.instance_variable_get("@#{attribute}") : nil
+        else
+          object.send(attribute)
+        end
+      end
+
+      # Sets a new value in the given object's attribute.
+      def write(object, attribute, value, ivar = false)
+        attribute = self.attribute(attribute)
+        ivar ? object.instance_variable_set(:"@#{attribute}", value) : object.send("#{attribute}=", value)
+      end
+
+      protected
+
+      # Determines if the machine's attribute needs to be initialized.  This
+      # will only be true if the machine's attribute is blank.
+      def initialize_state?(object)
+        value = read(object, :state)
+        (value.nil? || (value.respond_to?(:empty?) && value.empty?)) && !states[value, :value]
+      end
+    end
+  end
+end

data/lib/state_machines/machine/utilities.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Utilities
+      protected
+
+      # Looks up other machines that have been defined in the owner class and
+      # are targeting the same attribute as this machine.  When accessing
+      # sibling machines, they will be automatically copied for the current
+      # class if they haven't been already.  This ensures that any configuration
+      # changes made to the sibling machines only affect this class and not any
+      # base class that may have originally defined the machine.
+      def sibling_machines
+        owner_class.state_machines.each_with_object([]) do |(name, machine), machines|
+          machines << (owner_class.state_machine(name) {}) if machine.attribute == attribute && machine != self
+        end
+      end
+
+      # Looks up the ancestor class that has the given method defined.  This
+      # is used to find the method owner which is used to determine where to
+      # define new methods.
+      def owner_class_ancestor_has_method?(scope, method)
+        return false unless owner_class_has_method?(scope, method)
+
+        superclasses = owner_class.ancestors.select { |ancestor| ancestor.is_a?(Class) }[1..]
+
+        if scope == :class
+          current = owner_class.singleton_class
+          superclass = superclasses.first
+        else
+          current = owner_class
+          superclass = owner_class.superclass
+        end
+
+        # Generate the list of modules that *only* occur in the owner class, but
+        # were included *prior* to the helper modules, in addition to the
+        # superclasses
+        ancestors = current.ancestors - superclass.ancestors + superclasses
+        helper_module_index = ancestors.index(@helper_modules[scope])
+        ancestors = helper_module_index ? ancestors[helper_module_index..].reverse : ancestors.reverse
+
+        # Search for for the first ancestor that defined this method
+        ancestors.detect do |ancestor|
+          ancestor = ancestor.singleton_class if scope == :class && ancestor.is_a?(Class)
+          ancestor.method_defined?(method) || ancestor.private_method_defined?(method)
+        end
+      end
+
+      # Determines whether the given method is defined in the owner class or
+      # in a superclass.
+      def owner_class_has_method?(scope, method)
+        target = scope == :class ? owner_class.singleton_class : owner_class
+        target.method_defined?(method) || target.private_method_defined?(method)
+      end
+
+      # Pluralizes the given word using #pluralize (if available) or simply
+      # adding an "s" to the end of the word
+      def pluralize(word)
+        word = word.to_s
+        if word.respond_to?(:pluralize)
+          word.pluralize
+        else
+          "#{word}s"
+        end
+      end
+
+      # Generates the results for the given scope based on one or more states to
+      # filter by
+      def run_scope(scope, machine, klass, states)
+        values = states.flatten.compact.map { |state| machine.states.fetch(state).value }
+        scope.call(klass, values)
+      end
+
+      # Adds sibling machine configurations to the current machine.  This
+      # will add states from other machines that have the same attribute.
+      def add_sibling_machine_configs
+        # Add existing states
+        sibling_machines.each do |machine|
+          machine.states.each { |state| states << state unless states[state.name] }
+        end
+      end
+    end
+  end
+end

data/lib/state_machines/machine/validation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Validation
+      # Frozen constant to avoid repeated array allocations
+      DANGEROUS_PATTERNS = [
+        /`.*`/,           # Backticks (shell execution)
+        /system\s*\(/,    # System calls
+        /exec\s*\(/,      # Exec calls
+        /eval\s*\(/,      # Nested eval
+        /require\s+['"]/, # Require statements
+        /load\s+['"]/, # Load statements
+        /File\./,         # File operations
+        /IO\./,           # IO operations
+        /Dir\./,          # Directory operations
+        /Kernel\./        # Kernel operations
+      ].freeze
+
+      private
+
+      # Validates string input before eval to prevent code injection
+      # This is a basic safety check - not foolproof security
+      def validate_eval_string(method_string)
+        # Check for obviously dangerous patterns
+        DANGEROUS_PATTERNS.each do |pattern|
+          raise SecurityError, "Potentially dangerous code detected in eval string: #{method_string.inspect}" if method_string.match?(pattern)
+        end
+
+        # Basic syntax validation (cross-platform)
+        begin
+          SyntaxValidator.validate!(method_string, '(eval)')
+        rescue SyntaxError => e
+          raise ArgumentError, "Invalid Ruby syntax in eval string: #{e.message}"
+        end
+      end
+    end
+  end
+end