matchi 3.3.2 → 4.1.0

data/lib/matchi/be_an_instance_of.rb

@@ -1,49 +1,119 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Type/class* matcher.
+  # *Type/class* matcher with enhanced class checking.
+  #
+  # This matcher aims to provide a more reliable way to check if an object is an exact
+  # instance of a specific class (not a subclass). While not foolproof, it uses a more
+  # robust method to get the actual class of an object that helps resist common
+  # attempts at type checking manipulation.
+  #
+  # @example Basic usage
+  #   require "matchi/be_an_instance_of"
+  #
+  #   matcher = Matchi::BeAnInstanceOf.new(String)
+  #   matcher.match? { "foo" }  # => true
+  #   matcher.match? { :foo }   # => false
+  #
+  # @example Enhanced class checking in practice
+  #   # Consider a class that attempts to masquerade as String by overriding
+  #   # common type checking methods:
+  #   class MaliciousString
+  #     def class
+  #       ::String
+  #     end
+  #
+  #     def instance_of?(klass)
+  #       self.class == klass
+  #     end
+  #
+  #     def is_a?(klass)
+  #       "".is_a?(klass)  # Delegates to a real String
+  #     end
+  #
+  #     def kind_of?(klass)
+  #       is_a?(klass)     # Maintains Ruby's kind_of? alias for is_a?
+  #     end
+  #   end
+  #
+  #   obj = MaliciousString.new
+  #   obj.class                                             # => String
+  #   obj.is_a?(String)                                     # => true
+  #   obj.kind_of?(String)                                  # => true
+  #   obj.instance_of?(String)                              # => true
+  #
+  #   # Using our enhanced checking approach:
+  #   matcher = Matchi::BeAnInstanceOf.new(String)
+  #   matcher.match? { obj }                                # => false
   class BeAnInstanceOf
-    # @return [String] The expected class name.
-    attr_reader :expected
-
     # Initialize the matcher with (the name of) a class or module.
     #
     # @example
     #   require "matchi/be_an_instance_of"
     #
     #   Matchi::BeAnInstanceOf.new(String)
+    #   Matchi::BeAnInstanceOf.new("String")
+    #   Matchi::BeAnInstanceOf.new(:String)
     #
-    # @param expected [Class, #to_s] The expected class name.
+    # @param expected [Class, #to_s] The expected class name
+    # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
     def initialize(expected)
       @expected = String(expected)
+      return if /\A[A-Z]/.match?(@expected)
+
+      raise ::ArgumentError,
+            "expected must start with an uppercase letter (got: #{@expected})"
     end
 
-    # Boolean comparison between the class of the actual value and the
-    # expected class.
+    # Securely checks if the yielded object is an instance of the expected class.
     #
-    # @example
-    #   require "matchi/be_an_instance_of"
+    # This method uses a specific Ruby reflection technique to get the true class of
+    # an object, bypassing potential method overrides:
     #
-    #   matcher = Matchi::BeAnInstanceOf.new(String)
+    # 1. ::Object.instance_method(:class) retrieves the original, unoverridden 'class'
+    #    method from the Object class
+    # 2. .bind_call(obj) binds this original method to our object and calls it,
+    #    ensuring we get the real class regardless of method overrides
     #
-    #   matcher.expected           # => "String"
-    #   matcher.matches? { "foo" } # => true
+    # This approach is more reliable than obj.class because it uses Ruby's method
+    # binding mechanism to call the original implementation directly. While not
+    # completely foolproof, it provides better protection against type check spoofing
+    # than using regular method calls which can be overridden.
     #
-    # @yieldreturn [#class] the actual value to compare to the expected one.
+    # @example Basic class check
+    #   matcher = Matchi::BeAnInstanceOf.new(String)
+    #   matcher.match? { "test" }        # => true
+    #   matcher.match? { StringIO.new }  # => false
     #
