duck_typer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 06033bd68c3648b66718874887865c212abf0da7597d8904d511551fc2e651da
+  data.tar.gz: 18a800f2632fe5233946b4220df58a0728a5443d63881fa08d8f1296c4455e48
+SHA512:
+  metadata.gz: 99787de2400a1d21667f64c981e6ad1047c866a00645ec1f2b8534c3d1a692a1204a8e6f6d422c45caca61ef17123aa814a82f046ea5848c62a6b926cf35027c
+  data.tar.gz: 9034b7b8e3df7342e51ec9bbf1cb8cfc58d0f1f0d9d64839c53545585a2d5dfa5af0ee7c6d6cfc6fac613015ce8dfc9dbb9e5579d68ff1b607414fd608a46dbc

data/.standard.yml

@@ -0,0 +1,5 @@
+ignore:
+  - "test/**/*":
+    - Style/Semicolon
+  - "spec/**/*":
+    - Style/Semicolon

data/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+[Bug reports][bugs] and [pull requests][prs] are welcome on GitHub
+at https://github.com/thoughtbot/duck_typer.
+
+[bugs]: https://github.com/thoughtbot/duck_typer/issues/new
+[prs]: https://github.com/thoughtbot/duck_typer/pulls
+
+Please create a [new discussion][discussion] if you want to share
+ideas for new features.
+
+[discussion]: https://github.com/thoughtbot/duck_typer/discussions/new?category=ideas
+
+We love contributions from everyone.
+By participating in this project,
+you agree to abide by the thoughtbot [code of conduct].
+
+[code of conduct]: https://thoughtbot.com/open-source-code-of-conduct
+
+We expect everyone to follow the code of conduct
+anywhere in thoughtbot's project codebases,
+issue trackers, chatrooms, and mailing lists.
+
+## Contributing Code
+
+Fork the repo.
+
+Run the setup script.
+
+```
+./bin/setup
+```
+
+Make sure everything passes:
+
+```
+bundle exec rake test
+bundle exec standardrb
+```
+
+Make your change, with new passing tests.
+
+Push to your fork. Write a [good commit message][commit]. Submit a
+pull request.
+
+[commit]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+
+Others will give constructive feedback.
+This is a time for discussion and improvements,
+and making the necessary changes will be required before we can
+merge the contribution.
+
+## Publishing to RubyGems
+
+When the gem is ready to be shared as a formal release, it can be
+[published][published] to RubyGems.
+
+[published]: https://guides.rubyonrails.org/plugins.html#publishing-your-gem
+
+1. Bump the version number in `DuckTyper::VERSION`
+2. Run `bundle exec rake build`
+3. Run `bundle exec rake install`
+4. Run `bundle exec rake release`

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) thoughtbot, inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# DuckTyper
+
+[![CI](https://github.com/thoughtbot/duck_typer/actions/workflows/ci.yml/badge.svg)](https://github.com/thoughtbot/duck_typer/actions/workflows/ci.yml)
+
+DuckTyper enforces duck-typed interfaces in Ruby by comparing the
+public method signatures of classes, surfacing mismatches through
+your test suite.
+
+## Why DuckTyper?
+
+Ruby is a duck-typed language. When multiple classes play the same
+role, what matters is not what they _are_, but what they _do_ — the
+methods they respond to and the signatures they expose. No base
+class required. No type annotations. No interface declarations.
+
+Most approaches to enforcing this kind of contract pull Ruby away
+from its dynamic nature: abstract base classes that raise
+`NotImplementedError`, type-checking libraries that annotate method
+signatures, or inheritance hierarchies that couple unrelated
+classes. These work, but they're not very Ruby.
+
+DuckTyper takes a different approach. It compares public method
+signatures directly and reports mismatches through your test suite —
+the natural place to enforce design constraints in Ruby. There's
+nothing to annotate and nothing to inherit from. The classes remain
+independent; DuckTyper simply verifies that they're speaking the
+same language. The interface itself needs no declaration — it is
+the intersection of methods your classes define in common, a living
+document that evolves naturally.
+
+It's also useful during active development. When an interface
+evolves, implementations can easily fall out of sync. DuckTyper
+catches that immediately and reports clear, precise error messages
+showing exactly which signatures diverged — keeping your classes
+aligned as the design changes.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "duck_typer"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+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:
+
+StripeProcessor: charge(amount, currency:)
+BraintreeProcessor: charge(amount, currency:, description:)
+
+StripeProcessor: refund(transaction_id)
+BraintreeProcessor: refund(transaction_id, amount)
+```
+
+### Minitest
+
+Require the Minitest integration and include the module in your
+test class:
+
+```ruby
+require "duck_typer/minitest"
+
+class PaymentProcessorTest < Minitest::Test
+  include DuckTyper::Minitest
+end
+```
+
+To make `assert_interface_matches` available across all tests,
+require the integration in `test_helper.rb` and include the module
+in your base test class:
+
+```ruby
+# In test_helper.rb
+require "duck_typer/minitest"
+
+class ActiveSupport::TestCase
+  include DuckTyper::Minitest
+end
+```
+
+If you're not using Rails, include it in `Minitest::Test` directly:
+
+```ruby
+class Minitest::Test
+  include DuckTyper::Minitest
+end
+```
+
+Then use `assert_interface_matches` to assert that a list of
+classes share compatible interfaces:
+
+```ruby
+def test_payment_processors_have_compatible_interfaces
+  assert_interface_matches [StripeProcessor, PaypalProcessor, BraintreeProcessor]
+end
+```
+
+The same `type:` and `methods:` options are supported:
+
+```ruby
+assert_interface_matches [StripeProcessor, PaypalProcessor],
+  type: :class_methods,
+  methods: %i[charge refund]
+```
+
+### RSpec
+
+Require the RSpec integration in your `spec_helper.rb`:
+
+```ruby
+require "duck_typer/rspec"
+```
+
+#### Matcher
+
+Use `have_matching_interfaces` to assert that a list of classes
+share compatible interfaces:
+
+```ruby
+RSpec.describe "payment processors" do
+  it "have compatible interfaces" do
+    expect([StripeProcessor, PaypalProcessor, BraintreeProcessor]).to have_matching_interfaces
+  end
+end
+```
+
+For class-level interfaces, pass `type: :class_methods`:
+
+```ruby
+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])
+```
+
+#### Shared example
+
+If you prefer shared examples, register one in `spec_helper.rb`
+by calling:
+
+```ruby
+DuckTyper::RSpec.define_shared_example
+```
+
+This registers a shared example named `"an interface"`. To avoid
+conflicts with an existing shared example of the same name, pass
+a custom name:
+
+```ruby
+DuckTyper::RSpec.define_shared_example("a compatible interface")
+```
+
+Then use it in your specs:
+
+```ruby
+RSpec.describe "payment processors" do
+  it_behaves_like "an interface", [StripeProcessor, PaypalProcessor, BraintreeProcessor]
+end
+```
+
+The same `type:` and `methods:` options are supported:
+
+```ruby
+it_behaves_like "an interface", [StripeProcessor, PaypalProcessor],
+  type: :class_methods,
+  methods: %i[charge refund]
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install
+dependencies. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run
+`bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the
+version, push git commits and the created tag, and push the `.gem`
+file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+See the [CONTRIBUTING] document.
+Thank you, [contributors]!
+
+[CONTRIBUTING]: CONTRIBUTING.md
+[contributors]: https://github.com/thoughtbot/duck_typer/graphs/contributors
+
+## License
+
+DuckTyper is Copyright (c) thoughtbot, inc.
+It is free software, and may be redistributed
+under the terms specified in the [LICENSE] file.
+
+[LICENSE]: /LICENSE
+
+## About thoughtbot
+
+![thoughtbot](https://thoughtbot.com/thoughtbot-logo-for-readmes.svg)
+
+This repo is maintained and funded by thoughtbot, inc.
+The names and logos for thoughtbot are trademarks of thoughtbot, inc.
+
+We love open source software!
+See [our other projects][community].
+We are [available for hire][hire].
+
+[community]: https://thoughtbot.com/community?utm_source=github
+[hire]: https://thoughtbot.com/hire-us?utm_source=github

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rspec/core/rake_task"
+
+Rake::TestTask.new(:minitest) do |t|
+  t.pattern = "test/**/*_test.rb"
+end
+
+RSpec::Core::RakeTask.new(:rspec)
+
+task test: %i[minitest rspec]
+
+task default: %i[]

data/lib/duck_typer/bulk_interface_checker.rb

@@ -0,0 +1,17 @@
+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)
+      @objects = objects
+      @checker = InterfaceChecker.new(type:, partial_interface_methods:)
+    end
+
+    def call(&block)
+      @objects.each_cons(2).map do |left, right|
+        result = @checker.call(left, right)
+        block&.call(left, right, result)
+        result
+      end
+    end
+  end
+end

data/lib/duck_typer/interface_checker/method_inspector.rb

@@ -0,0 +1,49 @@
+module DuckTyper
+  class InterfaceChecker
+    class MethodInspector
+      def self.for(object, type)
+        if type == :class_methods
+          ClassMethodInspector
+        else
+          InstanceMethodInspector
+        end.new(object)
+      end
+    end
+
+    class ClassMethodInspector
+      def initialize(object)
+        @object = object
+      end
+
+      def public_methods
+        @object.public_methods - Object.methods
+      end
+
+      def parameters_for(method_name)
+        @object.method(method_name).parameters
+      end
+
+      def display_name_for(method_name)
+        "self.#{method_name}"
+      end
+    end
+
+    class InstanceMethodInspector
+      def initialize(object)
+        @object = object
+      end
+
+      def public_methods
+        @object.public_instance_methods - Object.methods
+      end
+
+      def parameters_for(method_name)
+        @object.instance_method(method_name).parameters
+      end
+
+      def display_name_for(method_name)
+        method_name
+      end
+    end
+  end
+end

data/lib/duck_typer/interface_checker/params_normalizer.rb

@@ -0,0 +1,28 @@
+module DuckTyper
+  class InterfaceChecker
+    # Normalizes method parameters to enable interface comparison. For
+    # example, two methods may use different names for positional
+    # arguments, but if the parameter types and order match, they should
+    # be considered equivalent. This class replaces argument names with
+    # 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
+
+        params.map do |type, name|
+          name = next_sequential_param(sequential_name) if %i[req opt rest keyrest block].include?(type)
+
+          [type, name]
+        end
+      end
+
+      def self.next_sequential_param(enumerator)
+        enumerator.next
+      rescue StopIteration
+        raise TooManyParametersError, "too many positional parameters, maximum supported is 26"
+      end
+      private_class_method :next_sequential_param
+    end
+  end
+end

data/lib/duck_typer/interface_checker/result.rb

@@ -0,0 +1,33 @@
+module DuckTyper
+  class InterfaceChecker
+    class Result
+      attr_reader :left, :right
+
+      def initialize(left:, right:, match:, method_signatures:)
+        @left = left
+        @right = right
+        @match = match
+        @method_signatures = method_signatures
+      end
+
+      def match?
+        @match.call
+      end
+
+      def failure_message
+        <<~MSG
+          Expected #{@left} and #{@right} to have compatible method \
+          signatures, but the following signatures do not match:
+
+          #{method_signatures}
+        MSG
+      end
+
+      private
+
+      def method_signatures
+        @method_signatures.call
+      end
+    end
+  end
+end

data/lib/duck_typer/interface_checker.rb

@@ -0,0 +1,92 @@
+require_relative "interface_checker/result"
+require_relative "interface_checker/method_inspector"
+require_relative "interface_checker/params_normalizer"
+
+module DuckTyper
+  # Compares the public method signatures of two classes and reports mismatches.
+  class InterfaceChecker
+    TYPES = %i[instance_methods class_methods].freeze
+
+    def initialize(type: :instance_methods, partial_interface_methods: nil)
+      unless TYPES.include?(type)
+        raise ArgumentError, "Invalid type #{type.inspect}, must be one of #{TYPES}"
+      end
+
+      @type = type
+      @partial_interface_methods = partial_interface_methods
+      @inspectors = Hash.new { |h, k| h[k] = MethodInspector.for(k, @type) }
+    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)
+
+      match = -> { match?(left_params, right_params) }
+      method_signatures = -> { build_method_signatures(left, right, diff) }
+
+      Result.new(left:, right:, match:, method_signatures:)
+    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
+
+      "#{object}: #{signature}"
+    end
+
+    def method_params(inspector, method_name, object)
+      inspector.parameters_for(method_name)
+    rescue NameError
+      raise MethodNotFoundError, "undefined method `#{method_name}' for #{object}"
+    end
+
+    def params_for_comparison(object, params_processor = -> { _1 })
+      inspector = @inspectors[object]
+      methods = @partial_interface_methods || inspector.public_methods
+
+      methods.map do |method_name|
+        params = method_params(inspector, method_name, object)
+        args = params_processor.call(params).map do |type, name|
+          case type
+          when :key then "#{name}: :opt"
+          when :keyreq then "#{name}:"
+          when :keyrest then "**#{name}"
+          when :block then "&#{name}"
+          when :req then name.to_s
+          when :opt then "#{name} = :opt"
+          when :rest then "*#{name}"
+          end
+        end
+
+        [method_name, args]
+      end
+    end
+  end
+end

