eager_eye 0.1.0

data/lib/eager_eye/analyzer.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "parser/current"
+
+module EagerEye
+  class Analyzer
+    DETECTOR_CLASSES = {
+      loop_association: Detectors::LoopAssociation,
+      serializer_nesting: Detectors::SerializerNesting,
+      missing_counter_cache: Detectors::MissingCounterCache
+    }.freeze
+
+    attr_reader :paths, :issues
+
+    def initialize(paths: nil)
+      @paths = Array(paths || EagerEye.configuration.app_path)
+      @issues = []
+    end
+
+    def run
+      @issues = []
+
+      ruby_files.each do |file_path|
+        analyze_file(file_path)
+      end
+
+      @issues
+    end
+
+    private
+
+    def ruby_files
+      all_files = paths.flat_map do |path|
+        if File.file?(path)
+          [path]
+        elsif File.directory?(path)
+          Dir.glob(File.join(path, "**", "*.rb"))
+        else
+          Dir.glob(path)
+        end
+      end
+
+      all_files.reject { |file| excluded?(file) }
+    end
+
+    def excluded?(file_path)
+      EagerEye.configuration.excluded_paths.any? do |pattern|
+        File.fnmatch?(pattern, file_path, File::FNM_PATHNAME)
+      end
+    end
+
+    def analyze_file(file_path)
+      source = File.read(file_path)
+      ast = parse_source(source)
+      return unless ast
+
+      enabled_detectors.each do |detector|
+        file_issues = detector.detect(ast, file_path)
+        @issues.concat(file_issues)
+      end
+    rescue Errno::ENOENT, Errno::EACCES => e
+      warn "EagerEye: Could not read file #{file_path}: #{e.message}"
+    end
+
+    def parse_source(source)
+      Parser::CurrentRuby.parse(source)
+    rescue Parser::SyntaxError
+      nil
+    end
+
+    def enabled_detectors
+      @enabled_detectors ||= EagerEye.configuration.enabled_detectors.filter_map do |name|
+        detector_class = DETECTOR_CLASSES[name]
+        detector_class&.new
+      end
+    end
+  end
+end

data/lib/eager_eye/cli.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module EagerEye
+  class CLI
+    attr_reader :argv, :options
+
+    def initialize(argv = ARGV)
+      @argv = argv
+      @options = default_options
+    end
+
+    def run
+      parse_options!
+      return 0 if options[:help] || options[:version]
+
+      issues = analyze
+      output_report(issues)
+      exit_code(issues)
+    end
+
+    private
+
+    def default_options
+      {
+        paths: [],
+        format: :console,
+        exclude: [],
+        only: [],
+        fail_on_issues: true,
+        colorize: $stdout.tty?,
+        help: false,
+        version: false
+      }
+    end
+
+    def parse_options!
+      parser.parse!(argv)
+      options[:paths] = argv.empty? ? [EagerEye.configuration.app_path] : argv
+    rescue OptionParser::InvalidOption => e
+      warn "Error: #{e.message}"
+      warn parser
+      exit 1
+    end
+
+    def parser
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = "Usage: eager_eye [options] [paths...]"
+        opts.separator ""
+        opts.separator "Options:"
+
+        opts.on("-f", "--format FORMAT", %i[console json], "Output format (console, json)") do |format|
+          options[:format] = format
+        end
+
+        opts.on("-e", "--exclude PATTERN", "Exclude files matching pattern (can be used multiple times)") do |pattern|
+          options[:exclude] << pattern
+        end
+
+        opts.on("-o", "--only DETECTORS", "Run only specified detectors (comma-separated)") do |detectors|
+          options[:only] = detectors.split(",").map(&:strip).map(&:to_sym)
+        end
+
+        opts.on("--no-fail", "Exit with 0 even if issues found") do
+          options[:fail_on_issues] = false
+        end
+
+        opts.on("--no-color", "Disable colored output") do
+          options[:colorize] = false
+        end
+
+        opts.on("-v", "--version", "Show version") do
+          puts "EagerEye #{EagerEye::VERSION}"
+          options[:version] = true
+        end
+
+        opts.on("-h", "--help", "Show this help message") do
+          puts opts
+          options[:help] = true
+        end
+      end
+    end
+
+    def analyze
+      configure_from_options!
+
+      analyzer = Analyzer.new(paths: options[:paths])
+      analyzer.run
+    end
+
+    def configure_from_options!
+      EagerEye.configure do |config|
+        config.excluded_paths += options[:exclude]
+        config.enabled_detectors = options[:only] unless options[:only].empty?
+      end
+    end
+
+    def output_report(issues)
+      reporter = create_reporter(issues)
+      puts reporter.report
+    end
+
+    def create_reporter(issues)
+      case options[:format]
+      when :json
+        Reporters::Json.new(issues, pretty: true)
+      else
+        Reporters::Console.new(issues, colorize: options[:colorize])
+      end
+    end
+
+    def exit_code(issues)
+      return 0 unless options[:fail_on_issues]
+      return 0 if issues.empty?
+
+      1
+    end
+  end
+end

