Merge pull request #11 from alpaca-tc/update-readme

Update README

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<String>, Set<String>, 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<String>, 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

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']))
   )
 )
 

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