-    # @return [Boolean] Comparison between actual and expected values.
-    def matches?
-      self.class.const_get(expected).equal?(yield.class)
-    end
+    # @see https://ruby-doc.org/core/Method.html#method-i-bind_call
+    # @see https://ruby-doc.org/core/UnboundMethod.html
+    #
+    # @yieldreturn [Object] the actual value to check
+    # @return [Boolean] true if the object's actual class is exactly the expected class
+    # @raise [ArgumentError] if no block is provided
+    def match?
+      raise ::ArgumentError, "a block must be provided" unless block_given?
 
-    # A string containing a human-readable representation of the matcher.
-    def inspect
-      "#{self.class}(#{expected})"
+      actual_class = ::Object.instance_method(:class).bind_call(yield)
+      expected_class == actual_class
     end
 
     # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     def to_s
-      "be an instance of #{expected}"
+      "be an instance of #{@expected}"
+    end
+
+    private
+
+    # Resolves the expected class name to an actual Class object.
+    # This method handles both string and symbol class names through constant resolution.
+    #
+    # @return [Class] the resolved class
+    # @raise [NameError] if the class doesn't exist
+    def expected_class
+      ::Object.const_get(@expected)
     end
   end
 end

data/lib/matchi/be_within/of.rb

@@ -4,9 +4,6 @@ module Matchi
   class BeWithin
     # *BeWithin of* matcher.
     class Of
-      # @return [Numeric] An expected value.
-      attr_reader :expected
-
       # Initialize the matcher with a delta and an expected value.
       #
       # @example
@@ -17,6 +14,10 @@ module Matchi
       # @param delta    [Numeric] The accepted variation of the actual value.
       # @param expected [Numeric] The expected value.
       def initialize(delta, expected)
+        raise ::ArgumentError, "delta must be a Numeric" unless delta.is_a?(::Numeric)
+        raise ::ArgumentError, "expected must be a Numeric" unless expected.is_a?(::Numeric)
+        raise ::ArgumentError, "delta must be non-negative" if delta.negative?
+
         @delta    = delta
         @expected = expected
       end
@@ -28,25 +29,22 @@ module Matchi
       #   require "matchi/be_within/of"
       #
       #   matcher = Matchi::BeWithin::Of.new(1, 41)
-      #
-      #   matcher.expected        # => 41
-      #   matcher.matches? { 42 } # => true
+      #   matcher.match? { 42 } # => true
       #
       # @yieldreturn [Numeric] The block of code to execute.
       #
       # @return [Boolean] Comparison between the actual and the expected values.
-      def matches?
-        (expected - yield).abs <= @delta
-      end
+      def match?
+        raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      # A string containing a human-readable representation of the matcher.
-      def inspect
-        "#{self.class}(#{@delta}, #{expected})"
+        (@expected - yield).abs <= @delta
       end
 
       # Returns a string representing the matcher.
+      #
+      # @return [String] a human-readable description of the matcher
       def to_s
-        "be within #{@delta} of #{expected}"
+        "be within #{@delta} of #{@expected}"
       end
     end
   end

data/lib/matchi/be_within.rb

@@ -14,6 +14,9 @@ module Matchi
     #
     # @param delta [Numeric] A numeric value.
     def initialize(delta)
+      raise ::ArgumentError, "delta must be a Numeric" unless delta.is_a?(::Numeric)
+      raise ::ArgumentError, "delta must be non-negative" if delta.negative?
+
       @delta = delta
     end
 
@@ -27,7 +30,7 @@ module Matchi
     #
     # @param expected [Numeric] The expected value.
     #
-    # @return [#matches?] A *be_within of* matcher.
+    # @return [#match?] A *be_within of* matcher.
     def of(expected)
       Of.new(@delta, expected)
     end

data/lib/matchi/change/by.rb

@@ -4,9 +4,6 @@ module Matchi
   class Change
     # *Change by* matcher.
     class By
-      # @return [#object_id] An expected delta.
-      attr_reader :expected
-
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -20,6 +17,9 @@ module Matchi
       # @param state    [Proc]        A block of code to execute to get the
       #   state of the object.
       def initialize(expected, &state)
