Add canonical interface checker

Pairwise comparison verifies that every adjacent pair of classes in a
list agree with each other, which works well when all classes are peers
with no single authoritative definition. Canonical interface comparison
takes a different approach: one class is designated as the reference,
and every other class is checked against it directly. This is useful
when the interface already has a clear owner — an abstract base, a
well-established implementation, or a purpose-built interface class —
and you want to confirm that all other implementations conform to that
definition. Because all comparisons share the same right-hand side,
failures from multiple classes are aggregated into a single result,
making it easier to see the full picture at a glance.

- Adds `CanonicalInterfaceChecker`, which compares every class in a list
  against a single canonical reference rather than in consecutive pairs.
  All failures are aggregated into one result, so a single assertion
  reports every non-conforming class at once.

- Exposes `assert_canonical_interface_match(canonical, objects, **opts)`
  in the Minitest integration and
  `implement_canonical_interface(canonical, **opts)` in the RSpec
  integration. All existing options (`type:`, `methods:`, `strict:`,
  `name:`, `namespace:`) are supported.

- Extracts shared checker initialization (argument validation, object
  resolution, name inference, checker construction) into
  `InterfaceSetup`, eliminating duplication between
  `BulkInterfaceChecker` and `CanonicalInterfaceChecker`.

Author: thiagoa

README.md

@@ -168,6 +168,54 @@ 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.
 
+#### Canonical interface
+
+Use `assert_canonical_interface_match` when you have a reference
+class and want to verify that every implementation conforms to it.
+The canonical class comes first — following the `assert_equal
+expected, actual` convention — followed by the list of classes to
+check:
+
+```ruby
+def test_payment_processors_implement_canonical_interface
+  assert_canonical_interface_match PaymentBase, [
+    StripeProcessor,
+    PaypalProcessor,
+    BraintreeProcessor
+  ]
+end
+```
+
+You can also pass a `namespace:` instead of a list:
+
+```ruby
+assert_canonical_interface_match PaymentBase, namespace: Payments
+```
+
+When multiple classes fail, a single assertion reports all of them
+at once:
+
+```
+Expected all objects to implement compatible interfaces defined by
+PaymentBase, but the following method signatures differ:
+
+StripeProcessor: charge(amount)
+PaymentBase: charge(amount, currency:)
+
+PaypalProcessor: refund not defined
+PaymentBase: refund(transaction_id)
+```
+
+The same `type:`, `methods:`, `strict:`, and `name:` options are
+supported:
+
+```ruby
+assert_canonical_interface_match PaymentBase, [StripeProcessor, PaypalProcessor],
+  methods: %i[charge refund],
+  strict: true,
+  name: "PaymentProcessor"
+```
+
 ### RSpec
 
 Require the RSpec integration in your `spec_helper.rb`:
