matchi 4.2.0 → 5.0.0

data/lib/matchi/change/to.rb

@@ -1,56 +1,20 @@
 # frozen_string_literal: true
 
+require_relative "../eq"
+
 module Matchi
   class Change
-    # Final state matcher that verifies if a method returns an expected value after a change.
-    #
-    # This matcher focuses on the final state of an object, verifying that a method call
-    # returns an expected value after executing a block of code. Unlike the full from/to
-    # matcher, it only cares about the end result, not the initial state.
-    #
-    # @example Basic string transformation
-    #   text = "hello"
-    #   matcher = Matchi::Change::To.new("HELLO") { text.to_s }
-    #   matcher.match? { text.upcase! }   # => true
-    #   matcher.match? { text.reverse! }  # => false
-    #
-    # @example Number calculations
-    #   counter = 0
-    #   matcher = Matchi::Change::To.new(5) { counter }
-    #   matcher.match? { counter = 5 }    # => true
-    #   matcher.match? { counter += 1 }   # => false
-    #
-    # @example With object attributes
-    #   class User
-    #     attr_accessor :status
-    #     def initialize(status)
-    #       @status = status
-    #     end
-    #   end
-    #
-    #   user = User.new(:pending)
-    #   matcher = Matchi::Change::To.new(:active) { user.status }
-    #   matcher.match? { user.status = :active }  # => true
+    # Passes when the observed value is not the expected value before the
+    # block and is the expected value after it: the value must change to it.
+    # The block is always evaluated.
     #
-    # @see Matchi::Change::From::To For checking both initial and final states
-    # @see Matchi::Change::By For checking numeric changes
+    # @example
+    #   s = +"a"
+    #   Matchi::Change.new(s, :to_s).to("b").match? { s.replace("b") } # => true
     class To
-      # Initialize the matcher with an expected new value and a state block.
-      #
-      # @api public
-      #
-      # @param expected [#eql?] The expected final value
-      # @param state [Proc] Block that retrieves the value to check
-      #
-      # @raise [ArgumentError] if no state block is provided
-      #
-      # @return [To] a new instance of the matcher
-      #
-      # @example With simple value
-      #   To.new("test") { object.value }
-      #
-      # @example With complex calculation
-      #   To.new(100) { object.items.count }
+      # @param expected [#eql?] the expected value after the block
+      # @yieldreturn [Object] the observed value
+      # @raise [ArgumentError] when no block is given
       def initialize(expected, &state)
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
@@ -58,47 +22,19 @@ module Matchi
         @state = state
       end
 
-      # Checks if the state block returns the expected value after executing the provided block.
-      #
-      # This method executes the provided block and then checks if the state block
-      # returns the expected value. It only cares about the final state, not any
-      # intermediate values or the initial state.
-      #
-      # @api public
-      #
-      # @yield [] Block that should cause the state change
-      # @yieldreturn [Object] The result of the block (not used)
-      #
-      # @return [Boolean] true if the final state matches the expected value
-      #
-      # @raise [ArgumentError] if no block is provided
-      #
-      # @example Basic usage
-      #   text = "hello"
-      #   matcher = To.new("HELLO") { text.to_s }
-      #   matcher.match? { text.upcase! }  # => true
-      #
-      # @example With method chaining
-      #   array = [1, 2, 3]
-      #   matcher = To.new(6) { array.sum }
-      #   matcher.match? { array.map! { |x| x * 2 } }  # => false
+      # @yieldreturn [Object] ignored, the block is evaluated for its effect
+      # @return [Boolean]
+      # @raise [ArgumentError] when no block is given
       def match?
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
+        already = Eq.eql?(@expected, @state.call)
         yield
-        value_after = @state.call
 
-        @expected.eql?(value_after)
+        !already && Eq.eql?(@expected, @state.call)
       end
 
-      # Returns a human-readable description of the matcher.
-      #
-      # @api public
-      #
-      # @return [String] A string describing what this matcher verifies
-      #
-      # @example
-      #   To.new("test").to_s # => 'change to "test"'
+      # @return [String]
       def to_s
         "change to #{@expected.inspect}"
       end

