rails-schema 0.1.0

data/lib/rails/schema/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    class Configuration
+      attr_accessor :output_path, :exclude_models, :title, :theme, :expand_columns
+
+      def initialize
+        @output_path = "docs/schema.html"
+        @exclude_models = []
+        @title = "Database Schema"
+        @theme = :auto
+        @expand_columns = false
+      end
+    end
+  end
+end

data/lib/rails/schema/extractor/association_reader.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    module Extractor
+      class AssociationReader
+        def read(model)
+          model.reflect_on_all_associations.filter_map do |ref|
+            next if skip_association?(ref)
+
+            build_association_data(model, ref)
+          end
+        end
+
+        private
+
+        def skip_association?(ref)
+          # Skip polymorphic belongs_to — no fixed target model
+          ref.macro == :belongs_to && ref.options[:polymorphic]
+        end
+
+        def build_association_data(model, ref)
+          {
+            from: model.name,
+            to: target_model_name(ref),
+            association_type: ref.macro.to_s,
+            label: ref.name.to_s,
+            foreign_key: ref.foreign_key.to_s,
+            through: ref.options[:through]&.to_s,
+            polymorphic: ref.options[:as] ? true : false
+          }
+        rescue StandardError
+          nil
+        end
+
+        def target_model_name(ref)
+          ref.klass.name
+        rescue StandardError
+          ref.class_name
+        end
+      end
+    end
+  end
+end

data/lib/rails/schema/extractor/column_reader.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    module Extractor
+      class ColumnReader
+        def initialize(schema_data: nil)
+          @schema_data = schema_data
+        end
+
+        def read(model)
+          if @schema_data&.key?(model.table_name)
+            @schema_data[model.table_name]
+          else
+            read_from_model(model)
+          end
+        end
+
+        private
+
+        def read_from_model(model)
+          model.columns.map do |col|
+            {
+              name: col.name,
+              type: col.type.to_s,
+              nullable: col.null,
+              primary: col.name == model.primary_key,
+              default: col.default
+            }
+          end
+        rescue StandardError
+          []
+        end
+      end
+    end
+  end
+end

data/lib/rails/schema/extractor/model_scanner.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    module Extractor
+      class ModelScanner
+        def initialize(configuration: ::Rails::Schema.configuration, schema_data: nil)
+          @configuration = configuration
+          @schema_data = schema_data
+        end
+
+        def scan
+          eager_load_models!
+
+          all_descendants = ActiveRecord::Base.descendants
+          non_abstract = all_descendants.reject(&:abstract_class?)
+          named = non_abstract.reject { |m| m.name.nil? }
+          with_tables = named.select { |m| table_known?(m) }
+          included = with_tables.reject { |m| excluded?(m) }
+          log_empty_scan(all_descendants, non_abstract, named, with_tables) if included.empty?
+
+          included.sort_by(&:name)
+        end
+
+        private
+
+        def eager_load_models!
+          return unless defined?(::Rails.application) && ::Rails.application
+
+          if defined?(::Rails.autoloaders) && ::Rails.autoloaders.respond_to?(:main)
+            eager_load_via_zeitwerk!
+          else
+            eager_load_via_application!
+          end
+        end
+
+        def eager_load_via_zeitwerk!
+          loader = ::Rails.autoloaders.main
+          models_path = ::Rails.root&.join("app", "models")&.to_s
+
+          if models_path && File.directory?(models_path) && loader.respond_to?(:eager_load_dir)
+            loader.eager_load_dir(models_path)
+          else
+            loader.eager_load
+          end
+        rescue StandardError => e
+          warn "[rails-schema] Zeitwerk eager_load failed (#{e.class}: #{e.message}), " \
+               "trying Rails.application.eager_load!"
+          eager_load_via_application!
+        end
+
+        def eager_load_via_application!
+          ::Rails.application.eager_load!
+        rescue StandardError => e
+          warn "[rails-schema] eager_load! failed (#{e.class}: #{e.message}), " \
+               "falling back to per-file model loading"
+          eager_load_model_files!
+        end
+
+        def eager_load_model_files!
+          return unless defined?(::Rails.root) && ::Rails.root
+
+          models_path = ::Rails.root.join("app", "models")
+          return unless models_path.exist?
+
+          Dir.glob(models_path.join("**/*.rb")).each do |file|
+            require file
+          rescue StandardError => e
+            warn "[rails-schema] Could not load #{file}: #{e.class}: #{e.message}"
+          end
+        end
+
+        def table_known?(model)
+          if @schema_data
+            @schema_data.key?(model.table_name)
+          else
+            safe_table_exists?(model)
+          end
+        end
+
+        def safe_table_exists?(model)
+          model.table_exists?
+        rescue StandardError => e
+          warn "[rails-schema] Could not check table for #{model.name}: #{e.class}: #{e.message}"
+          false
+        end
+
+        def excluded?(model)
+          @configuration.exclude_models.any? do |pattern|
+            if pattern.end_with?("*")
+              model.name.start_with?(pattern.delete_suffix("*"))
+            else
+              model.name == pattern
+            end
+          end
+        end
+
+        def log_empty_scan(all_descendants, non_abstract, named, with_tables)
+          return if all_descendants.empty?
+
+          warn "[rails-schema] No models found! Filtering: " \
+               "#{all_descendants.size} descendants → #{non_abstract.size} concrete → " \
+               "#{named.size} named → #{with_tables.size} with tables"
+        end
+      end
+    end
+  end
+end

