rails-schema 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14f99b5a4a676074862ccab2a47f79ebb68595632cf6b3770e9383d14ab02202
-  data.tar.gz: e145477c9d42ac72e16972eed1ef0d2dd3d325cd4a9fcf1ba0bf595beceb2d4d
+  metadata.gz: 06e278b737001f1ceeae2ef9d2014893a265125c7c011191a222a3d3fc48745e
+  data.tar.gz: '039a8aef58083c1ff5e023fee87e113c394a0dc1f008e37421460187f6fb3d44'
 SHA512:
-  metadata.gz: c756f2e042f3b2958357eeb3048f900ea695139f4163ebe50770926dd1e597eda5695f96aa4763e7a401ef5b5f5d767e5306bd595528534cffb08601e20cda4a
-  data.tar.gz: 3a7734bc958fdac6246e35585fb66ed62609c1bbfa30dd5fa8640dcb36d7817d774321dd439bb51589eef657cdd8b7324699babf20e34ecf49a3367da6140a51
+  metadata.gz: 17d59e29828e31ee3298a2f5b0f86b24d31240912b77668874f2be071c610f3af50641ebadaaf1c449d6cd532c0b5bdc4ac36c6137cdc15f5ca075a102c1a9e1
+  data.tar.gz: 979e7da7b4e3fb215b2f25095ae0eae96d6901efa5cb0915a5a76273571ec222ccc5fa41f2495e15126f3c01312a4096f5e44966a0b94c8e0fc59228dcb0b957