data/lib/matchi/change.rb

@@ -1,85 +1,54 @@
 # frozen_string_literal: true
 
-require_relative File.join("change", "by_at_least")
-require_relative File.join("change", "by_at_most")
-require_relative File.join("change", "by")
-require_relative File.join("change", "from")
-require_relative File.join("change", "to")
+require_relative "change/delta"
+require_relative "change/from"
+require_relative "change/to"
+require_relative "constant"
 
 module Matchi
-  # Wraps the target of a change matcher.
+  # State change matcher: passes when evaluating the block changes the value
+  # returned by a public method of an object.
+  #
+  # The observed method is called with `public_send` before and after the
+  # block, and the two values are compared with `eql?`. The observed method
+  # must return a value, not the mutated object itself: when it returns the
+  # very same unfrozen object twice, the comparison cannot tell whether that
+  # object changed, and `match?` raises instead of answering `false`.
+  # `attr_reader :items` with `items << x` is that case; observe
+  # `items.length` or use {#to}, which compares with the expected value. A
+  # frozen object returned twice counts as an unchanged value.
+  #
+  # The refinements {#by}, {#by_at_least}, {#by_at_most}, {#from} and {#to}
+  # build more specific matchers. `Change`, `by`, `by_at_least` and
+  # `by_at_most` compare values produced by the observed object, so they
+  # depend on its honesty, like {Matchi::Predicate}. `to` and `from … to`
+  # compare with the expected value, like {Matchi::Eq}. Whatever the
+  # observed method raises propagates.
+  #
+  # @example
+  #   list = []
+  #   Matchi::Change.new(list, :length).match? { list << 1 }       # => true
+  #   Matchi::Change.new(list, :length).by(1).match? { list << 1 } # => true
   class Change
-    # Initialize a wrapper of the change matcher with an object and the name of
-    # one of its methods.
-    #
-    # @api public
-    #
-    # @param object [#object_id] The object whose state will be monitored
-    # @param method [Symbol] The name of the method to track
-    # @param args [Array] Additional positional arguments to pass to the method
-    # @param kwargs [Hash] Additional keyword arguments to pass to the method
-    # @param block [Proc] Optional block to pass to the method
-    #
-    # @raise [ArgumentError] if method is not a Symbol
-    # @raise [ArgumentError] if object doesn't respond to method
-    #
-    # @return [Change] a new instance of the change wrapper
-    #
-    # @example Basic initialization
-    #   array = []
-    #   Change.new(array, :length)              # Track array length changes
-    #
-    # @example With positional arguments
-    #   hash = { key: "value" }
-    #   Change.new(hash, :fetch, :key)          # Track specific key value
-    #
-    # @example With keyword arguments
-    #   hash = { a: 1, b: 2 }
-    #   Change.new(hash, :fetch, default: 0)    # Track with default value
-    #
-    # @example With block
-    #   hash = { a: 1 }
-    #   Change.new(hash, :fetch, :b) { |k| k.to_s }  # Track with block default
+    # @param object [Object] the object to observe
+    # @param method [Symbol, String] a public method of that object
+    # @param args [Array] positional arguments for the method
+    # @param kwargs [Hash] keyword arguments for the method
+    # @param block [Proc, nil] a block for the method
+    # @raise [ArgumentError] when method is neither a Symbol nor a String
     def initialize(object, method, *args, **kwargs, &block)
-      raise ::ArgumentError, "method must be a Symbol" unless method.is_a?(::Symbol)
-      raise ::ArgumentError, "object must respond to method" unless object.respond_to?(method)
+      raise ::ArgumentError, "method must be a Symbol or a String (got: #{method.inspect})" unless name?(method)
 
-      @state = -> { object.send(method, *args, **kwargs, &block) }
+      @object = object
+      @method = method.to_sym
+      @state = -> { ::Kernel.instance_method(:public_send).bind_call(object, @method, *args, **kwargs, &block) }
     end
 
