matchi 4.2.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eed23fa6963893d67a2cc6042f1f977f4fb0012013d53775e142bf92e1333a6d
-  data.tar.gz: 97c4f82fa65c4d46af8babc966005d8a2db81b85b26987cf5fe3444f14ef6a25
+  metadata.gz: 66ca7f8e6eb1fb3e7fa80907957f37af41fd04b678258199c0f1abfe784aa839
+  data.tar.gz: b25bc8c4da4bb7db33478cf7fda77e7119bf0fce94fdfd8310ab8d7c79f8638c
 SHA512:
-  metadata.gz: 271a0262764b04a77af4d149485395a1cf4d617c62e65dc6fab2388ad5873f3092ce08a9c273e836780623122599603a2a365c199f51ba20a2cda0f6a94f4867
-  data.tar.gz: baa9876cb229024e218d1ee07d4913805f9b64eaa49fab23e76b01d2fdab1f05ba4b952920cb127a3e3fe8c71990a7653d7513828e68faa056632ce0619854de
+  metadata.gz: 5c4b77eb03979138e162a7040380b9b74c31b16e1995e67e537eebd3d83074913fa39d377f29759e085f35a143a15f19407f77dcd6b2788fc5e2874b28f3591f
+  data.tar.gz: e570be50f7b9338a24489b791b0b118b0c892fcc6c8fdc7f375b6187cf63a430642d6a87c7b7016f28b9b6742e7a8c4c07cbcf94bf340a9d590dfbeb49ef0e87

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2025 Cyril Kato
+Copyright (c) 2015-2026 Cyril Kato
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -4,288 +4,152 @@
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/matchi/main)
 [![License](https://img.shields.io/github/license/fixrb/matchi?label=License&logo=github)](https://github.com/fixrb/matchi/raw/main/LICENSE.md)
 
-Matchi is a lightweight, framework-agnostic Ruby library that provides a comprehensive set of expectation matchers for elegant and secure testing. Its design focuses on simplicity, security, and extensibility.
+Framework-agnostic matchers for Ruby. Small, explicit, and written so that the object under test cannot forge a match.
 
 ![A Rubyist juggling between Matchi letters](https://github.com/fixrb/matchi/raw/main/img/matchi.png)
 
-## Key Features
-
-- **Framework Agnostic**: Easily integrate with any Ruby testing framework
-- **Security-Focused Design**: Built with robust type checking for most matchers
-- **Simple Integration**: Minimal setup required to get started
-- **Extensible**: Create custom matchers with just a few lines of code
-- **Comprehensive**: Rich set of built-in matchers for common testing scenarios
-- **Well Documented**: Extensive documentation with clear examples and implementation details
-- **Thread Safe**: Immutable matchers design ensures thread safety in concurrent environments
-
-### Security Considerations for Predicate Matchers
-
-While most Matchi matchers are designed to resist type spoofing, predicate matchers (`Matchi::Predicate`) rely on Ruby's dynamic method dispatch system and can be vulnerable to method overriding:
-
-```ruby
-# Example of predicate matcher vulnerability:
-matcher = Matchi::Predicate.new(:be_empty)
-array = []
-
-# Method overriding can defeat the matcher
-def array.empty?
-  false
-end
-
-matcher.match? { array } # => false (Even though array is empty!)
-```
-
-This limitation is inherent to Ruby's dynamic nature when working with predicate methods. If your tests require strict security guarantees, consider using direct state verification matchers instead of predicate matchers.
-
-## What is a Matchi Matcher?
-
-A Matchi matcher is a simple Ruby object that follows a specific contract:
-
-1. **Core Interface**: Every matcher must implement a `match?` method that:
-   - Accepts a block as its only parameter
-   - Executes that block to get the actual value
-   - Returns a boolean indicating if the actual value matches the expected criteria
-
-2. **Optional Description**: Matchers can implement a `to_s` method that returns a human-readable description of the match criteria
-
-Here's the simplest possible matcher:
-
-```ruby
-module Matchi
-  class SimpleEqual
-    def initialize(expected)
-      @expected = expected
-    end
-
-    def match?
-      raise ArgumentError, "a block must be provided" unless block_given?
-
-      @expected == yield
-    end
-
-    def to_s
-      "equal #{@expected.inspect}"
-    end
-  end
-end
-
-# Usage:
-matcher = Matchi::SimpleEqual.new(42)
-matcher.match? { 42 }     # => true
-matcher.match? { "42" }   # => false
-matcher.to_s              # => "equal 42"
-```
-
-This design provides several benefits:
-- **Lazy Evaluation**: The actual value is only computed when needed via the block
-- **Encapsulation**: Each matcher is a self-contained object with clear responsibilities
-- **Composability**: Matchers can be easily combined and reused
-- **Testability**: The contract is simple and easy to verify
-
 ## Installation
 
-Add to your Gemfile:
-
 ```ruby
+# Gemfile
 gem "matchi"
 ```
 
-Or install directly:
+Matchi requires Ruby 3.3 or later and has no runtime dependency.
 
-```ruby
-gem install matchi
-```
+## Usage
 
-## Quick Start
+A matcher is built with its expected value, then asked whether an actual value matches. The block yields the actual value once; `match?` answers `true` or `false`.
 
 ```ruby
 require "matchi"
 
-# Basic equality matching
-Matchi::Eq.new("hello").match? { "hello" } # => true
-
-# Type checking
-Matchi::BeAKindOf.new(Numeric).match? { 42 }   # => true
-Matchi::BeAKindOf.new(String).match? { 42 }    # => false
-
-# State change verification
-array = []
-Matchi::Change.new(array, :length).by(2).match? { array.push(1, 2) } # => true
+matcher = Matchi::Eq.new(42)
+matcher.match? { 42 } # => true
+matcher.match? { 41 } # => false
+matcher.to_s          # => "eq 42"
 ```
 
-## Core Matchers
-
-### Value Comparison
+Every `to_s` completes the sentence "expected ACTUAL to …", which is all a test framework needs:
 
 ```ruby
-# Exact equality (eql?)
-Matchi::Eq.new("test").match? { "test" } # => true
-Matchi::Eq.new([1, 2, 3]).match? { [1, 2, 3] } # => true
-
-# Object identity (equal?)
-symbol = :test
-Matchi::Be.new(symbol).match? { symbol } # => true
-string = "test"
-Matchi::Be.new(string).match? { string.dup } # => false
-```
-
-### Type Checking
-
-```ruby
-# Inheritance-aware type checking
-Matchi::BeAKindOf.new(Numeric).match? { 42.0 } # => true
-Matchi::BeAKindOf.new(Integer).match? { 42.0 } # => false
-
-# Exact type matching
-Matchi::BeAnInstanceOf.new(Float).match? { 42.0 } # => true
-Matchi::BeAnInstanceOf.new(Numeric).match? { 42.0 } # => false
-
-# Using class names as strings
-Matchi::BeAKindOf.new("Numeric").match? { 42.0 } # => true
-Matchi::BeAnInstanceOf.new("Float").match? { 42.0 } # => true
-```
-
-### State Changes
-
-```ruby
-# Verify exact changes
-counter = 0
-Matchi::Change.new(counter, :to_i).by(5).match? { counter += 5 } # => true
-
-# Verify minimum changes
-Matchi::Change.new(counter, :to_i).by_at_least(2).match? { counter += 3 } # => true
-
-# Verify maximum changes
-Matchi::Change.new(counter, :to_i).by_at_most(5).match? { counter += 3 } # => true
-
-# Track value transitions
-string = "hello"
-Matchi::Change.new(string, :to_s).from("hello").to("HELLO").match? { string.upcase! } # => true
+# Minitest
+def assert_matches(matcher, actual)
+  assert matcher.match? { actual }, "expected #{actual.inspect} to #{matcher}"
+end
 
-# Simple change detection
-array = []
-Matchi::Change.new(array, :length).match? { array << 1 } # => true
+def refute_matches(matcher, actual)
+  refute matcher.match? { actual }, "expected #{actual.inspect} not to #{matcher}"
+end
 
-# Check final state only
-counter = 0
-Matchi::Change.new(counter, :to_i).to(5).match? { counter = 5 } # => true
+assert_matches Matchi::BeAKindOf.new(Numeric), 42
+refute_matches Matchi::Match.new(/^foo/), "bar"
 ```
 
-### Pattern Matching
-
-```ruby
-# Regular expressions
-Matchi::Match.new(/^test/).match? { "test_string" } # => true
-Matchi::Match.new(/^\d{3}-\d{2}$/).match? { "123-45" } # => true
-
-# Custom predicates with Satisfy
-Matchi::Satisfy.new { |x| x.positive? && x < 10 }.match? { 5 } # => true
-Matchi::Satisfy.new { |arr| arr.all?(&:even?) }.match? { [2, 4, 6] } # => true
-
-# Built-in predicates
-Matchi::Predicate.new(:be_empty).match? { [] } # => true
-Matchi::Predicate.new(:have_key, :name).match? { { name: "Alice" } } # => true
-```
+Negation is the framework's job: Matchi has no `not_to`, it answers a boolean.
 
-### Exception Handling
+## Matchers
 
 ```ruby
-# Verify raised exceptions
-Matchi::RaiseException.new(ArgumentError).match? { raise ArgumentError } # => true
+require "matchi"
 
-# Works with inheritance
-Matchi::RaiseException.new(StandardError).match? { raise ArgumentError } # => true
+# Identity (equal?) and equivalence (eql?)
+Matchi::Be.new(:foo).match? { :foo }            # => true
+Matchi::Eq.new("foo").match? { "foo" }          # => true
+Matchi::Eq.new(1).match? { 1.0 }                # => false
 
-# Using exception class names
-Matchi::RaiseException.new("ArgumentError").match? { raise ArgumentError } # => true
-```
+# Types: a module, or its name resolved when the matcher runs
+Matchi::BeAKindOf.new(Numeric).match? { 42 }       # => true
+Matchi::BeAnInstanceOf.new(:Integer).match? { 42 } # => true
+Matchi::BeAnInstanceOf.new(Numeric).match? { 42 }  # => false
 
-### Numeric Comparisons
+# Numeric proximity; a non-Numeric actual value fails
+Matchi::BeWithin.new(0.01).of(0.3).match? { 0.1 + 0.2 } # => true
 
-```ruby
-# Delta comparisons
-Matchi::BeWithin.new(0.5).of(3.0).match? { 3.2 } # => true
-Matchi::BeWithin.new(2).of(10).match? { 9 } # => true
-```
+# Patterns and predicates
+Matchi::Match.new(/^foo/).match? { "foobar" }            # => true
+Matchi::Satisfy.new { |v| v > 41 }.match? { 42 }         # => true
+Matchi::Predicate.new(:be_empty).match? { [] }           # => true (calls empty?)
+Matchi::Predicate.new(:have_key, :a).match? { { a: 1 } } # => true (calls has_key?(:a))
 
-## Creating Custom Matchers
+# Exceptions, by class or by name, optionally with a message (String or Regexp)
+Matchi::RaiseException.new(ZeroDivisionError).match? { 1 / 0 }               # => true
+Matchi::RaiseException.new("Errno::ENOENT").match? { File.read("/missing") } # => true
+Matchi::RaiseException.new(ZeroDivisionError, /by 0/).match? { 1 / 0 }       # => true
 
-Creating custom matchers is straightforward:
+# State changes, observed through a public method
+list = []
+Matchi::Change.new(list, :length).match? { list << 1 }                # => true
+Matchi::Change.new(list, :length).by(2).match? { list.push(1, 2) }    # => true
+Matchi::Change.new(list, :length).by_at_least(1).match? { list << 1 } # => true
+Matchi::Change.new(list, :length).by_at_most(1).match? { list << 1 }  # => true
 
-```ruby
-module Matchi
-  class BePositive
-    def match?
-      yield.positive?
-    end
-
-    def to_s
-      "be positive"
-    end
-  end
-end
-
-matcher = Matchi::BePositive.new
-matcher.match? { 42 }  # => true
-matcher.match? { -1 }  # => false
+list = []
+Matchi::Change.new(list, :length).to(1).match? { list << 1 }         # => true
+Matchi::Change.new(list, :length).from(1).to(2).match? { list << 1 } # => true
 ```
 
-## Security Best Practices
+`BeWithin.new(delta)` and `Change#from(value)` are builders, not matchers: they do not respond to `match?` until `of` or `to` completes them.
 
-### Proper Value Comparison Order
+Arguments are validated when the matcher is built (`ArgumentError`); a name is resolved when the matcher runs (`NameError`, or `TypeError` when the constant is not a module). A block is always required by `match?`. Whatever the actual value or an observed method raises propagates; `RaiseException` catches what its block raises, not what its message filter or the resolution of its name raises.
 
-One of the most critical aspects when implementing matchers is the order of comparison between expected and actual values. Always compare values in this order:
+`RaiseException` catches every `Exception`, including `SystemExit` and `Interrupt`, so that a specification can assert on them; an unexpected `exit` inside the block is a failure, not the end of the process.
 
-```ruby
-# GOOD: Expected value controls the comparison
-expected_value.eql?(actual_value)
-# BAD: Actual value controls the comparison
-actual_value.eql?(expected_value)
-```
+`Change` observes a value: when the observed method returns the same unfrozen object twice (an `attr_reader` on a mutated array, say), `match?` raises instead of reporting no change. Observe `items.length`, or use `to`.
 
-#### Why This Matters
+## Writing a matcher
 
-The order is crucial because the object receiving the comparison method controls how the comparison is performed. When testing, the actual value might come from untrusted or malicious code that could override comparison methods:
+Any object that responds to `match?` with a block and to `to_s` is a matcher:
 
 ```ruby
-# Example of how comparison can be compromised
-class MaliciousString
-  def eql?(other)
-    true  # Always returns true regardless of actual equality
+class BePositive
+  def match?
+    yield.positive?
   end
 
-  def ==(other)
-    true  # Always returns true regardless of actual equality
+  def to_s
+    "be positive"
   end
 end
 
-actual = MaliciousString.new
-expected = "expected string"
-actual.eql?(expected)      # => true (incorrect result!)
-expected.eql?(actual)      # => false (correct result)
+BePositive.new.match? { 42 } # => true
 ```
 
-This is why Matchi's built-in matchers are implemented with this security consideration in mind. For example, the `Eq` matcher:
+Every matcher in Matchi follows two rules, which are worth keeping in your own:
 
-```ruby
-# Implementation in Matchi::Eq
-def match?
-  @expected.eql?(yield) # Expected value controls the comparison
-end
-```
+- **The expected value receives the comparison.** `Matchi::Eq.new(a).match? { b }` evaluates `a.eql?(b)`, never `b.eql?(a)`, so an actual value that redefines `eql?` cannot pass; since `Hash#eql?` hands the comparison back to an operand of another class, `Eq` also requires the two values to be of the same class. Classes are compared with `Module#===`, the class of the actual value is read with `Kernel#class` bound to it, and `BeWithin` only subtracts core numbers, for the same reason.
+- **A predicate answers `true` or `false`.** `Satisfy` and `Predicate` raise a `TypeError` on any other value instead of treating it as truthy.
 
-## Extensions
+Two matchers depend on the honesty of the object under test, because they use values it produces: `Predicate` calls one of its methods, and `Change` (with `by`, `by_at_least`, `by_at_most`) compares two values returned by the observed method, including the subtraction between them. So does the message filter of `RaiseException`, which reads the exception's own message. `Change#to` and `from … to` compare with the expected value and do not.
 
-### matchi-fix
+A class or an exception given by name (`:Duck`, `"Errno::ENOENT"`) is resolved from `Object` when the matcher runs, so a specification can be written before the class it describes is loaded. An `autoload` or an `Object.const_missing` defined by the code under test takes part in that resolution, so a name does not carry the guarantee a module does. Names are ASCII constant paths; `"::Integer"` is not accepted.
 
-The [matchi-fix gem](https://rubygems.org/gems/matchi-fix) extends Matchi with support for testing against [Fix](https://github.com/fixrb/fix) specifications. It provides a seamless integration between Matchi's matcher interface and Fix's powerful specification system.
+## Differences from RSpec
 
-```ruby
-# Add to your Gemfile
-gem "matchi-fix"
-```
+If you come from RSpec or Minitest, these will surprise you:
+
+- `Eq` is RSpec's `eql`, not its `eq`: it compares with `eql?`, so `1` is not `1.0`, and a value object that only defines `==` never matches. Define `eql?` and `hash` on it, or use `Satisfy`. `Integer#==` hands the comparison to the other operand, which is why Matchi does not use it.
+- `Match` takes a `Regexp` only. For a literal substring, `Matchi::Match.new(Regexp.new(Regexp.escape("a.b")))`.
+- `RaiseException` is `raise_error`; it needs an exception class, or its name, and takes an optional message.
+- `Change#to` demands a change: a value already equal to the target does not pass. `Change` without a refinement needs the observed method to return a value, not the mutated object.
+- `Predicate` only calls a method of the actual value: `be_nil` calls `nil?`, but `be_truthy`, `be_falsey` and `be_a` are not predicates and do not exist. Use `Be.new(nil)`, `Satisfy`, `BeAKindOf`.
+- There is no `and`, `or`, `not_to` or `all`: compose in your framework, with plain booleans.
+
+## Changes in 5.0
 
-This extension adds a `Fix` matcher that allows you to verify implementation conformance to Fix test specifications across different testing frameworks like Minitest and RSpec.
+- `BeAKindOf`, `BeAnInstanceOf` and `RaiseException` accept a module directly, so anonymous classes work. A name is still accepted; it must be a constant path (`"Foo::bar"` is rejected at construction) and resolve to a module, or a class for `BeAnInstanceOf` and an exception class for `RaiseException`. `BeAnInstanceOf` rejects a module that is not a class.
+- `RaiseException` compares with `Module#===` and always answers `true` or `false`; `Module#<=` could answer `nil` and let the exception control the comparison. A non-exception class is rejected at construction. An expected message, `String` or `Regexp`, can be given.
+- `Match` accepts a `Regexp` only, and fails on an actual value that is neither a `String` nor a `Symbol`, or whose encoding is invalid or incompatible. With a `String` pattern, the actual value would have become the regular expression.
+- `Eq`, `Change#to` and `from … to` require the actual value to be of the class of the expected value, so that `Hash#eql?` cannot hand the comparison to the object under test.
+- `Satisfy` requires a `true` or `false` answer (`TypeError`), as `Predicate` already did. The error names the class of the answer, never its `inspect`.
+- `Predicate` and `Change` reach the object under test through `Kernel#public_send`: a private or protected predicate is now a `NoMethodError`. `Change` accepts a `String` method name and no longer checks `respond_to?` at construction; a missing method is a `NoMethodError` when the matcher runs.
+- `BeWithin::Of` only subtracts an `Integer`, a `Float`, a `Rational` or a `BigDecimal`; any other actual value fails, including a user-defined `Numeric` that could control the subtraction through `coerce`. Deltas and expected values, there and in `by`, `by_at_least`, `by_at_most`, must be finite real numbers (`NaN`, infinities and `Complex` are rejected).
+- `BeWithin` without `of` and `Change#from` without `to` no longer respond to `match?`.
+- `from … to` compares with `eql?`, like `to` and `Eq` already did; `to` requires a change; both always evaluate the block. `Change` raises a `TypeError` when the observed method returns the same unfrozen object twice: in particular, asserting that an attribute holding an unfrozen object (a `Time`, an `Array`) did not change now raises instead of answering `false`. The three `by` refinements are one class, `Change::Delta`; `Change::From::To` is `Change::FromTo`.
+- Descriptions are stable: `Change#to_s` names the observed class and method (`change Array#length`), an anonymous class reads `an anonymous class`, and no `to_s` calls `inspect` on an object under test.
+- Error messages are rewritten and all read `X must be … (got: …)`; `Predicate::PREFIXES` is gone.
+- The `Matchi` helper module removed in 4.2 is not back: `Matchi` is a namespace. Frameworks define their own helpers.
+- Ruby 3.3 or later.
 
 ## Versioning
 

data/lib/matchi/be.rb

@@ -1,83 +1,28 @@
 # frozen_string_literal: true
 
 module Matchi
-  # Identity matcher that checks if two objects are the exact same instance.
+  # Identity matcher: passes when the actual value is the very same object as
+  # the expected one (`equal?`).
   #
-  # This matcher verifies object identity using Ruby's Object#equal? method, which
-  # compares object IDs to determine if two references point to the exact same object
-  # in memory. This is different from equality comparison (==) which compares values.
-  #
-  # @example Basic usage with symbols
-  #   matcher = Matchi::Be.new(:foo)
-  #   matcher.match? { :foo }             # => true
-  #   matcher.match? { :bar }             # => false
-  #
-  # @example Identity comparison with strings
-  #   string = "test"
-  #   matcher = Matchi::Be.new(string)
-  #   matcher.match? { string }           # => true
-  #   matcher.match? { string.dup }       # => false
-  #   matcher.match? { "test" }           # => false
-  #
-  # @example With mutable objects
-  #   array = [1, 2, 3]
-  #   matcher = Matchi::Be.new(array)
-  #   matcher.match? { array }            # => true
-  #   matcher.match? { array.dup }        # => false
-  #   matcher.match? { [1, 2, 3] }        # => false
-  #
-  # @see https://ruby-doc.org/core/Object.html#method-i-equal-3F
-  # @see Matchi::Eq
+  # @example
+  #   Matchi::Be.new(:foo).match? { :foo } # => true
+  #   Matchi::Be.new("a").match? { "a".dup } # => false (another object)
   class Be
-    # Initialize the matcher with a reference object.
-    #
-    # @api public
-    #
-    # @param expected [#equal?] The expected identical object
-    #
-    # @return [Be] a new instance of the matcher
-    #
-    # @example
-    #   string = "test"
-    #   Be.new(string)             # Match only the same string instance
+    # @param expected [Object] the expected object
     def initialize(expected)
       @expected = expected
     end
 
-    # Checks if the yielded object is the same instance as the expected object.
-    #
-    # This method uses Ruby's Object#equal? method, which performs identity comparison
-    # by comparing object IDs. Two objects are considered identical only if they are
-    # the exact same instance in memory.
-    #
-    # @api public
-    #
-    # @yield [] Block that returns the object to check
-    # @yieldreturn [Object] The object to verify identity with
-    #
-    # @return [Boolean] true if both objects are the same instance
-    #
-    # @raise [ArgumentError] if no block is provided
-    #
-    # @example
-    #   obj = "test"
-    #   matcher = Be.new(obj)
-    #   matcher.match? { obj }      # => true
-    #   matcher.match? { obj.dup }  # => 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.equal?(yield)
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   Be.new("test").to_s # => 'be "test"'
+    # @return [String]
     def to_s
       "be #{@expected.inspect}"
     end

data/lib/matchi/be_a_kind_of.rb

@@ -1,134 +1,39 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # Type matcher that checks if an object is an instance of a class or one of its subclasses.
-  #
-  # This matcher provides a reliable way to verify object types while respecting Ruby's
-  # inheritance hierarchy. It uses the case equality operator (===) which is Ruby's
-  # built-in mechanism for type checking, ensuring consistent behavior with Ruby's
-  # own type system.
-  #
-  # @example Basic usage with simple types
-  #   matcher = Matchi::BeAKindOf.new(Numeric)
-  #   matcher.match? { 42 }     # => true
-  #   matcher.match? { 42.0 }   # => true
-  #   matcher.match? { "42" }   # => false
-  #
-  # @example Working with inheritance hierarchies
-  #   class Animal; end
-  #   class Dog < Animal; end
-  #   class GermanShepherd < Dog; end
-  #
-  #   matcher = Matchi::BeAKindOf.new(Animal)
-  #   matcher.match? { Dog.new }             # => true
-  #   matcher.match? { GermanShepherd.new }  # => true
-  #   matcher.match? { Object.new }          # => false
-  #
-  # @example Using with modules and interfaces
-  #   module Swimmable
-  #     def swim; end
-  #   end
-  #
-  #   class Duck
-  #     include Swimmable
-  #   end
-  #
-  #   matcher = Matchi::BeAKindOf.new(Swimmable)
-  #   matcher.match? { Duck.new }     # => true
-  #   matcher.match? { Object.new }   # => false
+  # Type matcher: passes when the actual value is an instance of the expected
+  # module or of one of its descendants (`Module#===`, so a `BasicObject` is
+  # handled and an object redefining `is_a?` cannot lie).
   #
-  # @example Different ways to specify the class
-  #   # Using class directly
-  #   Matchi::BeAKindOf.new(String)
+  # The expected module can be given directly, or by name; see
+  # {Matchi::Constant}.
   #
-  #   # Using class name as string
-  #   Matchi::BeAKindOf.new("String")
-  #
-  #   # Using class name as symbol
-  #   Matchi::BeAKindOf.new(:String)
-  #
-  #   # Using namespaced class
-  #   Matchi::BeAKindOf.new("MyModule::MyClass")
-  #
-  # @see Matchi::BeAnInstanceOf
-  # @see https://ruby-doc.org/core/Module.html#method-i-3D-3D-3D
+  # @example
+  #   Matchi::BeAKindOf.new(Numeric).match? { 42 }    # => true
+  #   Matchi::BeAKindOf.new(:Numeric).match? { "42" } # => false
   class BeAKindOf
-    # Creates a new type matcher for the specified class.
-    #
-    # @api public
-    #
-    # @param expected [Class, #to_s] The expected class or its name
-    #   Can be provided as a Class object, String, or Symbol
-    #
-    # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
-    #
-    # @return [BeAKindOf] a new instance of the matcher
-    #
-    # @example
-    #   BeAKindOf.new(String)          # Using class
-    #   BeAKindOf.new("String")        # Using string
-    #   BeAKindOf.new(:String)         # Using symbol
+    # @param expected [Module, String, Symbol] the expected module, or its name
+    # @raise [ArgumentError] when expected is neither a Module nor a constant name
     def initialize(expected)
-      @expected = String(expected)
-      return if /\A[A-Z]/.match?(@expected)
-
-      raise ArgumentError,
-            "expected must start with an uppercase letter (got: #{@expected})"
+      @expected = Constant.normalize(expected, ::Module)
     end
 
-    # Checks if the yielded object is an instance of the expected class or its subclasses.
-    #
-    # This method leverages Ruby's case equality operator (===) which provides a reliable
-    # way to check class hierarchy relationships. When a class is the receiver of ===,
-    # it returns true if the argument is an instance of that class or one of its subclasses.
-    #
-    # @api public
-    #
-    # @yield [] Block that returns the object to check
-    # @yieldreturn [Object] The object to verify the type of
-    #
-    # @return [Boolean] true if the object is an instance of the expected class or one of its subclasses
-    #
-    # @raise [ArgumentError] if no block is provided
-    # @raise [NameError] if the expected class cannot be found
-    #
-    # @example Simple type check
-    #   matcher = BeAKindOf.new(Numeric)
-    #   matcher.match? { 42 }      # => true
-    #
-    # @example With inheritance
-    #   matcher = BeAKindOf.new(Animal)
-    #   matcher.match? { Dog.new } # => true
+    # @yieldreturn [Object] the actual value
+    # @return [Boolean]
+    # @raise [ArgumentError] when no block is given
+    # @raise [NameError] when the name is not defined
+    # @raise [TypeError] when the name does not resolve to a Module
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      expected_class === yield # rubocop:disable Style/CaseEquality
+      Constant.resolve(@expected, ::Module) === yield
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   BeAKindOf.new(String).to_s # => "be a kind of String"
+    # @return [String]
     def to_s
-      "be a kind of #{@expected}"
-    end
-
-    private
-
-    # Resolves the expected class name to an actual Class object.
-    #
-    # @api private
-    #
-    # @return [Class] The resolved class object
-    # @raise [NameError] If the class name cannot be resolved to an actual class
-    #
-    # @note This method handles both string and symbol class names through constant resolution
-    def expected_class
-      ::Object.const_get(@expected)
+      "be a kind of #{Constant.label(@expected)}"
     end
   end
 end