data/lib/duck_typer/minitest.rb

@@ -0,0 +1,14 @@
+require_relative "../duck_typer"
+
+module DuckTyper
+  module Minitest
+    def assert_interface_matches(objects, type: :instance_methods, methods: nil)
+      checker = BulkInterfaceChecker
+        .new(objects, type:, partial_interface_methods: methods)
+
+      checker.call do |_, _, result|
+        assert result.match?, result.failure_message
+      end
+    end
+  end
+end

data/lib/duck_typer/rspec.rb

@@ -0,0 +1,28 @@
+require_relative "../duck_typer"
+
+RSpec::Matchers.define :have_matching_interfaces do |type: :instance_methods, methods: nil|
+  match do |objects|
+    checker = DuckTyper::BulkInterfaceChecker
+      .new(objects, type:, partial_interface_methods: methods)
+
+    @failures = checker.call.reject(&:match?)
+    @failures.empty?
+  end
+
+  failure_message do
+    @failures.map(&:failure_message).join("\n")
+  end
+end
+
+module DuckTyper
+  module RSpec
+    def self.define_shared_example(name = "an interface")
+      ::RSpec.shared_examples name do |objects, type: :instance_methods, methods: nil|
+        it "has compatible interfaces" do
+          failures = DuckTyper::BulkInterfaceChecker.new(objects, type:, partial_interface_methods: methods).call.reject(&:match?)
+          raise ::RSpec::Expectations::ExpectationNotMetError, failures.map(&:failure_message).join("\n") if failures.any?
+        end
+      end
+    end
+  end
+end