+        raise ::ArgumentError, "expected must be a Numeric" unless expected.is_a?(::Numeric)
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
         @expected = expected
         @state    = state
       end
@@ -33,30 +33,27 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::By.new(1) { object.length }
-      #
-      #   matcher.expected                     # => 1
-      #   matcher.matches? { object << "foo" } # => true
+      #   matcher.match? { object << "foo" } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?
+      def match?
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
         value_before = @state.call
         yield
         value_after = @state.call
 
-        expected == (value_after - value_before)
-      end
-
-      # A string containing a human-readable representation of the matcher.
-      def inspect
-        "#{self.class}(#{expected.inspect})"
+        @expected == (value_after - value_before)
       end
 
       # Returns a string representing the matcher.
+      #
+      # @return [String] a human-readable description of the matcher
       def to_s
-        "change by #{expected.inspect}"
+        "change by #{@expected.inspect}"
       end
     end
   end

data/lib/matchi/change/by_at_least.rb

@@ -4,9 +4,6 @@ module Matchi
   class Change
     # *Change by at least* matcher.
     class ByAtLeast
-      # @return [#object_id] An expected delta.
-      attr_reader :expected
-
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -20,6 +17,10 @@ module Matchi
       # @param state    [Proc]        A block of code to execute to get the
       #   state of the object.
       def initialize(expected, &state)
+        raise ::ArgumentError, "expected must be a Numeric" unless expected.is_a?(::Numeric)
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+        raise ::ArgumentError, "expected must be non-negative" if expected.negative?
+
         @expected = expected
         @state    = state
       end
@@ -33,30 +34,27 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::ByAtLeast.new(1) { object.length }
-      #
-      #   matcher.expected                     # => 1
-      #   matcher.matches? { object << "foo" } # => true
+      #   matcher.match? { object << "foo" } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?
+      def match?
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
         value_before = @state.call
         yield
         value_after = @state.call
 
-        expected <= (value_after - value_before)
-      end
-
-      # A string containing a human-readable representation of the matcher.
-      def inspect
-        "#{self.class}(#{expected.inspect})"
+        @expected <= (value_after - value_before)
       end
 
       # Returns a string representing the matcher.
+      #
+      # @return [String] a human-readable description of the matcher
       def to_s
-        "change by at least #{expected.inspect}"
+        "change by at least #{@expected.inspect}"
       end
     end
   end

data/lib/matchi/change/by_at_most.rb

@@ -4,9 +4,6 @@ module Matchi
   class Change
     # *Change by at most* matcher.
     class ByAtMost
-      # @return [#object_id] An expected delta.
-      attr_reader :expected
-
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -20,6 +17,10 @@ module Matchi
       # @param state    [Proc]        A block of code to execute to get the
       #   state of the object.
       def initialize(expected, &state)
+        raise ::ArgumentError, "expected must be a Numeric" unless expected.is_a?(::Numeric)
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+        raise ::ArgumentError, "expected must be non-negative" if expected.negative?
+
         @expected = expected
         @state    = state
       end
@@ -33,30 +34,27 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::ByAtMost.new(1) { object.length }
-      #
-      #   matcher.expected                     # => 1
-      #   matcher.matches? { object << "foo" } # => true
+      #   matcher.match? { object << "foo" } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?
+      def match?
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
         value_before = @state.call
         yield
         value_after = @state.call
 
-        expected >= (value_after - value_before)
-      end
-
-      # A string containing a human-readable representation of the matcher.
-      def inspect
-        "#{self.class}(#{expected.inspect})"
+        @expected >= (value_after - value_before)
       end
 
       # Returns a string representing the matcher.
+      #
+      # @return [String] a human-readable description of the matcher
       def to_s
-        "change by at most #{expected.inspect}"
+        "change by at most #{@expected.inspect}"
       end
     end
   end

data/lib/matchi/change/from/to.rb

@@ -5,9 +5,6 @@ module Matchi
     class From
       # *Change from to* matcher.
       class To
-        # @return [#object_id] An expected new value.
-        attr_reader :expected
-
         # Initialize the matcher with two objects and a block.
         #
         # @example
