rails_lens 0.0.0 → 0.2.2

data/lib/rails_lens/analyzers/performance_analyzer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Analyzers
+    class PerformanceAnalyzer < Base
+      def analyze
+        notes = []
+        notes.concat(analyze_large_text_columns)
+        notes.concat(analyze_uuid_indexes)
+        notes.concat(analyze_query_performance)
+        notes
+      end
+
+      private
+
+      def analyze_large_text_columns
+        notes = []
+
+        text_columns.each do |column|
+          if frequently_queried_column?(column)
+            notes << "Large text column '#{column.name}' is frequently queried - consider separate storage"
+          end
+        end
+
+        notes
+      end
+
+      def analyze_uuid_indexes
+        notes = []
+
+        uuid_columns.each do |column|
+          next if column.name == 'id' # Primary keys are already indexed
+
+          if should_be_indexed?(column) && !indexed?(column)
+            notes << "UUID column '#{column.name}' should be indexed for better query performance"
+          end
+        end
+
+        notes
+      end
+
+      def analyze_query_performance
+        notes = []
+
+        # Check for columns that are commonly used in WHERE clauses
+        commonly_queried_columns.each do |column|
+          next if indexed?(column)
+
+          notes << "Column '#{column.name}' is commonly used in queries - consider adding an index"
+        end
+
+        # Check for missing indexes on scoped columns
+        scoped_columns.each do |column|
+          next if indexed?(column)
+
+          notes << "Scope column '#{column.name}' should be indexed"
+        end
+
+        notes
+      end
+
+      def text_columns
+        model_class.columns.select { |c| c.type == :text }
+      end
+
+      def uuid_columns
+        model_class.columns.select { |c| c.type == :uuid || (c.type == :string && c.name.match?(/uuid|guid/i)) }
+      end
+
+      def frequently_queried_column?(column)
+        # Heuristic: columns with certain names are likely to be queried frequently
+        column.name.match?(/title|name|slug|description|summary|content|body/i)
+      end
+
+      def should_be_indexed?(column)
+        # UUID columns used as foreign keys or identifiers should be indexed
+        column.name.end_with?('_id', '_uuid', '_guid') ||
+          column.name.match?(/identifier|reference|token/i)
+      end
+
+      def commonly_queried_columns
+        model_class.columns.select do |column|
+          column.name.match?(/email|username|slug|token|code|status|state|type/i) ||
+            column.name.end_with?('_type', '_kind', '_category')
+        end
+      end
+
+      def scoped_columns
+        model_class.columns.select do |column|
+          column.name.match?(/scope|tenant|company|organization|account|workspace/i) &&
+            column.name.end_with?('_id')
+        end
+      end
+
+      def indexed?(column)
+        connection.indexes(table_name).any? do |index|
+          index.columns.include?(column.name)
+        end
+      end
+
+      def connection
+        model_class.connection
+      end
+
+      def table_name
+        model_class.table_name
+      end
+    end
+  end
+end

data/lib/rails_lens/annotation_pipeline.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RailsLens
+  # Manages the pipeline of content providers for generating annotations
+  class AnnotationPipeline
+    attr_reader :providers
+
+    def initialize
+      @providers = []
+      register_default_providers
+    end
+
+    def register(provider)
+      @providers << provider
+    end
+
+    def unregister(provider_class)
+      @providers.reject! { |p| p.is_a?(provider_class) }
+    end
+
+    delegate :clear, to: :@providers
+
+    def process(model_class)
+      results = {
+        schema: nil,
+        sections: [],
+        notes: []
+      }
+
+      @providers.each do |provider|
+        next unless provider.applicable?(model_class)
+
+        begin
+          result = provider.process(model_class)
+
+          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
+      end
+
+      results
+    end
+
+    private
+
+    def register_default_providers
+      # Schema provider (primary content)
+      register(Providers::SchemaProvider.new)
+
+      # Section providers (additional structured content)
+      register(Providers::ExtensionsProvider.new) if RailsLens.config.extensions[:enabled]
+      register(Providers::InheritanceProvider.new)
+      register(Providers::EnumsProvider.new)
+      register(Providers::DelegatedTypesProvider.new)
+      register(Providers::CompositeKeysProvider.new)
+      register(Providers::DatabaseConstraintsProvider.new)
+      register(Providers::GeneratedColumnsProvider.new)
+
+      # Notes providers (analysis and recommendations)
+      return unless RailsLens.config.schema[:include_notes]
+
+      register(Providers::IndexNotesProvider.new)
+      register(Providers::ForeignKeyNotesProvider.new)
+      register(Providers::AssociationNotesProvider.new)
+      register(Providers::ColumnNotesProvider.new)
+      register(Providers::PerformanceNotesProvider.new)
+      register(Providers::BestPracticesNotesProvider.new)
+      register(Providers::ExtensionNotesProvider.new) if RailsLens.config.extensions[:enabled]
+    end
+  end
+end

