rails-mermaid_erd_markdown 0.1.0 → 0.3.0

data/bin/rubocop

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rubocop", "rubocop")

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/docs/examples/erd.yml

@@ -1,4 +1,4 @@
 # This is the path and filename of the generated ERD. You can modify it to change where the ERD is stored/updated.
-# Default output path: 'app/ERD.md'
+# Default output path: 'app/models/ERD.md'
 erd:
     output_path: 'app/ERD.md'

data/lib/rails-mermaid_erd_markdown/configuration.rb

@@ -1,20 +1,29 @@
+# frozen_string_literal: true
+
 require "yaml"
-require "logger"
 
-class MermaidErdMarkdown::Configuration
-  attr_accessor :output_path
+module MermaidErdMarkdown
+  class Configuration
+    attr_accessor :output_path, :split_output, :relationship_depth
 
-  def initialize
-    config = {
-      output_path: "app/models/ERD.md"
-    }
-    erd_config_path = "erd.yml"
+    def initialize
+      config = {
+        output_path: "app/models/ERD.md",
+        split_output: false,
+        relationship_depth: 1
+      }
+      erd_config_path = "erd.yml"
 
-    begin
-      erd_yml = YAML.safe_load File.open(erd_config_path)
-      @output_path = erd_yml["erd"]["output_path"]
-    rescue StandardError
-      @output_path = config[:output_path]
+      begin
+        erd_yml = YAML.safe_load File.open(erd_config_path)
+        @output_path = erd_yml["erd"]["output_path"] || config[:output_path]
+        @split_output = erd_yml["erd"]["split_output"] || config[:split_output]
+        @relationship_depth = erd_yml["erd"]["relationship_depth"] || config[:relationship_depth]
+      rescue StandardError
+        @output_path = config[:output_path]
+        @split_output = config[:split_output]
+        @relationship_depth = config[:relationship_depth]
+      end
     end
   end
 end

data/lib/rails-mermaid_erd_markdown/generator.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "markdown_document"
+require_relative "source_data"
+require "digest/md5"
+require "logger"
+require "pathname"
+
+module MermaidErdMarkdown
+  class Generator
+    attr_writer :logger
+
+    def self.generate
+      new.generate
+    end
+
+    def generate
+      return unless find_or_create_output
+      return unless erd_changed?
+
+      update_erd
+
+      update_split_erds if configuration.split_output
+    end
+
+    def index_markdown(files)
+      MermaidErdMarkdown::MarkdownDocument.create do |doc|
+        doc.add(doc.header("Entity Relationship Diagrams"))
+        doc.add(
+          "Each model has its own ERD diagram. The diagram shows the " \
+          "selected model, plus #{configuration.relationship_depth} " \
+          "associated model(s) deep. Click on the model name to view " \
+          "the diagram.\n"
+        )
+        doc.add(doc.subheader("Models"))
+        files.each do |model, path|
+          doc.add(doc.list_item(doc.link(model, "../#{path}")))
+        end
+        doc.add("")
+      end
+    end
+
+    def model_markdown(output)
+      MermaidErdMarkdown::MarkdownDocument.create do |doc|
+        model_name = output[:Models].first[:ModelName]
+        doc.add(doc.header("#{model_name} Entity-Relationship Diagram"))
+        doc.add(doc.subheader("Associated Models"))
+        output[:Models].each do |model|
+          next if model[:ModelName] == model_name
+
+          model_path = "../#{output_path(model[:ModelName])}"
+
+          doc.add(doc.list_item(doc.link(model[:ModelName], model_path)))
+        end
+        doc.add("")
+        doc.add(doc.subheader("Entity-Relationship Diagram"))
+        doc.add(mermaid_markdown(output))
+      end
+    end
+
+    def mermaid_markdown(source)
+      MermaidErdMarkdown::MarkdownDocument.create do
+        erd do
+          add(
+            source[:Models].map do |model|
+              erd_table(model[:TableName], model[:ModelName]) do
+                model[:Columns].map do |column|
+                  erd_table_column(column)
+                end
+              end
+            end
+          )
+          add(
+            source[:Relations].map do |relation|
+              erd_relation(relation)
+            end
+          )
+        end
+      end
+    end
+
+    private
+
+    def comprehensive_erd
+      @comprehensive_erd ||= mermaid_markdown(source_data.data)
+    end
+
+    def configuration
+      @configuration ||= MermaidErdMarkdown::Configuration.new
+    end
+
+    def erd_changed?
+      # check if two diagrams are the same by comparing their MD5 hashes
+      existing_erd_hash = Digest::MD5.hexdigest(File.read(output_path))
+      new_erd_hash = Digest::MD5.hexdigest(comprehensive_erd)
+
+      return true if existing_erd_hash != new_erd_hash
+
+      logger.info("ERD already exists and is up to date. Skipping...")
+
+      false
+    end
+
+    def find_or_create_output
+      return true if output_path.exist?
+
+      logger.info("ERD does not currently exist at result path. Creating...")
+      begin
+        write_file("", output_path)
+        logger.info("ERD successfully created at #{output_path}")
+      rescue StandardError
+        logger.info("Could not create ERD. Output path is invalid.")
+
+        false
+      end
+
+      true
+    end
+
+    def logger
+      @logger ||= Logger.new($stdout).tap do |log|
+        log.progname = self.class.name.split("::").first
+      end
+    end
+
+    def output_path(extension = nil)
+      return Pathname.new(configuration.output_path) unless extension
+
+      Pathname.new(configuration.output_path).sub_ext("_#{extension}.md")
+    end
+
+    def source_data
+      @source_data ||= MermaidErdMarkdown::SourceData.new
+    end
+
+    def update_erd
+      logger.info("ERD writing to #{output_path}...")
+      write_file(comprehensive_erd, output_path)
+      logger.info("ERD successfully written")
+    end
+
+    def update_split_erds
+      # first remove all existing model ERD files
+      Dir.glob(output_path.sub_ext("_*.md")).each do |file|
+        File.delete(file)
+      end
+
+      files = {}
+
+      depth = configuration.relationship_depth
+
+      source_data.split_output(depth).each do |output|
+        model_name = output[:Models].first[:ModelName]
+        model_path = output_path(model_name)
+        write_file(model_markdown(output), model_path)
+        logger.info("ERD successfully written to #{model_path}")
+        files[model_name] = model_path
+      end
+
+      index_path = output_path("index")
+      write_file(index_markdown(files), index_path)
+    end
+
+    def write_file(new_erd, path)
+      File.write(path, new_erd)
+    end
+  end
+end