data/lib/eager_eye/configuration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module EagerEye
+  class Configuration
+    attr_accessor :excluded_paths, :enabled_detectors, :app_path, :fail_on_issues
+
+    DEFAULT_DETECTORS = %i[loop_association serializer_nesting missing_counter_cache].freeze
+
+    def initialize
+      @excluded_paths = []
+      @enabled_detectors = DEFAULT_DETECTORS.dup
+      @app_path = "app"
+      @fail_on_issues = true
+    end
+  end
+end

data/lib/eager_eye/detectors/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "parser/current"
+
+module EagerEye
+  module Detectors
+    class Base
+      class << self
+        def detector_name
+          raise NotImplementedError, "Subclasses must implement .detector_name"
+        end
+      end
+
+      def detect(_ast, _file_path)
+        raise NotImplementedError, "Subclasses must implement #detect"
+      end
+
+      protected
+
+      def create_issue(file_path:, line_number:, message:, severity: :warning, suggestion: nil)
+        Issue.new(
+          detector: self.class.detector_name,
+          file_path: file_path,
+          line_number: line_number,
+          message: message,
+          severity: severity,
+          suggestion: suggestion
+        )
+      end
+
+      def traverse_ast(node, &block)
+        return unless node.is_a?(Parser::AST::Node)
+
+        yield node
+
+        node.children.each do |child|
+          traverse_ast(child, &block)
+        end
+      end
+
+      def parse_source(source)
+        Parser::CurrentRuby.parse(source)
+      rescue Parser::SyntaxError
+        nil
+      end
+    end
+  end
+end

data/lib/eager_eye/detectors/loop_association.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module EagerEye
+  module Detectors
+    class LoopAssociation < Base
+      ITERATION_METHODS = %i[each map collect select find find_all reject filter filter_map flat_map].freeze
+
+      # Common singular association names (belongs_to pattern)
+      SINGULAR_ASSOCIATIONS = %w[
+        author user owner creator admin member customer client
+        post article comment category tag parent company organization
+        project task item order product account profile setting
+        image avatar photo attachment document
+      ].freeze
+
+      # Common plural association names (has_many pattern)
+      PLURAL_ASSOCIATIONS = %w[
+        authors users owners creators admins members customers clients
+        posts articles comments categories tags children companies organizations
+        projects tasks items orders products accounts profiles settings
+        images avatars photos attachments documents
+      ].freeze
+
+      # Methods that should NOT be treated as associations
+      EXCLUDED_METHODS = %i[
+        id to_s to_h to_a to_json to_xml inspect class object_id
+        nil? blank? present? empty? any? none? size count length
+        save save! update update! destroy destroy! delete delete!
+        valid? invalid? errors new? persisted? changed? frozen?
+        name title body content text description value key type status state
+        created_at updated_at deleted_at
+      ].freeze
+
+      def self.detector_name
+        :loop_association
+      end
+
+      def detect(ast, file_path)
+        return [] unless ast
+
+        issues = []
+
+        traverse_ast(ast) do |node|
+          next unless iteration_block?(node)
+
+          block_var = extract_block_variable(node)
+          next unless block_var
+
+          block_body = node.children[2]
+          next unless block_body
+
+          find_association_calls(block_body, block_var, file_path, issues)
+        end
+
+        issues
+      end
+
+      private
+
+      def iteration_block?(node)
+        return false unless node.type == :block
+
+        send_node = node.children[0]
+        return false unless send_node&.type == :send
+
+        method_name = send_node.children[1]
+        ITERATION_METHODS.include?(method_name)
+      end
+
+      def extract_block_variable(block_node)
+        args_node = block_node.children[1]
+        return nil unless args_node&.type == :args
+        return nil if args_node.children.empty?
+
+        first_arg = args_node.children[0]
+        return nil unless first_arg&.type == :arg
+
+        first_arg.children[0]
+      end
+
+      def find_association_calls(node, block_var, file_path, issues)
+        reported_associations = Set.new
+
+        traverse_ast(node) do |child|
+          next unless child.type == :send
+
+          receiver = child.children[0]
+          method_name = child.children[1]
+
+          # Only detect direct calls on block variable (post.author, not post.author.name)
+          next unless direct_call_on_block_var?(receiver, block_var)
+          next unless likely_association?(method_name)
+
+          # Avoid duplicate reports for same association on same line
+          report_key = "#{child.loc.line}:#{method_name}"
+          next if reported_associations.include?(report_key)
+
+          reported_associations << report_key
+
+          issues << create_issue(
+            file_path: file_path,
+            line_number: child.loc.line,
+            message: "Potential N+1 query: `#{block_var}.#{method_name}` called inside iteration",
+            suggestion: "Consider using `includes(:#{method_name})` on the collection before iterating"
+          )
+        end
+      end
+
+      def direct_call_on_block_var?(receiver, block_var)
+        return false unless receiver
+
+        receiver.type == :lvar && receiver.children[0] == block_var
+      end
+
+      def likely_association?(method_name)
+        return false if EXCLUDED_METHODS.include?(method_name)
+
+        name = method_name.to_s
+
+        SINGULAR_ASSOCIATIONS.include?(name) || PLURAL_ASSOCIATIONS.include?(name)
+      end
+    end
+  end
+end

