rails-erd 2.0.2 → 2.1.0

data/lib/rails_erd/diagram/mermaid.rb

@@ -15,6 +15,16 @@ module RailsERD
         # Respect orientation option: horizontal = TB (top-down), vertical = LR (left-right)
         direction = (options.orientation.to_s == "vertical") ? "LR" : "TB"
         self.graph << "\tdirection #{direction}"
+
+        # Initialize namespace grouping for clustering
+        @entities_by_namespace = Hash.new { |h, k| h[k] = [] }
+        @clustering_enabled = options[:cluster] && !er_diagram?
+        @clustered_entities_emitted = false
+
+        # Warn if clustering requested with erDiagram (not supported)
+        if options[:cluster] && er_diagram? && options[:warn]
+          warn "Clustering is not supported with erDiagram style. Use mermaid_style: classdiagram instead."
+        end
       end
 
       each_entity do |entity, attributes|
@@ -28,6 +38,12 @@ module RailsERD
           end
           entity_lines << "\t}"
           graph << entity_lines.join("\n")
+        elsif @clustering_enabled
+          # Collect entities by namespace for later emission
+          ns = entity.namespace || ""
+          short_name = entity.namespace ? entity.name.split("::").last : entity.name
+          entity_block = build_class_diagram_entity(short_name, entity.name, attributes)
+          @entities_by_namespace[ns] << entity_block
         else
           graph << "\tclass `#{entity}`"
           attributes.each do |attr|
@@ -37,6 +53,12 @@ module RailsERD
       end
 
       each_specialization do |specialization|
+        # Emit clustered entities before the first specialization (same as relationships)
+        if @clustering_enabled && !@clustered_entities_emitted
+          emit_clustered_entities
+          @clustered_entities_emitted = true
+        end
+
         from, to = specialization.generalized, specialization.specialized
         if er_diagram?
           # erDiagram doesn't have a direct polymorphic notation, use inheritance-like
@@ -48,6 +70,12 @@ module RailsERD
       end
 
       each_relationship do |relationship|
+        # Emit clustered entities before the first relationship
+        if @clustering_enabled && !@clustered_entities_emitted
+          emit_clustered_entities
+          @clustered_entities_emitted = true
+        end
+
         from, to = relationship.source, relationship.destination
         next unless from && to
 
@@ -77,6 +105,12 @@ module RailsERD
       save do
         raise "Saving diagram failed!\nOutput directory '#{File.dirname(filename)}' does not exist." unless File.directory?(File.dirname(filename))
 
+        # Emit clustered entities if not already emitted (e.g., no relationships)
+        if @clustering_enabled && !@clustered_entities_emitted
+          emit_clustered_entities
+          @clustered_entities_emitted = true
+        end
+
         File.write(filename.gsub(/\s/,"_"), graph.uniq.join("\n"))
         filename
       end
@@ -159,6 +193,36 @@ module RailsERD
         relationship.many_to? ? "<" : ""
       end
 
+      # Build entity lines for classDiagram mode (used in clustering)
+      def build_class_diagram_entity(short_name, full_name, attributes)
+        lines = ["\t\tclass `#{short_name}`"]
+        attributes.each do |attr|
+          lines << "\t\t`#{short_name}` : +#{attr.type} #{attr.name}"
+        end
+        lines
+      end
+
+      # Emit entities grouped by namespace for clustering
+      def emit_clustered_entities
+        # Entities without namespace go first (outside any namespace block)
+        @entities_by_namespace[""].each do |entity_lines|
+          entity_lines.each { |line| graph << line.sub(/^\t\t/, "\t") }
+        end
+
+        # Then emit each namespace block
+        @entities_by_namespace.each do |ns, entity_blocks|
+          next if ns == ""
+
+          # Convert Ruby namespace (Admin::Users) to Mermaid format (Admin.Users)
+          mermaid_ns = ns.gsub("::", ".")
+          graph << "\tnamespace #{mermaid_ns} {"
+          entity_blocks.each do |entity_lines|
+            entity_lines.each { |line| graph << line }
+          end
+          graph << "\t}"
+        end
+      end
+
     end
   end
 end

