rails-schema 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37ed34e2667a948b30551666b19657a3bf6e1a484e4fe4660a3da03c9d356f66
-  data.tar.gz: c7f9ac452ae98d4188718c47879a2b1fc2769b21d308b7d07f89779c42273f95
+  metadata.gz: 71fa755a65ac8dcdb27f419857dd5ede16a13d4c26e5b9a40bc7e8ec1f41d36b
+  data.tar.gz: 4940bf9f24e51d6caf3e5e70526f7a2ed8d097c352e99920e6191212c1d6137e
 SHA512:
-  metadata.gz: a21acfd8d250d9fffdd67acc95a6743167f26cf2754c4d71d35af9a74a1f450c4954eb6443fe20d8198e066f8ef8e783924ed4cab3a7b39f7f2f9006e5913af7
-  data.tar.gz: 837e5b1171e30ff17aca2e8871bed916d691203c28e8a876d92948ef38018ce23856f7263c95d96c3334c04be853b46bad48cd09101f5b7cf42da742f1db9246
+  metadata.gz: 8004dd0d9b8a82008ec7e4b53c0ec444067ed1ba477e1bafe59dcd18810149bdc713e1c5f1009ae3bcd456a6cfcd46e62be112cd3f1ae4d0a44ccd2929f644f2
+  data.tar.gz: 4269f97b5b87daf25cfd24ed9138b4ed363e3a9ea4c7f70695abc53517216cc04d299567c1c48a80b6f2fae9b99b602434574110c3cd2afc1ccdea0e4c5a6bf0

data/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.1.4] - 2026-03-08
+
+### Added
+
+- Support for Ruby 2.7+ and Rails 5.2+ (improved compatibility with older versions)
+
+### Changed
+
+- Self-referential-only models (all edges point to themselves) are now placed in a vertical column to the left of the main graph instead of floating in the force simulation
+- True orphan models (zero edges) continue to appear in rows above the diagram
+- Improved class names and table names visibility
+
+## [0.1.3] - 2026-03-01
+
+### Added
+
+- Mongoid support: visualize MongoDB-backed models without a schema file (`schema_format: :mongoid`)
+- Auto-detection of Mongoid when `schema_format: :auto` and `Mongoid::Document` is defined
+- Mongoid extractors: `ModelScanner`, `ModelAdapter`, `ColumnReader`, `AssociationReader`
+- Support for all Mongoid association types: `has_many`, `has_one`, `belongs_to`, `has_and_belongs_to_many`, `embeds_many`, `embeds_one`, `embedded_in`
+- Embedded document styling in the frontend (dashed borders for embed associations)
+- Engine model eager-loading for Mongoid apps
+
 ## [0.1.2] - 2026-02-22
 
 ### Added

data/CLAUDE.md

@@ -16,16 +16,58 @@ bundle exec rspec spec/rails/schema/extractor/mongoid/  # Mongoid tests only
 
 Three-layer pipeline: **Extractor → Transformer → Renderer**
 
+| Layer | Responsibility | Key Classes |
+|---|---|---|
+| **Extractor** | Introspects Rails environment; collects models, columns, associations | `ModelScanner`, `ColumnReader`, `AssociationReader`, `SchemaFileParser`, `StructureSqlParser`, plus `Mongoid::ModelScanner`, `Mongoid::ModelAdapter`, `Mongoid::ColumnReader`, `Mongoid::AssociationReader` |
+| **Transformer** | Normalizes extracted data into a serializable graph (nodes + edges + metadata) | `GraphBuilder`, `Node`, `Edge` |
+| **Renderer** | Injects graph data into an HTML/JS/CSS template via ERB | `HtmlGenerator` |
+| **Railtie** | Provides the `rails_schema:generate` rake task | `Railtie` |
+
+### Key Paths
+
 - `lib/rails/schema.rb` — entry point, `generate` dispatches to ActiveRecord or Mongoid pipeline
 - `lib/rails/schema/extractor/` — model discovery, column/association reading, schema file parsing
-- `lib/rails/schema/extractor/mongoid/` — Mongoid-specific extractors (model_scanner, model_adapter, column_reader, association_reader)
-- `lib/rails/schema/transformer/` — builds normalized graph JSON (nodes + edges + metadata)
+- `lib/rails/schema/extractor/mongoid/` — Mongoid-specific extractors
+- `lib/rails/schema/transformer/` — builds normalized graph JSON
 - `lib/rails/schema/renderer/` — ERB-based HTML generation with inlined JS/CSS/data
 - `lib/rails/schema/assets/` — frontend (vanilla JS + d3-force, CSS, HTML template)
 
+### Generation Pipeline
+
+```ruby
+def generate(output: nil)
+  schema_data = parse_schema
+  models = Extractor::ModelScanner.new(schema_data: schema_data).scan
+  column_reader = Extractor::ColumnReader.new(schema_data: schema_data)
+  graph_data = Transformer::GraphBuilder.new(column_reader: column_reader).build(models)
+  Renderer::HtmlGenerator.new(graph_data: graph_data).render_to_file(output)
+end
+```
+
+### Data Extraction Strategy
+
+1. **`db/schema.rb`** — `SchemaFileParser` parses with regex (table names, columns, types, nullable, defaults, PKs)
+2. **`db/structure.sql`** — `StructureSqlParser` parses SQL `CREATE TABLE` statements, maps SQL types to Rails types
+3. **ActiveRecord reflection API** — `AssociationReader` uses `reflect_on_all_associations` for associations
+4. **`Model.columns`** — `ColumnReader` falls back to this when table not found in schema_data
+
+### Model Discovery
+
+`ModelScanner` (ActiveRecord):
+1. Calls `Rails.application.eager_load!` (Zeitwerk support, multiple fallback strategies including `LoadError` rescue)
+2. Collects `ActiveRecord::Base.descendants`
+3. Filters: abstract classes, anonymous classes, models without known tables
+4. Applies `exclude_models` config (supports wildcard prefix like `"ActiveStorage::*"`)
+
+`Mongoid::ModelScanner`:
+1. Eager-loads via Zeitwerk or file glob with fallbacks
+2. Scans `ObjectSpace` for `Mongoid::Document` includers
+3. Also loads models from mounted Rails engines
+4. Returns models wrapped in `ModelAdapter` for GraphBuilder compatibility
+
 ## Key Conventions
 