-    # Checks if the tracked method's return value changes when executing the block.
-    #
-    # This method verifies that the value changes in any way between the start and end
-    # of the block execution. It doesn't care about the type or magnitude of the change,
-    # only that it's different.
-    #
-    # @api public
-    #
-    # @yield [] Block during which the change should occur
-    # @yieldreturn [Object] Result of the block execution (not used)
-    #
-    # @return [Boolean] true if the value changed, false otherwise
-    #
-    # @raise [ArgumentError] if no block is provided
-    #
-    # @example Basic usage with array length
-    #   array = []
-    #   matcher = Change.new(array, :length)
-    #   matcher.match? { array << "item" }    # => true
-    #   matcher.match? { array.clear }        # => true (from 1 to 0)
-    #   matcher.match? { array.dup }          # => false (no change)
-    #
-    # @example With method parameters
-    #   hash = { key: "old" }
-    #   matcher = Change.new(hash, :fetch, :key)
-    #   matcher.match? { hash[:key] = "new" }  # => true
-    #   matcher.match? { hash[:key] = "new" }  # => false (same value)
-    #
-    # @example With computed values
-    #   text = "hello"
-    #   matcher = Change.new(text, :upcase)
-    #   matcher.match? { text.upcase! }        # => true
-    #   matcher.match? { text.upcase! }        # => false (already uppercase)
+    # @yieldreturn [Object] ignored, the block is evaluated for its effect
+    # @return [Boolean]
+    # @raise [ArgumentError] when no block is given
+    # @raise [NoMethodError] when the object has no such public method
+    # @raise [TypeError] when the observed method returns the same unfrozen object twice
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
@@ -87,98 +56,54 @@ module Matchi
       yield
       value_after = @state.call
 
-      !value_before.eql?(value_after)
+      return !value_before.eql?(value_after) unless value_before.equal?(value_after)
+      return false if ::Kernel.instance_method(:frozen?).bind_call(value_before)
+
+      raise ::TypeError, "#{self} returned the same unfrozen object twice: observe a value, not the object"
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   Change.new("test", :upcase).to_s # => 'eq "test"'
+    # @return [String] the observed class and method, such as `change Array#length`
     def to_s
-      "change #{@state.inspect}"
+      "change #{Constant.label(::Kernel.instance_method(:class).bind_call(@object))}##{@method}"
     end
 
-    # Specifies a minimum delta of the expected change.
-    #
-    # @api public
-    #
-    # @param minimum_delta [#object_id] The minimum expected change amount
-    #
-    # @return [#match?] A matcher that verifies the minimum change
-    #
-    # @example
-    #   counter = 0
-    #   matcher = Change.new(counter, :to_i).by_at_least(5)
-    #   matcher.match? { counter += 6 }  # => true
-    def by_at_least(minimum_delta)
-      ByAtLeast.new(minimum_delta, &@state)
+    # @param delta [Numeric] the exact expected difference, negative allowed
+    # @return [Matchi::Change::Delta]
+    # @raise [ArgumentError] when delta is not a finite real Numeric
+    def by(delta)
+      Delta.new(:by, delta, &@state)
     end
 
-    # Specifies a maximum delta of the expected change.
-    #
-    # @api public
-    #
-    # @param maximum_delta [#object_id] The maximum allowed change amount
-    #
-    # @return [#match?] A matcher that verifies the maximum change
-    #
-    # @example
-    #   counter = 0
-    #   matcher = Change.new(counter, :to_i).by_at_most(5)
-    #   matcher.match? { counter += 3 }  # => true
-    def by_at_most(maximum_delta)
-      ByAtMost.new(maximum_delta, &@state)
+    # @param delta [Numeric] the smallest acceptable increase, zero or positive
+    # @return [Matchi::Change::Delta]
+    # @raise [ArgumentError] when delta is not a finite real non-negative Numeric
+    def by_at_least(delta)
+      Delta.new(:by_at_least, delta, &@state)
     end
 