data/lib/rails/schema/extractor/schema_file_parser.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    module Extractor
+      class SchemaFileParser
+        def initialize(schema_path = nil)
+          @schema_path = schema_path
+        end
+
+        def parse
+          path = resolve_path
+          return {} unless path && File.exist?(path)
+
+          parse_content(File.read(path))
+        end
+
+        def parse_content(content)
+          @tables = {}
+          @current_table = nil
+          @pk_type = nil
+          @has_pk = true
+
+          content.each_line { |line| process_line(line.strip) }
+
+          @tables
+        end
+
+        private
+
+        def resolve_path
+          return @schema_path if @schema_path
+
+          if defined?(::Rails.root) && ::Rails.root
+            ::Rails.root.join("db", "schema.rb").to_s
+          else
+            File.join(Dir.pwd, "db", "schema.rb")
+          end
+        end
+
+        def extract_pk_type(line)
+          if (match = line.match(/id:\s*:(\w+)/))
+            match[1]
+          else
+            "integer"
+          end
+        end
+
+        def parse_column(line)
+          return nil if line.start_with?("t.index")
+
+          match = line.match(/\At\.(\w+)\s+"(\w+)"(.*)/)
+          return nil unless match
+
+          type = match[1]
+          name = match[2]
+          options = match[3]
+
+          {
+            name: name,
+            type: type,
+            nullable: !options.match?(/null:\s*false/),
+            default: extract_default(options),
+            primary: false
+          }
+        end
+
+        def process_line(stripped)
+          if (match = stripped.match(/\Acreate_table\s+"(\w+)"/))
+            start_table(match, stripped)
+          elsif @current_table && stripped == "end"
+            close_table
+          elsif @current_table && (col = parse_column(stripped))
+            @tables[@current_table] << col
+          end
+        end
+
+        def start_table(match, stripped)
+          @current_table = match[1]
+          @tables[@current_table] = []
+          @has_pk = !stripped.match?(/id:\s*false/)
+          @pk_type = extract_pk_type(stripped)
+        end
+
+        def close_table
+          if @has_pk
+            pk_column = { name: "id", type: @pk_type, nullable: false, default: nil, primary: true }
+            @tables[@current_table].unshift(pk_column)
+          end
+          @current_table = nil
+          @pk_type = nil
+          @has_pk = true
+        end
+
+        def extract_default(options)
+          if (match = options.match(/default:\s*(?:"([^"]*)"|(\d+(?:\.\d+)?))/))
+            match[1] || match[2]
+          elsif options.match?(/default:\s*true/)
+            "true"
+          elsif options.match?(/default:\s*false/)
+            "false"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/schema/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    class Railtie < ::Rails::Railtie
+      rake_tasks do
+        namespace :rails_schema do
+          desc "Generate an interactive HTML schema diagram"
+          task generate: :environment do
+            path = ::Rails::Schema.generate
+            puts "Schema diagram generated: #{path}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/schema/renderer/html_generator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+require "fileutils"
+
+module Rails
+  module Schema
+    module Renderer
+      class HtmlGenerator
+        ASSETS_DIR = File.expand_path("../../schema/assets", __dir__)
+
+        def initialize(graph_data:, configuration: ::Rails::Schema.configuration)
+          @graph_data = graph_data
+          @configuration = configuration
+        end
+
+        def render
+          template = File.read(File.join(ASSETS_DIR, "template.html.erb"))
+          erb = ERB.new(template)
+          erb.result(binding)
+        end
+
+        def render_to_file(path = nil)
+          path ||= @configuration.output_path
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, render)
+          path
+        end
+
+        private
+
+        def title
+          @configuration.title
+        end
+
+        def theme_class
+          case @configuration.theme
+          when :light then "light"
+          when :dark then "dark"
+          else ""
+          end
+        end
+
+        def css_content
+          File.read(File.join(ASSETS_DIR, "style.css"))
+        end
+
+        def d3_js_content
+          File.read(File.join(ASSETS_DIR, "vendor", "d3.min.js"))
+        end
+
+        def app_js_content
+          File.read(File.join(ASSETS_DIR, "app.js"))
+        end
+
+        def graph_json
+          JSON.generate(@graph_data).gsub("</", '<\/')
+        end
+
+        def config_json
+          config = {
+            expand_columns: @configuration.expand_columns,
+            theme: @configuration.theme.to_s
+          }
+          JSON.generate(config).gsub("</", '<\/')
+        end
+      end
+    end
+  end
+end

