activerecord_callback_lens 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32dbc737ca1362eab8b3a931bd7b2a6ccba9801be70b512d6e47e73d365634c1
-  data.tar.gz: a8500d0321565cacec20b3145d315d804215ef616f8619407f5c0e72c4fb199d
+  metadata.gz: d449ee130b618f98ee114f459fbb178a5b7cded7465853e2b1eb5c2c39893061
+  data.tar.gz: 0b64c3820a229bb381b597faecc9936e29d3a053cb174beccbe557d1eb86f368
 SHA512:
-  metadata.gz: f7b3ff8e64d67c4f875bc01dc9adbafe80786cabb5db56718805cb2503aa96acb06e38ac4df17041a9171c0a728a8c3acf7c4e3e766f38e66ac716b6bd29576d
-  data.tar.gz: 59f152922559ae9811d339ba8e44bd7de7c3a9198a0c97cb397763e8ccb2bf442e58367d84d0bc61acd8250607d2b5f9fa60f6ca951f5ace8281a425a3fefc21
+  metadata.gz: eb0f92c15fb5e7c8ed1bcdd1a1bb25f2a70e2c9b7b898d88b6614369ea24a7aeb2c8627e37b192a404259b9fa3143582d27e8a45671fd8ce52b0b8e052db1e01
+  data.tar.gz: 1f01ab230f4ac8b50a604df94a33eb95c63e0f8bfdc1eaba1a4997bf069e0e4272365b556a5e5fffa6af687d1017d5b10bdd9937a8944e2d532005c37b7a0804

data/README.md

@@ -2,7 +2,7 @@
 
 **X-ray your ActiveRecord callbacks.**
 
-Callbacks are easy to add and hard to reason about. `activerecord_callback_lens` statically analyzes the callbacks registered on your ActiveRecord models, parses their `if`/`unless` conditions into logical trees, and renders the result as a Mermaid diagram so you can see exactly what runs and why.
+Callbacks are easy to add and hard to reason about. `activerecord_callback_lens` statically analyzes the callbacks registered on your ActiveRecord models, parses their `if`/`unless` conditions into logical trees, and renders the result as a Mermaid diagram, Graphviz DOT graph, or a self-contained HTML report so you can see exactly what runs and why.
 
 ## Requirements
 
@@ -76,6 +76,60 @@ 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`.
+
+#### HTML report
+
+Pass `--html FILE` (CLI) or use `callback_lens:html` (Rake) to generate a
+self-contained HTML report. The file embeds a Mermaid diagram (via CDN), an
+inline Graphviz SVG (when `dot` is installed), a callback list table, an
+execution-order flow, and a nested dependency tree for every condition — no
+external dependencies at view time.
+
+```bash
+# CLI — write report to a file
+callback_lens analyze User --html report.html
+
+# CLI — combine with stdout output
+callback_lens analyze User --mermaid --html report.html
+
+# Rake — default output filename: callback_lens_report.html
+rake callback_lens:html MODEL=User
+
+# Rake — custom output path
+rake callback_lens:html MODEL=User OUT=tmp/user_callbacks.html
+
+# Rake — with recursive method expansion
+rake callback_lens:html MODEL=User OUT=tmp/user_callbacks.html EXPAND=true
+```
+
+| ENV variable | Required | Default | Description |
+|---|---|---|---|
+| `MODEL` | Yes | — | ActiveRecord model class name |
+| `OUT` | No | `callback_lens_report.html` | Output path for the HTML file |
+| `EXPAND` | No | `false` | Set to `true` to recursively expand method conditions |
+
 ### Programmatic API
 
 ```ruby
