rails_lens 0.0.0 → 0.2.0

data/lib/rails_lens/providers/inheritance_provider.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class InheritanceProvider < Base
+      def type
+        :section
+      end
+
+      def process(model_class)
+        analyzer = Analyzers::Inheritance.new(model_class)
+        content = analyzer.analyze
+
+        return nil unless content
+
+        {
+          title: nil, # Content already includes section header
+          content: content
+        }
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/notes_provider_base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    # Base class for notes providers that wrap analyzers
+    class NotesProviderBase < Base
+      def type
+        :notes
+      end
+
+      def applicable?(model_class)
+        model_has_table?(model_class)
+      end
+
+      def analyzer_class
+        raise NotImplementedError, "#{self.class} must implement #analyzer_class"
+      end
+
+      def process(model_class)
+        analyzer = analyzer_class.new(model_class)
+        analyzer.analyze
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/performance_notes_provider.rb

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

data/lib/rails_lens/providers/schema_provider.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    class SchemaProvider < Base
+      def type
+        :schema
+      end
+
+      def applicable?(_model_class)
+        true # Always applicable - handles both abstract and regular models
+      end
+
+      def process(model_class)
+        if model_class.abstract_class?
+          # For abstract classes, show database connection information in TOML format
+          connection = model_class.connection
+          adapter_name = connection.adapter_name
+
+          lines = []
+          lines << "database_dialect = \"#{adapter_name}\""
+
+          # Add basic database information
+          begin
+            db_name = begin
+              connection.database_version
+            rescue StandardError
+              'unknown'
+            end
+            lines << "database_version = \"#{db_name}\""
+          rescue StandardError
+            # Skip if can't get version
+          end
+
+          lines << ''
+          lines << '# This is an abstract class that establishes a database connection'
+          lines << '# but does not have an associated table.'
+
+          lines.join("\n")
+        else
+          # Add schema information for regular models
+          adapter = Connection.adapter_for(model_class)
+          adapter.generate_annotation(model_class)
+        end
+      end
+    end
+  end
+end

data/lib/rails_lens/providers/section_provider_base.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Providers
+    # Base class for section providers that wrap analyzers
+    class SectionProviderBase < Base
+      def type
+        :section
+      end
+
+      def analyzer_class
+        raise NotImplementedError, "#{self.class} must implement #analyzer_class"
+      end
+
+      def process(model_class)
+        analyzer = analyzer_class.new(model_class)
+        content = analyzer.analyze
+
+        return nil unless content
+
+        {
+          title: nil, # Analyzers include their own section headers
+          content: content
+        }
+      end
+    end
+  end
+end

data/lib/rails_lens/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module RailsLens
+  class Railtie < Rails::Railtie
+    railtie_name :rails_lens
+
+    rake_tasks do
+      load 'rails_lens/tasks/annotate.rake'
+      load 'rails_lens/tasks/erd.rake'
+      load 'rails_lens/tasks/schema.rake'
+      load 'rails_lens/tasks/routes.rake'
+      load 'rails_lens/tasks/mailers.rake'
+    end
+  end
+end

