rails-schema 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1275bccb3e5144d351dcf4445209299ee269dfae8e75b4176e8a91bb85b5ccc2
+  data.tar.gz: 2ba3e983963eaef3a933ba9d99eebd7b3221acdaca492212ddda04d5a0354122
+SHA512:
+  metadata.gz: bade47644111e000883867b876dad54b59aa07df5800719185c48cd9d2307fa030d3d1df38c00a738be94bd2c37426bbe5d181729dc9b0995872103449332e1b
+  data.tar.gz: ee1eaa1f3050778be38ae59a69269b93658e149466cc135ec7eb58cbc34cbf2ec814ea99d665777887c64ff341440351a63ac9707a791add32e9fb30d152ab52

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Andrei Kislichenko
+
+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/PROJECT.md

@@ -0,0 +1,322 @@
+# 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.0`
+
+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` |
+| **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 = Extractor::SchemaFileParser.new.parse
+  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
+```
+
+---
+
+## 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. **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`.
+3. **`Model.columns`** — `ColumnReader` falls back to `model.columns` via ActiveRecord when a table is not found in schema_data.
+
+### 3.2 Model Discovery
+
+`ModelScanner` 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.
+
+### 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 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
+end
+```
+
+---
+
+## 6. Gem Structure
+
+```
+rails-schema/
+├── lib/
+│   ├── rails/schema.rb                    # Entry point, configuration DSL, generate method
+│   └── rails/schema/
+│       ├── version.rb                     # VERSION = "0.1.0"
+│       ├── configuration.rb               # Config object (5 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
+│       ├── 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 models
+│   └── 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
+│       ├── 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?
+
+Parsing `db/schema.rb` 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.
+
+### 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) |
+| 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 |
+
+**66 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.0). Future enhancements are aspirational and subject to refinement.*

data/README.md

@@ -0,0 +1,77 @@
+# Rails::Schema
+
+Interactive HTML visualization of your Rails database schema. Introspects your app's models, associations, and columns, then generates a single self-contained HTML file with an interactive entity-relationship diagram.
+
+No external server, no CDN — just one command and a browser.
+
+**[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)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "rails-schema", group: :development
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Rake task
+
+```bash
+rake rails_schema:generate
+```
+
+This generates `docs/schema.html` by default. Open it in your browser.
+
+### Programmatic
+
+```ruby
+Rails::Schema.generate(output: "docs/schema.html")
+```
+
+## Configuration
+
+Create an initializer at `config/initializers/rails_schema.rb`:
+
+```ruby
+Rails::Schema.configure do |config|
+  config.output_path = "docs/schema.html"
+  config.title = "My App Schema"
+  config.theme = :auto          # :auto, :light, or :dark
+  config.expand_columns = false # start with columns collapsed
+  config.exclude_models = [
+    "ActiveStorage::Blob",
+    "ActiveStorage::Attachment",
+    "ActionMailbox::*"           # wildcard prefix matching
+  ]
+end
+```
+
+## How it works
+
+The gem parses your `db/schema.rb` file to extract table and column information — **no database connection required**. It also introspects loaded ActiveRecord models for association metadata. This means the gem works even if you don't have a local database set up, as long as `db/schema.rb` is present (which is standard in Rails projects under version control).
+
+## Features
+
+- **No database required** — reads directly from `db/schema.rb`
+- **Force-directed layout** — models cluster naturally by association density
+- **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
+- **Dark/light theme** — toggle or auto-detect from system preference
+- **Zoom & pan** — scroll wheel, pinch, or buttons
+- **Keyboard shortcuts** — `/` search, `Esc` deselect, `+/-` zoom, `F` fit to screen
+- **Self-contained** — single HTML file with all CSS, JS, and data inlined
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]