@@ -228,6 +276,40 @@ To check all classes in a module, pass it as a named subject:
 expect(namespace: Payments).to have_matching_interfaces
 ```
 
+#### Canonical interface
+
+Use `implement_canonical_interface` when you have a reference class
+and want to verify that a list of classes conforms to it:
+
+```ruby
+RSpec.describe "payment processors" do
+  it "implement the canonical interface" do
+    expect([StripeProcessor, PaypalProcessor, BraintreeProcessor])
+      .to implement_canonical_interface(PaymentBase)
+  end
+end
+```
+
+You can also pass a namespace:
+
+```ruby
+expect(namespace: Payments).to implement_canonical_interface(PaymentBase)
+```
+
+The same `type:`, `methods:`, `strict:`, and `name:` options are
+supported:
+
+```ruby
+expect([StripeProcessor, PaypalProcessor])
+  .to implement_canonical_interface(PaymentBase,
+    methods: %i[charge refund],
+    strict: true,
+    name: "PaymentProcessor")
+```
+
+When multiple classes fail, the failure message reports all of them
+at once.
+
 #### Shared example
 
 If you prefer shared examples, register one in `spec_helper.rb`

lib/duck_typer.rb

@@ -3,6 +3,7 @@
 require_relative "duck_typer/version"
 require_relative "duck_typer/interface_checker"
 require_relative "duck_typer/bulk_interface_checker"
+require_relative "duck_typer/canonical_interface_checker"
 
 # DuckTyper enforces duck-typed interfaces in Ruby by comparing the public
 # method signatures of classes, surfacing mismatches through your test suite.

lib/duck_typer/bulk_interface_checker.rb

@@ -1,39 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "interface_setup"
+
 module DuckTyper
   # Runs interface checks across all consecutive pairs of classes in a list.
   class BulkInterfaceChecker
     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 = 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:)
+      @setup = InterfaceSetup.new(objects, namespace:, type:, methods:, strict:, name:, minimum: 2)
     end
 
     def call(&block)
-      @objects.each_cons(2).map do |left, right|
-        result = @checker.call(left, right)
+      @setup.objects.each_cons(2).map do |left, right|
+        result = @setup.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

lib/duck_typer/canonical_interface_checker.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "canonical_interface_checker/result"
+require_relative "interface_setup"
+
+module DuckTyper
+  # Compares each class in a list against a single canonical reference class.
+  class CanonicalInterfaceChecker
+    def initialize(objects = nil, canonical:, namespace: nil, type: :instance_methods, methods: nil, strict: false, name: nil)
+      @setup = InterfaceSetup.new(objects, namespace:, type:, methods:, strict:, name:, minimum: 1)
+      @canonical = canonical
+    end
+
+    def call
+      results = @setup.objects.map { |obj| @setup.checker.call(obj, @canonical) }
+
+      Result.new(canonical: @canonical, results:, name: @setup.name, strict: @setup.strict)
+    end
+  end
+end

lib/duck_typer/canonical_interface_checker/result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../result_formatting"
+
+module DuckTyper
+  class CanonicalInterfaceChecker
+    class Result
+      include ResultFormatting
+
+      def initialize(canonical:, results:, name:, strict:)
+        @canonical = canonical
+        @results = results
+        @name = name
+        @strict = strict
+      end
+
+      def match?
+        @results.all?(&:match?)
+      end
+
+      def failure_message
+        return if match?
+
+        failing = @results.reject(&:match?)
+
+        <<~MSG
+          Expected all objects to implement compatible \
+          #{interface_label} defined by #{@canonical}, \
+          but the following method signatures differ:#{strict_note}
+
+          #{failing.map(&:diff_message).join("\n")}
+        MSG
+      end
+    end
+  end
+end

lib/duck_typer/interface_checker/result.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require_relative "../result_formatting"
+
 module DuckTyper
   class InterfaceChecker
     class Result
+      include ResultFormatting
+
       attr_reader :left, :right
 
       def initialize(left:, right:, match:, diff_message:, name:, strict:)
@@ -18,6 +22,10 @@ def match?
         @match.call
       end
 
+      def diff_message
+        @diff_message.call
+      end
+
       def failure_message
         return if match?
 
@@ -28,16 +36,6 @@ def failure_message
           #{@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

lib/duck_typer/interface_setup.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "interface_checker"
+
+module DuckTyper
+  class InterfaceSetup
+    attr_reader :objects, :checker, :name, :strict
+
+    def initialize(objects, namespace:, type:, methods:, strict:, name:, minimum: 0)
+      raise ArgumentError, "cannot specify both objects and namespace" if objects && namespace
+      raise ArgumentError, "objects or namespace is required" if objects.nil? && namespace.nil?
+
+      @objects = resolve_objects(objects, namespace)
+      raise ArgumentError, "at least #{minimum} object(s) required" if @objects.size < minimum
+
+      name ||= namespace&.name
+      @name = name
+      @strict = strict
+      @checker = InterfaceChecker.new(type:, methods:, strict:, name:)
+    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

lib/duck_typer/minitest.rb

@@ -14,5 +14,13 @@ def assert_interfaces_match(objects = nil, namespace: nil, type: :instance_metho
     end
 
     alias_method :assert_duck_types_match, :assert_interfaces_match
+
+    def assert_canonical_interface_match(canonical, objects = nil, namespace: nil, type: :instance_methods, methods: nil, strict: false, name: nil)
+      checker = CanonicalInterfaceChecker
+        .new(objects, canonical:, namespace:, type:, methods:, strict:, name:)
+
+      result = checker.call
+      assert result.match?, result.failure_message
+    end
   end
 end

lib/duck_typer/result_formatting.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DuckTyper
+  module ResultFormatting
+    private
+
+    def interface_label
+      @name ? %("#{@name}" interfaces) : "interfaces"
+    end
+
+    def strict_note
+      @strict ? " (strict mode: positional argument names must match)" : ""
+    end
+  end
+end

lib/duck_typer/rspec.rb

@@ -21,6 +21,23 @@
 
 RSpec::Matchers.alias_matcher :have_matching_duck_types, :have_matching_interfaces
 
+RSpec::Matchers.define :implement_canonical_interface do |canonical, 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::CanonicalInterfaceChecker
+      .new(objects, canonical:, namespace:, type:, methods:, strict:, name:)
+
+    @result = checker.call
+    @result.match?
+  end
+
+  failure_message do
+    @result.failure_message
+  end
+end
+
 module DuckTyper
   module RSpec
     def self.define_shared_example(name = "an interface")