activerecord_callback_lens 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d449ee130b618f98ee114f459fbb178a5b7cded7465853e2b1eb5c2c39893061
-  data.tar.gz: 0b64c3820a229bb381b597faecc9936e29d3a053cb174beccbe557d1eb86f368
+  metadata.gz: 4135903a860b81ecc58cade60bf40079716b57147a5ed5103385efb8888deabc
+  data.tar.gz: 76ef506c8897d02301f1fb6aa629c4364c5041f452e75f0547cb9085d3bc8883
 SHA512:
-  metadata.gz: eb0f92c15fb5e7c8ed1bcdd1a1bb25f2a70e2c9b7b898d88b6614369ea24a7aeb2c8627e37b192a404259b9fa3143582d27e8a45671fd8ce52b0b8e052db1e01
-  data.tar.gz: 1f01ab230f4ac8b50a604df94a33eb95c63e0f8bfdc1eaba1a4997bf069e0e4272365b556a5e5fffa6af687d1017d5b10bdd9937a8944e2d532005c37b7a0804
+  metadata.gz: bbd09f9d42c5a00a442cb3eb798eec0e07ecd6e68402f167310f171d1b1551a29704bc365fedc9d5f96598284c2703ae42c6a72151446d6342a6d62afc42dc71
+  data.tar.gz: a21cac7359e0e8939b642bca3f45630bbd66b586796051916902255b976f90336316268f231ec6f71560f3f6241b4a25078d8d7e50a80c3a320eb69c7d52bfaa

data/README.md

