diagrammer 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ed36b91c2cc6ff7abad9f7e84311d355052a09dbe663afc53f427ffccf11579
-  data.tar.gz: ec99b68c56d6494974257a305c16520a5d64e2bb2cd96105a0471269c491f812
+  metadata.gz: 3209269f5b2888c4144c95abffc3455328d429e11286f1805ff1ab86990f0a50
+  data.tar.gz: 25f0e0c9ea02edb84d192ace0ba79470ea8b5951666234a05d72182e6d793383
 SHA512:
-  metadata.gz: f1c7bb5c91510867e0ff7213d70dcdcc6e04ca88676389dcb35aa00d3e47ab0b5c8e91997e557aad72f821d498272bb540ffd77097f6a99c73a4cc7a54f0b13e
-  data.tar.gz: 2216ce3565d37fb8b0ff6552f7fbd3905f7211cfc7ae734be828b6af6bc84813e57be41b27c39a3f6ad01b1352c5de0955d3edede47bf2665db8bf14eacc77e7
+  metadata.gz: 1111b36151de7366fba5eee4f5f0a56ca3cecbd731baea320973296f20129e706e2c024df1a0e47aae51f041accb74f22afe56d805897281eaec83a2e584fe06
+  data.tar.gz: 51e7569e6d222052fbce83141c86d238b6de67943658e86c9d7e0d35bdc07c4169bbac66cbb4be75b47bb4b4f2fbb4b24b3faf9bf06ba4e793f8e5653a66cf54

data/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-07-21
+
+### Fixed
+
+- Do not crash on anonymous ActiveRecord classes. Sorting models by `name`
+  raised `ArgumentError: comparison of NilClass with String failed` when any
+  `Class.new(ActiveRecord::Base)` was loaded in the process.
+- Do not crash when `Rails` is loaded without an application (engines, gem test
+  suites). The eager-load guard checked `Rails.respond_to?(:application)`, which
+  is true even while `Rails.application` is still `nil`.
+- Draw one connector per relationship instead of two. A `belongs_to` and its
+  inverse `has_many`/`has_one` describe the same foreign key, and both were
+  emitted, producing duplicate lines with contradicting crow's feet. On a
+  17-table application this halved the edge count from 36 to 18.
+- Label a shared table with its STI base class rather than whichever subclass
+  sorted first alphabetically (`AdminUser` no longer names the `users` card),
+  and never let an anonymous class name a table it shares.
+- Anchor connectors on the real foreign key column instead of guessing
+  `"#{association_name}_id"`, which missed every association declared with a
+  custom `:foreign_key`.
+- Create missing parent directories for the output path, so writing to a nested
+  path such as `tmp/diagrams/erd.html` no longer raises `Errno::ENOENT`.
+- Keep graph traversal correct for tables and columns whose names collide with
+  `Object.prototype` members (`constructor`, `__proto__`), which previously
+  stranded such a card at the origin, unlaid-out and overlapping its neighbours.
+
+### Changed
+
+- Relationships are now oriented from the table holding the foreign key to the
+  table it references, and carry a `foreign_key` field. `has_many :through` is
+  no longer emitted, since it has no foreign key of its own and the underlying
+  associations already draw every physical link along the path.
+- Relationship mapping moved into `Diagrammer::RelationshipMapper`.
+- The README screenshot uses an absolute URL so it renders outside the
+  repository, where the previous relative path resolved to nothing.
+
 ## [0.1.0] - 2026-06-28
 
 ### Added
@@ -21,5 +57,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   cluster-based layout that fills the viewport width, and zoom/pan/drag — no
   Graphviz, no CDN, no network access required.
 
-[Unreleased]: https://github.com/alex-andreiev/diagrammer/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/alex-andreiev/diagrammer/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/alex-andreiev/diagrammer/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/alex-andreiev/diagrammer/releases/tag/v0.1.0

data/README.md

@@ -2,7 +2,7 @@
 
 Diagrammer is a Rails gem that generates a standalone, interactive database relationship diagram from ActiveRecord models.
 
-![Diagrammer example output](docs/screenshot.png)
+![Diagrammer example output](https://raw.githubusercontent.com/alex-andreiev/diagrammer/main/docs/screenshot.png)
 
 It introspects your Rails application, reads model columns and associations, and writes a single browser-friendly HTML file. The diagram renders as draggable table cards — similar in spirit to dbdiagram.io — directly in the browser. The main design goal is a zero-dependency workflow: no Graphviz, no system packages, no local diagram renderer, no PDF toolchain, and no network access required to view the result.
 

data/lib/diagrammer/generator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+
 module Diagrammer
   class Generator
     def initialize(output:, models: nil, introspector: ModelIntrospector.new(models: models))
@@ -15,12 +17,20 @@ module Diagrammer
         notice: notice_for(diagram)
       ).call
 
-      File.write(@output, html)
+      write(html)
       @output.to_s
     end
 
     private
 
+    # The rake task defaults to Rails.root, but an explicit path may point into
+    # a directory that does not exist yet (tmp/, doc/, a CI artifact dir).
+    def write(html)
+      path = @output.to_s
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, html)
+    end
+
     def notice_for(diagram)
       return unless diagram.fetch(:tables).empty?
 

data/lib/diagrammer/html_renderer.rb

@@ -242,7 +242,9 @@ module Diagrammer
             }
 
             // ---- Build cards -------------------------------------------------
