why_chain 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc9a06ec23c45c166f5f1ee5ef100e2a611b4a221800bf6f5b947a026c357e8a
-  data.tar.gz: 542eca20fb80f277e8bdfac100af52f01e781ebe7f4c3a1621f2bf3cadb4e370
+  metadata.gz: 57709eb19a0190d1c1cde75dc2cb9b4a657edfd5b4a57cda237a7665b9b027f4
+  data.tar.gz: 76a6b127db4b8acaa90f4e7047e2d64d4d12ff5e8553c3faf48d8b20a6b23141
 SHA512:
-  metadata.gz: ea34de73851a224c13f468019c23cc9379edc1ac85b75e0975dc3419a67dc3a3a47bca4e19d12591f3e1335a54ad788e0bb0feafcd1838bc4522c965010efbae
-  data.tar.gz: 0cd9ad56a88c26c350c9f9d35918c2eef28223d0a751b31a584292c9051e44cdde069f12eb1307850f064fee0f39b7a0c34b82c37c1d3cc2ab226adf9890c019
+  metadata.gz: b1b2fd4c412353c75e0fc7b2645fae16bd76587e91b312785125e48487b5a7304c12ff72f4569955471fb9c657c3db474ac3190163860c1d9d166ad70bbcc78a
+  data.tar.gz: fce81cd5ebf55df0fe92a8ddcb6fb1667f836ca806cb323625447fe77e22c2ab4dd1ce3a260981f1cb7b0787b1a4f74e7b92680f84d42fe41da0800dd891de51

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-11
+
+- Refactor internals by extracting shared method-definition predicate into `MethodDefinition`.
+- Remove duplicated visibility checks from `Tracer` and `MethodLocator` without behavior changes.
+
+## [0.2.0] - 2026-05-11
+
+- Add `WhyChain.explain(object, method_name)` for human-readable dispatch output.
+- Extend `DispatchTrace` with `source_location` and ordered `steps` data.
+- Introduce `DispatchStep` value object for typed dispatch step representation.
+- Add focused specs for explain output and super-path step tracing.
+
 ## [0.1.0] - 2026-05-10
 
 - Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    why_chain (0.1.0)