data/lib/rails_lens/rake_bootstrapper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RailsLens
+  class RakeBootstrapper
+    class << self
+      def call
+        require 'rake'
+        load './Rakefile' if File.exist?('./Rakefile') && !Rake::Task.task_defined?(:environment)
+
+        begin
+          Rake::Task[:environment].invoke
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rails_lens/route/annotator.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Route
+    # Handles adding route annotations to controller files
+    class Annotator
+      def initialize(dry_run: false)
+        @dry_run = dry_run
+        @routes = RailsLens::Route::Extractor.call
+        @changed_files = []
+      end
+
+      # Annotate all controller files with route information
+      #
+      # @param pattern [String] Glob pattern for controller files
+      # @param exclusion [String] Glob pattern for files to exclude
+      # @return [Array<String>] List of changed files
+      def annotate_all(pattern: '**/*_controller.rb', exclusion: 'vendor/**/*_controller.rb')
+        controller_paths = Rails.root.glob(pattern)
+                                .reject { |path| Rails.root.glob(exclusion).include?(path) }
+
+        source_paths_map.each do |source_path, actions|
+          # Use exact path matching or find controller files by parsing
+          if controller_paths.include?(source_path) || controller_file_exists?(source_path)
+            annotate_file(path: source_path, actions: actions)
+          end
+        end
+
+        @changed_files
+      end
+
+      # Remove route annotations from all controller files
+      #
+      # @param pattern [String] Glob pattern for controller files
+      # @param exclusion [String] Glob pattern for files to exclude
+      # @return [Array<String>] List of changed files
+      def remove_all(pattern: '**/*_controller.rb', exclusion: 'vendor/**/*_controller.rb')
+        controller_paths = Rails.root.glob(pattern)
+                                .reject { |path| Rails.root.glob(exclusion).include?(path) }
+
+        # Also include controller files from source paths
+        all_controller_paths = (controller_paths + source_paths_map.keys).uniq
+        all_controller_paths.select! { |path| controller_file_exists?(path) }
+
+        all_controller_paths.each do |path|
+          remove_annotations_from_file(path)
+        end
+
+        @changed_files
+      end
+
+      private
+
+      # Map source paths to their respective routes
+      #
+      # @return [Hash] Source paths mapped to their routes
+      def source_paths_map
+        map = {}
+
+        @routes.each_value do |actions|
+          actions.each do |action, data|
+            data.each do |datum|
+              map[datum[:source_path]] ||= {}
+              map[datum[:source_path]][action] ||= []
+              map[datum[:source_path]][action].push(datum)
+            end
+          end
+        end
+
+        map
+      end
+
+      # Annotate a single controller file
+      #
+      # @param path [String] Path to controller file
+      # @param actions [Hash] Action data for the controller
+      # @return [void]
+      def annotate_file(path:, actions:)
+        parsed_file = RailsLens::Route::Parser.call(path: path, actions: actions.keys)
+
+        parsed_file[:groups].each_cons(2) do |prev, curr|
+          clean_group(prev)
+          next unless curr[:type] == :action
+
+          route_data = actions[curr[:action]]
+          next unless route_data&.any?
+
+          annotate_group(group: curr, route_data: route_data)
+        end
+
+        write_to_file(path: path, parsed_file: parsed_file)
+      end
+
+      # Remove annotations from a single file
+      #
+      # @param path [String] Path to controller file
+      # @return [void]
+      def remove_annotations_from_file(path)
+        content = File.read(path)
+        original_content = content.dup
+
+        # Remove rails-lens route annotations
+        content.gsub!(/^.*<rails-lens:routes:begin>.*$\n/, '')
+        content.gsub!(/^.*<rails-lens:routes:end>.*$\n/, '')
+        content.gsub!(/^\s*#\s*@route.*$\n/, '')
+        content.gsub!(/^\s*#\s*ROUTE:.*$\n/, '')
+
+        return unless content != original_content
+
+        write_content_to_file(path: path, content: content)
+      end
+
+      # Clean existing route annotations from a comment group
+      #
+      # @param group [Hash] Parsed group from parser
+      # @return [void]
+      def clean_group(group)
+        return unless group[:type] == :comment
+
+        # Remove existing route annotations
+        group[:body] = group[:body].gsub(/^\s*#\s*@route.*$\n/, '')
+        group[:body] = group[:body].gsub(/^\s*#\s*ROUTE:.*$\n/, '')
+        group[:body] = group[:body].gsub(/^.*<rails-lens:routes:begin>.*$\n/, '')
+        group[:body] = group[:body].gsub(/^.*<rails-lens:routes:end>.*$\n/, '')
+      end
+
+      # Add route annotations to a group
+      #
+      # @param group [Hash] Parsed group from parser
+      # @param route_data [Array<Hash>] Route data for the action
+      # @return [void]
+      def annotate_group(group:, route_data:)
+        whitespace = /^(\s*).*$/.match(group[:body])[1]
+
+        # Build annotation block
+        annotation_lines = []
+        annotation_lines << "#{whitespace}# <rails-lens:routes:begin>"
+
+        # Group routes by path only (not by name)
+        # This allows different named routes with same path to be merged
+        grouped_routes = {}
+        route_data.each do |datum|
+          key = datum[:path]
+          grouped_routes[key] ||= {
+            path: datum[:path],
+            name: datum[:name],
+            verbs: [],
+            defaults: datum[:defaults]
+          }
+
+          # If this path already has a different name, keep routes separate
+          if grouped_routes[key][:name] == datum[:name]
+            grouped_routes[key][:verbs] << datum[:verb]
+          else
+            # Create a unique key for this different route
+            unique_key = "#{datum[:path]}__#{datum[:name]}"
+            grouped_routes[unique_key] = {
+              path: datum[:path],
+              name: datum[:name],
+              verbs: [datum[:verb]],
+              defaults: datum[:defaults]
+            }
+          end
+        end
+
+        # Add grouped annotations
+        grouped_routes.values.reverse_each do |route|
+          annotation_lines << "#{whitespace}# #{format_route_annotation_structured(**route)}"
+        end
+
+        annotation_lines << "#{whitespace}# <rails-lens:routes:end>"
+
+        # Add to group
+        annotation_block = "#{annotation_lines.join("\n")}\n"
+        group[:body] = annotation_block + group[:body]
+      end
+
+      # Format a single route annotation
+      #
+      # @param verb [String] HTTP verb
+      # @param path [String] Route path
+      # @param name [String] Route name
+      # @param defaults [Hash] Default parameters
+      # @param source_path [String] Controller file path
+      # @return [String] Formatted annotation
+      def format_route_annotation(verb:, path:, name:, defaults:, source_path:)
+        annotation = "@route #{verb} #{path}"
+
+        if defaults&.any?
+          defaults_str = defaults.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')
+          annotation += " {#{defaults_str}}"
+        end
+
+        annotation += " (#{name})" if name
+        annotation
+      end
+
+      # Format a single route annotation in structured format
+      #
+      # @param verbs [Array<String>] HTTP verbs (can be single verb for backward compatibility)
+      # @param path [String] Route path
+      # @param name [String] Route name
+      # @param defaults [Hash] Default parameters
+      # @param source_path [String] Controller file path (optional)
+      # @param verb [String] Single HTTP verb (for backward compatibility)
+      # @return [String] Formatted structured annotation
+      def format_route_annotation_structured(path:, name:, defaults:, verbs: nil, source_path: nil, verb: nil)
+        # Handle backward compatibility - if verbs not provided, use verb
+        verbs ||= [verb].compact
+
+        parts = []
+        parts << path
+        parts << "name: #{name}" if name
+
+        # Format verbs - use array syntax if multiple, single if one
+        if verbs.size > 1
+          parts << "via: [#{verbs.join(', ')}]"
+        elsif verbs.size == 1
+          parts << "via: #{verbs.first}"
+        end
+
+        parts << "defaults: #{defaults.inspect}" if defaults&.any?
+
+        "ROUTE: #{parts.join(', ')}"
+      end
+
+      # Write parsed file content back to disk
+      #
+      # @param path [String] File path
+      # @param parsed_file [Hash] Parsed file from parser
+      # @return [void]
+      def write_to_file(path:, parsed_file:)
+        new_content = parsed_file[:groups].pluck(:body).join
+        return if parsed_file[:content] == new_content
+
+        write_content_to_file(path: path, content: new_content)
+      end
+
+      # Write content to file
+      #
+      # @param path [String] File path
+      # @param content [String] File content
+      # @return [void]
+      def write_content_to_file(path:, content:)
+        return if @dry_run
+
+        File.write(path, content)
+        @changed_files << path
+      end
+
+      # Check if a controller file exists and contains controller classes
+      #
+      # @param path [String] File path
+      # @return [Boolean] Whether file exists and contains controller classes
+      def controller_file_exists?(path)
+        return false unless File.exist?(path)
+
+        begin
+          parser_result = RailsLens::Parsers::PrismParser.parse_file(path)
+          parser_result.classes.any? { |cls| cls.name.end_with?('Controller') }
+        rescue RailsLens::ParseError, Errno::ENOENT, IOError
+          # Fallback to filename-based detection
+          File.basename(path).end_with?('_controller.rb')
+        end
+      end
+    end
+  end
+end

data/lib/rails_lens/route/extractor.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Route
+    # Handles extracting route information from Rails application
+    class Extractor
+      class << self
+        # Extract all routes from Rails application
+        #
+        # @return [Hash] Routes hash organized by controller and action
+        def call
+          routes = {}
+
+          populate_routes(Rails.application, routes)
+          backfill_routes(routes)
+        end
+
+        private
+
+        # Recursively populate routes from Rails application (handles engines)
+        #
+        # @param app [Rails::Application] Rails application instance
+        # @param routes [Hash] Collection of all route info
+        # @return [void]
+        def populate_routes(app, routes)
+          app.routes.routes.each do |route|
+            if route.app.respond_to?(:engine?) && route.app.engine?
+              populate_routes(route.app.app, routes)
+              next
+            end
+
+            controller, action, defaults, source_path = extract_data_from(route)
+            next unless controller && action && source_path
+
+            routes[controller] ||= {}
+            routes[controller][action] ||= []
+
+            add_route_info(
+              route: route,
+              routes: routes,
+              controller: controller,
+              action: action,
+              defaults: defaults,
+              source_path: source_path
+            )
+          end
+        end
+
+        # Add formatted route info for the given parameters
+        #
+        # @param route [ActionDispatch::Journey::Route] Route instance
+        # @param routes [Hash] Collection of all route info
+        # @param controller [String] Controller name
+        # @param action [String] Action name
+        # @param defaults [Hash] Default parameters for route
+        # @param source_path [String] Path to controller file
+        # @return [void]
+        def add_route_info(route:, routes:, controller:, action:, defaults:, source_path:)
+          verbs_for(route).each do |verb|
+            route_info = {
+              verb: verb,
+              path: route.path.spec.to_s.gsub('(.:format)', ''),
+              name: route.name,
+              defaults: defaults,
+              source_path: source_path
+            }
+
+            routes[controller][action].push(route_info)
+            routes[controller][action].uniq!
+          end
+        end
+
+        # Extract HTTP verbs from route
+        #
+        # @param route [ActionDispatch::Journey::Route] Route instance
+        # @return [Array<String>] List of HTTP verbs
+        def verbs_for(route)
+          route_verb = route.verb.to_s
+          %w[GET POST PUT PATCH DELETE].select { |verb| route_verb.include?(verb) }
+        end
+
+        # Extract controller, action, defaults, and source path from route
+        #
+        # @param route [ActionDispatch::Journey::Route] Route instance
+        # @return [Array<String, String, Hash, String>] controller, action, defaults, source_path
+        def extract_data_from(route)
+          defaults = route.defaults.dup
+          controller = defaults.delete(:controller)
+          action = defaults.delete(:action)
+
+          return [nil, nil, nil, nil] unless controller && action
+
+          begin
+            controller_class = "#{controller.underscore.camelize}Controller".constantize
+            action_method = action.to_sym
+
+            source_path = if controller_class.method_defined?(action_method)
+                            controller_class.instance_method(action_method).source_location&.first
+                          end
+
+            [controller, action, defaults, source_path]
+          rescue NameError
+            [nil, nil, nil, nil]
+          end
+        end
+
+        # Backfill route names that might be missing
+        #
+        # @param routes [Hash] Routes hash
+        # @return [Hash] Backfilled routes hash
+        def backfill_routes(routes)
+          paths = {}
+
+          # Map paths to their verbs and names
+          routes.each_value do |actions|
+            actions.each_value do |data|
+              data.each do |datum|
+                paths[datum[:path]] ||= {}
+                paths[datum[:path]][datum[:verb]] ||= datum[:name]
+
+                # Backfill names for routes that don't have them
+                datum[:name] ||= paths.dig(datum[:path], datum[:verb])
+                datum[:name] ||= paths[datum[:path]]&.values&.compact&.first
+              end
+            end
+          end
+
+          routes
+        end
+      end
+    end
+  end
+end

data/lib/rails_lens/route/parser.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RailsLens
+  module Route
+    # Handles parsing controller files and groups lines into categories
+    class Parser
+      class << self
+        # Parse a controller file and return grouped content
+        #
+        # @param path [String] File path to parse
+        # @param actions [Array<String>] List of valid actions for this controller
+        # @return [Hash] { content => String, groups => Array<Hash> }
+        def call(path:, actions:)
+          groups = []
+          group = {}
+          content = File.read(path)
+
+          content.each_line.with_index do |line, index|
+            parsed_line = parse_line(line: line, actions: actions)
+
+            if group[:type] == parsed_line[:type]
+              # Same group. Push the current line into the current group.
+              group[:body] += line
+            else
+              # Now looking at a new group. Push the current group onto the array
+              # and start a new one.
+              groups.push(group) unless group.empty?
+              group = parsed_line.merge(line_number: index + 1)
+            end
+          end
+
+          # Push the last group onto the array and return.
+          groups.push(group)
+          { content: content, groups: groups }
+        end
+
+        private
+
+        # Parse a single line and determine its type
+        #
+        # @param line [String] A line of a file
+        # @param actions [Array<String>] List of valid actions for this controller
+        # @return [Hash] { type => Symbol, body => String, action => String }
+        def parse_line(line:, actions:)
+          comment_match = /^\s*#.*$/.match(line)
+          def_match = /^\s*def\s+(\w*)\s*\w*.*$/.match(line)
+
+          if comment_match
+            { type: :comment, body: line, action: nil }
+          elsif def_match && actions.include?(def_match[1])
+            { type: :action, body: line, action: def_match[1] }
+          else
+            { type: :code, body: line, action: nil }
+          end
+        end
+      end
+    end
+  end
+end