duck_typer 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f51efa5736485f62f43d321e7e3d8d612081c6b5eca59bb66823d78cb38b5442
-  data.tar.gz: b75e8517ce41187b4df7b9f5260aa8da119feec892f34bc79e6e2865bd90bce8
+  metadata.gz: e7c4910b3357c23523997ed6cbb76cc1add4824af460fe8845390f1f69cfe2e6
+  data.tar.gz: 4aea61000506666b3ce649e08398247c9ab72c75826cc9e4819e91471547f8dd
 SHA512:
-  metadata.gz: 87660bdaeb1b662f9b8c2cdf9399d564c3444990d61fa61223dca973b12d21941575baebd91ff04e0b36e9a5bb2a0b1f56277ea4df43fdaf56d263eb3008b43a
-  data.tar.gz: 0ca5ae8d8de916e313655c97555582f8dbd7bff499492bcd90288a4e9d2e2da4c70641cd94de47ef9872be5e1b838894c9f6193f4b739524a0502c60a56fabb1
+  metadata.gz: 48bcd0be970572a490e373064d3894bd174aaffc29b52a0c7b8beea030530b0661bde8221b01a0b681d3511478259cb7edfe858383def4a1e8f22f1afec36577
+  data.tar.gz: 923d8722ae7ac8fb7f86aa12292056014fb00f5328c2034d63ed8b3c87984a0cce8890a0983d48fb2148b7d9ff1eb68888079cbaac90d4a7a7ebf33c8b5d6156

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.6.0] - 2026-05-15
+
+### Added
+- `CanonicalInterfaceChecker`: compares every class in a list
+  against a single canonical reference rather than in consecutive
+  pairs; all failures are aggregated into one result
+- `assert_canonical_interface_match` Minitest assertion
+- `implement_canonical_interface` RSpec matcher
+- `InterfaceSetup`: extracted shared checker initialization
+  (argument validation, object resolution, name inference) from
+  `BulkInterfaceChecker` and `CanonicalInterfaceChecker`
+- `ResultFormatting`: extracted shared result formatting logic
+
+### Changed
+- Improved test accuracy and coverage for
+  `BulkInterfaceChecker` and `InterfaceChecker`
+
 ## [0.5.0] - 2026-03-13
 
 ### Added

data/README.md

@@ -168,6 +168,78 @@ 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.
+
+The recommended approach is to define the interface inline with
+`Class.new`, so it lives next to the assertion and makes the
+expected contract explicit. Duck Typer doesn't encourage
+inheritance by default — your implementations can be completely
+independent:
+
+```ruby
+def test_payment_processors_implement_canonical_interface
+  interface = Class.new do
+    def charge(amount, currency:) = nil
+    def refund(transaction_id) = nil
+  end
+
+  assert_canonical_interface_match interface, [
+    StripeProcessor,
+    PaypalProcessor,
+    BraintreeProcessor
+  ]
+end
+```
+
+If you already have an existing class that defines the contract,
+you can pass it directly:
+
+```ruby
+def test_payment_processors_implement_canonical_interface
+  assert_canonical_interface_match PaymentGateway, [
+    StripeProcessor,
+    PaypalProcessor,
+    BraintreeProcessor
+  ]
+end
+```
+
+You can also pass a `namespace:` instead of a list:
+
+```ruby
+assert_canonical_interface_match PaymentGateway, namespace: Payments
+```
+
+When multiple classes fail, a single assertion reports all of them
+at once:
+
+```
+Expected all objects to implement compatible interfaces defined by
+PaymentGateway, but the following method signatures differ:
+
+StripeProcessor: charge(amount)
+PaymentGateway: charge(amount, currency:)
+
+PaypalProcessor: refund not defined
+PaymentGateway: refund(transaction_id)
+```
+
+The same `type:`, `methods:`, `strict:`, and `name:` options are
+supported:
+
+```ruby
+assert_canonical_interface_match PaymentGateway, [StripeProcessor, PaypalProcessor],
+  methods: %i[charge refund],
+  strict: true,
+  name: "PaymentProcessor"
+```
+
 ### RSpec
 
 Require the RSpec integration in your `spec_helper.rb`:
@@ -228,6 +300,60 @@ 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. The
+recommended approach is to define the interface inline with
+`Class.new` — Duck Typer doesn't encourage inheritance by default,
+and your implementations can be completely independent:
+
+```ruby
+RSpec.describe "payment processors" do
+  it "implement the canonical interface" do
+    interface = Class.new do
+      def charge(amount, currency:) = nil
+      def refund(transaction_id) = nil
+    end
+
+    expect([StripeProcessor, PaypalProcessor, BraintreeProcessor])
+      .to implement_canonical_interface(interface)
+  end
+end
+```
+
+If you already have an existing class that defines the contract,
+you can pass it directly:
+
+```ruby
+RSpec.describe "payment processors" do
+  it "implement the canonical interface" do
+    expect([StripeProcessor, PaypalProcessor, BraintreeProcessor])
+      .to implement_canonical_interface(PaymentGateway)
+  end
+end
+```
+
+You can also pass a namespace:
+
+```ruby
+expect(namespace: Payments).to implement_canonical_interface(PaymentGateway)
+```
+
+The same `type:`, `methods:`, `strict:`, and `name:` options are
+supported:
+
+```ruby
+expect([StripeProcessor, PaypalProcessor])
+  .to implement_canonical_interface(PaymentGateway,
+    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`

data/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

data/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

data/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

data/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 @@ module DuckTyper
         @match.call
       end
 
+      def diff_message
+        @diff_message.call
+      end
+
       def failure_message
         return if match?
 
@@ -25,19 +33,9 @@ module DuckTyper
           Expected #{@left} and #{@right} to implement compatible \
           #{interface_label}, but the following method signatures differ:#{strict_note}
 
-          #{@diff_message.call}
+          #{diff_message}
         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_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

data/lib/duck_typer/minitest.rb

@@ -14,5 +14,13 @@ module DuckTyper
     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

data/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

data/lib/duck_typer/rspec.rb

@@ -21,6 +21,23 @@ end
 
 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")

data/lib/duck_typer/version.rb

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

data/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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: duck_typer
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Thiago A. Silva
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-13 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -28,11 +28,15 @@ files:
 - Rakefile
 - lib/duck_typer.rb
 - lib/duck_typer/bulk_interface_checker.rb
+- lib/duck_typer/canonical_interface_checker.rb
+- lib/duck_typer/canonical_interface_checker/result.rb
 - lib/duck_typer/interface_checker.rb
 - lib/duck_typer/interface_checker/result.rb
+- lib/duck_typer/interface_setup.rb
 - lib/duck_typer/method_inspector.rb
 - lib/duck_typer/minitest.rb
 - lib/duck_typer/params_normalizer.rb
+- lib/duck_typer/result_formatting.rb
 - lib/duck_typer/rspec.rb
 - lib/duck_typer/version.rb
 homepage: https://github.com/thoughtbot/duck_typer