data/lib/rails-mermaid_erd_markdown/markdown_document.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module MermaidErdMarkdown
+  class MarkdownDocument
+    attr_accessor :is_show_key, :is_show_comment
+
+    def self.create(&block)
+      new.generate(&block)
+    end
+
+    def initialize
+      @is_show_key = true
+      @is_show_comment = true
+    end
+
+    def add(element)
+      document << element
+    end
+
+    def document
+      @document ||= []
+    end
+
+    def erd(&block)
+      add(erd_header)
+      block.arity == 1 ? block[self] : instance_eval(&block)
+      add(erd_footer)
+    end
+
+    def erd_footer
+      "```"
+    end
+
+    def erd_header
+      [
+        "```mermaid",
+        "erDiagram",
+        "    %% --------------------------------------------------------",
+        "    %% Entity-Relationship Diagram",
+        "    %% --------------------------------------------------------",
+        ""
+      ].join("\n")
+    end
+
+    def erd_relation(relation)
+      left_model_name = relation[:LeftModelName].tr(":", "-")
+      right_model_name = relation[:RightModelName].tr(":", "-")
+      comment = is_show_comment ? ": \"#{relation[:Comment]}\"" : ": \"\""
+
+      "    #{left_model_name} #{relation[:LeftValue]}" \
+        "#{relation[:Line]}#{relation[:RightValue]} " \
+        "#{right_model_name} #{comment}"
+    end
+
+    def erd_table(table_name, model_name)
+      lines = [erd_table_header(table_name, model_name)]
+      lines << yield
+      lines << erd_table_footer
+      lines.join("\n")
+    end
+
+    def erd_table_column(column)
+      key = is_show_key ? column[:key] : ""
+      line = "        #{column[:type]} #{column[:name]}"
+      line << " #{key}" unless key.empty?
+      line
+    end
+
+    def erd_table_header(table_name, model_name)
+      [
+        "    %% table name: #{table_name}",
+        "    #{model_name.tr(":", "-")}{"
+      ].join("\n")
+    end
+
+    def erd_table_footer
+      [
+        "    }",
+        ""
+      ].join("\n")
+    end
+
+    def header(text)
+      "# #{text}\n"
+    end
+
+    def generate(&block)
+      block.arity == 1 ? block[self] : instance_eval(&block)
+      document.join("\n")
+    end
+
+    def link(text, url)
+      "[#{text}](#{url})"
+    end
+
+    def list_item(text)
+      "- #{text}"
+    end
+
+    def subheader(text)
+      "## #{text}\n"
+    end
+  end
+end