-- Ruby >= 3.2, Rails >= 6.0
+- Ruby >= 2.7, Rails >= 5.2
 - Double quotes for strings (RuboCop enforced)
 - RuboCop max method length: 15 lines, default ABC/complexity limits
 - No `Style/Documentation` required
@@ -44,5 +86,22 @@ Three-layer pipeline: **Extractor → Transformer → Renderer**
 ## Testing Notes
 
 - Always run `bundle exec rubocop` before committing — CI checks both tests and linting
+- CI matrix: Ruby 2.7, 3.0, 3.1, 3.2, 3.3, 3.4
 - Mongoid specs stub `Rails::Engine` and `Rails::Application` since they may not exist in test env
 - SimpleCov is enabled; coverage report goes to `coverage/`
+
+## Frontend
+
+Single self-contained HTML file — no CDN, no network requests. D3 is vendored/minified.
+
+- **Vanilla JS + d3-force** for graph rendering
+- **CSS custom properties** for dark/light theming
+- Features: searchable sidebar, click-to-focus, detail panel, zoom/pan, keyboard shortcuts (`/` search, `Esc` deselect, `+/-` zoom, `F` fit)
+
+## Design Decisions
+
+- **Single HTML file** — zero deployment friction, offline-first, portable (CI, GitHub Pages, email)
+- **Not a mounted engine** — static file works without a running server
+- **Parse schema files** — works without DB connection (CI environments, no local DB)
+- **Force-directed layout** — handles unknown schemas gracefully without pre-defined positions
+- **Node layout categories** — three-way partition in `app.js`: connected nodes use force simulation, self-ref-only models (all edges point to themselves) are placed in a vertical left column via `layoutSelfRefNodes()`, true orphans (zero edges) are placed in rows above the diagram via `layoutOrphans()`

data/README.md

@@ -4,6 +4,13 @@ Interactive HTML visualization of your Rails database schema. Introspects your a
 
 No external server, no CDN — just one command and a browser.
 
+## Compatibility
+
+| Dependency | Required version |
+|-----------|-----------------|
+| Ruby | >= 2.7 |
+| Rails | >= 5.2 |
+
 **[Live example](https://andrew2net.github.io/rails-schema/)** — generated from [Fizzy](https://www.fizzy.do), a modern spin on kanban for tracking just about anything, created by [37signals](https://37signals.com).
 
 ![Rails Schema screenshot](docs/screenshot.png)
@@ -100,7 +107,7 @@ For Mongoid apps, the gem introspects model classes at runtime to read field def
 ## Features
 
 - **No database required** — reads from `db/schema.rb`, `db/structure.sql`, or Mongoid model introspection
-- **Force-directed layout** — models cluster naturally by association density
+- **Force-directed layout** — models cluster naturally by association density; self-referential-only models are placed in a left column, true orphans in rows above
 - **Searchable sidebar** — filter models by name or table
 - **Click-to-focus** — click a model to highlight its neighborhood, fading unrelated models
 - **Detail panel** — full column list and associations for the selected model

data/lib/rails/schema/assets/app.js

@@ -195,6 +195,10 @@
   }
 
   // d3-force simulation
+  var orphanNodes = [];
+  var connectedNodes = [];
+  var selfRefNodes = [];
+
   function setupSimulation() {
     var nodeMap = {};
     nodes.forEach(function(n) { nodeMap[n.id] = n; });
@@ -207,18 +211,156 @@
 
     var simNodes = nodes.filter(function(n) { return visibleModels.has(n.id); });
 
+    // Partition into connected, self-ref-only, and orphan nodes
+    var connectedIds = new Set();
+    var selfRefIds = new Set();
+    simEdges.forEach(function(e) {
+      if (e.data.from !== e.data.to) {
+        connectedIds.add(e.data.from);
+        connectedIds.add(e.data.to);
+      } else {
+        selfRefIds.add(e.data.from);
+      }
+    });
+    // Self-ref-only = has self-ref edge but no cross-model edges
+    selfRefIds.forEach(function(id) { if (connectedIds.has(id)) selfRefIds.delete(id); });
+
+    connectedNodes = simNodes.filter(function(n) { return connectedIds.has(n.id); });
+    selfRefNodes = simNodes.filter(function(n) { return selfRefIds.has(n.id); });
+    selfRefNodes.sort(function(a, b) { return a.id.localeCompare(b.id); });
+    orphanNodes = simNodes.filter(function(n) { return !connectedIds.has(n.id) && !selfRefIds.has(n.id); });
+    orphanNodes.sort(function(a, b) { return a.id.localeCompare(b.id); });
+
+    // Exclude self-ref-only edges from force simulation
+    var forceEdges = simEdges.filter(function(e) {
+      return !selfRefIds.has(e.data.from) || connectedIds.has(e.data.from);
+    });
+
     if (simulation) simulation.stop();
 
-    simulation = d3.forceSimulation(simNodes)
-      .force("link", d3.forceLink(simEdges).id(function(d) { return d.id; }).distance(320))
+    simulation = d3.forceSimulation(connectedNodes)
+      .force("link", d3.forceLink(forceEdges).id(function(d) { return d.id; }).distance(320))
       .force("charge", d3.forceManyBody().strength(-600))
       .force("center", d3.forceCenter(svgEl.clientWidth / 2, svgEl.clientHeight / 2))
       .force("collide", d3.forceCollide().radius(function(d) { return Math.max(NODE_WIDTH, d._height) / 2 + 50; }))
       .on("tick", ticked);
 
+    // Manually resolve edge references for self-ref-only nodes
+    simEdges.forEach(function(e) {
+      if (typeof e.source === 'string' && selfRefIds.has(e.source)) {
+        var node = selfRefNodes.find(function(n) { return n.id === e.source; });
+        e.source = node;
+        e.target = node;
+      }
+    });
+
     return { simNodes: simNodes, simEdges: simEdges };
   }
 
