eager_eye 1.2.15 → 1.3.0

data/README.md

@@ -1,87 +1,52 @@
 <p align="center">
-  <img src="images/icon.png" alt="EagerEye Logo" width="140">
+  <img src="images/icon.png" alt="EagerEye" width="140">
 </p>
 
 <h1 align="center">EagerEye</h1>
 
 <p align="center">
-  <strong>Static analysis tool for detecting N+1 queries in Rails applications.</strong>
+  <strong>Catch N+1 queries in your Rails app — without running it.</strong><br>
+  <sub>Static analysis powered by Ruby AST. Fast. Zero runtime overhead. CI-ready.</sub>
 </p>
 
 <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.2.15-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>
-  <a href="https://marketplace.visualstudio.com/items?itemName=hamzagedikkaya.eager-eye"><img src="https://img.shields.io/badge/VS%20Code-Extension-blue.svg" alt="VS Code Extension"></a>
+  <strong>English</strong> · <a href="README.tr.md">Türkçe</a>
 </p>
 
 <p align="center">
-  <em>Analyze your Ruby code without running it — find N+1 query issues before they hit production using AST parsing.</em>
+  <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/gem/v/eager_eye?color=red&label=gem" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/eager_eye"><img src="https://img.shields.io/gem/dt/eager_eye?color=blue&label=downloads" alt="Downloads"></a>
+  <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D" alt="Ruby"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/github/license/hamzagedikkaya/eager_eye" alt="License"></a>
+  <a href="https://marketplace.visualstudio.com/items?itemName=hamzagedikkaya.eager-eye"><img src="https://img.shields.io/badge/VS%20Code-Extension-007ACC?logo=visualstudiocode&logoColor=white" alt="VS Code Extension"></a>
 </p>
 
+> 💡 **Prefer in-editor warnings?** Install the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=hamzagedikkaya.eager-eye) — same engine, runs on save, surfaces issues right next to the offending line. Same speed as the CLI, just a smoother feedback loop.
+
 ---
 
-## Table of Contents
-- [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)
-
-## Features
-
-✨ **Detects 11 types of N+1 problems:**
-- Loop associations (queries in iterations)
-- Serializer nesting issues
-- Missing counter caches
-- Custom method queries
-- Count in iteration patterns
-- Callback query N+1s
-- Pluck to array misuse
-- Delegation N+1s (hidden via `delegate :method, to: :association`)
-- Decorator N+1s (Draper, SimpleDelegator, Presenter, ViewObject)
-- Scope chain N+1s (named scopes on associations in loops)
-- Validation N+1s (uniqueness validation in batch create/save)
-
-🔧 **Developer-friendly:**
-- Inline suppression (like RuboCop)
-- Auto-fix support (3 fixers: PluckToSelect, CountToSize, AddIncludes)
-- `.jbuilder` file support (`json.array!` iteration detection)
-- 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:
+## Why EagerEye?
+
+**Bullet** finds N+1s when your tests hit them. **EagerEye** finds them statically — before any code runs.
+
+- 🎯 **Catch what tests miss** — N+1s in code paths your test suite doesn't exercise still get flagged.
+- ⚡ **Run in CI on every PR** — no DB, no fixtures, no Rails boot. Just `eager_eye app/`.
+- 🔬 **11 detector types** — beyond simple loop access: serializer nesting, callback queries, decorator/delegation traps, batch validation, scope chains, plucked-array misuse, and more.
+- 🤝 **Plays well with Bullet** — static + runtime cover different blind spots. Use both.
+
+## Install
 
 ```ruby
+# Gemfile
 gem "eager_eye", group: :development
 ```
 
-Then run:
-
 ```bash
 bundle install
 ```
 
-Or install standalone:
+Or standalone:
 
 ```bash
 gem install eager_eye
@@ -89,477 +54,322 @@ gem install eager_eye
 
 ## Quick Start
 
-### CLI Usage
-
 ```bash
-# Analyze default app/ directory
+# Scan the default app/ directory
 eager_eye
 
-# Analyze specific paths
+# Or scan specific paths
 eager_eye app/controllers app/serializers
 
-# Output as JSON (for CI)
-eager_eye --format json
-
-# Don't fail on issues (exit 0)
-eager_eye --no-fail
-
-# Run specific detectors only
-eager_eye --only loop_association,serializer_nesting
+# Generate a config file (optional)
+rails g eager_eye:install
 