+    why_chain (0.2.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -30,12 +30,16 @@ bundle install
 ```ruby
 trace = WhyChain.trace(object, :method_name)
 pp trace.to_h
+
+puts WhyChain.explain(object, :method_name)
 ```
 
 `trace` is a `WhyChain::DispatchTrace` object with readers:
 - `lookup_chain`
 - `owner`
 - `next_super_owner`
+- `source_location`
+- `steps` (`WhyChain::DispatchStep` objects)
 
 As hash:
 
@@ -44,10 +48,31 @@ trace.to_h
 # {
   lookup_chain: [...],
   owner: SomeClassOrModule,
-  next_super_owner: AnotherClassOrModule
+  next_super_owner: AnotherClassOrModule,
+  source_location: ["file.rb", 12],
+  steps: [
+    { owner: SomeClassOrModule, source_location: ["file.rb", 12] }
+  ]
 # }
 ```
 
+`WhyChain.explain` returns a human-readable dispatch explanation:
+
+```ruby
+puts WhyChain.explain(B.new, :foo)
+# Ruby dispatch explanation for :foo
+#
+# 1. P#foo
+#    defined at:
+#    /path/to/file.rb:12
+#
+#    calls super ->
+#
+# 2. A#foo
+#    defined at:
+#    /path/to/file.rb:7
+```
+
 ## Usage examples
 
 ### 1) `prepend` vs `include` in runtime lookup

data/lib/why_chain/dispatch_step.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module WhyChain
+  # Immutable value object for a single dispatch step.
+  class DispatchStep
+    attr_reader :owner, :source_location
+
+    def initialize(owner:, source_location:)
+      @owner = owner
+      @source_location = source_location
+    end
+
+    def to_h
+      {
+        owner: owner,
+        source_location: source_location
+      }
+    end
+  end
+end

data/lib/why_chain/dispatch_trace.rb

@@ -3,24 +3,38 @@
 module WhyChain
   # Immutable value object for traced dispatch data.
   class DispatchTrace
-    attr_reader :lookup_chain, :owner, :next_super_owner
+    attr_reader :lookup_chain, :owner, :next_super_owner, :source_location, :steps
 
     def initialize(
       lookup_chain:,
       owner:,
-      next_super_owner:
+      next_super_owner:,
+      source_location: nil,
+      steps: []
     )
       @lookup_chain = lookup_chain
       @owner = owner
       @next_super_owner = next_super_owner
+      @source_location = source_location
+      @steps = steps.map { |step| coerce_step(step) }
     end
 
     def to_h
       {
         lookup_chain: lookup_chain,
         owner: owner,
-        next_super_owner: next_super_owner
+        next_super_owner: next_super_owner,
+        source_location: source_location,
+        steps: steps.map(&:to_h)
       }
     end
+
+    private
+
+    def coerce_step(step)
+      return step if step.is_a?(DispatchStep)
+
+      DispatchStep.new(**step)
+    end
   end
 end

data/lib/why_chain/explainer.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module WhyChain
+  # Formats a human-friendly runtime dispatch explanation.
+  class Explainer
+    def initialize(trace, method_name)
+      @trace = trace
+      @method_name = method_name
+    end
+
+    def to_s
+      lines = ["Ruby dispatch explanation for :#{@method_name}", ""]
+
+      explanation_steps.each_with_index do |step, index|
+        lines.concat(step_lines(step, index))
+      end
+
+      lines.join("\n")
+    end
+
+    private
+
+    def explanation_steps
+      return @trace.steps unless @trace.steps.empty?
+
+      [DispatchStep.new(owner: @trace.owner, source_location: @trace.source_location)]
+    end
+
+    def format_source_location(source_location)
+      source_location ? source_location.join(":") : "<native>"
+    end
+
+    def step_lines(step, index)
+      lines = [
+        "#{index + 1}. #{step.owner}##{@method_name}",
+        "   defined at:",
+        "   #{format_source_location(step.source_location)}"
+      ]
+
+      return lines unless index < explanation_steps.length - 1
+
+      lines + ["", "   calls super ->", ""]
+    end
+  end
+end

data/lib/why_chain/method_definition.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module WhyChain
+  # Shared predicate for direct method definitions in a lookup node.
+  module MethodDefinition
+    module_function
+
+    def defined_directly?(mod, method_name)
+      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/method_locator.rb

@@ -15,16 +15,8 @@ module WhyChain
       return nil unless owner_index
 
       @lookup_chain[(owner_index + 1)..].find do |mod|
-        defines_instance_method?(mod)
+        MethodDefinition.defined_directly?(mod, @method_name)
       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

@@ -12,7 +12,9 @@ module WhyChain
       DispatchTrace.new(
         lookup_chain: lookup_chain,
         owner: owner,
-        next_super_owner: next_super_owner
+        next_super_owner: next_super_owner,
+        source_location: method_object.source_location,
+        steps: steps
       )
     end
 
@@ -23,11 +25,26 @@ module WhyChain
     end
 
     def owner
-      @owner ||= @object.method(@method_name).owner
+      @owner ||= method_object.owner
+    end
+
+    def method_object
+      @method_object ||= @object.method(@method_name)
     end
 
     def next_super_owner
       MethodLocator.new(lookup_chain, owner, @method_name).next_super_owner
     end
+
+    def steps
+      lookup_chain.filter_map do |mod|
+        next unless MethodDefinition.defined_directly?(mod, @method_name)
+
+        DispatchStep.new(
+          owner: mod,
+          source_location: mod.instance_method(@method_name).source_location
+        )
+      end
+    end
   end
 end

data/lib/why_chain/version.rb

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

data/lib/why_chain.rb

@@ -3,7 +3,10 @@
 require_relative "why_chain/version"
 require_relative "why_chain/tracer"
 require_relative "why_chain/dispatch_trace"
+require_relative "why_chain/dispatch_step"
+require_relative "why_chain/method_definition"
 require_relative "why_chain/method_locator"
+require_relative "why_chain/explainer"
 
 # Entry point for WhyChain runtime dispatch introspection.
 module WhyChain
@@ -12,4 +15,8 @@ module WhyChain
   def self.trace(object, method_name)
     Tracer.new(object, method_name).trace
   end
+
+  def self.explain(object, method_name)
+    Explainer.new(trace(object, method_name), method_name).to_s
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: why_chain
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - alessio salati
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-10 00:00:00.000000000 Z
+date: 2026-05-11 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.
@@ -27,7 +27,10 @@ files:
 - README.md
 - Rakefile
 - lib/why_chain.rb
+- lib/why_chain/dispatch_step.rb
 - lib/why_chain/dispatch_trace.rb
+- lib/why_chain/explainer.rb
+- lib/why_chain/method_definition.rb
 - lib/why_chain/method_locator.rb
 - lib/why_chain/tracer.rb
 - lib/why_chain/version.rb