data/lib/duck_typer/version.rb

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

data/lib/duck_typer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "duck_typer/version"
+require_relative "duck_typer/interface_checker"
+require_relative "duck_typer/bulk_interface_checker"
+
+# DuckTyper enforces duck-typed interfaces in Ruby by comparing the public
+# method signatures of classes, surfacing mismatches through your test suite.
+module DuckTyper
+  class MethodNotFoundError < StandardError; end
+  class TooManyParametersError < StandardError; end
+end

data/sig/duck_typer.rbs

@@ -0,0 +1,4 @@
+module DuckTyper
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: duck_typer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thiago A. Silva
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-07 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- thiagoaraujos@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".standard.yml"
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/duck_typer.rb
+- lib/duck_typer/bulk_interface_checker.rb
+- lib/duck_typer/interface_checker.rb
+- lib/duck_typer/interface_checker/method_inspector.rb
+- lib/duck_typer/interface_checker/params_normalizer.rb
+- lib/duck_typer/interface_checker/result.rb
+- lib/duck_typer/minitest.rb
+- lib/duck_typer/rspec.rb
+- lib/duck_typer/version.rb
+- sig/duck_typer.rbs
+homepage: https://github.com/thoughtbot/duck_typer
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/thoughtbot/duck_typer
+  source_code_uri: https://github.com/thoughtbot/duck_typer
+  changelog_uri: https://github.com/thoughtbot/duck_typer/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Enforce duck-typed interfaces in Ruby through your test suite.
+test_files: []