data/lib/rails_lens/cli.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'commands'
+require_relative 'cli_error_handler'
+
+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'
+    class_option :debug, type: :boolean, desc: 'Debug output with full backtraces'
+
+    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'
+    option :all, type: :boolean, desc: 'Annotate models, routes, and mailers'
+    def annotate
+      with_error_handling do
+        setup_environment
+
+        results = {}
+        commands = Commands.new(self)
+
+        # Annotate models (default behavior or when --all is specified)
+        results[:models] = commands.annotate_models(options) if should_annotate_models?
+
+        # Annotate routes
+        results[:routes] = commands.annotate_routes(options) if should_annotate_routes?
+
+        # Annotate mailers
+        results[:mailers] = commands.annotate_mailers(options) if should_annotate_mailers?
+
+        results
+      end
+    end
+
+    desc 'remove', 'Remove annotations from Rails files'
+    option :routes, type: :boolean, desc: 'Remove controller route annotations'
+    option :mailers, type: :boolean, desc: 'Remove mailer annotations'
+    option :all, type: :boolean, desc: 'Remove all annotations'
+    def remove
+      with_error_handling do
+        setup_environment
+
+        results = {}
+        commands = Commands.new(self)
+
+        # Remove model annotations (default behavior or when --all is specified)
+        results[:models] = commands.remove_models(options) if should_remove_models?
+
+        # Remove route annotations
+        results[:routes] = commands.remove_routes(options) if should_remove_routes?
+
+        # Remove mailer annotations
+        results[:mailers] = commands.remove_mailers(options) if should_remove_mailers?
+
+        results
+      end
+    end
+
+    desc 'erd', 'Generate Entity Relationship Diagram (Mermaid format)'
+    option :output, type: :string, desc: 'Output directory'
+    option :verbose, type: :boolean, desc: 'Verbose output'
+    option :group_by_database, type: :boolean, desc: 'Group models by database connection instead of domain'
+    def erd
+      with_error_handling do
+        setup_environment
+
+        # Transform CLI options to visualizer options
+        visualizer_options = options.dup
+        visualizer_options[:output_dir] = options[:output] || 'output'
+
+        commands = Commands.new(self)
+        commands.generate_erd(visualizer_options)
+      end
+    end
+
+    desc 'version', 'Show Rails Lens version'
+    def version
+      say "Rails Lens #{RailsLens::VERSION}"
+    end
+
+    desc 'lint', 'Lint Rails Lens configuration and model annotations'
+    option :domains, type: :array, desc: 'Specific domains to lint (models, routes, mailers)'
+    def lint
+      with_error_handling do
+        setup_environment
+
+        commands = Commands.new(self)
+        commands.lint(options)
+      end
+    end
+
+    desc 'check', 'Check Rails Lens configuration validity'
+    def check
+      with_error_handling do
+        setup_environment
+
+        commands = Commands.new(self)
+        commands.check(options)
+      end
+    end
+
+    desc 'config SUBCOMMAND', 'Manage Rails Lens configuration'
+    option :key, type: :string, desc: 'Configuration key'
+    option :value, type: :string, desc: 'Configuration value'
+    def config(subcommand = 'show')
+      with_error_handling do
+        setup_environment
+
+        commands = Commands.new(self)
+        commands.config(subcommand, options)
+      end
+    end
+
+    private
+
+    def setup_environment
+      RakeBootstrapper.call
+      load_configuration(options[:config])
+      configure_error_reporting
+    end
+
+    def load_configuration(config_file)
+      if File.exist?(config_file)
+        RailsLens.load_config_file(config_file)
+        say "Loaded configuration from #{config_file}", :green if options[:verbose]
+      elsif config_file != '.rails-lens.yml'
+        raise ConfigurationError, "Configuration file not found: #{config_file}"
+      elsif options[:verbose]
+        say "Using default configuration (#{config_file} not found)", :yellow
+      end
+    end
+
+    def configure_error_reporting
+      RailsLens.config.verbose = options[:verbose]
+      RailsLens.config.debug = options[:debug]
+    end
+
+    # Helper methods to determine what to annotate/remove
+    def should_annotate_models?
+      (!options[:routes] && !options[:mailers]) || options[:all]
+    end
+
+    def should_annotate_routes?
+      options[:routes] || options[:all]
+    end
+
+    def should_annotate_mailers?
+      options[:mailers] || options[:all]
+    end
+
+    def should_remove_models?
+      (!options[:routes] && !options[:mailers]) || options[:all]
+    end
+
+    def should_remove_routes?
+      options[:routes] || options[:all]
+    end
+
+    def should_remove_mailers?
+      options[:mailers] || options[:all]
+    end
+  end
+end

