activerecord_callback_lens 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a539b633bd3793bd684d7a93236783afbdb13b946400fd968c204281c3435e7f
+  data.tar.gz: 806014fbee749570c24bac4df333d85f96157d16e42ba5b880380682c729102d
+SHA512:
+  metadata.gz: 44ab27417d490c5ab1e39b8d3f900f92aa94ece3334be91dd65a04113b77ad2c93a1b95a09b5ec12e90344bd9911f7239e2b9f6864c11cd1f673d4cd23ec792a
+  data.tar.gz: 384e76570141682a41e7fd5dd2402580999a52e24c8196271739017b83452d4ec5ccd94fcf1918ef8a04f1a8842ea1c49ed16a68653b665796d427fdff29be53

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eraxel.Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,110 @@
+# activerecord_callback_lens
+
+**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.
+
+## Requirements
+
+- Ruby >= 3.2
+- ActiveRecord >= 7.0, < 9.0
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "activerecord_callback_lens"
+```
+
+Or install directly:
+
+```sh
+gem install activerecord_callback_lens
+```
+
+## Usage
+
+### CLI
+
+Point the `callback_lens` binary at any loaded ActiveRecord model:
+
+```sh
+callback_lens analyze User
+```
+
+This prints a Mermaid `graph TD` diagram to stdout showing every callback and its condition dependencies.
+
+```
+graph TD
+  n0["before_save"]
+  n1["AndNode"]
+  n2["saved_change_to_title?"]
+  n3["status_completed?"]
+  n2 --> n1
+  n3 --> n1
+  n1 --> n0
+```
+
+> **Note:** The model class must be loaded before analysis. In a Rails app, run the binary inside `rails runner` or require your environment first.
+
+### Rake task (Rails)
+
+The gem ships a Railtie that automatically loads the `callback_lens` namespace into your Rails rake tasks:
+
+```sh
+rake callback_lens:analyze MODEL=User
+rake callback_lens:mermaid  MODEL=User   # alias
+```
+
+### Programmatic API
+
+```ruby
+require "activerecord_callback_lens"
+
+# 1. Collect raw callback definitions
+definitions = ActiverecordCallbackLens::Collector::CallbackCollector.collect(User)
+
+# 2. Parse if/unless conditions into ConditionTrees
+definitions = definitions.map { |d| ActiverecordCallbackLens::Parser::ConditionParser.parse(d) }
+
+# 3. Build a dependency graph
+graph = ActiverecordCallbackLens::Graph::GraphBuilder.build(definitions)
+
+# 4. Render as Mermaid
+puts ActiverecordCallbackLens::Renderer::MermaidRenderer.render(graph)
+```
+
+## How it works
+
+| Layer | Class | Responsibility |
+|---|---|---|
+| 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 |
+| Graph | `GraphBuilder` | Assembles a DAG of `CallbackNode`, `ConditionNode`, `PredicateNode`, and `MethodNode` values |
+| Renderer | `MermaidRenderer` | Serializes the graph to a Mermaid `graph TD` string |
+
+## Condition tree nodes
+
+| Node | Meaning |
+|---|---|
+| `AndNode` | All children must be true |
+| `OrNode` | At least one child must be true |
+| `NotNode` | Negates its child (from `unless:`) |
+| `PredicateNode` | A leaf predicate call (e.g. `saved_change_to_title?`) |
+| `MethodRefNode` | A Symbol condition (e.g. `:sync_required?`) — expanded in v0.2 |
+
+## Roadmap
+
+| Version | Feature |
+|---|---|
+| **v0.1** | CallbackCollector, Prism condition parser, Mermaid renderer, CLI, Rake task |
+| v0.2 | MethodResolver — recursive expansion of Symbol conditions |
+| v0.3 | Graphviz / DOT renderer |
+| 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 |
+
+## License
+
+[MIT](LICENSE)

data/activerecord_callback_lens.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/activerecord_callback_lens/version"
+
+Gem::Specification.new do |s|
+  s.name        = "activerecord_callback_lens"
+  s.version     = ActiverecordCallbackLens::VERSION
+  s.summary     = "X-ray your ActiveRecord callbacks"
+  s.description = "Inspect, parse, and visualize the callbacks registered on your " \
+                  "ActiveRecord models — including their if/unless conditions — as " \
+                  "graphs and diagrams."
+  s.authors     = ["Eraxel.Dev"]
+  s.email       = ["masacode.vancouver@gmail.com"]
+  s.homepage    = "https://github.com/eraxel/activerecord_callback_lens"
+  s.license     = "MIT"
+
+  s.required_ruby_version = ">= 3.2"
+
+  s.bindir        = "exe"
+  s.executables   = ["callback_lens"]
+  s.require_paths = ["lib"]
+  s.files = Dir[
+    "lib/**/*.rb",
+    "lib/**/*.rake",
+    "exe/*",
+    "LICENSE",
+    "README.md",
+    "activerecord_callback_lens.gemspec"
+  ]
+
+  s.metadata = {
+    "homepage_uri" => s.homepage,
+    "source_code_uri" => s.homepage,
+    "rubygems_mfa_required" => "true"
+  }
+
+  s.add_dependency "activerecord", ">= 7.0", "< 9.0"
+  s.add_dependency "prism", "~> 1.0"
+  s.add_dependency "thor", "~> 1.0"
+end

data/exe/callback_lens

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "activerecord_callback_lens"
+
+ActiverecordCallbackLens::CLI::App.start(ARGV)

data/lib/activerecord_callback_lens/cli/cli.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "thor"
+
+require_relative "../collector/callback_collector"
+require_relative "../parser/condition_parser"
+require_relative "../graph/graph_builder"
+require_relative "../renderer/mermaid_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.
+    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.
+      #
+      # @return [Boolean]
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "analyze MODEL", "Analyze callbacks for a model class and print a Mermaid diagram"
+      option :mermaid, type: :boolean, default: true, desc: "Output a Mermaid diagram to stdout"
+      # Runs the analysis pipeline for +model_name+ and prints the result.
+      #
+      # @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)
+        puts Renderer::MermaidRenderer.render(graph) if options[:mermaid]
+      end
+
+      private
+
+      # Resolves a model class by name, printing a friendly error and exiting
+      # non-zero when the constant cannot be found.
+      #
+      # @param model_name [String]
+      # @return [Class]
+      def resolve_model(model_name)
+        Object.const_get(model_name)
+      rescue NameError
+        warn "Error: cannot find model class '#{model_name}'. Make sure it is loaded."
+        exit 1
+      end
+
+      # Collect -> Parse -> Build the dependency graph for a model class.
+      #
+      # @param model_class [Class]
+      # @return [Graph::Graph]
+      def build_graph(model_class)
+        definitions = Collector::CallbackCollector.collect(model_class)
+        definitions = definitions.map { |definition| Parser::ConditionParser.parse(definition) }
+        Graph::GraphBuilder.build(definitions)
+      end
+    end
+  end
+end

data/lib/activerecord_callback_lens/collector/callback_collector.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "callback_definition"
+
+module ActiverecordCallbackLens
+  module Collector
+    # Reads ActiveRecord's internal callback chains for a model class and returns
+    # an array of CallbackDefinition structs with raw condition data, ready for
+    # the Parser layer to populate +condition_tree+.
+    #
+    # Each of the five callback events (save, create, update, destroy, validation)
+    # is accessed through ActiveRecord's private chain accessor and every
+    # ActiveSupport::Callbacks::Callback in the chain is converted into one
+    # CallbackDefinition.
+    class CallbackCollector
+      # The callback events enumerated, in a stable order.
+      EVENTS = %i[save create update destroy validation].freeze
+
+      # Maps each event to ActiveRecord's internal callback chain accessor.
+      CHAIN_METHODS = {
+        save: :_save_callbacks,
+        create: :_create_callbacks,
+        update: :_update_callbacks,
+        destroy: :_destroy_callbacks,
+        validation: :_validation_callbacks
+      }.freeze
+
+      # Collect all callbacks registered on a model class.
+      #
+      # @param model_class [Class] an ActiveRecord::Base subclass
+      # @return [Array<CallbackDefinition>]
+      def self.collect(model_class)
+        new(model_class).collect
+      end
+
+      # @param model_class [Class] an ActiveRecord::Base subclass
+      def initialize(model_class)
+        @model_class = model_class
+      end
+
+      # @return [Array<CallbackDefinition>]
+      def collect
+        EVENTS.flat_map { |event| collect_event(event) }
+      end
+
+      private
+
+      # @param event [Symbol]
+      # @return [Array<CallbackDefinition>]
+      def collect_event(event)
+        chain = @model_class.send(CHAIN_METHODS[event])
+        chain.map { |callback| build_definition(callback, event) }
+      end
+
+      # @param callback [ActiveSupport::Callbacks::Callback]
+      # @param event [Symbol]
+      # @return [CallbackDefinition]
+      def build_definition(callback, event)
+        filter = callback.filter
+        CallbackDefinition.new(
+          model: @model_class,
+          event: event,
+          phase: callback.kind,
+          filter: filter,
+          raw_conditions: extract_conditions(callback),
+          condition_tree: nil,
+          source_location: resolve_location(filter)
+        )
+      end
+
+      # Extracts the raw if/unless condition arrays from a callback's internals.
+      #
+      # @param callback [ActiveSupport::Callbacks::Callback]
+      # @return [Hash{Symbol => Array}]
+      def extract_conditions(callback)
+        {
+          if: Array(callback.instance_variable_get(:@if)),
+          unless: Array(callback.instance_variable_get(:@unless))
+        }
+      end
+
+      # Resolves the source location for a filter when possible.
+      #
+      # Proc/Lambda filters expose +source_location+; Symbol filters are resolved
+      # later by the MethodResolver (v0.2), and String filters have no location.
+      #
+      # @param filter [Symbol, Proc, String]
+      # @return [Array(String, Integer), nil]
+      def resolve_location(filter)
+        case filter
+        when Proc then filter.source_location
+        end
+      end
+    end
+  end
+end

data/lib/activerecord_callback_lens/collector/callback_definition.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActiverecordCallbackLens
+  module Collector
+    # Represents a single callback registered on an ActiveRecord model.
+    #
+    # event + phase together reconstruct the full callback name
+    # (e.g. :before + :save => before_save).
+    # raw_conditions holds the unprocessed if/unless arrays from AR internals.
+    # condition_tree is nil until the Parser populates it (nil when no conditions).
+    CallbackDefinition = Data.define(
+      :model,           # Class — the ActiveRecord model class
+      :event,           # Symbol — :save, :create, :update, :destroy, :validation
+      :phase,           # Symbol — :before, :after, :around
+      :filter,          # Symbol | Proc | String — the callback body
+      :raw_conditions,  # { if: [...], unless: [...] } — raw arrays from AR internals
+      :condition_tree,  # ConditionTree::Node | nil — parsed logical tree
+      :source_location  # [String, Integer] | nil — file and line of the filter
+    )
+  end
+end

data/lib/activerecord_callback_lens/graph/graph_builder.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "nodes"
+require_relative "../parser/condition_tree"
+
+module ActiverecordCallbackLens
+  module Graph
+    # Converts an array of parsed CallbackDefinition objects into a Graph.
+    #
+    # Each definition becomes a CallbackNode. When a definition has a
+    # condition_tree, the tree is walked recursively and mapped onto graph nodes:
+    #
+    #   AndNode / OrNode  -> ConditionNode, then recurse into children
+    #   NotNode           -> no node; recurse into the child (negation is dropped
+    #                        for the v0.1 dependency view)
+    #   PredicateNode     -> PredicateNode graph node
+    #   MethodRefNode     -> MethodNode; recurse into expanded_tree when present
+    #
+    # Every condition/predicate/method node gets a +:requires+ edge pointing at
+    # its parent (the callback or enclosing combinator), so edges flow from a
+    # dependency up to the thing that depends on it.
+    class GraphBuilder
+      # @param definitions [Array<Collector::CallbackDefinition>]
+      # @return [Graph::Graph]
+      def self.build(definitions)
+        new(definitions).build
+      end
+
+      # @param definitions [Array<Collector::CallbackDefinition>]
+      def initialize(definitions)
+        @definitions = definitions
+        @nodes = []
+        @edges = []
+        @counter = 0
+      end
+
+      # @return [Graph::Graph]
+      def build
+        @definitions.each { |definition| add_callback(definition) }
+        Graph.new(nodes: @nodes, edges: @edges)
+      end
+
+      private
+
+      # Generates a stable, monotonically increasing node id ("n0", "n1", ...).
+      #
+      # @return [String]
+      def next_id
+        id = "n#{@counter}"
+        @counter += 1
+        id
+      end
+
+      # @param definition [Collector::CallbackDefinition]
+      # @return [void]
+      def add_callback(definition)
+        callback_node = CallbackNode.new(id: next_id, definition: definition)
+        @nodes << callback_node
+        return unless definition.condition_tree
+
+        add_tree(definition.condition_tree, parent_id: callback_node.id)
+      end
+
+      # Recursively maps a ConditionTree node onto graph nodes and edges.
+      #
+      # @param tree_node [Parser::ConditionTree::Node, nil]
+      # @param parent_id [String] id of the node this subtree depends on
+      # @return [void]
+      def add_tree(tree_node, parent_id:)
+        case tree_node
+        when Parser::ConditionTree::AndNode, Parser::ConditionTree::OrNode
+          add_combinator(tree_node, parent_id: parent_id)
+        when Parser::ConditionTree::NotNode
+          add_tree(tree_node.child, parent_id: parent_id)
+        when Parser::ConditionTree::PredicateNode
+          add_leaf(PredicateNode.new(id: next_id, predicate_name: tree_node.name), parent_id: parent_id)
+        when Parser::ConditionTree::MethodRefNode
+          add_method_ref(tree_node, parent_id: parent_id)
+        end
+      end
+
+      # @param tree_node [Parser::ConditionTree::AndNode, Parser::ConditionTree::OrNode]
+      # @param parent_id [String]
+      # @return [void]
+      def add_combinator(tree_node, parent_id:)
+        condition_node = ConditionNode.new(id: next_id, tree_node: tree_node)
+        @nodes << condition_node
+        @edges << Edge.new(from_id: condition_node.id, to_id: parent_id, label: :requires)
+        tree_node.children.each { |child| add_tree(child, parent_id: condition_node.id) }
+      end
+
+      # @param tree_node [Parser::ConditionTree::MethodRefNode]
+      # @param parent_id [String]
+      # @return [void]
+      def add_method_ref(tree_node, parent_id:)
+        method_node = MethodNode.new(id: next_id, method_name: tree_node.name)
+        @nodes << method_node
+        @edges << Edge.new(from_id: method_node.id, to_id: parent_id, label: :requires)
+        return unless tree_node.expanded_tree
+
+        add_tree(tree_node.expanded_tree, parent_id: method_node.id)
+      end
+
+      # Appends a leaf node and its edge to the enclosing parent.
+      #
+      # @param node [Graph::PredicateNode]
+      # @param parent_id [String]
+      # @return [void]
+      def add_leaf(node, parent_id:)
+        @nodes << node
+        @edges << Edge.new(from_id: node.id, to_id: parent_id, label: :requires)
+      end
+    end
+  end
+end

data/lib/activerecord_callback_lens/graph/nodes.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActiverecordCallbackLens
+  module Graph
+    # The graph layer turns a list of CallbackDefinition objects (with their
+    # parsed ConditionTrees) into a directed acyclic graph of typed nodes and
+    # labelled edges, ready for a renderer to emit.
+    #
+    # Every node carries a unique +id+ (assigned by the GraphBuilder) plus the
+    # domain object it represents. Edges connect a child node to its parent via
+    # +from_id+ / +to_id+ and carry a +label+ describing the relationship
+    # (+:requires+ for condition/predicate/method dependencies).
+    #
+    # All node and edge types are immutable Data values.
+
+    # One node per CallbackDefinition, e.g. before_save / after_commit.
+    # definition: Collector::CallbackDefinition
+    CallbackNode = Data.define(:id, :definition)
+
+    # One node per logical combinator (AndNode / OrNode) in a ConditionTree.
+    # tree_node: ConditionTree::AndNode | ConditionTree::OrNode
+    ConditionNode = Data.define(:id, :tree_node)
+
+    # One node per Symbol condition (e.g. :sync_required?). method_name: String
+    MethodNode = Data.define(:id, :method_name)
+
+    # One node per predicate method call (e.g. saved_change_to_title?).
+    # predicate_name: String
+    PredicateNode = Data.define(:id, :predicate_name)
+
+    # A directed edge from a child node to its parent node. label: Symbol
+    Edge = Data.define(:from_id, :to_id, :label)
+
+    # The assembled graph: a flat list of nodes and a flat list of edges.
+    # nodes: Array<node>, edges: Array<Edge>
+    Graph = Data.define(:nodes, :edges)
+  end
+end

data/lib/activerecord_callback_lens/parser/condition_parser.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "condition_tree"
+
+module ActiverecordCallbackLens
+  module Parser
+    # Turns a CallbackDefinition's raw if/unless conditions into a structured
+    # ConditionTree.
+    #
+    # Proc/Lambda conditions are parsed by reading their source file with Prism,
+    # isolating the enclosing lambda/block node by line number, and recursively
+    # mapping the boolean AST (`&&`, `||`, `!`, predicate calls) onto ConditionTree
+    # nodes. Symbol conditions become MethodRefNodes whose expansion is deferred to
+    # the MethodResolver. Any other entry kind (e.g. ActiveModel's framework
+    # injected Conditionals::Value guard on after_* callbacks) is ignored.
+    #
+    # Parsing never raises on missing or unreadable source: a nil source_location
+    # or a missing file is skipped silently, and a Prism parse failure warns to
+    # $stderr while leaving the condition unresolved.
+    class ConditionParser
+      # @param definition [Collector::CallbackDefinition]
+      # @return [Collector::CallbackDefinition] a copy with condition_tree populated
+      def self.parse(definition)
+        new(definition).parse
+      end
+
+      # @param definition [Collector::CallbackDefinition]
+      def initialize(definition)
+        @definition = definition
+      end
+
+      # @return [Collector::CallbackDefinition] a copy with condition_tree set
+      def parse
+        @definition.with(condition_tree: build_tree)
+      end
+
+      private
+
+      # Assembles if_nodes and negated unless_nodes into a single tree.
+      #
+      # @return [ConditionTree::Node, nil] nil when there are no resolvable conditions
+      def build_tree
+        conditions   = @definition.raw_conditions
+        if_nodes     = Array(conditions[:if]).map { |c| parse_condition(c) }
+        unless_nodes = Array(conditions[:unless]).map { |c| negate(parse_condition(c)) }
+
+        combine((if_nodes + unless_nodes).compact)
+      end
+
+      # Reduces a flat list of resolved condition nodes to a single tree.
+      #
+      # @param nodes [Array<ConditionTree::Node>]
+      # @return [ConditionTree::Node, nil]
+      def combine(nodes)
+        case nodes.size
+        when 0 then nil
+        when 1 then nodes.first
+        else ConditionTree::AndNode.new(children: nodes)
+        end
+      end
+
+      # @param node [ConditionTree::Node, nil]
+      # @return [ConditionTree::NotNode, nil]
+      def negate(node)
+        return nil if node.nil?
+
+        ConditionTree::NotNode.new(child: node)
+      end
+
+      # Dispatches a single raw condition entry to the right handler.
+      #
+      # @param condition [Symbol, Proc, Object]
+      # @return [ConditionTree::Node, nil]
+      def parse_condition(condition)
+        case condition
+        when Symbol then ConditionTree::MethodRefNode.new(name: condition.to_s, expanded_tree: nil)
+        when Proc   then parse_proc(condition)
+        end
+      end
+
+      # Parses a Proc/Lambda condition by reading and walking its source.
+      #
+      # @param proc_obj [Proc]
+      # @return [ConditionTree::Node, nil]
+      def parse_proc(proc_obj)
+        file, line = proc_obj.source_location
+        return nil unless file && File.exist?(file)
+
+        result = Prism.parse_file(file)
+        unless result.success?
+          warn("[ActiverecordCallbackLens] Failed to parse #{file}: #{result.errors.map(&:message).join(', ')}")
+          return nil
+        end
+
+        locator = LambdaLocator.new(target_line: line)
+        locator.visit(result.value)
+        walk(locator.node)
+      end
+
+      # Recursively maps a Prism boolean AST onto ConditionTree nodes.
+      #
+      # @param node [Prism::Node, nil]
+      # @return [ConditionTree::Node, nil]
+      def walk(node)
+        case node
+        in Prism::StatementsNode then walk(node.body.last)
+        in Prism::ParenthesesNode then walk(node.body)
+        in Prism::AndNode then combinator(ConditionTree::AndNode, node)
+        in Prism::OrNode then combinator(ConditionTree::OrNode, node)
+        in Prism::CallNode if node.name == :! then negate(walk(node.receiver))
+        in Prism::CallNode then ConditionTree::PredicateNode.new(name: node.name.to_s)
+        else nil
+        end
+      end
+
+      # Builds an And/Or combinator from a binary Prism node, walking both sides
+      # and dropping any unresolved (nil) operand.
+      #
+      # @param klass [Class] ConditionTree::AndNode or ConditionTree::OrNode
+      # @param node [Prism::AndNode, Prism::OrNode]
+      # @return [ConditionTree::Node]
+      def combinator(klass, node)
+        klass.new(children: [walk(node.left), walk(node.right)].compact)
+      end
+
+      # A Prism visitor that captures the innermost LambdaNode or BlockNode whose
+      # source range encloses a target line. Used to isolate a single proc's body
+      # from the surrounding file AST.
+      class LambdaLocator < Prism::Visitor
+        # @return [Prism::Node, nil] the body of the innermost matching lambda/block
+        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's body 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.body
+        end
+      end
+    end
+  end
+end

data/lib/activerecord_callback_lens/parser/condition_tree.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ActiverecordCallbackLens
+  module Parser
+    # The ConditionTree is the parsed, logical representation of a callback's
+    # if/unless conditions. Every node is an immutable Data type.
+    module ConditionTree
+      # Base node carrying an arbitrary set of children. Retained for
+      # forward-compatibility with generic tree traversals.
+      Node = Data.define(:children)
+
+      # Logical combinators.
+      AndNode = Data.define(:children) # children: Array<Node>
+      OrNode  = Data.define(:children) # children: Array<Node>
+      NotNode = Data.define(:child)    # child: Node
+
+      # Leaf: a single predicate method call, e.g. "saved_change_to_title?".
+      PredicateNode = Data.define(:name) # name: String
+
+      # Leaf: a symbol condition such as :sync_required?.
+      # expanded_tree is the result of MethodResolver, nil in v0.1 / when unresolved.
+      MethodRefNode = Data.define(:name, :expanded_tree) # name: String, expanded_tree: Node | nil
+    end
+  end
+end

data/lib/activerecord_callback_lens/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiverecordCallbackLens
+  # Rails integration hook. When the gem is loaded inside a Rails application,
+  # this Railtie registers the gem's Rake tasks so that
+  # +rake callback_lens:analyze MODEL=User+ works without any manual +require+.
+  #
+  # The file is only loaded when +Rails::Railtie+ is defined (guarded by the
+  # top-level entry point), so it is a no-op outside of Rails.
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("tasks/callback_lens.rake", __dir__)
+    end
+  end
+end

data/lib/activerecord_callback_lens/renderer/mermaid_renderer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "../graph/nodes"
+
+module ActiverecordCallbackLens
+  module Renderer
+    # Renders a Graph::Graph as a Mermaid `graph TD` (top-down) diagram string.
+    #
+    # The output is a header line followed by one declaration per node and one
+    # arrow per edge:
+    #
+    #   graph TD
+    #     n0["before_save"]
+    #     n1["active?"]
+    #     n1 --> n0
+    #
+    # Node labels are derived from the node type (see #node_label) and are
+    # escaped so that quotes in a predicate or method name cannot break the
+    # surrounding Mermaid label syntax.
+    class MermaidRenderer
+      # @param graph [Graph::Graph]
+      # @return [String]
+      def self.render(graph)
+        new(graph).render
+      end
+
+      # @param graph [Graph::Graph]
+      def initialize(graph)
+        @graph = graph
+      end
+
+      # @return [String]
+      def render
+        lines = ["graph TD"]
+        lines.concat(node_declarations)
+        lines.concat(edge_declarations)
+        lines.join("\n")
+      end
+
+      private
+
+      # @return [Array<String>]
+      def node_declarations
+        @graph.nodes.map { |node| "  #{node.id}[\"#{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 `["..."]` Mermaid label.
+      # Double quotes become the Mermaid HTML entity and the escape character
+      # itself is normalised so the label stays a single, valid token.
+      #
+      # @param label [String]
+      # @return [String]
+      def escape(label)
+        label.to_s.gsub("\"", "&quot;")
+      end
+    end
+  end
+end

data/lib/activerecord_callback_lens/tasks/callback_lens.rake

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "callback_lens_helpers"
+
+namespace :callback_lens do
+  desc "Print callback Mermaid diagram for MODEL (e.g. rake callback_lens:analyze MODEL=User)"
+  task analyze: :environment do
+    model_class = CallbackLensRakeHelpers.resolve_model!(ENV.fetch("MODEL", nil))
+    puts CallbackLensRakeHelpers.render_mermaid(model_class)
+  end
+
+  desc "Alias for callback_lens:analyze — print Mermaid diagram for MODEL"
+  task mermaid: :environment do
+    model_class = CallbackLensRakeHelpers.resolve_model!(ENV.fetch("MODEL", nil))
+    puts CallbackLensRakeHelpers.render_mermaid(model_class)
+  end
+end

data/lib/activerecord_callback_lens/tasks/callback_lens_helpers.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "activerecord_callback_lens"
+
+# Helpers backing the callback_lens Rake tasks. Extracted into a plain Ruby
+# module (rather than task-local methods) so the logic is namespaced and unit
+# testable without loading Rake or invoking a task.
+module CallbackLensRakeHelpers
+  module_function
+
+  # Resolves an ActiveRecord model class from its name, raising a descriptive
+  # error when MODEL is missing or the constant cannot be found.
+  #
+  # @param name [String, nil] the value of the MODEL environment variable
+  # @return [Class]
+  # @raise [RuntimeError] when name is nil/empty or the class is not loaded
+  def resolve_model!(name)
+    raise "MODEL is required. Usage: rake callback_lens:analyze MODEL=User" if name.nil? || name.empty?
+
+    Object.const_get(name)
+  rescue NameError
+    raise "Cannot find model class '#{name}'. Make sure it is loaded."
+  end
+
+  # Runs the full pipeline (collect -> parse -> build -> render) for a model.
+  #
+  # @param model_class [Class]
+  # @return [String] the Mermaid diagram
+  def render_mermaid(model_class)
+    definitions = ActiverecordCallbackLens::Collector::CallbackCollector.collect(model_class)
+    definitions = definitions.map { |definition| ActiverecordCallbackLens::Parser::ConditionParser.parse(definition) }
+    graph = ActiverecordCallbackLens::Graph::GraphBuilder.build(definitions)
+    ActiverecordCallbackLens::Renderer::MermaidRenderer.render(graph)
+  end
+end

data/lib/activerecord_callback_lens/version.rb

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

data/lib/activerecord_callback_lens.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "activerecord_callback_lens/version"
+require "activerecord_callback_lens/collector/callback_definition"
+require "activerecord_callback_lens/collector/callback_collector"
+require "activerecord_callback_lens/parser/condition_tree"
+require "activerecord_callback_lens/parser/condition_parser"
+require "activerecord_callback_lens/graph/nodes"
+require "activerecord_callback_lens/graph/graph_builder"
+require "activerecord_callback_lens/renderer/mermaid_renderer"
+require "activerecord_callback_lens/cli/cli"
+require "activerecord_callback_lens/railtie" if defined?(Rails::Railtie)
+
+# Top-level namespace for the gem. Subsequent tasks append their requires above.
+module ActiverecordCallbackLens
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: activerecord_callback_lens
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eraxel.Dev
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Inspect, parse, and visualize the callbacks registered on your ActiveRecord
+  models — including their if/unless conditions — as graphs and diagrams.
+email:
+- masacode.vancouver@gmail.com
+executables:
+- callback_lens
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- activerecord_callback_lens.gemspec
+- exe/callback_lens
+- lib/activerecord_callback_lens.rb
+- 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/graph/graph_builder.rb
+- lib/activerecord_callback_lens/graph/nodes.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/mermaid_renderer.rb
+- lib/activerecord_callback_lens/tasks/callback_lens.rake
+- lib/activerecord_callback_lens/tasks/callback_lens_helpers.rb
+- lib/activerecord_callback_lens/version.rb
+homepage: https://github.com/eraxel/activerecord_callback_lens
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/eraxel/activerecord_callback_lens
+  source_code_uri: https://github.com/eraxel/activerecord_callback_lens
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: X-ray your ActiveRecord callbacks
+test_files: []