-    # Specifies the exact delta of the expected change.
-    #
-    # @api public
-    #
-    # @param delta [#object_id] The exact expected change amount
-    #
-    # @return [#match?] A matcher that verifies the exact change
-    #
-    # @example
-    #   counter = 0
-    #   matcher = Change.new(counter, :to_i).by(5)
-    #   matcher.match? { counter += 5 }  # => true
-    def by(delta)
-      By.new(delta, &@state)
+    # @param delta [Numeric] the largest acceptable increase, zero or positive
+    # @return [Matchi::Change::Delta]
+    # @raise [ArgumentError] when delta is not a finite real non-negative Numeric
+    def by_at_most(delta)
+      Delta.new(:by_at_most, delta, &@state)
     end
 
-    # Specifies the original value in a value transition check.
-    #
-    # @api public
-    #
-    # @param old_value [#object_id] The expected initial value
-    #
-    # @return [#to] A wrapper for creating a from/to matcher
-    #
-    # @example
-    #   string = "foo"
-    #   Change.new(string, :to_s).from("foo").to("FOO")
+    # @param old_value [#eql?] the expected value before the block
+    # @return [Matchi::Change::From] a builder; call `to` on it
     def from(old_value)
       From.new(old_value, &@state)
     end
 
-    # Specifies the final value to expect.
-    #
-    # @api public
-    #
-    # @param new_value [#object_id] The expected final value
-    #
-    # @return [#match?] A matcher that verifies the final state
-    #
-    # @example
-    #   string = "foo"
-    #   matcher = Change.new(string, :to_s).to("FOO")
-    #   matcher.match? { string.upcase! }  # => true
+    # @param new_value [#eql?] the expected value after the block
+    # @return [Matchi::Change::To]
     def to(new_value)
       To.new(new_value, &@state)
     end
+
+    private
+
+    def name?(method)
+      ::Symbol === method || ::String === method
+    end
   end
 end

data/lib/matchi/constant.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Matchi
+  # Shared handling of an expected module given directly or by name.
+  #
+  # A name is a String or a Symbol holding a constant path such as
+  # `"Comparable"` or `:"Foo::Bar"`. It is validated when the matcher is built
+  # and resolved from `Object` when the matcher runs, which lets a
+  # specification be written before the class it describes is loaded. Since
+  # resolution goes through `Object.const_get`, an `autoload` or an
+  # `Object.const_missing` defined by the code under test takes part in it.
+  #
+  # @api private
+  module Constant
+    # A constant path: ASCII segments that start with a capital letter,
+    # joined by `::`, such as `"Comparable"` or `"File::Stat"`.
+    NAME = /\A[A-Z]\w*(::[A-Z]\w*)*\z/
+
+    # @param expected [Module, String, Symbol] a module, or its name
+    # @param kind [Class] `Module` or `Class`, what expected must be
+    # @return [Module, String] the module itself, or the validated name
+    # @raise [ArgumentError] when expected is neither
+    def self.normalize(expected, kind)
+      return expected if kind === expected
+      return String(expected) if (::String === expected || ::Symbol === expected) && NAME.match?(expected)
+
+      raise ::ArgumentError, "expected must be a #{kind} or a constant name (got: #{expected.inspect})"
+    end
+
+    # @param expected [Module, String] a module, or a validated name
+    # @return [String] the name, or a stable label for an anonymous module
+    #
+    # The name is read with `Module#name` bound to the module, so a class
+    # of the code under test that redefines `name` cannot break a report.
+    def self.label(expected)
+      return expected unless ::Module === expected
+
+      ::Module.instance_method(:name).bind_call(expected) || "an anonymous #{::Class === expected ? "class" : "module"}"
+    end
+
+    # @param expected [Module, String] a module, or a validated name
+    # @param kind [Class] `Module` or `Class`, what the name must resolve to
+    # @return [Module]
+    # @raise [NameError] when the name is not defined
+    # @raise [TypeError] when the name does not resolve to the expected kind
+    def self.resolve(expected, kind)
+      return expected if kind === expected
+
+      value = ::Object.const_get(expected)
+      raise ::TypeError, "#{expected} is not a #{kind}" unless kind === value
+
+      value
+    end
+  end
+end