data/lib/rails_lens/cli_error_handler.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RailsLens
+  # Provides consistent error handling for CLI commands
+  module CLIErrorHandler
+    def with_error_handling
+      yield
+    rescue Interrupt
+      say "\nOperation cancelled by user", :yellow
+      exit 1
+    rescue ConfigurationError => e
+      handle_configuration_error(e)
+    rescue ModelDetectionError => e
+      handle_model_error(e)
+    rescue DatabaseError => e
+      handle_database_error(e)
+    rescue AnnotationError => e
+      handle_annotation_error(e)
+    rescue ExtensionError => e
+      handle_extension_error(e)
+    rescue StandardError => e
+      handle_unexpected_error(e)
+    end
+
+    private
+
+    def handle_configuration_error(error)
+      say "Configuration Error: #{error.message}", :red
+      say 'Please check your .rails-lens.yml file', :yellow
+      exit 1
+    end
+
+    def handle_model_error(error)
+      say "Model Error: #{error.message}", :red
+      if options[:verbose]
+        say 'Make sure your Rails application is properly loaded', :yellow
+        say 'Try running: bundle exec rails_lens annotate', :yellow
+      end
+      exit 1
+    end
+
+    def handle_database_error(error)
+      say "Database Error: #{error.message}", :red
+      if options[:verbose]
+        say 'Possible causes:', :yellow
+        say '  - Database server is not running', :yellow
+        say '  - Invalid database credentials', :yellow
+        say '  - Table does not exist', :yellow
+        say '  - Permission denied', :yellow
+      end
+      exit 1
+    end
+
+    def handle_annotation_error(error)
+      say "Annotation Error: #{error.message}", :red
+      if options[:verbose]
+        say 'Failed to annotate one or more files', :yellow
+        say 'Check file permissions and syntax', :yellow
+      end
+      exit 1
+    end
+
+    def handle_extension_error(error)
+      say "Extension Error: #{error.message}", :red
+      return unless options[:verbose]
+
+      say 'An extension failed to load or execute', :yellow
+      say 'You can disable extensions in .rails-lens.yml', :yellow
+
+      # Don't exit - extensions are optional
+    end
+
+    def handle_unexpected_error(error)
+      say "Unexpected Error: #{error.class.name}", :red
+      say error.message, :red
+
+      if options[:verbose] || options[:debug]
+        say "\nBacktrace:", :yellow
+        say error.backtrace.first(10).join("\n"), :yellow
+      end
+
+      say "\nPlease report this issue at: https://github.com/your-org/rails_lens/issues", :cyan
+      exit 1
+    end
+  end
+end

data/lib/rails_lens/commands.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module RailsLens
+  # Handles the actual execution of CLI commands
+  class Commands
+    attr_reader :output
+
+    def initialize(output = $stdout)
+      @output = output
+    end
+
+    def annotate_models(options = {})
+      results = Schema::AnnotationManager.annotate_all(options)
+
+      output.say "Annotated #{results[:annotated].length} models", :green
+      output.say "Skipped #{results[:skipped].length} models", :yellow if results[:skipped].any?
+
+      if results[:failed].any?
+        output.say "Failed to annotate #{results[:failed].length} models:", :red
+        results[:failed].each do |failure|
+          output.say "  - #{failure[:model]}: #{failure[:error]}", :red
+        end
+      end
+
+      results
+    end
+
+    def annotate_routes(options = {})
+      annotator = Route::Annotator.new(dry_run: options[:dry_run])
+      changed_files = annotator.annotate_all
+
+      output.say "Annotated #{changed_files.length} controller files with routes", :green
+      changed_files.each { |file| output.say "  - #{file}", :blue } if options[:verbose] && changed_files.any?
+
+      { changed_files: changed_files }
+    end
+
+    def annotate_mailers(options = {})
+      annotator = Mailer::Annotator.new(dry_run: options[:dry_run])
+      changed_files = annotator.annotate_all
+
+      output.say "Annotated #{changed_files.length} mailer files", :green
+      changed_files.each { |file| output.say "  - #{file}", :blue } if options[:verbose] && changed_files.any?
+
+      { changed_files: changed_files }
+    end
+
+    def remove_models(options = {})
+      results = Schema::AnnotationManager.remove_all(options)
+      output.say "Removed annotations from #{results[:removed].length} models", :green
+      results
+    end
+
+    def remove_routes(options = {})
+      annotator = Route::Annotator.new(dry_run: options[:dry_run])
+      changed_files = annotator.remove_all
+      output.say "Removed route annotations from #{changed_files.length} controller files", :green
+      { changed_files: changed_files }
+    end
+
+    def remove_mailers(options = {})
+      annotator = Mailer::Annotator.new(dry_run: options[:dry_run])
+      changed_files = annotator.remove_all
+      output.say "Removed mailer annotations from #{changed_files.length} mailer files", :green
+      { changed_files: changed_files }
+    end
+
+    def generate_erd(options = {})
+      visualizer = ERD::Visualizer.new(options: options)
+      filename = visualizer.generate
+      output.say "Entity Relationship Diagram generated at #{filename}", :green
+      filename
+    end
+
+    def lint(options = {})
+      output.say 'Linting Rails Lens configuration and annotations...', :blue
+
+      issues = []
+      warnings = []
+      domains = options[:domains] || %w[models routes mailers]
+
+      domains.each do |domain|
+        case domain
+        when 'models'
+          # Check for inconsistent model annotations
+          output.say '  Checking models domain...', :blue if options[:verbose]
+        when 'routes'
+          # Check for route annotation consistency
+          output.say '  Checking routes domain...', :blue if options[:verbose]
+        when 'mailers'
+          # Check for mailer annotation consistency
+          output.say '  Checking mailers domain...', :blue if options[:verbose]
+        end
+      end
+
+      if issues.empty? && warnings.empty?
+        output.say 'No linting issues found', :green
+      else
+        output.say "Found #{issues.length} issues and #{warnings.length} warnings", :yellow
+      end
+
+      { issues: issues, warnings: warnings }
+    end
+
+    def check(_options = {})
+      output.say 'Checking Rails Lens configuration validity...', :blue
+
+      # Check if Rails is properly loaded
+      unless defined?(Rails)
+        output.say 'Rails environment not detected', :red
+        return { valid: false, errors: ['Rails environment not detected'] }
+      end
+
+      # Check database connections
+      errors = []
+      begin
+        ApplicationRecord.connection.execute('SELECT 1')
+        output.say 'Primary database connection: OK', :green
+      rescue StandardError => e
+        errors << "Primary database connection failed: #{e.message}"
+        output.say 'Primary database connection: FAILED', :red
+      end
+
+      if errors.empty?
+        output.say 'Configuration is valid', :green
+        { valid: true, errors: [] }
+      else
+        output.say 'Configuration has errors', :red
+        { valid: false, errors: errors }
+      end
+    end
+
+    def config(subcommand, options = {})
+      case subcommand
+      when 'show'
+        output.say 'Rails Lens Configuration:', :blue
+        output.say "  Config file: #{RailsLens.config_file || 'default'}"
+        output.say "  Verbose: #{RailsLens.config.verbose || false}"
+        output.say "  Debug: #{RailsLens.config.debug || false}"
+
+        if RailsLens.config.respond_to?(:position)
+          output.say "  Default position: #{RailsLens.config.position || 'before'}"
+        end
+
+      when 'set'
+        if options[:key] && options[:value]
+          output.say "Setting #{options[:key]} = #{options[:value]}", :green
+          # NOTE: This would require implementing config persistence
+          output.say 'Note: Configuration changes are not persisted yet', :yellow
+        else
+          output.say 'Usage: config set --key KEY --value VALUE', :red
+        end
+
+      when 'reset'
+        output.say 'Resetting configuration to defaults', :yellow
+        # NOTE: This would reset to defaults
+
+      else
+        output.say "Unknown config subcommand: #{subcommand}", :red
+        output.say 'Available: show, set, reset'
+      end
+    end
+  end
+end