data/lib/rails-mermaid_erd_markdown/source_data.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "rails-mermaid_erd"
+
+module MermaidErdMarkdown
+  class SourceData
+    def data
+      @data ||= RailsMermaidErd::Builder.model_data
+    end
+
+    def split_output(depth = 1)
+      source_models = data[:Models]
+      source_relations = data[:Relations]
+      output = []
+
+      source_models.each do |model|
+        model_names = [model[:ModelName]]
+        search_models = model_names
+        relations = []
+
+        depth.times do
+          found_relations = []
+          next_search_models = []
+          search_models.each do |search_model|
+            found_relations += related_models(search_model, source_relations)
+            next_search_models += related_model_names(search_model, found_relations)
+          end
+          search_models = next_search_models
+          model_names += search_models
+          relations += found_relations
+        end
+
+        output << {
+          Models: models(model_names.uniq, source_models),
+          Relations: relations.uniq
+        }
+      end
+
+      output
+    end
+
+    private
+
+    def models(model_names, source_models)
+      model_names.map do |model_name|
+        source_models.find { |m| m[:ModelName] == model_name }
+      end.compact
+    end
+
+    def related_model_names(model_name, relations)
+      relations.map do |r|
+        r[:LeftModelName] == model_name ? r[:RightModelName] : r[:LeftModelName]
+      end
+    end
+
+    def related_models(model_name, relations)
+      relations.select do |relation|
+        relation[:LeftModelName] == model_name ||
+          relation[:RightModelName] == model_name
+      end
+    end
+  end
+end

data/lib/rails-mermaid_erd_markdown/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MermaidErdMarkdown
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/rails-mermaid_erd_markdown.rb

@@ -1,108 +1,19 @@
 # frozen_string_literal: true
 
-require_relative "rails-mermaid_erd_markdown/configuration"
-require "digest/md5"
+require_relative "rails-mermaid_erd_markdown/generator"
 require "rake"
 require "rake/dsl_definition"
-require "pathname"
-require "logger"
 
 module MermaidErdMarkdown
   extend Rake::DSL
 
   class << self
-    attr_writer :logger
-
-    def logger
-      @logger ||= Logger.new($stdout).tap do |log|
-        log.progname = name
-      end
-    end
-
-    def configuration
-      @configuration ||= MermaidErdMarkdown::Configuration.new
-    end
-
     def perform
-      new_erd = generate_mermaid_erd
-      existing_erd_path = Pathname.new(configuration.output_path)
-
-      unless existing_erd_path.exist?
-        logger.info("ERD does not currently exist at result path. Creating...")
-        begin
-          create_erd_file(new_erd)
-          logger.info("ERD successfully created at #{configuration.output_path}")
-        rescue StandardError
-          logger.info("Could not create ERD. Output path is invalid.")
-        end
-
-        return
-      end
-
-      existing_erd = File.read(existing_erd_path)
-      update_erd_file(existing_erd, new_erd)
-    end
-
-    def update_erd_file(current_erd, new_erd)
-      # check if two diagrams are the same by comparing their MD5 hashes
-      if Digest::MD5.hexdigest(current_erd) == Digest::MD5.hexdigest(new_erd)
-        logger.info("ERD already exists and is up to date. Skipping...")
-        return
-      end
-
-      logger.info("ERD already exists but is out of date. Overwriting...")
-      File.write(configuration.output_path, new_erd)
-      logger.info("ERD successfully updated")
-
-      nil
-    end
-
-    def create_erd_file(erd)
-      File.write(configuration.output_path, erd)
-
-      nil
-    end
-
-    def generate_mermaid_erd
-      data = RailsMermaidErd::Builder.model_data
-
-      is_show_key = true
-      is_show_relation_comment = true
-
-      lines = ["```mermaid"]
-      lines << "erDiagram"
-      lines << "    %% --------------------------------------------------------"
-      lines << "    %% Entity-Relationship Diagram"
-      lines << "    %% --------------------------------------------------------"
-      lines << ""
-
-      data[:Models].each do |model|
-        lines << "    %% table name: #{model[:TableName]}"
-        lines << "    #{model[:ModelName].tr(":", "-")}{"
-
-        model[:Columns].each do |column|
-          key = is_show_key ? column[:key] : ""
-          lines << "        #{column[:type]} #{column[:name]} #{key} "
-        end
-
-        lines << "    }"
-        lines << ""
-      end
-
-      data[:Relations].each do |relation|
-        left_model_name = relation[:LeftModelName].tr(":", "-")
-        right_model_name = relation[:RightModelName].tr(":", "-")
-        comment = is_show_relation_comment ? ": \"#{relation[:Comment]}\"" : ": \"\""
-
-        lines << "    #{left_model_name} #{relation[:LeftValue]}#{relation[:Line]}#{relation[:RightValue]} #{right_model_name} #{comment}"
-      end
-
-      lines << "```"
-      lines.join("\n")
+      MermaidErdMarkdown::Generator.generate
     end
   end
 