data/lib/rails_erd/diagram/tbls.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "rails_erd/diagram"
+require "json"
+
+module RailsERD
+  class Diagram
+    # Emits a JSON description of the domain in the tbls schema format
+    # (https://github.com/k1LoW/tbls). Consumable by any tbls-compatible tool —
+    # for example Liam ERD: `liam erd build --input erd.json --format tbls`.
+    #
+    # Unlike a schema.rb dump, this reflects the relationships rails-erd derives
+    # from ActiveRecord — including FKs that exist only as `belongs_to`
+    # associations and not as DB-level constraints.
+    class Tbls < Diagram
+      attr_accessor :tables_by_name
+
+      setup do
+        self.tables_by_name = {}
+      end
+
+      each_entity do |entity, _attributes|
+        next if entity.generalized?
+        next unless entity.model
+
+        table_name = entity.model.table_name
+        next if tables_by_name.key?(table_name)
+
+        tables_by_name[table_name] = build_table(entity)
+      end
+
+      each_relationship do |relationship|
+        next if relationship.indirect?
+        next unless relationship.source && relationship.destination
+        next if relationship.source.generalized? || relationship.destination.generalized?
+
+        add_foreign_keys(relationship)
+      end
+
+      save do
+        dir = File.dirname(filename)
+        raise "Saving diagram failed!\nOutput directory '#{dir}' does not exist." unless File.directory?(dir)
+
+        File.write(filename, JSON.pretty_generate(schema_payload))
+        filename
+      end
+
+      def filename
+        "#{options.filename}.json"
+      end
+
+      private
+
+      def schema_payload
+        {
+          name: domain.name || "rails-erd",
+          tables: tables_by_name.values,
+        }
+      end
+
+      def build_table(entity)
+        model = entity.model
+        comment = model.respond_to?(:table_comment) ? model.table_comment : nil
+        payload = {
+          name: model.table_name,
+          type: "BASE TABLE",
+          columns: entity.attributes.map { |attr| column_payload(attr) },
+          indexes: indexes_payload(model),
+          constraints: primary_key_constraints(model),
+        }
+        payload[:comment] = comment if comment && !comment.empty?
+        payload
+      end
+
+      def column_payload(attr)
+        column = attr.column
+        payload = {
+          name: column.name,
+          type: column.sql_type.to_s,
+          nullable: column.null,
+        }
+        payload[:default] = column.default.to_s unless column.default.nil?
+        comment = column.comment if column.respond_to?(:comment)
+        payload[:comment] = comment if comment && !comment.empty?
+        payload
+      end
+
+      def indexes_payload(model)
+        return [] unless model.connection.respond_to?(:indexes)
+
+        model.connection.indexes(model.table_name).map do |idx|
+          columns = Array(idx.columns).map(&:to_s)
+          {
+            name: idx.name,
+            def: index_def(model.table_name, idx, columns),
+            table: model.table_name,
+            columns: columns,
+          }
+        end
+      rescue StandardError
+        []
+      end
+
+      def index_def(table_name, idx, columns)
+        unique = idx.unique ? "UNIQUE " : ""
+        "CREATE #{unique}INDEX #{idx.name} ON #{table_name} (#{columns.join(", ")})"
+      end
+
+      def primary_key_constraints(model)
+        pk = Array(model.primary_key).compact.map(&:to_s)
+        return [] if pk.empty?
+
+        [{
+          name: "#{model.table_name}_pkey",
+          type: "PRIMARY KEY",
+          def: "PRIMARY KEY (#{pk.join(", ")})",
+          table: model.table_name,
+          referenced_table: "",
+          columns: pk,
+        }]
+      end
+
+      def add_foreign_keys(relationship)
+        relationship.associations.each do |assoc|
+          next if assoc.options[:polymorphic]
+          next unless assoc.belongs_to?
+
+          fk_columns = Array(assoc.send(Domain.foreign_key_method_name)).map(&:to_s).reject(&:empty?)
+          next if fk_columns.empty?
+
+          target_model = safe_klass(assoc)
+          next unless target_model
+
+          target_pk = Array(target_model.primary_key).compact.map(&:to_s)
+          next if target_pk.empty?
+
+          owning_table = assoc.active_record.table_name
+          target_table = target_model.table_name
+          name = "fk_#{owning_table}_#{fk_columns.join("_")}"
+
+          add_constraint(owning_table, {
+            name: name,
+            type: "FOREIGN KEY",
+            def: "FOREIGN KEY (#{fk_columns.join(", ")}) REFERENCES #{target_table}(#{target_pk.join(", ")})",
+            table: owning_table,
+            referenced_table: target_table,
+            columns: fk_columns,
+            referenced_columns: target_pk,
+          })
+        end
+      end
+
+      def safe_klass(association)
+        association.klass
+      rescue NameError
+        nil
+      end
+
+      def add_constraint(table_name, constraint)
+        table = tables_by_name[table_name]
+        return unless table
+        return if table[:constraints].any? { |c| c[:name] == constraint[:name] }
+
+        table[:constraints] << constraint
+      end
+    end
+  end
+end

