rails_model_viz 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d7286f0c8faf1b1a2110ddd83d629e60da4c30066e4628a9f4c7ef225735f63
+  data.tar.gz: 9a523bf923177660563d8fb3ae3bdaebba962a3e8bd34f845eda598066659d92
+SHA512:
+  metadata.gz: 9681fb9367802103df78dcc80e273644a5b900a55cbaf2f9aee2764589c0240e2382b54d01c1fe459f823ca6b55729eb21f5c210af8ae065fca81091bce733c3
+  data.tar.gz: 69da66c4d72f8a891067b5eb1632e6984e7fc2027fd9ea4e478b8d51cd7c71fff5db3e51e128547c12c0397bf7d2fcccda2932afa84adf96c1b7d12fbfc3b995

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Seiya Takahashi
+
+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,61 @@
+# RailsModelViz
+
+RailsModelViz is a Rails engine (and optional rake task) that visualizes your ActiveRecord models and associations using Mermaid.js. It automatically generates diagrams of your models’relationships (and optionally columns) in a clear and interactive format.
+
+## Installation
+
+1. Add this line to your application’s Gemfile:
+
+```ruby
+gem 'rails_model_viz'
+```
+
+2. Then execute:
+
+```sh
+bundle install
+```
+
+## Usage
+
+1. Mount the Rails Engine
+
+In your main application’s config/routes.rb, mount the engine so you can access the visualization:
+
+```ruby
+Rails.application.routes.draw do
+
+  # Other routes...
+  if Rails.env.development?
+    mount RailsModelViz::Engine, at: '/rails_model_viz'
+  end
+end
+```
+
+After this, start your Rails server and navigate to:
+
+http://localhost:3000/rails_model_viz
+
+You should see a Mermaid-based diagram of your models’ relationships.
+
+![relations](docs/img/relations.png)
+
+2. Toggle Columns View
+
+By default, RailsModelViz may show only associations. If you’d like to view columns as well, you can pass a mode=columns parameter. For example:
+
+http://localhost:3000/rails_model_viz?mode=columns
+
+This will enrich each entity in the diagram with column names (and types).
+
+![columns](docs/img/columns.png)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/PeterTakahashi/rails_model_viz. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.
+
+Feel free to add more sections (e.g., advanced configuration, known issues, screenshots, etc.) as you see fit!

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/controllers/rails_model_viz/graph_controller.rb

@@ -0,0 +1,120 @@
+module RailsModelViz
+  class GraphController < ActionController::Base
+    def index
+      Rails.application.eager_load!
+
+      @mode = params[:mode] || 'relations'
+      models = ApplicationRecord.descendants
+
+      # Generate text for Mermaid's ER diagram
+      @mermaid_text = build_mermaid_text(models, @mode)
+    end
+
+    private
+
+    def build_mermaid_text(models, mode)
+      graph_data = build_graph_data(models, mode)
+      to_mermaid_er_diagram(graph_data)
+    end
+
+    def build_graph_data(models, mode)
+      # For erDiagram, we assemble the list of columns each model has
+      # and information about their associations
+      nodes = []
+      edges = []
+
+      models.each do |model|
+        # Retrieve columns only when mode=='columns' to include details
+        columns = []
+        if mode == 'columns'
+          model.load_schema
+          columns = model.columns.map { |col| [col.name, col.type.to_s] }
+        end
+
+        # Node (table) information
+        nodes << {
+          id: model.name,   # e.g., "User"
+          columns: columns  # e.g., [ ["id","integer"], ["name","string"], ... ]
+        }
+
+        # Gather associations as edges
+        model.reflect_on_all_associations.each do |assoc|
+          # Polymorphic associations do not have a single definite class,
+          # so we treat them separately
+          if assoc.polymorphic?
+            edges << { from: model.name, to: "Polymorphic(#{assoc.name})", type: assoc.macro.to_s }
+          else
+            edges << { from: model.name, to: assoc.klass.name, type: assoc.macro.to_s }
+          end
+        end
+      end
+
+      { nodes: nodes, edges: edges }
+    end
+
+    # ===========================================================================
+    # Build a Mermaid erDiagram notation string
+    # https://mermaid.js.org/syntax/entityRelationshipDiagram.html
+    #
+    #   erDiagram
+    #     TABLE_NAME {
+    #       column_name data_type
+    #       column_name data_type
+    #     }
+    #
+    #     TABLE_NAME ||--|{ OTHER_TABLE : "relationship"
+    # ===========================================================================
+    def to_mermaid_er_diagram(graph_data)
+      mermaid = "erDiagram\n"
+
+      # (1) Define each table (entity)
+      graph_data[:nodes].each do |node|
+        mermaid << "  #{node[:id]} {\n"
+
+        # Output field definitions only if node[:columns] is present
+        node[:columns].each do |(col_name, col_type)|
+          # For example: "id integer", "name string", etc.
+          mermaid << "    #{col_name} #{col_type}\n"
+        end
+
+        mermaid << "  }\n\n"
+      end
+
+      # (2) Define relationships
+      #    ER notation like "||--||" indicates multiplicity (1, n, etc.)
+      graph_data[:edges].each do |edge|
+        from = edge[:from]
+        to   = edge[:to]
+        rel_type = edge[:type]  # e.g. "has_many", "belongs_to"
+
+        # Convert association type to an ER diagram multiplicity symbol
+        cardinality = map_assoc_to_er_cardinality(rel_type)
+
+        # Example: User ||--|{ Post : "has_many"
+        mermaid << "  #{from} #{cardinality} #{to} : \"#{rel_type}\"\n"
+      end
+
+      mermaid
+    end
+
+    # Map association types to ER diagram cardinality symbols:
+    #  - belongs_to → 1-to-many from the other side, often "||--|{"
+    #  - has_many   → 1-to-many
+    #  - has_one    → 1-to-1
+    #  - has_and_belongs_to_many → many-to-many
+    def map_assoc_to_er_cardinality(rel_type)
+      case rel_type.to_s
+      when "belongs_to"
+        "||--|{"
+      when "has_many"
+        "||--|{"
+      when "has_one"
+        "||--||"
+      when "has_and_belongs_to_many"
+        "}o--o{"
+      else
+        "||--||"  # Default to 1-to-1
+      end
+    end
+  end
+end