+  function layoutOrphans() {
+    if (orphanNodes.length === 0) return;
+
+    // Find connected graph bounds
+    var minY = Infinity, minX = Infinity, maxX = -Infinity;
+    connectedNodes.forEach(function(n) {
+      var top = n.y - n._height / 2;
+      if (top < minY) minY = top;
+      if (n.x - NODE_WIDTH / 2 < minX) minX = n.x - NODE_WIDTH / 2;
+      if (n.x + NODE_WIDTH / 2 > maxX) maxX = n.x + NODE_WIDTH / 2;
+    });
+
+    // Defaults when no connected nodes
+    if (minY === Infinity) minY = svgEl.clientHeight / 2;
+    if (minX === Infinity) minX = svgEl.clientWidth / 2 - NODE_WIDTH;
+    if (maxX === -Infinity) maxX = svgEl.clientWidth / 2 + NODE_WIDTH;
+
+    var centerX = (minX + maxX) / 2;
+    var gap = 20;
+    var rowGap = 30;
+
+    // Lay out orphans into rows (wrap when exceeding connected graph width)
+    var maxRowWidth = Math.max(maxX - minX, NODE_WIDTH * 3);
+    var rows = [[]];
+    var rowWidths = [0];
+
+    orphanNodes.forEach(function(n) {
+      var lastRow = rows[rows.length - 1];
+      var lastWidth = rowWidths[rows.length - 1];
+      var addedWidth = (lastRow.length > 0 ? gap : 0) + NODE_WIDTH;
+
+      if (lastRow.length > 0 && lastWidth + addedWidth > maxRowWidth) {
+        rows.push([n]);
+        rowWidths.push(NODE_WIDTH);
+      } else {
+        lastRow.push(n);
+        rowWidths[rows.length - 1] = lastWidth + addedWidth;
+      }
+    });
+
+    // Position rows above the diagram, bottom row first (closest to graph)
+    var currentY = minY - rowGap;
+    for (var r = rows.length - 1; r >= 0; r--) {
+      var row = rows[r];
+      var rowHeight = 0;
+      row.forEach(function(n) { if (n._height > rowHeight) rowHeight = n._height; });
+
+      currentY -= rowHeight / 2;
+      var startX = centerX - rowWidths[r] / 2 + NODE_WIDTH / 2;
+
+      row.forEach(function(n, i) {
+        n.x = startX + i * (NODE_WIDTH + gap);
+        n.y = currentY;
+      });
+
+      currentY -= rowHeight / 2 + rowGap;
+    }
+
+  }
+
+  function layoutSelfRefNodes() {
+    if (selfRefNodes.length === 0) return;
+
+    var minX = Infinity, minY = Infinity, maxY = -Infinity;
+    connectedNodes.forEach(function(n) {
+      if (n.x - NODE_WIDTH / 2 < minX) minX = n.x - NODE_WIDTH / 2;
+      if (n.y - n._height / 2 < minY) minY = n.y - n._height / 2;
+      if (n.y + n._height / 2 > maxY) maxY = n.y + n._height / 2;
+    });
+
+    if (minX === Infinity) minX = svgEl.clientWidth / 2;
+    if (minY === Infinity) minY = svgEl.clientHeight / 2 - 100;
+    if (maxY === -Infinity) maxY = svgEl.clientHeight / 2 + 100;
+
+    var gap = 20;
+    var colGap = 40;
+    var centerY = (minY + maxY) / 2;
+
+    var totalHeight = 0;
+    selfRefNodes.forEach(function(n) { totalHeight += n._height; });
+    totalHeight += (selfRefNodes.length - 1) * gap;
+
+    var currentY = centerY - totalHeight / 2;
+    var x = minX - NODE_WIDTH - colGap;
+
+    selfRefNodes.forEach(function(n) {
+      n.x = x;
+      n.y = currentY + n._height / 2;
+      currentY += n._height + gap;
+    });
+  }
+
+  function truncateText(text, maxWidth, font) {
+    var canvas = document.createElement("canvas");
+    var ctx = canvas.getContext("2d");
+    ctx.font = font + " " + getComputedStyle(document.body).fontFamily;
+    if (ctx.measureText(text).width <= maxWidth) return text;
+    var truncated = text;
+    while (truncated.length > 0 && ctx.measureText(truncated + "…").width > maxWidth) {
+      truncated = truncated.slice(0, -1);
+    }
+    return truncated + "…";
+  }
+
   // Render
   var currentSim;
 
