feat: add database view annotation support (#7)

- Add ViewMetadata class for view detection and metadata extraction
- Implement view-specific adapters for PostgreSQL, MySQL, and SQLite
- Support regular views and materialized views with proper annotations
- Add ViewNotesProvider for view-specific analysis and recommendations

Author: seuros

lib/rails_lens/analyzers/notes.rb

@@ -29,12 +29,22 @@ def analyze
 
         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 @@ def analyze
 
       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 @@ def uuid_columns
           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

lib/rails_lens/annotation_pipeline.rb

@@ -65,6 +65,7 @@ def register_default_providers
 
       # 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 +76,7 @@ def register_default_providers
       # 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)

lib/rails_lens/erd/visualizer.rb

@@ -66,8 +66,11 @@ def generate_mermaid(models)
             # Additional safety check: Skip abstract models that might have slipped through
             next if model.abstract_class?
 
-            # Skip models without valid tables or columns
-            next unless model.table_exists? && model.columns.present?
+            # 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)
 
@@ -105,12 +108,19 @@ def generate_mermaid(models)
           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?
-          next unless model.table_exists? && model.columns.present?
+
+          # 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
@@ -253,6 +263,43 @@ def add_theme_configuration(output)
         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] = [] }
 

lib/rails_lens/model_detector.rb

@@ -37,8 +37,81 @@ def sti_child_models
         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

lib/rails_lens/providers/extension_notes_provider.rb

@@ -8,7 +8,8 @@ def type
       end
 
       def applicable?(model_class)
-        RailsLens.config.extensions[:enabled] && model_has_table?(model_class)
+        # Only applicable to tables, not views
+        RailsLens.config.extensions[:enabled] && model_has_table?(model_class) && !ModelDetector.view_exists?(model_class)
       end
 
       def process(model_class)

lib/rails_lens/providers/index_notes_provider.rb

@@ -8,7 +8,8 @@ def type
       end
 
       def applicable?(model_class)
-        model_has_table?(model_class)
+        # Only applicable to tables, not views
+        model_has_table?(model_class) && !ModelDetector.view_exists?(model_class)
       end
 
       def process(model_class)

lib/rails_lens/providers/notes_provider_base.rb

@@ -9,7 +9,8 @@ def type
       end
 
       def applicable?(model_class)
-        model_has_table?(model_class)
+        # Only applicable to tables, not views
+        model_has_table?(model_class) && !ModelDetector.view_exists?(model_class)
       end
 
       def analyzer_class

lib/rails_lens/providers/schema_provider.rb

@@ -51,7 +51,7 @@ def process(model_class)
 
           lines.join("\n")
         else
-          # Add schema information for regular models
+          # Add schema information for regular models (tables or views)
           adapter = Connection.adapter_for(model_class)
           adapter.generate_annotation(model_class)
         end