data/app/views/rails_model_viz/graph/index.html.erb

@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Rails Model Viz (Mermaid)</title>
+  <!-- Example using Mermaid's CDN -->
+  <script src="https://unpkg.com/mermaid/dist/mermaid.min.js"></script>
+
+  <style>
+    /* Header design */
+    h1 {
+      display: flex;
+      justify-content: space-between; /* Place items at both ends horizontally */
+      align-items: center;
+      background: #f5f5f5;
+      padding: 10px 15px;
+      margin: 0 0 20px 0; /* Add bottom spacing */
+      border-bottom: 2px solid #ccc;
+      font-family: sans-serif;
+    }
+
+    /* Toggle button style */
+    .toggle-button {
+      text-decoration: none;
+      color: #333;
+      background: #e0e0e0;
+      padding: 6px 10px;
+      border-radius: 4px;
+      font-size: 14px;
+      border: 1px solid #ccc;
+      transition: background 0.2s;
+    }
+
+    .toggle-button:hover {
+      background: #ccc;
+    }
+
+    /* Optional additional styling for the Mermaid container */
+    .mermaid {
+      margin: 0 20px;
+    }
+  </style>
+</head>
+<body>
+  <!-- Title + Toggle button -->
+  <h1>
+    Rails Model Visualization (Mermaid)
+
+    <!-- Display links to switch modes -->
+    <% if params[:mode] == 'columns' %>
+      <!-- Currently in "columns" mode: switch to "relations only" -->
+      <a class="toggle-button" href="<%= graph_index_path(mode: 'relations') %>">
+        Show relations only
+      </a>
+    <% else %>
+      <!-- Currently in "relations only" mode: switch to "columns" -->
+      <a class="toggle-button" href="<%= graph_index_path(mode: 'columns') %>">
+        Show columns
+      </a>
+    <% end %>
+  </h1>
+
+  <!-- Mermaid rendering area -->
+  <!-- Insert the @mermaid_text generated by the controller -->
+  <div class="mermaid">
+    <%= @mermaid_text %>
+  </div>
+
+  <!-- Mermaid initialization script -->
+  <script>
+    mermaid.initialize({ startOnLoad: true });
+  </script>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,4 @@
+RailsModelViz::Engine.routes.draw do
+  root to: "graph#index"
+  resources :graph, only: [:index]
+end

data/lib/rails_model_viz/engine.rb

@@ -0,0 +1,5 @@
+module RailsModelViz
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsModelViz
+  end
+end

data/lib/rails_model_viz/version.rb

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

data/lib/rails_model_viz.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "rails_model_viz/version"
+require "rails_model_viz/engine"
+
+module RailsModelViz
+  class Error < StandardError; end
+end

data/sig/rails_model_viz.rbs

@@ -0,0 +1,4 @@
+module RailsModelViz
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: rails_model_viz
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Peter Takahashi
+- Seiya Takahashi
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-02-22 00:00:00.000000000 Z
+dependencies: []
+description: "**Rails Model Viz** is a development tool that automatically visualizes
+  your Rails application's models, \nassociations, and (optionally) column details
+  using Mermaid.js. This gem provides both a command-line task \nand a Rails Engine
+  interface, allowing you to view interactive entity-relationship diagrams (ER diagrams)
+  \ndirectly in your browser. It helps developers quickly understand, explore, and
+  document the structure of \ntheir ActiveRecord models.\n"
+email:
+- seiya4@icloud.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- " CHANGELOG.md"
+- ".rspec"
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/rails_model_viz/graph_controller.rb
+- app/views/rails_model_viz/graph/index.html.erb
+- config/routes.rb
+- docs/img/columns.png
+- docs/img/relations.png
+- lib/rails_model_viz.rb
+- lib/rails_model_viz/engine.rb
+- lib/rails_model_viz/version.rb
+- sig/rails_model_viz.rbs
+homepage: https://github.com/PeterTakahashi/rails_model_viz
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/PeterTakahashi/rails_model_viz
+  source_code_uri: https://github.com/PeterTakahashi/rails_model_viz
+  changelog_uri: https://github.com/PeterTakahashi/rails_model_viz/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+- app
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: A Rails engine that visualizes your ActiveRecord models and associations
+  using Mermaid.js.
+test_files: []