@@ -324,7 +466,7 @@
       .attr("y", function(d) { return -d._height / 2 + 16; })
       .attr("text-anchor", "middle")
       .attr("dominant-baseline", "central")
-      .text(function(d) { return d.id; });
+      .text(function(d) { return truncateText(d.id, NODE_WIDTH - NODE_PADDING * 2, "bold 13px"); });
 
     // Table name
     nGroups.append("text")
@@ -333,7 +475,7 @@
       .attr("y", function(d) { return -d._height / 2 + 30; })
       .attr("text-anchor", "middle")
       .attr("dominant-baseline", "central")
-      .text(function(d) { return d.table_name; });
+      .text(function(d) { return truncateText(d.table_name, NODE_WIDTH - NODE_PADDING * 2, "10px"); });
 
     // Columns
     nGroups.each(function(d) {
@@ -369,6 +511,8 @@
   }
 
   function ticked() {
+    layoutOrphans();
+    layoutSelfRefNodes();
     edgeGroup.selectAll(".edge-group").each(function(d) {
       var g = d3.select(this);
       var src = d.source;
@@ -487,18 +631,30 @@
   }
 
   // Drag behavior
+  function isOrphan(d) {
+    return orphanNodes.indexOf(d) !== -1 || selfRefNodes.indexOf(d) !== -1;
+  }
+
   function dragStarted(event, d) {
+    if (isOrphan(d)) return;
     if (!event.active) simulation.alphaTarget(0.3).restart();
     d.fx = d.x;
     d.fy = d.y;
   }
 
   function dragged(event, d) {
+    if (isOrphan(d)) {
+      d.x = event.x;
+      d.y = event.y;
+      ticked();
+      return;
+    }
     d.fx = event.x;
     d.fy = event.y;
   }
 
   function dragEnded(event, d) {
+    if (isOrphan(d)) return;
     if (!event.active) simulation.alphaTarget(0);
     d.fx = null;
     d.fy = null;
@@ -559,10 +715,11 @@
 
     var nodeEdges = edges.filter(function(e) { return e.from === nodeId || e.to === nodeId; });
 
-    var html = '<div style="position:relative;">';
+    var html = '<div class="detail-header">';
+    html += '<h2 title="' + escapeHtml(node.id) + '">' + escapeHtml(node.id) + '</h2>';
     html += '<button id="detail-close" onclick="window.__closeDetail()">&times;</button>';
-    html += '<h2>' + escapeHtml(node.id) + '</h2>';
-    html += '<div class="detail-table">' + escapeHtml(node.table_name) + '</div>';
+    html += '</div>';
+    html += '<div class="detail-table" title="' + escapeHtml(node.table_name) + '">' + escapeHtml(node.table_name) + '</div>';
 
     html += '<h3>Columns</h3>';
     html += '<ul class="column-list">';
@@ -587,7 +744,6 @@
       html += '</ul>';
     }
 
-    html += '</div>';
     content.innerHTML = html;
 
     // Click association targets to navigate
@@ -769,5 +925,5 @@
   render();
 
   // Fit after simulation settles
-  setTimeout(fitToScreen, 1500);
+  setTimeout(function() { fitToScreen(); }, 1500);
 })();

data/lib/rails/schema/assets/style.css

@@ -375,19 +375,35 @@ body {
 
 #detail-content {
   padding: 16px;
+  padding-top: calc(var(--toolbar-height) + 16px);
   width: var(--detail-width);
 }
 
+.detail-header {
+  display: flex;
+  align-items: center;
+  position: relative;
+  padding-right: 28px;
+}
+
 #detail-content h2 {
+  flex: 1;
+  min-width: 0;
   font-size: 18px;
   font-weight: 700;
   margin-bottom: 4px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 #detail-content .detail-table {
   font-size: 12px;
   color: var(--text-secondary);
   margin-bottom: 16px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 #detail-content h3 {
@@ -456,15 +472,16 @@ body {
 }
 
 #detail-close {
-  position: absolute;
-  top: 12px;
-  right: 12px;
   background: none;
   border: none;
   color: var(--text-secondary);
   cursor: pointer;
   font-size: 18px;
   padding: 4px;
+  flex-shrink: 0;
+  position: absolute;
+  top: -8px;
+  right: 0;
 }
 
 /* Legend */

data/lib/rails/schema/extractor/model_scanner.rb

@@ -6,7 +6,7 @@ module Rails
       class ModelScanner
         def initialize(configuration: ::Rails::Schema.configuration, schema_data: nil)
           @configuration = configuration
-          @schema_data = schema_data
+          @schema_data = schema_data.nil? || schema_data.empty? ? nil : schema_data
         end
 
         def scan
@@ -43,7 +43,7 @@ module Rails
           else
             loader.eager_load
           end
-        rescue StandardError => e
+        rescue StandardError, LoadError => e
           warn "[rails-schema] Zeitwerk eager_load failed (#{e.class}: #{e.message}), " \
                "trying Rails.application.eager_load!"
           eager_load_via_application!
@@ -51,7 +51,7 @@ module Rails
 
         def eager_load_via_application!
           ::Rails.application.eager_load!
-        rescue StandardError => e
+        rescue StandardError, LoadError => e
           warn "[rails-schema] eager_load! failed (#{e.class}: #{e.message}), " \
                "falling back to per-file model loading"
           eager_load_model_files!
@@ -63,9 +63,9 @@ module Rails
           models_path = ::Rails.root.join("app", "models")
           return unless models_path.exist?
 
-          Dir.glob(models_path.join("**/*.rb")).each do |file|
+          Dir.glob(models_path.join("**/*.rb")).sort.each do |file|
             require file
