duck_typer 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24207ce1f63f8b0871e06127e2644497f4c60314bbb5fab55f0e8a9f2b30349b
-  data.tar.gz: 8dbebe87508eb66d745af1ce8a0fd6d30865b5929b2de47e092cba9122bcab29
+  metadata.gz: 881833f4db9f3c47049ad45e41c804a74a97db030438f43f933a388dc0f41cba
+  data.tar.gz: ad0b846adb0389c1db0cd49d9d245cb6c006c136e76ea0e7b3980a8d1fb4d3ce
 SHA512:
-  metadata.gz: d97a298dd8aaa903f2a9e2ae451f530a79aa433d9734ae220f89573f88d3ea9288dd1c9feb61c981eda95b272f2fea4b0763f67374bba972cb678ab52692a03b
-  data.tar.gz: 75b66d83757541fdd0cc1ead317aa3e15a7fe9878e1fb57a9b348b3a6c63bce5da2e5fe8091296914ea3bf2e637446af0031806baaed208f5ba01497a479c41c
+  metadata.gz: be49c0476b7afe2c3df16fcede0480f242cfab68c0d1d0a637bba8ac4aa6070bada1c9bbd0350c556193340d62cc2a5665b9949b1c838840127574c2761ff57a
+  data.tar.gz: e9f4543f7117f6e7e3709a153cb316ce90974a984fc302bec71dc84c78fff89a706585cffc9581a24b6f9fa679df3dd0f971a0a82b44c1b78644ff1a8948ba1e

data/.ruby-version

@@ -0,0 +1 @@
+3.1.0

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.1.0

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.4.0] - 2026-03-09
+
+### Added
+- Strict mode (`strict: true`) for interface comparison: positional
+  argument names must match exactly. Available on
+  `assert_interfaces_match`, `have_matching_interfaces`, and the
+  RSpec shared example. Keyword argument names always matter
+  regardless of this setting.
+- `assert_duck_types_match` as an alias for `assert_interfaces_match`
+- `have_matching_duck_types` as an alias for `have_matching_interfaces`
+- `BulkInterfaceChecker` now raises `ArgumentError` when fewer than
+  two classes are given
+
+### Fixed
+- RSpec shared example was broken on Ruby 3.1 due to proc argument
+  destructuring differences between Ruby versions
+
+### Changed
+- `ParamsNormalizer` refactored into a factory (`ParamsNormalizer.for(strict:)`)
+  with extracted modules: `KeywordNormalizer`, `SequentialNormalizer`,
+  `DefaultParamsNormalizer`, `StrictParamsNormalizer`, and
+  `NullParamsNormalizer` — all consolidated in a single file
+- CI now runs against Ruby 3.1 (minimum) and 3.4 (latest)
+
 ## [0.3.2] - 2026-03-07
 
 ### Changed

data/CLAUDE.md

@@ -15,6 +15,29 @@
 - After releasing, delete the generated `.gem` files from the root
   directory — they are not committed and should not linger.
 
+## Ruby version
+
+For now, use the minimum required Ruby version for development —
+this ensures the gem works for everyone who meets that requirement.
+
+When updating the minimum required Ruby version, update it in all
+of these places:
+
+- `.ruby-version`
+- `.tool-versions`
+- `duck_typer.gemspec` (`spec.required_ruby_version`)
+- `.github/workflows/ci.yml` (`ruby-version`)
+
+## Git
+
+- Before staging specific files, always run `git status` to check
+  whether the staging area already has changes that would be
+  unintentionally included in the commit.
+- After staging, double-check the staged changes match what was
+  asked before committing.
+- Always run `bundle exec rake ci` before pushing.
+- Always ask for confirmation before pushing.
+
 ## Commands
 
 - `bundle exec rake test` — run Minitest and RSpec suites

data/CONTRIBUTING.md

@@ -34,11 +34,11 @@ Run the setup script.
 Make sure everything passes:
 
 ```
-bundle exec rake test
-bundle exec standardrb
+bundle exec rake ci
 ```
 
-Make your change, with new passing tests.
+Make your change, with new passing tests. Before pushing, run
+`bundle exec rake ci` again to make sure nothing is broken.
 
 Push to your fork. Write a [good commit message][commit]. Submit a
 pull request.

data/README.md