@@ -148,6 +148,25 @@ graph = ActiverecordCallbackLens::Graph::GraphBuilder.build(definitions)
 puts ActiverecordCallbackLens::Renderer::MermaidRenderer.render(graph)
 ```
 
+## Example app
+
+A runnable example Rails app lives in [`examples/blog_app/`](examples/blog_app/).
+It defines a small blog domain (`Article`, `User`, `Comment`) with callbacks
+covering every lifecycle event and condition style, and points its `Gemfile` at
+this repo via `path: "../.."` so it always exercises the current gem code:
+
+```bash
+cd examples/blog_app
+bundle install
+bin/rails callback_lens:analyze MODEL=Article            # Mermaid diagram
+bin/rails callback_lens:analyze MODEL=Article EXPAND=true # expanded predicates
+bin/rails callback_lens:html MODEL=Article OUT=reports/article.html
+bin/callback_lens_demo                                    # programmatic API demo
+```
+
+See [`examples/blog_app/README.md`](examples/blog_app/README.md) for the full
+command matrix and expected output.
+
 ## How it works
 
 | Layer | Class | Responsibility |

data/lib/activerecord_callback_lens/cli/cli.rb

@@ -48,7 +48,7 @@ module ActiverecordCallbackLens
       def analyze(model_name)
         model_class = resolve_model(model_name)
         definitions, graph = build_pipeline(model_class, expand: options[:expand])
-        render_outputs(graph, definitions)
+        render_outputs(graph, definitions, expand: options[:expand])
       end
 
       private
@@ -58,11 +58,12 @@ module ActiverecordCallbackLens
       #
       # @param graph [Graph::Graph]
       # @param definitions [Array<Collector::CallbackDefinition>]
+      # @param expand [Boolean]
       # @return [void]
-      def render_outputs(graph, definitions)
-        puts Renderer::MermaidRenderer.render(graph) if options[:mermaid]
-        puts Renderer::GraphvizRenderer.render(graph) if options[:graphviz]
-        write_html(graph, definitions, options[:html]) if options[:html]
+      def render_outputs(graph, definitions, expand:)
+        puts Renderer::MermaidRenderer.render(graph, expand: expand) if options[:mermaid]
+        puts Renderer::GraphvizRenderer.render(graph, expand: expand) if options[:graphviz]
+        write_html(graph, definitions, options[:html], expand: expand) if options[:html]
       end
 
       # Resolves a model class by name, printing a friendly error and exiting
@@ -105,9 +106,10 @@ module ActiverecordCallbackLens
       # @param graph [Graph::Graph]
       # @param definitions [Array<Collector::CallbackDefinition>]
       # @param path [String]
+      # @param expand [Boolean]
       # @return [void]
-      def write_html(graph, definitions, path)
-        html = Renderer::HtmlRenderer.render(graph, definitions: definitions)
+      def write_html(graph, definitions, path, expand: false)
+        html = Renderer::HtmlRenderer.render(graph, definitions: definitions, expand: expand)
         File.write(path, html)
         puts "HTML report written to #{path}"
       end

data/lib/activerecord_callback_lens/collector/callback_definition.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "prism"
+
 module ActiverecordCallbackLens
   module Collector
     # Represents a single callback registered on an ActiveRecord model.
@@ -17,5 +19,111 @@ module ActiverecordCallbackLens
       :condition_tree,  # ConditionTree::Node | nil — parsed logical tree
       :source_location  # [String, Integer] | nil — file and line of the filter
     )
+
+    # Reopened to add the shared formatting behaviour every renderer needs: the
+    # callback's lifecycle name and a human-readable label for its filter. Keeping
+    # this on the domain object (rather than duplicating it across the Mermaid,
+    # Graphviz, and HTML renderers) guarantees identical output everywhere and
+    # isolates the one I/O-heavy path (proc source slicing) for focused testing.
+    class CallbackDefinition
+      # The callback's lifecycle name, e.g. "before_save". Centralises the string
+      # the renderers previously each rebuilt from phase + event.
+      #
+      # @return [String]
+      def callback_name
+        "#{phase}_#{event}"
+      end
+
+      # A human-readable label for the filter (Symbol, String, or Proc).
+      #
+      # Symbol/String filters render as their own text. A Proc renders as
+      # "(proc)" by default; when +expand+ is true it renders its actual source
+      # snippet (e.g. "-> { compute_reading_time }"), falling back to "(proc)" on
+      # any I/O or parse error.
+      #
+      # @param expand [Boolean]
+      # @return [String]
+      def filter_label(expand: false)
+        case filter
+        when Proc
+          return "(proc)" unless expand
+
+          proc_source || "(proc)"
+        else
+          filter.to_s
+        end
+      end
+
+      private
+
+      # Extracts the Proc's raw source snippet by reading its source file with
+      # Prism and slicing the enclosing lambda/block node, reusing the same
+      # technique as ConditionParser#parse_proc. Returns nil on any error
+      # (nil source_location, missing/unreadable file, parse failure, slice
+      # error), so #filter_label falls back to "(proc)".
+      #
+      # @return [String, nil] the single-line source snippet, or nil on any error
+      def proc_source
+        file, line = filter.source_location
+        return nil unless file && File.exist?(file)
+
+        result = Prism.parse_file(file)
+        return nil unless result.success?
+
+        locator = ProcNodeLocator.new(target_line: line)
+        locator.visit(result.value)
+        node = locator.node
+        return nil if node.nil?
+
+        node.location.slice.strip.gsub(/\s*\n\s*/, " ")
+      rescue StandardError
+        nil
+      end
+
+      # A Prism visitor that captures the innermost LambdaNode or BlockNode whose
+      # source range encloses a target line — the *whole* node (so its
+      # location.slice yields the full "-> { ... }" / "{ ... }" text), unlike
+      # ConditionParser::LambdaLocator which captures only the node body.
+      class ProcNodeLocator < Prism::Visitor
+        # @return [Prism::Node, nil] the innermost matching lambda/block node
+        attr_reader :node
+
+        # @param target_line [Integer] the line the proc's source_location reports
+        def initialize(target_line:)
+          @target_line = target_line
+          @node = nil
+          super()
+        end
+
+        # @param lambda_node [Prism::LambdaNode]
+        # @return [void]
+        def visit_lambda_node(lambda_node)
+          capture(lambda_node)
+          super
+        end
+
+        # @param block_node [Prism::BlockNode]
+        # @return [void]
+        def visit_block_node(block_node)
+          capture(block_node)
+          super
+        end
+
+        private
+
+        # Records the candidate when it encloses the target line. Because the
+        # visitor descends depth-first, the last (innermost) enclosing match
+        # wins, isolating nested blocks correctly.
+        #
+        # @param candidate [Prism::LambdaNode, Prism::BlockNode]
+        # @return [void]
+        def capture(candidate)
+          location = candidate.location
+          return unless @target_line.between?(location.start_line, location.end_line)
+
+          @node = candidate
+        end
+      end
+    end
   end
 end

data/lib/activerecord_callback_lens/renderer/graphviz_renderer.rb

@@ -21,14 +21,17 @@ module ActiverecordCallbackLens
     # `\"` so they cannot break the surrounding DOT label syntax.
     class GraphvizRenderer
       # @param graph [Graph::Graph]
