deps_grapher 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31d04a84f91bd795f6c19d70a9de853963cd02d298cadb8cceaf68fae288e10e
+  data.tar.gz: 284e8006b5cd05e76e8446ca6732048267ee7e234d13d3320589c7e2bb79b38c
+SHA512:
+  metadata.gz: 261f74611a3ac886afd45c7ec1487dcd4db6bb83ede88f6aadf70b1f338725b989bf546b6f0476cffb35251791ebc426c57ab5e887e2b129a82fe8511b625566
+  data.tar.gz: 752589ecdbc90718919f0fcdeefe18e75aa0cced56532aa7ed01f2bf220e4cfc26f0f79d0b3051d6d4016f9f5893a049518b3fe955eb77157c4acbffaa22aa7f

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [1.0.0] - 2024-03-22
+
+- Initial release

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in deps_grapher.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"
+
+gem "simplecov", require: false, group: :test
+
+gem "webmock", "~> 3.0"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 jk-es335
+
+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,327 @@
+Deps Grapher
+====
+
+A Tool to visualize Ruby class dependencies
+
+## Description
+
+Deps Grapher is intended for a general understanding of class dependencies through static analysis. It uses `parser` gem.
+
+Please note the following:
+
+- Information determined at runtime cannot be analyzed
+- Dependencies of classes and methods that are likely to change dynamically cannot be analyzed
+- Method arguments that are variables cannot be analyzed
+
+Therefore, it may not be accurate and should be used as a reference only.
+
+## Installation
+
+Please add this line to your application's Gemfile:
+
+```ruby
+gem "deps_grapher"
+```
+
+And then run the following command:
+
+```shell
+bundle install
+```
+
+## Usage
+
+### Generate a configuration file
+
+```shell
+cd ${your directory}
+bundle exec deps_grapher init
+```
+
+The following message will be displayed.
+
+```shell
+`${your directory}/graphile.rb` was created.
+Please edit the configuration file.
+Run `bundle exec deps_grapher -c graphile.rb`.
+```
+
+Please try to run the following command.
+
+```shell
+bundle exec deps_grapher -c graphile.rb
+```
+
+The visualized graph will be output to the tmp directory.
+
+Please open the index.html in the graph directory with your browser.
+
+> ${your directory}/tmp/deps_grapher/graph/index.html
+
+### Customize the configuration file for your project
+
+DSL is used to define the configuration file.
+
+The DSL provides the following methods.
+
+- `output_dir` - Specify the output directory where the graph html is output
+- `cache_dir` - Specify the cache directory where the analysis result is stored
+- `plugin_dir` - Specify the plugin directory. Plugins allow you to use customized visualizations and will be loaded by `Configuration#load_plugin!` method.
+- `visualizer` - Specify the default graph type (default: "cy:klay")
+- `ast_processor_policy` - Specify the policy for processing the AST
+  - `include_const` - Specify the constant or regular expression to be included in the analysis
+  - `exclude_const` - Specify the constant or regular expression to be excluded from the analysis
+  - `include_location` - Specify the location or regular expression to be included in the analysis
+  - `exclude_location` - Specify the location or regular expression to be excluded from the analysis
+  - `advanced_const_resolver` - Specify the object that has `call` method to resolve the constant. You can write a custom logic to resolve the constant using ast_node of parser gem. The block should return a string of const name or nil. If return nil, the const name will be resolved by default logic.
+- `layer` - Specify the layer to be displayed in the graph
+  - `name` - Specify the layer name (required)
+  - `visible` - Specify whether the layer is visible (default: true)
+  - `source` - Specify the source directory of the layer (required)
+    - `root` - Specify the root directory of the layer (required)
+    - `include_pattern` - Specify the pattern to include in the analysis (default: nil)
+    - `exclude_pattern` - Specify the pattern to exclude from the analysis (default: nil)
+    - `glob_pattern` - Specify the glob pattern to include in the analysis (default: ["**/*.rb"])
+  - `color` - Specify the color of the layer (required)
+    - `background` - Specify the background color of the node and the edge (required)
+    - `arrow` - Specify the arrow color of the edge (default: same as `background`)
+    - `border` - Specify the border color of the node and the edge (required)
+    - `font` - Specify the font color of the the node and the edge (required)
+- `with_plugin` - Specify the extension plugin directory. Plugins allow you to use customized visualizations.
+
+### Configuration example
+
+```ruby
+# frozen_string_literal: true
+
+# directory settings
+# customize for your project
+output_dir File.expand_path "tmp/deps_grapher/graph"
+cache_dir File.expand_path "tmp/deps_grapher/cache"
+
+root_dir = "<%= root_dir %>"
+lib_root_dir = File.join(root_dir, "lib")
+layer_root_dir = File.join(lib_root_dir, "deps_grapher")
+
+# default visualizer setting
+visualizer "<%= visualizer %>"
+
+ast_processor_policy do
+  exclude_const /\ADepsGrapher\z/
+
+  # advanced_const_resolver do |ast_node|
+  #   # some advanced logic using ast_node of parser gem
+  #   # this block should return a string of const name or nil
+  #   # if return nil, the const name will be resolved by default logic
+  # end
+end
+
+layer do
+  name :deps_grapher
+  visible true
+
+  source do
+    root lib_root_dir
+    exclude_pattern %r{/(command|cytoscape|vis|visualizer)}
+  end
+
+  color do
+    background "#FF5252"
+    border "#EF5350"
+    font "#FF5252"
+  end
+end
+
+layer do
+  name :command
+  visible true
+
+  source do
+    root File.join(layer_root_dir, "command")
+  end
+
+  color do
+    background "#512DA8"
+    border "#673AB7"
+    font "#512DA8"
+  end
+end
+
+layer do
+  name :cytoscape
+  visible true
+
+  source do
+    root layer_root_dir
+    glob_pattern ["cytoscape.rb", "cytoscape/**/*.rb"]
+  end
+
+  color do
+    background "#448AFF"
+    border "#42A5F5"
+    font "#448AFF"
+  end
+end
+
+layer do
+  name :vis
+  visible true
+
+  source do
+    root layer_root_dir
+    glob_pattern ["vis.rb", "vis/**/*.rb"]
+  end
+
+  color do
+    background "#00B8D4"
+    border "#00ACC1"
+    font "#00B8D4"
+  end
+end
+
+layer do
+  name :visualizer
+  visible true
+
+  source do
+    root layer_root_dir
+    glob_pattern ["visualizer.rb", "visualizer/**/*.rb"]
+  end
+
+  color do
+    background "#00C853"
+    border "#4CAF50"
+    font "#00C853"
+  end
+end
+
+with_plugin do |plugin_dir|
+  layer do
+    name :plugin
+    visible true
+
+    source do
+      root plugin_dir
+    end
+
+    color do
+      background "#607D8B"
+      border "#78909C"
+      font "#607D8B"
+    end
+  end
+end
+```
+
+
+### Run deps_grapher
+
+```shell
+cd ${your directory}
+bundle exec deps_grapher -c graphile.rb [options]
+```
+
+If `-c` is omitted, will find the configuration file `./graphile.rb` from the current directory and use it if found 
+
+```shell
+bundle exec deps_grapher --source "*Controller"  --target "*Service"
+```
+
+#### Command line options
+
+| Option                | Short Form  | Description                                                                                                   |
+|-----------------------|-------------|---------------------------------------------------------------------------------------------------------------|
+| `--config CONFIG`     | `-c CONFIG` | Specify the path to the configuration file                                                                    |
+| `--dump`              |             | Dump the configuration                                                                                        |
+| `--root ROOT_DIR`     |             | Specify a directory path you want to check without configuration                                              |
+| `--graph GRAPH`       | `-g GRAPH`  | Specify the type of graph                                                                                     |
+| `--layer LAYER`       |             | Specify the visible layer name (comma-separated is okay, also "all" means that displays all layers)           |
+| `--source CLASS_NAME` |             | Specify the source class on the graph (wildcards can be used, also `--target` is required if use this option) |
+| `--target CLASS_NAME` |             | Specify the target class on the graph (wildcards can be used)                                                 |
+| `--clean`             |             | Clear the cache and output directory                                                                          |
+| `--ignore-errors`     |             | Ignore errors                                                                                                 |
+| `--verbose`           |             | Display verbose log                                                                                           |
+
+
+#### Without the configuration file
+
+The `root` option allows you to run it without configuration.
+
+```shell
+bundle exec deps_grapher --root ${your directory} --source "*Controller"  --target "*Service"
+```
+
+This is generating a temporary configuration file internally.
+
+### Visualize the graph
+
+#### cy:klay (default)
+
+
+```shell
+bundle exec deps_grapher -g cy:klay
+```
+
+![cy:klay](./docs/cytoscape:klay.png)
+
+#### cy:cose
+
+```shell
+bundle exec deps_grapher -g cy:cose
+```
+
+![cy:cose](./docs/cytoscape:cose.png)
+
+#### cy:fcose
+
+```shell
+bundle exec deps_grapher -g cy:fcose
+```
+
+![cy:fcose](./docs/cytoscape:fcose.png)
+
+#### vis:box
+
+```shell
+bundle exec deps_grapher -g vis:box
+```
+
+![vis:box](./docs/vis:box.png)
+
+#### vis:dot
+
+```shell
+bundle exec deps_grapher -g vis:dot
+```
+
+![vis:dot](./docs/vis:dot.png)
+
+### Specify the layer to be displayed in the graph
+
+```shell
+bundle exec deps_grapher --layer your_layer,another_layer...
+```
+
+If no layer is specified, layers with "visible" set to "true" will be displayed.
+
+Also if you want to display all layers, specify as follows.
+
+```shell
+bundle exec deps_grapher --layer all --source "*Controller" --target "*Service"
+```
+
+However, be careful as having too many dependencies can greatly reduce readability and performance.
+
+It is recommended to use both the `source` and `target` options.
+
+## License
+[The MIT License](./LICENSE.txt)
+
+## Acknowledgement
+
+This tool is using the following open-source software.
+
+- cytoscape.js (https://github.com/cytoscape/cytoscape.js) - Licensed under MIT License (https://opensource.org/licenses/MIT)
+- vis-network (https://github.com/visjs/vis-network) - Licensed under Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0) and MIT License (https://opensource.org/licenses/MIT)
+
+We thank the contributors of these software for their great work.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "deps_grapher"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/deps_grapher

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path(File.join("..", "Gemfile"), __dir__)
+require "bundler/setup"
+require_relative "../lib/deps_grapher"
+
+options = {
+  config: ENV.fetch("DEPS_GRAPHILE", nil),
+  visualizer: nil,
+  visualizer_options: {
+    layers: []
+  }
+}
+
+config = DepsGrapher.config
+context = config.context
+
+if ARGV[0] == "init"
+  command = DepsGrapher::Command::Init.new context
+else
+  opts = OptionParser.new
+  opts.on("-c CONFIG", "--config CONFIG", "specify config path") { |v| options[:config] = File.expand_path v }
+  opts.on("--dump", "dump configuration", TrueClass) { |v| config.dump = v }
+  opts.on("--root ROOT_DIR", "specify a directory path you want to check without configuration") do |v|
+    config.root_dir = File.expand_path v
+    options[:config] = context.generate_temp_graphile
+  end
+  opts.on("-g GRAPH", "--graph GRAPH", "specify graph") { |v| options[:visualizer] = v }
+  opts.on("--layer LAYER", "visible layer name (comma separated is okay)") do |v|
+    options[:visualizer_options][:layers] = v.split(/,+/).to_set do
+      _1.downcase.to_sym
+    end
+  end
+  opts.on("--source CLASS_NAME", "source class on graph, wildcards can be used, also `--target` is required if use this option") { |v| config.source_path = v }
+  opts.on("--target CLASS_NAME", "target class on graph, wildcards can be used") { |v| config.target_path = v }
+  opts.on("--clean", "clear cache", TrueClass) { |v| config.clean = v }
+  opts.on("--ignore-errors", "ignore errors", TrueClass) { |v| config.ignore_errors = v }
+  opts.on("--verbose", "display verbose log", TrueClass) { |v| config.verbose = v }
+
+  begin
+    opts.parse! ARGV
+  rescue OptionParser::InvalidOption, OptionParser::MissingArgument, ArgumentError => e
+    config.logger.warn e.message
+    config.logger.warn ""
+    config.logger.warn opts
+    exit 1
+  end
+
+  config_path = options.delete(:config)
+
+  if config_path.blank?
+    config_path = Dir.glob("graphile.rb").first
+
+    if config_path.blank?
+      config.logger.warn "Run `bundle exec deps_grapher init` to create a configuration file"
+      exit 0
+    end
+    config.logger.info "Detected `#{File.expand_path(config_path)}` and will use it as a configuration file"
+  end
+
+  config.load! config_path
+  config.load_plugin!
+
+  visualizer = options.delete(:visualizer)
+  if visualizer.present?
+    available_visualizers = config.available_visualizers
+
+    if available_visualizers.include?(visualizer)
+      config.visualizer = visualizer
+    else
+      graph_banner = available_visualizers.map do |v|
+        "`#{v}`"
+      end.join(" or ")
+      config.logger.warn "Invalid visualizer: #{visualizer}"
+      config.logger.warn "Available visualizers: #{graph_banner}"
+      exit 1
+    end
+  end
+
+  options[:visualizer_options][:layers] = if options[:visualizer_options][:layers].present?
+                                            if options[:visualizer_options][:layers].include?(:all)
+                                              DepsGrapher::Layer.names
+                                            else
+                                              DepsGrapher::Layer.names & options[:visualizer_options][:layers]
+                                            end
+                                          else
+                                            DepsGrapher::Layer.visible_names
+                                          end
+
+  config.merge! options
+
+  command = DepsGrapher::Command::Analyzer.new config.input.files, context
+end
+
+exit DepsGrapher::Cli.run!(command)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/deps_grapher.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/deps_grapher/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "deps_grapher"
+  spec.version = DepsGrapher::VERSION
+  spec.authors = ["jk-es335"]
+  spec.email = ["dev@hacomono.co.jp", "soultraingang.dev@gmail.com"]
+
+  spec.summary = "Tool to visualize Ruby class dependencies"
+  spec.homepage = "https://github.com/hacomono-lib/deps_grapher"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/hacomono-lib/deps_grapher"
+  spec.metadata["changelog_uri"] = "https://github.com/hacomono-lib/deps_grapher"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features|docs)/|\.(?:git|travis|circleci|rspec|rubocop)|appveyor)})
+    end
+  end
+  spec.bindir = "bin"
+  spec.executables << "deps_grapher"
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport"
+  spec.add_dependency "parser"
+end

data/lefthook.yml

@@ -0,0 +1,14 @@
+#   Refer for explanation to following link:
+#   https://github.com/evilmartians/lefthook/blob/master/docs/configuration.md
+pre-push:
+  commands:
+    test:
+      tags: run rspec
+      run: bundle exec rspec
+
+pre-commit:
+  commands:
+    rubocop:
+      tags: check style
+      glob: "*.rb"
+      run: bundle exec rubocop --force-exclusion {staged_files}