DiverDown

DiverDown is a tool designed to dynamically analyze application dependencies and generate a comprehensive dependency map. It is particularly useful for analyzing Ruby applications, aiding significantly in large-scale refactoring projects or transitions towards a modular monolith architecture.

• Dependency Mapping: Analyze and generate an application dependencies.
• Module Categorization: Organizes file-by-file associations into specific groups, facilitating deeper modular monolith architectural analysis and understanding.

Add this line to your application's Gemfile:

gem 'diver_down'

And then execute:

$ bundle

Or install it yourself as:

$ gem install diver_down

diver_down is mainly divided into the DiverDown::Trace for dynamic analysing ruby code, and the DiverDown::Web for viewing the result on the browser.

The DiverDown::Trace module analyzes the execution of Ruby code and outputs the results as DiverDown::Definition objects.

tracer = DiverDown::Trace::Tracer.new

# Analyze the processing in the block.
definition = tracer.trace do
  # do something
end

# Or, analyze the processing without block.
session = tracer.new_session

session.start
# do something
session.stop

definition = session.definition

# Analysis results can be titled.
# And if specified the `definition_group`, the results can be grouped when viewed in a browser.
tracer = DiverDown::Trace::Tracer.new

tracer.trace(title: 'title', definition_group: 'group name') do
  # do something
end

Options

When analyzing user applications, it is recommended to specify the option.

Example

# Your rails application paths
application_paths = [
  *Dir['app/**/*.rb'], 
  *Dir['lib/**/*.rb'],
].map { File.expand_path(_1) }

ignored_application_paths = [
  'app/models/application_record.rb',
].map { File.expand_path(_1) }

module_set = DiverDown::Trace::ModuleSet.new(modules: modules - ignored_modules)

filter_method_id_path = ->(path) { path.remove("#{Rails.root}/") }

tracer = DiverDown::Trace::Tracer.new(
  caller_paths: application_paths,
  module_set: {
    paths: (application_paths - ignored_application_paths)
  },
  filter_method_id_path:
)

definition = tracer.trace do
  # do something
end

The analysis results are intended to be saved to a specific directory in either .json or .yaml format. These files are compatible with DiverDown::Web, which can read and display the results.

dir = 'tmp/diver_down'

definition = tracer.trace do
  # do something
end

File.write(File.join(dir, "#{definition.title}.json"), definition.to_h.to_json)
File.write(File.join(dir, "#{definition.title}.yaml"), definition.to_h.to_yaml)

View the analysis results in a browser.

This gem is specifically designed to analyze large applications with a modular monolithic architecture. It allows users to categorize each analyzed file into specified modules directly through the web interface.

• --definition-dir Specifies the directory where the analysis results are stored.
• --metadata Designates a path to save the results that include details on which module each file belongs to. If this option is not specified, the results will be temporarily stored in a default temporary file.

bundle exec diver_down_web --definition-dir tmp/diver_down --metadata tmp/metadata.yml
open http://localhost:8080

1. Checking out the repo git clone https://github.com/alpaca-tc/diver_down
2. Install dependencies.

• Install pnpm
• Install Ruby
• pnpm install
• bundle install

1. Run the tests/static code analyzer.

• Ruby: bundle exec rspec, bundle exec rubocop
• TypeScript: pnpm run test, pnpm run lint

If you want to develop DiverDown::Web locally, set up a server for development.

# Start server for frontend
$ pnpm install
$ pnpm run dev

# Start server for backend
$ bundle install
$ DIVER_DOWN_DIR=/path/to/definitions_dir DIVER_DOWN_METADATA=/path/to/metadata.yml bundle exec puma

Bug reports and pull requests are welcome on GitHub at https://github.com/alpaca-tc/diver_down. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the DiverDown project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.