data/lib/matchi/eq.rb

@@ -1,85 +1,44 @@
 # frozen_string_literal: true
 
 module Matchi
-  # Value equivalence matcher that checks if two objects have identical values.
+  # Equivalence matcher: passes when the actual value is of the same class as
+  # the expected value and `eql?` to it.
   #
-  # This matcher verifies value equality using Ruby's Object#eql? method, which
-  # compares the values of objects rather than their identity. This is different
-  # from identity comparison (equal?) which checks if objects are the same instance.
+  # The expected value receives the `eql?` call, so the actual value cannot
+  # lie. The class check comes first because a few core `eql?` methods, such
+  # as `Hash#eql?`, hand the comparison back to an operand of another class;
+  # it costs nothing, since `eql?` never holds across classes for core values.
   #
-  # @example Basic usage with strings
-  #   matcher = Matchi::Eq.new("test")
-  #   matcher.match? { "test" }         # => true
-  #   matcher.match? { "test".dup }     # => true
-  #   matcher.match? { "other" }        # => false
-  #
-  # @example With numbers
-  #   matcher = Matchi::Eq.new(42)
-  #   matcher.match? { 42 }             # => true
-  #   matcher.match? { 42.0 }           # => false  # Different types
-  #   matcher.match? { 43 }             # => false
-  #
-  # @example With collections
-  #   array = [1, 2, 3]
-  #   matcher = Matchi::Eq.new(array)
-  #   matcher.match? { array.dup }      # => true   # Same values
-  #   matcher.match? { array }          # => true   # Same object
-  #   matcher.match? { [1, 2, 3] }      # => true   # Same values
-  #   matcher.match? { [1, 2] }         # => false  # Different values
-  #
-  # @see https://ruby-doc.org/core/Object.html#method-i-eql-3F
-  # @see Matchi::Be
+  # @example
+  #   Matchi::Eq.new("foo").match? { "foo" } # => true
+  #   Matchi::Eq.new(1).match? { 1.0 }       # => false (eql? is strict on type)
   class Eq
-    # Initialize the matcher with a reference value.
-    #
-    # @api public
-    #
-    # @param expected [#eql?] The expected equivalent value
-    #
-    # @return [Eq] a new instance of the matcher
-    #
-    # @example
-    #   Eq.new("test")              # Match strings with same value
-    #   Eq.new([1, 2, 3])           # Match arrays with same elements
+    # @param expected [#eql?] the expected value
     def initialize(expected)
       @expected = expected
     end
 
-    # Checks if the yielded object has a value equivalent to the expected object.
-    #
-    # This method uses Ruby's Object#eql? method, which performs value comparison.
-    # Two objects are considered equivalent if they have the same value, even if
-    # they are different instances.
-    #
-    # @api public
-    #
-    # @yield [] Block that returns the object to check
-    # @yieldreturn [Object] The object to verify equivalence with
-    #
-    # @return [Boolean] true if both objects have equivalent values
-    #
-    # @raise [ArgumentError] if no block is provided
-    #
-    # @example
-    #   matcher = Eq.new([1, 2, 3])
-    #   matcher.match? { [1, 2, 3] }      # => true
-    #   matcher.match? { [1, 2, 3].dup }  # => true
+    # @yieldreturn [Object] the actual value
+    # @return [Boolean]
+    # @raise [ArgumentError] when no block is given
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      @expected.eql?(yield)
+      Eq.eql?(@expected, yield)
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   Eq.new("test").to_s # => 'eq "test"'
+    # @return [String]
     def to_s
       "eq #{@expected.inspect}"
     end
+
+    # @param expected [#eql?] the value that receives the comparison
+    # @param actual [Object] a value from the code under test
+    # @return [Boolean] whether actual is of the class of expected and `eql?` to it
+    def self.eql?(expected, actual)
+      return false unless ::Kernel.instance_method(:class).bind_call(actual).equal?(expected.class)
+
+      expected.eql?(actual) ? true : false
+    end
   end
 end

data/lib/matchi/match.rb

