activerecord_callback_lens 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32dbc737ca1362eab8b3a931bd7b2a6ccba9801be70b512d6e47e73d365634c1
-  data.tar.gz: a8500d0321565cacec20b3145d315d804215ef616f8619407f5c0e72c4fb199d
+  metadata.gz: 93034e63e1e99dfe1e6ea64193460d4a206bdf88a01e1c6606385e48228e292c
+  data.tar.gz: d5fae7891b074b7459d7127d9b34befbf8345bd6ee27cef938e0cf0215adddc5
 SHA512:
-  metadata.gz: f7b3ff8e64d67c4f875bc01dc9adbafe80786cabb5db56718805cb2503aa96acb06e38ac4df17041a9171c0a728a8c3acf7c4e3e766f38e66ac716b6bd29576d
-  data.tar.gz: 59f152922559ae9811d339ba8e44bd7de7c3a9198a0c97cb397763e8ccb2bf442e58367d84d0bc61acd8250607d2b5f9fa60f6ca951f5ace8281a425a3fefc21
+  metadata.gz: 9a29d788fe927d7c24b82e70965219b3dfdebdd04a6fa36d1b05d0b968f9265a4b280a0e5e8f67436681cd71a80cbddc0ee993f1fe76befcc3bd698aa7371daf
+  data.tar.gz: 0dfa3cc6f1ebac81b1b8469ce70a1a35482ff948bab5462d3ed777d64843ee948dbeea89fd208d32b8efa24fe54f91a59ff50b7116b1d7fdc25141e9e3b1ba8e

data/README.md

@@ -76,6 +76,29 @@ rake callback_lens:mermaid  MODEL=User EXPAND=true
 Only the exact value `EXPAND=true` (case-insensitive) enables expansion; any
 other value (`EXPAND=1`, `EXPAND=yes`, empty, or absent) leaves it off.
 
