blast_radius 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 654553ebc700ee352c5d6f5bc909effe458664ad3b24f138dc9a54320336db4c
+  data.tar.gz: 54cb0c8cd25bfac54475c94465588c2029faf455f4c6e9d8ece8ea00b917f625
+SHA512:
+  metadata.gz: c33eae8d1de31cbb141e1217a83711be7cc4577c6b6da178de494234d9849368346e9f71df1d84ecf97a6bb5ba4f456f284dda6e6372af6a2b264bd68d3593c0
+  data.tar.gz: 39729fe6274532a7f78a0476efe9f929597841730d0985122e3b3a6d5b2f3caff955dad328a4c1112f5f30818ae44bd7e01b95c47cb742956cb01386d19ae068

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.1.0 - 2025-12-17
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,259 @@
+# BlastRadius
+
+A Ruby gem for visualizing the cascade deletion impact in Rails applications. BlastRadius helps you understand which records will be deleted when you delete a record, based on ActiveRecord associations with `dependent` options.
+
+## Features
+
+- Dependency Analysis: Analyze ActiveRecord model associations and their `dependent` options
+- Cascade Visualization: Build and visualize dependency trees showing cascade deletion paths
+- Impact Calculation: Calculate the actual number of records that would be deleted
+- Multiple Dependent Types: Support for `:destroy`, `:delete_all`, `:destroy_async`, `:nullify`, `:restrict_with_exception`, `:restrict_with_error`
+- Multiple Output Formats:
+  - Text: ASCII tree for terminal/console
+  - Mermaid: Diagrams for Markdown (GitHub, GitLab)
+  - JSON: Machine-readable format for APIs
+  - DOT: Graphviz format for generating images (PNG, SVG, PDF)
+  - HTML: Self-contained interactive visualization
+- Rails Integration: ActiveRecord DSL, Rake tasks, and console helpers
+- Configurable: Depth limits, model exclusion patterns, and format options
+- Safe: Dry-run mode to preview deletions without actually deleting
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'blast_radius'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+# Analyze a model
+tree = BlastRadius.analyze(User)
+
+# Format as text
+formatter = BlastRadius::Formatters::TextFormatter.new
+puts formatter.format(tree)
+```
+
+### Rails Integration
+
+#### ActiveRecord DSL
+
+```ruby
+# Class method - analyze model dependencies
+User.blast_radius                      # Default format (text)
+User.blast_radius(format: :mermaid)    # Mermaid format
+User.blast_radius(format: :json)       # JSON format
+User.blast_radius(format: :dot)        # DOT (Graphviz) format
+User.blast_radius(format: :html)       # HTML format
+
+# Instance methods - analyze specific record impact
+user = User.find(1)
+user.blast_radius_impact               # Returns hash of model => count
+user.blast_radius_dry_run              # Returns detailed impact with sample IDs
+```
+
+#### Rake Tasks
+
+```bash
+# Visualize all models
+rails blast_radius:visualize
+
+# Visualize specific model
+rails blast_radius:visualize[User]
+
+# Visualize with different format
+rails blast_radius:visualize[User,mermaid]
+FORMAT=json rails blast_radius:visualize[User]
+
+# Calculate impact of deleting a specific record
+rails blast_radius:impact[User,123]
+
+# Generate HTML file
+rails blast_radius:html[User,output.html]
+```
+
+### Impact Calculation
+
+Calculate the actual number of records that would be deleted:
+
+```ruby
+user = User.find(1)
+
+# Simple count
+impact = user.blast_radius_impact
+# => {"Post" => 5, "Comment" => 20, "Like" => 100}
+
+# Detailed information with sample IDs
+detailed = user.blast_radius_dry_run
+# => {
+#   "Post" => {
+#     count: 5,
+#     dependent_type: :destroy,
+#     sample_ids: [1, 2, 3, 4, 5]
+#   },
+#   "Comment" => {...}
+# }
+```
+
+### Configuration
+
+```ruby
+# config/initializers/blast_radius.rb
+BlastRadius.configure do |config|
+  config.max_depth = 10
+  config.default_format = :text
+  config.include_nullify = false
+  config.include_restrict = false
+  config.exclude_models = [/^HABTM_/, /^ActiveStorage::/]
+  config.colorize = true
+end
+```
+
+## Output Format Examples
+
+BlastRadius supports multiple output formats for different use cases. See the [`examples/`](./examples/) directory for complete examples.
+
+### Text Format (ASCII Tree)
+
+Terminal-friendly output with box-drawing characters:
+
+```
+User
+├── [destroy] posts (Post)
+│   ├── [destroy] comments (Comment)
+│   │   └── [destroy] reactions (Reaction)
+│   └── [delete_all] likes (Like)
+├── [destroy] profile (Profile)
+└── [destroy_async] notifications (Notification)
+```
+
+### Mermaid Format
+
+For documentation in Markdown (GitHub, GitLab):
+
+```mermaid
+graph TD
+    User -->|posts|destroy| node1[Post]
+    node1 -->|comments|destroy| node2[Comment]
+    node2 -->|reactions|destroy| node3[Reaction]
+    node1 -->|likes|delete_all| node4[Like]
+    User -->|profile|destroy| node5[Profile]
+    User -->|notifications|destroy_async| node6[Notification]
+```
+
+### JSON Format
+
+For programmatic processing:
+
+```json
+{
+  "model": "User",
+  "children": [
+    {
+      "model": "Post",
+      "association": "posts",
+      "type": "has_many",
+      "dependent": "destroy",
+      "children": [
+        {
+          "model": "Comment",
+          "association": "comments",
+          "type": "has_many",
+          "dependent": "destroy"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### DOT Format (Graphviz)
+
+Generate PNG/SVG/PDF diagrams:
+
+```bash
+User.blast_radius(format: :dot) # => DOT format output
+# Save and convert:
+# dot -Tpng output.dot -o diagram.png
+```
+
+### HTML Format (Interactive ER Diagram)
+
+The HTML formatter generates a professional, interactive Entity-Relationship diagram with cascade deletion heatmap:
+
+```ruby
+# Generate interactive HTML
+html = User.blast_radius(format: :html)
+File.write('blast_radius.html', html)
+
+# Open in browser to see:
+# - Full ER diagram of all models
+# - Click any model to see cascade deletion impact
+# - Color-coded heatmap (red → orange → yellow by depth)
+# - Multiple layout algorithms (Force, Tree)
+# - Zoom, pan, and export capabilities
+```
+
+Core Features:
+- Heatmap Visualization: Click on any table to see which other tables will be affected when deleting records
+- Depth-Based Coloring:
+  - 🔴 Red: Directly deleted (depth 1)
+  - 🟠 Orange: Indirectly deleted (depth 2)
+  - 🟡 Yellow: Further cascades (depth 3+)
+  - ⬜ Gray: Unaffected tables
+
+Layout Algorithms:
+- ⚡ Force: Physics-based automatic layout (default)
+- 🌳 Tree: Hierarchical top-down view from selected model
+
+Interaction:
+- Mouse Wheel: Zoom in/out
+- Drag Background: Pan across the graph
+- Click Node: Select and see cascade impact
+- Hover: Tooltips with model and association details
+- Fit to Screen: Auto-zoom to show all nodes
+
+Export:
+- SVG: Vector format for editing
+- PNG: Raster format for presentations
+
+Keyboard Shortcuts:
+- `Escape`: Reset selection
+- `F`: Fit to screen
+- `+/-`: Zoom in/out
+
+Technical:
+- No External Dependencies: Completely self-contained HTML file
+- Dark Mode: Automatically adapts to OS preference
+- Responsive Design: Works on desktop and mobile
+- Console Access: `window.blastRadiusGraph` for programmatic control
+
+See the [`examples/`](./examples/) directory for complete output samples.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+## Requirements
+
+- Ruby >= 3.0.0
+- Rails >= 6.1 (ActiveRecord)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.

data/lib/blast_radius/active_record_extension.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module BlastRadius
+  module ActiveRecordExtension
+    module ClassMethods
+      # Analyze the blast radius for this model class
+      #
+      # @param options [Hash] options
+      #   - :format [Symbol] output format (:text, :mermaid, :json, :dot, :html)
+      #   - :max_depth [Integer] maximum depth
+      #   - :include_nullify [Boolean] include nullify associations
+      #   - :include_restrict [Boolean] include restrict associations
+      # @return [String] formatted dependency tree
+      def blast_radius(options = {})
+        format = options.delete(:format) || BlastRadius.configuration.default_format
+        tree = BlastRadius.analyze(self, options)
+
+        formatter = formatter_for(format)
+        formatter.format(tree)
+      end
+
+      private
+
+      def formatter_for(format)
+        case format
+        when :text
+          BlastRadius::Formatters::TextFormatter.new
+        when :mermaid
+          BlastRadius::Formatters::MermaidFormatter.new
+        when :json
+          BlastRadius::Formatters::JsonFormatter.new
+        when :dot
+          BlastRadius::Formatters::DotFormatter.new
+        when :html
+          BlastRadius::Formatters::HtmlFormatter.new
+        else
+          raise ArgumentError, "Unknown format: #{format}"
+        end
+      end
+    end
+
+    module InstanceMethods
+      # Calculate the blast radius impact for this specific record
+      #
+      # @param options [Hash] options (same as ImpactCalculator#calculate)
+      # @return [Hash] hash of model names to record counts
+      def blast_radius_impact(options = {})
+        calculator = BlastRadius::ImpactCalculator.new
+        calculator.calculate(self, options)
+      end
+
+      # Perform a dry run to see what would be deleted
+      #
+      # @param options [Hash] options (same as ImpactCalculator#dry_run)
+      # @return [Hash] detailed impact information
+      def blast_radius_dry_run(options = {})
+        calculator = BlastRadius::ImpactCalculator.new
+        calculator.dry_run(self, options)
+      end
+    end
+  end
+end

data/lib/blast_radius/analyzer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module BlastRadius
+  class Analyzer
+    # Analyze model associations and extract those with dependent options
+    #
+    # @param model_class [Class] ActiveRecord model class
+    # @return [Array<Hash>] array of association information
+    #   - :name [Symbol] association name
+    #   - :type [Symbol] :has_many, :has_one, :belongs_to
+    #   - :dependent [Symbol] :destroy, :delete_all, etc.
+    #   - :class_name [String] associated model name
+    #   - :through [Symbol, nil] through association name if applicable
+    def analyze(model_class)
+      return [] unless valid_model?(model_class)
+
+      associations = []
+
+      model_class.reflect_on_all_associations.each do |reflection|
+        next unless has_dependent_option?(reflection)
+
+        associations << build_association_info(reflection)
+      end
+
+      associations
+    end
+
+    # Get all models in Rails application
+    # @return [Array<Class>] array of ActiveRecord model classes
+    def all_models
+      if defined?(Rails)
+        Rails.application.eager_load!
+        ApplicationRecord.descendants
+      else
+        []
+      end
+    end
+
+    private
+
+    def valid_model?(model_class)
+      model_class.is_a?(Class) && model_class < ActiveRecord::Base
+    end
+
+    def has_dependent_option?(reflection)
+      reflection.options[:dependent].present?
+    end
+
+    def build_association_info(reflection)
+      {
+        name: reflection.name,
+        type: reflection.macro,
+        dependent: reflection.options[:dependent],
+        class_name: reflection.class_name,
+        through: reflection.options[:through],
+        polymorphic: reflection.options[:polymorphic] || false
+      }
+    end
+  end
+end

data/lib/blast_radius/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module BlastRadius
+  class Configuration
+    attr_accessor :max_depth,
+                  :default_format,
+                  :include_nullify,
+                  :include_restrict,
+                  :exclude_models,
+                  :enable_web_ui,
+                  :colorize,
+                  :colors
+
+    def initialize
+      @max_depth = 10
+      @default_format = :text
+      @include_nullify = false
+      @include_restrict = false
+      @exclude_models = [/^HABTM_/, /^ActiveStorage::/]
+      @enable_web_ui = false
+      @colorize = true
+      @colors = {
+        destroy: :red,
+        delete_all: :yellow,
+        destroy_async: :magenta,
+        nullify: :blue,
+        restrict: :gray
+      }
+    end
+  end
+end

data/lib/blast_radius/dependency_tree.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module BlastRadius
+  class DependencyTree
+    def initialize(configuration = nil)
+      @configuration = configuration || BlastRadius.configuration
+      @analyzer = Analyzer.new
+    end
+
+    # Build dependency tree from a root model
+    #
+    # @param root_model [Class] root ActiveRecord model class
+    # @param options [Hash] options
+    #   - :max_depth [Integer] maximum depth (default: from configuration)
+    #   - :include_nullify [Boolean] include nullify associations (default: from configuration)
+    #   - :include_restrict [Boolean] include restrict associations (default: from configuration)
+    # @return [Node] root node of dependency tree
+    def build(root_model, options = {})
+      max_depth = options[:max_depth] || @configuration.max_depth
+      include_nullify = options.fetch(:include_nullify, @configuration.include_nullify)
+      include_restrict = options.fetch(:include_restrict, @configuration.include_restrict)
+
+      root_node = Node.new(root_model, depth: 0)
+      build_tree(root_node, max_depth, include_nullify, include_restrict)
+      root_node
+    end
+
+    private
+
+    def build_tree(node, max_depth, include_nullify, include_restrict)
+      return if node.depth >= max_depth
+      return if node.circular_reference?
+
+      associations = @analyzer.analyze(node.model_class)
+      associations = filter_associations(associations, include_nullify, include_restrict)
+
+      associations.each do |assoc|
+        next if excluded_model?(assoc[:class_name])
+        next if assoc[:polymorphic] # Skip polymorphic associations for now
+
+        begin
+          associated_class = assoc[:class_name].constantize
+        rescue NameError
+          # Skip if class doesn't exist
+          next
+        end
+
+        child_node = Node.new(
+          associated_class,
+          association_name: assoc[:name],
+          dependent_type: assoc[:dependent],
+          association_type: assoc[:type],
+          through: assoc[:through],
+          polymorphic: assoc[:polymorphic],
+          parent: node,
+          depth: node.depth + 1
+        )
+
+        node.add_child(child_node)
+        build_tree(child_node, max_depth, include_nullify, include_restrict)
+      end
+    end
+
+    def filter_associations(associations, include_nullify, include_restrict)
+      associations.select do |assoc|
+        dependent = assoc[:dependent]
+
+        case dependent
+        when :destroy, :delete_all, :destroy_async
+          true
+        when :nullify
+          include_nullify
+        when :restrict_with_exception, :restrict_with_error
+          include_restrict
+        else
+          false
+        end
+      end
+    end
+
+    def excluded_model?(model_name)
+      @configuration.exclude_models.any? do |pattern|
+        pattern.is_a?(Regexp) ? pattern.match?(model_name) : pattern == model_name
+      end
+    end
+  end
+end

data/lib/blast_radius/formatters/base.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module BlastRadius
+  module Formatters
+    class Base
+      def initialize(configuration = nil)
+        @configuration = configuration || BlastRadius.configuration
+      end
+
+      # Format the dependency tree
+      # @param root_node [Node] root node of dependency tree
+      # @return [String] formatted output
+      def format(root_node)
+        raise NotImplementedError, 'Subclasses must implement #format'
+      end
+
+      protected
+
+      def colorize?
+        @configuration.colorize
+      end
+
+      def color_for(dependent_type)
+        @configuration.colors[dependent_type] || :default
+      end
+    end
+  end
+end

data/lib/blast_radius/formatters/dot_formatter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module BlastRadius
+  module Formatters
+    class DotFormatter < Base
+      # Format dependency tree as Graphviz DOT format
+      # @param root_node [Node] root node of dependency tree
+      # @return [String] DOT format representation
+      def format(root_node)
+        @edges = []
+        @nodes = Set.new
+
+        # Collect all nodes and edges
+        collect_nodes_and_edges(root_node)
+
+        # Build DOT output
+        lines = [
+          'digraph blast_radius {',
+          '  rankdir=LR;',
+          '  node [shape=box];',
+          ''
+        ]
+
+        # Add nodes
+        @nodes.each do |node_name|
+          lines << %(  "#{node_name}";)
+        end
+
+        lines << ''
+
+        # Add edges
+        @edges.each do |edge|
+          lines << edge
+        end
+
+        lines << '}'
+        lines.join("\n")
+      end
+
+      private
+
+      def collect_nodes_and_edges(node)
+        @nodes.add(node.model_name)
+
+        node.children.each do |child|
+          @nodes.add(child.model_name)
+
+          # Create edge with label
+          label = "#{child.association_name}\\n#{child.dependent_type}"
+          edge = %(  "#{node.model_name}" -> "#{child.model_name}" [label="#{label}"];)
+          @edges << edge
+
+          # Recursively process children
+          collect_nodes_and_edges(child) unless child.children.empty?
+        end
+      end
+    end
+  end
+end