@@ -22,6 +19,8 @@ module Matchi
         # @param state              [Proc]       A block of code to execute to
         #   get the state of the object.
         def initialize(expected_init, expected_new_value, &state)
+          raise ::ArgumentError, "a block must be provided" unless block_given?
+
           @expected_init  = expected_init
           @expected       = expected_new_value
           @state          = state
@@ -36,32 +35,29 @@ module Matchi
         #   object = "foo"
         #
         #   matcher = Matchi::Change::From::To.new("foo", "FOO") { object.to_s }
-        #
-        #   matcher.expected                    # => "FOO"
-        #   matcher.matches? { object.upcase! } # => true
+        #   matcher.match? { object.upcase! } # => true
         #
         # @yieldreturn [#object_id] The block of code to execute.
         #
         # @return [Boolean] Comparison between the value before and after the
         #   code execution.
-        def matches?
+        def match?
+          raise ::ArgumentError, "a block must be provided" unless block_given?
+
           value_before = @state.call
           return false unless @expected_init == value_before
 
           yield
           value_after = @state.call
 
-          expected == value_after
-        end
-
-        # A string containing a human-readable representation of the matcher.
-        def inspect
-          "#{self.class}(#{@expected_init.inspect}, #{expected.inspect})"
+          @expected == value_after
         end
 
         # Returns a string representing the matcher.
+        #
+        # @return [String] a human-readable description of the matcher
         def to_s
-          "change from #{@expected_init.inspect} to #{expected.inspect}"
+          "change from #{@expected_init.inspect} to #{@expected.inspect}"
         end
       end
     end

data/lib/matchi/change/from.rb

@@ -19,6 +19,8 @@ module Matchi
       # @param state    [Proc]        A block of code to execute to get the
       #   state of the object.
       def initialize(expected, &state)
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
         @expected = expected
         @state    = state
       end
@@ -35,7 +37,7 @@ module Matchi
       #
       # @param expected_new_value [#object_id] The new value to expect.
       #
-      # @return [#matches?] A *change from to* matcher.
+      # @return [#match?] A *change from to* matcher.
       def to(expected_new_value)
         To.new(@expected, expected_new_value, &@state)
       end

data/lib/matchi/change/to.rb

@@ -4,9 +4,6 @@ module Matchi
   class Change
     # *Change to* matcher.
     class To
-      # @return [#object_id] An expected new value.
-      attr_reader :expected
-
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -20,6 +17,8 @@ module Matchi
       # @param state    [Proc]        A block of code to execute to get the
       #   state of the object.
       def initialize(expected, &state)
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
         @expected = expected
         @state    = state
       end
@@ -33,29 +32,26 @@ module Matchi
       #   object = "foo"
       #
       #   matcher = Matchi::Change::To.new("FOO") { object.to_s }
-      #
-      #   matcher.expected                    # => "FOO"
-      #   matcher.matches? { object.upcase! } # => true
+      #   matcher.match? { object.upcase! } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?
+      def match?
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
         yield
         value_after = @state.call
 
-        expected == value_after
-      end
-
-      # A string containing a human-readable representation of the matcher.
-      def inspect
-        "#{self.class}(#{expected.inspect})"
+        @expected == value_after
       end
 
       # Returns a string representing the matcher.
+      #
+      # @return [String] a human-readable description of the matcher
       def to_s
-        "change to #{expected.inspect}"
+        "change to #{@expected.inspect}"
       end
     end
   end

data/lib/matchi/change.rb

@@ -19,9 +19,10 @@ module Matchi
     #
     # @param object [#object_id]  An object.
     # @param method [Symbol]      The name of a method.
-    # @param args   [Array]       A list of arguments.
-    # @param kwargs [Hash]        A list of keyword arguments.
     def initialize(object, method, ...)
+      raise ::ArgumentError, "method must be a Symbol" unless method.is_a?(::Symbol)
+      raise ::ArgumentError, "object must respond to method" unless object.respond_to?(method)
+
       @state = -> { object.send(method, ...) }
     end
 