+      # @param expand [Boolean] expand proc filter labels to their source snippet
       # @return [String] DOT language string
-      def self.render(graph)
-        new(graph).render
+      def self.render(graph, expand: false)
+        new(graph, expand: expand).render
       end
 
       # @param graph [Graph::Graph]
-      def initialize(graph)
+      # @param expand [Boolean]
+      def initialize(graph, expand: false)
         @graph = graph
+        @expand = expand
       end
 
       # @return [String] DOT language string
@@ -73,7 +76,8 @@ module ActiverecordCallbackLens
       # @return [String]
       def node_label(node)
         case node
-        when Graph::CallbackNode  then "#{node.definition.phase}_#{node.definition.event}"
+        when Graph::CallbackNode
+          "#{node.definition.callback_name}: #{node.definition.filter_label(expand: @expand)}"
         when Graph::PredicateNode then node.predicate_name
         when Graph::MethodNode    then node.method_name
         when Graph::ConditionNode then node.tree_node.class.name.split("::").last

data/lib/activerecord_callback_lens/renderer/html_renderer.rb

@@ -97,16 +97,19 @@ module ActiverecordCallbackLens
 
       # @param graph [Graph::Graph] the assembled dependency graph
       # @param definitions [Array<Collector::CallbackDefinition>] parsed definitions
+      # @param expand [Boolean] expand proc filter labels to their source snippet
       # @return [String] a complete HTML document
-      def self.render(graph, definitions:)
-        new(graph, definitions).render
+      def self.render(graph, definitions:, expand: false)
+        new(graph, definitions, expand: expand).render
       end
 
       # @param graph [Graph::Graph]
       # @param definitions [Array<Collector::CallbackDefinition>]
-      def initialize(graph, definitions)
+      # @param expand [Boolean]
+      def initialize(graph, definitions, expand: false)
         @graph = graph
         @definitions = definitions
+        @expand = expand
       end
 
       # Assembles the full HTML document.
@@ -138,7 +141,7 @@ module ActiverecordCallbackLens
           "<tr>" \
             "<td>#{escape(definition.phase)}</td>" \
             "<td>#{escape(definition.event)}</td>" \
-            "<td>#{escape(filter_label(definition))}</td>" \
+            "<td>#{escape(definition.filter_label(expand: @expand))}</td>" \
             "<td>#{escape(conditions_label(definition))}</td>" \
             "</tr>"
         end
@@ -156,7 +159,9 @@ module ActiverecordCallbackLens
       # Section 2: callbacks in canonical create-path execution order.
       def execution_flow
         ordered = ExecutionOrderAnalyzer.sort(@definitions, operation: :create)