-          rescue StandardError => e
+          rescue StandardError, LoadError => e
             warn "[rails-schema] Could not load #{file}: #{e.class}: #{e.message}"
           end
         end

data/lib/rails/schema/extractor/mongoid/model_adapter.rb

@@ -23,9 +23,9 @@ module Rails
             model.respond_to?(method, include_private) || super
           end
 
-          def method_missing(method, ...)
+          def method_missing(method, *args, **kwargs, &block)
             if model.respond_to?(method)
-              model.send(method, ...)
+              model.send(method, *args, **kwargs, &block)
             else
               super
             end

data/lib/rails/schema/extractor/mongoid/model_scanner.rb

@@ -67,7 +67,7 @@ module Rails
             models_path = ::Rails.root.join("app", "models")
             return unless models_path.exist?
 
-            Dir.glob(models_path.join("**/*.rb")).each do |file|
+            Dir.glob(models_path.join("**/*.rb")).sort.each do |file|
               require file
             rescue StandardError => e
               warn "[rails-schema] Could not load #{file}: #{e.class}: #{e.message}"
@@ -111,7 +111,7 @@ module Rails
 
           def eager_load_engine_files(paths)
             paths.each do |path|
-              Dir.glob(File.join(path, "**/*.rb")).each do |file|
+              Dir.glob(File.join(path, "**/*.rb")).sort.each do |file|
                 require file
               rescue StandardError => e
                 warn "[rails-schema] Could not load engine model #{file}: #{e.class}: #{e.message}"

data/lib/rails/schema/extractor/structure_sql_parser.rb

@@ -19,9 +19,9 @@ module Rails
         }.freeze
 
         COMPOUND_TYPE_RE = /\A(character\s+varying|bit\s+varying|double\s+precision|
-                               timestamp(?:\(\d+\))?\s+with(?:out)?\s+time\s+zone)/ix
-        CONSTRAINT_RE = /\A(CONSTRAINT|UNIQUE|CHECK|EXCLUDE|FOREIGN\s+KEY)\b/i
-        PK_CONSTRAINT_RE = /PRIMARY\s+KEY\s*\(([^)]+)\)/i
+                               timestamp(?:\(\d+\))?\s+with(?:out)?\s+time\s+zone)/ix.freeze
+        CONSTRAINT_RE = /\A(CONSTRAINT|UNIQUE|CHECK|EXCLUDE|FOREIGN\s+KEY)\b/i.freeze
+        PK_CONSTRAINT_RE = /PRIMARY\s+KEY\s*\(([^)]+)\)/i.freeze
 
         def initialize(structure_path = nil)
           @structure_path = structure_path
@@ -56,7 +56,9 @@ module Rails
           File.join(Dir.pwd, "db", "structure.sql")
         end
 
-        def unquote(identifier) = identifier.delete('"')
+        def unquote(identifier)
+          identifier.delete('"')
+        end
 
         def extract_table_name(raw)
           unquote(raw).split(".").last

data/lib/rails/schema/transformer/graph_builder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Rails
   module Schema
     module Transformer
@@ -10,9 +12,12 @@ module Rails
         end
 
         def build(models)
