rails-schema 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1275bccb3e5144d351dcf4445209299ee269dfae8e75b4176e8a91bb85b5ccc2
-  data.tar.gz: 2ba3e983963eaef3a933ba9d99eebd7b3221acdaca492212ddda04d5a0354122
+  metadata.gz: 97d15de972c2e7c9c3d9e395d0b610b95806e7f6ef5729eed214f5cb7723bb61
+  data.tar.gz: 7edc0d7d8cd246ad80cc2dd54936a0c9802b662476400f095d076bed651d6472
 SHA512:
-  metadata.gz: bade47644111e000883867b876dad54b59aa07df5800719185c48cd9d2307fa030d3d1df38c00a738be94bd2c37426bbe5d181729dc9b0995872103449332e1b
-  data.tar.gz: ee1eaa1f3050778be38ae59a69269b93658e149466cc135ec7eb58cbc34cbf2ec814ea99d665777887c64ff341440351a63ac9707a791add32e9fb30d152ab52
+  metadata.gz: 3ba7bf7dd2ac15538fa4a9f14b2772c4065fd6dc51a5325e1863e4d4e83838cdaa14497f5b4a4f6d7ffcdc014fe03ba9e1f3464e722ef57f73a56d14314997f0
+  data.tar.gz: f41572f08a43be003061f2e47914ed36ed27b2718b10d0d3e238c9ca436ea3230ca7e61e5213acdbf50cab6f19b96506d5d1c8d0de33bc2831e2ab84181adac0

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+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.2] - 2026-02-22
+
+### Added
+
+- `StructureSqlParser` for extracting schema from `db/structure.sql` files
+- `schema_format` configuration option (`:ruby`, `:sql`, `:auto`)
+- `warn` messages to all silent rescue blocks in `AssociationReader` and `ColumnReader`
+
+## [0.1.1] - 2026-02-17
+
+### Added
+
+- ERD-style connections with crow's foot notation, directional indicators, and column-level attachment points
+
+### Changed
+
+- Refactored edge routing with cubic Bezier curves and improved self-referential association handling
+
+## [0.1.0] - 2026-02-15
+
+### Added
+
+- Initial release
+- Interactive HTML visualization of Rails database schema (force-directed ERD)
+- Model introspection: associations, columns, and schema file parsing
+- Self-contained single HTML file output (no external dependencies)
+- Searchable sidebar, click-to-focus, dark/light theme, keyboard shortcuts
+- Rake task (`rails_schema:generate`) and programmatic API
+- Configuration DSL: output path, title, theme, expand columns, exclude models

data/PROJECT.md

@@ -8,7 +8,7 @@
 
 **Name:** `rails-schema`
 **Module:** `Rails::Schema`
-**Version:** `0.1.0`
+**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.
 
@@ -43,7 +43,7 @@ Rails::Schema.generate(output: "docs/schema.html")
 
 | Layer | Responsibility | Key Classes |
 |---|---|---|
-| **Extractor** | Introspects Rails environment; collects models, columns, associations | `Rails::Schema::Extractor::ModelScanner`, `ColumnReader`, `AssociationReader`, `SchemaFileParser` |
+| **Extractor** | Introspects Rails environment; collects models, columns, associations | `Rails::Schema::Extractor::ModelScanner`, `ColumnReader`, `AssociationReader`, `SchemaFileParser`, `StructureSqlParser` |
 | **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` |
@@ -52,13 +52,23 @@ Rails::Schema.generate(output: "docs/schema.html")
 
 ```ruby
 def generate(output: nil)
-  schema_data = Extractor::SchemaFileParser.new.parse
+  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
 ```
 
 ---
@@ -68,8 +78,9 @@ end
 ### 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.
+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
 
@@ -92,7 +103,19 @@ When `schema_data` is available, table existence is checked against parsed schem
 - Handles custom primary key types (`id: :uuid`, `id: :bigint`) and `id: false`
 - Skips index definitions
 
-### 3.4 Intermediate Data Format (JSON Graph)
+### 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
 {
@@ -195,6 +218,7 @@ Rails::Schema.configure do |config|
   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, or :sql
 end
 ```
 
@@ -207,14 +231,15 @@ 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)
+│       ├── 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
+│       │   ├── schema_file_parser.rb      # Parses db/schema.rb
+│       │   └── structure_sql_parser.rb   # Parses db/structure.sql
 │       ├── transformer/
 │       │   ├── graph_builder.rb           # Builds node/edge graph
 │       │   ├── node.rb                    # Value object
@@ -238,7 +263,8 @@ rails-schema/
 │       │   ├── model_scanner_spec.rb
 │       │   ├── column_reader_spec.rb
 │       │   ├── association_reader_spec.rb
-│       │   └── schema_file_parser_spec.rb
+│       │   ├── schema_file_parser_spec.rb
+│       │   └── structure_sql_parser_spec.rb
 │       ├── transformer/
 │       │   └── graph_builder_spec.rb
 │       └── renderer/
@@ -263,9 +289,9 @@ rails-schema/
 
 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?
+### Why parse schema.rb / structure.sql?
 
-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.
+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?
 
@@ -292,12 +318,12 @@ spec.add_dependency "railties", ">= 6.0"
 
 | Layer | Approach |
 |---|---|
-| Extractor | Unit tests with in-memory SQLite models (User, Post, Comment, Tag) |
+| 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 |
 
-**66 tests, all passing.** Run with `bundle exec rspec`.
+**108 tests, all passing.** Run with `bundle exec rspec`.
 
 ---
 
@@ -319,4 +345,4 @@ spec.add_dependency "railties", ">= 6.0"
 
 ---
 
-*Document reflects the current implementation (v0.1.0). Future enhancements are aspirational and subject to refinement.*
+*Document reflects the current implementation (v0.1.2). Future enhancements are aspirational and subject to refinement.*

data/README.md

@@ -48,6 +48,7 @@ Rails::Schema.configure do |config|
   config.title = "My App Schema"
   config.theme = :auto          # :auto, :light, or :dark
   config.expand_columns = false # start with columns collapsed
+  config.schema_format = :auto  # :auto, :ruby, or :sql
   config.exclude_models = [
     "ActiveStorage::Blob",
     "ActiveStorage::Attachment",
@@ -56,13 +57,32 @@ Rails::Schema.configure do |config|
 end
 ```
 
+| Option | Default | Description |
+|--------|---------|-------------|
+| `output_path` | `"docs/schema.html"` | Path for the generated HTML file |
+| `title` | `"Database Schema"` | Title shown in the HTML page |
+| `theme` | `:auto` | Color theme — `:auto`, `:light`, or `:dark` |
+| `expand_columns` | `false` | Whether model nodes start with columns expanded |
+| `schema_format` | `:auto` | Schema source — `:auto`, `:ruby`, or `:sql` (see below) |
+| `exclude_models` | `[]` | Models to hide; supports exact names and wildcard prefixes (`"ActionMailbox::*"`) |
+
+### Schema format
+
+Rails projects can use either `db/schema.rb` (Ruby DSL) or `db/structure.sql` (raw SQL dump) to represent the database schema. Set `config.active_record.schema_format = :sql` in your Rails app to use `structure.sql`.
+
+| Value | Behavior |
+|-------|----------|
+| `:auto` | Tries `db/schema.rb` first, falls back to `db/structure.sql` |
+| `:ruby` | Only reads `db/schema.rb` |
+| `:sql` | Only reads `db/structure.sql` |
+
 ## 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).
+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).
 
 ## Features
 
-- **No database required** — reads directly from `db/schema.rb`
+- **No database required** — reads from `db/schema.rb` or `db/structure.sql`
 - **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