emad-elsaid / rubrowser Goto Github PK

a ruby code dependency graph interactive visualizer

License: MIT License

Ruby 38.66% CSS 2.82% JavaScript 50.88% HTML 7.64%

rubrowser's Introduction

Rubrowser (Ruby Browser)

a visualizer for ruby code (rails or otherwise), it analyze your code and extract the modules definitions and used classes/modules and render all these information as a directed force graph using D3.

Note:

Starting from version 2.0.0 the project is no longer an http server, it generates one HTML file that is self-contained, data and script and html in one file, so you can generate it in your CI build and publish it as part of your documentation

this project is so small that the visualization looks like so

the idea is that the project opens every .rb file and parse it with parser gem then list all modules and classes definitions, and all constants that are listed inside this module/class and link them together.

Here are some output examples

Gem	Visualization
rack-1.6.4/lib
actioncable-5.0.0/lib
railties-5.0.0/lib

there are couple things you need to keep in mind:

if your file doesn't have a valid ruby syntax it won't be parsed and will print warning.
if you reference a class that is not defined in your project it won't be in the graph, we only display the graph of classes/modules you defined
it statically analyze the code so meta programming is out of question in here
rails associations are meta programming so forget it 😄

Installation

gem install rubrowser

Usage

Usage: rubrowser [options] [file] ...
    -o, --output=FILE                output file page, if not specified output will be written to stdout
    -l, --layout=FILE                layout file to apply on the resulting graph
    -s, --server=SERVER:PORT         rubrowser server for execution monitoring
    -T, --no-toolbox                 Don't display toolbox on the page
    -j, --json                       Do export data as JSON instead of HTML
    -v, --version                    Print Rubrowser version
    -h, --help                       Prints this help

if you run it without any options

rubrowser

it'll analyze the current directory and print out an HTML file, so you can write it to a file, and open it in your browser

rubrowser > output.html

Monitoring your application execution

Add rubrowser to your ruby project Gemfile

gem 'rubrowser'

Add the following code before your application runs, if it's a rails project this should be an initializer

Rubrowser::Monitor.run(path: Rails.root.to_s, port: 8080)

path is your code path, and port is the execution websocket server port, the server will open that port and announce any execution happens to the code inside your project directory.

now generate a rubrowser HTML output that connect to your server

rubrowser -slocalhost:8080 > output.html

Using a saved layout

When you move classes/modules in the graph to fix them in one place, then you refresh the page, you'll reset the graph again.

for that reason there is a button to download the current graph state as json file (fixed nodes positions), when you generate the graph again you can pass that file to rubrowser to embed it inside the output HTML file.

rubrowser -l layout.json

I recommend putting that file in your project and name it .rubrowser in that case it'll be easy to use it whenever you generate the graph.

rubrowser -l .rubrowser

So that in the future probably rubrowser can pick the file automatically, if you follow that naming, your project will be ready in that case.

Export data for use in external tools

rubrowser -j|jq '.'

Features

trace your execution in realtime on the graph
interactive graph, you can pull any node to fix it to some position
to release node double click on it
zoom and pan with mouse or touch pad
highlight node and all related nodes, it'll make it easier for you to see what depends and dependencies of certain class
highlight nodes by names or file path
ignore node by name, or file path
ignore nodes of certain type (modules/classes)
hide namespaces
hide relations
change graph appearance (collision radius)
stop animation immediately
fix all nodes in position or release all fixed nodes
Module/class circle size on the graph will be relative to module number of lines in your code
cyclical dependencies are marked in red
after you move nodes around, you can download the layout as a file, then provide it when generating the graph file again with -l file.json it will embed the layout in the file and the graph will have the same layout by default.

Why?

Because i didn't find a good visualization tool to make me understand ruby projects when I join a new one.

it's great when you want to get into an open source project and visualize the structure to know where to work and the relations between modules/classes.

rubrowser's People

Contributors

Stargazers

Watchers

rubrowser's Issues

uninitialized constant Puma::HAS_SSL (NameError)

puma is installed but it requires ssl params , but how to use it wothout ssl locally?