data/lib/eager_eye/detectors/missing_counter_cache.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module EagerEye
+  module Detectors
+    class MissingCounterCache < Base
+      # Methods that trigger COUNT queries
+      COUNT_METHODS = %i[count size length].freeze
+
+      # Common has_many association names (plural)
+      PLURAL_ASSOCIATIONS = %w[
+        posts comments tags categories articles users members
+        items orders products tasks projects images attachments
+        documents files messages notifications reviews ratings
+        followers followings likes favorites bookmarks votes
+        children replies responses answers questions
+      ].freeze
+
+      def self.detector_name
+        :missing_counter_cache
+      end
+
+      def detect(ast, file_path)
+        return [] unless ast
+
+        issues = []
+
+        traverse_ast(ast) do |node|
+          next unless count_on_association?(node)
+
+          association_name = extract_association_name(node)
+          next unless association_name
+
+          issues << create_issue(
+            file_path: file_path,
+            line_number: node.loc.line,
+            message: "`.#{node.children[1]}` called on `#{association_name}` may cause N+1 queries",
+            suggestion: "Consider adding `counter_cache: true` to the belongs_to association"
+          )
+        end
+
+        issues
+      end
+
+      private
+
+      def count_on_association?(node)
+        return false unless node.type == :send
+
+        method_name = node.children[1]
+        return false unless COUNT_METHODS.include?(method_name)
+
+        receiver = node.children[0]
+        return false unless receiver
+
+        likely_association_receiver?(receiver)
+      end
+
+      def likely_association_receiver?(node)
+        return false unless node.type == :send
+
+        method_name = node.children[1]
+        PLURAL_ASSOCIATIONS.include?(method_name.to_s)
+      end
+
+      def extract_association_name(node)
+        receiver = node.children[0]
+        return nil unless receiver&.type == :send
+
+        receiver.children[1].to_s
+      end
+    end
+  end
+end

