rails_lens 0.0.0 → 0.2.2

data/lib/rails_lens/schema/annotation.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Schema
+    class Annotation
+      MARKER_FORMAT = 'rails-lens:schema'
+
+      attr_reader :content
+
+      def initialize
+        @content = []
+      end
+
+      def start_marker
+        "# <#{MARKER_FORMAT}:begin>"
+      end
+
+      def end_marker
+        "# <#{MARKER_FORMAT}:end>"
+      end
+
+      def add_line(line)
+        @content << line
+      end
+
+      def add_lines(lines)
+        @content.concat(lines)
+      end
+
+      def to_s
+        return '' if @content.empty?
+
+        lines = []
+        lines << start_marker
+
+        @content.each do |line|
+          lines << (line.empty? ? '#' : "# #{line}")
+        end
+
+        lines << end_marker
+        lines.join("\n")
+      end
+
+      def self.extract(file_content)
+        start_marker = "# <#{MARKER_FORMAT}:begin>"
+        end_marker = "# <#{MARKER_FORMAT}:end>"
+
+        start_index = file_content.index(start_marker)
+        return nil unless start_index
+
+        end_index = file_content.index(end_marker, start_index)
+        return nil unless end_index
+
+        {
+          start_index: start_index,
+          end_index: end_index + end_marker.length,
+          content: file_content[start_index..(end_index + end_marker.length - 1)]
+        }
+      end
+
+      def self.remove(file_content)
+        # Remove all occurrences of the annotation blocks
+        result = file_content.dup
+
+        while (annotation = extract(result))
+          # Preserve one newline if the annotation was followed by a newline
+          replacement = ''
+          replacement = "\n" if annotation[:end_index] < result.length && result[annotation[:end_index]] == "\n"
+
+          result[annotation[:start_index]...annotation[:end_index]] = replacement
+        end
+
+        # Clean up multiple consecutive blank lines
+        result.gsub(/\n\n\n+/, "\n\n")
+      end
+
+      def self.insert_after_line(file_content, line_pattern, annotation_text)
+        lines = file_content.split("\n")
+        insert_index = nil
+
+        lines.each_with_index do |line, index|
+          if line.match?(line_pattern)
+            insert_index = index + 1
+            break
+          end
+        end
+
+        return file_content unless insert_index
+
+        # Insert the annotation
+        lines.insert(insert_index, annotation_text)
+        lines.join("\n")
+      end
+
+      def self.update_or_insert(file_content, annotation_text, line_pattern)
+        # First, try to find and update existing annotation
+        if (existing = extract(file_content))
+          # Replace existing annotation
+          before = file_content[0...existing[:start_index]]
+          after = file_content[existing[:end_index]..]
+
+          # Ensure proper spacing
+          before = "#{before.rstrip}\n"
+          after = "\n#{after.lstrip}" if after && !after.start_with?("\n")
+
+          return before + annotation_text + after
+        end
+
+        # No existing annotation, insert new one
+        insert_after_line(file_content, line_pattern, annotation_text)
+      end
+
+      def self.parse_content(annotation_block)
+        return {} unless annotation_block
+
+        lines = annotation_block.split("\n").map { |line| line.sub(/^#\s?/, '') }
+
+        # Remove marker lines
+        lines = lines[1..-2] if lines.first&.match?(/<.*:begin>/) && lines.last&.match?(/<.*:end>/)
+
+        sections = {}
+        current_section = nil
+        current_content = []
+
+        lines.each do |line|
+          if line.match?(/^==\s+(.+)/)
+            # Save previous section if any
+            sections[current_section] = current_content.join("\n").strip if current_section
+
+            current_section = line.strip
+            current_content = []
+          else
+            current_content << line
+          end
+        end
+
+        # Save last section
+        sections[current_section] = current_content.join("\n").strip if current_section
+
+        sections
+      end
+    end
+  end
+end

data/lib/rails_lens/schema/annotation_manager.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative '../file_insertion_helper'
+
+module RailsLens
+  module Schema
+    class AnnotationManager
+      attr_reader :model_class
+
+      def initialize(model_class)
+        @model_class = model_class
+      end
+
+      def annotate_file(file_path = nil, allow_external_files: false)
+        file_path ||= model_file_path
+        return unless file_path && File.exist?(file_path)
+
+        # Only annotate files within the Rails application (unless explicitly allowed)
+        if !allow_external_files && defined?(Rails.root) && !file_path.start_with?(Rails.root.to_s)
+          return
+        end
+
+        annotation_text = generate_annotation
+
+        # First remove any existing annotations
+        content = File.read(file_path)
+        content = Annotation.remove(content) if Annotation.extract(content)
+
+        # Try AST-based insertion first
+        class_name = model_class.name.split('::').last
+
+        # Use Prism-based insertion
+        if FileInsertionHelper.insert_at_class_definition(file_path, class_name, annotation_text)
+          true
+        else
+          # Final fallback to old method
+          annotated_content = add_annotation(content, file_path)
+          if annotated_content == content
+            false
+          else
+            File.write(file_path, annotated_content)
+            true
+          end
+        end
+      end
+
+      def remove_annotations(file_path = nil)
+        file_path ||= model_file_path
+        return unless file_path && File.exist?(file_path)
+
+        content = File.read(file_path)
+        cleaned_content = Annotation.remove(content)
+
+        if cleaned_content == content
+          false
+        else
+          File.write(file_path, cleaned_content)
+          true
+        end
+      end
+
+      def generate_annotation
+        pipeline = AnnotationPipeline.new
+        results = pipeline.process(model_class)
+
+        annotation = Annotation.new
+
+        # Add schema content
+        annotation.add_lines(results[:schema].split("\n")) if results[:schema]
+
+        # Add sections
+        results[:sections].each do |section|
+          next unless section && section[:content]
+
+          annotation.add_line('')
+          # The provider can optionally provide a title
+          annotation.add_line(section[:title]) if section[:title]
+          annotation.add_lines(section[:content].split("\n"))
+        end
+
+        # Add notes
+        if results[:notes].any?
+          annotation.add_line('')
+          annotation.add_line('== Notes')
+          results[:notes].uniq.each do |note|
+            annotation.add_line("- #{note}")
+          end
+        end
+
+        annotation.to_s
+      end
+
+      def self.annotate_all(options = {})
+        models = ModelDetector.detect_models(options)
+
+        # Filter abstract classes based on options
+        if options[:include_abstract]
+          # Include all models
+        elsif options[:abstract_only]
+          models = models.select(&:abstract_class?)
+        else
+          # Default: exclude abstract classes
+          models = models.reject(&:abstract_class?)
+        end
+
+        results = { annotated: [], skipped: [], failed: [] }
+
+        models.each do |model|
+          # Ensure model is actually a class, not a hash or other object
+          unless model.is_a?(Class)
+            results[:failed] << { model: model.inspect, error: "Expected Class, got #{model.class}" }
+            next
+          end
+
+          # Skip models without tables or with missing tables (but not abstract classes)
+          unless model.abstract_class? || model.table_exists?
+            results[:skipped] << model.name
+            warn "Skipping #{model.name} - table does not exist" if options[:verbose]
+            next
+          end
+
+          manager = new(model)
+
+          # Determine file path based on options
+          file_path = if options[:models_path]
+                        File.join(options[:models_path], "#{model.name.underscore}.rb")
+                      else
+                        nil # Use default model_file_path
+                      end
+
+          # Allow external files when models_path is provided (for testing)
+          allow_external = options[:models_path].present?
+
+          if manager.annotate_file(file_path, allow_external_files: allow_external)
+            results[:annotated] << model.name
+          else
+            results[:skipped] << model.name
+          end
+        rescue ActiveRecord::StatementInvalid => e
+          # Handle database-related errors (missing tables, schemas, etc.)
+          results[:skipped] << model.name
+          warn "Skipping #{model.name} - database error: #{e.message}" if options[:verbose]
+        rescue StandardError => e
+          model_name = if model.is_a?(Class) && model.respond_to?(:name)
+                         model.name
+                       else
+                         model.inspect
+                       end
+          results[:failed] << { model: model_name, error: e.message }
+        end
+
+        results
+      end
+
+      def self.remove_all(options = {})
+        models = ModelDetector.detect_models(options)
+        results = { removed: [], skipped: [], failed: [] }
+
+        models.each do |model|
+          manager = new(model)
+          if manager.remove_annotations
+            results[:removed] << model.name
+          else
+            results[:skipped] << model.name
+          end
+        rescue StandardError => e
+          results[:failed] << { model: model.name, error: e.message }
+        end
+
+        results
+      end
+
+      private
+
+      def add_annotation(content, _file_path = nil)
+        annotation_text = generate_annotation
+
+        # First check if annotation already exists and remove it
+        existing = Annotation.extract(content)
+        content = Annotation.remove(content) if existing
+
+        # Use the file insertion helper to insert after frozen_string_literal
+        FileInsertionHelper.insert_after_frozen_string_literal(content, annotation_text)
+      end
+
+      def model_file_path
+        # First try const_source_location as it's more reliable for finding model files
+        const_source_location = Object.const_source_location(model_class.name)
+        return const_source_location.first if const_source_location
+
+        # Fallback to instance method source location (though this often points to ActiveRecord)
+        model_class.instance_method(:initialize).source_location.first
+      rescue StandardError
+        # As a last resort, try to construct the path from Rails conventions
+        if defined?(Rails.root) && model_class.name
+          model_path = Rails.root.join('app', 'models', "#{model_class.name.underscore}.rb").to_s
+          model_path if File.exist?(model_path)
+        end
+      end
+    end
+  end
+end

data/lib/rails_lens/tasks/annotate.rake

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+namespace :rails_lens do
+  desc 'Annotate Rails models with schema information'
+  task :annotate, [:models] => :environment do |_t, args|
+    require 'rails_lens/schema/annotation_manager'
+
+    options = {
+      models: args[:models]&.split(',')
+    }
+
+    results = RailsLens::Schema::AnnotationManager.annotate_all(options)
+
+    puts "Annotated #{results[:annotated].length} models"
+    puts "Skipped #{results[:skipped].length} models" if results[:skipped].any?
+    if results[:failed].any?
+      puts "Failed to annotate #{results[:failed].length} models:"
+      results[:failed].each do |failure|
+        puts "  - #{failure[:model]}: #{failure[:error]}"
+      end
+    end
+  end
+
+  desc 'Annotate all Rails files (models, routes, and mailers)'
+  task all: :environment do
+    # Annotate models
+    Rake::Task['rails_lens:annotate'].invoke
+
+    # Annotate routes
+    Rake::Task['rails_lens:routes:annotate'].invoke
+
+    # Annotate mailers
+    Rake::Task['rails_lens:mailers:annotate'].invoke
+  end
+end

data/lib/rails_lens/tasks/erd.rake

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+namespace :rails_lens do
+  desc 'Generate Entity Relationship Diagram (Mermaid format)'
+  task erd: :environment do
+    gem 'mermaid', '>= 0.0.5'
+    require 'mermaid'
+
+    puts 'Generating ERD...'
+    visualizer = RailsLens::ERD::Visualizer.new
+    filename = visualizer.generate
+    puts "ERD generated successfully: #{filename}"
+    puts ''
+    puts 'To view the ERD:'
+    puts '1. Install Mermaid CLI: npm install -g @mermaid-js/mermaid-cli'
+    puts "2. Generate image: mmdc -i #{filename} -o erd.png"
+    puts '3. Or view online: https://mermaid.live/'
+  rescue Gem::LoadError
+    puts 'Error: Mermaid gem (>= 0.0.5) is required for ERD generation.'
+    puts "Add to your Gemfile: gem 'mermaid', '>= 0.0.5'"
+    puts 'Then run: bundle install'
+    exit 1
+  end
+end

data/lib/rails_lens/tasks/mailers.rake

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+namespace :rails_lens do
+  namespace :mailers do
+    desc 'Annotate mailer files with mailer information'
+    task annotate: :environment do
+      require 'rails_lens/mailer/annotator'
+
+      annotator = RailsLens::Mailer::Annotator.new
+      changed_files = annotator.annotate_all
+
+      puts "Annotated #{changed_files.length} mailer files with mailer information"
+      changed_files.each { |file| puts "  - #{file}" }
+    end
+
+    desc 'Remove mailer annotations from mailer files'
+    task remove: :environment do
+      require 'rails_lens/mailer/annotator'
+
+      annotator = RailsLens::Mailer::Annotator.new
+      changed_files = annotator.remove_all
+
+      puts "Removed mailer annotations from #{changed_files.length} mailer files"
+      changed_files.each { |file| puts "  - #{file}" }
+    end
+  end
+end

data/lib/rails_lens/tasks/routes.rake

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+namespace :rails_lens do
+  namespace :routes do
+    desc 'Annotate controller files with route information'
+    task annotate: :environment do
+      require 'rails_lens/route/annotator'
+
+      annotator = RailsLens::Route::Annotator.new
+      changed_files = annotator.annotate_all
+
+      puts "Annotated #{changed_files.length} controller files with route information"
+      changed_files.each { |file| puts "  - #{file}" }
+    end
+
+    desc 'Remove route annotations from controller files'
+    task remove: :environment do
+      require 'rails_lens/route/annotator'
+
+      annotator = RailsLens::Route::Annotator.new
+      changed_files = annotator.remove_all
+
+      puts "Removed route annotations from #{changed_files.length} controller files"
+      changed_files.each { |file| puts "  - #{file}" }
+    end
+  end
+end

data/lib/rails_lens/tasks/schema.rake

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+namespace :rails_lens do
+  namespace :schema do
+    desc 'Annotate models with database schema information'
+    task annotate: :environment do
+      require 'rails_lens'
+
+      options = {}
+      options[:include_abstract] = true if ENV['INCLUDE_ABSTRACT'] == 'true'
+
+      puts 'Annotating models with schema information...'
+      results = RailsLens.annotate_models(options)
+
+      if results[:annotated].any?
+        puts "Annotated #{results[:annotated].length} models"
+        puts '(including abstract classes)' if options[:include_abstract]
+      end
+
+      puts "\nSkipped #{results[:skipped].length} models (no changes needed)" if results[:skipped].any?
+
+      if results[:failed].any?
+        puts "\nFailed to annotate #{results[:failed].length} models:"
+        results[:failed].each do |failure|
+          puts "  ✗ #{failure[:model]}: #{failure[:error]}"
+        end
+      end
+    end
+
+    desc 'Remove schema annotations from models'
+    task remove: :environment do
+      require 'rails_lens'
+
+      puts 'Removing schema annotations...'
+      results = RailsLens.remove_annotations
+
+      if results[:removed].any?
+        puts "Removed annotations from #{results[:removed].length} models:"
+        results[:removed].each { |model| puts "  ✓ #{model}" }
+      end
+
+      puts "\nSkipped #{results[:skipped].length} models (no annotations found)" if results[:skipped].any?
+
+      if results[:failed].any?
+        puts "\nFailed to process #{results[:failed].length} models:"
+        results[:failed].each do |failure|
+          puts "  ✗ #{failure[:model]}: #{failure[:error]}"
+        end
+      end
+    end
+
+    desc 'Analyze models and show notes'
+    task analyze: :environment do
+      require 'rails_lens'
+
+      puts 'Analyzing models...'
+
+      pipeline = RailsLens::AnnotationPipeline.new
+      models = RailsLens::ModelDetector.detect_models
+
+      models.each do |model|
+        next if model.abstract_class? || !model.table_exists?
+
+        results = pipeline.process(model)
+        notes = results[:notes]
+
+        if notes.any?
+          puts "\n#{model.name}:"
+          notes.uniq.each { |note| puts "  - #{note}" }
+        end
+      rescue StandardError => e
+        puts "\nError analyzing #{model.name}: #{e.message}"
+      end
+    end
+
+    desc 'List detected extensions'
+    task extensions: :environment do
+      require 'rails_lens'
+
+      puts 'Detected extensions:'
+
+      extensions = RailsLens::ExtensionLoader.load_extensions
+      if extensions.any?
+        extensions.each do |ext|
+          status = ext.detect? ? '✓ Active' : '○ Inactive'
+          version = begin
+            ext.interface_version
+          rescue StandardError
+            'Unknown'
+          end
+          puts "  #{status} #{ext.gem_name} (interface v#{version})"
+        end
+      else
+        puts '  No extensions detected'
+      end
+
+      config = RailsLens.config.extensions
+      puts "\nExtension configuration:"
+      puts "  Enabled: #{config[:enabled]}"
+      puts "  Autoload: #{config[:autoload]}"
+      puts "  Interface version: #{config[:interface_version]}"
+
+      puts "  Ignored gems: #{config[:ignore].join(', ')}" if config[:ignore].any?
+
+      puts "  Custom paths: #{config[:custom_paths].join(', ')}" if config[:custom_paths].any?
+    end
+  end
+end

data/lib/rails_lens/version.rb

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