data/lib/rails_erd/diagram.rb

@@ -231,8 +231,7 @@ module RailsERD
 
     def filtered_entities
       @domain.entities.reject { |entity|
-        options.exclude.present? && [options.exclude].flatten.map(&:to_sym).include?(entity.name.to_sym) or
-        options[:only].present? && entity.model && ![options[:only]].flatten.map(&:to_sym).include?(entity.name.to_sym) or
+        excluded_by_filter?(entity) or
         !options.inheritance && entity.specialized? or
         !options.polymorphism && entity.generalized? or
         !options.disconnected && entity.disconnected?
@@ -243,14 +242,75 @@ module RailsERD
 
     def filtered_relationships
       @domain.relationships.reject { |relationship|
-        !options.indirect && relationship.indirect?
+        (!options.indirect && relationship.indirect?) ||
+          # Drop relationships to a model removed by :only/:exclude, otherwise the filtered-out
+          # model leaks back in: Graphviz skips such edges implicitly (it only draws an edge when
+          # both nodes exist) but Mermaid emits every relationship and renders any named entity.
+          excluded_by_filter?(relationship.source) ||
+          excluded_by_filter?(relationship.destination)
       }
     end
 
+    # Whether the entity was removed from the diagram by the :only or :exclude option.
+    # Used to filter both entities and the relationships that touch them.
+    #
+    def excluded_by_filter?(entity)
+      name = entity.name.to_s
+
+      if options.exclude.present?
+        patterns = [options.exclude].flatten
+        return true if patterns.any? { |pattern| matches_pattern?(pattern, name) }
+      end
+
+      if options[:only].present? && entity.model
+        patterns = [options[:only]].flatten
+        return true unless patterns.any? { |pattern| matches_pattern?(pattern, name) }
+      end
+
+      false
+    end
+
+    # Matches a name against a pattern. Supports three pattern types:
+    #
+    # - Exact match: "Foo" matches only "Foo"
+    # - Glob pattern: "SolidQueue::*" matches "SolidQueue::Job", etc.
+    # - Regex pattern: "/^Active/" matches "ActiveRecord", "ActiveStorage::Blob"
+    #
+    def matches_pattern?(pattern, name)
+      pattern_str = pattern.to_s
+
+      # Regex pattern: /pattern/ or /pattern/flags
+      #
+      if pattern_str.start_with?("/") && pattern_str =~ %r{\A/(.+)/([imx]*)\z}
+        regex_body = Regexp.last_match(1)
+        flags_str = Regexp.last_match(2)
+        flags = 0
+        flags |= Regexp::IGNORECASE if flags_str.include?("i")
+        flags |= Regexp::MULTILINE if flags_str.include?("m")
+        flags |= Regexp::EXTENDED if flags_str.include?("x")
+        return Regexp.new(regex_body, flags).match?(name.to_s)
+      end
+
+      # Glob pattern: contains *, ?, or [
+      #
+      if pattern_str.include?("*") || pattern_str.include?("?") || pattern_str.include?("[")
+        return File.fnmatch?(pattern_str, name.to_s)
+      end
+
+      # Exact match (backward compatible)
+      pattern_str == name.to_s
+    end
+
     def filtered_specializations
       @domain.specializations.reject { |specialization|
         !options.inheritance && specialization.inheritance? or
-        !options.polymorphism && specialization.polymorphic?
+        !options.polymorphism && specialization.polymorphic? or
+        # Drop specializations whose generalized or specialized entity is not
+        # part of the rendered domain (e.g. an abstract parent whose child model
+        # has no table). These resolve to a Null entity with a blank name and
+        # would otherwise produce an edge to a nameless entity (invalid output).
+        specialization.generalized.name.to_s.empty? or
+        specialization.specialized.name.to_s.empty?
       }
     end
 
@@ -258,12 +318,14 @@ module RailsERD
       excluded = excluded_attributes_for(entity)
       return [] if excluded == :all
 
-      entity.attributes.reject { |attribute|
+      entity.attributes.select { |attribute|
         # Hide attributes excluded for this specific model.
-        excluded.include?(attribute.name) or
-        # Select attributes that satisfy the conditions in the :attributes option.
-        !options.attributes or entity.specialized? or
-        [*options.attributes].none? { |type| attribute.send(:"#{type.to_s.chomp('s')}?") }
+        next false if excluded.include?(attribute.name)
+        # Hide every attribute when the :attributes option is off or the entity
+        # is specialized (its attributes are shown on the parent instead).
+        next false if !options.attributes || entity.specialized?
+        # Otherwise keep only attributes matching the requested :attributes types.
+        [*options.attributes].any? { |type| attribute.send(:"#{type.to_s.chomp('s')}?") }
       }
     end
 

data/lib/rails_erd/domain.rb

@@ -128,6 +128,7 @@ module RailsERD
                     .reject { |model| tableless_rails_models.include?(model) }
                     .select { |model| check_model_validity(model) }
                     .reject { |model| check_habtm_model(model) }
+                    .sort_by { |model| model.name.to_s }
     end
 
     # Returns Rails model classes defined in the app
@@ -187,7 +188,39 @@ module RailsERD
     def excluded_model?(model)
       return false unless options.exclude.present?
 
-      [options.exclude].flatten.map(&:to_sym).include?(model.name.to_sym)
+      patterns = [options.exclude].flatten
+      patterns.any? { |pattern| matches_pattern?(pattern, model.name) }
+    end
+
+    # Matches a name against a pattern. Supports three pattern types:
+    #
+    # - Exact match: "Foo" matches only "Foo"
+    # - Glob pattern: "SolidQueue::*" matches "SolidQueue::Job", etc.
+    # - Regex pattern: "/^Active/" matches "ActiveRecord", "ActiveStorage::Blob"
+    #
+    def matches_pattern?(pattern, name)
+      pattern_str = pattern.to_s
+
+      # Regex pattern: /pattern/ or /pattern/flags
+      #
+      if pattern_str.start_with?("/") && pattern_str =~ %r{\A/(.+)/([imx]*)\z}
+        regex_body = Regexp.last_match(1)
+        flags_str = Regexp.last_match(2)
+        flags = 0
+        flags |= Regexp::IGNORECASE if flags_str.include?("i")
+        flags |= Regexp::MULTILINE if flags_str.include?("m")
+        flags |= Regexp::EXTENDED if flags_str.include?("x")
+        return Regexp.new(regex_body, flags).match?(name.to_s)
+      end
+
+      # Glob pattern: contains *, ?, or [
+      #
+      if pattern_str.include?("*") || pattern_str.include?("?") || pattern_str.include?("[")
+        return File.fnmatch?(pattern_str, name.to_s)
+      end
+
+      # Exact match (backward compatible)
+      pattern_str == name.to_s
     end
 
     def check_association_validity(association)
@@ -207,13 +240,14 @@ module RailsERD
     def excluded_association?(association)
       return false unless options.exclude.present?
 
-      excluded_names = [options.exclude].flatten.map(&:to_sym)
+      patterns = [options.exclude].flatten
 
       # Suppress warning if either the source model or target model is excluded
-      return true if excluded_names.include?(association.active_record.name.to_sym)
+      source_name = association.active_record.name
+      return true if patterns.any? { |pattern| matches_pattern?(pattern, source_name) }
 
       target_name = association.options[:polymorphic] ? association.class_name : association.klass.name
-      target_name && excluded_names.include?(target_name.to_sym)
+      target_name && patterns.any? { |pattern| matches_pattern?(pattern, target_name) }
     rescue NameError
       # If we can't determine the target class, the source model was already checked above
       false

data/lib/rails_erd/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module RailsERD
-  VERSION = "2.0.2"
+  VERSION = "2.1.0"
   BANNER  = "RailsERD #{VERSION}"
 end

data/test/unit/diagram_test.rb

@@ -165,6 +165,76 @@ class DiagramTest < ActiveSupport::TestCase
     assert_equal [Author, Editor], retrieve_entities(:only => ['Author', 'Editor']).map(&:model)
   end
 
+  test "generate should exclude relationships whose endpoints were removed by :only" do
+    create_model "Author"
+    create_model "Book", :author => :references do
+      belongs_to :author
+      has_many :reviews
+    end
+    create_model "Review", :book => :references do
+      belongs_to :book
+    end
+    relationships = retrieve_relationships(:only => [:Author, :Book])
+    assert_equal [Set[Author, Book]], relationships.map { |r| Set[r.source.model, r.destination.model] }
+  end
+
+  test "generate should exclude relationships to an excluded entity" do
+    create_model "Author"
+    create_model "Book", :author => :references do
+      belongs_to :author
+      has_many :reviews
+    end
+    create_model "Review", :book => :references do
+      belongs_to :book
+    end
+    relationships = retrieve_relationships(:exclude => [:Review])
+    assert_equal [Set[Author, Book]], relationships.map { |r| Set[r.source.model, r.destination.model] }
+  end
+
+  # Pattern matching for exclude/only ==========================================
+  test "generate should filter entities matching glob pattern in exclude" do
+    create_module_model "SolidQueue::Job"
+    create_module_model "SolidQueue::Process"
+    create_model "User"
+    assert_equal [User], retrieve_entities(:exclude => ["SolidQueue::*"]).map(&:model)
+  end
+
+  test "generate should filter entities matching regex pattern in exclude" do
+    create_module_model "SolidQueue::Job"
+    create_model "User"
+    assert_equal [User], retrieve_entities(:exclude => ["/^Solid/"]).map(&:model)
+  end
+
+  test "generate should include only entities matching glob pattern in only" do
+    create_module_model "MyApp::User"
+    create_module_model "MyApp::Post"
+    create_model "SomeOther"
+    entities = retrieve_entities(:only => ["MyApp::*"]).map(&:model)
+    assert_includes entities, MyApp::User
+    assert_includes entities, MyApp::Post
+    refute_includes entities, SomeOther
+  end
+
+  test "generate should include only entities matching regex pattern in only" do
+    create_model "AdminUser"
+    create_model "AdminPost"
+    create_model "GuestUser"
+    entities = retrieve_entities(:only => ["/^Admin/"]).map(&:model)
+    assert_includes entities, AdminUser
+    assert_includes entities, AdminPost
+    refute_includes entities, GuestUser
+  end
+
+  test "generate should exclude relationships when endpoint matches glob pattern" do
+    create_module_model "SolidQueue::Job"
+    create_model "Task", :solid_queue_job => :references do
+      belongs_to :solid_queue_job, :class_name => "SolidQueue::Job"
+    end
+    create_model "User"
+    relationships = retrieve_relationships(:exclude => ["SolidQueue::*"])
+    assert_equal [], relationships
+  end
+
   test "generate should filter disconnected entities if disconnected is false" do
     create_model "Book", :author => :references do
       belongs_to :author
@@ -235,7 +305,7 @@ class DiagramTest < ActiveSupport::TestCase
     create_model "Baz", :foo => :references do
       belongs_to :foo
     end
-    assert_equal [false, false, true], retrieve_relationships(:indirect => true).map(&:indirect?)
+    assert_equal({ false => 2, true => 1 }, retrieve_relationships(:indirect => true).map(&:indirect?).tally)
   end
 
   test "generate should filter indirect relationships if indirect is false" do
@@ -302,6 +372,21 @@ class DiagramTest < ActiveSupport::TestCase
       :polymorphism => true).map { |s| s.specialized.name }
   end
 
+  test "generate should not yield specializations whose entity is not part of the domain" do
+    # An abstract parent whose child model has no table (e.g. ActionMailbox::Record
+    # with a tableless ActionMailbox::InboundEmail): the child is excluded from the
+    # domain, so the specialization resolves to a nameless Null entity. It must not
+    # be yielded, otherwise generators emit an edge to a nameless entity (which is
+    # invalid Mermaid output).
+    Object.const_set "GhostRecord", Class.new(ActiveRecord::Base) { self.abstract_class = true }
+    Object.const_set "GhostThing", Class.new(GhostRecord)
+
+    specializations = retrieve_specializations(:inheritance => true, :polymorphism => true)
+    assert_equal [], specializations.select { |s|
+      s.generalized.name.to_s.empty? || s.specialized.name.to_s.empty?
+    }
+  end
+
   # Attribute filtering ======================================================
   test "generate should yield content attributes by default" do
     create_model "Book", :title => :string, :created_at => :datetime, :author => :references do
@@ -388,4 +473,27 @@ class DiagramTest < ActiveSupport::TestCase
     assert_equal %w{title}, attribute_lists[Book].map(&:name)
     assert_equal [], attribute_lists[Author].map(&:name)
   end
+
+  test "normalize_exclude_attributes should split namespaced models on the first dot only" do
+    assert_equal({ "Admin::User" => ["password_digest"] },
+      Diagram.normalize_exclude_attributes("Admin::User.password_digest"))
+  end
+
+  test "normalize_exclude_attributes should treat a bare namespaced model as hide all" do
+    assert_equal({ "Admin::User" => true },
+      Diagram.normalize_exclude_attributes("Admin::User"))
+  end
+
+  test "normalize_exclude_attributes should return an empty hash for nil" do
+    assert_equal({}, Diagram.normalize_exclude_attributes(nil))
+  end
+
+  test "normalize_exclude_attributes should return an empty hash for false" do
+    assert_equal({}, Diagram.normalize_exclude_attributes(false))
+  end
+
+  test "normalize_exclude_attributes should ignore blank entries in a string" do
+    assert_equal({ "Book" => true },
+      Diagram.normalize_exclude_attributes("Book, ,"))
+  end
 end