-            var nodes = {};        // table_name -> node
+            var nodes = Object.create(null);   // table_name -> node (null proto: table
+                                               // names like "constructor" must not
+                                               // collide with Object.prototype)
             var order = [];        // stable iteration order
             tables.forEach(function (t) {
               var el = document.createElement("div");
@@ -253,7 +255,7 @@ module Diagrammer
               header.textContent = t.table_name;
               el.appendChild(header);
 
-              var rows = {};       // column name -> row element
+              var rows = Object.create(null);  // column name -> row element
               (t.columns || []).forEach(function (c) {
                 var row = document.createElement("div");
                 row.className = "col" + (c.primary_key ? " is-pk" : "") + (c.foreign_key ? " is-fk" : "");
@@ -300,7 +302,9 @@ module Diagrammer
             relationships.forEach(function (r) {
               var from = nodes[r.from], to = nodes[r.to];
               if (!from || !to) { return; }
-              var fkName = (r.name || "") + "_id";
+              // The real FK column beats guessing "<assoc>_id", which misses
+              // whenever the association was declared with a custom :foreign_key.
+              var fkName = r.foreign_key || ((r.name || "") + "_id");
               var fkRow = from.rows[fkName] ? fkName : null;
               var pkCol = pkColumn(to);
               var link = { from: from, to: to, fkRow: fkRow, pkRow: pkCol, card: cardinality(r.macro), group: null };
@@ -317,13 +321,13 @@ module Diagrammer
             }
 
             // Map an association macro to crow's-foot cardinality at each end.
+            // Edges always run FK holder -> referenced table, so "from" is the
+            // child side for every macro except habtm.
             function cardinality(macro) {
               switch (macro) {
-                case "belongs_to": return { from: "many", to: "one" };
                 case "has_one": return { from: "one", to: "one" };
-                case "has_many": return { from: "one", to: "many" };
                 case "has_and_belongs_to_many": return { from: "many", to: "many" };
-                default: return { from: "one", to: "many" };
+                default: return { from: "many", to: "one" };
               }
             }
 
@@ -358,7 +362,7 @@ module Diagrammer
             }
 
             function connectedComponents() {
-              var seen = {}, comps = [];
+              var seen = Object.create(null), comps = [];
               order.forEach(function (start) {
                 if (seen[start.name]) { return; }
                 var queue = [start], comp = [];
@@ -675,7 +679,7 @@ module Diagrammer
             viewport.addEventListener("pointercancel", endPointer);
 
             function highlight(node, on) {
-              var related = {};
+              var related = Object.create(null);
               related[node.name] = true;
               node.edges.forEach(function (l) {
                 related[l.from.name] = true; related[l.to.name] = true;

data/lib/diagrammer/model_introspector.rb

@@ -1,11 +1,7 @@
 # frozen_string_literal: true
 
-require 'set'
-
 module Diagrammer
   class ModelIntrospector
-    ASSOCIATION_MACROS = %i[belongs_to has_one has_many has_and_belongs_to_many].freeze
-
     def initialize(models: nil)
       @models = models
     end
@@ -13,10 +9,10 @@ module Diagrammer
     def call
       eager_load_rails_application
 
-      models = selected_models.sort_by(&:name)
+      models = selected_models.sort_by { |model| model.name.to_s }
       {
         tables: unique_tables(models),
-        relationships: relationships_for(models)
+        relationships: RelationshipMapper.new(models: models).call
       }
     end
 
@@ -25,15 +21,30 @@ module Diagrammer
     # Several models can share one database table (STI subclasses, gem base
     # classes such as I18n's Translation, multi-schema rpush models). Emit a
     # single card per table; associations from every model still merge onto it
-    # via relationships_for, which is keyed by table name.
+    # via RelationshipMapper, which is keyed by table name.
     def unique_tables(models)
-      models.each_with_object({}) do |model, by_table|
-        by_table[model.table_name] ||= table_for(model)
-      end.values
+      models.group_by(&:table_name).map { |_table, group| table_for(preferred_model(group)) }
+    end
+
+    # Models are sorted by name, so an STI subclass can win the card label over
+    # its own base class ("AdminUser" < "User"). Prefer the root of the
+    # hierarchy, and never let an anonymous class name a table it shares.
+    def preferred_model(group)
+      named = group.reject { |model| model.name.to_s.empty? }
+      candidates = named.empty? ? group : named
+      candidates.find { |model| sti_base?(model) } || candidates.first
     end
 
+    def sti_base?(model)
+      model.respond_to?(:base_class) && model.base_class == model
+    rescue StandardError
+      false
+    end
+
+    # Rails.respond_to?(:application) is true even before an application is
+    # defined (engines, gem test suites), where the reader returns nil.
     def eager_load_rails_application
-      return unless defined?(Rails) && Rails.respond_to?(:application)
+      return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
 
       Rails.application.eager_load!
     end
@@ -78,36 +89,5 @@ module Diagrammer
         }
       end
     end
-
-    def relationships_for(models)
-      table_names = models.to_set(&:table_name)
-      models.flat_map { |model| model_relationships(model, table_names) }.uniq
-    end
-
-    def model_relationships(model, table_names)
-      model.reflect_on_all_associations.filter_map do |association|
-        relationship_for(model, association, table_names)
-      end
-    end
-
-    def relationship_for(model, association, table_names)
-      return unless ASSOCIATION_MACROS.include?(association.macro)
-
-      target_table = association_table_name(association)
-      return unless target_table && table_names.include?(target_table)
-
-      {
-        from: model.table_name,
-        to: target_table,
-        name: association.name.to_s,
-        macro: association.macro
-      }
-    end
-
-    def association_table_name(association)
-      association.klass.table_name
-    rescue StandardError
-      nil
-    end
   end
 end

data/lib/diagrammer/relationship_mapper.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Diagrammer
+  # Turns ActiveRecord reflections into the table-to-table edges the renderer
+  # draws. Every edge is oriented from the table holding the foreign key to the
+  # table it references, so the renderer can anchor the line on the FK column.
+  class RelationshipMapper
+    ASSOCIATION_MACROS = %i[belongs_to has_one has_many has_and_belongs_to_many].freeze
+
+    # Ordered weakest-to-strongest. When a belongs_to and its inverse collapse
+    # onto one edge, the strongest macro in the group decides the cardinality.
+    MACRO_STRENGTH = %i[belongs_to has_one has_many has_and_belongs_to_many].freeze
+
+    def initialize(models:)
+      @models = models
+      @table_names = models.to_set(&:table_name)
+    end
+
+    def call
+      candidates = @models.flat_map { |model| model_relationships(model) }
+      merge_reciprocals(candidates)
+    end
+
+    private
+
+    def model_relationships(model)
+      model.reflect_on_all_associations.filter_map do |association|
+        relationship_for(model, association)
+      end
+    end
+
+    # A belongs_to and its inverse has_many/has_one describe the *same* physical
+    # foreign key. Emitting both draws two connectors between the same pair of
+    # cards, with contradicting crow's feet, so collapse them onto one edge.
+    def merge_reciprocals(candidates)
+      candidates.group_by { |relationship| relationship[:key] }.map do |_key, group|
+        representative(group)
+          .merge(macro: strongest_macro(group))
+          .except(:key)
+      end
+    end
+
+    # The belongs_to side names the association after the foreign key, which
+    # makes the better edge label; fall back to whichever side we have.
+    def representative(group)
+      group.find { |relationship| relationship[:macro] == :belongs_to } || group.first
+    end
+
+    def strongest_macro(group)
+      group.map { |relationship| relationship[:macro] }
+           .max_by { |macro| MACRO_STRENGTH.index(macro) || -1 }
+    end
+
+    def relationship_for(model, association)
+      return unless ASSOCIATION_MACROS.include?(association.macro)
+      # A has_many :through has no foreign key of its own; the underlying
+      # associations already draw every physical link along the path.
+      return if through_association?(association)
+
+      target_table = association_table_name(association)
+      return unless target_table && @table_names.include?(target_table)
+
+      if association.macro == :has_and_belongs_to_many
+        habtm_relationship(model, association, target_table)
+      else
+        directed_relationship(model, association, target_table)
+      end
+    end
+
+    def directed_relationship(model, association, target_table)
+      foreign_key = association_foreign_key(association)
+      child, parent = endpoints(model, association, target_table)
+
+      {
+        key: [child, parent, foreign_key],
+        from: child, to: parent,
+        name: association.name.to_s,
+        macro: association.macro,
+        foreign_key: foreign_key
+      }
+    end
+
+    # Only belongs_to declares the foreign key on its own table; has_many and
+    # has_one point at a key living on the far side.
+    def endpoints(model, association, target_table)
+      if association.macro == :belongs_to
+        [model.table_name, target_table]
+      else
+        [target_table, model.table_name]
+      end
+    end
+
+    # Both sides of a habtm share one join table, which is what identifies the
+    # edge; the endpoints are sorted so either side produces the same key.
+    def habtm_relationship(model, association, target_table)
+      from, to = [model.table_name, target_table].sort
+
+      {
+        key: [:habtm, association_join_table(association), from, to],
+        from: from, to: to,
+        name: association.name.to_s,
+        macro: association.macro,
+        foreign_key: nil
+      }
+    end
+
+    def through_association?(association)
+      association.respond_to?(:through_reflection?) && association.through_reflection?
+    rescue StandardError
+      false
+    end
+
+    def association_table_name(association)
+      association.klass.table_name
+    rescue StandardError
+      nil
+    end
+
+    def association_foreign_key(association)
+      association.foreign_key.to_s
+    rescue StandardError
+      nil
+    end
+
+    def association_join_table(association)
+      association.join_table.to_s
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/diagrammer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Diagrammer
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/lib/diagrammer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'diagrammer/version'
+require_relative 'diagrammer/relationship_mapper'
 require_relative 'diagrammer/model_introspector'
 require_relative 'diagrammer/html_renderer'
 require_relative 'diagrammer/generator'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: diagrammer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Alex Andreiev
 bindir: bin
 cert_chain: []
-date: 2026-06-28 00:00:00.000000000 Z
+date: 2026-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -95,6 +95,7 @@ files:
 - lib/diagrammer/html_renderer.rb
 - lib/diagrammer/model_introspector.rb
 - lib/diagrammer/railtie.rb
+- lib/diagrammer/relationship_mapper.rb
 - lib/diagrammer/tasks/diagrammer.rake
 - lib/diagrammer/version.rb
 homepage: https://github.com/alex-andreiev/diagrammer