-        items = ordered.map { |d| "<li>#{escape("#{d.phase}_#{d.event}")}</li>" }
+        items = ordered.map do |d|
+          "<li>#{escape("#{d.callback_name}: #{d.filter_label(expand: @expand)}")}</li>"
+        end
         <<~HTML.chomp
           <h2>Execution Flow</h2>
           <ol>
@@ -171,7 +176,7 @@ module ActiverecordCallbackLens
         trees = @definitions.filter_map do |definition|
           next if definition.condition_tree.nil?
 
-          "<li>#{escape("#{definition.phase}_#{definition.event}")}" \
+          "<li>#{escape("#{definition.callback_name}: #{definition.filter_label(expand: @expand)}")}" \
             "#{ConditionTreeHtml.new(definition.condition_tree).to_html}</li>"
         end
         <<~HTML.chomp
@@ -186,14 +191,14 @@ module ActiverecordCallbackLens
       def mermaid_section
         <<~HTML.chomp
           <h2>Mermaid Diagram</h2>
-          <pre class="mermaid">#{escape(MermaidRenderer.render(@graph))}</pre>
+          <pre class="mermaid">#{escape(MermaidRenderer.render(@graph, expand: @expand))}</pre>
         HTML
       end
 
       # Section 5: the inline Graphviz SVG, or an empty string when +dot+ is not
       # installed (GraphvizRenderer#to_svg returns nil).
       def svg_section
-        svg = GraphvizRenderer.new(@graph).to_svg
+        svg = GraphvizRenderer.new(@graph, expand: @expand).to_svg
         return "" if svg.nil?
 
         <<~HTML.chomp
@@ -202,12 +207,6 @@ module ActiverecordCallbackLens
         HTML
       end
 
-      # A human-readable label for a definition's filter (Symbol, String, or Proc).
-      def filter_label(definition)
-        filter = definition.filter
-        filter.is_a?(Proc) ? "(proc)" : filter.to_s
-      end
-
       # A comma-joined label of a definition's condition leaf names, or "".
       def conditions_label(definition)
         tree = definition.condition_tree

data/lib/activerecord_callback_lens/renderer/mermaid_renderer.rb

@@ -19,14 +19,17 @@ module ActiverecordCallbackLens
     # surrounding Mermaid label syntax.
     class MermaidRenderer
       # @param graph [Graph::Graph]
+      # @param expand [Boolean] expand proc filter labels to their source snippet
       # @return [String]
-      def self.render(graph)
-        new(graph).render
+      def self.render(graph, expand: false)
+        new(graph, expand: expand).render
       end
 
       # @param graph [Graph::Graph]
-      def initialize(graph)
+      # @param expand [Boolean]
+      def initialize(graph, expand: false)
         @graph = graph
+        @expand = expand
       end
 
       # @return [String]
@@ -55,7 +58,8 @@ module ActiverecordCallbackLens
       # @return [String]
       def node_label(node)
         case node
-        when Graph::CallbackNode  then "#{node.definition.phase}_#{node.definition.event}"
+        when Graph::CallbackNode
+          "#{node.definition.callback_name}: #{node.definition.filter_label(expand: @expand)}"
         when Graph::PredicateNode then node.predicate_name
         when Graph::MethodNode    then node.method_name
         when Graph::ConditionNode then node.tree_node.class.name.split("::").last

data/lib/activerecord_callback_lens/tasks/callback_lens_helpers.rb

@@ -43,7 +43,7 @@ module CallbackLensRakeHelpers
       end
     end
     graph = ActiverecordCallbackLens::Graph::GraphBuilder.build(definitions)
-    ActiverecordCallbackLens::Renderer::MermaidRenderer.render(graph)
+    ActiverecordCallbackLens::Renderer::MermaidRenderer.render(graph, expand: expand)
   end
 
   # Runs the full pipeline (collect -> parse -> [expand] -> build -> render) for
@@ -63,7 +63,7 @@ module CallbackLensRakeHelpers
       end
     end
     graph = ActiverecordCallbackLens::Graph::GraphBuilder.build(definitions)
-    ActiverecordCallbackLens::Renderer::GraphvizRenderer.render(graph)
+    ActiverecordCallbackLens::Renderer::GraphvizRenderer.render(graph, expand: expand)
   end
 
   # Runs the full pipeline (collect -> parse -> [expand] -> build) for a model and
@@ -85,7 +85,7 @@ module CallbackLensRakeHelpers
       end
     end
     graph = ActiverecordCallbackLens::Graph::GraphBuilder.build(definitions)
-    ActiverecordCallbackLens::Renderer::HtmlRenderer.render(graph, definitions: definitions)
+    ActiverecordCallbackLens::Renderer::HtmlRenderer.render(graph, definitions: definitions, expand: expand)
   end
 
   # Parses the EXPAND environment variable using the strict truthy rule: only the

data/lib/activerecord_callback_lens/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiverecordCallbackLens
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord_callback_lens
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Eraxel.Dev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord