rails-mermaid_erd 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f3cfe23f8fa1343b2bd8a3ac5d47c1967613ce7a832d65de858b363402db0b1
-  data.tar.gz: 146d83e00452b8c56cbf8c4c6e0aebd62f99b3224e6b7e3062b4889b55bf0723
+  metadata.gz: 5a6ae2943632ef191d3758420e84a0fc2e43f17a677359e21328bc67b83bd172
+  data.tar.gz: d1ecd0768360f3bdbca63e1569ac26f708af009bfc3b18d09c8001ff474ea77a
 SHA512:
-  metadata.gz: 2c68987537096806829a9709f477dd8cc8a0108291387ff670796d2c41c4a900fe0f1a55902381b12d582d4e66d77f2b0421d929dfc72060a10d5b9ed020c4a6
-  data.tar.gz: 04cbecd36399c810f0846e1d4c4275922acfeb1ec2bcf426440f08902db6b4b051368f57ec57a0f8259108d9f727b77d0760ee0f817aee8122e4f3952dcfcc58
+  metadata.gz: 4ef1270960ec9ce3f1a91d7c8c9d6182f0ef489f11e10be3653f905e72dbf344d39cee5da22ac35cc2f799836e49da799f0db2df82f2e9c3b59f120b6592fcdd
+  data.tar.gz: f3a1d2f73421f4f2cbec8c7d394ca55ced02835df12e2fb3bfb24ec6c97685609cdd30137be1b9943d853b80ff86d6debdd996aa19066dd173009635c0615464

data/README.md

@@ -1,4 +1,4 @@
-[English](./README.md) | [日本語](./README.ja.md)
+[English](./README.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md) | [繁體中文](./README.zh-TW.md) | [한국어](./README.ko.md) | [Español](./README.es.md) | [Français](./README.fr.md) | [Deutsch](./README.de.md) | [Italiano](./README.it.md) | [Português (Brasil)](./README.pt-BR.md) | [Русский](./README.ru.md) | [العربية](./README.ar.md)
 
 # Rails Mermaid ERD
 
