rails-mermaid_erd 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f3cfe23f8fa1343b2bd8a3ac5d47c1967613ce7a832d65de858b363402db0b1
-  data.tar.gz: 146d83e00452b8c56cbf8c4c6e0aebd62f99b3224e6b7e3062b4889b55bf0723
+  metadata.gz: 02a09db4c8fe0efe3647b171cd713eb46664a961c36eb820691b069f1dec82b2
+  data.tar.gz: 0bc7bec06228e7a2e03055b0b82a9ff63031ef2e6ce008e0e3c7edbf6044128b
 SHA512:
-  metadata.gz: 2c68987537096806829a9709f477dd8cc8a0108291387ff670796d2c41c4a900fe0f1a55902381b12d582d4e66d77f2b0421d929dfc72060a10d5b9ed020c4a6
-  data.tar.gz: 04cbecd36399c810f0846e1d4c4275922acfeb1ec2bcf426440f08902db6b4b051368f57ec57a0f8259108d9f727b77d0760ee0f817aee8122e4f3952dcfcc58
+  metadata.gz: 5228d44560de7ae4bc244b7854a926144eee9ef1b1d16c77ddd71b999e1b260ccc3ae6de468968de1a208b2257d31121445366c72e0e9df932a9c61a751019b0
+  data.tar.gz: 856f64ddfa060ce33f859fe914c4be5ce93bd9898e3c75ec5ab2fa8fe2657ab2063b3bd56129e869af52723844c9e4b22e36085842813b5ceb672fd6e44ed180

data/README.md

@@ -58,11 +58,29 @@ 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.
 
+## 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 +91,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/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.7.0"
 end

data/lib/rails-mermaid_erd.rb

@@ -1,34 +1,32 @@
-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"
 
   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,37 @@
+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"
+
+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