duck_typer 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c357093ac549ba934b47e7923d236062457e52b494588adb8a2fdef41dc3b0a9
-  data.tar.gz: f900f3ad9409f4a8f0707b30aa88fd34ad6f330437e84fd6b3e8560d36edaaef
+  metadata.gz: 8effd9ab824cbdb302917cfce5b6e268d19a25b4320a9e55cfc26b20de81c4e9
+  data.tar.gz: 57f892ab39e37d9a791996814fd250ee1b5235d18158458ce8c3f784b2533e7b
 SHA512:
-  metadata.gz: 86a751c5a4a61ef768bee2aa753c6c16e6e3b9e58860c2ed3ed71c0bf1dd5cf3668c3b4258caa59dc588d5b15964481cf10bdc3913da6654327654a198321de4
-  data.tar.gz: c8a249693663d8a70cfb7af3aa8fa58d422ed19bea2626586ad6c93a6dd8ec9c99c86823cc8084c923e2922c7cd51e73413333844469bfdbe57d19b879fedc10
+  metadata.gz: 3647e54c41e0a190e2c5cb64bf714b7842cf58e9c1eaeacfab08e08c2eff9aa9e14256753306ed84cddc6819ef658381c3ccc5c552843dfebb057fe6c4c12965
+  data.tar.gz: e3f28a6a4423f580541a11fce992fde8a61c75540a8a0cddf4435fa33fa9abe7d13b42cf614540c2b0d91104eb3a7fa0595cb00443d9255dbe92f5fdacce09e2

data/README.md

@@ -54,8 +54,8 @@ When interfaces don't match, DuckTyper reports the differing
 signatures:
 
 ```
-Expected StripeProcessor and BraintreeProcessor to have compatible
-method signatures, but the following signatures do not match:
+Expected StripeProcessor and BraintreeProcessor to implement compatible
+interfaces, but the following method signatures differ:
 
 StripeProcessor: charge(amount, currency:)
 BraintreeProcessor: charge(amount, currency:, description:)
@@ -190,6 +190,33 @@ it_behaves_like "an interface", [StripeProcessor, PaypalProcessor],
   methods: %i[charge refund]
 ```
 
+## 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
+verify the following, which should be covered by your regular
+test suite:
+
+- **Parameter types.** DuckTyper 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.
+- **Return types.** Two methods can have identical signatures
+  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
+  divergence.
+
+Some things are intentionally out of scope:
+
+- **Private methods and `initialize`.** Private methods are not
+  part of a class's public interface — they are implementation
+  details and intentionally excluded. The same applies to
+  `initialize`: how an object is constructed is not an interface
+  concern.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install

data/lib/duck_typer/interface_checker/params_normalizer.rb

@@ -9,22 +9,40 @@ module DuckTyper
     # sequential placeholders when appropriate, focusing the comparison on
     # parameter structure rather than naming.
     class ParamsNormalizer
-      def self.call(params)
-        sequential_name = ("a".."z").to_enum
+      KEYWORD_TYPES = %i[key keyreq].freeze
 
-        params.map do |type, name|
-          name = next_sequential_param(sequential_name) if %i[req opt rest keyrest block].include?(type)
+      class << self
+        def call(params)
+          sequential_name = ("a".."z").to_enum
 
-          [type, name]
+          sort_keyword_params(params).map do |type, name|
+            if %i[req opt rest keyrest block].include?(type)
+              name = next_sequential_param(sequential_name)
+            end
+
+            [type, name]
+          end
         end
-      end
 
-      def self.next_sequential_param(enumerator)
-        enumerator.next
-      rescue StopIteration
-        raise TooManyParametersError, "too many positional parameters, maximum supported is 26"
+        private
+
+        # Keyword argument order is irrelevant to a method's interface —
+        # m(a:, b:) and m(b:, a:) are equivalent. Sort keyword params
+        # alphabetically so comparison is order-independent.
+        def sort_keyword_params(params)
+          keywords, non_keywords = params.partition do |type, _|
+            KEYWORD_TYPES.include?(type)
+          end
+
+          non_keywords + keywords.sort_by { |_, name| name }
+        end
+
+        def next_sequential_param(enumerator)
+          enumerator.next
+        rescue StopIteration
+          raise TooManyParametersError, "too many positional parameters, maximum supported is 26"
+        end
       end