@@ -58,11 +58,45 @@ This file is not required for Git management, so you can add it to `.gitignore`
 mermaid_erd
 ```
 
-`<app_root>/mermaid_erd/index.html` is a single HTML file.
+`<app_root>/mermaid_erd/index.html` is a single self-contained HTML file. All front-end dependencies (Tailwind, Mermaid, Vue) are inlined, so it works offline and behind strict corporate proxies — no CDN access is needed at view time. The file is roughly 4 MB because the bundles ship inside it.
+
 If you share this file, it can be used by those who do not have a Ruby on Rails environment. Or, you can upload the file to a web server and share it with the same URL.
 
 It would be very smart to generate it automatically using CI.
 
+### Print the Mermaid source to stdout
+
+Run rake task `mermaid_erd:print` to print the raw `erDiagram` source to stdout instead of writing the HTML viewer. This pipes cleanly into other tools:
+
+```bash
+$ bundle exec rails mermaid_erd:print
+$ bundle exec rails mermaid_erd:print > er.mmd
+$ bundle exec rails mermaid_erd:print | mmdc -i - -o er.svg
+```
+
+The output is the full diagram — every table, column, key, comment, and relation — equivalent to the HTML viewer with all of its detail toggles enabled.
+
+## Languages
+
+The viewer UI ships in 12 languages: English, 日本語, 简体中文, 繁體中文, 한국어, Español, Français, Deutsch, Italiano, Português (Brasil), Русский, and العربية (right-to-left). It auto-detects the browser language (`navigator.language`) on load, falls back to English for unsupported locales, and can be switched manually from the selector in the top-right corner.
+
+## Supported versions
+
+The Ruby × Rails combinations exercised by CI on every push and pull request:
+
+| Rails | Ruby                             |
+| ----- | -------------------------------- |
+| 5.2   | 2.7                              |
+| 6.0   | 2.7, 3.0                         |
+| 6.1   | 2.7, 3.0, 3.1, 3.2               |
+| 7.0   | 2.7, 3.0, 3.1, 3.2, 3.3          |
+| 7.1   | 3.1, 3.2, 3.3, 3.4               |
+| 7.2   | 3.1, 3.2, 3.3, 3.4               |
+| 8.0   | 3.2, 3.3, 3.4, 4.0               |
+| 8.1   | 3.2, 3.3, 3.4, 4.0               |
+
+Other combinations may work but are not verified.
+
 ## Configuration
 
 `./config/mermaid_erd.yml` to customize the configuration.
@@ -73,6 +107,7 @@ The setting items are as follows.
 | key | description | default |
 | --- | --- | --- |
 | `result_path` | Destination of generated files. | `mermaid_erd/index.html` |
+| `ignore_tables` | Array of regular-expression strings. Tables whose `table_name` matches any pattern are dropped from the generated ERD, along with any relations that point at them. Useful for excluding audit-log models, soft-deleted/legacy tables, or other large noise you don't want to render. Patterns are compiled with `Regexp.new`, so escape backslashes inside YAML strings (e.g. `"\\Aaudit_"`). | `[]` |
 
 <!--
 TODO:

data/lib/rails-mermaid_erd/builder.rb

@@ -1,5 +1,3 @@
-require "yaml"
-
 class RailsMermaidErd::Builder
   class << self
     def model_data
@@ -9,10 +7,28 @@ class RailsMermaidErd::Builder
       }
 
       ::Rails.application.eager_load!
+
+      # Compile each `ignore_tables` entry once. Wrap `RegexpError` so the
+      # rake-task output names the offending YAML entry rather than just the
+      # underlying parser message.
+      ignore_patterns = RailsMermaidErd.configuration.ignore_tables.map do |pattern|
+        Regexp.new(pattern)
+      rescue RegexpError => e
+        raise ArgumentError, "config/mermaid_erd.yml: invalid `ignore_tables` pattern #{pattern.inspect}: #{e.message}"
+      end
+
+      # Class names whose `table_name` matches an ignore pattern. Resolved
+      # *before* the main loop so we can also drop outgoing reflections that
+      # point at an ignored model — otherwise the diagram would render orphan
+      # nodes for the ignored tables. A Hash gives O(1) `key?` lookups without
+      # pulling in `set` (which is autoloaded on Ruby 3.2+ but not earlier).
+      ignored_model_names = compute_ignored_model_names(ignore_patterns)
+
       ::ActiveRecord::Base.descendants.sort_by(&:name).each do |defined_model|
         next unless defined_model.table_exists?
         next if defined_model.name.include?("HABTM_")
         next if defined_model.table_name.blank?
+        next if ignored_model_names.key?(defined_model.name)
 
         table_name = defined_model.table_name
         model = {
@@ -44,6 +60,7 @@ class RailsMermaidErd::Builder
 
         defined_model.reflect_on_all_associations(:has_many).each do |reflection|
           reflection_model_name = get_reflection_model_name(reflection)
+          next if ignored_model_names.key?(reflection_model_name)
 
           reverse_relation = result[:Relations].find { |r|
             if reflection.options[:through]
@@ -72,6 +89,7 @@ class RailsMermaidErd::Builder
 
         defined_model.reflect_on_all_associations(:has_and_belongs_to_many).each do |reflection|
           reflection_model_name = get_reflection_model_name(reflection)
+          next if ignored_model_names.key?(reflection_model_name)
 
           reverse_relation = result[:Relations].find { |r| r[:RightModelName] == model[:ModelName] && r[:LeftModelName] == reflection_model_name }
           if reverse_relation
@@ -89,7 +107,15 @@ class RailsMermaidErd::Builder
         end
 
         defined_model.reflect_on_all_associations(:belongs_to).each do |reflection|
+          # Polymorphic `belongs_to` has no concrete target class — the target is
+          # decided at row level by the `*_type` column. Emitting an edge to the
+          # macro name (e.g. `"Imageable"`) would render an orphan node with no
+          # columns; the polymorphic parents express the relationship via their
+          # `has_many ..., as: :foo` reflections instead.
+          next if reflection.polymorphic?
+
           reflection_model_name = get_reflection_model_name(reflection)
+          next if ignored_model_names.key?(reflection_model_name)
 
           reverse_relation = result[:Relations].find { |r| r[:RightModelName] == model[:ModelName] && r[:LeftModelName] == reflection_model_name }
           if reverse_relation
@@ -116,6 +142,7 @@ class RailsMermaidErd::Builder
 
         defined_model.reflect_on_all_associations(:has_one).each do |reflection|
           reflection_model_name = get_reflection_model_name(reflection)
+          next if ignored_model_names.key?(reflection_model_name)
 
           reverse_relation = result[:Relations].find { |r|
             if reflection.options[:through]
@@ -147,13 +174,38 @@ class RailsMermaidErd::Builder
       result
     end
 
+    # Returns a Hash keyed by class names whose underlying table matches an
+    # entry from `ignore_tables`. Mirrors the guard rails on the main loop
+    # (`table_exists?`, HABTM scaffolding, blank `table_name`) so that adding
+    # an `ignore_tables` entry can't crash the rake task on hosts with
+    # abstract STI bases or descendants whose backing table isn't created yet.
+    def compute_ignored_model_names(ignore_patterns)
+      return {} if ignore_patterns.empty?
+
+      ::ActiveRecord::Base.descendants.each_with_object({}) do |defined_model, acc|
+        next unless defined_model.table_exists?
+        next if defined_model.name.include?("HABTM_")
+        table_name = defined_model.table_name
+        next if table_name.blank?
+        acc[defined_model.name] = true if ignore_patterns.any? { |pattern| pattern.match?(table_name) }
+      end
+    end
+
     # Doc: https://guides.rubyonrails.org/association_basics.html
     def get_reflection_model_name(reflection)
       if reflection.options[:class_name]
         reflection.options[:class_name].to_s.classify
       elsif reflection.options[:through]
-        if reflection.options[:source]
+        # `:source_type` is the authoritative class hint for a polymorphic
+        # `:source`, so it takes precedence over `:source` when both are set.
+        if reflection.options[:source_type]
+          reflection.options[:source_type].to_s.classify
+        elsif reflection.options[:source]
           reflection.options[:source].to_s.classify
+        elsif reflection.source_reflection.nil?
+          # `:through` targets a polymorphic `belongs_to` without `:source_type`;
+          # Rails can't resolve a single class. Fall back to its `:source` default.
+          reflection.name.to_s.classify
         else
           reflection.class_name
         end

data/lib/rails-mermaid_erd/configuration.rb

@@ -1,19 +1,45 @@
 require "yaml"
 
 class RailsMermaidErd::Configuration
-  attr_accessor :result_path
+  attr_accessor :result_path, :ignore_tables
+
+  DEFAULTS = {
+    result_path: "mermaid_erd/index.html",
+    ignore_tables: []
+  }.freeze
 
   def initialize
-    config = {
-      result_path: "mermaid_erd/index.html"
-    }
+    config = DEFAULTS.dup
 
     config_file = Rails.root.join("config/mermaid_erd.yml")
     if File.exist?(config_file)
-      custom_config = YAML.load(config_file.read).symbolize_keys
+      # `safe_load` over `load` because this file is checked into the host
+      # repo and may eventually be templated from CI inputs. Disallow custom
+      # classes and aliases — the only legitimate value shapes here are
+      # strings and arrays of strings.
+      custom_config = YAML.safe_load(config_file.read, permitted_classes: [], aliases: false).symbolize_keys
       config = config.merge(custom_config)
     end
 
     @result_path = config[:result_path]
+    @ignore_tables = normalize_ignore_tables(config[:ignore_tables])
+  end
+
+  private
+
+  # Accept `nil` as "no patterns", reject anything that isn't an Array of
+  # non-empty Strings. We validate eagerly so a malformed config surfaces a
+  # clear ArgumentError at boot rather than a confusing `NoMethodError` deep
+  # in `Builder.model_data`. The empty-string rejection in particular blocks
+  # the silent footgun of `Regexp.new("")` matching every table.
+  def normalize_ignore_tables(value)
+    return [] if value.nil?
+
+    unless value.is_a?(Array) && value.all? { |entry| entry.is_a?(String) && !entry.empty? }
+      raise ArgumentError,
+        "config/mermaid_erd.yml: `ignore_tables` must be an array of non-empty regex strings, got #{value.inspect}"
+    end
+
+    value
   end
 end

data/lib/rails-mermaid_erd/mermaid_text.rb

@@ -0,0 +1,74 @@
+class RailsMermaidErd::MermaidText
+  # Renders the schema dump from RailsMermaidErd::Builder.model_data into
+  # Mermaid `erDiagram` source text.
+  #
+  # This is the *maximal* projection of the bundled front-end viewer
+  # (lib/templates/index.html.erb): the dump always shows every table, every
+  # column with its key marker and comment, and every relation label — i.e.
+  # the diagram the viewer produces with all of its detail toggles ("Show
+  # key", "Show comment", "Show relation comment") enabled and with no
+  # model-selection filtering. The viewer defaults those toggles off, so the
+  # dump is deliberately more detailed than the viewer's initial view. The only
+  # thing it drops is the viewer's "Restore Hash" comment line, which encodes
+  # browser-only UI state and is meaningless on the command line. Apart from
+  # that line and a single trailing newline (added by the rake task's `puts`),
+  # it is byte-identical to the viewer's "all toggles on" output.
+  #
+  # Comment values come from arbitrary DB metadata, so they are sanitised the
+  # same way the viewer's renderer must (and now does): newlines collapse to a
+  # space (a newline would split a label or terminate a `%%` line mid-diagram)
+  # and a literal `"` becomes Mermaid's `#quot;` entity (an unescaped quote
+  # closes the quoted label early). Keep this byte-aligned with the viewer at
+  # index.html.erb:809-845.
+  HEADER = [
+    "erDiagram",
+    "    %% --------------------------------------------------------",
+    '    %% Generated by "Rails Mermaid ERD"',
+    "    %% https://github.com/koedame/rails-mermaid_erd",
+    "    %% --------------------------------------------------------",
+    ""
+  ].freeze
+
+  class << self
+    # `result` is the hash returned by RailsMermaidErd::Builder.model_data.
+    def build(result)
+      lines = HEADER.dup
+
+      result[:Models].each do |model|
+        lines << "    %% table name: #{one_line(model[:TableName])}"
+        lines << "    %% table comment: #{one_line(model[:TableComment])}"
+        # Mermaid entity names can't contain ":", so namespaced models like
+        # `Admin::User` are written as `Admin-User` (matches the front-end).
+        lines << "    #{model[:ModelName].tr(":", "-")} {"
+        model[:Columns].each do |column|
+          lines << "        #{column[:type]} #{column[:name]} #{column[:key]} #{quoted(column[:comment])}"
+        end
+        lines << "    }"
+        lines << ""
+      end
+
+      result[:Relations].each do |relation|
+        left = relation[:LeftModelName].tr(":", "-")
+        right = relation[:RightModelName].tr(":", "-")
+        lines << "    #{left} #{relation[:LeftValue]}#{relation[:Line]}#{relation[:RightValue]} #{right} : #{quoted(relation[:Comment])}"
+      end
+
+      lines.join("\n")
+    end
+
+    private
+
+    # Collapse newlines so a value can't split a label or terminate a `%%`
+    # comment line mid-diagram.
+    def one_line(value)
+      value.to_s.gsub(/[\r\n]+/, " ")
+    end
+
+    # A Mermaid quoted label: newline-free, with `"` escaped to the `#quot;`
+    # entity so a comment can't close the string early.
+    def quoted(value)
+      escaped = one_line(value).gsub('"', "#quot;")
+      "\"#{escaped}\""
+    end
+  end
+end