@@ -100,8 +154,12 @@ puts ActiverecordCallbackLens::Renderer::MermaidRenderer.render(graph)
 |---|---|---|
 | Collector | `CallbackCollector` | Reads ActiveRecord's internal `_save_callbacks`, `_create_callbacks`, `_update_callbacks`, `_destroy_callbacks`, and `_validation_callbacks` chains |
 | Parser | `ConditionParser` | Uses [Prism](https://github.com/ruby/prism) to parse `Proc`/`Lambda` conditions into `AndNode`/`OrNode`/`NotNode`/`PredicateNode` trees; `Symbol` conditions become `MethodRefNode` stubs |
+| Resolver | `MethodResolver` | Recursively expands `MethodRefNode` symbols into full `ConditionTree` sub-trees (up to 5 levels deep) with cycle detection |
 | Graph | `GraphBuilder` | Assembles a DAG of `CallbackNode`, `ConditionNode`, `PredicateNode`, and `MethodNode` values |
+| Analyzer | `ExecutionOrderAnalyzer` | Sorts definitions into canonical Rails execution order (create or update path) |
 | Renderer | `MermaidRenderer` | Serializes the graph to a Mermaid `graph TD` string |
+| Renderer | `GraphvizRenderer` | Serializes the graph to a Graphviz DOT string; `#to_svg` shells out to `dot` |
+| Renderer | `HtmlRenderer` | Produces a self-contained HTML report embedding Mermaid, SVG, callback table, execution flow, and dependency tree |
 
 ## Condition tree nodes
 
@@ -118,9 +176,9 @@ puts ActiverecordCallbackLens::Renderer::MermaidRenderer.render(graph)
 | Version | Feature |
 |---|---|
 | 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.4 | HTML report (callback list, execution flow, embedded diagram) |
+| v0.2 | MethodResolver — recursive expansion of Symbol conditions (`--expand` / `EXPAND=true`) |
+| v0.3 | Graphviz / DOT renderer (`--graphviz` / `callback_lens:graphviz`) |
+| **v0.4** | HTML report — callback list table, execution-order flow, dependency tree, embedded Mermaid and Graphviz SVG (`--html` / `callback_lens:html`) |
 | 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,20 @@ 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"
+require_relative "../renderer/html_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,22 +30,41 @@ 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)"
+      option :html, type: :string, desc: "Write HTML report to FILE"
       # Runs the analysis pipeline for +model_name+ and prints the result.
       #
+      # When +--html FILE+ is given, a self-contained HTML report is written to
+      # FILE (in addition to any stdout output selected by the other flags) and a
+      # confirmation line is printed.
+      #
       # @param model_name [String] the ActiveRecord model class name
       # @return [void]
       def analyze(model_name)
         model_class = resolve_model(model_name)
-        graph = build_graph(model_class, expand: options[:expand])
-        puts Renderer::MermaidRenderer.render(graph) if options[:mermaid]
+        definitions, graph = build_pipeline(model_class, expand: options[:expand])
+        render_outputs(graph, definitions)
       end
 
       private
 
+      # Emits each output selected by the analyze options: Mermaid and/or Graphviz
+      # to stdout, and an HTML report to a file when +--html+ is given.
+      #
+      # @param graph [Graph::Graph]
+      # @param definitions [Array<Collector::CallbackDefinition>]
+      # @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]
+      end
+
       # Resolves a model class by name, printing a friendly error and exiting
       # non-zero when the constant cannot be found.
       #
@@ -60,16 +84,32 @@ module ActiverecordCallbackLens
       # MethodRefNodes resolved into ConditionTree sub-trees via MethodResolver.
       # When false, the pipeline is identical to v0.1 output.
       #
+      # Returns both the parsed definitions and the assembled graph so renderers
+      # that need the definitions directly (e.g. the HTML report) can access them
+      # without re-running the pipeline.
+      #
       # @param model_class [Class]
       # @param expand [Boolean]
-      # @return [Graph::Graph]
-      def build_graph(model_class, expand: false)
+      # @return [Array(Array<Collector::CallbackDefinition>, Graph::Graph)]
+      def build_pipeline(model_class, expand: false)
         definitions = Collector::CallbackCollector.collect(model_class)
         definitions = definitions.map { |definition| Parser::ConditionParser.parse(definition) }
         if expand
           definitions = definitions.map { |definition| Resolver::MethodResolver.expand(definition, model_class) }
         end
-        Graph::GraphBuilder.build(definitions)
+        [definitions, Graph::GraphBuilder.build(definitions)]
+      end
+
+      # Writes the HTML report to +path+ and prints a confirmation line.
+      #
+      # @param graph [Graph::Graph]
+      # @param definitions [Array<Collector::CallbackDefinition>]
+      # @param path [String]
+      # @return [void]
+      def write_html(graph, definitions, path)
+        html = Renderer::HtmlRenderer.render(graph, definitions: definitions)
+        File.write(path, html)
+        puts "HTML report written to #{path}"
       end
     end
   end

data/lib/activerecord_callback_lens/execution_order_analyzer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ActiverecordCallbackLens
+  # Sorts a list of Collector::CallbackDefinition objects into the canonical
+  # order in which Rails executes callbacks on a record save.
+  #
+  # Two orderings are supported, selected via the +operation+ keyword:
+  #
+  # * +:create+ (the default) follows the create path
+  #   (before_create / after_create around the INSERT).
+  # * +:update+ follows the update path
+  #   (before_update / after_update around the UPDATE).
+  #
+  # A definition's position is derived from its +phase_event+ pair (for example
+  # +before_save+). Callbacks whose pair is not part of the canonical order are
+  # placed at the end (sort index 999) while preserving their relative order,
+  # because Ruby's Array#sort_by is stable for equal keys.
+  class ExecutionOrderAnalyzer
+    # Canonical create-path order. Mirrors spec section 7.1 (create path).
+    SAVE_ORDER = %i[
+      before_validation after_validation
+      before_save
+      before_create
+      after_create
+      after_save
+      after_commit
+    ].freeze
+
+    # Canonical update-path order. Mirrors spec section 7.1 (update path).
+    UPDATE_ORDER = %i[
+      before_validation after_validation
+      before_save
+      before_update
+      after_update
+      after_save
+      after_commit
+    ].freeze
+
+    # Sort index assigned to callbacks whose phase_event pair is not part of the
+    # canonical order, so they sort after every recognised callback.
+    UNRECOGNISED_INDEX = 999
+
+    # Sorts +definitions+ into canonical execution order.
+    #
+    # @param definitions [Array<Collector::CallbackDefinition>]
+    # @param operation [Symbol] :create (default) or :update
+    # @return [Array<Collector::CallbackDefinition>] a new sorted array
+    def self.sort(definitions, operation: :create)
+      order = operation == :update ? UPDATE_ORDER : SAVE_ORDER
+      definitions.sort_by do |definition|
+        key = :"#{definition.phase}_#{definition.event}"
+        order.index(key) || UNRECOGNISED_INDEX
+      end
+    end
+  end
+end

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/renderer/html_renderer.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+require_relative "mermaid_renderer"
+require_relative "graphviz_renderer"
+require_relative "../execution_order_analyzer"
+require_relative "../parser/condition_tree"
+
+module ActiverecordCallbackLens
+  module Renderer
+    # Renders a single ConditionTree node (and its descendants) as nested +<ul>+
+    # markup, and exposes the flat list of leaf condition names. Extracted from
+    # HtmlRenderer so the recursive tree handling is a single, testable
+    # responsibility separate from page assembly.
+    #
+    # All names are HTML escaped via CGI.escapeHTML so values containing +<+,
+    # +>+ or +&+ cannot break the surrounding markup.
+    class ConditionTreeHtml
+      Tree = Parser::ConditionTree
+
+      # @param node [Parser::ConditionTree::Node]
+      def initialize(node)
+        @node = node
+      end
+
+      # @return [String] nested <ul> markup for the node
+      def to_html
+        render(@node)
+      end
+
+      # @return [Array<String>] leaf names (predicate + method refs), depth-first
+      def names
+        leaf_names(@node)
+      end
+
+      private
+
+      def render(node)
+        case node
+        when Tree::AndNode       then combinator("AND", node.children)
+        when Tree::OrNode        then combinator("OR", node.children)
+        when Tree::NotNode       then combinator("NOT", [node.child])
+        when Tree::PredicateNode then "<ul><li>#{escape(node.name)}</li></ul>"
+        when Tree::MethodRefNode then method_ref(node)
+        else ""
+        end
+      end
+
+      def combinator(label, children)
+        items = children.map { |child| "<li>#{render(child)}</li>" }
+        "<ul><li>#{escape(label)}</li>#{items.join}</ul>"
+      end
+
+      def method_ref(node)
+        inner = node.expanded_tree.nil? ? "" : render(node.expanded_tree)
+        "<ul><li>#{escape(node.name)}#{inner}</li></ul>"
+      end
+
+      def leaf_names(node)
+        case node
+        when Tree::AndNode, Tree::OrNode
+          node.children.flat_map { |child| leaf_names(child) }
+        when Tree::NotNode
+          leaf_names(node.child)
+        when Tree::PredicateNode, Tree::MethodRefNode
+          [node.name]
+        else
+          []
+        end
+      end
+
+      def escape(value)
+        CGI.escapeHTML(value.to_s)
+      end
+    end
+
+    # Renders a self-contained HTML report for a model's callbacks.
+    #
+    # The document embeds five sections (spec section 8.3):
+    #
+    # 1. Callback List   — a table with columns Phase, Event, Filter, Conditions.
+    # 2. Execution Flow  — an ordered list sorted by ExecutionOrderAnalyzer
+    #    (the +:create+ path).
+    # 3. Dependency Tree — a nested +<ul>+ built from each definition's
+    #    ConditionTree (via ConditionTreeHtml).
+    # 4. Mermaid Diagram — a +<pre class="mermaid">+ block populated by
+    #    MermaidRenderer and rendered client-side via the Mermaid CDN script.
+    # 5. Graphviz SVG    — the inline +<svg>+ produced by GraphvizRenderer#to_svg
+    #    when the +dot+ binary is available; the section is omitted otherwise.
+    #
+    # All user-derived text is HTML escaped with CGI.escapeHTML.
+    class HtmlRenderer
+      # The Mermaid.js bundle loaded from a CDN so the report stays a single,
+      # dependency-free HTML file.
+      MERMAID_CDN = "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"
+
+      # @param graph [Graph::Graph] the assembled dependency graph
+      # @param definitions [Array<Collector::CallbackDefinition>] parsed definitions
+      # @return [String] a complete HTML document
+      def self.render(graph, definitions:)
+        new(graph, definitions).render
+      end
+
+      # @param graph [Graph::Graph]
+      # @param definitions [Array<Collector::CallbackDefinition>]
+      def initialize(graph, definitions)
+        @graph = graph
+        @definitions = definitions
+      end
+
+      # Assembles the full HTML document.
+      #
+      # @return [String]
+      def render
+        <<~HTML
+          <!DOCTYPE html>
+          <html>
+          <head><meta charset="utf-8"><title>Callback Lens</title></head>
+          <body>
+          #{callback_table}
+          #{execution_flow}
+          #{dependency_trees}
+          #{mermaid_section}
+          #{svg_section}
+          <script src="#{MERMAID_CDN}"></script>
+          <script>mermaid.initialize({startOnLoad:true});</script>
+          </body>
+          </html>
+        HTML
+      end
+
+      private
+
+      # Section 1: a table with one row per definition.
+      def callback_table
+        rows = @definitions.map do |definition|
+          "<tr>" \
+            "<td>#{escape(definition.phase)}</td>" \
+            "<td>#{escape(definition.event)}</td>" \
+            "<td>#{escape(filter_label(definition))}</td>" \
+            "<td>#{escape(conditions_label(definition))}</td>" \
+            "</tr>"
+        end
+        <<~HTML.chomp
+          <h2>Callback List</h2>
+          <table>
+          <thead><tr><th>Phase</th><th>Event</th><th>Filter</th><th>Conditions</th></tr></thead>
+          <tbody>
+          #{rows.join("\n")}
+          </tbody>
+          </table>
+        HTML
+      end
+
+      # 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>" }
+        <<~HTML.chomp
+          <h2>Execution Flow</h2>
+          <ol>
+          #{items.join("\n")}
+          </ol>
+        HTML
+      end
+
+      # Section 3: a nested dependency tree per definition that carries a
+      # condition_tree. Definitions without conditions are skipped.
+      def dependency_trees
+        trees = @definitions.filter_map do |definition|
+          next if definition.condition_tree.nil?
+
+          "<li>#{escape("#{definition.phase}_#{definition.event}")}" \
+            "#{ConditionTreeHtml.new(definition.condition_tree).to_html}</li>"
+        end
+        <<~HTML.chomp
+          <h2>Dependency Tree</h2>
+          <ul>
+          #{trees.join("\n")}
+          </ul>
+        HTML
+      end
+
+      # Section 4: the Mermaid source wrapped in a client-rendered block.
+      def mermaid_section
+        <<~HTML.chomp
+          <h2>Mermaid Diagram</h2>
+          <pre class="mermaid">#{escape(MermaidRenderer.render(@graph))}</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
+        return "" if svg.nil?
+
+        <<~HTML.chomp
+          <h2>Graphviz SVG</h2>
+          <div class="graphviz">#{svg}</div>
+        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
+        return "" if tree.nil?
+
+        ConditionTreeHtml.new(tree).names.join(", ")
+      end
+
+      # HTML-escapes a value so it is safe to embed as element text.
+      def escape(value)
+        CGI.escapeHTML(value.to_s)
+      end
+    end
+  end
+end

data/lib/activerecord_callback_lens/tasks/callback_lens.rake

@@ -17,4 +17,22 @@ 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
+
+  desc "Write a self-contained HTML report to OUT for MODEL " \
+       "(e.g. rake callback_lens:html MODEL=User OUT=report.html EXPAND=true)"
+  task html: :environment do
+    model_class = CallbackLensRakeHelpers.resolve_model!(ENV.fetch("MODEL", nil))
+    expand = CallbackLensRakeHelpers.expand?(ENV.fetch("EXPAND", nil))
+    out = ENV.fetch("OUT", "callback_lens_report.html")
+    File.write(out, CallbackLensRakeHelpers.render_html(model_class, expand: expand))
+    puts "Report written to #{out}"
+  end
 end

data/lib/activerecord_callback_lens/tasks/callback_lens_helpers.rb

@@ -46,6 +46,48 @@ 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
+
+  # Runs the full pipeline (collect -> parse -> [expand] -> build) for a model and
+  # returns a self-contained HTML report via HtmlRenderer. Mirrors
+  # +render_mermaid+ / +render_graphviz+ but passes both the parsed definitions
+  # and the assembled graph to the HtmlRenderer, which needs the definitions to
+  # build the callback table, execution flow, and dependency tree. +expand+ is
+  # threaded through identically so the +EXPAND=true+ rake convention applies.
+  #
+  # @param model_class [Class]
+  # @param expand [Boolean]
+  # @return [String] a complete HTML document
+  def render_html(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::HtmlRenderer.render(graph, definitions: definitions)
+  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.4.0"
 end

data/lib/activerecord_callback_lens.rb

@@ -9,7 +9,10 @@ require "activerecord_callback_lens/parser/condition_parser"
 require "activerecord_callback_lens/resolver/method_resolver"
 require "activerecord_callback_lens/graph/nodes"
 require "activerecord_callback_lens/graph/graph_builder"
+require "activerecord_callback_lens/execution_order_analyzer"
 require "activerecord_callback_lens/renderer/mermaid_renderer"
+require "activerecord_callback_lens/renderer/graphviz_renderer"
+require "activerecord_callback_lens/renderer/html_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.4.0
 platform: ruby
 authors:
 - Eraxel.Dev
@@ -75,12 +75,15 @@ files:
 - lib/activerecord_callback_lens/cli/cli.rb
 - lib/activerecord_callback_lens/collector/callback_collector.rb
 - lib/activerecord_callback_lens/collector/callback_definition.rb
+- lib/activerecord_callback_lens/execution_order_analyzer.rb
 - lib/activerecord_callback_lens/graph/graph_builder.rb
 - lib/activerecord_callback_lens/graph/nodes.rb
 - lib/activerecord_callback_lens/parser/ast_walker.rb
 - 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/html_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