data/lib/rails/schema/transformer/edge.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    module Transformer
+      class Edge
+        attr_reader :from, :to, :association_type, :label, :foreign_key, :through, :polymorphic
+
+        def initialize(from:, to:, association_type:, label:, foreign_key: nil, through: nil, polymorphic: false)
+          @from = from
+          @to = to
+          @association_type = association_type
+          @label = label
+          @foreign_key = foreign_key
+          @through = through
+          @polymorphic = polymorphic
+        end
+
+        def to_h
+          {
+            from: @from,
+            to: @to,
+            association_type: @association_type,
+            label: @label,
+            foreign_key: @foreign_key,
+            through: @through,
+            polymorphic: @polymorphic
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rails/schema/transformer/graph_builder.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    module Transformer
+      class GraphBuilder
+        def initialize(column_reader: Extractor::ColumnReader.new, association_reader: Extractor::AssociationReader.new)
+          @column_reader = column_reader
+          @association_reader = association_reader
+        end
+
+        def build(models)
+          node_names = models.to_set(&:name)
+          nodes = models.map { |m| build_node(m) }
+          edges = models.flat_map { |m| build_edges(m, node_names) }
+
+          {
+            nodes: nodes.map(&:to_h),
+            edges: edges.map(&:to_h),
+            metadata: build_metadata(models)
+          }
+        end
+
+        private
+
+        def build_node(model)
+          Node.new(
+            id: model.name,
+            table_name: model.table_name,
+            columns: @column_reader.read(model)
+          )
+        end
+
+        def build_edges(model, node_names)
+          @association_reader.read(model).filter_map do |assoc|
+            next unless node_names.include?(assoc[:to])
+
+            Edge.new(
+              from: assoc[:from],
+              to: assoc[:to],
+              association_type: assoc[:association_type],
+              label: assoc[:label],
+              foreign_key: assoc[:foreign_key],
+              through: assoc[:through],
+              polymorphic: assoc[:polymorphic]
+            )
+          end
+        end
+
+        def build_metadata(models)
+          {
+            generated_at: Time.now.utc.iso8601,
+            model_count: models.size,
+            rails_version: defined?(::Rails.version) ? ::Rails.version : nil
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rails/schema/transformer/node.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    module Transformer
+      class Node
+        attr_reader :id, :table_name, :columns
+
+        def initialize(id:, table_name:, columns: [])
+          @id = id
+          @table_name = table_name
+          @columns = columns
+        end
+
+        def to_h
+          {
+            id: @id,
+            table_name: @table_name,
+            columns: @columns
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rails/schema/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rails
+  module Schema
+    VERSION = "0.1.0"
+  end
+end

data/lib/rails/schema.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "schema/version"
+require_relative "schema/configuration"
+require_relative "schema/transformer/node"
+require_relative "schema/transformer/edge"
+require_relative "schema/extractor/schema_file_parser"
+require_relative "schema/extractor/model_scanner"
+require_relative "schema/extractor/column_reader"
+require_relative "schema/extractor/association_reader"
+require_relative "schema/transformer/graph_builder"
+require_relative "schema/renderer/html_generator"
+
+module Rails
+  module Schema
+    class Error < StandardError; end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      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
+    end
+  end
+end
+
+require_relative "schema/railtie" if defined?(Rails::Railtie)

data/sig/rails/schema.rbs

@@ -0,0 +1,6 @@
+module Rails
+  module Schema
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: rails-schema
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrei Kislichenko
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Introspects a Rails app's models, associations, and columns, then generates
+  a single self-contained HTML file with an interactive entity-relationship diagram.
+email:
+- android.2net@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- PROJECT.md
+- README.md
+- Rakefile
+- docs/index.html
+- docs/screenshot.png
+- lib/rails/schema.rb
+- lib/rails/schema/assets/app.js
+- lib/rails/schema/assets/style.css
+- lib/rails/schema/assets/template.html.erb
+- lib/rails/schema/assets/vendor/d3.min.js
+- lib/rails/schema/configuration.rb
+- lib/rails/schema/extractor/association_reader.rb
+- lib/rails/schema/extractor/column_reader.rb
+- lib/rails/schema/extractor/model_scanner.rb
+- lib/rails/schema/extractor/schema_file_parser.rb
+- lib/rails/schema/railtie.rb
+- lib/rails/schema/renderer/html_generator.rb
+- lib/rails/schema/transformer/edge.rb
+- lib/rails/schema/transformer/graph_builder.rb
+- lib/rails/schema/transformer/node.rb
+- lib/rails/schema/version.rb
+- sig/rails/schema.rbs
+homepage: https://github.com/nicholaides/rails-schema
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nicholaides/rails-schema
+  source_code_uri: https://github.com/nicholaides/rails-schema
+  changelog_uri: https://github.com/nicholaides/rails-schema/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Interactive HTML visualization of your Rails database schema
+test_files: []