rails_lens 0.2.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2df49b10f106235177d40b7029a8519ab45d7ab88395eb26fd56855e69a1ada
-  data.tar.gz: 483fc63985bf291ff4a069793aaa9ff8a4e82d1c83c405dedce717fddc5d9dc6
+  metadata.gz: 7eaa2e258c8608dfd893bb5220840fc9febce43478aca9573ae0dbb885b33bf5
+  data.tar.gz: ed99614fc744e7f32e6c439a8f61e99b5d94787a684c694fbca7ed1eb546e6c6
 SHA512:
-  metadata.gz: 20e9000c791458cb09cc530ba00e88b3033290c4b8124e6f10afc0d5ba0cf9af9bee932517753987da5f1955d4a13dd92d6c8315cf651962f45449b88bd02183
-  data.tar.gz: 70bf1e3d3321abe358bf68d2e99a0d2a018e6f8c8e70cbe86d42e2c7358fdf0870c8d5f806628f63a2913fc431993576480fe03c10f1a8157148c5358ecf67da
+  metadata.gz: 0fc9a2a6d597e0d5a5e9b5e1c5eddf79bdca77448e780686fd28eabc26c5085829fe543595bdde05d31949a0e5ca42475bd379d89b9d552c128c06070d7a555c
+  data.tar.gz: 3982294a0d8a11b0ba516a7f90dc5595b488a3dcae79ef874c8d7d0cb0369f4a6438304adf1dd476d3aa8542bd445ec44022b549dcdeb48bf63084b5bebdd22d

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.2.3](https://github.com/seuros/rails_lens/compare/rails_lens/v0.2.2...rails_lens/v0.2.3) (2025-07-31)
+
+
+### Features
+
+* add database view annotation support ([#7](https://github.com/seuros/rails_lens/issues/7)) ([a42fdcd](https://github.com/seuros/rails_lens/commit/a42fdcdfe4da9e2a086488e0c5e0c72d2f3c5d3d))
+
+
+### Bug Fixes
+
+* centralize connection management to prevent "too many clients" errors ([#9](https://github.com/seuros/rails_lens/issues/9)) ([c5d85c7](https://github.com/seuros/rails_lens/commit/c5d85c7239d1eff49494a05582cb00a8e7402618))
+
+## [0.2.2](https://github.com/seuros/rails_lens/compare/rails_lens/v0.2.1...rails_lens/v0.2.2) (2025-07-31)
+
+
+### Bug Fixes
+
+* remove from format from the erd visualize ([#5](https://github.com/seuros/rails_lens/issues/5)) ([c2efdc7](https://github.com/seuros/rails_lens/commit/c2efdc7011425fcd8b46dce54d811ce166b0c660))
+
+## [0.2.1](https://github.com/seuros/rails_lens/compare/rails_lens/v0.2.0...rails_lens/v0.2.1) (2025-07-30)
+
+
+### Bug Fixes
+
+* resolve GitHub issue [#2](https://github.com/seuros/rails_lens/issues/2) CLI and provider errors ([6d92c67](https://github.com/seuros/rails_lens/commit/6d92c679f1da9186ec4f357c243b41bc57eecd94))
+* resolve GitHub issue [#2](https://github.com/seuros/rails_lens/issues/2) CLI and provider errors ([a583373](https://github.com/seuros/rails_lens/commit/a583373b40ee7fdde32b3e97295448b1ecaa7ca5))
+
 ## [0.2.0](https://github.com/seuros/rails_lens/compare/rails_lens-v0.1.0...rails_lens/v0.2.0) (2025-07-30)
 
 

data/README.md

@@ -1,5 +1,10 @@
 # Rails Lens 🔍
 
+![Gem Version](https://img.shields.io/gem/v/rails_lens)
+![GitHub stars](https://img.shields.io/github/stars/seuros/rails_lens)
+![Downloads](https://img.shields.io/gem/dt/rails_lens)
+![License](https://img.shields.io/github/license/seuros/rails_lens)
+
 > **Precision optics for the Rails universe** - Where every model has perfect clarity through spacetime
 
 Rails Lens provides intelligent model annotations and ERD generation for Rails applications with database-specific adapters, multi-database support, and advanced code analysis.
@@ -26,6 +31,71 @@ Rails Lens provides intelligent model annotations and ERD generation for Rails a
 **✨ Advanced Features:**
 - STI hierarchy mapping • Delegated types • Polymorphic associations • Enum analysis • LRDL-optimized output
 
+## Showcase: Real-World Example
+
+Rescued from AWS limbo, Rails Lens delivers cosmic schema clarity. See this `Announcement` model:
+
+```ruby
+# frozen_string_literal: true
+
+# <rails-lens:schema:begin>
+# table = "announcements"
+# database_dialect = "PostgreSQL"
+#
+# columns = [
+#   { name = "id", type = "integer", primary_key = true, nullable = false },
+#   { name = "body", type = "text", nullable = true },
+#   { name = "audience", type = "string", nullable = true },
+#   { name = "scheduled_at", type = "datetime", nullable = true },
+#   { name = "created_at", type = "datetime", nullable = false },
+#   { name = "updated_at", type = "datetime", nullable = false }
+# ]
+#
+# == Polymorphic Associations
+# Polymorphic Targets:
+# - entry (as: :entryable)
+#
+# == Enums
+# - audience: { all_users: "all_users", crew_only: "crew_only", officers_only: "officers_only", command_staff: "command_staff" } (string)
+#
+# == Notes
+# - Column 'body' should probably have NOT NULL constraint
+# - Column 'audience' should probably have NOT NULL constraint
+# - String column 'audience' has no length limit - consider adding one
+# - Large text column 'body' is frequently queried - consider separate storage
+# <rails-lens:schema:end>
+class Announcement < ApplicationRecord
+  enum :audience, { all_users: 'all_users', crew_only: 'crew_only', officers_only: 'officers_only', command_staff: 'command_staff' }, suffix: true
+  has_one :entry, as: :entryable, dependent: :destroy
+  validates :audience, presence: true
+  validates :body, presence: true
+  scope :recent, -> { order(created_at: :desc) }
+end
+```
+
+**ERD Visualization:**
+```mermaid
+erDiagram
+    Announcement ||--o{ Entry : entryable
+    Announcement {
+        integer id PK
+        text body
+        string audience
+        datetime scheduled_at
+        datetime created_at
+        datetime updated_at
+    }
+    Entry {
+        integer id PK
+        string entryable_type
+        integer entryable_id
+        datetime created_at
+        datetime updated_at
+    }
+```
+
+**No grepping, no LLM hallucinations. Try it:** `gem install rails_lens`
+
 ## Requirements
 
 - Ruby >= 3.4.0

data/lib/rails_lens/analyzers/delegated_types.rb

@@ -17,7 +17,12 @@ module RailsLens
 
         lines << "Type Column: #{delegated_type_info[:type_column]}"
         lines << "ID Column: #{delegated_type_info[:id_column]}"
-        lines << "Types: #{delegated_type_info[:types].join(', ')}"
+        types_list = if delegated_type_info[:types].respond_to?(:keys)
+                       delegated_type_info[:types].keys
+                     else
+                       Array(delegated_type_info[:types])
+                     end
+        lines << "Types: #{types_list.join(', ')}"
 
         lines.join("\n")
       end

data/lib/rails_lens/analyzers/notes.rb

@@ -29,12 +29,22 @@ module RailsLens
 
         notes = []
 
-        notes.concat(analyze_indexes)
-        notes.concat(analyze_foreign_keys)
-        notes.concat(analyze_associations)
-        notes.concat(analyze_columns)
-        notes.concat(analyze_performance)
-        notes.concat(analyze_best_practices)
+        # Check if this model is backed by a view
+        is_view = ModelDetector.view_exists?(model_class)
+
+        if is_view
+          # For views, add view-specific checks
+          notes.concat(analyze_view_readonly)
+          notes.concat(analyze_view_gotchas)
+        else
+          # For tables, run all standard checks
+          notes.concat(analyze_indexes)
+          notes.concat(analyze_foreign_keys)
+          notes.concat(analyze_associations)
+          notes.concat(analyze_columns)
+          notes.concat(analyze_performance)
+          notes.concat(analyze_best_practices)
+        end
 
         notes.compact.uniq
       rescue ActiveRecord::StatementInvalid => e
@@ -47,6 +57,54 @@ module RailsLens
 
       private
 
+      def analyze_view_readonly
+        notes = []
+
+        # Check if this model is backed by a database view
+        if ModelDetector.view_exists?(model_class)
+          notes << '👁️ View-backed model: read-only'
+
+          # Check if model has readonly implementation
+          unless has_readonly_implementation?
+            notes << 'Add readonly? method'
+          end
+        end
+
+        notes
+      rescue StandardError => e
+        Rails.logger.debug { "Error checking view readonly status for #{model_class.name}: #{e.message}" }
+        []
+      end
+
+      def analyze_view_gotchas
+        notes = []
+        view_metadata = ViewMetadata.new(model_class)
+
+        # Check for materialized view specific issues
+        if view_metadata.materialized_view?
+          notes << '🔄 Materialized view: data may be stale until refreshed'
+          unless has_refresh_methods?
+            notes << 'Add refresh! method for manual updates'
+          end
+        end
+
+        # Check for nested views (view depending on other views)
+        dependencies = view_metadata.dependencies
+        if dependencies.any? { |dep| view_exists_by_name?(dep) }
+          notes << '⚠️ Nested views detected: may impact query performance'
+        end
+
+        # Check for readonly implementation
+        unless has_readonly_implementation?
+          notes << '🔒 Add readonly protection to prevent write operations'
+        end
+
+        notes
+      rescue StandardError => e
+        Rails.logger.debug { "Error analyzing view gotchas for #{model_class.name}: #{e.message}" }
+        []
+      end
+
       def analyze_indexes
         notes = []
 
@@ -320,6 +378,56 @@ module RailsLens
           column.type == :uuid || (column.type == :string && column.name.match?(/uuid|guid/))
         end
       end
+
+      def has_readonly_implementation?
+        # Check if model has readonly? method defined (not just inherited from ActiveRecord)
+        model_class.method_defined?(:readonly?) &&
+          model_class.instance_method(:readonly?).owner != ActiveRecord::Base
+      rescue StandardError
+        false
+      end
+
+      def has_refresh_methods?
+        # Check if model has refresh! method for materialized views
+        model_class.respond_to?(:refresh!) || model_class.respond_to?(:refresh_concurrently!)
+      rescue StandardError
+        false
+      end
+
+      def view_exists_by_name?(view_name)
+        # Check if a view exists in the database by name
+        case @connection.adapter_name.downcase
+        when 'postgresql'
+          result = @connection.exec_query(<<~SQL.squish, 'Check PostgreSQL View Existence')
+            SELECT 1 FROM information_schema.views#{' '}
+            WHERE table_name = '#{@connection.quote_string(view_name)}'
+            UNION ALL
+            SELECT 1 FROM pg_matviews#{' '}
+            WHERE matviewname = '#{@connection.quote_string(view_name)}'
+            LIMIT 1
+          SQL
+          result.rows.any?
+        when 'mysql', 'mysql2'
+          result = @connection.exec_query(<<~SQL.squish, 'Check MySQL View Existence')
+            SELECT 1 FROM information_schema.views#{' '}
+            WHERE table_name = '#{@connection.quote_string(view_name)}'
+            LIMIT 1
+          SQL
+          result.rows.any?
+        when 'sqlite', 'sqlite3'
+          result = @connection.exec_query(<<~SQL.squish, 'Check SQLite View Existence')
+            SELECT 1 FROM sqlite_master#{' '}
+            WHERE type = 'view' AND name = '#{@connection.quote_string(view_name)}'
+            LIMIT 1
+          SQL
+          result.rows.any?
+        else
+          false
+        end
+      rescue StandardError => e
+        Rails.logger.debug { "Error checking view existence for #{view_name}: #{e.message}" }
+        false
+      end
     end
   end
 end

data/lib/rails_lens/annotation_pipeline.rb

@@ -27,30 +27,33 @@ module RailsLens
         notes: []
       }
 
-      @providers.each do |provider|
-        next unless provider.applicable?(model_class)
+      # Use the model's connection pool to manage a single connection for all providers
+      model_class.connection_pool.with_connection do |connection|
+        @providers.each do |provider|
+          next unless provider.applicable?(model_class)
 
-        begin
-          result = provider.process(model_class)
+          begin
+            result = provider.process(model_class, connection)
 
-          case provider.type
-          when :schema
-            results[:schema] = result
-          when :section
-            results[:sections] << result if result
-          when :notes
-            results[:notes].concat(Array(result))
+            case provider.type
+            when :schema
+              results[:schema] = result
+            when :section
+              results[:sections] << result if result
+            when :notes
+              results[:notes].concat(Array(result))
+            end
+          rescue ActiveRecord::StatementInvalid => e
+            warn "Provider #{provider.class} database error for #{model_class}: #{e.message}"
+          rescue ActiveRecord::ConnectionNotDefined => e
+            warn "Provider #{provider.class} connection error for #{model_class}: #{e.message}"
+          rescue NameError, NoMethodError => e
+            warn "Provider #{provider.class} method error for #{model_class}: #{e.message}"
+          rescue RailsLens::Error => e
+            warn "Provider #{provider.class} rails_lens error for #{model_class}: #{e.message}"
+          rescue StandardError => e
+            warn "Provider #{provider.class} unexpected error for #{model_class}: #{e.message}"
           end
-        rescue ActiveRecord::StatementInvalid => e
-          warn "Provider #{provider.class} database error for #{model_class}: #{e.message}"
-        rescue ActiveRecord::ConnectionNotDefined => e
-          warn "Provider #{provider.class} connection error for #{model_class}: #{e.message}"
-        rescue NameError, NoMethodError => e
-          warn "Provider #{provider.class} method error for #{model_class}: #{e.message}"
-        rescue RailsLens::Error => e
-          warn "Provider #{provider.class} rails_lens error for #{model_class}: #{e.message}"
-        rescue StandardError => e
-          warn "Provider #{provider.class} unexpected error for #{model_class}: #{e.message}"
         end
       end
 
@@ -65,6 +68,7 @@ module RailsLens
 
       # Section providers (additional structured content)
       register(Providers::ExtensionsProvider.new) if RailsLens.config.extensions[:enabled]
+      register(Providers::ViewProvider.new)
       register(Providers::InheritanceProvider.new)
       register(Providers::EnumsProvider.new)
       register(Providers::DelegatedTypesProvider.new)
@@ -75,6 +79,7 @@ module RailsLens
       # Notes providers (analysis and recommendations)
       return unless RailsLens.config.schema[:include_notes]
 
+      register(Providers::ViewNotesProvider.new)
       register(Providers::IndexNotesProvider.new)
       register(Providers::ForeignKeyNotesProvider.new)
       register(Providers::AssociationNotesProvider.new)

data/lib/rails_lens/cli.rb

@@ -8,6 +8,11 @@ module RailsLens
   class CLI < Thor
     include CLIErrorHandler
 
+    # Thor configuration: exit with proper status codes on failure (modern behavior)
+    def self.exit_on_failure?
+      true
+    end
+
     class_option :config, type: :string, default: '.rails-lens.yml', desc: 'Configuration file path'
     class_option :dry_run, type: :boolean, desc: 'Show what would be done without making changes'
     class_option :verbose, type: :boolean, desc: 'Verbose output'
@@ -15,6 +20,7 @@ module RailsLens
 
     desc 'annotate', 'Annotate Rails models with schema information'
     option :models, type: :array, desc: 'Specific models to annotate'
+    option :include_abstract, type: :boolean, desc: 'Include abstract classes'
     option :position, type: :string, enum: %w[before after top bottom], desc: 'Annotation position'
     option :routes, type: :boolean, desc: 'Annotate controller routes'
     option :mailers, type: :boolean, desc: 'Annotate mailer methods'

data/lib/rails_lens/connection.rb

@@ -3,12 +3,12 @@
 module RailsLens
   class Connection
     class << self
-      def adapter_for(model_class)
-        connection = model_class.connection
-        adapter_name = detect_adapter_name(connection)
+      def adapter_for(model_class, connection = nil)
+        conn = connection || model_class.connection
+        adapter_name = detect_adapter_name(conn)
 
         adapter_class = resolve_adapter_class(adapter_name)
-        adapter_class.new(connection, model_class.table_name)
+        adapter_class.new(conn, model_class.table_name)
       end
 
       def resolve_adapter_class(adapter_name)

data/lib/rails_lens/erd/visualizer.rb

@@ -63,9 +63,22 @@ module RailsLens
           end
 
           group_models.each do |model|
+            # Additional safety check: Skip abstract models that might have slipped through
+            next if model.abstract_class?
+
+            # Skip models without valid tables/views or columns
+            # Include both table-backed and view-backed models
+            is_view = ModelDetector.view_exists?(model)
+            has_data_source = is_view || (model.table_exists? && model.columns.present?)
+            next unless has_data_source
+
             model_display_name = format_model_name(model)
+
             output << "  #{model_display_name} {"
+            # Track opening brace position for error recovery
+            brace_position = output.size
 
+            columns_added = false
             model.columns.each do |column|
               type_str = format_column_type(column)
               name_str = column.name
@@ -73,23 +86,42 @@ module RailsLens
               key_str = keys.map(&:to_s).join(' ')
 
               output << "    #{type_str} #{name_str}#{" #{key_str}" unless key_str.empty?}"
+              columns_added = true
             end
 
-            output << '  }'
-            output << ''
-
-            Rails.logger.debug { "Added entity: #{model_display_name}" } if options[:verbose]
+            # Only close the entity if we successfully added columns
+            if columns_added
+              output << '  }'
+              output << ''
+              Rails.logger.debug { "Added entity: #{model_display_name}" } if options[:verbose]
+            else
+              # Remove the opening brace if no columns were added
+              output.slice!(brace_position..-1)
+              Rails.logger.debug { "Skipped entity #{model_display_name}: no columns found" } if options[:verbose]
+            end
           rescue StandardError => e
             Rails.logger.debug { "Warning: Could not add entity #{model.name}: #{e.message}" }
-            # Don't add partial entity if there's an error
-            # Remove the opening brace line if it was added
-            output.pop if output.last&.end_with?(' {')
+            # Remove any partial entity content added since the opening brace
+            if output.size > brace_position
+              output.slice!(brace_position..-1)
+            end
           end
         end
 
+        # Add visual styling for views vs tables
+        add_visual_styling(output, models)
+
         # Add relationships
         output << '  %% Relationships'
         models.each do |model|
+          # Skip abstract models in relationship generation too
+          next if model.abstract_class?
+
+          # Include both table-backed and view-backed models
+          is_view = ModelDetector.view_exists?(model)
+          has_data_source = is_view || (model.table_exists? && model.columns.present?)
+          next unless has_data_source
+
           add_model_relationships(output, model, models)
         end
 
@@ -152,6 +184,10 @@ module RailsLens
 
           next unless target_model && models.include?(target_model)
 
+          # Skip relationships to abstract models
+          next if target_model.abstract_class?
+          next unless target_model.table_exists? && target_model.columns.present?
+
           case association.macro
           when :belongs_to
             add_belongs_to_relationship(output, model, association, target_model)
@@ -164,10 +200,12 @@ module RailsLens
           end
         end
 
-        # Check for closure_tree self-reference
-        return unless model.respond_to?(:_ct)
-
-        output << "  #{format_model_name(model)} }o--o{ #{format_model_name(model)} : \"closure_tree\""
+        # Check for closure_tree self-reference - but only if model is not abstract
+        # rubocop:disable Style/GuardClause
+        if model.respond_to?(:_ct) && !model.abstract_class?
+          output << "  #{format_model_name(model)} }o--o{ #{format_model_name(model)} : \"closure_tree\""
+        end
+        # rubocop:enable Style/GuardClause
       end
 
       def add_belongs_to_relationship(output, model, association, target_model)
@@ -225,6 +263,43 @@ module RailsLens
         output << '  }}%%'
       end
 
+      def add_visual_styling(output, models)
+        # Add class definitions for visual distinction between tables and views
+        output << ''
+        output << '  %% Entity Styling'
+
+        # Define styling classes
+        output << '  classDef tableEntity fill:#f9f9f9,stroke:#333,stroke-width:2px'
+        output << '  classDef viewEntity fill:#e6f3ff,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5'
+        output << '  classDef materializedViewEntity fill:#ffe6e6,stroke:#333,stroke-width:3px,stroke-dasharray: 5 5'
+
+        # Apply styling to each model
+        models.each do |model|
+          next if model.abstract_class?
+
+          is_view = ModelDetector.view_exists?(model)
+          has_data_source = is_view || (model.table_exists? && model.columns.present?)
+          next unless has_data_source
+
+          model_display_name = format_model_name(model)
+
+          if is_view
+            view_metadata = ViewMetadata.new(model)
+            output << if view_metadata.materialized_view?
+                        "  class #{model_display_name} materializedViewEntity"
+                      else
+                        "  class #{model_display_name} viewEntity"
+                      end
+          else
+            output << "  class #{model_display_name} tableEntity"
+          end
+        rescue StandardError => e
+          Rails.logger.debug { "Warning: Could not apply styling to #{model.name}: #{e.message}" }
+        end
+
+        output << ''
+      end
+
       def group_models_by_database(models)
         grouped = Hash.new { |h, k| h[k] = [] }
 

data/lib/rails_lens/model_detector.rb

@@ -37,8 +37,81 @@ module RailsLens
         concrete_models.select { |model| model.superclass != ActiveRecord::Base && concrete_models.include?(model.superclass) }
       end
 
+      def view_backed_models
+        detect_models.select { |model| view_exists?(model) }
+      end
+
+      def table_backed_models
+        detect_models.reject { |model| view_exists?(model) }
+      end
+
+      def view_exists?(model_class)
+        return false if model_class.abstract_class?
+        return false unless model_class.table_name
+
+        # Cache view existence checks for performance
+        @view_cache ||= {}
+        cache_key = "#{model_class.connection.object_id}_#{model_class.table_name}"
+
+        return @view_cache[cache_key] if @view_cache.key?(cache_key)
+
+        @view_cache[cache_key] = check_view_existence(model_class)
+      end
+
       private
 
+      def check_view_existence(model_class)
+        connection = model_class.connection
+        table_name = model_class.table_name
+
+        case connection.adapter_name.downcase
+        when 'postgresql'
+          check_postgresql_view(connection, table_name)
+        when 'mysql', 'mysql2'
+          check_mysql_view(connection, table_name)
+        when 'sqlite', 'sqlite3'
+          check_sqlite_view(connection, table_name)
+        else
+          false # Unsupported adapter
+        end
+      rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotDefined
+        false # If we can't check, assume it's not a view
+      end
+
+      # rubocop:disable Naming/PredicateMethod
+      def check_postgresql_view(connection, table_name)
+        # Check both regular views and materialized views
+        result = connection.exec_query(<<~SQL.squish, 'Check PostgreSQL View')
+          SELECT 1 FROM information_schema.views#{' '}
+          WHERE table_name = '#{connection.quote_string(table_name)}'
+          UNION ALL
+          SELECT 1 FROM pg_matviews#{' '}
+          WHERE matviewname = '#{connection.quote_string(table_name)}'
+          LIMIT 1
+        SQL
+        result.rows.any?
+      end
+
+      def check_mysql_view(connection, table_name)
+        result = connection.exec_query(<<~SQL.squish, 'Check MySQL View')
+          SELECT 1 FROM information_schema.views#{' '}
+          WHERE table_name = '#{connection.quote_string(table_name)}'
+          AND table_schema = DATABASE()
+          LIMIT 1
+        SQL
+        result.rows.any?
+      end
+
+      def check_sqlite_view(connection, table_name)
+        result = connection.exec_query(<<~SQL.squish, 'Check SQLite View')
+          SELECT 1 FROM sqlite_master#{' '}
+          WHERE type = 'view' AND name = '#{connection.quote_string(table_name)}'
+          LIMIT 1
+        SQL
+        result.rows.any?
+      end
+      # rubocop:enable Naming/PredicateMethod
+
       def eager_load_models
         # Zeitwerk is always available in Rails 7+
         Zeitwerk::Loader.eager_load_all
@@ -125,7 +198,7 @@ module RailsLens
 
         # Exclude abstract models and models without valid tables
         before_count = models.size
-        models = filter_models_concurrently(models, trace_filtering)
+        models = filter_models_concurrently(models, trace_filtering, options)
         log_filter_step('Abstract/invalid table removal', before_count, models.size, trace_filtering)
 
         # Exclude tables from configuration
@@ -183,7 +256,7 @@ module RailsLens
         end
       end
 
-      def filter_models_concurrently(models, trace_filtering)
+      def filter_models_concurrently(models, trace_filtering, options = {})
         # Use concurrent futures to check table existence in parallel
         futures = models.map do |model|
           Concurrent::Future.execute do
@@ -191,10 +264,13 @@ module RailsLens
             reason = nil
 
             begin
-              # Skip abstract models
-              if model.abstract_class?
+              # Skip abstract models unless explicitly included
+              if model.abstract_class? && !options[:include_abstract]
                 should_exclude = true
                 reason = 'abstract class'
+              # For abstract models that are included, skip table checks
+              elsif model.abstract_class? && options[:include_abstract]
+                reason = 'abstract class (included)'
               # Skip models without configured tables
               elsif !model.table_name
                 should_exclude = true
@@ -203,8 +279,12 @@ module RailsLens
               elsif !model.table_exists?
                 should_exclude = true
                 reason = "table '#{model.table_name}' does not exist"
+              # Additional check: Skip models that don't have any columns
+              elsif model.columns.empty?
+                should_exclude = true
+                reason = "table '#{model.table_name}' has no columns"
               else
-                reason = "table '#{model.table_name}' exists"
+                reason = "table '#{model.table_name}' exists with #{model.columns.size} columns"
               end
             rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotDefined => e
               should_exclude = true
@@ -212,6 +292,10 @@ module RailsLens
             rescue NameError, NoMethodError => e
               should_exclude = true
               reason = "method error checking model - #{e.message}"
+            rescue StandardError => e
+              # Catch any other errors and exclude the model to prevent ERD corruption
+              should_exclude = true
+              reason = "unexpected error checking model - #{e.message}"
             end
 
             if trace_filtering