duck_typer 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 881833f4db9f3c47049ad45e41c804a74a97db030438f43f933a388dc0f41cba
-  data.tar.gz: ad0b846adb0389c1db0cd49d9d245cb6c006c136e76ea0e7b3980a8d1fb4d3ce
+  metadata.gz: f51efa5736485f62f43d321e7e3d8d612081c6b5eca59bb66823d78cb38b5442
+  data.tar.gz: b75e8517ce41187b4df7b9f5260aa8da119feec892f34bc79e6e2865bd90bce8
 SHA512:
-  metadata.gz: be49c0476b7afe2c3df16fcede0480f242cfab68c0d1d0a637bba8ac4aa6070bada1c9bbd0350c556193340d62cc2a5665b9949b1c838840127574c2761ff57a
-  data.tar.gz: e9f4543f7117f6e7e3709a153cb316ce90974a984fc302bec71dc84c78fff89a706585cffc9581a24b6f9fa679df3dd0f971a0a82b44c1b78644ff1a8948ba1e
+  metadata.gz: 87660bdaeb1b662f9b8c2cdf9399d564c3444990d61fa61223dca973b12d21941575baebd91ff04e0b36e9a5bb2a0b1f56277ea4df43fdaf56d263eb3008b43a
+  data.tar.gz: 0ca5ae8d8de916e313655c97555582f8dbd7bff499492bcd90288a4e9d2e2da4c70641cd94de47ef9872be5e1b838894c9f6193f4b739524a0502c60a56fabb1

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.5.0] - 2026-03-13
+
+### Added
+- `name:` option: includes the interface name in failure messages
+  (e.g. `compatible "Linkable" interfaces`)
+- `namespace:` option: resolves a module's constants as the list of
+  objects to compare; infers the interface name from the module name
+  when `name:` is not given
+- Strict mode now notes itself in the failure message:
+  `(strict mode: positional argument names must match)`
+- `BulkInterfaceChecker` and `InterfaceChecker` raise
+  `PrivateMethodError` when a private method is specified in
+  `methods:`
+
+### Changed
+- `partial_interface_methods:` renamed to `methods:` across
+  `BulkInterfaceChecker`, `InterfaceChecker`, `assert_interfaces_match`,
+  and `have_matching_interfaces` (breaking change)
+- RSpec matcher now accepts a module as the subject via
+  `expect(namespace: MyModule).to have_matching_interfaces`
+- RSpec shared example now accepts `namespace:` as a keyword argument
+
+### Fixed
+- Numbered block parameters (`_1`) replaced with named ones to avoid
+  `Style/ItBlockParameter` lint failures on Ruby 3.4
+
 ## [0.4.0] - 2026-03-09
 
 ### Added

data/README.md