data/lib/eager_eye/detectors/serializer_nesting.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module EagerEye
+  module Detectors
+    class SerializerNesting < Base
+      # Serializer base classes to detect
+      SERIALIZER_PATTERNS = [
+        "ActiveModel::Serializer",
+        "ActiveModelSerializers::Model",
+        "Blueprinter::Base",
+        "Alba::Resource"
+      ].freeze
+
+      # Method names that define attributes in serializers
+      ATTRIBUTE_METHODS = %i[attribute field attributes].freeze
+
+      # Object reference names in serializers
+      OBJECT_REFS = %i[object record resource].freeze
+
+      # Common association names (same as LoopAssociation)
+      ASSOCIATION_NAMES = %w[
+        author user owner creator admin member customer client
+        post article comment category tag parent company organization
+        project task item order product account profile setting
+        image avatar photo attachment document
+        authors users owners creators admins members customers clients
+        posts articles comments categories tags children companies organizations
+        projects tasks items orders products accounts profiles settings
+        images avatars photos attachments documents
+      ].freeze
+
+      def self.detector_name
+        :serializer_nesting
+      end
+
+      def detect(ast, file_path)
+        return [] unless ast
+
+        issues = []
+
+        traverse_ast(ast) do |node|
+          next unless serializer_class?(node)
+
+          find_nested_associations(node, file_path, issues)
+        end
+
+        issues
+      end
+
+      private
+
+      def serializer_class?(node)
+        return false unless node.type == :class
+
+        # Check class name ends with Serializer, Blueprint, or Resource
+        class_name = extract_class_name(node)
+        return false unless class_name
+
+        class_name.end_with?("Serializer", "Blueprint", "Resource") ||
+          inherits_from_serializer?(node) ||
+          includes_serializer_module?(node)
+      end
+
+      def extract_class_name(class_node)
+        name_node = class_node.children[0]
+        return nil unless name_node
+        return nil unless name_node.type == :const
+
+        name_node.children[1].to_s
+      end
+
+      def inherits_from_serializer?(class_node)
+        parent_node = class_node.children[1]
+        return false unless parent_node
+
+        parent_name = const_to_string(parent_node)
+        SERIALIZER_PATTERNS.any? { |pattern| parent_name&.include?(pattern.split("::").last) }
+      end
+
+      def includes_serializer_module?(class_node)
+        body = class_node.children[2]
+        return false unless body
+
+        traverse_ast(body) do |node|
+          next unless node.type == :send
+
+          method = node.children[1]
+          return true if method == :include && alba_resource?(node)
+        end
+
+        false
+      end
+
+      def alba_resource?(include_node)
+        arg = include_node.children[2]
+        return false unless arg
+
+        const_to_string(arg)&.include?("Alba")
+      end
+
+      def const_to_string(node)
+        return nil unless node&.type == :const
+
+        parts = []
+        current = node
+
+        while current&.type == :const
+          parts.unshift(current.children[1].to_s)
+          current = current.children[0]
+        end
+
+        parts.join("::")
+      end
+
+      def find_nested_associations(class_node, file_path, issues)
+        body = class_node.children[2]
+        return unless body
+
+        traverse_ast(body) do |node|
+          next unless attribute_block?(node)
+
+          block_body = node.children[2]
+          next unless block_body
+
+          find_association_in_block(block_body, node, file_path, issues)
+        end
+      end
+
+      def attribute_block?(node)
+        return false unless node.type == :block
+
+        send_node = node.children[0]
+        return false unless send_node&.type == :send
+
+        method_name = send_node.children[1]
+        ATTRIBUTE_METHODS.include?(method_name)
+      end
+
+      def find_association_in_block(block_body, _block_node, file_path, issues)
+        traverse_ast(block_body) do |node|
+          next unless node.type == :send
+
+          receiver = node.children[0]
+          method_name = node.children[1]
+
+          next unless object_reference?(receiver)
+          next unless likely_association?(method_name)
+
+          issues << create_issue(
+            file_path: file_path,
+            line_number: node.loc.line,
+            message: "Nested association `#{receiver_name(receiver)}.#{method_name}` in serializer attribute",
+            suggestion: "Eager load :#{method_name} in controller or use association serializer"
+          )
+        end
+      end
+
+      def object_reference?(node)
+        return false unless node
+
+        case node.type
+        when :send
+          # object.something or record.something
+          receiver = node.children[0]
+          method = node.children[1]
+
+          receiver.nil? && OBJECT_REFS.include?(method)
+        when :lvar
+          # Block variable like |post|
+          true
+        else
+          false
+        end
+      end
+
+      def receiver_name(node)
+        case node.type
+        when :send
+          node.children[1].to_s
+        when :lvar
+          node.children[0].to_s
+        else
+          "object"
+        end
+      end
+
+      def likely_association?(method_name)
+        ASSOCIATION_NAMES.include?(method_name.to_s)
+      end
+    end
+  end
+end

data/lib/eager_eye/generators/install_generator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module EagerEye
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Creates an EagerEye configuration file"
+
+      def create_config_file
+        create_file ".eager_eye.yml", config_content
+      end
+
+      private
+
+      def config_content
+        <<~YAML
+          # EagerEye Configuration
+          # See https://github.com/hamzagedikkaya/eager_eye for documentation
+
+          # Paths to exclude from analysis (glob patterns)
+          excluded_paths:
+            # - app/serializers/legacy/**
+            # - lib/tasks/**
+
+          # Detectors to enable (default: all)
+          enabled_detectors:
+            - loop_association
+            - serializer_nesting
+            - missing_counter_cache
+
+          # Base path to analyze (default: app)
+          app_path: app
+
+          # Exit with error code when issues found (default: true)
+          fail_on_issues: true
+        YAML
+      end
+    end
+  end
+end