data/lib/rails-mermaid_erd/railtie.rb

@@ -0,0 +1,12 @@
+module RailsMermaidErd
+  # Registers the `mermaid_erd` rake task only when Rails is actually loading
+  # tasks (i.e. under `rake`/`rails` CLIs, never on web/console/job boots).
+  # Pairs with the `autoload` declarations in lib/rails-mermaid_erd.rb so the
+  # heavy `Builder` / `Configuration` constants — and the `erb`/`fileutils`
+  # requires their task body needs — stay off the boot path entirely.
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/mermaid_erd.rake", __dir__)
+    end
+  end
+end

data/lib/rails-mermaid_erd/version.rb

@@ -1,3 +1,3 @@
 module RailsMermaidErd
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/rails-mermaid_erd.rb

@@ -1,34 +1,33 @@
-require "erb"
-require "fileutils"
-require "rake"
-require "rake/dsl_definition"
 require_relative "rails-mermaid_erd/version"
-require_relative "rails-mermaid_erd/configuration"
-require_relative "rails-mermaid_erd/builder"
 
 module RailsMermaidErd
-  extend Rake::DSL
+  # Resolve `Builder` and `Configuration` lazily so requiring this file from
+  # Bundler's auto-require on every Rails boot (web, console, jobs) only pays
+  # for the Railtie declaration below. The actual classes — plus their
+  # transitive `yaml` require — load on first reference, which in practice
+  # means "when the rake task runs."
+  autoload :Builder, "rails-mermaid_erd/builder"
+  autoload :Configuration, "rails-mermaid_erd/configuration"
+  autoload :MermaidText, "rails-mermaid_erd/mermaid_text"
 
   class << self
     def configuration
