diver_down 0.0.1.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be24104efe3c4cc931f29552c5922681622e5efcc29d74edd26ea0058d68823b
+  data.tar.gz: 9813779ca1e2451ed7cb97f983e198c2f749fc2f3dc88b54db0f33813e938255
+SHA512:
+  metadata.gz: 583e816d1ff590d7e42e5c02f3546e67802ea1046c5bb8183e973cf65ae1ce37b2c7e1549578b4d848383ff2a5affd1f51455ad78cd3799e73cfecbc40b1c3ec
+  data.tar.gz: 150a56d11ff08e5f0a43e5483c3d5d59a6ac94dde414af484183a4b6b265c8310b8583a10488e28b1bf3f5b6a9bd205e39e2b77b5a15666bf1b03c7958d94ca8

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-03-05
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 alpaca-tc
+
+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,132 @@
+# DiverDown
+
+`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 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
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'diver_down'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ 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
+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
+
+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 server for frontend
+$ pnpm install
+$ pnpm run dev
+
+# Start server for backend
+$ bundle install
+# 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
+
+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](https://github.com/alpaca-tc/diver_down/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the DiverDown project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/alpaca-tc/diver_down/blob/main/CODE_OF_CONDUCT.md).

data/exe/diver_down_web

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'rack/contrib'
+require 'webrick'
+require 'diver_down'
+require 'diver_down-web'
+require 'optparse'
+
+options = {}
+option_parser = OptionParser.new do |opts|
+  opts.banner = <<~BANNER
+    Usage: diver_down_web [options]
+
+    Example:
+      diver_down_web --definition-dir /path/to/definitions --module-store /path/to/module_store.yml
+
+    Options:
+  BANNER
+
+  opts.on('--definition-dir PATH', 'Path to the definition directory') do |path|
+    options[:definition_dir] = path
+  end
+
+  opts.on('--module-store PATH', 'Path to the module store') do |path|
+    options[:module_store] = path
+  end
+end
+option_parser.parse!(ARGV)
+
+unless options[:definition_dir]
+  puts 'Missing --definition-dir'
+  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] || Tempfile.new(['module_store', '.yaml']))
+  )
+)
+
+begin
+  # Rack 2.0
+  require 'rack'
+  require 'rack/server'
+  Rack::Server.new(app:, server: :webrick).start
+rescue LoadError
+  # Rack 3.0
+  require 'rackup'
+  Rackup::Server.new(app:, server: :webrick).start
+end

data/lib/diver_down/definition/dependency.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module DiverDown
+  class Definition
+    class Dependency
+      include Comparable
+
+      # @param hash [Hash]
+      # @return [DiverDown::Definition::Dependency]
+      def self.from_hash(hash)
+        method_ids = (hash[:method_ids] || hash['method_ids'] || []).map do
+          DiverDown::Definition::MethodId.from_hash(_1)
+        end
+
+        new(
+          source_name: hash[:source_name] || hash['source_name'],
+          method_ids:
+        )
+      end
+
+      # @param dependencies [Array<DiverDown::Definition::Dependency>]
+      # @return [Array<DiverDown::Definition::Dependency>]
+      def self.combine(*dependencies)
+        dependencies.group_by(&:source_name).map do |source_name, same_source_dependencies|
+          new_dependency = new(source_name:)
+
+          same_source_dependencies.each do |dependency|
+            dependency.method_ids.each do |method_id|
+              new_method_id = new_dependency.find_or_build_method_id(name: method_id.name, context: method_id.context)
+              new_method_id.add_path(*method_id.paths)
+            end
+          end
+
+          new_dependency
+        end
+      end
+
+      attr_reader :source_name
+
+      # @param source_name [String]
+      # @param method_ids [Array<DiverDown::Definition::MethodId>]
+      def initialize(source_name:, method_ids: [])
+        @source_name = source_name
+        @method_id_map = {
+          'class' => {},
+          'instance' => {},
+        }
+
+        method_ids.each do |method_id|
+          @method_id_map[method_id.context][method_id.name] = method_id
+        end
+      end
+
+      # @param name [String]
+      # @param context ['instance', 'class']
+      # @return [DiverDown::Definition::MethodId]
+      def find_or_build_method_id(name:, context:)
+        @method_id_map[context.to_s][name.to_s] ||= DiverDown::Definition::MethodId.new(name:, context:)
+      end
+
+      # @param name [String, Symbol]
+      # @param context ['instance', 'class']
+      # @return [DiverDown::Definition::MethodId, nil]
+      def method_id(name:, context:)
+        @method_id_map[context.to_s][name.to_s]
+      end
+
+      # @return [Array<DiverDown::Definition::MethodId>]
+      def method_ids
+        (@method_id_map['class'].values + @method_id_map['instance'].values).sort
+      end
+
+      # @return [Hash]
+      def to_h
+        {
+          source_name:,
+          method_ids: method_ids.map(&:to_h),
+        }
+      end
+
+      # @return [Integer]
+      def <=>(other)
+        source_name <=> other.source_name
+      end
+
+      # @param other [Object, DiverDown::Definition::Source]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class) &&
+          source_name == other.source_name &&
+          method_ids == other.method_ids
+      end
+      alias eq? ==
+      alias eql? ==
+
+      # @return [Integer]
+      def hash
+        [self.class, source_name, method_ids].hash
+      end
+
+      # @return [String]
+      def inspect
+        %(#<#{self.class} source_name="#{source_name}" method_ids=#{method_ids}>")
+      end
+    end
+  end
+end

data/lib/diver_down/definition/method_id.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module DiverDown
+  class Definition
+    class MethodId
+      VALID_CONTEXT = %w[instance class].freeze
+      private_constant :VALID_CONTEXT
+
+      include Comparable
+
+      attr_reader :name, :context, :paths
+
+      # @param hash [Hash]
+      def self.from_hash(hash)
+        new(
+          name: hash[:name] || hash['name'],
+          context: hash[:context] || hash['context'],
+          paths: hash[:paths] || hash['paths'] || []
+        )
+      end
+
+      # @param name [String, Symbol]
+      # @param context ['instance', 'class']
+      # @param paths [Set<String>]
+      def initialize(name:, context:, paths: Set.new)
+        raise ArgumentError, "invalid context: #{context}" unless VALID_CONTEXT.include?(context)
+
+        @name = name.to_s
+        @context = context.to_s
+        @paths = paths.to_set
+      end
+
+      # @param path [Array<String>]
+      def add_path(*paths)
+        paths.each do
+          @paths.add(_1)
+        end
+      end
+
+      # @return [String]
+      def human_method_name
+        prefix = context == 'instance' ? '#' : '.'
+        "#{prefix}#{name}"
+      end
+
+      # @return [Hash]
+      def to_h
+        {
+          name:,
+          context:,
+          paths: @paths.sort,
+        }
+      end
+
+      # @return [Integer]
+      def hash
+        [self.class, name, context, paths].hash
+      end
+
+      # @param other [DiverDown::Definition::MethodId]
+      # @return [Integer]
+      def <=>(other)
+        [context, name] <=> [other.context, other.name]
+      end
+
+      # @param other [Object, DiverDown::Definition::Source]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class) &&
+          name == other.name &&
+          context == other.context &&
+          paths == other.paths
+      end
+      alias eq? ==
+      alias eql? ==
+
+      # @return [String]
+      def inspect
+        %(#<#{self.class} #{human_method_name} paths=#{paths.inspect}>")
+      end
+    end
+  end
+end

data/lib/diver_down/definition/source.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module DiverDown
+  class Definition
+    class Source
+      include Comparable
+
+      # @param hash [Hash]
+      def self.from_hash(hash)
+        new(
+          source_name: hash[:source_name] || hash['source_name'],
+          dependencies: (hash[:dependencies] || hash['dependencies'] || []).map { DiverDown::Definition::Dependency.from_hash(_1) }
+        )
+      end
+
+      # @param sources [Array<DiverDown::Definition::Source>]
+      # @return [DiverDown::Definition::Source]
+      def self.combine(*sources)
+        raise ArgumentError, 'sources are empty' if sources.empty?
+
+        unique_sources = sources.map(&:source_name).uniq
+        raise ArgumentError, "sources are unmatched. (#{unique_sources})" unless unique_sources.length == 1
+
+        all_dependencies = sources.flat_map(&:dependencies)
+
+        new(
+          source_name: unique_sources[0],
+          dependencies: DiverDown::Definition::Dependency.combine(*all_dependencies)
+        )
+      end
+
+      attr_reader :source_name
+
+      # @param source_name [String] filename of the source file
+      # @param dependencies [Array<DiverDown::Definition::Dependency>]
+      def initialize(source_name:, dependencies: [])
+        @source_name = source_name
+        @dependency_map = dependencies.map { [_1.source_name, _1] }.to_h
+      end
+
+      # @param source [String]
+      # @return [DiverDown::Definition::Dependency, nil] return nil if source is self.source
+      def find_or_build_dependency(dependency_source_name)
+        return if source_name == dependency_source_name
+
+        @dependency_map[dependency_source_name] ||= DiverDown::Definition::Dependency.new(source_name: dependency_source_name)
+      end
+
+      # @param dependency_source_name [String]
+      # @return [DiverDown::Definition::Dependency, nil]
+      def dependency(dependency_source_name)
+        @dependency_map[dependency_source_name]
+      end
+
+      # @return [Array<DiverDown::Definition::Dependency>]
+      def dependencies
+        @dependency_map.values.sort
+      end
+
+      # @return [Hash]
+      def to_h
+        {
+          source_name:,
+          dependencies: dependencies.map(&:to_h),
+        }
+      end
+
+      # @param other [DiverDown::Definition::Source]
+      # @return [Integer]
+      def <=>(other)
+        source_name <=> other.source_name
+      end
+
+      # @param other [Object, DiverDown::Definition::Source]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class) &&
+          source_name == other.source_name &&
+          dependencies == other.dependencies
+      end
+      alias eq? ==
+      alias eql? ==
+
+      # @return [Integer]
+      def hash
+        [self.class, source_name, dependencies].hash
+      end
+    end
+  end
+end

data/lib/diver_down/definition.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module DiverDown
+  class Definition
+    require 'diver_down/definition/source'
+    require 'diver_down/definition/dependency'
+    require 'diver_down/definition/method_id'
+
+    # @param hash [Hash]
+    # @return [DiverDown::Definition]
+    def self.from_hash(hash)
+      new(
+        title: hash[:title] || hash['title'] || '',
+        definition_group: hash[:definition_group] || hash['definition_group'],
+        sources: (hash[:sources] || hash['sources'] || []).map do |source_hash|
+          DiverDown::Definition::Source.from_hash(source_hash)
+        end
+      )
+    end
+
+    # @param definition_group [String, nil]
+    # @param title [String]
+    # @param definitions [Array<DiverDown::Definition>]
+    def self.combine(definition_group:, title:, definitions: [])
+      all_sources = definitions.flat_map(&:sources)
+
+      sources = all_sources.group_by(&:source_name).map do |_, same_sources|
+        DiverDown::Definition::Source.combine(*same_sources)
+      end
+
+      new(
+        definition_group:,
+        title:,
+        sources:
+      )
+    end
+
+    attr_reader :definition_group, :title
+
+    # ID issued when stored in DiverDown::Web::DefinitionStore
+    # I want to manage ID in DiverDown::Web::DefinitionStore, but for performance reasons, I have to set Definition#id to determine its identity
+    # because naive comparing the identity by instance variables of Definitions is slow.
+    # @attr_accessor [Integer]
+    attr_accessor :store_id
+
+    # @param title [String]
+    # @param sources [Array<DiverDown::Definition::Source>]
+    def initialize(definition_group: nil, title: '', sources: [])
+      @definition_group = definition_group
+      @title = title
+      @source_map = sources.map { [_1.source_name, _1] }.to_h
+    end
+
+    # @param source_name [String]
+    # @return [DiverDown::Definition::Source]
+    def find_or_build_source(source_name)
+      @source_map[source_name] ||= DiverDown::Definition::Source.new(source_name:)
+    end
+
+    # @param source_name [String]
+    # @return [DiverDown::Definition::Source, nil]
+    def source(source_name)
+      @source_map[source_name]
+    end
+
+    # @return [Array<DiverDown::Definition::Source>]
+    def sources
+      @source_map.values.sort
+    end
+
+    # @return [String]
+    def to_h
+      {
+        definition_group:,
+        title:,
+        sources: sources.map(&:to_h),
+      }
+    end
+
+    # @return [String]
+    def to_msgpack
+      MessagePack.pack(to_h)
+    end
+
+    # @param other [Object, DiverDown::Definition::Source]
+    # @return [Boolean]
+    def ==(other)
+      if store_id
+        other.is_a?(self.class) &&
+          store_id == other.store_id
+      else
+        other.is_a?(self.class) &&
+          definition_group == other.definition_group &&
+          title == other.title &&
+          sources.sort == other.sources.sort
+      end
+    end
+    alias eq? ==
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      if store_id
+        [self.class, store_id].hash
+      else
+        [self.class, definition_group, title, sources].hash
+      end
+    end
+  end
+end

data/lib/diver_down/helper.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module DiverDown
+  module Helper
+    CLASS_NAME_QUERY = Module.method(:name).unbind.freeze
+
+    INSTANCE_CLASS_QUERY = Class.instance_method(:class).freeze
+    private_constant :INSTANCE_CLASS_QUERY
+
+    # @param obj [Object, String, Module, Class]
+    # @return [String, nil] if obj is anonymous module, return nil
+    def self.normalize_module_name(obj)
+      if String === obj
+        obj
+      else
+        mod = resolve_module(obj)
+
+        # Do not call the original method as much as possible
+        CLASS_NAME_QUERY.bind_call(mod) ||
+          (mod.name if mod.respond_to?(:name))
+      end
+    end
+
+    # @note The object passed as an argument may be a Proxied BasicObject.
+    # For example, the DSL of FactoryBot's factory will add a new method in response to the invoked method name,
+    # so passed as an argument methods are not called within this method.
+    #
+    # @return [Module, Class]
+    def self.resolve_module(obj)
+      if module?(obj) # Do not call method of this
+        resolve_singleton_class(obj)
+      else
+        k = INSTANCE_CLASS_QUERY.bind_call(obj)
+        resolve_singleton_class(k)
+      end
+    end
+
+    # @param obj [Module, Class]
+    # @return [Module, Class]
+    def self.resolve_singleton_class(obj)
+      if obj.singleton_class?
+        obj.attached_object
+      else
+        obj
+      end
+    end
+
+    # @param obj [Object]
+    # @return [Boolean]
+    def self.module?(obj)
+      Module === obj
+    end
+
+    # @param obj [Object]
+    # @return [Boolean]
+    def self.class?(obj)
+      Class === obj
+    end
+
+    # @param str [String]
+    # @return [Module]
+    def self.constantize(str)
+      ::ActiveSupport::Inflector.constantize(str)
+    end
+
+    # @param hash [Hash]
+    # @return [Hash]
+    def self.deep_symbolize_keys(object)
+      case object
+      when Hash
+        object.each_with_object({}) do |(key, value), memo|
+          memo[key.to_sym] = deep_symbolize_keys(value)
+        end
+      when Array
+        object.map { deep_symbolize_keys(_1) }
+      else
+        object
+      end
+    end
+  end
+end