@@ -2,6 +2,12 @@
 
 [![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">
+</div>
+
+> If it quacks like a duck, it's a duck... or is it?
+
 DuckTyper enforces duck-typed interfaces in Ruby by comparing the
 public method signatures of classes, surfacing mismatches through
 your test suite.
@@ -39,7 +45,7 @@ aligned as the design changes.
 Add to your Gemfile:
 
 ```ruby
-gem "duck_typer"
+gem "duck_typer", group: :test
 ```
 
 Then run:
@@ -103,10 +109,17 @@ classes share compatible interfaces:
 
 ```ruby
 def test_payment_processors_have_compatible_interfaces
-  assert_interfaces_match [StripeProcessor, PaypalProcessor, BraintreeProcessor]
+  assert_interfaces_match [
+    StripeProcessor,
+    PaypalProcessor,
+    BraintreeProcessor
+  ]
 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
 class-level interfaces instead, pass `type: :class_methods`:
 
@@ -125,6 +138,19 @@ assert_interfaces_match [StripeProcessor, PaypalProcessor],
 This is useful if your class implements multiple interfaces, in
 which case you can write an assertion for each.
 
+To enforce that positional argument names also match (strict
+mode), pass `strict: true`:
+
+```ruby
+assert_interfaces_match [StripeProcessor, PaypalProcessor],
+  strict: true
+```
+
+By default, positional argument names are ignored — only their
+count and kind (required, optional, rest) are compared. In strict
+mode, names must match exactly. Keyword argument names always
+matter regardless of this setting.
+
 ### RSpec
 
 Require the RSpec integration in your `spec_helper.rb`:
@@ -141,21 +167,35 @@ share compatible interfaces:
 ```ruby
 RSpec.describe "payment processors" do
   it "have compatible interfaces" do
-    expect([StripeProcessor, PaypalProcessor, BraintreeProcessor]).to have_matching_interfaces
+    expect([StripeProcessor, PaypalProcessor, BraintreeProcessor])
+      .to have_matching_interfaces
   end
 end
 ```
 
+> If you prefer duck typing terminology, `have_matching_duck_types`
+> is available as an alias.
+
 For class-level interfaces, pass `type: :class_methods`:
 
 ```ruby
-expect([StripeProcessor, PaypalProcessor]).to have_matching_interfaces(type: :class_methods)
+expect([StripeProcessor, PaypalProcessor])
+  .to have_matching_interfaces(type: :class_methods)
 ```
 
 To check only a subset of methods, use `methods:`:
 
 ```ruby
-expect([StripeProcessor, PaypalProcessor]).to have_matching_interfaces(methods: %i[charge refund])
+expect([StripeProcessor, PaypalProcessor])
+  .to have_matching_interfaces(methods: %i[charge refund])
+```
+
+To enforce that positional argument names also match, pass
+`strict: true`:
+
+```ruby
+expect([StripeProcessor, PaypalProcessor])
+  .to have_matching_interfaces(strict: true)
 ```
 
 #### Shared example
@@ -178,23 +218,30 @@ Then use it in your specs:
 
 ```ruby
 RSpec.describe "payment processors" do
-  it_behaves_like "an interface", [StripeProcessor, PaypalProcessor, BraintreeProcessor]
+  it_behaves_like "an interface", [
+    StripeProcessor,
+    PaypalProcessor,
+    BraintreeProcessor
+  ]
 end
 ```
 
-The same `type:` and `methods:` options are supported:
+The same `type:`, `methods:`, and `strict:` options are supported:
 
 ```ruby
 it_behaves_like "an interface", [StripeProcessor, PaypalProcessor],
   type: :class_methods,
-  methods: %i[charge refund]
+  methods: %i[charge refund],
+  strict: true
 ```
 
 ## Limitations
 
-DuckTyper checks the **structure** of public method signatures
-— the number of parameters, their kinds (required, optional,
-keyword, rest, block), and keyword argument names. It does not
+By default, DuckTyper 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
+not
 verify the following, which should be covered by your regular
 test suite:
 
@@ -217,6 +264,14 @@ Some things are intentionally out of scope:
   `initialize`: how an object is constructed is not an interface
   concern.
 
+## Stability
+
+DuckTyper 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
+support. It is safe to depend on without worrying about churn.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install

data/lib/duck_typer/bulk_interface_checker.rb

@@ -3,9 +3,11 @@
 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)
+    def initialize(objects, type: :instance_methods, partial_interface_methods: nil, strict: false)
+      raise ArgumentError, "more than one class is required" if objects.size < 2
+
       @objects = objects
-      @checker = InterfaceChecker.new(type:, partial_interface_methods:)
+      @checker = InterfaceChecker.new(type:, partial_interface_methods:, strict:)
     end
 
     def call(&block)

data/lib/duck_typer/interface_checker.rb

@@ -3,14 +3,14 @@
 require_relative "interface_checker/result"
 require_relative "method_inspector"
 require_relative "params_normalizer"
-require_relative "null_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)
+    def initialize(type: :instance_methods, partial_interface_methods: nil, strict: false)
       @type = type
       @partial_interface_methods = partial_interface_methods
+      @strict = strict
       @inspectors = Hash.new { |h, k| h[k] = MethodInspector.for(k, @type) }
     end
 
@@ -25,18 +25,19 @@ module DuckTyper
     private
 
     def calculate_diff(left, right)
-      left_params = params_for_comparison(left, ParamsNormalizer)
-      right_params = params_for_comparison(right, ParamsNormalizer)
+      normalizer = ParamsNormalizer.for(strict: @strict)
+      left_params = params_for_comparison(left, normalizer)
+      right_params = params_for_comparison(right, normalizer)
 
       (left_params - right_params) + (right_params - left_params)
     end
 
-    def params_for_comparison(object, params_processor)
+    def params_for_comparison(object, params_normalizer)
       methods = @partial_interface_methods || @inspectors[object].public_methods
 
       methods.map do |method_name|
         params = method_params(method_name, object)
-        args = params_processor.call(params).map do |type, name|
+        args = params_normalizer.call(params).map do |type, name|
           case type
           when :key then "#{name}: :opt"
           when :keyreq then "#{name}:"
@@ -61,8 +62,8 @@ module DuckTyper
 
     def diff_message(left, right, diff)
       methods = diff.map(&:first).uniq
-      left_params = params_for_comparison(left, NullParamsNormalizer)
-      right_params = params_for_comparison(right, NullParamsNormalizer)
+      left_params = params_for_comparison(left, ParamsNormalizer::NullParamsNormalizer)
+      right_params = params_for_comparison(right, ParamsNormalizer::NullParamsNormalizer)
 
       methods.map do |method_name|
         <<~DIFF

data/lib/duck_typer/minitest.rb

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

data/lib/duck_typer/params_normalizer.rb

@@ -1,46 +1,77 @@
 # frozen_string_literal: true
 
 module DuckTyper
-  # Normalizes method parameters to enable interface comparison.
-  # Keyword argument order is irrelevant — m(a:, b:) and m(b:, a:)
-  # are equivalent — so keywords are sorted alphabetically. Positional
-  # argument names are also replaced with sequential placeholders,
-  # focusing the comparison on parameter structure rather than naming.
-  class ParamsNormalizer # :nodoc:
-    KEYWORD_TYPES = %i[key keyreq].freeze
-    SEQUENTIAL_TYPES = %i[req opt rest keyrest block].freeze
-
-    class << self
-      def call(params)
-        sort_keyword_params(params).then { sequentialize_params(_1) }
+  # Factory for parameter normalization. Use ParamsNormalizer.for(strict:)
+  # to get the right normalizer for the given comparison mode.
+  module ParamsNormalizer # :nodoc:
+    def self.for(strict:)
+      strict ? StrictParamsNormalizer : DefaultParamsNormalizer
+    end
+
+    # Normalizes method parameters for default interface comparison.
+    # Sorts keywords alphabetically and replaces positional argument
+    # names with sequential placeholders.
+    module DefaultParamsNormalizer # :nodoc:
+      def self.call(params)
+        KeywordNormalizer.call(params).then { |p| SequentialNormalizer.call(p) }
       end
+    end
 
-      private
+    # Normalizes method parameters for strict interface comparison,
+    # where positional argument names are significant. Sorts keywords
+    # alphabetically but preserves positional argument names.
+    module StrictParamsNormalizer # :nodoc:
+      def self.call(params)
+        KeywordNormalizer.call(params)
+      end
+    end
 
-      def sort_keyword_params(params)
-        keywords, sequentials = params.partition do |type, _|
-          KEYWORD_TYPES.include?(type)
-        end
+    # Sorts keyword argument parameters alphabetically, making keyword
+    # order irrelevant for interface comparison.
+    module KeywordNormalizer # :nodoc:
+      KEYWORD_TYPES = %i[key keyreq].freeze
+
+      def self.call(params)
+        keywords, sequentials = params.partition { |type, _| KEYWORD_TYPES.include?(type) }
 
         sequentials + keywords.sort_by { |_, name| name }
       end
+    end
+
+    # Replaces positional parameter names with sequential placeholders
+    # (a, b, c, ...), focusing comparison on structure rather than naming.
+    module SequentialNormalizer # :nodoc:
+      SEQUENTIAL_TYPES = %i[req opt rest keyrest block].freeze
+
+      class << self
+        def call(params)
+          sequential_name = ("a".."z").to_enum
 
-      def sequentialize_params(params)
-        sequential_name = ("a".."z").to_enum
+          params.map do |type, name|
+            if SEQUENTIAL_TYPES.include?(type)
+              name = next_sequential_param(sequential_name)
+            end
 
-        params.map do |type, name|
-          if SEQUENTIAL_TYPES.include?(type)
-            name = next_sequential_param(sequential_name)
+            [type, name]
           end
+        end
+
+        private
 
-          [type, name]
+        def next_sequential_param(enumerator)
+          enumerator.next.to_sym
+        rescue StopIteration
+          raise TooManyParametersError, "too many positional parameters, maximum supported is 26"
         end
       end
+    end
 
-      def next_sequential_param(enumerator)
-        enumerator.next.to_sym
-      rescue StopIteration
-        raise TooManyParametersError, "too many positional parameters, maximum supported is 26"
+    # A no-op params processor that returns params unchanged. Used when
+    # interface comparison should preserve original parameter names rather
+    # than normalizing them.
+    module NullParamsNormalizer # :nodoc:
+      def self.call(params)
+        params
       end
     end
   end

data/lib/duck_typer/rspec.rb

@@ -2,10 +2,10 @@
 
 require_relative "../duck_typer"
 
-RSpec::Matchers.define :have_matching_interfaces do |type: :instance_methods, methods: nil|
+RSpec::Matchers.define :have_matching_interfaces do |type: :instance_methods, methods: nil, strict: false|
   match do |objects|
     checker = DuckTyper::BulkInterfaceChecker
-      .new(objects, type:, partial_interface_methods: methods)
+      .new(objects, type:, partial_interface_methods: methods, strict:)
 
     @failures = checker.call.reject(&:match?)
     @failures.empty?
@@ -16,17 +16,20 @@ RSpec::Matchers.define :have_matching_interfaces do |type: :instance_methods, me
   end
 end
 
+RSpec::Matchers.alias_matcher :have_matching_duck_types, :have_matching_interfaces
+
 module DuckTyper
   module RSpec
     def self.define_shared_example(name = "an interface")
-      ::RSpec.shared_examples name do |objects, type: :instance_methods, methods: nil|
+      ::RSpec.shared_examples name do |*objects, type: :instance_methods, methods: nil, strict: false|
+        objects = objects.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)
+            .new(objects, type:, partial_interface_methods: methods, strict:)
 
           failures = checker.call.reject(&:match?)
 

data/lib/duck_typer/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: duck_typer
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Thiago A. Silva
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-07 00:00:00.000000000 Z
+date: 2026-03-09 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -17,7 +17,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".ruby-version"
 - ".standard.yml"
+- ".tool-versions"
 - CHANGELOG.md
 - CLAUDE.md
 - CONTRIBUTING.md
@@ -30,7 +32,6 @@ files:
 - lib/duck_typer/interface_checker/result.rb
 - lib/duck_typer/method_inspector.rb
 - lib/duck_typer/minitest.rb
-- lib/duck_typer/null_params_normalizer.rb
 - lib/duck_typer/params_normalizer.rb
 - lib/duck_typer/rspec.rb
 - lib/duck_typer/version.rb
@@ -57,7 +58,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
+rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
 summary: Enforce duck-typed interfaces in Ruby through your test suite.

data/lib/duck_typer/null_params_normalizer.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module DuckTyper
-  # A no-op params processor that returns params unchanged. Used when
-  # interface comparison should preserve original parameter names rather
-  # than normalizing them.
-  class NullParamsNormalizer # :nodoc:
-    def self.call(params)
-      params
-    end
-  end
-end