rubrowser -slocalhost:8080 > output.html                                         
Traceback (most recent call last):
	29: from /Users/serj/.rvm/gems/ruby-2.6.4/bin/ruby_executable_hooks:24:in `<main>'
	28: from /Users/serj/.rvm/gems/ruby-2.6.4/bin/ruby_executable_hooks:24:in `eval'
	27: from /Users/serj/.rvm/gems/ruby-2.6.4/bin/rubrowser:23:in `<main>'
	26: from /Users/serj/.rvm/gems/ruby-2.6.4/bin/rubrowser:23:in `load'
	25: from /Users/serj/.rvm/gems/ruby-2.6.4/gems/rubrowser-2.9.1/bin/rubrowser:5:in `<top (required)>'
	24: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:54:in `require'
	23: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:54:in `require'
	22: from /Users/serj/.rvm/gems/ruby-2.6.4/gems/rubrowser-2.9.1/lib/rubrowser.rb:2:in `<top (required)>'
	21: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:54:in `require'
	20: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:54:in `require'
	19: from /Users/serj/.rvm/gems/ruby-2.6.4/gems/rubrowser-2.9.1/lib/rubrowser/monitor.rb:2:in `<top (required)>'
	18: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:54:in `require'
	17: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:54:in `require'
	16: from /Users/serj/.rvm/gems/ruby-2.6.4/gems/rubrowser-2.9.1/lib/rubrowser/server.rb:4:in `<top (required)>'
	15: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:65:in `require'
	14: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:65:in `require'
	13: from /Users/serj/.rvm/gems/ruby-2.6.4/gems/puma-5.2.2/lib/puma/launcher.rb:5:in `<top (required)>'
	12: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:65:in `require'
	11: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:65:in `require'
	10: from /Users/serj/.rvm/gems/ruby-2.6.4/gems/puma-5.2.2/lib/puma/cluster.rb:3:in `<top (required)>'
	 9: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:65:in `require'
	 8: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:65:in `require'
	 7: from /Users/serj/.rvm/gems/ruby-2.6.4/gems/puma-5.2.2/lib/puma/runner.rb:3:in `<top (required)>'
	 6: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:65:in `require'
	 5: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:65:in `require'
	 4: from /Users/serj/.rvm/gems/ruby-2.6.4/gems/puma-5.2.2/lib/puma/server.rb:11:in `<top (required)>'
	 3: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:65:in `require'
	 2: from /Users/serj/.rvm/rubies/ruby-2.6.4/lib/ruby/site_ruby/2.6.0/rubygems/core_ext/kernel_require.rb:65:in `require'
	 1: from /Users/serj/.rvm/gems/ruby-2.6.4/gems/puma-5.2.2/lib/puma/binder.rb:10:in `<top (required)>'
/Users/serj/.rvm/gems/ruby-2.6.4/gems/puma-5.2.2/lib/puma/binder.rb:12:in `<module:Puma>': uninitialized constant Puma::HAS_SSL (NameError)

yard graph vs rubrowser

Hi!
Thanks for the nice project!
Look at yard graph for additional inspiration, it's a pretty standard tool for class diagram and dependency visualizations for Ruby projects.

syntax error running 'rubrowser'

When I run rubrowser, this happens:

moadadmins-MacBook-Pro:directory userFolder$ rubrowser
/Users/userFolder/.rvm/rubies/ruby-2.2.6/lib/ruby/site_ruby/2.2.0/rubygems/core_ext/kernel_require.rb:54:in `require': /Users/userFolder/.rvm/gems/ruby-2.2.6@project-mapper/gems/litecable-0.5.0/lib/lite_cable/anycable.rb:29: syntax error, unexpected '.' (SyntaxError)
subscriptions&.each { |id| @subscriptions.add(id, false) }

Is there a way to generate dependencies around single file

Hi Team,

Is there a way to generate dependencies around single file?

When I try something like rubrowser /Users/code-name/server/app/controllers/portal/test_controller.rb> output.html
It creates a blank graph.

needs dependencies optimisation

Parsing documentation for rack-protection-1.5.3
Installing ri documentation for rack-protection-1.5.3
Parsing documentation for sinatra-1.4.7
Installing ri documentation for sinatra-1.4.7

Done installing documentation for rack-protection, sinatra, ast, parser, parallel, haml, rubrowser after 273 seconds
7 gems installed

after 273 seconds! =)

is this necessary?

Mark cyclic dependencies red

I hate dependency cycles. I like to get rid of them. I would like to use rubrowser to find them.
So what about an option to mark cyclic dependencies?

Cheers, ellcs

Problems with official website?

Tried to reach http://www.emadelsaid.com/rubrowser but it seems I'm entering a redirect loop. Just wanted to let you know.

Build arcs for Rails associations?

Super cool project- thanks for putting this together! Would you consider building dependencies between Rails models linked by has_many / belongs_to associations? Those are pretty common dependencies that aren't directly referenced by the constant name.

Ignore namespace / file path not working

I've tried all sorts of combinations in the text boxes and nothing has affected the graph.. how are these supposed to work?

Rubrowser only works on unstable versions of Ruby

The stable versions of Ruby available from rbenv are:

$ rbenv install --list
3.0.6
3.1.4
3.2.2
jruby-9.4.5.0
mruby-3.2.0
picoruby-3.0.0
truffleruby-23.1.1
truffleruby+graalvm-23.1.1

Only latest stable releases for each Ruby implementation are shown.
Use 'rbenv install --list-all / -L' to show all local versions.

Attempt 1

$ rbenv global 3.1.2

$ gem install rubrowser
*... Lots of output, not shown ...*

$ rubrowser > rubrowser.html
rubrowser > rubrowser.html
warning: parser/current is loading parser/ruby31, which recognizes 3.1.6-compliant syntax, but you are running 3.1.2.
Please see https://github.com/whitequark/parser#compatibility-with-ruby-mri.

Attempt 2

$ rbenv global 3.2.2

$ gem install rubrowser
*... Lots of output, not shown ...*

$ rubrowser > rubrowser.html
rubrowser > rubrowser.html
warning: parser/current is loading parser/ruby32, which recognizes 3.2.4-compliant syntax, but you are running 3.2.2.
Please see https://github.com/whitequark/parser#compatibility-with-ruby-mri.