@@ -37,7 +38,7 @@ module Matchi
     #
     # @param minimum_delta [#object_id] The minimum delta of the expected change.
     #
-    # @return [#matches?] A *change by at least* matcher.
+    # @return [#match?] A *change by at least* matcher.
     def by_at_least(minimum_delta)
       ByAtLeast.new(minimum_delta, &@state)
     end
@@ -54,7 +55,7 @@ module Matchi
     #
     # @param maximum_delta [#object_id] The maximum delta of the expected change.
     #
-    # @return [#matches?] A *change by at most* matcher.
+    # @return [#match?] A *change by at most* matcher.
     def by_at_most(maximum_delta)
       ByAtMost.new(maximum_delta, &@state)
     end
@@ -71,7 +72,7 @@ module Matchi
     #
     # @param delta [#object_id] The delta of the expected change.
     #
-    # @return [#matches?] A *change by* matcher.
+    # @return [#match?] A *change by* matcher.
     def by(delta)
       By.new(delta, &@state)
     end
@@ -86,7 +87,7 @@ module Matchi
     #
     # @param old_value [#object_id] The original value.
     #
-    # @return [#matches?] A *change from* wrapper.
+    # @return [#match?] A *change from* wrapper.
     def from(old_value)
       From.new(old_value, &@state)
     end
@@ -101,7 +102,7 @@ module Matchi
     #
     # @param new_value [#object_id] The new value to expect.
     #
-    # @return [#matches?] A *change to* matcher.
+    # @return [#match?] A *change to* matcher.
     def to(new_value)
       To.new(new_value, &@state)
     end

data/lib/matchi/eq.rb

@@ -3,9 +3,6 @@
 module Matchi
   # *Equivalence* matcher.
   class Eq
-    # @return [#eql?] An expected equivalent object.
-    attr_reader :expected
-
     # Initialize the matcher with an object.
     #
     # @example
@@ -24,26 +21,23 @@ module Matchi
     #   require "matchi/eq"
     #
     #   matcher = Matchi::Eq.new("foo")
-    #
-    #   matcher.expected           # => "foo"
-    #   matcher.matches? { "foo" } # => true
+    #   matcher.match? { "foo" } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?
-      expected.eql?(yield)
-    end
+    def match?
+      raise ::ArgumentError, "a block must be provided" unless block_given?
 
-    # A string containing a human-readable representation of the matcher.
-    def inspect
-      "#{self.class}(#{expected.inspect})"
+      @expected.eql?(yield)
     end
 
     # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     def to_s
-      "eq #{expected.inspect}"
+      "eq #{@expected.inspect}"
     end
   end
 end

data/lib/matchi/match.rb

@@ -3,9 +3,6 @@
 module Matchi
   # *Regular expressions* matcher.
   class Match
-    # @return [#match] A regular expression.
-    attr_reader :expected
-
     # Initialize the matcher with an instance of Regexp.
     #
     # @example
@@ -15,6 +12,8 @@ module Matchi
     #
     # @param expected [#match] A regular expression.
     def initialize(expected)
+      raise ::ArgumentError, "expected must respond to match?" unless expected.respond_to?(:match?)
+
       @expected = expected
     end
 
@@ -24,26 +23,23 @@ module Matchi
     #   require "matchi/match"
     #
     #   matcher = Matchi::Match.new(/^foo$/)
-    #
-    #   matcher.expected           # => /^foo$/
-    #   matcher.matches? { "foo" } # => true
+    #   matcher.match? { "foo" } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?
-      expected.match?(yield)
-    end
+    def match?
+      raise ::ArgumentError, "a block must be provided" unless block_given?
 
-    # A string containing a human-readable representation of the matcher.
-    def inspect
-      "#{self.class}(#{expected.inspect})"
+      @expected.match?(yield)
     end
 
     # Returns a string representing the matcher.
+    #
+    # @return [String] a human-readable description of the matcher
     def to_s
-      "match #{expected.inspect}"
+      "match #{@expected.inspect}"
     end
   end
 end