-      @configuration ||= RailsMermaidErd::Configuration.new
+      @configuration ||= Configuration.new
     end
-  end
-
-  desc "Generate Mermaid ERD."
-  task mermaid_erd: :environment do
-    result = RailsMermaidErd::Builder.model_data
-
-    version = VERSION
-    app_name = ::Rails.application.class.try(:parent_name) || ::Rails.application.class.try(:module_parent_name)
-    logo = File.read(File.expand_path("./assets/logo.svg", __dir__))
-    erb = ERB.new(File.read(File.expand_path("./templates/index.html.erb", __dir__)))
-    result_html = erb.result(binding)
 
-    result_dir = Rails.root.join(File.dirname(RailsMermaidErd.configuration.result_path))
-    FileUtils.mkdir_p(result_dir)
-
-    result_file = Rails.root.join(RailsMermaidErd.configuration.result_path)
-    File.write(result_file, result_html)
+    # File.read with a domain-specific error when the bundled asset is missing,
+    # which usually means a broken gem install (e.g. lib/templates/vendor/ got
+    # pruned). The default Errno::ENOENT just points at this file and is hard
+    # to act on.
+    def read_gem_asset(relative_path)
+      path = File.expand_path(relative_path, __dir__)
+      File.read(path)
+    rescue Errno::ENOENT
+      raise "rails-mermaid_erd: bundled asset missing at #{path}. " \
+            "The gem appears to be incompletely installed; " \
+            "try `gem pristine rails-mermaid_erd` or reinstall the gem."
+    end
   end
 end