-          node_names = models.to_set(&:name)
-          nodes = models.map { |m| build_node(m) }
-          edges = models.flat_map { |m| build_edges(m, node_names) }
+          model_ids = assign_unique_ids(models)
+          name_to_id = {}
+          model_ids.each { |m, uid| name_to_id[m.name] ||= uid }
+
+          nodes = model_ids.map { |m, uid| build_node(m, uid) }
+          edges = model_ids.flat_map { |m, uid| build_edges(m, uid, name_to_id) }
 
           {
             nodes: nodes.map(&:to_h),
@@ -23,21 +28,29 @@ module Rails
 
         private
 
-        def build_node(model)
+        def assign_unique_ids(models)
+          counts = models.group_by(&:name).transform_values(&:size)
+          models.map do |m|
+            uid = counts[m.name] > 1 ? "#{m.name} (#{m.table_name})" : m.name
+            [m, uid]
+          end
+        end
+
+        def build_node(model, unique_id)
           Node.new(
-            id: model.name,
+            id: unique_id,
             table_name: model.table_name,
             columns: @column_reader.read(model)
           )
         end
 
-        def build_edges(model, node_names)
+        def build_edges(model, unique_id, name_to_id)
           @association_reader.read(model).filter_map do |assoc|
-            next unless node_names.include?(assoc[:to])
+            next unless name_to_id.key?(assoc[:to])
 
             Edge.new(
-              from: assoc[:from],
-              to: assoc[:to],
+              from: unique_id,
+              to: name_to_id[assoc[:to]],
               association_type: assoc[:association_type],
               label: assoc[:label],
               foreign_key: assoc[:foreign_key],

data/lib/rails/schema/version.rb

@@ -2,6 +2,6 @@
 
 module Rails
   module Schema
-    VERSION = "0.1.3"
+    VERSION = "0.1.4"
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-schema
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Andrei Kislichenko
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -15,28 +16,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '5.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '5.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '5.2'
 description: Introspects a Rails app's models, associations, and columns, then generates
   a single self-contained HTML file with an interactive entity-relationship diagram.
 email:
@@ -48,7 +63,6 @@ files:
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
-- PROJECT.md
 - README.md
 - Rakefile
 - docs/index.html
@@ -75,14 +89,15 @@ files:
 - lib/rails/schema/transformer/node.rb
 - lib/rails/schema/version.rb
 - sig/rails/schema.rbs
-homepage: https://github.com/nicholaides/rails-schema
+homepage: https://github.com/andrew2net/rails-schema
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/nicholaides/rails-schema
-  source_code_uri: https://github.com/nicholaides/rails-schema
-  changelog_uri: https://github.com/nicholaides/rails-schema/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/andrew2net/rails-schema
+  source_code_uri: https://github.com/andrew2net/rails-schema
+  changelog_uri: https://github.com/andrew2net/rails-schema/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -90,14 +105,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.1.6
+signing_key:
 specification_version: 4
 summary: Interactive HTML visualization of your Rails database schema
 test_files: []

data/PROJECT.md

@@ -1,367 +0,0 @@
-# Rails::Schema — Project Design
-
-**A Ruby gem that generates an interactive HTML/JS/CSS page to visualize the database schema of a Rails application.**
-
----
-
-## 1. Gem Overview
-
-**Name:** `rails-schema`
-**Module:** `Rails::Schema`
-**Version:** `0.1.2`
-
-Rails::Schema introspects a Rails app's models, associations, and database columns at runtime, then generates a single self-contained HTML file with an interactive, explorable entity-relationship diagram. No external server, no SaaS dependency — just one command and a browser.
-
-```bash
-# Rake task
-rake rails_schema:generate
-
-# Programmatic
-Rails::Schema.generate(output: "docs/schema.html")
-```
-
----
-
-## 2. Architecture
-
-```
-┌──────────────────────────────────────────────────────┐
-│                   rails-schema gem                    │
-├──────────────┬──────────────┬────────────────────────┤
-│  Extractor   │  Transformer │  Renderer              │
-│  (Ruby)      │  (Ruby)      │  (ERB → HTML/JS/CSS)   │
-├──────────────┼──────────────┼────────────────────────┤
-│ Reads Rails  │ Builds a     │ Produces a single      │
-│ models,      │ normalized   │ self-contained .html   │
-│ reflections, │ graph JSON   │ file with embedded     │
-│ schema.rb,   │ structure    │ JS app + CSS           │
-│ columns      │              │                        │
-└──────────────┴──────────────┴────────────────────────┘
-```
-
-### 2.1 Layer Breakdown
-
-| Layer | Responsibility | Key Classes |
-|---|---|---|
-| **Extractor** | Introspects Rails environment; collects models, columns, associations | `Rails::Schema::Extractor::ModelScanner`, `ColumnReader`, `AssociationReader`, `SchemaFileParser`, `StructureSqlParser`, plus `Mongoid::ModelScanner`, `Mongoid::ModelAdapter`, `Mongoid::ColumnReader`, `Mongoid::AssociationReader` |
-| **Transformer** | Normalizes extracted data into a serializable graph structure (nodes + edges + metadata) | `Rails::Schema::Transformer::GraphBuilder`, `Node`, `Edge` |
-| **Renderer** | Takes the graph data and injects it into an HTML/JS/CSS template using ERB | `Rails::Schema::Renderer::HtmlGenerator` |
-| **Railtie** | Provides the `rails_schema:generate` rake task | `Rails::Schema::Railtie` |
-
-### 2.2 Generation Pipeline
-
-```ruby
-def generate(output: nil)
-  schema_data = parse_schema
-  models = Extractor::ModelScanner.new(schema_data: schema_data).scan
-  column_reader = Extractor::ColumnReader.new(schema_data: schema_data)
-  graph_data = Transformer::GraphBuilder.new(column_reader: column_reader).build(models)
-  generator = Renderer::HtmlGenerator.new(graph_data: graph_data)
-  generator.render_to_file(output)
-end
-
-def parse_schema
-  case configuration.schema_format
-  when :ruby then Extractor::SchemaFileParser.new.parse
-  when :sql  then Extractor::StructureSqlParser.new.parse
-  when :auto
-    data = Extractor::SchemaFileParser.new.parse
-    data.empty? ? Extractor::StructureSqlParser.new.parse : data
-  end
-end
-```
-
----
-
-## 3. Data Extraction Strategy
-
-### 3.1 Sources of Truth
-
-1. **`db/schema.rb` parsing** — `SchemaFileParser` parses the schema file line-by-line with regex to extract table names, column definitions (name, type, nullable, default), and primary key info. This is attempted first and used as a fast, database-free source.
-2. **`db/structure.sql` parsing** — `StructureSqlParser` parses SQL `CREATE TABLE` statements for projects using `config.active_record.schema_format = :sql`. Maps SQL types to Rails-friendly types, detects `NOT NULL`, `DEFAULT` values, and primary keys. Handles schema-qualified names (`public.users`), timestamp precision (`timestamp(6)`), and both quoted and unquoted identifiers.
-3. **ActiveRecord reflection API** — `AssociationReader` uses `Model.reflect_on_all_associations` for associations (`has_many`, `belongs_to`, `has_one`, `has_and_belongs_to_many`), including `:through` and `:polymorphic`.
-4. **`Model.columns`** — `ColumnReader` falls back to `model.columns` via ActiveRecord when a table is not found in schema_data.
-
-### 3.2 Model Discovery
-
-`ModelScanner` (ActiveRecord) discovers models by:
-
-1. Calling `Rails.application.eager_load!` (with Zeitwerk support and multiple fallback strategies)
-2. Collecting `ActiveRecord::Base.descendants`
-3. Filtering out abstract classes, anonymous classes, and models without known tables
-4. Applying `exclude_models` configuration (supports wildcard prefix matching like `"ActiveStorage::*"`)
-5. Returning models sorted by name
-
-When `schema_data` is available, table existence is checked against parsed schema data instead of hitting the database.
-
-`Mongoid::ModelScanner` discovers Mongoid models by:
-
-1. Eager-loading models via Zeitwerk or file glob (with fallback strategies)
-2. Scanning `ObjectSpace` for classes that include `Mongoid::Document`
-3. Also eager-loads models from mounted Rails engines
-4. Applying `exclude_models` configuration
-5. Returning models sorted by name, wrapped in `ModelAdapter` for GraphBuilder compatibility
-
-### 3.3 Schema File Parser
-
-`SchemaFileParser` provides database-free column extraction:
-
-- Parses `create_table` blocks from `db/schema.rb`
-- Extracts column types, names, nullability, and defaults (string, numeric, boolean)
-- Handles custom primary key types (`id: :uuid`, `id: :bigint`) and `id: false`
-- Skips index definitions
-
-### 3.4 Structure SQL Parser
-
-`StructureSqlParser` provides database-free column extraction from SQL dumps:
-
-- Parses `CREATE TABLE` statements from `db/structure.sql`
-- Maps SQL types to Rails types (e.g. `character varying` → `string`, `bigint` → `bigint`, `timestamp without time zone` → `datetime`)
-- Handles schema-qualified table names (`public.users` → `users`)
-- Handles timestamp precision (`timestamp(6) without time zone`)
-- Detects primary keys from `CONSTRAINT ... PRIMARY KEY` and inline `PRIMARY KEY`
-- Extracts `NOT NULL`, `DEFAULT` values (strings, numbers, booleans)
-- Skips constraint lines (`CONSTRAINT`, `UNIQUE`, `CHECK`, `FOREIGN KEY`, etc.)
-
-### 3.5 Intermediate Data Format (JSON Graph)
-
-```json
-{
-  "nodes": [
-    {
-      "id": "User",
-      "table": "users",
-      "columns": [
-        { "name": "id", "type": "bigint", "primary": true },
-        { "name": "email", "type": "string", "nullable": false },
-        { "name": "name", "type": "string", "nullable": true }
-      ]
-    }
-  ],
-  "edges": [
-    {
-      "from": "User",
-      "to": "Post",
-      "type": "has_many",
-      "through": null,
-      "foreign_key": "user_id",
-      "polymorphic": false,
-      "label": "posts"
-    }
-  ],
-  "metadata": {
-    "rails_version": "7.2.0",
-    "generated_at": "2026-02-15T12:00:00Z",
-    "model_count": 42
-  }
-}
-```
-
----
-
-## 4. Interactive Frontend Design
-
-The generated HTML file is a **single self-contained file** — no CDN dependencies, no network requests. All JS and CSS are inlined. The JSON graph is embedded as a `<script>` tag.
-
-### 4.1 Technology Choices
-
-| Concern | Choice | Rationale |
-|---|---|---|
-| Graph rendering | **SVG + d3-force** (vendored/minified) | DOM-level interactivity, good for typical schema sizes |
-| Layout algorithm | Force-directed (d3-force) | Natural clustering of related models |
-| UI framework | Vanilla JS | Zero dependencies, small file size |
-| Styling | CSS custom properties + embedded stylesheet | Theming support, dark/light mode |
-
-### 4.2 Implemented Interactive Features
-
-#### A. Model Selector Panel (left sidebar, 280px)
-
-- Searchable list of all models with filtering
-- Multi-select checkboxes to toggle visibility
-- Model count display
-
-#### B. Canvas / Diagram Area (center)
-
-- **Nodes** = model cards showing:
-  - Model name (bold header)
-  - Column list (expandable/collapsible — collapsed by default)
-  - Primary key highlighted
-  - Column types shown in a muted typeface
-- **Edges** = association lines:
-  - Color-coded by association type
-  - Labels on hover (association name + foreign key)
-- **Force-directed layout** that stabilizes, then allows manual drag-and-drop
-
-#### C. Zoom & Navigation
-
-- Scroll-wheel zoom with smooth interpolation
-- Pinch-to-zoom on trackpads
-- Fit-to-screen button
-- Zoom-to-selection (click a model in sidebar to center on it)
-
-#### D. Focus Mode
-
-When a user clicks on a model node:
-
-1. The selected model and its directly associated models are highlighted
-2. All other nodes and edges fade to reduced opacity
-3. A detail panel (right sidebar, 320px) shows full column/association info
-4. Press `Esc` or click background to exit
-
-#### E. Toolbar (48px)
-
-- Dark / Light theme toggle (respects `prefers-color-scheme`)
-- Fit-to-screen button
-- Keyboard shortcuts: `/` to focus search, `Esc` to deselect
-
----
-
-## 5. Configuration
-
-```ruby
-# config/initializers/rails_schema.rb
-Rails::Schema.configure do |config|
-  config.output_path    = "docs/schema.html"    # Output file location
-  config.exclude_models = []                     # Models to exclude (supports "Namespace::*" wildcards)
-  config.title          = "Database Schema"      # Page title
-  config.theme          = :auto                  # :light, :dark, :auto
-  config.expand_columns = false                  # Start with columns expanded
-  config.schema_format  = :auto                  # :auto, :ruby, :sql, or :mongoid
-end
-```
-
----
-
-## 6. Gem Structure
-
-```
-rails-schema/
-├── lib/
-│   ├── rails/schema.rb                    # Entry point, configuration DSL, generate method
-│   └── rails/schema/
-│       ├── version.rb                     # VERSION = "0.1.2"
-│       ├── configuration.rb               # Config object (6 attributes)
-│       ├── railtie.rb                     # Rails integration, rake task
-│       ├── extractor/
-│       │   ├── model_scanner.rb           # Discovers AR models
-│       │   ├── association_reader.rb      # Reads reflections
-│       │   ├── column_reader.rb           # Reads columns (schema_data or AR)
-│       │   ├── schema_file_parser.rb      # Parses db/schema.rb
-│       │   ├── structure_sql_parser.rb   # Parses db/structure.sql
-│       │   └── mongoid/
-│       │       ├── model_scanner.rb      # Discovers Mongoid models
-│       │       ├── model_adapter.rb      # Wraps Mongoid model for GraphBuilder
-│       │       ├── column_reader.rb      # Reads Mongoid fields
-│       │       └── association_reader.rb # Reads Mongoid relations
-│       ├── transformer/
-│       │   ├── graph_builder.rb           # Builds node/edge graph
-│       │   ├── node.rb                    # Value object
-│       │   └── edge.rb                    # Value object
-│       ├── renderer/
-│       │   └── html_generator.rb          # ERB rendering, asset inlining
-│       └── assets/
-│           ├── template.html.erb          # Main HTML template
-│           ├── app.js                     # Interactive frontend (vanilla JS)
-│           ├── style.css                  # Stylesheet with CSS custom properties
-│           └── vendor/
-│               └── d3.min.js              # Vendored d3 library
-├── spec/
-│   ├── spec_helper.rb
-│   ├── support/
-│   │   ├── test_models.rb                # User, Post, Comment, Tag AR models
-│   │   └── mongoid_test_models.rb       # MongoidUser, MongoidPost, MongoidComment
-│   └── rails/schema/
-│       ├── rails_schema_spec.rb
-│       ├── configuration_spec.rb
-│       ├── extractor/
-│       │   ├── model_scanner_spec.rb
-│       │   ├── column_reader_spec.rb
-│       │   ├── association_reader_spec.rb
-│       │   ├── schema_file_parser_spec.rb
-│       │   ├── structure_sql_parser_spec.rb
-│       │   └── mongoid/
-│       │       ├── model_scanner_spec.rb
-│       │       ├── model_adapter_spec.rb
-│       │       ├── column_reader_spec.rb
-│       │       └── association_reader_spec.rb
-│       ├── transformer/
-│       │   └── graph_builder_spec.rb
-│       └── renderer/
-│           └── html_generator_spec.rb
-├── Gemfile
-├── rails-schema.gemspec
-├── LICENSE.txt
-└── README.md
-```
-
----
-
-## 7. Key Design Decisions
-
-### Why a single HTML file?
-
-- **Zero deployment friction** — open in any browser, share via Slack/email, commit to repo
-- **Offline-first** — works on airplane mode, no CDN failures
-- **Portable** — CI can generate it, GitHub Pages can host it, anyone can view it
-
-### Why not a mounted Rails engine?
-
-A mounted engine requires a running server. A static file can be generated in CI, committed to the repo, and opened by anyone — including non-developers looking at a data model.
-
-### Why parse schema.rb / structure.sql?
-
-Parsing `db/schema.rb` or `db/structure.sql` allows column extraction without a database connection. This means the gem can work in CI environments or development setups where the database isn't running. It also avoids eager-loading the entire app just to read column metadata. The `schema_format: :auto` default tries `schema.rb` first, then falls back to `structure.sql`, so the gem works out of the box regardless of which format a project uses.
-
-### Why force-directed layout?
-
-It handles unknown schemas gracefully — you don't need to pre-define positions. Combined with drag-and-drop repositioning, it gives the best default experience.
-
----
-
-## 8. Dependencies
-
-```ruby
-# rails-schema.gemspec
-spec.add_dependency "activerecord", ">= 6.0"
-spec.add_dependency "railties", ">= 6.0"
-
-# Development
-# rspec (~> 3.0), rubocop (~> 1.21), sqlite3
-```
-
-**Zero runtime JS dependencies shipped to the user** — d3 is vendored and minified into the template. The HTML file has no external requests.
-
----
-
-## 9. Testing Strategy
-
-| Layer | Approach |
-|---|---|
-| Extractor | Unit tests with in-memory SQLite models (User, Post, Comment, Tag); rescue-path warnings tested via `output(...).to_stderr` |
-| Transformer | Pure Ruby unit tests — graph building, edge filtering |
-| Renderer | Output tests — verify HTML structure, embedded data, script injection safety |
-| Configuration | Unit tests for defaults and attribute setting |
-
-**153 tests, all passing.** Run with `bundle exec rspec`.
-
----
-
-## 10. Future Enhancements (Roadmap)
-
-1. **CLI executable** — `bundle exec rails_schema` binary for standalone usage
-2. **Live mode** — a mounted Rails engine with hot-reload when migrations run
-3. **Additional layout modes** — hierarchical, circular, grid
-4. **Validation extraction** — read `Model.validators` for presence, uniqueness constraints
-5. **STI handling** — group models sharing a table, show children as badges
-6. **Concern extraction** — display included modules on model nodes
-7. **Export options** — PNG, SVG, Mermaid ER diagram, raw JSON
-8. **Schema diff** — compare two generated JSONs and highlight changes
-9. **Multi-database support** — Rails 6+ multi-DB configs
-10. **Minimap** — thumbnail overview for large schemas
-11. **Permalink / State URL** — encode view state in URL hash for sharing
-12. **Advanced filtering** — `include_only`, namespace grouping, tag-based filters
-13. **Custom CSS/JS injection** — user-provided assets inlined into output
-
----
-
-*Document reflects the current implementation (v0.1.2). Future enhancements are aspirational and subject to refinement.*