-# Exclude paths
-eager_eye --exclude "app/legacy/**"
+# Run via rake
+rake eager_eye:analyze
 ```
 
-### Rails Integration
+Sample output:
 
-```bash
-# Generate config file
-rails g eager_eye:install
+```text
+app/controllers/posts_controller.rb
+  Line 15: [LoopAssociation] Potential N+1 query: `post.author` called inside iteration
+           Suggestion: Use `includes(:author)` on the collection before iterating
 
-# Run via rake
-rake eager_eye:analyze
+  Line 23: [MissingCounterCache] `.count` called on `comments` may cause N+1 queries
+           Suggestion: Add `counter_cache: true` to the belongs_to association
 
-# JSON output
-rake eager_eye:json
+Total: 2 issues (2 warnings, 0 errors)
 ```
 
-## Detected Issues
+## What it detects
+
+| # | Detector | What it catches |
+|---|---|---|
+| 1 | **LoopAssociation** | Association calls inside `each`/`map`/`find_each`/etc. without preloading |
+| 2 | **SerializerNesting** | Nested association access in Blueprinter / ActiveModel::Serializer / Alba blocks |
+| 3 | **MissingCounterCache** | `.count` / `.size` on associations inside loops where a counter cache would help |
+| 4 | **CustomMethodQuery** | `.where`, `.find_by`, `.exists?` etc. on association chains inside iterations |
+| 5 | **CountInIteration** | `.count` (always queries) used in loops where `.size` (uses preload) would suffice |
+| 6 | **CallbackQuery** | Iteration-driven queries inside ActiveRecord callbacks (`after_save`, `after_create`, ...) |
+| 7 | **PluckToArray** | `.pluck(:id)` results passed to `where(id: ...)` instead of using a subquery; flags `.all.pluck` as critical |
+| 8 | **DelegationNPlusOne** | `delegate :method, to: :association` calls in loops where the target isn't preloaded |
+| 9 | **DecoratorNPlusOne** | Draper / SimpleDelegator / Presenter / ViewObject access without preload before `.decorate` |
+| 10 | **ScopeChainNPlusOne** | Named scopes (`.recent`, `.active`) on associations in loops — invisible query triggers |
+| 11 | **ValidationNPlusOne** | `Model.create`/`save` inside loops on models with `validates :x, uniqueness: true` |
 
-### 1. Loop Association (N+1 in iterations)
+EagerEye also tracks preloads across pagination wrappers (`pagy`, `paginate`, `kaminari`), per-method scope, multi-line builder chains, and helper-method parameters — so warnings respect the eager-loading you've already set up.
 
-Detects association calls inside loops that may cause N+1 queries.
+<details>
+<summary><b>Detailed examples for each detector →</b></summary>
+
+### 1. LoopAssociation
 
 ```ruby
-# Bad - N+1 query on each iteration
-posts.each do |post|
-  post.author.name      # Query for each post!
-  post.comments.count   # Another query for each post!
-end
+# Bad
+posts.each { |post| post.author.name }   # query per post
 
-# Good - Eager load associations (chained)
-posts.includes(:author, :comments).each do |post|
-  post.author.name      # No additional query
-  post.comments.count   # No additional query
-end
+# Good — chained
+posts.includes(:author).each { |post| post.author.name }
 
-# Good - Eager load on separate line (also detected correctly!)
+# Good — separate line (preload tracked across assignment)
 @posts = Post.includes(:author)
-@posts.each do |post|
-  post.author.name      # No warning - EagerEye tracks the preload
-end
-
-# Also works with preload and eager_load
-posts = Post.preload(:comments)
-posts.each { |post| post.comments.size }  # No warning
+@posts.each { |post| post.author.name }
 
-# Single record context - no N+1 possible (also detected correctly!)
+# Good — single record (no N+1 possible)
 @user = User.find(params[:id])
-@user.posts.each do |post|
-  post.comments  # No warning - single user, no N+1
-end
-
-# Scope-defined preloads are recognized (v1.1.0+)
-# In Post model:
-class Post < ApplicationRecord
-  has_many :comments, -> { includes(:author) }
-end
-
-# In controller - EagerEye recognizes comments are already preloaded via scope!
-posts.each do |post|
-  post.comments.map(&:author)  # No warning - preloaded via scope
-end
+@user.posts.each { |post| post.comments }
 ```
 
-### 2. Serializer Nesting (N+1 in serializers)
+Recognizes `.includes`, `.preload`, `.eager_load`, scoped `has_many` (`-> { includes(:author) }`), and pagination wrappers like `@pagy, items = pagy(...)`.
 
-Detects nested association access in serializer blocks.
+### 2. SerializerNesting
 
 ```ruby
-# Bad - N+1 in serializer
-class PostSerializer < ActiveModel::Serializer
-  attribute :author_name do
-    object.author.name  # Query for each serialized post!
-  end
+# Bad
+class PostSerializer < Blueprinter::Base
+  field :author_name { |post| post.author.name }   # query per serialized post
 end
 
-# Good - Eager load in controller
-class PostsController < ApplicationController
-  def index
-    @posts = Post.includes(:author)
-    render json: @posts, each_serializer: PostSerializer
-  end
-end
+# Good — preload in controller
+@posts = Post.includes(:author)
+render json: PostSerializer.render(@posts)
 ```
 
-Supports multiple serializer libraries:
-- ActiveModel::Serializers
-- Blueprinter
-- Alba
+Supports Blueprinter, ActiveModel::Serializers, Alba.
 
-### 3. Missing Counter Cache
-
-Detects `.count`, `.size`, or `.length` calls on associations **inside iterations** that could benefit from counter caches. Single calls outside loops are not flagged since they don't cause N+1 issues.
+### 3. MissingCounterCache
 
 ```ruby
-# Bad - COUNT query for each post in iteration
-posts.each do |post|
-  post.comments.count   # Detected: N+1 query!
-  post.likes.size       # Detected: N+1 query!
-end
+# Bad — COUNT query for each post
+posts.each { |post| post.comments.count }
 
-# OK - Single count call (not in iteration, no N+1)
-post.comments.count     # Not flagged - single query is fine
-
-# Good - Add counter cache for iteration use cases
-# In Comment model:
-belongs_to :post, counter_cache: true
-
-# Then this is a simple column read:
-posts.each do |post|
-  post.comments_count   # No query - just reads the column
-end
+# Good — counter cache (Comment: belongs_to :post, counter_cache: true)
+posts.each { |post| post.comments_count }   # column read, no query
 ```
 
-### 4. Custom Method Query (N+1 in query methods)
+Only flagged inside iterations — single calls don't cause N+1.
 
-Detects query methods (`.where`, `.find_by`, `.exists?`, etc.) called on associations inside loops.
+### 4. CustomMethodQuery
 
 ```ruby
-# Bad - where inside loop
-class User < ApplicationRecord
-  def supports?(team_name)
-    teams.where(name: team_name).exists?
-  end
-end
-
-@users.each do |user|
-  user.supports?("Lakers")  # Query for each user!
-end
-
-# Bad - find_by inside loop
-@orders.each do |order|
-  order.line_items.find_by(featured: true)
-end
+# Bad — where inside loop
+@users.each { |user| user.teams.where(name: "Lakers").exists? }
 
-# Good - Preload and filter in Ruby
-@users.includes(:teams).each do |user|
-  user.teams.any? { |t| t.name == "Lakers" }
-end
+# Good — preload + filter in Ruby
+@users.includes(:teams).each { |user| user.teams.any? { |t| t.name == "Lakers" } }
 ```
 
-**Detected methods:** `where`, `find_by`, `find_by!`, `exists?`, `find`, `first`, `last`, `take`, `pluck`, `ids`, `count`, `sum`, `average`, `minimum`, `maximum`
-
-### 5. Count in Iteration
+Detected: `where`, `find_by`, `exists?`, `find`, `first`, `last`, `take`, `pluck`, `count`, `sum`, `average`, `minimum`, `maximum`. Per-model scoped — won't flag `obj.foo` just because some other model defines `def foo` with a query.
 
-Detects `.count` called on associations inside loops. Unlike `.size`, `.count` always executes a COUNT query even when the association is preloaded.
+### 5. CountInIteration
 
 ```ruby
-# Bad - COUNT query for each user, even with includes!
+# Bad — .count always queries, even with includes
 @users = User.includes(:posts)
-@users.each do |user|
-  user.posts.count  # Executes: SELECT COUNT(*) FROM posts WHERE user_id = ?
-end
-
-# Good - Use .size (checks if loaded first)
-@users.each do |user|
-  user.posts.size   # No query - counts the loaded array
-end
+@users.each { |user| user.posts.count }   # SELECT COUNT(*) per user
 
-# Best - Use counter_cache for frequent counts
-# In Post model: belongs_to :user, counter_cache: true
-user.posts_count  # Just reads the column
+# Good — .size uses the preload
+@users.each { |user| user.posts.size }
 ```
 
-**Key differences:**
-
-| Method | Loaded Collection | Not Loaded |
-|--------|------------------|------------|
+| Method | Loaded | Not loaded |
+|---|---|---|
 | `.count` | COUNT query | COUNT query |
-| `.size` | Array#size | COUNT query |
-| `.length` | Array#length | Loads all, then counts |
-
-### 6. Callback Query Detection
+| `.size` | array#size | COUNT query |
+| `.length` | array#length | loads all then counts |
 
-Detects N+1 patterns inside ActiveRecord callbacks - specifically iterations that execute queries on each loop.
+### 6. CallbackQuery
 
 ```ruby
-# Bad - N+1 in callback (DETECTED)
+# Bad — N+1 inside callback
 class Order < ApplicationRecord
   after_create :notify_subscribers
 
   def notify_subscribers
-    customer.followers.each do |follower|  # Error: Iteration in callback
-      follower.notifications.create!(...)  # Warning: Query on iteration variable
-    end
+    customer.followers.each { |f| f.notifications.create!(...) }   # N inserts + N queries
   end
 end
 
-# OK - Single query in callback (NOT flagged - not N+1)
-class Article < ApplicationRecord
-  after_save :update_stats
-
-  def update_stats
-    author.articles.count  # Single query, acceptable
-  end
-end
-
-# OK - Query not on iteration variable (NOT flagged)
-class Post < ApplicationRecord
-  after_save :process_items
-
-  def process_items
-    items.each do |item|
-      OtherModel.where(name: item.name).first  # OtherModel is receiver, not item
-    end
-  end
-end
-
-# Good - Move iterations to background job
+# Good — defer to background job
 after_commit :schedule_notifications, on: :create
-
 def schedule_notifications
   NotifySubscribersJob.perform_later(id)
 end
 ```
 
-### 7. Pluck to Array Misuse
-
-Detects when `.pluck(:id)` or `.map(&:id)` results are used in `where` clauses instead of subqueries.
+### 7. PluckToArray
 
 ```ruby
-# Bad - Two queries + memory overhead
+# Warning — two queries + memory overhead
 user_ids = User.active.pluck(:id)
-Post.where(user_id: user_ids)  # ⚠️ Warning
+Post.where(user_id: user_ids)
 
-# Worse - Loads entire table! 🔴 Error
+# Error — loads entire table
 user_ids = User.all.pluck(:id)
 Post.where(user_id: user_ids)
 
-# Good - Single subquery
+# Good — single subquery
 Post.where(user_id: User.active.select(:id))
 ```
 
-**Severity:**
-- ⚠️ **Warning** - Scoped `.pluck(:id)` (two queries, memory overhead)
-- 🔴 **Error** - Unscoped `.all.pluck(:id)` (loads entire table)
+`.where(...).all.pluck(:id)` is correctly recognized as scoped, not a table scan.
 
-### 8. Delegation N+1
-
-Detects when methods delegated via `delegate :method, to: :association` are called inside loops without preloading the target association. These are invisible to `LoopAssociation` because `order.name` looks like a plain attribute, not an association access.
+### 8. DelegationNPlusOne
 
 ```ruby
-# Model
 class Order < ApplicationRecord
   belongs_to :user
   delegate :full_name, :email, to: :user
 end
 
-# Bad - N+1 (each call hits the database for user)
-orders.each do |order|
-  order.full_name   # actually: order.user.full_name — loads user for each order!
-  order.email       # actually: order.user.email — another load!
-end
+# Bad — looks like attribute access, actually loads user per order
+orders.each { |o| o.full_name }
 
-# Good - Eager load the delegated-to association
-orders.includes(:user).each do |order|
-  order.full_name   # no N+1 — user is already loaded
-  order.email       # no N+1 — user is already loaded
-end
+# Good
+orders.includes(:user).each { |o| o.full_name }
 ```
 
-EagerEye detects these by:
-1. Scanning model files for `delegate :method, to: :assoc` declarations
-2. Tracking which methods delegate to which associations
-3. Flagging calls to those methods inside iteration blocks when the association is not preloaded
+Cross-file: scans models for `delegate ... to: :assoc` declarations.
 
-### 9. Decorator N+1
-
-Detects N+1 queries inside Draper decorators, SimpleDelegator subclasses, and classes named `Decorator`, `Presenter`, or `ViewObject`. Each decorator wraps a single record — when a collection is decorated without preloading, every method that accesses an association triggers a new query per record.
+### 9. DecoratorNPlusOne
 
 ```ruby
-# Bad - N+1 on each decorated post
 class PostDecorator < Draper::Decorator
   def comment_summary
-    object.comments.map(&:body).join(", ")   # Query for each post!
-  end
-
-  def tag_list
-    object.tags.map(&:name).join(", ")        # Another query for each post!
+    object.comments.map(&:body).join(", ")   # query per decorated post
   end
 end
 
-# Controller - no includes = N+1
+# Bad
 @posts = Post.all.decorate
 
-# Good - Eager load before decorating
-@posts = Post.includes(:comments, :tags).all.decorate
+# Good
+@posts = Post.includes(:comments).all.decorate
 ```
 
-Supports the following object references inside decorators:
-- `object` — Draper standard
-- `__getobj__` — SimpleDelegator standard
-- `source`, `model` — alternative Draper aliases
-
-### 10. Scope Chain N+1
+Recognizes `object`, `__getobj__`, `source`, `model` references inside Draper / SimpleDelegator / Presenter / ViewObject classes.
 
-Detects named scope calls on associations inside iterations. Unlike explicit query methods (`.where`, `.find_by`) caught by `CustomMethodQuery`, named scopes (`.recent`, `.active`, `.published`) are invisible query triggers.
+### 10. ScopeChainNPlusOne
 
 ```ruby
-# Model
 class Comment < ApplicationRecord
   scope :recent, -> { where("created_at > ?", 1.week.ago) }
-  scope :approved, -> { where(approved: true) }
 end
 
-# Bad - scope call per iteration
-posts.each do |post|
-  post.comments.recent          # Query for each post!
-  post.comments.approved.count  # Query for each post!
-end
+# Bad — scope call per iteration
+posts.each { |post| post.comments.recent }
 
-# Good - preload and filter in Ruby
-posts.includes(:comments).each do |post|
-  post.comments.select { |c| c.created_at > 1.week.ago }
-end
+# Good — preload + filter
+posts.includes(:comments).each { |post| post.comments.select { |c| c.created_at > 1.week.ago } }
 ```
 
-EagerEye detects these by:
-1. Scanning model files for `scope :name, -> { ... }` declarations
-2. Flagging known scope names called on association chains inside iteration blocks
+Cross-file: scans models for `scope :name, -> { ... }` declarations.
 
-### 11. Validation N+1
-
-Detects batch create/save operations inside iterations for models with `validates uniqueness`. Each uniqueness validation triggers a SELECT query per record, resulting in 2N queries (SELECT + INSERT per record).
+### 11. ValidationNPlusOne
 
 ```ruby
-# Model
 class User < ApplicationRecord
   validates :email, uniqueness: true
 end
 
-# Bad - 2N queries (SELECT + INSERT per record)
-params[:users].each do |user_params|
-  User.create!(user_params)          # SELECT + INSERT for each!
-end
+# Bad — SELECT + INSERT per record
+params[:users].each { |p| User.create!(p) }
 
-# Bad - same problem with new + save
-params[:users].each do |user_params|
-  user = User.new(user_params)
-  user.save!                         # SELECT + INSERT for each!
-end
-
-# Good - use insert_all with unique index
-User.insert_all(params[:users])      # Single bulk INSERT, DB enforces uniqueness
+# Good — single bulk INSERT, DB enforces uniqueness via index
+User.insert_all(params[:users])
 ```
 
-EagerEye detects these by:
-1. Scanning model files for `validates :attr, uniqueness: true` or `validates_uniqueness_of` declarations
-2. Flagging `Model.create/create!` or `Model.new` + `.save/.save!` patterns inside iteration blocks
+</details>
 
-## Inline Suppression
+## Inline suppression
 
-Suppress false positives using inline comments (RuboCop-style):
+RuboCop-style comments suppress false positives or accepted patterns:
 
 ```ruby
-# Disable for single line
+# Single line
 user.posts.count  # eager_eye:disable CountInIteration
 
-# Disable for next line
+# Next line
 # eager_eye:disable-next-line LoopAssociation
 @users.each { |u| u.profile }
 
-# Disable block
+# Block
 # eager_eye:disable LoopAssociation, SerializerNesting
-@users.each do |user|
-  user.posts.each { |p| p.author }
-end
+@users.each { |u| u.posts.each { |p| p.author } }
 # eager_eye:enable LoopAssociation, SerializerNesting
 
-# Disable entire file (must be in first 5 lines)
+# Whole file (must be in first 5 lines)
 # eager_eye:disable-file CustomMethodQuery
 
 # With reason
 user.posts.count  # eager_eye:disable CountInIteration -- using counter_cache
 
-# Disable all detectors
+# Disable everything
 # eager_eye:disable all
 ```
 
-### Available Detector Names
+Detector names are accepted as either CamelCase (`LoopAssociation`) or snake_case (`loop_association`).
 
-Both CamelCase and snake_case formats are accepted:
+## Auto-fix (experimental)
 
-| Detector | CamelCase | snake_case |
-|----------|-----------|------------|
-| Loop Association | `LoopAssociation` | `loop_association` |
-| Serializer Nesting | `SerializerNesting` | `serializer_nesting` |
-| Missing Counter Cache | `MissingCounterCache` | `missing_counter_cache` |
-| Custom Method Query | `CustomMethodQuery` | `custom_method_query` |
-| Count in Iteration | `CountInIteration` | `count_in_iteration` |
-| Callback Query | `CallbackQuery` | `callback_query` |
-| Pluck to Array | `PluckToArray` | `pluck_to_array` |
-| Delegation N+1 | `DelegationNPlusOne` | `delegation_n_plus_one` |
-| Decorator N+1 | `DecoratorNPlusOne` | `decorator_n_plus_one` |
-| Scope Chain N+1 | `ScopeChainNPlusOne` | `scope_chain_n_plus_one` |
-| Validation N+1 | `ValidationNPlusOne` | `validation_n_plus_one` |
-| All Detectors | `all` | `all` |
+```bash
+eager_eye --suggest-fixes   # show diff
+eager_eye --fix             # interactive
+eager_eye --fix --force     # apply all without confirmation
+```
 
-## Auto-fix (Experimental)
+| Issue | Auto-fix |
+|---|---|
+| `.pluck(:id)` used in `.where(id: ...)` | → `.select(:id)` |
+| `.count` in iteration | → `.size` |
+| Missing `includes` before loop | → inserts `.includes(:assoc)` |
 
-EagerEye can automatically fix some simple issues:
+> ⚠ Always review the diff and re-run your test suite after `--fix`.
 
-```bash
-# Show fix suggestions
-eager_eye --suggest-fixes
+## CI integration
 
-# Apply fixes interactively
-eager_eye --fix
+```yaml
+# .github/workflows/eager_eye.yml
+name: EagerEye
+on: [pull_request]
 
-# Apply all fixes without confirmation
-eager_eye --fix --force
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+      - run: gem install eager_eye
+      - run: eager_eye app/ --format json > report.json
+      - run: |
+          issues=$(ruby -rjson -e 'puts JSON.parse(File.read("report.json"))["summary"]["total_issues"]')
+          [ "$issues" -gt 0 ] && echo "::warning::Found $issues potential N+1 issues" || true
 ```
 
-### Currently Supported Auto-fixes
+See [examples/github_action.yml](examples/github_action.yml) for a fuller setup with PR annotations.
 
-| Issue | Fix |
-|-------|-----|
-| `.pluck(:id)` inline | → `.select(:id)` |
-| `.count` in iteration | → `.size` |
-| Missing `includes` before loop | → `.includes(:assoc)` inserted |
+### Baseline mode (brownfield projects)
 
-### Example
+Most existing Rails apps have hundreds of N+1 issues already — failing CI on
+every one of them is noise. Capture today's report as a baseline and let CI
+fail **only on regressions** (new issues introduced by a PR):
 
-```
-$ eager_eye --suggest-fixes
-
-app/services/user_service.rb:
-  Line 12:
-    - Post.where(user_id: User.active.pluck(:id))
-    + Post.where(user_id: User.active.select(:id))
-
-app/controllers/posts_controller.rb:
-  Line 8:
-    - user.posts.count
-    + user.posts.size
-
-  Line 5:
-    - @posts.each do |post|
-    + @posts.includes(:author).each do |post|
-
-$ eager_eye --fix
-app/services/user_service.rb:12
-  - Post.where(user_id: User.active.pluck(:id))
-  + Post.where(user_id: User.active.select(:id))
-Apply this fix? [y/n/q] y
-  Applied
-```
+```bash
+# One-time: capture the current state as the baseline
+eager_eye app/ --format json > .eager_eye_baseline.json
 
-> **Warning:** Auto-fix is experimental. Always review changes and run your test suite after applying fixes.
+# In CI: only NEW issues count
+eager_eye app/ --baseline .eager_eye_baseline.json
+```
 
-## RSpec Integration
+The baseline file is a normal `--format json` report. Refresh it as you
+fix existing issues. The match key is `(detector, file_path, line_number,
+message, severity, suggestion)` — if any of those change for a known issue,
+it shows up as "new" until the baseline is refreshed.
 
-EagerEye provides RSpec matchers for testing your codebase:
+## RSpec integration
 
 ```ruby
 # spec/rails_helper.rb
@@ -575,228 +385,104 @@ RSpec.describe "EagerEye Analysis" do
     expect("app/serializers").to pass_eager_eye(only: [:serializer_nesting])
   end
 
-  # Allow some issues during migration
+  # Allow some during migration
   it "legacy code is acceptable" do
     expect("app/services/legacy").to pass_eager_eye(max_issues: 10)
   end
-
-  it "models have no callback issues except legacy" do
-    expect("app/models").to pass_eager_eye(
-      only: [:callback_query],
-      exclude: ["app/models/legacy/**"]
-    )
-  end
 end
 ```
 
-### Matcher Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `only` | `Array<Symbol>` | Run only specified detectors |
-| `exclude` | `Array<String>` | Glob patterns to exclude |
-| `max_issues` | `Integer` | Maximum allowed issues (default: 0) |
+Matcher options: `only:` (Array<Symbol>), `exclude:` (Array<String> globs), `max_issues:` (Integer, default 0).
 
 ## Configuration
 
-### Config File (.eager_eye.yml)
-
 ```yaml
-# Paths to exclude from analysis (glob patterns)
+# .eager_eye.yml
 excluded_paths:
-  - app/serializers/legacy/**
+  - app/legacy/**
   - lib/tasks/**
 
-# Detectors to enable (default: all)
-enabled_detectors:
+enabled_detectors:        # default: all
   - loop_association
   - serializer_nesting
-  - missing_counter_cache
   - custom_method_query
-  - count_in_iteration
-  - callback_query
-  - pluck_to_array
-  - delegation_n_plus_one
-  - decorator_n_plus_one
-  - scope_chain_n_plus_one
-  - validation_n_plus_one
-
-# 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
-  delegation_n_plus_one: warning    # Hidden delegation N+1
-  decorator_n_plus_one: warning     # Decorator/Presenter N+1
-  scope_chain_n_plus_one: warning   # Scope chain on association
-  validation_n_plus_one: warning    # Uniqueness validation in batch
-  missing_counter_cache: info       # Suggestion
-
-# Minimum severity to report (default: info)
-min_severity: warning
-
-# Base path to analyze (default: app)
-app_path: app
+  loop_association: error
+  missing_counter_cache: info
+  # ...
 
-# Exit with error code when issues found (default: true)
+min_severity: warning     # info | warning | error
+app_path: app
 fail_on_issues: true
 ```
 
-### Programmatic Configuration
+Or programmatically:
 
 ```ruby
 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
 ```
 
-## CI Integration
+## CLI reference
 
-### GitHub Actions
-
-```yaml
-name: EagerEye
-on: [pull_request]
-
-jobs:
-  analyze:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: "3.3"
-      - run: gem install eager_eye
-      - run: eager_eye app/ --format json > report.json
-      - name: Check results
-        run: |
-          issues=$(cat report.json | ruby -rjson -e 'puts JSON.parse(STDIN.read)["summary"]["total_issues"]')
-          if [ "$issues" -gt 0 ]; then
-            echo "::warning::Found $issues potential N+1 issues"
-          fi
-```
-
-See [examples/github_action.yml](examples/github_action.yml) for a complete example with PR annotations.
-
-## CLI Reference
-
-```
+```text
 Usage: eager_eye [paths] [options]
 
-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
-    -h, --help               Show this help message
-```
-
-## Output Formats
-
-### Console (default)
-
-```
-EagerEye Analysis Results
-=========================
-
-app/controllers/posts_controller.rb
-  Line 15: [LoopAssociation] Potential N+1 query: `post.author` called inside iteration
-           Suggestion: Consider using `includes(:author)` on the collection before iterating
-
-  Line 23: [MissingCounterCache] `.count` called on `comments` may cause N+1 queries
-           Suggestion: Consider adding `counter_cache: true` to the belongs_to association
-
-----------------------------------------
-Total: 2 issues (2 warnings, 0 errors)
-```
-
-### JSON
-
-```json
-{
-  "summary": {
-    "total_issues": 2,
-    "warnings": 2,
-    "errors": 0,
-    "files_analyzed": 15
-  },
-  "issues": [
-    {
-      "detector": "loop_association",
-      "file_path": "app/controllers/posts_controller.rb",
-      "line_number": 15,
-      "message": "Potential N+1 query: `post.author` called inside iteration",
-      "severity": "warning",
-      "suggestion": "Consider using `includes(:author)` on the collection"
-    }
-  ]
-}
+  -f, --format FORMAT       console | json (default: console)
+  -e, --exclude PATTERN     glob to exclude (repeatable)
+  -o, --only DETECTORS      comma-separated detector list
+  -s, --min-severity LEVEL  info | warning | error
+      --no-fail             always exit 0
+      --no-color            plain output
+      --baseline FILE       compare against a previous JSON report;
+                            only NEW issues are reported (and counted)
+      --suggest-fixes       print fix diffs without applying
+      --fix                 interactively apply auto-fixes
+      --fix --force         apply all auto-fixes
+  -v, --version
+  -h, --help
 ```
 
 ## Limitations
 
-EagerEye uses static analysis, which means:
-
-- **No runtime context** - Cannot know if associations are already eager loaded elsewhere
-- **Heuristic-based** - Uses naming conventions to identify associations (may have false positives)
-- **Ruby code only** - Does not analyze SQL queries or ActiveRecord internals
-- **Cross-file scope** - Cross-file analysis covers model-defined query methods; controller-to-view or service-to-service patterns are not yet tracked
-
-For best results, use EagerEye alongside runtime tools like Bullet for comprehensive N+1 detection.
-
-## VS Code Extension
+EagerEye is static analysis. That comes with trade-offs:
 
-EagerEye is also available as a VS Code extension for real-time analysis while coding.
+- **No runtime context** — can't see what `find_each` block actually does at runtime.
+- **Heuristic association detection** — falls back to common name patterns (`author`, `user`, ...) when a model isn't in the parsed set; can over-flag in tiny edge cases.
+- **Cross-file flow** — propagates preloads across same-class methods (controller → its private helpers), but cross-file flow (controller → external service object → iteration) isn't tracked yet.
+- **Ruby code only** — doesn't read SQL or your DB schema.
 
-**Features:**
-- Real-time analysis on file save
-- Problem highlighting with squiggly underlines
-- Quick fix actions for common issues
-- Status bar showing issue count
-
-**Install:** Search for "EagerEye" in VS Code Extensions or visit the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=hamzagedikkaya.eager-eye).
+Use it alongside [Bullet](https://github.com/flyerhzm/bullet) for a complete picture: static (EagerEye) catches code paths tests don't hit, runtime (Bullet) catches what static can't see.
 
 ## Development
 
 ```bash
-# Setup
 bin/setup
-
-# Run tests
 bundle exec rspec
-
-# Run linter
 bundle exec rubocop
-
-# Interactive console
 bin/console
 ```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/hamzagedikkaya/eager_eye.
+Bug reports and PRs welcome at <https://github.com/hamzagedikkaya/eager_eye>.
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/my-feature`)
-3. Commit your changes (`git commit -am 'Add my feature'`)
-4. Push to the branch (`git push origin feature/my-feature`)
-5. Create a Pull Request
+1. Fork
+2. `git checkout -b feature/my-feature`
+3. Add specs (this repo is at ~95% coverage)
+4. `git commit -am 'Add my feature'`
+5. Open a Pull Request
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT — see [LICENSE.txt](LICENSE.txt).
 
 ## Code of Conduct
 
-Everyone interacting in the EagerEye project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hamzagedikkaya/eager_eye/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in EagerEye's codebases, issue trackers, and discussions is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).