why_chain 0.1.0 → 0.2.0

checksums.yaml

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

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [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.0)
 
 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/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,32 @@ 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 defines_instance_method?(mod)
+
+        DispatchStep.new(
+          owner: mod,
+          source_location: mod.instance_method(@method_name).source_location
+        )
+      end
+    end
+
+    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/version.rb

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

data/lib/why_chain.rb

@@ -3,7 +3,9 @@
 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_locator"
+require_relative "why_chain/explainer"
 
 # Entry point for WhyChain runtime dispatch introspection.
 module WhyChain
@@ -12,4 +14,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.0
 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,9 @@ 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_locator.rb
 - lib/why_chain/tracer.rb
 - lib/why_chain/version.rb