data/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.7] - 2026-04-25
+
+### Added
+
+- Manual Positioning toggle — toolbar checkbox that removes all simulation forces when enabled; nodes stay wherever they are dropped and drag-and-drop continues to work normally; unchecking re-enables automatic force-directed layout (#33)
+- Layout persistence — node positions, visibility, zoom, and toggle states are auto-saved to `localStorage` and restored on page reload; layouts are scoped per schema via a fingerprint hash so different projects don't collide (#33)
+- Save/Load Layout — export the current layout as a portable `.json` file to share with teammates or check into git; import a saved layout file to restore it (#33)
+- File menu dropdown — toolbar "File" menu groups Export Mermaid, Save Layout, and Load Layout actions (#33)
+
+## [0.1.6] - 2026-03-28
+
+### Added
+
+- Model grouping via `model_schema_group` configuration — organize sidebar models under collapsible group headers with color-coded dots; supports `:namespaces` or a custom `Proc`; same-group nodes cluster via d3 force (#27)
+- Packwerk package discovery — `PackwerkDiscovery` auto-discovers model directories from Packwerk packages (`packwerk.yml` → `package_paths`) (#29)
+- Through edges toggle — legend checkbox to show/hide `:through` edges at runtime; `show_through_edges` config sets initial state (default `true`); through associations remain visible in the detail panel (#31)
+
 ## [0.1.5] - 2026-03-14
 
 ### Added

data/CLAUDE.md

@@ -18,7 +18,7 @@ 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` |
+| **Extractor** | Introspects Rails environment; collects models, columns, associations | `ModelScanner`, `PackwerkDiscovery`, `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` |
@@ -54,10 +54,16 @@ end
 ### 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
+1. Discovers model directories: `app/models` + Packwerk package dirs via `PackwerkDiscovery`
+2. Eager-loads via Zeitwerk `eager_load_dir` for each model directory; falls back to `loader.eager_load` if no concrete models found, then `Rails.application.eager_load!`, then per-file `require`
+3. Collects `ActiveRecord::Base.descendants`
+4. Filters: abstract classes, anonymous classes, models without known tables
+5. Applies `exclude_models` config (supports wildcard prefix like `"ActiveStorage::*"`) and `exclude_model_if` proc
+
+`PackwerkDiscovery`:
+1. Reads `packwerk.yml` from `Rails.root` for `package_paths` glob patterns
+2. Finds directories with `package.yml` under those paths
+3. Returns `app/models` and `app/public` paths for each package
 
 `Mongoid::ModelScanner`:
 1. Eager-loads via Zeitwerk or file glob with fallbacks
@@ -71,7 +77,7 @@ end
 - Double quotes for strings (RuboCop enforced)
 - RuboCop max method length: 15 lines, default ABC/complexity limits
 - No `Style/Documentation` required
-- `spec/support/test_models.rb` — ActiveRecord test models (User, Post, Comment, Tag)
+- `spec/support/test_models.rb` — ActiveRecord test models (User, Post, Comment, Tag, Admin::Dashboard, Admin::Reports::Summary)
 - `spec/support/mongoid_test_models.rb` — Mongoid test models (MongoidUser, MongoidPost, MongoidComment)
 - Tests use in-memory SQLite for ActiveRecord, stubbed Mongoid::Document for Mongoid
 - `config.before(:each) { Rails::Schema.reset_configuration! }` in spec_helper
@@ -96,8 +102,13 @@ Single self-contained HTML file — no CDN, no network requests. D3 is vendored/
 
 - **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
+- Features: searchable sidebar, click-to-focus, double-click to isolate neighborhood, detail panel (clicking a relation link auto-selects the related model, adding it to the diagram if hidden), zoom/pan, keyboard shortcuts (`/` search, `Esc` deselect, `+/-` zoom, `F` fit)
+- **Through edges toggle** — legend checkbox to show/hide `:through` edges on the diagram at runtime; `config.show_through_edges` (default `true`) sets the initial checkbox state; through associations always remain visible in the detail panel regardless of toggle state; filtering happens in `setupSimulation()` on the frontend (edges stay in `data.edges` for the detail panel)
+- **Manual Positioning toggle** — toolbar checkbox that removes all simulation forces when enabled; nodes stay wherever they are dropped since nothing pushes or pulls them; drag-and-drop continues to work normally via the standard `fx/fy` mechanism; unchecking calls `render()` to restore all forces and resume automatic layout; in manual mode, `ticked()` skips `layoutOrphans()`/`layoutSelfRefNodes()` to preserve manually-placed positions; `dragEnded` keeps `fx/fy` set so nodes stay pinned where dropped
+- **Layout persistence** — node positions, visibility, zoom, collapsed groups, and toggle states are auto-saved to `localStorage` on every state change; on page load, saved layout is restored via `applyLayout()`, which honors the saved `manualPositioning` flag: when true, nodes are pinned via `fx/fy` and forces are removed so the restored layout is frozen; when false, positions seed `x/y` only and forces keep running so automatic layout resumes; `localStorage` key is `"rails-schema-layout:" + fingerprint` where fingerprint is a djb2 hash of sorted node IDs, so different schemas get separate saved layouts
+- **File menu dropdown** — toolbar dropdown ("File ▼") groups export/import actions: "Export Mermaid" (`.mmd` filtered by sidebar visibility), "Save Layout" (downloads a `.json` file with positions, visibility, zoom, and toggle state), "Load Layout" (reads a `.json` file via file picker and applies it); the JSON format uses a `version: 1` field and `schemaFingerprint` for forward compatibility; layout files are portable and can be shared with teammates or checked into git
 - **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
+- **Model grouping** — when `config.model_schema_group` is set, models are organized under collapsible group headers in the sidebar with color-coded dots; each group's models get a distinct node header color in the SVG; a custom d3 force (`strength 0.15`) pulls same-group nodes toward their centroid, and a separation force pushes overlapping group bounding boxes apart; double-click a group header to select/deselect (uses delayed click timer to avoid triggering collapse); search also matches group names
 
 ## Design Decisions
 
@@ -107,3 +118,5 @@ Single self-contained HTML file — no CDN, no network requests. D3 is vendored/
 - **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.
+- **Layout persistence** — dual storage: `localStorage` for automatic save/restore (zero friction), plus JSON file export/import for portability and sharing. Restoring a layout honors the saved `manualPositioning` flag: manual-mode layouts are pinned and frozen (forces removed) so they survive exactly; auto-mode layouts seed initial positions but let forces keep running so the user can return to automatic layout by unchecking the toggle and reloading. The `schemaFingerprint` (djb2 hash of sorted node IDs) scopes `localStorage` keys so different schemas don't collide and schema changes get a clean slate.
+- **Model grouping config** — `config.model_schema_group` accepts `nil` (default, no grouping), `:namespaces` (splits `model.name` on `::`, drops the model name, keeps namespace parts), or a custom `Proc` that receives a model and returns an array (e.g., `["Admin", "Reports"]`). `Configuration#resolved_group_proc` normalizes all forms into a callable proc. `GraphBuilder` calls it per model and attaches the result as `Node#group`. The `group` field is omitted from JSON when empty to keep output compact when grouping is off.

data/README.md

@@ -62,6 +62,9 @@ Rails::Schema.configure do |config|
     "ActionMailbox::*"           # wildcard prefix matching
   ]
   config.exclude_model_if = ->(model) { model.table_name.start_with?("_") }
+  config.model_schema_group = :namespaces  # group models by Ruby namespace
+  config.collapse_groups = true            # start with groups collapsed
+  config.show_through_edges = true         # show :through edges on the diagram
 end
 ```
 
@@ -74,6 +77,9 @@ end
 | `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 |
+| `model_schema_group` | `nil` | Group models visually — `:namespaces`, or a custom proc (see below) |
+| `collapse_groups` | `true` | Whether sidebar groups start collapsed |
+| `show_through_edges` | `true` | Whether `:through` association edges are shown on the diagram initially (toggleable at runtime via legend checkbox) |
 
 ### Schema format
 
@@ -100,29 +106,85 @@ When set to `:auto`, Mongoid mode activates automatically if `Mongoid::Document`
 
 The Mongoid pipeline reads fields, types, defaults, and presence validations from your models, and discovers all association types including `embeds_many`, `embeds_one`, `embedded_in`, and `has_and_belongs_to_many`.
 
+### Model grouping
+
+Group models visually by assigning each group a distinct header color in the diagram and organizing them under collapsible headers in the sidebar.
+
+**By namespace** — splits on `::` and groups by the namespace path:
+
+```ruby
+Rails::Schema.configure do |config|
+  config.model_schema_group = :namespaces
+end
+```
+
+This groups `Admin::Dashboard` under "Admin" and `Admin::Reports::Summary` under "Admin > Reports". Non-namespaced models like `User` remain ungrouped.
+
+**Custom proc** — return an array representing the group hierarchy:
+
+```ruby
+Rails::Schema.configure do |config|
+  config.model_schema_group = proc do |model|
+    case model.name
+    when /^Admin::/ then ["Admin"]
+    when /^Billing::/ then ["Billing"]
+    else ["Core"]
+    end
+  end
+end
+```
+
+Returning `["A", "B"]` means group "A" with subgroup "B". Returning `[]` or `nil` leaves the model ungrouped.
+
+**Sidebar behavior with grouping enabled:**
+
+- Each group has a **checkbox** to select/deselect all models in the group (supports indeterminate state for partial selection)
+- **Double-click** a group header to isolate that group — selects only its models and deselects everything else
+- **Click** a group header to collapse/expand its model list
+- A **collapse/expand all** button (▼/▶) appears in the sidebar actions bar to toggle all groups at once
+- Model names are **color-coded** to match their group's color
+- The **group header highlights** when one of its models is selected on the diagram
+- Models in the same group **cluster together** in the force-directed layout
+
 ## How it works
 
 The gem parses your `db/schema.rb` or `db/structure.sql` 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 a schema file is present (which is standard in Rails projects under version control).
 
 For Mongoid apps, the gem introspects model classes at runtime to read field definitions, associations, and validations — no schema file or database connection required.
 
+### Packwerk support
+
+If your app uses [Packwerk](https://github.com/Shopify/packwerk) for modular monolith architecture, rails-schema automatically discovers models inside packages. It reads your `packwerk.yml` to find `package_paths`, then looks for models in `app/models` and `app/public` under each package that has a `package.yml`. No configuration needed — it works out of the box.
+
+If the targeted loading doesn't find any models, the gem falls back to a full eager load of the entire application.
+
 ## Features
 
 - **No database required** — reads from `db/schema.rb`, `db/structure.sql`, or Mongoid model introspection
+- **Model grouping** — group models by namespace or custom logic; each group gets a distinct color for node headers and sidebar model names, collapsible sidebar sections with checkboxes, a collapse/expand-all toggle, group header highlighting on model selection, and force-layout clustering
 - **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
+- **Through edges toggle** — checkbox in the legend to show/hide `:through` association edges on the diagram; through associations always remain visible in the detail panel regardless of toggle state
+- **Manual Positioning** — toolbar checkbox that removes all simulation forces; nodes stay exactly where you drop them and drag-and-drop continues to work normally; uncheck to re-enable automatic force-directed layout
+- **Layout persistence** — node positions, visibility, zoom, and toggle states are automatically saved to `localStorage` and restored on page reload; scoped per schema so different projects don't collide
+- **Detail panel** — full column list and associations for the selected model; clicking a relation link auto-selects the related model (adding it to the diagram if hidden)
 - **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
+- **File menu** — toolbar dropdown grouping export/import actions: Export Mermaid (`.mmd`), Save Layout (`.json`), and Load Layout
+	- **Save/Load Layout** — export the current layout as a portable `.json` file to share with teammates or check into version control; import a saved layout to restore it on any machine or browser
+	- **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
 
+## Support
+
+If you find this gem useful, consider [buying me a coffee](https://www.paypal.com/donate/?hosted_button_id=5PZC9UEJWFJYJ).
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).