rails_lens 0.0.0 → 0.2.0

data/lib/rails_lens/model_detector.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module RailsLens
+  class ModelDetector
+    class << self
+      def detect_models(options = {})
+        # Always eager load all models
+        eager_load_models
+
+        # Find all ActiveRecord models (always use ActiveRecord::Base as it's always defined)
+        models = find_descendants_of(ActiveRecord::Base)
+
+        # Filter and sort models
+        models = filter_models(models, options)
+        models.sort_by { |model| model.name || '' }
+      end
+
+      def model_for_table(table_name)
+        detect_models.find { |model| model.table_name == table_name }
+      end
+
+      def abstract_models
+        detect_models.select(&:abstract_class?)
+      end
+
+      def concrete_models
+        detect_models.reject(&:abstract_class?)
+      end
+
+      def sti_base_models
+        concrete_models.select { |model| has_sti_column?(model) }
+      end
+
+      def sti_child_models
+        concrete_models.select { |model| model.superclass != ActiveRecord::Base && concrete_models.include?(model.superclass) }
+      end
+
+      private
+
+      def eager_load_models
+        # Zeitwerk is always available in Rails 7+
+        Zeitwerk::Loader.eager_load_all
+      end
+
+      def find_descendants_of(base_class)
+        base_class.descendants.select do |klass|
+          klass.name && !klass.name.start_with?('HABTM_')
+        end
+      end
+
+      def filter_models(models, options)
+        # Data provenance trace - log filtering decisions
+        trace_filtering = options[:trace_filtering] || ENV.fetch('RAILS_LENS_TRACE_FILTERING', nil)
+
+        original_count = models.size
+        Rails.logger.debug { "[ModelDetector] Starting with #{original_count} models" } if trace_filtering
+
+        # Remove anonymous classes and non-class objects
+        before_count = models.size
+        models = models.select { |model| model.is_a?(Class) && model.name.present? }
+        log_filter_step('Anonymous/unnamed class removal', before_count, models.size, trace_filtering)
+
+        # Filter by namespace if specified
+        if options[:namespace]
+          namespace = options[:namespace].to_s
+          before_count = models.size
+          models = models.select { |model| model.name.start_with?(namespace) }
+          log_filter_step("Namespace filter (#{namespace})", before_count, models.size, trace_filtering)
+        end
+
+        # Exclude specific models
+        if options[:exclude]
+          exclude_patterns = Array(options[:exclude])
+          before_count = models.size
+          models = models.reject do |model|
+            excluded = exclude_patterns.any? do |pattern|
+              case pattern
+              when Regexp
+                model.name.match?(pattern)
+              when String
+                model.name == pattern || model.table_name == pattern
+              else
+                false
+              end
+            end
+            if excluded && trace_filtering
+              Rails.logger.debug do
+                "[ModelDetector] Excluding #{model.name}: matched exclude pattern"
+              end
+            end
+            excluded
+          end
+          log_filter_step('Exclude patterns', before_count, models.size, trace_filtering)
+        end
+
+        # Include only specific models
+        if options[:include]
+          include_patterns = Array(options[:include])
+          before_count = models.size
+          models = models.select do |model|
+            included = include_patterns.any? do |pattern|
+              case pattern
+              when Regexp
+                model.name.match?(pattern)
+              when String
+                model.name == pattern || model.table_name == pattern
+              else
+                false
+              end
+            end
+            if included && trace_filtering
+              Rails.logger.debug do
+                "[ModelDetector] Including #{model.name}: matched include pattern"
+              end
+            end
+            if !included && trace_filtering
+              Rails.logger.debug { "[ModelDetector] Excluding #{model.name}: did not match include patterns" }
+            end
+            included
+          end
+          log_filter_step('Include patterns', before_count, models.size, trace_filtering)
+        end
+
+        # Exclude abstract models and models without valid tables
+        before_count = models.size
+        models = filter_models_concurrently(models, trace_filtering)
+        log_filter_step('Abstract/invalid table removal', before_count, models.size, trace_filtering)
+
+        # Exclude tables from configuration
+        excluded_tables = RailsLens.config.schema[:exclude_tables]
+        before_count = models.size
+        models = models.reject do |model|
+          begin
+            excluded = excluded_tables.include?(model.table_name)
+            if excluded && trace_filtering
+              Rails.logger.debug do
+                "[ModelDetector] Excluding #{model.name}: table '#{model.table_name}' in exclude_tables config"
+              end
+            end
+            excluded
+          rescue ActiveRecord::ConnectionNotDefined
+            # This can happen in multi-db setups if the connection is not yet established
+            # We will assume the model should be kept in this case
+            if trace_filtering
+              Rails.logger.debug do
+                "[ModelDetector] Keeping #{model.name}: connection not defined, assuming keep"
+              end
+            end
+            false
+          end
+        rescue ActiveRecord::StatementInvalid => e
+          if trace_filtering
+            Rails.logger.debug do
+              "[ModelDetector] Keeping #{model.name}: database error checking exclude_tables - #{e.message}"
+            end
+          end
+          false
+        end
+        log_filter_step('Configuration exclude_tables', before_count, models.size, trace_filtering)
+
+        if trace_filtering
+          Rails.logger.debug do
+            "[ModelDetector] Final result: #{models.size} models after all filtering"
+          end
+        end
+        Rails.logger.debug { "[ModelDetector] Final models: #{models.map(&:name).join(', ')}" } if trace_filtering
+
+        models
+      end
+
+      def log_filter_step(step_name, before_count, after_count, trace_filtering)
+        return unless trace_filtering
+
+        filtered_count = before_count - after_count
+        if filtered_count.positive?
+          Rails.logger.debug do
+            "[ModelDetector] #{step_name}: filtered out #{filtered_count} models (#{before_count} -> #{after_count})"
+          end
+        else
+          Rails.logger.debug { "[ModelDetector] #{step_name}: no models filtered (#{after_count} remain)" }
+        end
+      end
+
+      def filter_models_concurrently(models, trace_filtering)
+        # Use concurrent futures to check table existence in parallel
+        futures = models.map do |model|
+          Concurrent::Future.execute do
+            should_exclude = false
+            reason = nil
+
+            begin
+              # Skip abstract models
+              if model.abstract_class?
+                should_exclude = true
+                reason = 'abstract class'
+              # Skip models without configured tables
+              elsif !model.table_name
+                should_exclude = true
+                reason = 'no table name'
+              # Skip models whose tables don't exist
+              elsif !model.table_exists?
+                should_exclude = true
+                reason = "table '#{model.table_name}' does not exist"
+              else
+                reason = "table '#{model.table_name}' exists"
+              end
+            rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotDefined => e
+              should_exclude = true
+              reason = "database error checking model - #{e.message}"
+            rescue NameError, NoMethodError => e
+              should_exclude = true
+              reason = "method error checking model - #{e.message}"
+            end
+
+            if trace_filtering
+              action = should_exclude ? 'Excluding' : 'Keeping'
+              Rails.logger.debug { "[ModelDetector] #{action} #{model.name}: #{reason}" }
+            end
+
+            { model: model, exclude: should_exclude }
+          end
+        end
+
+        # Wait for all futures to complete and filter results
+        results = futures.map(&:value!)
+        results.reject { |result| result[:exclude] }.pluck(:model)
+      end
+
+      def has_sti_column?(model)
+        return false unless model.table_exists?
+
+        sti_column = model.inheritance_column
+        model.column_names.include?(sti_column)
+      rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotDefined
+        false
+      end
+    end
+  end
+end

data/lib/rails_lens/parsers/class_info.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Parsers
+    class ClassInfo
+      attr_reader :name, :line_number, :column, :end_line, :namespace
+
+      def initialize(name:, line_number:, column:, end_line:, namespace: nil)
+        @name = name
+        @line_number = line_number
+        @column = column
+        @end_line = end_line
+        @namespace = namespace
+      end
+
+      def full_name
+        if namespace.present?
+          "#{namespace}::#{name}"
+        else
+          name
+        end
+      end
+
+      def matches?(class_name)
+        class_name_str = class_name.to_s
+
+        # Exact matches
+        return true if name == class_name_str
+        return true if full_name == class_name_str
+
+        # Handle simple name match only if no namespace specified in query
+        return true if class_name_str.exclude?('::') && (name == class_name_str)
+
+        false
+      end
+
+      def to_s
+        full_name
+      end
+
+      def inspect
+        "#<ClassInfo name=#{name} line=#{line_number} namespace=#{namespace}>"
+      end
+    end
+  end
+end

data/lib/rails_lens/parsers/module_info.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Parsers
+    class ModuleInfo
+      attr_reader :name, :line_number, :column, :end_line, :namespace
+
+      def initialize(name:, line_number:, column:, end_line:, namespace: nil)
+        @name = name
+        @line_number = line_number
+        @column = column
+        @end_line = end_line
+        @namespace = namespace
+      end
+
+      def full_name
+        if namespace.present?
+          "#{namespace}::#{name}"
+        else
+          name
+        end
+      end
+
+      def to_s
+        full_name
+      end
+
+      def inspect
+        "#<ModuleInfo name=#{name} line=#{line_number} namespace=#{namespace}>"
+      end
+    end
+  end
+end

data/lib/rails_lens/parsers/parser_result.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Parsers
+    class ParserResult
+      attr_reader :classes, :modules, :file_path
+
+      def initialize(classes:, modules:, file_path:)
+        @classes = classes
+        @modules = modules
+        @file_path = file_path
+      end
+
+      def find_class(name)
+        classes.find { |cls| cls.matches?(name) }
+      end
+
+      def find_module(name)
+        modules.find { |mod| mod.name == name || mod.full_name == name }
+      end
+
+      def class_names
+        classes.map(&:full_name)
+      end
+
+      def module_names
+        modules.map(&:full_name)
+      end
+
+      def empty?
+        classes.empty? && modules.empty?
+      end
+
+      def to_s
+        lines = ["File: #{file_path}"]
+
+        unless modules.empty?
+          lines << 'Modules:'
+          modules.each { |mod| lines << "  #{mod}" }
+        end
+
+        unless classes.empty?
+          lines << 'Classes:'
+          classes.each { |cls| lines << "  #{cls}" }
+        end
+
+        lines.join("\n")
+      end
+
+      def inspect
+        "#<ParserResult file=#{file_path} classes=#{classes.size} modules=#{modules.size}>"
+      end
+    end
+  end
+end

data/lib/rails_lens/parsers/prism_parser.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module RailsLens
+  module Parsers
+    class PrismParser
+      def self.parse_file(file_path)
+        source = File.read(file_path)
+        parsed = Prism.parse(source)
+
+        classes = []
+        modules = []
+
+        traverse_node(parsed.value, classes, modules)
+
+        ParserResult.new(
+          classes: classes,
+          modules: modules,
+          file_path: file_path
+        )
+      rescue Prism::ParseError, Errno::ENOENT, IOError
+        # Return empty result on parse errors
+        ParserResult.new(
+          classes: [],
+          modules: [],
+          file_path: file_path
+        )
+      end
+
+      def self.traverse_node(node, classes, modules, namespace = [])
+        return unless node
+
+        case node
+        when Prism::ClassNode
+          class_name = extract_constant_name(node.constant_path)
+
+          classes << ClassInfo.new(
+            name: class_name,
+            line_number: node.location.start_line,
+            column: node.location.start_column,
+            end_line: node.location.end_line,
+            namespace: namespace.join('::').presence
+          )
+
+          # Process nested classes and modules
+          traverse_children(node, classes, modules, namespace + [class_name])
+
+        when Prism::ModuleNode
+          module_name = extract_constant_name(node.constant_path)
+
+          modules << ModuleInfo.new(
+            name: module_name,
+            line_number: node.location.start_line,
+            column: node.location.start_column,
+            end_line: node.location.end_line,
+            namespace: namespace.join('::').presence
+          )
+
+          # Process nested classes and modules
+          traverse_children(node, classes, modules, namespace + [module_name])
+
+        else
+          # For other node types, recursively traverse children
+          traverse_children(node, classes, modules, namespace)
+        end
+      end
+
+      def self.traverse_children(node, classes, modules, namespace = [])
+        return unless node.respond_to?(:child_nodes)
+
+        node.child_nodes.each do |child_node|
+          traverse_node(child_node, classes, modules, namespace)
+        end
+      end
+
+      def self.extract_constant_name(constant_path)
+        case constant_path
+        when Prism::ConstantReadNode
+          constant_path.name.to_s
+        when Prism::ConstantPathNode
+          # For nested constants like A::B::C, extract the last part
+          extract_constant_name(constant_path.child)
+        else
+          constant_path.to_s
+        end
+      end
+    end
+  end
+end

data/lib/rails_lens/parsers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Parsers
+    # Main entry point for parsing functionality
+    def self.parse_file(file_path)
+      PrismParser.parse_file(file_path)
+    end
+  end
+end

data/lib/rails_lens/providers/association_notes_provider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class AssociationNotesProvider < NotesProviderBase
+      def analyzer_class
+        Analyzers::AssociationAnalyzer
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/base.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    # Base class for all annotation content providers
+    class Base
+      # Returns the type of content this provider generates
+      # :schema - Primary schema information (only one allowed)
+      # :section - A named section with structured content
+      # :notes - Analysis notes and recommendations
+      def type
+        raise NotImplementedError, "#{self.class} must implement #type"
+      end
+
+      # Returns true if this provider should process the given model
+      def applicable?(_model_class)
+        true
+      end
+
+      # Processes the model and returns content
+      # For :schema type - returns a string with the schema content
+      # For :section type - returns a hash with { title: String, content: String } or nil
+      # For :notes type - returns an array of note strings
+      def process(model_class)
+        raise NotImplementedError, "#{self.class} must implement #process"
+      end
+
+      protected
+
+      def model_has_table?(model_class)
+        !model_class.abstract_class? && model_class.table_exists?
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/best_practices_notes_provider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class BestPracticesNotesProvider < NotesProviderBase
+      def analyzer_class
+        Analyzers::BestPracticesAnalyzer
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/column_notes_provider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class ColumnNotesProvider < NotesProviderBase
+      def analyzer_class
+        Analyzers::ColumnAnalyzer
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/composite_keys_provider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class CompositeKeysProvider < SectionProviderBase
+      def analyzer_class
+        Analyzers::CompositeKeys
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/database_constraints_provider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class DatabaseConstraintsProvider < SectionProviderBase
+      def analyzer_class
+        Analyzers::DatabaseConstraints
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/delegated_types_provider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class DelegatedTypesProvider < SectionProviderBase
+      def analyzer_class
+        Analyzers::DelegatedTypes
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/enums_provider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class EnumsProvider < SectionProviderBase
+      def analyzer_class
+        Analyzers::Enums
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/extension_notes_provider.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class ExtensionNotesProvider < Base
+      def type
+        :notes
+      end
+
+      def applicable?(model_class)
+        RailsLens.config.extensions[:enabled] && model_has_table?(model_class)
+      end
+
+      def process(model_class)
+        results = ExtensionLoader.apply_extensions(model_class)
+        results[:notes]
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/extensions_provider.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class ExtensionsProvider < Base
+      def type
+        :section
+      end
+
+      def process(model_class)
+        results = ExtensionLoader.apply_extensions(model_class)
+
+        return nil if results[:annotations].empty?
+
+        {
+          title: '== Extensions',
+          content: results[:annotations].join("\n")
+        }
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/foreign_key_notes_provider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class ForeignKeyNotesProvider < NotesProviderBase
+      def analyzer_class
+        Analyzers::ForeignKeyAnalyzer
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/generated_columns_provider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class GeneratedColumnsProvider < SectionProviderBase
+      def analyzer_class
+        Analyzers::GeneratedColumns
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/index_notes_provider.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class IndexNotesProvider < Base
+      def type
+        :notes
+      end
+
+      def applicable?(model_class)
+        model_has_table?(model_class)
+      end
+
+      def process(model_class)
+        analyzer = Analyzers::IndexAnalyzer.new(model_class)
+        analyzer.analyze
+      end
+    end
+  end
+end