why_chain 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57709eb19a0190d1c1cde75dc2cb9b4a657edfd5b4a57cda237a7665b9b027f4
-  data.tar.gz: 76a6b127db4b8acaa90f4e7047e2d64d4d12ff5e8553c3faf48d8b20a6b23141
+  metadata.gz: 2fa488f47789be0531b412a2c9407deda76c1cf5760f1a13510f313d852dbe5a
+  data.tar.gz: d464be25491fb7111b91869d340bb3f8ab8c003878be50d80ff8f2deaf765719
 SHA512:
-  metadata.gz: b1b2fd4c412353c75e0fc7b2645fae16bd76587e91b312785125e48487b5a7304c12ff72f4569955471fb9c657c3db474ac3190163860c1d9d166ad70bbcc78a
-  data.tar.gz: fce81cd5ebf55df0fe92a8ddcb6fb1667f836ca806cb323625447fe77e22c2ab4dd1ce3a260981f1cb7b0787b1a4f74e7b92680f84d42fe41da0800dd891de51
+  metadata.gz: bc4a485648f1dc97335cb4bec48909903156f7c464f3ac637c1945ea6ec33ad0c2ea4b668e15e5054f5651075e5ce51d17b2844c1ad9f0e9df121f03a8faac95
+  data.tar.gz: 9f2b823a8e304dfc90ca9d704e320d9b98b090ac706841c9300cff024805ef568569c861526e94e872f5a89f0c0a131c9548e05ad24be27696f1e04f59f495c1

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-15
+
+- Add style/color options to `WhyChain.explain` with `:teaching` and compact debug format.
+- Introduce compact step labels for dispatch kind: `singleton`, `prepend`, `include`, and `class`.
+- Refactor explainer internals into dedicated formatter and colorizer classes for maintainability.
+
 ## [0.2.1] - 2026-05-11
 
 - Refactor internals by extracting shared method-definition predicate into `MethodDefinition`.

data/Gemfile.lock

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

data/lib/why_chain/dispatch_step.rb

@@ -3,17 +3,19 @@
 module WhyChain
   # Immutable value object for a single dispatch step.
   class DispatchStep
-    attr_reader :owner, :source_location
+    attr_reader :owner, :source_location, :kind
 
-    def initialize(owner:, source_location:)
+    def initialize(owner:, source_location:, kind: nil)
       @owner = owner
       @source_location = source_location
+      @kind = kind
     end
 
     def to_h
       {
         owner: owner,
-        source_location: source_location
+        source_location: source_location,
+        kind: kind
       }
     end
   end

data/lib/why_chain/explainer/colorizer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module WhyChain
+  class Explainer
+    # Handles ANSI color output and source location formatting.
+    class Colorizer
+      ANSI_CODES = {
+        title: "1;36",
+        owner: "32",
+        kind: "35",
+        label: "2;37",
+        location: "2;37",
+        native: "33",
+        arrow: "36"
+      }.freeze
+
+      def initialize(color_mode)
+        @use_color = resolve_color(color_mode)
+      end
+
+      def colorize(text, tone)
+        return text unless @use_color
+
+        code = ANSI_CODES.fetch(tone, "0")
+        "\e[#{code}m#{text}\e[0m"
+      end
+
+      def format_source_location(source_location, color: true)
+        formatted = source_location ? source_location.join(":") : "<native>"
+        return formatted unless color
+
+        source_location ? colorize(formatted, :location) : colorize(formatted, :native)
+      end
+
+      private
+
+      def resolve_color(color)
+        case color
+        when true
+          true
+        when false
+          false
+        when :auto
+          $stdout.tty? && ENV["CI"] != "true"
+        else
+          raise ArgumentError, "Unknown color mode: #{color.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/why_chain/explainer/compact_formatter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module WhyChain
+  class Explainer
+    # Compact debug-friendly explanation format.
+    class CompactFormatter
+      def initialize(method_name, steps, graph, colorizer)
+        @method_name = method_name
+        @steps = steps
+        @graph = graph
+        @colorizer = colorizer
+      end
+
+      def render
+        lines = [@colorizer.colorize("WhyChain :#{@method_name}", :title)]
+
+        @steps.each_with_index do |step, index|
+          lines << step_line(step, index)
+          lines << @colorizer.colorize("   -> super", :arrow) if @graph && index < @steps.length - 1
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def step_line(step, index)
+        kind = @colorizer.colorize("[#{step.kind || :unknown}]", :kind)
+        label = @colorizer.colorize("#{index + 1}) #{kind} #{step.owner}##{@method_name}", :owner)
+        location = @colorizer.format_source_location(step.source_location, color: false)
+        "#{label}  #{@colorizer.colorize(location, :location)}"
+      end
+    end
+  end
+end

