why_chain 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bc9a06ec23c45c166f5f1ee5ef100e2a611b4a221800bf6f5b947a026c357e8a
+  data.tar.gz: 542eca20fb80f277e8bdfac100af52f01e781ebe7f4c3a1621f2bf3cadb4e370
+SHA512:
+  metadata.gz: ea34de73851a224c13f468019c23cc9379edc1ac85b75e0975dc3419a67dc3a3a47bca4e19d12591f3e1335a54ad788e0bb0feafcd1838bc4522c965010efbae
+  data.tar.gz: 0cd9ad56a88c26c350c9f9d35918c2eef28223d0a751b31a584292c9051e44cdde069f12eb1307850f064fee0f39b7a0c34b82c37c1d3cc2ab226adf9890c019

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-05-10
+
+- Initial release

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in why_chain.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"

data/Gemfile.lock

@@ -0,0 +1,65 @@
+PATH
+  remote: .
+  specs:
+    why_chain (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    diff-lcs (1.6.2)
+    json (2.19.5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    parallel (1.28.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.86.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-24
+
+DEPENDENCIES
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+  why_chain!
+
+BUNDLED WITH
+   2.4.10

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 alessio salati
+
+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,127 @@
+# WhyChain
+
+A tiny gem to inspect Ruby method dispatch at runtime.
+
+WhyChain helps you see:
+- method lookup chain (`ancestors`)
+- method owner resolution
+- where `super` would resolve next
+
+Built for learning and debugging Ruby internals. Not a production framework.
+
+You can inspect this manually in Ruby console, but WhyChain gives you a consistent, teachable trace in one call.
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "why_chain"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick start
+
+```ruby
+trace = WhyChain.trace(object, :method_name)
+pp trace.to_h
+```
+
+`trace` is a `WhyChain::DispatchTrace` object with readers:
+- `lookup_chain`
+- `owner`
+- `next_super_owner`
+
+As hash:
+
+```ruby
+trace.to_h
+# {
+  lookup_chain: [...],
+  owner: SomeClassOrModule,
+  next_super_owner: AnotherClassOrModule
+# }
+```
+
+## Usage examples
+
+### 1) `prepend` vs `include` in runtime lookup
+
+```ruby
+module P
+  def foo = :p
+end
+
+module I
+  def foo = :i
+end
+
+class A
+  def foo = :a
+end
+
+class B < A
+  include I
+  prepend P
+end
+
+trace = WhyChain.trace(B.new, :foo)
+pp trace.to_h
+# {
+#   lookup_chain: [P, B, I, A, Object, Kernel, BasicObject],
+#   owner: P,
+#   next_super_owner: I
+# }
+```
+
+### 2) Singleton method takes precedence
+
+```ruby
+obj = Object.new
+def obj.single_foo = :singleton
+
+trace = WhyChain.trace(obj, :single_foo)
+pp trace.to_h
+# {
+#   lookup_chain: [#<Class:#<Object:...>>, Object, Kernel, BasicObject],
+#   owner: #<Class:#<Object:...>>,
+#   next_super_owner: nil
+# }
+```
+
+### 3) Missing method fails fast
+
+```ruby
+WhyChain.trace(Object.new, :not_existing_method)
+# raises NameError
+```
+
+Note: some entries in `lookup_chain` can appear as anonymous classes/modules (for example singleton classes). This is expected and reflects Ruby runtime internals.
+
+## Development
+
+Run tests:
+
+```bash
+bundle exec rspec
+```
+
+Run lint:
+
+```bash
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub:
+[https://github.com/alessio-salati/why_chain](https://github.com/alessio-salati/why_chain)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/why_chain/dispatch_trace.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module WhyChain
+  # Immutable value object for traced dispatch data.
+  class DispatchTrace
+    attr_reader :lookup_chain, :owner, :next_super_owner
+
+    def initialize(
+      lookup_chain:,
+      owner:,
+      next_super_owner:
+    )
+      @lookup_chain = lookup_chain
+      @owner = owner
+      @next_super_owner = next_super_owner
+    end
+
+    def to_h
+      {
+        lookup_chain: lookup_chain,
+        owner: owner,
+        next_super_owner: next_super_owner
+      }
+    end
+  end
+end

data/lib/why_chain/method_locator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module WhyChain
+  # Finds where super resolves after a method owner.
+  class MethodLocator
+    def initialize(lookup_chain, owner, method_name)
+      @lookup_chain = lookup_chain
+      @owner = owner
+      @method_name = method_name
+    end
+
+    def next_super_owner
+      owner_index = @lookup_chain.index(@owner)
+
+      return nil unless owner_index
+
+      @lookup_chain[(owner_index + 1)..].find do |mod|
+        defines_instance_method?(mod)
+      end
+    end
+
+    private
+
+    def defines_instance_method?(mod)
+      mod.method_defined?(@method_name, false) ||
+        mod.private_method_defined?(@method_name, false) ||
+        mod.protected_method_defined?(@method_name, false)
+    end
+  end
+end

data/lib/why_chain/tracer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module WhyChain
+  # Builds a dispatch trace for a receiver and method.
+  class Tracer
+    def initialize(object, method_name)
+      @object = object
+      @method_name = method_name
+    end
+
+    def trace
+      DispatchTrace.new(
+        lookup_chain: lookup_chain,
+        owner: owner,
+        next_super_owner: next_super_owner
+      )
+    end
+
+    private
+
+    def lookup_chain
+      @object.singleton_class.ancestors
+    end
+
+    def owner
+      @owner ||= @object.method(@method_name).owner
+    end
+
+    def next_super_owner
+      MethodLocator.new(lookup_chain, owner, @method_name).next_super_owner
+    end
+  end
+end

data/lib/why_chain/version.rb

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

data/lib/why_chain.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "why_chain/version"
+require_relative "why_chain/tracer"
+require_relative "why_chain/dispatch_trace"
+require_relative "why_chain/method_locator"
+
+# Entry point for WhyChain runtime dispatch introspection.
+module WhyChain
+  class Error < StandardError; end
+
+  def self.trace(object, method_name)
+    Tracer.new(object, method_name).trace
+  end
+end

data/sig/why_chain.rbs

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

data/why_chain.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "lib/why_chain/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "why_chain"
+  spec.version = WhyChain::VERSION
+  spec.authors = ["alessio salati"]
+  spec.email = ["alessio.salati@gmail.com"]
+
+  spec.summary = "Inspect Ruby method dispatch at runtime."
+  spec.description = "WhyChain is a tiny educational gem to inspect lookup chain, " \
+                     "method owner, and next super target in Ruby."
+  spec.homepage = "https://github.com/alessio-salati/why_chain"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/alessio-salati/why_chain"
+  spec.metadata["changelog_uri"] = "https://github.com/alessio-salati/why_chain/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor]) ||
+        f.end_with?(".gem")
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: why_chain
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- alessio salati
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-10 00:00:00.000000000 Z
+dependencies: []
+description: WhyChain is a tiny educational gem to inspect lookup chain, method owner,
+  and next super target in Ruby.
+email:
+- alessio.salati@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/why_chain.rb
+- lib/why_chain/dispatch_trace.rb
+- lib/why_chain/method_locator.rb
+- lib/why_chain/tracer.rb
+- lib/why_chain/version.rb
+- sig/why_chain.rbs
+- why_chain.gemspec
+homepage: https://github.com/alessio-salati/why_chain
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/alessio-salati/why_chain
+  source_code_uri: https://github.com/alessio-salati/why_chain
+  changelog_uri: https://github.com/alessio-salati/why_chain/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.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Inspect Ruby method dispatch at runtime.
+test_files: []