rails-realtime-erd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: efe3b4e2ea8f20ac758e39b19f90494e08dc462d6582e8581555eebf69f2baa6
+  data.tar.gz: 053f0a83cd28180b2a95895d27e69e13d73299495effbaadc3dc5a97f6806521
+SHA512:
+  metadata.gz: 17ef9d429795bc8100e029edadbb3e78f548cdd8d687f910b019eb1e0e894a0a550fcc5e60d8e848129895dcd03bde37b5e3950bbf08e414a045128bfdbb71f1
+  data.tar.gz: 71e1b2f091c753a558d1daf47f837fb95328b516f52d36491c368d8468a70657036883f8aeab84defccc855996f487fdbd80fa4781948ac72f7e8009ce7dfd22

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jackson Pires
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+# Rails Realtime ERD
+
+Live Mermaid ERD viewer for any Rails app, mounted as a real-time route, powered by Hotwire.
+
+Inspired by [`rails-mermaid_erd`](https://github.com/koedame/rails-mermaid_erd) — but instead of generating a static HTML file you check into your repo, this gem mounts `GET /rails/erd` in your Rails app and renders the ERD **on every request** by introspecting your current `ActiveRecord` models and live schema. Run a migration, refresh the page, see the new diagram.
+
+The frontend is plain Hotwire (Stimulus) — **no Vue**, no build step, no asset pipeline required in the host app.
+
+## Features
+
+- Mounts `/rails/erd` automatically in `development` and `test` environments
+- On-the-fly introspection: no pre-generated HTML to keep in sync with `schema.rb`
+- Mermaid ERD rendered client-side, with filters / options / zoom / pan
+- Copy Mermaid code, Copy Markdown, Copy shareable URL (state in `location.hash`)
+- Download SVG / PNG of the rendered diagram
+- Sidebar filter to scope the diagram to a subset of models
+- Works with any host asset pipeline (Sprockets, Propshaft, importmap, or none) — all CSS/JS is inlined by the engine layout
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "rails-realtime-erd", group: :development
+```
+
+Then:
+
+```bash
+$ bundle install
+```
+
+That's it. Boot your Rails dev server and visit:
+
+```
+http://localhost:3000/rails/erd
+```
+
+## Configuration
+
+Optional. Create `config/initializers/rails_realtime_erd.rb`:
+
+```ruby
+RailsRealtimeErd.configure do |c|
+  c.mount_path           = "/rails/erd"           # default
+  c.auto_mount           = true                    # default
+  c.enabled_environments = %w[development test]    # default
+end
+```
+
+If you set `auto_mount = false`, mount the engine yourself in `config/routes.rb`:
+
+```ruby
+mount RailsRealtimeErd::Engine => "/rails/erd"
+```
+
+## Why use it instead of `rails-mermaid_erd`?
+
+- No rake step. No `mermaid_erd/index.html` to regenerate, share, or `.gitignore`.
+- The diagram is always in sync with your live schema and models.
+- No JS framework dependency in your host app — only standard Hotwire.
+
+If you want a shareable static file (for documentation, CI artifacts, public demos), use [`rails-mermaid_erd`](https://github.com/koedame/rails-mermaid_erd). The two gems target different use cases.
+
+## Development
+
+Specs run against a SQLite-backed dummy Rails app in `spec/dummy`. SQLite does not preserve column/table comments, so the Builder spec asserts `nil`/`""` for those fields even though the schema declares comments — the Builder forwards whatever the connection returns, so on Postgres/MySQL those values round-trip correctly.
+
+```bash
+$ bundle install
+$ bundle exec rspec
+```
+
+## License
+
+MIT. See `MIT-LICENSE`.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+end

data/app/assets/stylesheets/rails_realtime_erd/erd.css

@@ -0,0 +1,214 @@
+/* =========================================================================
+ * Rails Realtime ERD — self-contained stylesheet.
+ *
+ * Implements only the utility classes referenced by this gem's ERB views,
+ * plus a small reset. Intentionally avoids a CDN so the engine renders
+ * correctly inside hosts with strict Content Security Policy.
+ * ========================================================================= */
+
+/* ------- Reset / Preflight ------- */
+*, *::before, *::after { box-sizing: border-box; border: 0 solid #e5e7eb; }
+html, body { margin: 0; padding: 0; }
+body {
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  font-size: 14px;
+  line-height: 1.4;
+  color: #111827;
+  background: #ffffff;
+}
+h1, h2, h3, h4, p { margin: 0; font-size: inherit; font-weight: inherit; }
+button {
+  background: transparent;
+  cursor: pointer;
+  font-family: inherit;
+  font-size: 100%;
+  padding: 0;
+  border: 0;
+  color: inherit;
+  -webkit-appearance: button;
+}
+input, textarea, select {
+  font-family: inherit;
+  font-size: 100%;
+  line-height: inherit;
+  color: inherit;
+  margin: 0;
+  padding: 0;
+}
+textarea { resize: vertical; }
+input[type="search"] { -webkit-appearance: textfield; outline-offset: -2px; }
+input[type="checkbox"] {
+  appearance: auto;
+  width: 1rem;
+  height: 1rem;
+  vertical-align: middle;
+  accent-color: #dc2626;
+}
+svg { display: inline-block; vertical-align: middle; flex-shrink: 0; }
+a { color: inherit; text-decoration: inherit; }
+
+/* ------- Display / Layout ------- */
+.flex { display: flex; }
+.inline-flex { display: inline-flex; }
+.block { display: block; }
+.flex-1 { flex: 1 1 0%; }
+.flex-none { flex: none; }
+.flex-col { flex-direction: column; }
+.items-center { align-items: center; }
+.items-start { align-items: flex-start; }
+.justify-between { justify-content: space-between; }
+.justify-center { justify-content: center; }
+.min-w-0 { min-width: 0; }
+
+/* ------- Position ------- */
+.relative { position: relative; }
+.absolute { position: absolute; }
+.inset-0 { top: 0; right: 0; bottom: 0; left: 0; }
+.bottom-0 { bottom: 0; }
+.right-0 { right: 0; }
+.left-1\/2 { left: 50%; }
+.-translate-x-1\/2 { transform: translateX(-50%); }
+.pointer-events-none { pointer-events: none; }
+
+/* ------- Spacing — margin ------- */
+.mx-auto { margin-left: auto; margin-right: auto; }
+.mr-1 { margin-right: 0.25rem; }
+.mr-2 { margin-right: 0.5rem; }
+.ml-1 { margin-left: 0.25rem; }
+.mb-1 { margin-bottom: 0.25rem; }
+.my-1 { margin-top: 0.25rem; margin-bottom: 0.25rem; }
+
+/* ------- Spacing — padding ------- */
+.p-1 { padding: 0.25rem; }
+.p-2 { padding: 0.5rem; }
+.p-4 { padding: 1rem; }
+.px-2 { padding-left: 0.5rem; padding-right: 0.5rem; }
+.px-3 { padding-left: 0.75rem; padding-right: 0.75rem; }
+.px-4 { padding-left: 1rem; padding-right: 1rem; }
+.py-1 { padding-top: 0.25rem; padding-bottom: 0.25rem; }
+.py-1\.5 { padding-top: 0.375rem; padding-bottom: 0.375rem; }
+.py-2 { padding-top: 0.5rem; padding-bottom: 0.5rem; }
+.py-4 { padding-top: 1rem; padding-bottom: 1rem; }
+
+/* ------- Space-between children ------- */
+.space-x-1 > * + * { margin-left: 0.25rem; }
+.space-x-2 > * + * { margin-left: 0.5rem; }
+.space-x-4 > * + * { margin-left: 1rem; }
+.space-x-6 > * + * { margin-left: 1.5rem; }
+.space-y-1 > * + * { margin-top: 0.25rem; }
+.space-y-2 > * + * { margin-top: 0.5rem; }
+.space-y-8 > * + * { margin-top: 2rem; }
+
+/* ------- Sizing ------- */
+.w-full { width: 100%; }
+.w-\[250px\] { width: 250px; }
+.w-3 { width: 0.75rem; }
+.w-4 { width: 1rem; }
+.w-6 { width: 1.5rem; }
+.h-3 { height: 0.75rem; }
+.h-4 { height: 1rem; }
+.h-6 { height: 1.5rem; }
+.h-full { height: 100%; }
+.min-h-\[calc\(100vh-56px-32px\)\] { min-height: calc(100vh - 56px - 32px); }
+.min-h-\[calc\(100vh-56px-32px-56px\)\] { min-height: calc(100vh - 56px - 32px - 56px); }
+
+/* ------- Borders ------- */
+.border { border-width: 1px; }
+.border-0 { border-width: 0; }
+.border-r { border-right-width: 1px; }
+.border-gray-300 { border-color: #d1d5db; }
+.rounded { border-radius: 0.25rem; }
+
+/* ------- Background colors ------- */
+.bg-red-600 { background-color: #dc2626; }
+.bg-gray-100 { background-color: #f3f4f6; }
+.bg-gray-300 { background-color: #d1d5db; }
+.bg-gray-400 { background-color: #9ca3af; }
+.bg-gray-800 { background-color: #1f2937; }
+.bg-gray-900 { background-color: #111827; }
+.bg-white { background-color: #ffffff; }
+
+/* ------- Text colors ------- */
+.text-white { color: #ffffff; }
+.text-white\/60 { color: rgba(255, 255, 255, 0.6); }
+.text-white\/80 { color: rgba(255, 255, 255, 0.8); }
+.text-gray-300 { color: #d1d5db; }
+.text-gray-600 { color: #4b5563; }
+.text-gray-700 { color: #374151; }
+.text-gray-900 { color: #111827; }
+.text-red-200 { color: #fecaca; }
+.text-red-600 { color: #dc2626; }
+.text-red-900 { color: #7f1d1d; }
+.text-orange-900 { color: #7c2d12; }
+
+/* ------- Typography ------- */
+.text-xs { font-size: 0.75rem; line-height: 1rem; }
+.text-sm { font-size: 0.875rem; line-height: 1.25rem; }
+.text-\[10px\] { font-size: 10px; line-height: 1.2; }
+.font-bold { font-weight: 700; }
+.font-medium { font-weight: 500; }
+.font-mono { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; }
+.text-center { text-align: center; }
+
+/* ------- Hover ------- */
+.hover\:bg-white:hover { background-color: #ffffff; }
+.hover\:bg-gray-100:hover { background-color: #f3f4f6; }
+.hover\:text-gray-400:hover { color: #9ca3af; }
+.hover\:text-red-200:hover { color: #fecaca; }
+.hover\:text-red-900:hover { color: #7f1d1d; }
+
+/* ------- Cursors / state ------- */
+.cursor-pointer { cursor: pointer; }
+.cursor-not-allowed { cursor: not-allowed; }
+.cursor-grab { cursor: grab; }
+.cursor-grabbing { cursor: grabbing; }
+.opacity-60 { opacity: 0.6; }
+
+/* ------- Focus rings (simplified) ------- */
+.focus\:ring:focus,
+.focus\:ring-2:focus { outline: 2px solid #dc2626; outline-offset: 2px; }
+.focus\:ring-red-600:focus { outline-color: #dc2626; }
+.focus\:ring-white:focus { outline-color: #ffffff; }
+.focus\:ring-0:focus { outline: 0; }
+.focus\:ring-offset-1:focus { outline-offset: 1px; }
+.focus\:ring-offset-2:focus { outline-offset: 2px; }
+.focus\:border-red-600:focus { border-color: #dc2626; }
+
+/* ------- Misc ------- */
+.overflow-hidden { overflow: hidden; }
+
+/* ------- Mermaid override ------- */
+#mermaid-erd { fill: #9c9c9c !important; }
+
+/* ------- Engine-specific ------- */
+[data-rre-hidden] { display: none !important; }
+
+[data-zoom-pan-target="area"] {
+  transform-origin: top left;
+  will-change: transform;
+  position: absolute;
+  inset: 0;
+}
+
+[data-zoom-pan-dragging="true"],
+[data-zoom-pan-dragging="true"] * {
+  user-select: none;
+  cursor: grabbing !important;
+}
+
+[data-zoom-pan-space-pressed="true"] [data-zoom-pan-target="canvas"] {
+  cursor: grab;
+}
+
+#rre-preview {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1rem;
+}
+#rre-preview svg {
+  max-width: 100%;
+  height: auto;
+}

data/app/controllers/rails_realtime_erd/application_controller.rb

@@ -0,0 +1,5 @@
+module RailsRealtimeErd
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end

data/app/controllers/rails_realtime_erd/assets_controller.rb

@@ -0,0 +1,23 @@
+module RailsRealtimeErd
+  class AssetsController < ApplicationController
+    ASSETS = {
+      "stimulus.js" => "app/javascript/rails_realtime_erd/vendor/stimulus.js",
+      "mermaid.js" => "app/javascript/rails_realtime_erd/vendor/mermaid.js",
+      "application.js" => "app/javascript/rails_realtime_erd/application.js"
+    }.freeze
+
+    skip_forgery_protection if respond_to?(:skip_forgery_protection)
+
+    def show
+      relative_path = ASSETS[params[:name]]
+      return head :not_found unless relative_path
+
+      path = Engine.root.join(relative_path)
+      return head :not_found unless File.exist?(path)
+
+      response.headers["Cache-Control"] = "private, max-age=300"
+      response.headers["X-Content-Type-Options"] = "nosniff"
+      send_file path, type: "text/javascript; charset=utf-8", disposition: "inline"
+    end
+  end
+end

data/app/controllers/rails_realtime_erd/erd_controller.rb

@@ -0,0 +1,18 @@
+module RailsRealtimeErd
+  class ErdController < ApplicationController
+    layout "rails_realtime_erd/application"
+
+    def show
+      ::Rails.application.eager_load!
+
+      if ::Rails.env.development?
+        connection = ::ActiveRecord::Base.connection
+        connection.schema_cache.clear! if connection.respond_to?(:schema_cache)
+      end
+
+      @schema = Builder.model_data
+      @app_name = ::Rails.application.class.try(:module_parent_name) || ::Rails.application.class.try(:parent_name) || "Application"
+      @version = RailsRealtimeErd::VERSION
+    end
+  end
+end

data/app/helpers/rails_realtime_erd/erd_helper.rb

@@ -0,0 +1,25 @@
+module RailsRealtimeErd
+  module ErdHelper
+    def inline_asset(relative_path)
+      path = Engine.root.join(relative_path)
+      File.read(path)
+    end
+
+    def inline_stylesheet(relative_path)
+      content_tag(:style, inline_asset(relative_path).html_safe)
+    end
+
+    def inline_javascript(relative_path, type: "module")
+      content_tag(:script, inline_asset(relative_path).html_safe, type: type)
+    end
+
+    def schema_data_tag(schema)
+      content_tag(
+        :script,
+        schema.to_json.html_safe,
+        type: "application/json",
+        id: "rre-schema-data"
+      )
+    end
+  end
+end