-  desc "Generate/update mermaid ERD diagram for database Models."
+  desc "Generate/update mermaid ERD diagram(s) for database Models."
   task generate_erd: :environment do
     perform
   end

data/rails-mermaid_erd_markdown.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/rails-mermaid_erd_markdown/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rails-mermaid_erd_markdown"
+  spec.version = MermaidErdMarkdown::VERSION
+  spec.authors = ["humzahkiani"]
+  spec.email = ["89326566+humzahkiani@users.noreply.github.com"]
+
+  spec.summary = "This is a rails gem that extends the rails-mermaid_erd gem to generate a mermaid ERD for Rails " \
+                 "Models in markdown directly in source code."
+  spec.homepage = "https://github.com/humzahkiani/rails-mermaid_erd_markdown"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/humzahkiani/rails-mermaid_erd_markdown"
+  spec.metadata["changelog_uri"] = "https://github.com/humzahkiani/rails-mermaid_erd_markdown/blob/main/CHANGELOG.md"
+  spec.metadata["github_repo"] = "ssh://github.com/humzahkiani/rails-mermaid_erd_markdown"
+  # 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")
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime Dependencies
+  spec.add_dependency "rails", ">= 5.2"
+  spec.add_dependency "rails-mermaid_erd", "~> 0.4.2"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

data/sig/rails/mermaid_erd_markdown.rbs

@@ -0,0 +1,6 @@
+module Rails
+  module MermaidErdMarkdown
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

data/test/example_output/mock_ERD.md

@@ -0,0 +1,48 @@
+```mermaid
+erDiagram
+    %% --------------------------------------------------------
+    %% Entity-Relationship Diagram
+    %% --------------------------------------------------------
+
+    %% table name: users
+    User{
+        integer id PK
+        string name
+        string email
+        datetime created_at
+        datetime updated_at
+    }
+
+    %% table name: profiles
+    Profile{
+        integer id PK
+        text bio
+        integer user_id FK
+        datetime created_at
+        datetime updated_at
+    }
+
+    %% table name: articles
+    Article{
+        integer id PK
+        string title
+        text content
+        integer user_id FK
+        datetime created_at
+        datetime updated_at
+    }
+
+    %% table name: comments
+    Comment{
+        integer id PK
+        string commenter
+        text body
+        integer article_id FK
+        datetime created_at
+        datetime updated_at
+    }
+
+    Article }o--|| User : "BT:user"
+    Profile }o--|| User : "BT:user"
+    Comment }o--|| Article : "BT:article"
+```

data/test/example_output/mock_ERD_index.md

@@ -0,0 +1,10 @@
+# Entity Relationship Diagrams
+
+Each model has its own ERD diagram. The diagram shows the selected model, plus 1 associated model(s) deep. Click on the model name to view the diagram.
+
+## Models
+
+- [User](../User.md)
+- [Profile](../Profile.md)
+- [Article](../Article.md)
+- [Comment](../Comment.md)

data/test/example_output/mock_ERD_model.md

@@ -0,0 +1,46 @@
+# User Entity-Relationship Diagram
+
+## Associated Models
+
+- [Article](../app/models/ERD_Article.md)
+- [Profile](../app/models/ERD_Profile.md)
+
+## Entity-Relationship Diagram
+
+```mermaid
+erDiagram
+    %% --------------------------------------------------------
+    %% Entity-Relationship Diagram
+    %% --------------------------------------------------------
+
+    %% table name: users
+    User{
+        integer id PK
+        string name
+        string email
+        datetime created_at
+        datetime updated_at
+    }
+
+    %% table name: articles
+    Article{
+        integer id PK
+        string title
+        text content
+        integer user_id FK
+        datetime created_at
+        datetime updated_at
+    }
+
+    %% table name: profiles
+    Profile{
+        integer id PK
+        text bio
+        integer user_id FK
+        datetime created_at
+        datetime updated_at
+    }
+
+    Article }o--|| User : "BT:user"
+    Profile }o--|| User : "BT:user"
+```