+
+require_relative "rails-mermaid_erd/railtie" if defined?(Rails::Railtie)

data/lib/tasks/mermaid_erd.rake

@@ -0,0 +1,61 @@
+require "erb"
+require "fileutils"
+# Explicit `require_relative` rather than leaning on the module's `autoload`:
+# if the gem install is broken (e.g. lib/rails-mermaid_erd/builder.rb pruned),
+# we want a LoadError with the missing path here — not a NameError raised
+# deep inside the task body where the cause is harder to diagnose.
+require_relative "../rails-mermaid_erd/builder"
+require_relative "../rails-mermaid_erd/configuration"
+require_relative "../rails-mermaid_erd/mermaid_text"
+
+desc "Generate Mermaid ERD."
+task mermaid_erd: :environment do
+  result = RailsMermaidErd::Builder.model_data
+
+  version = RailsMermaidErd::VERSION
+  app_name = ::Rails.application.class.try(:parent_name) || ::Rails.application.class.try(:module_parent_name)
+  logo = RailsMermaidErd.read_gem_asset("./assets/logo.svg")
+  tailwindcss_js = RailsMermaidErd.read_gem_asset("./templates/vendor/tailwindcss.js")
+  mermaid_js = RailsMermaidErd.read_gem_asset("./templates/vendor/mermaid.min.js")
+  vue_js = RailsMermaidErd.read_gem_asset("./templates/vendor/vue.global.prod.min.js")
+  erb = ERB.new(RailsMermaidErd.read_gem_asset("./templates/index.html.erb"))
+  result_html = erb.result(binding)
+
+  result_file = ::Rails.root.join(RailsMermaidErd.configuration.result_path)
+  result_dir = result_file.dirname
+
+  # Re-raise filesystem failures with an actionable hint pointing at the
+  # `result_path` config key, mirroring the friendly error in
+  # `RailsMermaidErd.read_gem_asset`. Without this the user just sees a raw
+  # `Errno::EACCES` / `Errno::ENOSPC` and has to guess which knob controls it.
+  begin
+    FileUtils.mkdir_p(result_dir)
+    File.write(result_file, result_html)
+  rescue SystemCallError => e
+    raise "rails-mermaid_erd: could not write ERD to #{result_file} (#{e.class}: #{e.message}). " \
+          "Check the `result_path` key in config/mermaid_erd.yml and that the directory is writable."
+  end
+end
+
+namespace :mermaid_erd do
+  desc "Print Mermaid ERD source to stdout."
+  task print: :environment do
+    # Builder calls `ActiveRecord::Schema.foreign_keys`, whose migration-style
+    # `-- foreign_keys(...)` / `-> 0.001s` logging would otherwise land on
+    # stdout and corrupt the piped diagram. Mute it just for the build, and
+    # restore it in `ensure` so an error mid-build can't leak the muted global
+    # into later tasks running in the same process.
+    was_verbose = ActiveRecord::Migration.verbose
+    ActiveRecord::Migration.verbose = false
+    result =
+      begin
+        RailsMermaidErd::Builder.model_data
+      ensure
+        ActiveRecord::Migration.verbose = was_verbose
+      end
+
+    # Stream the raw `erDiagram` text to stdout so it pipes into other tools
+    # (`> er.mmd`, `| mmdc -i - -o er.svg`) without writing the HTML viewer.
+    $stdout.puts RailsMermaidErd::MermaidText.build(result)
+  end
+end