diff --git a/README.md b/README.md index cd04946..eb3938b 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ `divertdown` is a tool that dynamically analyzes application dependencies and creates a dependency map. This tool was created to analyze Ruby applications for use in large-scale refactoring such as moduler monolith. -The results of the analysis can be viewed in a browser, allowing you to deepen your architectural considerations while viewing the results. +The results of the analysis can be viewed the dependency map graph, and and since the file-by-file association can be categorized into specific groups, you can deepen your architectural consideration. ## Installation @@ -19,44 +19,104 @@ And then execute: Or install it yourself as: - $ gem install active_record_bitmask + $ gem install diver_down ## Usage +`divert_down` is mainly divided into the `DiverDown::Trace` for dynamic analysing ruby code, and the `DiverDown::Web` for viewing the result on the browser. + +### `DiverDown::Trace` + +Analyzes the processing of ruby code and outputs the analysis results as `DiverDown::Definition`. + +```ruby +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 +``` + +```ruby +# 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 +``` + +The analysis results should be output to a specific directory. +Files saved in `.msgpack`, `.json`, or `.yaml` can be read by `DiverDown::Web`. + ```ruby -tracer = DiverDown::Trace::Tracer.new( - # @param target_files [Array, Set, nil] If nil, all files are targeted but slow. - # List of target files to be analyzed. Usually, gem and other files are excluded and specified. - target_files: Dir["app/**/*.rb"], - # @param module_set [Array, DiverDown::Trace::ModuleSet] List of modules to be analyzed. - # When analyzing a your Rails application, set all classes/modules under app/. - module_set: [ - 'User', - 'Item', - 'Order', - ... - ], - # @param filter_method_id_path [#call, nil] The analysis result outputs the absolute path of the caller. To convert to a relative path, define the conversion logic manually. - filter_method_id_path: -> (path) { path.remove(Rails.root.to_s) }, - # @param module_finder [#call, nil] Specify the logic to determine which module the source found. diver_down promote moduler monolithization, so such an option exists. - module_finder: -> (source) { 'OrderSystem' if source.source == 'Order' }, -) +dir = 'tmp/diver_down' + +definition = tracer.trace do + # do something +end + +File.binwrite(File.join(dir, "#{definition.title}.msgpack"), definition.to_msgpack) +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) +``` + +**Options** + +TODO + +### `DiverDown::Web` + +View the analysis results in a browser. + +This gem is designed to consider large application with a modular monolithic architecture. +Each file in the analysis can be specified to belong to a module you specify on the browser. + +- `--definition-dir` specifies the directory where the analysis results are stored. +- `--module-store-path` will store the results specifying which module each file belongs to. If not specified, the specified results are stored in tempfile. + +```sh +bundle exec diver_down_web --definition-dir tmp/diver_down --module-store-path tmp/module_store.yml +open http://localhost:8080 ``` ## Development -After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests. +1. Checking out the repo `git clone https://github.com/alpaca-tc/diver_down` +1. Install dependencies. + - [Install pnpm](https://pnpm.io/installation) + - [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) + - `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` ### Development DiverDown::Web +If you want to develop `DiverDown::Web` locally, set up a server for development. + ``` -# Start vite +# Start server for frontend $ pnpm install $ pnpm run dev -# Start rack +# Start server for backend $ bundle install -$ DIVERDOWN_DIR=/path/to/definitions_dir bundle exec puma +# DIVER_DOWN_DIR specifies the directory where the analysis results are stored. +# DIVER_DOWN_MODULE_STORE specifies a yaml file that defines which module the file belongs to, but this file is newly created, so it works even if the file does not exist. +$ DIVER_DOWN_DIR=/path/to/definitions_dir DIVER_DOWN_MODULE_STORE=/path/to/module_store.yml bundle exec puma ``` ## Contributing diff --git a/exe/diver_down_web b/exe/diver_down_web index 2dca201..1601484 100755 --- a/exe/diver_down_web +++ b/exe/diver_down_web @@ -36,17 +36,10 @@ unless options[:definition_dir] exit 1 end -unless options[:module_store] - puts 'Missing --module-store' - puts - puts option_parser.help - exit 1 -end - app = Rack::JSONBodyParser.new( DiverDown::Web.new( definition_dir: options.fetch(:definition_dir), - module_store: DiverDown::Web::ModuleStore.new(options[:module_store]) + module_store: DiverDown::Web::ModuleStore.new(options[:module_store] || Tempfile.new(['module_store', '.yaml'])) ) ) diff --git a/spec/diver_down/trace/tracer_spec.rb b/spec/diver_down/trace/tracer_spec.rb index 91783c7..7303638 100644 --- a/spec/diver_down/trace/tracer_spec.rb +++ b/spec/diver_down/trace/tracer_spec.rb @@ -55,7 +55,11 @@ def self.call stub_const('A', klass_a) stub_const('B', klass_b) - tracer = DiverDown::Trace::Tracer.new + tracer = DiverDown::Trace::Tracer.new( + module_set: { + modules: [A, B], + } + ) definition_1 = tracer.trace(title: 'title') do A.call_b