rails_visualizer 0.1.0

data/lib/rails_visualizer/schema/model_inspector.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module RailsVisualizer
+  module Schema
+    class ModelInspector
+      include RailsVisualizer::PathHelper
+
+      SERIALIZABLE_TYPES = [String, Symbol, Integer, Float, TrueClass, FalseClass, NilClass, Array, Hash].freeze
+      CALLBACK_TYPES     = %w[validate save create update destroy commit rollback find initialize touch].freeze
+
+      # file_cache and method_location_cache are shared across all ModelInspector
+      # instances in a single run to avoid redundant file reads and instance_method
+      # lookups for concern/parent methods included by many models.
+      def initialize(model, schema_cache = nil, file_cache = nil, method_location_cache = nil)
+        @model                 = model
+        @schema_cache          = schema_cache
+        @file_cache            = file_cache || {}
+        @method_location_cache = method_location_cache || {}
+        @index_map             = if schema_cache
+                                   schema_cache.index_map_for(model.table_name)
+                                 else
+                                   IndexInspector.new(model).call
+                                 end
+        @method_cache          = {}
+      end
+
+      def call
+        {
+          name: @model.name,
+          table_name: @model.table_name,
+          abstract: false,
+          file_path: source_path_for(@model),
+          columns: columns,
+          associations: associations,
+          validations: validations,
+          enums: enums,
+          scopes: scopes,
+          callbacks: callbacks
+        }
+      end
+
+      private
+
+      def columns
+        return [] unless table_exists?
+
+        raw = @schema_cache ? @schema_cache.columns_for(@model.table_name) : @model.columns
+        ignored = ignored_column_names
+        raw = raw.reject { |col| ignored.include?(col.name) } if ignored.any?
+        raw.map { |col| build_column(col) }
+      end
+
+      def build_column(col)
+        data = {
+          name: col.name,
+          type: col.type.to_s,
+          primary: col.name == model_primary_key,
+          null: col.null,
+          default: col.default
+        }
+        data[:index] = @index_map[col.name].first if @index_map[col.name]
+        enum_vals = cached_enums[col.name]
+        data[:enum] = enum_vals.keys if enum_vals
+        data
+      end
+
+      def associations
+        @model.reflect_on_all_associations.map { |r| build_association(r) }
+      end
+
+      def build_association(reflection)
+        assoc = {
+          macro: reflection.macro.to_s,
+          name: reflection.name.to_s,
+          class_name: resolve_class_name(reflection),
+          foreign_key: resolve_foreign_key(reflection)
+        }
+        apply_assoc_options(assoc, reflection.options)
+        assoc
+      end
+
+      def apply_assoc_options(assoc, opts)
+        assoc[:through]     = opts[:through].to_s if opts[:through]
+        assoc[:as]          = opts[:as].to_s if opts[:as]
+        assoc[:polymorphic] = true                  if opts[:polymorphic]
+        assoc[:dependent]   = opts[:dependent].to_s if opts[:dependent]
+      end
+
+      def validations
+        attribute_validators + method_validators
+      rescue StandardError
+        []
+      end
+
+      def attribute_validators
+        @model.validators.map do |v|
+          {
+            kind: v.kind.to_s,
+            attributes: v.attributes.map(&:to_s),
+            options: serializable_options(v.options),
+            validator_class: v.class.name
+          }
+        end
+      rescue StandardError
+        []
+      end
+
+      def method_validators
+        @model._validate_callbacks.filter_map do |cb|
+          next unless cb.filter.is_a?(Symbol)
+          next unless app_method_info(cb.filter)
+
+          { kind: cb.filter.to_s, attributes: [], options: {}, validator_class: nil }
+        end
+      rescue StandardError
+        []
+      end
+
+      # Two-level cache: per-model @method_cache avoids repeated instance_method
+      # lookups within one model, and @method_location_cache (shared across ALL
+      # models) caches the app_root check by [owner_id, method_name] — so a
+      # concern method included by 500 models does one source_location check globally.
+      def app_method_info(name)
+        @method_cache.fetch(name) do
+          unbound = @model.instance_method(name)
+          owner   = unbound.owner
+          loc_key = [owner.object_id, name]
+
+          app_defined = @method_location_cache.fetch(loc_key) do
+            location = unbound.source_location
+            @method_location_cache[loc_key] = location&.first&.start_with?(app_root)
+          end
+
+          @method_cache[name] = app_defined ? owner : nil
+        end
+      rescue StandardError
+        @method_cache[name] = nil
+      end
+
+      def serializable_options(options)
+        options.each_with_object({}) do |(key, value), hash|
+          next if %i[if unless on].include?(key)
+          next unless SERIALIZABLE_TYPES.any? { |t| value.is_a?(t) }
+
+          hash[key] = value.is_a?(Symbol) ? value.to_s : value
+        end
+      end
+
+      def cached_enums
+        @cached_enums ||= @model.defined_enums
+      rescue StandardError
+        @cached_enums ||= {}
+      end
+
+      def enums
+        cached_enums.transform_values(&:keys)
+      end
+
+      def scopes
+        file_path = source_path_for(@model)
+        return [] unless file_path
+
+        content = read_file(file_path)
+        return [] unless content
+
+        content.scan(/^\s*scope\s+:(\w+)/).flatten
+      rescue StandardError
+        []
+      end
+
+      def read_file(relative_path)
+        @file_cache.fetch(relative_path) do
+          absolute = Rails.root.join(relative_path)
+          @file_cache[relative_path] = absolute.exist? ? File.read(absolute) : nil
+        end
+      rescue StandardError
+        @file_cache[relative_path] = nil
+      end
+
+      def callbacks
+        CALLBACK_TYPES.flat_map do |type|
+          chain = @model.send(:"_#{type}_callbacks")
+          chain.filter_map do |cb|
+            next unless cb.filter.is_a?(Symbol)
+
+            owner = app_method_info(cb.filter)
+            next unless owner
+
+            {
+              kind: "#{cb.kind}_#{type}",
+              name: cb.filter.to_s,
+              defined_in: owner == @model ? nil : owner.name,
+              conditional: cb.instance_variable_get(:@if).present? ||
+                cb.instance_variable_get(:@unless).present?
+            }
+          end
+        rescue StandardError
+          []
+        end
+      rescue StandardError
+        []
+      end
+
+      def model_primary_key
+        @model_primary_key ||= if @schema_cache
+                                 @schema_cache.primary_key_for(@model.table_name)
+                               else
+                                 @model.primary_key
+                               end
+      rescue StandardError
+        'id'
+      end
+
+      def table_exists?
+        if @schema_cache
+          @schema_cache.table_exists?(@model.table_name)
+        else
+          @model.connection.table_exists?(@model.table_name)
+        end
+      rescue StandardError
+        false
+      end
+
+      def ignored_column_names
+        Set.new(@model.ignored_columns.map(&:to_s))
+      rescue StandardError
+        Set.new
+      end
+
+      def resolve_class_name(reflection)
+        return nil if reflection.options[:polymorphic]
+
+        reflection.class_name
+      rescue NameError
+        nil
+      end
+
+      def resolve_foreign_key(reflection)
+        reflection.foreign_key.to_s
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/rails_visualizer/serializer.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'time'
+
+module RailsVisualizer
+  LOGO_CANDIDATES = [
+    ['public/favicon.svg',          'image/svg+xml'],
+    ['public/favicon.png',          'image/png'],
+    ['public/favicon.ico',          'image/x-icon'],
+    ['public/apple-touch-icon.png', 'image/png']
+  ].freeze
+
+  class Serializer
+    def initialize(app_data, configuration = RailsVisualizer.configuration)
+      @app_data      = app_data
+      @configuration = configuration
+      @key_cache     = {}
+    end
+
+    def call
+      JSON.generate(deep_camelize(payload))
+    end
+
+    private
+
+    def payload
+      {
+        generated_at: Time.now.utc.iso8601,
+        rails_version: rails_version,
+        ruby_version: RUBY_VERSION,
+        db_version: db_version,
+        app_name: @app_data.fetch(:app_name, nil),
+        app_title: app_title,
+        app_logo: app_logo_data_uri,
+        app_root: app_root,
+        models: @app_data.fetch(:models, []),
+        routes: @app_data.fetch(:routes, []),
+        jobs: @app_data.fetch(:jobs, {}),
+        controllers: @app_data.fetch(:controllers, []),
+        migrations: @app_data.fetch(:migrations, {}),
+        mailers: @app_data.fetch(:mailers, []),
+        gems: @app_data.fetch(:gems, [])
+      }
+    end
+
+    def rails_version
+      Rails::VERSION::STRING if defined?(Rails::VERSION)
+    end
+
+    def app_title
+      root = app_root
+      layout = File.join(root, 'app/views/layouts/application.html.erb')
+      return nil unless File.file?(layout)
+
+      content = File.read(layout)
+      # Only extract plain-text titles — skip any that contain ERB expressions
+      match = content.match(%r{<title>([^<%>]+)</title>})
+      title = match&.[](1)&.strip
+      title.presence
+    rescue StandardError
+      nil
+    end
+
+    def db_version
+      return nil unless defined?(ActiveRecord::Base)
+
+      conn = ActiveRecord::Base.connection
+      version = case conn.adapter_name.downcase
+                when /postgresql|postgis/
+                  conn.select_value("SELECT current_setting('server_version')")
+                when /mysql/
+                  conn.select_value('SELECT VERSION()')
+                when /sqlite/
+                  conn.select_value('SELECT sqlite_version()')
+                end
+      version&.to_s&.strip
+    rescue StandardError
+      nil
+    end
+
+    def app_root
+      defined?(Rails) && Rails.respond_to?(:root) ? Rails.root.to_s : Dir.pwd
+    end
+
+    def app_logo_data_uri
+      root = app_root
+      RailsVisualizer::LOGO_CANDIDATES.each do |relative_path, mime|
+        full_path = File.join(root, relative_path)
+        next unless File.file?(full_path)
+
+        encoded = Base64.strict_encode64(File.binread(full_path))
+        return "data:#{mime};base64,#{encoded}"
+      rescue StandardError
+        next
+      end
+      nil
+    end
+
+    # Recursively converts all Hash keys from snake_case to camelCase.
+    # Key conversions are memoised — the same ~30 key names appear millions
+    # of times across thousands of models/controllers/routes.
+    def deep_camelize(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), h|
+          h[camelize(k.to_s)] = deep_camelize(v)
+        end
+      when Array
+        obj.map { |v| deep_camelize(v) }
+      else
+        obj
+      end
+    end
+
+    def camelize(str)
+      @key_cache[str] ||= begin
+        parts = str.split('_')
+        parts.first + parts[1..].map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/rails_visualizer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsVisualizer
+  VERSION = '0.1.0'
+end

