rails-schema 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37ed34e2667a948b30551666b19657a3bf6e1a484e4fe4660a3da03c9d356f66
-  data.tar.gz: c7f9ac452ae98d4188718c47879a2b1fc2769b21d308b7d07f89779c42273f95
+  metadata.gz: 14f99b5a4a676074862ccab2a47f79ebb68595632cf6b3770e9383d14ab02202
+  data.tar.gz: e145477c9d42ac72e16972eed1ef0d2dd3d325cd4a9fcf1ba0bf595beceb2d4d
 SHA512:
-  metadata.gz: a21acfd8d250d9fffdd67acc95a6743167f26cf2754c4d71d35af9a74a1f450c4954eb6443fe20d8198e066f8ef8e783924ed4cab3a7b39f7f2f9006e5913af7
-  data.tar.gz: 837e5b1171e30ff17aca2e8871bed916d691203c28e8a876d92948ef38018ce23856f7263c95d96c3334c04be853b46bad48cd09101f5b7cf42da742f1db9246
+  metadata.gz: c756f2e042f3b2958357eeb3048f900ea695139f4163ebe50770926dd1e597eda5695f96aa4763e7a401ef5b5f5d767e5306bd595528534cffb08601e20cda4a
+  data.tar.gz: 3a7734bc958fdac6246e35585fb66ed62609c1bbfa30dd5fa8640dcb36d7817d774321dd439bb51589eef657cdd8b7324699babf20e34ecf49a3367da6140a51

data/CHANGELOG.md

@@ -4,6 +4,46 @@ 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.5] - 2026-03-14
+
+### Added
+
+- `exclude_model_if` configuration option: provide a proc/lambda to dynamically exclude models based on arbitrary conditions, works with both ActiveRecord and Mongoid pipelines (#16)
+- Mermaid ER diagram export (`.mmd`) — respects sidebar visibility filters so you can export a subset of models (#23)
+- Double-click a model node to isolate its neighborhood (#20)
+- Shift-click range selection for sidebar checkboxes (#24)
+- Smart "Select All" toggle — when all models are selected and a search filter is active, narrows to only filtered models (#24)
+- Search clear button in the sidebar (#24)
+- Color-coded edge labels by association type (#19)
+- Edge deduplication for `has_many`/`belongs_to` pairs — reciprocal associations are merged into a single edge with dual labels, each colored by its own association type
+
+### Changed
+
+- Refactored text measurement and truncation functions for cleaner rendering
+
+## [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::*"`) and `exclude_model_if` proc
+
+`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,24 @@ 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, double-click to isolate neighborhood, detail panel, zoom/pan, keyboard shortcuts (`/` search, `Esc` deselect, `+/-` zoom, `F` fit), Mermaid ER diagram export (`.mmd`) filtered by sidebar visibility
+- **Select All smart toggle** — when all models are already selected and a search filter is active, "Select All" narrows to only filtered models (acts as "select only these"); otherwise it adds filtered models to the current selection
+
+## 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()`
+- **Edge deduplication** — `GraphBuilder.deduplicate_edges` chains two passes: (1) HABTM dedup merges symmetric `has_and_belongs_to_many` pairs into one edge with `reverse_label`, (2) has_many/belongs_to dedup merges matching pairs (same foreign_key, reversed endpoints) into one edge where the has_many/has_one side is kept and the belongs_to label becomes `reverse_label` with its own `reverse_association_type`. The frontend uses `reverse_association_type` to color each label by its own association type.

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)
@@ -54,6 +61,7 @@ Rails::Schema.configure do |config|
     "ActiveStorage::Attachment",
     "ActionMailbox::*"           # wildcard prefix matching
   ]
+  config.exclude_model_if = ->(model) { model.table_name.start_with?("_") }
 end
 ```
 
@@ -65,6 +73,7 @@ end
 | `expand_columns` | `false` | Whether model nodes start with columns expanded |
 | `schema_format` | `:auto` | Schema source — `:auto`, `:ruby`, `:sql`, or `:mongoid` (see below) |
 | `exclude_models` | `[]` | Models to hide; supports exact names and wildcard prefixes (`"ActionMailbox::*"`) |
+| `exclude_model_if` | `nil` | A proc/lambda that receives a model class and returns `true` to exclude it |
 
 ### Schema format
 
@@ -100,13 +109,18 @@ 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
-- **Searchable sidebar** — filter models by name or table
+- **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, with a clear button to reset
+- **Select/Deselect All** — operates on filtered (visible) models only, so you can search and bulk-toggle a subset; when all models are selected and a search filter is active, "Select All" narrows the selection to only the filtered models
+- **Shift-click range selection** — hold Shift and click checkboxes to toggle a range at once
 - **Click-to-focus** — click a model to highlight its neighborhood, fading unrelated models
+- **Double-click to isolate** — double-click a model to filter the view to only that model and its direct neighbors
 - **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
+- **Export to Mermaid** — download the diagram as a `.mmd` file for use in Markdown, GitHub, or other tools that render Mermaid ER diagrams; respects sidebar visibility filters so you can export a subset of models
+- **Deduplicated edges** — reciprocal associations (e.g. `has_many :posts` / `belongs_to :user`, or symmetric HABTM) are merged into a single edge with dual labels, each colored by its own association type
 - **Self-contained** — single HTML file with all CSS, JS, and data inlined
 
 ## License