data/lib/why_chain/explainer/teaching_formatter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module WhyChain
+  class Explainer
+    # Verbose didactic explanation format.
+    class TeachingFormatter
+      def initialize(method_name, steps, graph, colorizer)
+        @method_name = method_name
+        @steps = steps
+        @graph = graph
+        @colorizer = colorizer
+      end
+
+      def render
+        lines = [@colorizer.colorize("Ruby dispatch explanation for :#{@method_name}", :title), ""]
+
+        @steps.each_with_index do |step, index|
+          lines.concat(step_lines(step, index))
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def step_lines(step, index)
+        lines = [
+          @colorizer.colorize("#{index + 1}. #{step.owner}##{@method_name}", :owner),
+          @colorizer.colorize("   defined at:", :label),
+          "   #{@colorizer.format_source_location(step.source_location)}"
+        ]
+
+        return lines unless @graph && index < @steps.length - 1
+
+        lines + ["", @colorizer.colorize("   calls super ->", :arrow), ""]
+      end
+    end
+  end
+end

data/lib/why_chain/explainer.rb

@@ -1,21 +1,29 @@
 # frozen_string_literal: true
 
+require_relative "explainer/colorizer"
+require_relative "explainer/teaching_formatter"
+require_relative "explainer/compact_formatter"
+
 module WhyChain
   # Formats a human-friendly runtime dispatch explanation.
   class Explainer
-    def initialize(trace, method_name)
+    def initialize(trace, method_name, style: :teaching, color: :auto, graph: true)
       @trace = trace
       @method_name = method_name
+      @style = style
+      @graph = graph
+      @colorizer = Colorizer.new(color)
     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))
+      case @style
+      when :teaching
+        TeachingFormatter.new(@method_name, explanation_steps, @graph, @colorizer).render
+      when :compact
+        CompactFormatter.new(@method_name, explanation_steps, @graph, @colorizer).render
+      else
+        raise ArgumentError, "Unknown style: #{@style.inspect}"
       end
-
-      lines.join("\n")
     end
 
     private
@@ -25,21 +33,5 @@ module WhyChain
 
       [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

@@ -37,14 +37,27 @@ module WhyChain
     end
 
     def steps
+      receiver_class = @object.is_a?(Module) ? @object : @object.class
+      receiver_class_index = lookup_chain.index(receiver_class)
+
       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
+          source_location: mod.instance_method(@method_name).source_location,
+          kind: step_kind_for(mod, receiver_class_index)
         )
       end
     end
+
+    def step_kind_for(mod, receiver_class_index)
+      return :singleton if mod == @object.singleton_class
+      return :class if mod.is_a?(Class)
+
+      return :include unless receiver_class_index
+
+      lookup_chain.index(mod) < receiver_class_index ? :prepend : :include
+    end
   end
 end

data/lib/why_chain/version.rb

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

data/lib/why_chain.rb

@@ -16,7 +16,13 @@ module WhyChain
     Tracer.new(object, method_name).trace
   end
 
-  def self.explain(object, method_name)
-    Explainer.new(trace(object, method_name), method_name).to_s
+  def self.explain(object, method_name, style: :teaching, color: :auto, graph: true)
+    Explainer.new(
+      trace(object, method_name),
+      method_name,
+      style: style,
+      color: color,
+      graph: graph
+    ).to_s
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: why_chain
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - alessio salati
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-15 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.
@@ -30,6 +30,9 @@ files:
 - lib/why_chain/dispatch_step.rb
 - lib/why_chain/dispatch_trace.rb
 - lib/why_chain/explainer.rb
+- lib/why_chain/explainer/colorizer.rb
+- lib/why_chain/explainer/compact_formatter.rb
+- lib/why_chain/explainer/teaching_formatter.rb
 - lib/why_chain/method_definition.rb
 - lib/why_chain/method_locator.rb
 - lib/why_chain/tracer.rb