-      private_class_method :next_sequential_param
     end
   end
 end

data/lib/duck_typer/interface_checker/result.rb

@@ -5,11 +5,11 @@ module DuckTyper
     class Result
       attr_reader :left, :right
 
-      def initialize(left:, right:, match:, method_signatures:)
+      def initialize(left:, right:, match:, diff_message:)
         @left = left
         @right = right
         @match = match
-        @method_signatures = method_signatures
+        @diff_message = diff_message
       end
 
       def match?
@@ -17,11 +17,13 @@ module DuckTyper
       end
 
       def failure_message
+        return if match?
+
         <<~MSG
-          Expected #{@left} and #{@right} to have compatible method \
-          signatures, but the following signatures do not match:
+          Expected #{@left} and #{@right} to implement compatible \
+          interfaces, but the following method signatures differ:
 
-          #{@method_signatures.call}
+          #{@diff_message.call}
         MSG
       end
     end

data/lib/duck_typer/interface_checker.rb

@@ -20,47 +20,20 @@ module DuckTyper
     end
 
     def call(left, right)
-      left_params = params_for_comparison(left, ParamsNormalizer)
-      right_params = params_for_comparison(right, ParamsNormalizer)
-      diff = (left_params - right_params) + (right_params - left_params)
+      diff = calculate_diff(left, right)
+      match = -> { diff.empty? }
+      diff_message = -> { diff_message(left, right, diff) }
 
-      match = -> { match?(left_params, right_params) }
-      method_signatures = -> { build_method_signatures(left, right, diff) }
-
-      Result.new(left:, right:, match:, method_signatures:)
+      Result.new(left:, right:, match:, diff_message:)
     end
 
     private
 
-    def match?(left_params, right_params)
-      diff = (left_params - right_params) + (right_params - left_params)
-      diff.empty?
-    end
-
-    def build_method_signatures(left, right, diff)
-      methods = diff.map(&:first).uniq
-      left_params = params_for_comparison(left).to_h.slice(*methods)
-      right_params = params_for_comparison(right).to_h.slice(*methods)
-
-      methods.map do |method_name|
-        <<~DIFF
-          #{join_signature(left, method_name, left_params)}
-          #{join_signature(right, method_name, right_params)}
-        DIFF
-      end.join("\n")
-    end
-
-    def join_signature(object, method_name, params)
-      inspector = @inspectors[object]
-      display_name = inspector.display_name_for(method_name)
-
-      signature = if params[method_name]
-        "#{display_name}(#{params[method_name].join(", ")})"
-      else
-        "#{display_name} not defined"
-      end
+    def calculate_diff(left, right)
+      left_params = params_for_comparison(left, ParamsNormalizer)
+      right_params = params_for_comparison(right, ParamsNormalizer)
 
-      "#{object}: #{signature}"
+      (left_params - right_params) + (right_params - left_params)
     end
 
     def method_params(inspector, method_name, object)
@@ -84,11 +57,38 @@ module DuckTyper
           when :req then name.to_s
           when :opt then "#{name} = :opt"
           when :rest then "*#{name}"
+          when :nokey then "**nil"
           end
         end
 
         [method_name, args]
       end
     end
+
+    def diff_message(left, right, diff)
+      methods = diff.map(&:first).uniq
+      left_params = params_for_comparison(left).to_h.slice(*methods)
+      right_params = params_for_comparison(right).to_h.slice(*methods)
+
+      methods.map do |method_name|
+        <<~DIFF
+          #{join_signature(left, method_name, left_params)}
+          #{join_signature(right, method_name, right_params)}
+        DIFF
+      end.join("\n")
+    end
+
+    def join_signature(object, method_name, params)
+      inspector = @inspectors[object]
+      display_name = inspector.display_name_for(method_name)
+
+      signature = if params[method_name]
+        "#{display_name}(#{params[method_name].join(", ")})"
+      else
+        "#{display_name} not defined"
+      end
+
+      "#{object}: #{signature}"
+    end
   end
 end

data/lib/duck_typer/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: duck_typer
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Thiago A. Silva