@@ -1,83 +1,47 @@
 # frozen_string_literal: true
 
 module Matchi
-  # Pattern matching matcher that checks if a value matches a regular expression.
+  # Regular expression matcher: passes when the actual value is a String or a
+  # Symbol that the expected Regexp matches. Any other actual value fails, as
+  # does a string with an invalid or incompatible encoding.
   #
-  # This matcher verifies that a value matches a pattern using Ruby's Regexp#match? method.
-  # It's particularly useful for string validation, pattern matching, and text analysis.
-  # The matcher ensures secure pattern matching by requiring the pattern to respond to match?.
+  # Only a `Regexp` is accepted as pattern: with a `String` pattern,
+  # `String#match?` would turn the actual value into the regular expression,
+  # handing the comparison to the code under test. Use {Matchi::Satisfy} for
+  # other predicates.
   #
-  # @example Basic usage
-  #   matcher = Matchi::Match.new(/^test/)
-  #   matcher.match? { "test_string" }     # => true
-  #   matcher.match? { "other_string" }    # => false
-  #
-  # @example Case sensitivity
-  #   matcher = Matchi::Match.new(/^test$/i)
-  #   matcher.match? { "TEST" }            # => true
-  #   matcher.match? { "Test" }            # => true
-  #   matcher.match? { "testing" }         # => false
-  #
-  # @example Multiline patterns
-  #   matcher = Matchi::Match.new(/\A\d+\Z/m)
-  #   matcher.match? { "123" }             # => true
-  #   matcher.match? { "12.3" }            # => false
-  #
-  # @see https://ruby-doc.org/core/Regexp.html#method-i-match-3F
+  # @example
+  #   Matchi::Match.new(/^foo/).match? { "foobar" } # => true
+  #   Matchi::Match.new(/^foo/).match? { 42 }       # => false
   class Match
-    # Initialize the matcher with a pattern.
-    #
-    # @api public
-    #
-    # @param expected [#match?] A pattern that responds to match?
-    #
-    # @raise [ArgumentError] if the pattern doesn't respond to match?
-    #
-    # @return [Match] a new instance of the matcher
-    #
-    # @example
-    #   Match.new(/\d+/)           # Match digits
-    #   Match.new(/^test$/i)       # Case-insensitive match
-    #   Match.new(/\A\w+\Z/)       # Full string word characters
+    # @param expected [Regexp] the pattern
+    # @raise [ArgumentError] when expected is not a Regexp
     def initialize(expected)
-      raise ::ArgumentError, "expected must respond to match?" unless expected.respond_to?(:match?)
+      raise ::ArgumentError, "expected must be a Regexp (got: #{expected.inspect})" unless ::Regexp === expected
 
       @expected = expected
     end
 
-    # Checks if the yielded value matches the expected pattern.
-    #
-    # This method uses the pattern's match? method to perform the comparison.
-    # The match is performed on the entire string unless the pattern specifically
-    # allows partial matches.
-    #
-    # @api public
-    #
-    # @yield [] Block that returns the value to check
-    # @yieldreturn [#to_s] The value to match against the pattern
-    #
-    # @return [Boolean] true if the value matches the pattern
-    #
-    # @raise [ArgumentError] if no block is provided
-    #
-    # @example
-    #   matcher = Match.new(/^\d{3}-\d{2}-\d{4}$/)
-    #   matcher.match? { "123-45-6789" }   # => true
-    #   matcher.match? { "123456789" }     # => false
+    # @yieldreturn [Object] the actual value
+    # @return [Boolean]
+    # @raise [ArgumentError] when no block is given
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      @expected.match?(yield)
+      actual = yield
+      return false unless ::String === actual || ::Symbol === actual
+
+      string = ::Symbol === actual ? actual.name : actual
+      return false unless string.valid_encoding?
+
+      begin
+        @expected.match?(string)
+      rescue ::Encoding::CompatibilityError
+        false
+      end
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   Match.new(/^test/).to_s # => "match /^test/"
+    # @return [String]
     def to_s
       "match #{@expected.inspect}"
     end