rails-erd 2.0.1 → 2.1.0

data/lib/rails_erd/cli.rb

@@ -9,7 +9,7 @@ Choice.options do
 
   option :generator do
     long "--generator=Generator"
-    desc "Generator to use (mermaid or graphviz). Defaults to mermaid."
+    desc "Generator to use (mermaid, graphviz, or tbls). Defaults to mermaid."
   end
 
   option :mermaid_style do
@@ -72,6 +72,11 @@ Choice.options do
     desc "Filter to exclude listed models in diagram."
   end
 
+  option :exclude_attributes do
+    long "--exclude_attributes=MODEL[.ATTRIBUTE],..."
+    desc "Hide attributes per model. Use Model to hide all its attributes or Model.attribute to hide one, e.g. BigTable,User.password_digest."
+  end
+
   option :sort do
     long "--sort=BOOLEAN"
     desc "Sort attribute list alphabetically"
@@ -188,10 +193,11 @@ module RailsERD
     def initialize(path, options)
       @path, @options = path, options
       generator = options[:generator] || RailsERD.options[:generator]
-      if generator == :mermaid
-        require "rails_erd/diagram/mermaid"
-      else
-        require "rails_erd/diagram/graphviz"
+      case generator
+      when :mermaid  then require "rails_erd/diagram/mermaid"
+      when :tbls     then require "rails_erd/diagram/tbls"
+      when :graphviz then require "rails_erd/diagram/graphviz"
+      else                require "rails_erd/diagram/mermaid"
       end
     end
 
@@ -231,10 +237,11 @@ module RailsERD
 
     def generator
       generator_type = options[:generator] || RailsERD.options[:generator]
-      if generator_type == :mermaid
-        RailsERD::Diagram::Mermaid
-      else
-        RailsERD::Diagram::Graphviz
+      case generator_type
+      when :mermaid  then RailsERD::Diagram::Mermaid
+      when :tbls     then RailsERD::Diagram::Tbls
+      when :graphviz then RailsERD::Diagram::Graphviz
+      else                RailsERD::Diagram::Mermaid
       end
     end
 

data/lib/rails_erd/config.rb

@@ -73,6 +73,11 @@ module RailsERD
       when :only, :exclude
         Array(value).join(",").split(",").map { |v| v.strip }
 
+      # nil | { <string> => true | [<string>] }
+      when :exclude_attributes
+        require "rails_erd/diagram"
+        RailsERD::Diagram.normalize_exclude_attributes(value)
+
       # true | false
       when :disconnected, :indirect, :inheritance, :markup, :polymorphism,
            :warn, :cluster

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

@@ -55,6 +55,14 @@ module RailsERD
   # attributes:: Selects which attributes to display. Can be any combination of
   #              +:content+, +:primary_keys+, +:foreign_keys+, +:timestamps+, or
   #              +:inheritance+.
+  # exclude_attributes:: Hides attributes on a per-model basis, without affecting
+  #                      other models. Accepts a hash that maps model names to
+  #                      either +true+ (hide all attributes for that model) or a
+  #                      list of attribute names to hide. From the command line it
+  #                      can also be given as a comma separated string where each
+  #                      entry is either +Model+ (hide all attributes) or
+  #                      +Model.attribute+ (hide a single attribute), for example
+  #                      <tt>exclude_attributes="BigTable,User.password_digest"</tt>.
   # disconnected:: Set to +false+ to exclude entities that are not connected to other
   #                entities. Defaults to +false+.
   # indirect:: Set to +false+ to exclude relationships that are indirect.
@@ -76,6 +84,38 @@ module RailsERD
         new(Domain.generate(options), options).create
       end
 