@@ -1,18 +1,18 @@
-# DuckTyper
+# Duck Typer
 
 [![CI](https://github.com/thoughtbot/duck_typer/actions/workflows/ci.yml/badge.svg)](https://github.com/thoughtbot/duck_typer/actions/workflows/ci.yml)
 
 <div align="center">
-  <img alt="DuckTyper mascot" src="assets/swan_mugshot.png" width="300">
+  <img alt="Duck Typer mascot" src="assets/swan_mugshot.png" width="300">
 </div>
 
 > If it quacks like a duck, it's a duck... or is it?
 
-DuckTyper enforces duck-typed interfaces in Ruby by comparing the
+Duck Typer enforces duck-typed interfaces in Ruby by comparing the
 public method signatures of classes, surfacing mismatches through
 your test suite.
 
-## Why DuckTyper?
+## Why Duck Typer?
 
 Ruby is a duck-typed language. When multiple classes play the same
 role, what matters is not what they _are_, but what they _do_ — the
@@ -25,17 +25,17 @@ from its dynamic nature: abstract base classes that raise
 signatures, or inheritance hierarchies that couple unrelated
 classes. These work, but they're not very Ruby.
 
-DuckTyper takes a different approach. It compares public method
+Duck Typer takes a different approach. It compares public method
 signatures directly and reports mismatches through your test suite —
 the natural place to enforce design constraints in Ruby. There's
 nothing to annotate and nothing to inherit from. The classes remain
-independent; DuckTyper simply verifies that they're speaking the
+independent; Duck Typer simply verifies that they're speaking the
 same language. The interface itself needs no declaration — it is
 the intersection of methods your classes define in common, a living
 document that evolves naturally.
 
 It's also useful during active development. When an interface
-evolves, implementations can easily fall out of sync. DuckTyper
+evolves, implementations can easily fall out of sync. Duck Typer
 catches that immediately and reports clear, precise error messages
 showing exactly which signatures diverged — keeping your classes
 aligned as the design changes.
@@ -56,7 +56,7 @@ bundle install
 
 ## Usage
 
-When interfaces don't match, DuckTyper reports the differing
+When interfaces don't match, Duck Typer reports the differing
 signatures:
 
 ```
@@ -120,7 +120,7 @@ end
 > If you prefer duck typing terminology, `assert_duck_types_match`
 > is available as an alias.
 
-By default, DuckTyper checks instance method interfaces. To check
+By default, Duck Typer checks instance method interfaces. To check
 class-level interfaces instead, pass `type: :class_methods`:
 
 ```ruby
@@ -151,6 +151,23 @@ count and kind (required, optional, rest) are compared. In strict
 mode, names must match exactly. Keyword argument names always
 matter regardless of this setting.
 
+To include the interface name in failure messages, use `name:`:
+
+```ruby
+assert_interfaces_match [StripeProcessor, PaypalProcessor],
+  name: "PaymentProcessor"
+```
+
+If your classes are organized under a module, pass it with
+`namespace:` instead of listing them explicitly:
+
+```ruby
+assert_interfaces_match namespace: Payments
+```
+
+Duck Typer will resolve the module's constants and infer the
+interface name from the module name when `name:` is not given.
+
 ### RSpec
 
 Require the RSpec integration in your `spec_helper.rb`:
@@ -198,6 +215,19 @@ expect([StripeProcessor, PaypalProcessor])
   .to have_matching_interfaces(strict: true)
 ```
 
+To include the interface name in failure messages, use `name:`:
+
+```ruby
+expect([StripeProcessor, PaypalProcessor])
+  .to have_matching_interfaces(name: "PaymentProcessor")
+```
+
+To check all classes in a module, pass it as a named subject:
+
+```ruby
+expect(namespace: Payments).to have_matching_interfaces
+```
+
 #### Shared example
 
 If you prefer shared examples, register one in `spec_helper.rb`
@@ -226,7 +256,8 @@ RSpec.describe "payment processors" do
 end
 ```
 
-The same `type:`, `methods:`, and `strict:` options are supported:
+The same `type:`, `methods:`, `strict:`, and `name:` options are
+supported:
 
 ```ruby
 it_behaves_like "an interface", [StripeProcessor, PaypalProcessor],
@@ -235,9 +266,15 @@ it_behaves_like "an interface", [StripeProcessor, PaypalProcessor],
   strict: true
 ```
 
+To check all classes in a module, pass it with `namespace:`:
+
+```ruby
+it_behaves_like "an interface", namespace: Payments
+```
+
 ## Limitations
 
-By default, DuckTyper checks the **structure** of public method
+By default, Duck Typer checks the **structure** of public method
 signatures — the number of parameters, their kinds (required,
 optional, keyword, rest, block), and keyword argument names. In
 strict mode, positional argument names are also compared. It does
@@ -245,7 +282,7 @@ not
 verify the following, which should be covered by your regular
 test suite:
 
-- **Parameter types.** DuckTyper only checks that both methods
+- **Parameter types.** Duck Typer only checks that both methods
   declare an `amount` parameter — not what type of value it
   expects. Two methods with identical signatures may still be
   incompatible if they expect different types.
@@ -253,7 +290,7 @@ test suite:
   but return completely different things.
 - **Behavior.** Matching signatures are a necessary but not
   sufficient condition for duck typing to work correctly at
-  runtime. DuckTyper catches structural drift, not semantic
+  runtime. Duck Typer catches structural drift, not semantic
   divergence.
 
 Some things are intentionally out of scope:
@@ -266,7 +303,7 @@ Some things are intentionally out of scope:
 
 ## Stability
 
-DuckTyper is intentionally minimal. It reflects Ruby's own method
+Duck Typer is intentionally minimal. It reflects Ruby's own method
 introspection API, which rarely changes — so the gem rarely needs
 to either. When it does change, it will most likely be for additive reasons:
 new API options, better error messages, or broader test framework
@@ -295,7 +332,7 @@ Thank you, [contributors]!
 
 ## License
 
-DuckTyper is Copyright (c) thoughtbot, inc.
+Duck Typer is Copyright (c) thoughtbot, inc.
 It is free software, and may be redistributed
 under the terms specified in the [LICENSE] file.
 

data/lib/duck_typer/bulk_interface_checker.rb

@@ -3,19 +3,37 @@
 module DuckTyper
   # Runs interface checks across all consecutive pairs of classes in a list.
   class BulkInterfaceChecker
-    def initialize(objects, type: :instance_methods, partial_interface_methods: nil, strict: false)
-      raise ArgumentError, "more than one class is required" if objects.size < 2
+    def initialize(objects = nil, namespace: nil, type: :instance_methods, methods: nil, strict: false, name: nil)
+      raise ArgumentError, "cannot specify both objects and namespace" if objects && namespace
+      raise ArgumentError, "objects or namespace is required" if objects.nil? && namespace.nil?
 
-      @objects = objects
-      @checker = InterfaceChecker.new(type:, partial_interface_methods:, strict:)
+      @objects = resolve_objects(objects, namespace)
+      raise ArgumentError, "more than one object is required" if @objects.size < 2
+
+      name ||= namespace&.name
+      @checker = InterfaceChecker.new(type:, methods:, strict:, name:)
     end
 
     def call(&block)
       @objects.each_cons(2).map do |left, right|
         result = @checker.call(left, right)
         block&.call(result)
+
         result
       end
     end
+
+    private
+
+    def resolve_objects(objects, namespace)
+      namespace ? resolve_namespace(namespace) : Array(objects)
+    end
+
+    def resolve_namespace(namespace)
+      namespace
+        .constants
+        .map { |const| namespace.const_get(const) }
+        .select { |const| const.is_a?(Module) }
+    end
   end
 end

data/lib/duck_typer/interface_checker/result.rb

@@ -5,11 +5,13 @@ module DuckTyper
     class Result
       attr_reader :left, :right
 
-      def initialize(left:, right:, match:, diff_message:)
+      def initialize(left:, right:, match:, diff_message:, name:, strict:)
         @left = left
         @right = right
         @match = match
         @diff_message = diff_message
+        @name = name
+        @strict = strict
       end
 
       def match?
@@ -21,11 +23,21 @@ module DuckTyper
 
         <<~MSG
           Expected #{@left} and #{@right} to implement compatible \
-          interfaces, but the following method signatures differ:
+          #{interface_label}, but the following method signatures differ:#{strict_note}
 
           #{@diff_message.call}
         MSG
       end
+
+      private
+
+      def interface_label
+        @name ? %("#{@name}" interfaces) : "interfaces"
+      end
+
+      def strict_note
+        @strict ? " (strict mode: positional argument names must match)" : ""
+      end
     end
   end
 end

data/lib/duck_typer/interface_checker.rb

@@ -7,10 +7,11 @@ require_relative "params_normalizer"
 module DuckTyper
   # Compares the public method signatures of two classes and reports mismatches.
   class InterfaceChecker
-    def initialize(type: :instance_methods, partial_interface_methods: nil, strict: false)
+    def initialize(type: :instance_methods, methods: nil, strict: false, name: nil)
       @type = type
-      @partial_interface_methods = partial_interface_methods
+      @methods = methods
       @strict = strict
+      @name = name
       @inspectors = Hash.new { |h, k| h[k] = MethodInspector.for(k, @type) }
     end
 
@@ -19,7 +20,7 @@ module DuckTyper
       match = -> { diff.empty? }
       diff_message = -> { diff_message(left, right, diff) }
 
-      Result.new(left:, right:, match:, diff_message:)
+      Result.new(left:, right:, match:, diff_message:, name: @name, strict: @strict)
     end
 
     private
@@ -33,9 +34,9 @@ module DuckTyper
     end
 
     def params_for_comparison(object, params_normalizer)
-      methods = @partial_interface_methods || @inspectors[object].public_methods
+      method_names = @methods || @inspectors[object].public_methods
 
-      methods.map do |method_name|
+      method_names.map do |method_name|
         params = method_params(method_name, object)
         args = params_normalizer.call(params).map do |type, name|
           case type
@@ -55,6 +56,10 @@ module DuckTyper
     end
 
     def method_params(method_name, object)
+      if @inspectors[object].private_method?(method_name)
+        raise PrivateMethodError, "private method `#{method_name}' for #{object}"
+      end
+
       @inspectors[object].parameters_for(method_name)
     rescue NameError
       raise MethodNotFoundError, "undefined method `#{method_name}' for #{object}"

data/lib/duck_typer/method_inspector.rb

@@ -25,6 +25,10 @@ module DuckTyper
         @object.public_methods - Object.methods
       end
 
+      def private_method?(method_name)
+        @object.singleton_class.private_method_defined?(method_name)
+      end
+
       def parameters_for(method_name)
         @object.method(method_name).parameters
       end
@@ -43,6 +47,10 @@ module DuckTyper
         @object.public_instance_methods - Object.methods
       end
 
+      def private_method?(method_name)
+        @object.private_method_defined?(method_name)
+      end
+
       def parameters_for(method_name)
         @object.instance_method(method_name).parameters
       end

data/lib/duck_typer/minitest.rb

@@ -4,9 +4,9 @@ require_relative "../duck_typer"
 
 module DuckTyper
   module Minitest
-    def assert_interfaces_match(objects, type: :instance_methods, methods: nil, strict: false)
+    def assert_interfaces_match(objects = nil, namespace: nil, type: :instance_methods, methods: nil, strict: false, name: nil)
       checker = BulkInterfaceChecker
-        .new(objects, type:, partial_interface_methods: methods, strict:)
+        .new(objects, namespace:, type:, methods:, strict:, name:)
 
       checker.call do |result|
         assert result.match?, result.failure_message

data/lib/duck_typer/rspec.rb

@@ -2,10 +2,13 @@
 
 require_relative "../duck_typer"
 
-RSpec::Matchers.define :have_matching_interfaces do |type: :instance_methods, methods: nil, strict: false|
-  match do |objects|
+RSpec::Matchers.define :have_matching_interfaces do |name: nil, type: :instance_methods, methods: nil, strict: false|
+  match do |actual|
+    namespace = actual.is_a?(Hash) ? actual[:namespace] : nil
+    objects = namespace ? nil : actual
+
     checker = DuckTyper::BulkInterfaceChecker
-      .new(objects, type:, partial_interface_methods: methods, strict:)
+      .new(objects, namespace:, type:, methods:, strict:, name:)
 
     @failures = checker.call.reject(&:match?)
     @failures.empty?
@@ -21,15 +24,16 @@ RSpec::Matchers.alias_matcher :have_matching_duck_types, :have_matching_interfac
 module DuckTyper
   module RSpec
     def self.define_shared_example(name = "an interface")
-      ::RSpec.shared_examples name do |*objects, type: :instance_methods, methods: nil, strict: false|
-        objects = objects.first
+      ::RSpec.shared_examples name do |*args, namespace: nil, name: nil, type: :instance_methods, methods: nil, strict: false|
+        objects = namespace ? nil : args.first
+
         # We intentionally avoid reusing the have_matching_interfaces matcher
         # here. Since this shared example is defined in gem code, RSpec filters
         # it from its backtrace, causing the Failure/Error: line to show an
         # internal RSpec constant instead of useful context.
         it "has compatible interfaces" do
           checker = DuckTyper::BulkInterfaceChecker
-            .new(objects, type:, partial_interface_methods: methods, strict:)
+            .new(objects, namespace:, type:, methods:, strict:, name:)
 
           failures = checker.call.reject(&:match?)
 

data/lib/duck_typer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DuckTyper
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/duck_typer.rb

@@ -8,5 +8,6 @@ require_relative "duck_typer/bulk_interface_checker"
 # method signatures of classes, surfacing mismatches through your test suite.
 module DuckTyper
   class MethodNotFoundError < StandardError; end
+  class PrivateMethodError < StandardError; end
   class TooManyParametersError < StandardError; end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: duck_typer
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Thiago A. Silva
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-09 00:00:00.000000000 Z
+date: 2026-03-13 00:00:00.000000000 Z
 dependencies: []
 description:
 email: