eager_eye 1.0.7 → 1.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f19a4d72ee31d2ea100782d4fd9da6594db5f9ec78e9290723461441f58e264d
-  data.tar.gz: d8b347ecb77010db7ebff3db74610de1516c653991d7264321f302d2b3eaf0ea
+  metadata.gz: 44b2f46a77bcc0bb742c6d169cebb7be6b9a8b722b64044b153397fcf7686872
+  data.tar.gz: 25a589c3401fe25248b6fe429e0255e5d2d9ada9b50bd7bbf467ada161e0ca95
 SHA512:
-  metadata.gz: 6e676774f31b89d5a6948dda61c18e6c08a522f83c224d796a16dc954f3ae2fd6ef63e91bb1d4e9afe652ab4447538af5e521875bc2544833cabf429549582ff
-  data.tar.gz: a6bde55b11a3cb95f2550ddd5592b855e2ed6accd36abf3e1fb33f00ba34343291e0eab1a17253de95990c876a9119d15ef1b9e2548cc706e7dea0c6c446a510
+  metadata.gz: 2ea1baa8c98a5362527e991d3712c0a3c0d821307a99e1b8b1a9a0ac76fbff5d4adcf4f4cd512990971956fcc3bd61ef97fb8c047d0b44609e4bd55ca385bfb4
+  data.tar.gz: 8d1590b243420e3ea3534290f15725a0aa70f3ea537aa7da05cd4648521fe284718965d27e4b00ac77ea277d4ca400107e49a18a7759780dd532c560ef1b91b3

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.9] - 2025-12-26
+
+### Added
+
+- **Inline Suppression Comments** - Suppress specific warnings with RuboCop-style inline comments
+  - `# eager_eye:disable-next-line` - Suppress next line
+  - `# eager_eye:disable CallbackQuery` - Suppress specific detector inline
+  - `# eager_eye:disable-block` / `# eager_eye:enable-block` - Suppress block of code
+  - `# eager_eye:disable-file DetectorName` - Suppress entire file
+  - Supports both CamelCase and snake_case detector names
+  - Can disable all detectors with `all` keyword
+
+### Improved
+
+- Enhanced README with table of contents and better organization
+- Improved code readability and documentation structure
+- Updated version badge to v1.0.9
+
+## [1.0.8] - 2025-12-25
+
+### Added
+
+- **Severity Levels** - error/warning/info with `--min-severity` filtering
+  - Defaults: `loop_association`=error, `missing_counter_cache`=info, others=warning
+  - Configurable via `.eager_eye.yml` (`severity_levels`, `min_severity`)
+
 ## [1.0.7] - 2025-12-24
 
 ### Fixed

data/README.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <a href="https://github.com/hamzagedikkaya/eager_eye/actions/workflows/main.yml"><img src="https://github.com/hamzagedikkaya/eager_eye/actions/workflows/main.yml/badge.svg" alt="CI"></a>
-  <a href="https://rubygems.org/gems/eager_eye"><img src="https://img.shields.io/badge/gem-v1.0.7-red.svg" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/eager_eye"><img src="https://img.shields.io/badge/gem-v1.0.9-red.svg" alt="Gem Version"></a>
   <a href="https://github.com/hamzagedikkaya/eager_eye"><img src="https://img.shields.io/badge/coverage-95%25-brightgreen.svg" alt="Coverage"></a>
   <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg" alt="Ruby"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
@@ -23,6 +23,24 @@
 
 ---
 
+## Table of Contents
+- [Why EagerEye?](#why-eagereye)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Detected Issues](#detected-issues)
+- [Inline Suppression](#inline-suppression)
+- [Auto-fix](#auto-fix-experimental)
+- [RSpec Integration](#rspec-integration)
+- [Configuration](#configuration)
+- [CI Integration](#ci-integration)
+- [CLI Reference](#cli-reference)
+- [Output Formats](#output-formats)
+- [Limitations](#limitations)
+- [VS Code Extension](#vs-code-extension)
+- [Development](#development)
+- [Contributing](#contributing)
+
 ## Why EagerEye?
 
 Unlike runtime tools like Bullet, EagerEye:
@@ -41,6 +59,28 @@ Unlike runtime tools like Bullet, EagerEye:
 | CI integration | Native | Requires tests |
 | False positive rate | Higher | Lower |
 
+## Features
+
+✨ **Detects 7 types of N+1 problems:**
+- Loop associations (queries in iterations)
+- Serializer nesting issues
+- Missing counter caches
+- Custom method queries (invisible to Bullet)
+- Count in iteration patterns
+- Callback query N+1s
+- Pluck to array misuse
+
+🔧 **Developer-friendly:**
+- Inline suppression (like RuboCop)
+- Auto-fix support (experimental)
+- JSON/Console output formats
+- RSpec integration
+
+🚀 **CI-ready:**
+- No test suite required
+- GitHub Actions examples included
+- Severity levels and filtering
+
 ## Installation
 
 Add to your Gemfile:
@@ -457,6 +497,19 @@ enabled_detectors:
   - callback_query
   - pluck_to_array
 
+# Severity levels per detector (error, warning, info)
+severity_levels:
+  loop_association: error        # Definite N+1
+  serializer_nesting: warning
+  custom_method_query: warning
+  count_in_iteration: warning
+  callback_query: warning
+  pluck_to_array: warning        # Optimization
+  missing_counter_cache: info    # Suggestion
+
+# Minimum severity to report (default: info)
+min_severity: warning
+
 # Base path to analyze (default: app)
 app_path: app
 
@@ -470,6 +523,8 @@ fail_on_issues: true
 EagerEye.configure do |config|
   config.excluded_paths = ["app/legacy/**"]
   config.enabled_detectors = [:loop_association, :serializer_nesting]
+  config.severity_levels = { loop_association: :error, missing_counter_cache: :info }
+  config.min_severity = :warning
   config.app_path = "app"
   config.fail_on_issues = true
 end
@@ -512,6 +567,7 @@ Options:
     -f, --format FORMAT      Output format: console, json (default: console)
     -e, --exclude PATTERN    Exclude files matching pattern (can be used multiple times)
     -o, --only DETECTORS     Run only specified detectors (comma-separated)
+    -s, --min-severity LEVEL Minimum severity to report (info, warning, error)
         --no-fail            Exit with 0 even when issues are found
         --no-color           Disable colored output
     -v, --version            Show version

data/lib/eager_eye/analyzer.rb

@@ -68,6 +68,10 @@ module EagerEye
           comment_parser.disabled_at?(issue.line_number, issue.detector)
         end
 
+        # Filter by minimum severity
+        min_severity = EagerEye.configuration.min_severity
+        file_issues.select! { |issue| issue.meets_minimum_severity?(min_severity) }
+
         @issues.concat(file_issues)
       end
     rescue Errno::ENOENT, Errno::EACCES => e

data/lib/eager_eye/cli.rb

@@ -41,6 +41,7 @@ module EagerEye
         format: :console,
         exclude: [],
         only: [],
+        min_severity: nil,
         fail_on_issues: true,
         colorize: $stdout.tty?,
         help: false,
@@ -92,6 +93,11 @@ module EagerEye
       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("-s", "--min-severity LEVEL", %i[info warning error],
+              "Minimum severity to report (info, warning, error)") do |level|
+        options[:min_severity] = level
+      end
     end
 
     def add_behavior_options(opts)
@@ -140,6 +146,7 @@ module EagerEye
       EagerEye.configure do |config|
         config.excluded_paths += options[:exclude]
         config.enabled_detectors = options[:only] unless options[:only].empty?
+        config.min_severity = options[:min_severity] if options[:min_severity]
       end
     end
 

data/lib/eager_eye/comment_parser.rb

@@ -2,12 +2,12 @@
 
 module EagerEye
   class CommentParser
-    DISABLE_PATTERN = /eager_eye:disable(?:-next-line|-file)?\s+(.+?)(?:\s+--|$)/i
-    ENABLE_PATTERN = /eager_eye:enable\s+(.+?)(?:\s+--|$)/i
-    INLINE_DISABLE_PATTERN = /eager_eye:disable\s+(.+?)(?:\s+--|$)/i
     FILE_DISABLE_PATTERN = /eager_eye:disable-file\s+(.+?)(?:\s+--|$)/i
-    NEXT_LINE_PATTERN = /eager_eye:disable-next-line\s+(.+?)(?:\s+--|$)/i
-    BLOCK_DISABLE_PATTERN = /eager_eye:disable\s+(.+?)(?:\s+--|$)/i
+    NEXT_LINE_PATTERN = /eager_eye:disable-next-line(?:\s+(.+?))?(?:\s+--|$)/i
+    BLOCK_START_PATTERN = /eager_eye:disable-block(?:\s+(.+?))?(?:\s+--|$)/i
+    BLOCK_END_PATTERN = /eager_eye:enable-block(?:\s+(.+?))?(?:\s+--|$)/i
+    INLINE_DISABLE_PATTERN = /eager_eye:disable\s+(.+?)(?:\s+--|$)/i
+    ENABLE_PATTERN = /eager_eye:enable(?:\s+(.+?))?(?:\s+--|$)/i
 
     def initialize(source_code)
       @source_code = source_code.encode("UTF-8", invalid: :replace, undef: :replace)
@@ -46,39 +46,50 @@ module EagerEye
     def detect_directive(line, line_num)
       detect_file_directive(line, line_num) ||
         detect_next_line_directive(line) ||
-        detect_block_directive(line) ||
-        detect_enable_directive(line) ||
-        detect_inline_directive(line)
+        detect_block_end_directive(line) ||
+        detect_block_or_inline_directive(line)
     end
 
     def detect_file_directive(line, line_num)
       return unless line_num <= 5 && line =~ FILE_DISABLE_PATTERN
 
-      { type: :file, detectors: parse_detector_names(::Regexp.last_match(1)) }
+      detectors = parse_detector_names(::Regexp.last_match(1) || "all")
+      { type: :file, detectors: detectors }
     end
 
     def detect_next_line_directive(line)
       return unless line =~ NEXT_LINE_PATTERN
 
-      { type: :next_line, detectors: parse_detector_names(::Regexp.last_match(1)) }
+      detectors = parse_detector_names(::Regexp.last_match(1) || "all")
+      { type: :next_line, detectors: detectors }
     end
 
-    def detect_block_directive(line)
-      return unless line =~ BLOCK_DISABLE_PATTERN && !inline_disable?(line)
-
-      { type: :block_start, detectors: parse_detector_names(::Regexp.last_match(1)) }
-    end
-
-    def detect_enable_directive(line)
+    def detect_block_end_directive(line)
       return unless line =~ ENABLE_PATTERN
 
-      { type: :block_end, detectors: parse_detector_names(::Regexp.last_match(1)) }
+      detectors = parse_detector_names(::Regexp.last_match(1) || "all")
+      { type: :block_end, detectors: detectors }
     end
 
-    def detect_inline_directive(line)
+    def detect_block_or_inline_directive(line)
+      # Check for eager_eye:disable-block explicitly
+      if line =~ BLOCK_START_PATTERN && !code_before_comment?(line)
+        detectors = parse_detector_names(::Regexp.last_match(1) || "all")
+        return { type: :block_start, detectors: detectors }
+      end
+
+      # Check for eager_eye:disable (either inline or block start)
       return unless line =~ INLINE_DISABLE_PATTERN
 
-      { type: :inline, detectors: parse_detector_names(::Regexp.last_match(1)) }
+      detectors = parse_detector_names(::Regexp.last_match(1) || "all")
+
+      # If there's code before the comment, it's inline (same line only)
+      if code_before_comment?(line)
+        { type: :inline, detectors: detectors }
+      else
+        # No code before comment, so it's a block start
+        { type: :block_start, detectors: detectors }
+      end
     end
 
     def apply_directive(directive, line_num)
@@ -129,7 +140,14 @@ module EagerEye
       code_part && !code_part.strip.empty?
     end
 
+    def code_before_comment?(line)
+      code_part = line.split("#").first
+      code_part && !code_part.strip.empty?
+    end
+
     def parse_detector_names(str)
+      return ["all"] if str.nil? || str.strip.empty?
+
       str.split(/[,\s]+/).map(&:strip).reject(&:empty?).map do |name|
         normalize_detector_name(name)
       end

data/lib/eager_eye/configuration.rb

@@ -2,7 +2,8 @@
 
 module EagerEye
   class Configuration
-    attr_accessor :excluded_paths, :enabled_detectors, :app_path, :fail_on_issues
+    attr_accessor :excluded_paths, :enabled_detectors, :app_path, :fail_on_issues,
+                  :severity_levels, :min_severity
 
     DEFAULT_DETECTORS = %i[
       loop_association serializer_nesting missing_counter_cache
@@ -10,11 +11,33 @@ module EagerEye
       pluck_to_array
     ].freeze
 
+    DEFAULT_SEVERITY_LEVELS = {
+      loop_association: :error,
+      serializer_nesting: :warning,
+      missing_counter_cache: :info,
+      custom_method_query: :warning,
+      count_in_iteration: :warning,
+      callback_query: :warning,
+      pluck_to_array: :warning
+    }.freeze
+
+    VALID_SEVERITIES = %i[info warning error].freeze
+
     def initialize
       @excluded_paths = []
       @enabled_detectors = DEFAULT_DETECTORS.dup
       @app_path = "app"
       @fail_on_issues = true
+      @severity_levels = DEFAULT_SEVERITY_LEVELS.dup
+      @min_severity = :info
+    end
+
+    def severity_for(detector_name)
+      severity_levels.fetch(detector_name.to_sym, :warning)
+    end
+
+    def valid_severity?(severity)
+      VALID_SEVERITIES.include?(severity.to_sym)
     end
   end
 end

data/lib/eager_eye/detectors/base.rb

@@ -9,6 +9,10 @@ module EagerEye
         def detector_name
           raise NotImplementedError, "Subclasses must implement .detector_name"
         end
+
+        def default_severity
+          :warning
+        end
       end
 
       def detect(_ast, _file_path)
@@ -17,17 +21,22 @@ module EagerEye
 
       protected
 
-      def create_issue(file_path:, line_number:, message:, severity: :warning, suggestion: nil)
+      def create_issue(file_path:, line_number:, message:, severity: nil, suggestion: nil)
+        resolved_severity = severity || configured_severity
         Issue.new(
           detector: self.class.detector_name,
           file_path: file_path,
           line_number: line_number,
           message: message,
-          severity: severity,
+          severity: resolved_severity,
           suggestion: suggestion
         )
       end
 
+      def configured_severity
+        EagerEye.configuration.severity_for(self.class.detector_name)
+      end
+
       def traverse_ast(node, &block)
         return unless node.is_a?(Parser::AST::Node)
 

data/lib/eager_eye/detectors/count_in_iteration.rb

@@ -128,7 +128,6 @@ module EagerEye
           file_path: @file_path,
           line_number: node.loc.line,
           message: "`.count` called on `#{receiver_chain}` inside iteration always executes a COUNT query",
-          severity: :warning,
           suggestion: "Use `.size` instead (uses loaded collection) or add `counter_cache: true`"
         )
       end

data/lib/eager_eye/detectors/custom_method_query.rb

@@ -165,7 +165,6 @@ module EagerEye
           file_path: @file_path,
           line_number: node.loc.line,
           message: "Query method `.#{method_name}` called on `#{association_chain}` inside iteration",
-          severity: :warning,
           suggestion: "This query executes on each iteration. Consider preloading data or restructuring the query."
         )
       end

data/lib/eager_eye/detectors/pluck_to_array.rb

@@ -140,7 +140,6 @@ module EagerEye
           file_path: @file_path,
           line_number: node.loc.line,
           message: "Using plucked/mapped array in `where` causes two queries and holds IDs in memory",
-          severity: :warning,
           suggestion: "Use `.select(:id)` subquery: `Model.where(col: OtherModel.condition.select(:id))`"
         )
       end

data/lib/eager_eye/issue.rb

@@ -4,7 +4,8 @@ module EagerEye
   class Issue
     attr_reader :detector, :file_path, :line_number, :message, :severity, :suggestion
 
-    VALID_SEVERITIES = %i[warning error].freeze
+    VALID_SEVERITIES = %i[info warning error].freeze
+    SEVERITY_ORDER = { info: 0, warning: 1, error: 2 }.freeze
 
     def initialize(detector:, file_path:, line_number:, message:, severity: :warning, suggestion: nil)
       @detector = detector
@@ -15,6 +16,14 @@ module EagerEye
       @suggestion = suggestion
     end
 
+    def severity_level
+      SEVERITY_ORDER[severity]
+    end
+
+    def meets_minimum_severity?(min_severity)
+      severity_level >= SEVERITY_ORDER.fetch(min_severity, 0)
+    end
+
     def to_h
       {
         detector: detector,

data/lib/eager_eye/reporters/base.rb

@@ -19,6 +19,10 @@ module EagerEye
         issues.group_by(&:file_path)
       end
 
+      def info_count
+        issues.count { |i| i.severity == :info }
+      end
+
       def warning_count
         issues.count { |i| i.severity == :warning }
       end

data/lib/eager_eye/reporters/console.rb

@@ -61,7 +61,7 @@ module EagerEye
 
       def format_issue(issue)
         detector_label = format_detector(issue.detector)
-        severity_color = issue.severity == :error ? :red : :yellow
+        severity_color = severity_to_color(issue.severity)
 
         line = "  Line #{issue.line_number}: "
         line += colorize("[#{detector_label}]", severity_color)
@@ -72,18 +72,24 @@ module EagerEye
         line
       end
 
+      def severity_to_color(severity)
+        { error: :red, warning: :yellow, info: :cyan }.fetch(severity, :yellow)
+      end
+
       def format_detector(detector)
         detector.to_s.split("_").map(&:capitalize).join
       end
 
       def summary
         total = issues.size
-        warnings = warning_count
         errors = error_count
+        warnings = warning_count
+        infos = info_count
 
         "Total: #{total} issue#{"s" unless total == 1} " \
-          "(#{warnings} warning#{"s" unless warnings == 1}, " \
-          "#{errors} error#{"s" unless errors == 1})"
+          "(#{errors} error#{"s" unless errors == 1}, " \
+          "#{warnings} warning#{"s" unless warnings == 1}, " \
+          "#{infos} info)"
       end
 
       def colorize(text, color)

data/lib/eager_eye/reporters/json.rb

@@ -24,8 +24,9 @@ module EagerEye
       def summary_hash
         {
           total: issues.size,
-          warnings: warning_count,
           errors: error_count,
+          warnings: warning_count,
+          infos: info_count,
           files_affected: issues_by_file.keys.size
         }
       end

data/lib/eager_eye/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EagerEye
-  VERSION = "1.0.7"
+  VERSION = "1.0.9"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eager_eye
 version: !ruby/object:Gem::Version
-  version: 1.0.7
+  version: 1.0.9
 platform: ruby
 authors:
 - hamzagedikkaya
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-24 00:00:00.000000000 Z
+date: 2025-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ast
@@ -56,9 +56,7 @@ files:
 - README.md
 - Rakefile
 - SECURITY.md
-- examples/github_action.yml
 - exe/eager_eye
-- images/icon.png
 - lib/eager_eye.rb
 - lib/eager_eye/analyzer.rb
 - lib/eager_eye/auto_fixer.rb

data/examples/github_action.yml

@@ -1,75 +0,0 @@
-# Example GitHub Action workflow for using EagerEye in your Rails project
-# Copy this file to .github/workflows/eager_eye.yml in your repository
-
-name: EagerEye N+1 Analysis
-
-on:
-  pull_request:
-    paths:
-      - "app/**/*.rb"
-      - "lib/**/*.rb"
-
-jobs:
-  analyze:
-    runs-on: ubuntu-latest
-    name: N+1 Query Detection
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: "3.3"
-
-      - name: Install EagerEye
-        run: gem install eager_eye
-
-      - name: Run EagerEye analysis
-        run: eager_eye app/ --format json > eager_eye_report.json
-        continue-on-error: true
-
-      - name: Upload report artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: eager-eye-report
-          path: eager_eye_report.json
-
-      - name: Check for N+1 issues
-        run: |
-          if [ -f eager_eye_report.json ]; then
-            issues=$(cat eager_eye_report.json | ruby -rjson -e 'puts JSON.parse(STDIN.read)["summary"]["total_issues"]')
-            if [ "$issues" -gt 0 ]; then
-              echo "::warning::EagerEye detected $issues potential N+1 query issue(s)"
-              cat eager_eye_report.json | ruby -rjson -e '
-                data = JSON.parse(STDIN.read)
-                data["issues"].each do |issue|
-                  puts "::warning file=#{issue["file_path"]},line=#{issue["line_number"]}::#{issue["message"]}"
-                end
-              '
-            else
-              echo "No N+1 query issues detected!"
-            fi
-          fi
-
-  # Alternative: Strict mode that fails the build on issues
-  analyze-strict:
-    runs-on: ubuntu-latest
-    name: N+1 Query Detection (Strict)
-    if: false  # Set to true to enable strict mode
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: "3.3"
-
-      - name: Install EagerEye
-        run: gem install eager_eye
-
-      - name: Run EagerEye analysis (strict)
-        run: eager_eye app/ --no-color