Add strict mode for interface comparison

Extract KeywordNormalizer and SequentialNormalizer from
ParamsNormalizer. Add DefaultParamsNormalizer (both normalizers)
and StrictParamsNormalizer (keywords only), where strict mode
makes positional argument names significant. ParamsNormalizer
becomes a factory via ParamsNormalizer.for(strict:). Thread
strict: false through InterfaceChecker, BulkInterfaceChecker,
and both test helpers.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: thiagoa

CLAUDE.md

@@ -35,6 +35,7 @@ of these places:
   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

README.md

@@ -138,6 +138,19 @@ which case you can write an assertion for each.
 If you prefer duck typing terminology, `assert_duck_types_match`
 is available as an alias.
 
+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`:
@@ -177,6 +190,14 @@ expect([StripeProcessor, PaypalProcessor])
 If you prefer duck typing terminology, `have_matching_duck_types`
 is available as an alias.
 
+To enforce that positional argument names also match, pass
+`strict: true`:
+
+```ruby
+expect([StripeProcessor, PaypalProcessor])
+  .to have_matching_interfaces(strict: true)
+```
+
 #### Shared example
 
 If you prefer shared examples, register one in `spec_helper.rb`
@@ -205,19 +226,22 @@ RSpec.describe "payment processors" do
 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:
 

lib/duck_typer/bulk_interface_checker.rb

@@ -3,11 +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)

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 @@ def call(left, right)
     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 @@ def method_params(method_name, object)
 
     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

lib/duck_typer/minitest.rb

@@ -4,9 +4,9 @@
 
 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

lib/duck_typer/null_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 { |sorted| sequentialize_params(sorted) }
+  # 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

lib/duck_typer/params_normalizer.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?
@@ -21,15 +21,15 @@
 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?)
 

lib/duck_typer/rspec.rb

@@ -511,4 +511,27 @@ def foo(bananas, coconuts, *others, format:, locale: nil, **opts, &blk) = nil
       "foo(bananas, coconuts, *others, format:, locale: :opt, **opts, &blk)"
     )
   end
+
+  # Strict mode
+
+  def test_strict_mode_positional_arg_names_must_match
+    left = Class.new { def foo(a, b) = nil }
+    right = Class.new { def foo(x, y) = nil }
+
+    refute match?(left, right, strict: true)
+  end
+
+  def test_strict_mode_same_positional_arg_names_match
+    left = Class.new { def foo(a, b) = nil }
+    right = Class.new { def foo(a, b) = nil }
+
+    assert match?(left, right, strict: true)
+  end
+
+  def test_strict_mode_keyword_order_does_not_matter
+    left = Class.new { def foo(a:, b:) = nil }
+    right = Class.new { def foo(b:, a:) = nil }
+
+    assert match?(left, right, strict: true)
+  end
 end