+      # Canonicalises the +exclude_attributes+ option into a hash that maps
+      # model names (as strings) to either +true+ (hide all attributes) or an
+      # array of attribute names to hide. Accepts several input shapes:
+      #
+      #   * a hash, e.g. <tt>{ "BigTable" => true, "User" => ["password_digest"] }</tt>
+      #     (values may be +true+/+"all"+ to hide every attribute, +false+/+nil+
+      #     to hide none, or a comma separated string / array of names);
+      #   * a string or array of <tt>Model</tt> / <tt>Model.attribute</tt>
+      #     entries, e.g. <tt>"BigTable,User.password_digest"</tt>.
+      def normalize_exclude_attributes(value)
+        return {} if value.nil? || value == false
+
+        if value.is_a?(Hash)
+          value.each_with_object({}) do |(model, attrs), result|
+            result[model.to_s] = normalize_exclude_attribute_value(attrs)
+          end
+        else
+          entries = Array(value).flat_map { |entry| entry.to_s.split(",") }
+          entries.each_with_object({}) do |entry, result|
+            model, attribute = entry.split(".", 2)
+            model = model.to_s.strip
+            next if model.empty?
+
+            if attribute.nil?
+              result[model] = true
+            elsif result[model] != true
+              (result[model] ||= []) << attribute.strip
+            end
+          end
+        end
+      end
+
       protected
 
       def setup(&block)
@@ -103,6 +143,16 @@ module RailsERD
       def callbacks
         @callbacks ||= Hash.new { proc {} }
       end
+
+      def normalize_exclude_attribute_value(attrs)
+        case attrs
+        when true then true
+        when false, nil then []
+        when "all", :all, "true" then true
+        else
+          Array(attrs).flat_map { |attr| attr.to_s.split(",") }.map(&:strip).reject(&:empty?)
+        end
+      end
     end
 
     # The options that are used to create this diagram.
@@ -181,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?
@@ -193,25 +242,106 @@ 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
 
     def filtered_attributes(entity)
-      entity.attributes.reject { |attribute|
-        # 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')}?") }
+      excluded = excluded_attributes_for(entity)
+      return [] if excluded == :all
+
+      entity.attributes.select { |attribute|
+        # Hide attributes excluded for this specific model.
+        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
 
+    # Returns the attribute exclusions configured for the given entity through
+    # the +exclude_attributes+ option. Returns +:all+ when every attribute
+    # should be hidden, or an array of attribute names otherwise.
+    def excluded_attributes_for(entity)
+      spec = normalized_exclude_attributes[entity.name]
+      return :all if spec == true
+      Array(spec)
+    end
+
+    def normalized_exclude_attributes
+      @normalized_exclude_attributes ||= self.class.normalize_exclude_attributes(options.exclude_attributes)
+    end
+
     def warn(message)
       puts "Warning: #{message}" if options.warn
     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,14 +240,17 @@ 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
-      excluded_names.include?(association.active_record.name.to_sym) ||
-        (association.klass.name && excluded_names.include?(association.klass.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 && patterns.any? { |pattern| matches_pattern?(pattern, target_name) }
     rescue NameError
-      # If we can't determine the target class, check only the source model
-      excluded_names.include?(association.active_record.name.to_sym)
+      # If we can't determine the target class, the source model was already checked above
+      false
     end
 
     def check_polymorphic_association_validity(association)

data/lib/rails_erd/version.rb

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

data/lib/rails_erd.rb

@@ -55,6 +55,7 @@ module RailsERD
         :warn, true,
         :title, true,
         :exclude, nil,
+        :exclude_attributes, nil,
         :only, nil,
         :only_recursion_depth, nil,
         :prepend_primary, false,

data/test/unit/config_test.rb

@@ -122,6 +122,17 @@ class ConfigTest < ActiveSupport::TestCase
     assert_equal [:content, :primary_keys], normalize_value(:attributes, ["content", "primary_keys"])
   end
 
+  test "normalize_value should canonicalize a hash when key is :exclude_attributes." do
+    value = { "BigTable" => true, "User" => ["password_digest"] }
+    expected = { "BigTable" => true, "User" => ["password_digest"] }
+    assert_equal expected, normalize_value(:exclude_attributes, value)
+  end
+
+  test "normalize_value should parse a string when key is :exclude_attributes." do
+    expected = { "BigTable" => true, "User" => ["password_digest"] }
+    assert_equal expected, normalize_value(:exclude_attributes, "BigTable,User.password_digest")
+  end
+
   test "normalize_value should return hash with symbol keys when key is :fonts and value is a hash." do
     fonts_value = { "normal" => "Arial", "bold" => "Arial Bold", "italic" => "Arial Italic" }
     expected = {:normal => "Arial", :bold => "Arial Bold", :italic => "Arial Italic"}