+#### Graphviz DOT output
+
+Pass `--graphviz` (CLI) or use `callback_lens:graphviz` (Rake) to output a
+[Graphviz DOT](https://graphviz.org/) diagram to stdout. Pipe it to `dot` to
+generate an image:
+
+```bash
+# CLI — print DOT to stdout
+callback_lens analyze User --graphviz
+
+# CLI — combine with Mermaid output
+callback_lens analyze User --mermaid --graphviz
+
+# CLI — pipe to dot for a PNG
+callback_lens analyze User --graphviz | dot -Tpng -o callbacks.png
+
+# Rake
+rake callback_lens:graphviz MODEL=User
+rake callback_lens:graphviz MODEL=User EXPAND=true
+```
+
+Requires [Graphviz](https://graphviz.org/download/) only when piping to `dot`.
+
 ### Programmatic API
 
 ```ruby
@@ -119,7 +142,7 @@ puts ActiverecordCallbackLens::Renderer::MermaidRenderer.render(graph)
 |---|---|
 | v0.1 | CallbackCollector, Prism condition parser, Mermaid renderer, CLI, Rake task |
 | **v0.2** | MethodResolver — recursive expansion of Symbol conditions (`--expand` / `EXPAND=true`) |
-| v0.3 | Graphviz / DOT renderer |
+| **v0.3** | Graphviz / DOT renderer (`--graphviz` / `callback_lens:graphviz`) |
 | v0.4 | HTML report (callback list, execution flow, embedded diagram) |
 | v1.0 | Runtime tracer via `ActiveSupport::Notifications` |
 | v2.0 | RBS analysis, cross-model dependency graph |

data/lib/activerecord_callback_lens/cli/cli.rb

@@ -7,15 +7,19 @@ require_relative "../parser/condition_parser"
 require_relative "../resolver/method_resolver"
 require_relative "../graph/graph_builder"
 require_relative "../renderer/mermaid_renderer"
+require_relative "../renderer/graphviz_renderer"
 
 module ActiverecordCallbackLens
   module CLI
     # Thor application exposing the callback_lens command-line interface.
     #
-    # For v0.1 it provides a single command, +analyze+, which runs the full
-    # pipeline (collect -> parse -> build graph -> render) and prints a Mermaid
-    # diagram to stdout. An unknown model name is reported with a friendly
-    # message and a non-zero exit status rather than a Ruby backtrace.
+    # It provides a single command, +analyze+, which runs the full pipeline
+    # (collect -> parse -> build graph -> render) and prints the result to
+    # stdout. Output format is selectable per invocation: a Mermaid diagram
+    # (+--mermaid+, on by default) and/or a Graphviz DOT graph (+--graphviz+);
+    # the two flags are independent and may be combined. An unknown model name
+    # is reported with a friendly message and a non-zero exit status rather than
+    # a Ruby backtrace.
     class App < Thor
       # Tells Thor to exit with a non-zero status when a command raises, so the
       # +exit 1+ paths below propagate a failure code to the shell.
@@ -25,8 +29,10 @@ module ActiverecordCallbackLens
         true
       end
 
-      desc "analyze MODEL", "Analyze callbacks for a model class and print a Mermaid diagram"
+      desc "analyze MODEL", "Analyze callbacks for a model class and print a Mermaid and/or Graphviz diagram"
       option :mermaid, type: :boolean, default: true, desc: "Output a Mermaid diagram to stdout"
+      option :graphviz, type: :boolean, default: false,
+                        desc: "Output DOT graph via Graphviz to stdout"
       option :expand, type: :boolean, default: false,
                       desc: "Expand method conditions recursively (up to depth 5)"
       # Runs the analysis pipeline for +model_name+ and prints the result.
@@ -37,6 +43,7 @@ module ActiverecordCallbackLens
         model_class = resolve_model(model_name)
         graph = build_graph(model_class, expand: options[:expand])
         puts Renderer::MermaidRenderer.render(graph) if options[:mermaid]
+        puts Renderer::GraphvizRenderer.render(graph) if options[:graphviz]
       end
 
       private

data/lib/activerecord_callback_lens/renderer/graphviz_renderer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "../graph/nodes"
+
+module ActiverecordCallbackLens
+  module Renderer
+    # Renders a Graph::Graph as a Graphviz DOT language string.
+    #
+    # The output is a `digraph` block with a left-to-right rank direction, one
+    # declaration per node and one arrow per edge:
+    #
+    #   digraph callback_lens {
+    #     rankdir=LR;
+    #     n0 [label="before_save"];
+    #     n1 [label="active?"];
+    #     n1 -> n0;
+    #   }
+    #
+    # Node labels are derived from the node type (see #node_label) using the same
+    # four-case logic as MermaidRenderer. Double quotes in a label are escaped as
+    # `\"` so they cannot break the surrounding DOT label syntax.
+    class GraphvizRenderer
+      # @param graph [Graph::Graph]
+      # @return [String] DOT language string
+      def self.render(graph)
+        new(graph).render
+      end
+
+      # @param graph [Graph::Graph]
+      def initialize(graph)
+        @graph = graph
+      end
+
+      # @return [String] DOT language string
+      def render
+        lines = ["digraph callback_lens {", "  rankdir=LR;"]
+        lines.concat(node_declarations)
+        lines.concat(edge_declarations)
+        lines << "}"
+        lines.join("\n")
+      end
+
+      # Shells out to the `dot` binary and returns the rendered SVG string.
+      # Returns nil when Graphviz is not installed (the `dot` binary is absent
+      # from PATH) rather than raising.
+      #
+      # @return [String, nil]
+      def to_svg
+        IO.popen(["dot", "-Tsvg"], "r+") do |io|
+          io.write(render)
+          io.close_write
+          io.read
+        end
+      rescue Errno::ENOENT
+        nil
+      end
+
+      private
+
+      # @return [Array<String>]
+      def node_declarations
+        @graph.nodes.map { |node| "  #{node.id} [label=\"#{escape(node_label(node))}\"];" }
+      end
+
+      # @return [Array<String>]
+      def edge_declarations
+        @graph.edges.map { |edge| "  #{edge.from_id} -> #{edge.to_id};" }
+      end
+
+      # Derives the human-readable label for a graph node from its type.
+      #
+      # @param node [Graph::CallbackNode, Graph::PredicateNode, Graph::MethodNode, Graph::ConditionNode]
+      # @return [String]
+      def node_label(node)
+        case node
+        when Graph::CallbackNode  then "#{node.definition.phase}_#{node.definition.event}"
+        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
+        else node.id
+        end
+      end
+
+      # Escapes characters that would otherwise break a `label="..."` DOT label.
+      # Double quotes become a backslash-escaped quote so the label stays a
+      # single, valid DOT token. (DOT uses `\"`, unlike Mermaid's `&quot;`.)
+      #
+      # @param label [String]
+      # @return [String]
+      def escape(label)
+        label.to_s.gsub("\"", "\\\"")
+      end
+    end
+  end
+end

data/lib/activerecord_callback_lens/tasks/callback_lens.rake

@@ -17,4 +17,12 @@ namespace :callback_lens do
     expand = CallbackLensRakeHelpers.expand?(ENV.fetch("EXPAND", nil))
     puts CallbackLensRakeHelpers.render_mermaid(model_class, expand: expand)
   end
+
+  desc "Write Graphviz DOT to STDOUT for MODEL " \
+       "(e.g. rake callback_lens:graphviz MODEL=User EXPAND=true)"
+  task graphviz: :environment do
+    model_class = CallbackLensRakeHelpers.resolve_model!(ENV.fetch("MODEL", nil))
+    expand = CallbackLensRakeHelpers.expand?(ENV.fetch("EXPAND", nil))
+    puts CallbackLensRakeHelpers.render_graphviz(model_class, expand: expand)
+  end
 end

data/lib/activerecord_callback_lens/tasks/callback_lens_helpers.rb

@@ -46,6 +46,26 @@ module CallbackLensRakeHelpers
     ActiverecordCallbackLens::Renderer::MermaidRenderer.render(graph)
   end
 
+  # Runs the full pipeline (collect -> parse -> [expand] -> build -> render) for
+  # a model and returns a Graphviz DOT language string. Mirrors +render_mermaid+
+  # but uses the GraphvizRenderer; +expand+ is threaded through identically so
+  # the +EXPAND=true+ rake convention applies to the graphviz task too.
+  #
+  # @param model_class [Class]
+  # @param expand [Boolean]
+  # @return [String] DOT language string
+  def render_graphviz(model_class, expand: false)
+    definitions = ActiverecordCallbackLens::Collector::CallbackCollector.collect(model_class)
+    definitions = definitions.map { |definition| ActiverecordCallbackLens::Parser::ConditionParser.parse(definition) }
+    if expand
+      definitions = definitions.map do |definition|
+        ActiverecordCallbackLens::Resolver::MethodResolver.expand(definition, model_class)
+      end
+    end
+    graph = ActiverecordCallbackLens::Graph::GraphBuilder.build(definitions)
+    ActiverecordCallbackLens::Renderer::GraphvizRenderer.render(graph)
+  end
+
   # Parses the EXPAND environment variable using the strict truthy rule: only the
   # exact string "true" (case-insensitive, surrounding whitespace stripped)
   # enables expansion. Any other value ("1", "yes", "", nil) leaves it off.

data/lib/activerecord_callback_lens/version.rb

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

data/lib/activerecord_callback_lens.rb

@@ -10,6 +10,7 @@ require "activerecord_callback_lens/resolver/method_resolver"
 require "activerecord_callback_lens/graph/nodes"
 require "activerecord_callback_lens/graph/graph_builder"
 require "activerecord_callback_lens/renderer/mermaid_renderer"
+require "activerecord_callback_lens/renderer/graphviz_renderer"
 require "activerecord_callback_lens/cli/cli"
 require "activerecord_callback_lens/railtie" if defined?(Rails::Railtie)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord_callback_lens
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Eraxel.Dev
@@ -81,6 +81,7 @@ files:
 - lib/activerecord_callback_lens/parser/condition_parser.rb
 - lib/activerecord_callback_lens/parser/condition_tree.rb
 - lib/activerecord_callback_lens/railtie.rb
+- lib/activerecord_callback_lens/renderer/graphviz_renderer.rb
 - lib/activerecord_callback_lens/renderer/mermaid_renderer.rb
 - lib/activerecord_callback_lens/resolver/method_resolver.rb
 - lib/activerecord_callback_lens/tasks/callback_lens.rake