data/lib/rails_visualizer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'rails_visualizer/version'
+require_relative 'rails_visualizer/configuration'
+require_relative 'rails_visualizer/path_helper'
+require_relative 'rails_visualizer/schema/cache'
+require_relative 'rails_visualizer/schema/index_inspector'
+require_relative 'rails_visualizer/schema/model_inspector'
+require_relative 'rails_visualizer/introspector'
+require_relative 'rails_visualizer/routes_inspector'
+require_relative 'rails_visualizer/jobs_inspector'
+require_relative 'rails_visualizer/controllers_inspector'
+require_relative 'rails_visualizer/migrations_inspector'
+require_relative 'rails_visualizer/mailers_inspector'
+require_relative 'rails_visualizer/gems_inspector'
+require_relative 'rails_visualizer/serializer'
+require_relative 'rails_visualizer/renderer'
+
+module RailsVisualizer
+end
+
+require_relative 'rails_visualizer/railtie' if defined?(Rails::Railtie)

data/lib/tasks/rails_visualizer.rake

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+desc 'Introspect the Rails app and open the interactive RailsVisualizer dashboard in your browser'
+task rails_visualizer: :environment do # rubocop:disable Metrics/BlockLength
+  require 'rails_visualizer'
+
+  puts 'RailsVisualizer: Introspecting app...'
+  app_data = RailsVisualizer::Introspector.new.call
+
+  # Build a set of "controller#action" pairs from non-internal routes only
+  # (mirrors the UI's `routes.filter(r => !r.internal)` logic).
+  routed_pairs = app_data[:routes].each_with_object(Set.new) do |r, set|
+    set.add("#{r[:controller]}##{r[:action]}") unless r[:internal]
+  end
+
+  # Count public routable actions with no matching route, excluding actions that
+  # are registered as callbacks — they run as filters, not dispatched actions,
+  # so having no route for them is expected (mirrors deadCode.ts logic).
+  no_route_count = app_data[:controllers].sum do |ctrl|
+    callback_names = [
+      *(ctrl[:before_actions] || []),
+      *(ctrl[:after_actions] || []),
+      *(ctrl[:around_actions] || [])
+    ].to_set { |cb| cb[:name] }
+
+    (ctrl[:actions] || []).count do |action|
+      callback_names.exclude?(action[:name]) &&
+        routed_pairs.exclude?("#{ctrl[:controller_path]}##{action[:name]}")
+    end
+  end
+
+  pl = ->(n, singular, plural = "#{singular}s") { "#{n} #{n == 1 ? singular : plural}" }
+
+  pending_count  = app_data.dig(:migrations, :pending_count) || 0
+  migration_icon = pending_count.positive? ? '⚠' : '✓'
+
+  puts "  ✓ #{pl.call(app_data[:models].size, 'model')}"
+  puts "  ✓ #{pl.call(app_data[:routes].size, 'route')}"
+  puts "  ✓ #{pl.call(app_data.dig(:jobs, :active_jobs)&.size || 0, 'job')}"
+  controller_icon  = no_route_count.positive? ? '⚠' : '✓'
+  no_route_suffix  = no_route_count.positive? ? " (#{pl.call(no_route_count, 'action')} without route)" : ''
+  puts "  #{controller_icon} #{pl.call(app_data[:controllers].size, 'controller')}#{no_route_suffix}"
+  pending_suffix = pending_count.positive? ? " (#{pl.call(pending_count, 'pending migration')})" : ''
+  puts "  #{migration_icon} #{pl.call(app_data.dig(:migrations, :total_count) || 0, 'migration')}#{pending_suffix}"
+  puts "  ✓ #{pl.call(app_data[:mailers].size, 'mailer')}"
+
+  puts 'RailsVisualizer: Rendering...'
+  json = RailsVisualizer::Serializer.new(app_data).call
+
+  output_dir = Rails.root.join(RailsVisualizer.configuration.output_path)
+  FileUtils.mkdir_p(output_dir)
+
+  output_file = output_dir.join(RailsVisualizer.configuration.filename)
+  File.write(output_file, RailsVisualizer::Renderer.new(json).call)
+
+  puts "RailsVisualizer: Done → #{output_file}"
+
+  system('open', output_file.to_s) if RailsVisualizer.configuration.open_browser
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: rails_visualizer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Raj Kamal Lashkari
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-18 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  rails_visualizer introspects a Rails application and generates a self-contained
+  interactive HTML dashboard with no server, no config, and no Node.js required for
+  end users. Run one Rake task to explore models, associations, routes, controllers,
+  jobs, mailers, migrations, and gems through a polished 8-tab UI with search,
+  filters, an ER diagram canvas, and built-in health checks.
+email:
+- rajkamallashkari@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/rails_visualizer.rb
+- lib/rails_visualizer/assets/dist/index.html
+- lib/rails_visualizer/configuration.rb
+- lib/rails_visualizer/controllers_inspector.rb
+- lib/rails_visualizer/gems_inspector.rb
+- lib/rails_visualizer/introspector.rb
+- lib/rails_visualizer/jobs_inspector.rb
+- lib/rails_visualizer/mailers_inspector.rb
+- lib/rails_visualizer/migrations_inspector.rb
+- lib/rails_visualizer/path_helper.rb
+- lib/rails_visualizer/railtie.rb
+- lib/rails_visualizer/renderer.rb
+- lib/rails_visualizer/routes_inspector.rb
+- lib/rails_visualizer/schema/cache.rb
+- lib/rails_visualizer/schema/index_inspector.rb
+- lib/rails_visualizer/schema/model_inspector.rb
+- lib/rails_visualizer/serializer.rb
+- lib/rails_visualizer/version.rb
+- lib/tasks/rails_visualizer.rake
+homepage: https://github.com/rajkamallashkari/rails_visualizer
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://github.com/rajkamallashkari/rails_visualizer/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/rajkamallashkari/rails_visualizer
+  bug_tracker_uri: https://github.com/rajkamallashkari/rails_visualizer/issues
+  documentation_uri: https://github.com/rajkamallashkari/rails_visualizer#readme
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Interactive Rails app visualizer — models, routes, controllers, and more
+  in one dashboard.
+test_files: []