eager_eye 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dce399f8b8160530246911ddbd4c9c5a9fb6cad487d409924c6e520993ff37cc
+  data.tar.gz: 3be96cbcf42c206f0348c63a91991c1a872addd775d5054be9e3dc44cc8b4f52
+SHA512:
+  metadata.gz: 23923fe65f0f51de105b9a6df93a8a115d9ceb40042dedc9d112ccfbdc48a324935cd48f18306944708ca355cb463caad4b97b994f619dff24d8c6cf475180c0
+  data.tar.gz: efc5cfe923e04b55b3e5f2a9a6b201298176e4370a5cac92825bd01649ec528ea978fb378151ea7b74c2a82ce6194a02df6ce8c52018725f86bd83736410b71d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,35 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Max: 35
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+    - "lib/eager_eye/railtie.rb"
+
+Metrics/ParameterLists:
+  Max: 6
+
+Metrics/AbcSize:
+  Max: 35
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/ClassLength:
+  Max: 150
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-12-15
+
+### Added
+
+- **Static Analysis Engine**: AST-based code analysis using the `parser` gem
+- **Three N+1 Detectors**:
+  - `LoopAssociation`: Detects association calls inside iteration blocks (each, map, select, etc.)
+  - `SerializerNesting`: Detects nested association access in serializer blocks (ActiveModel::Serializer, Blueprinter, Alba)
+  - `MissingCounterCache`: Detects `.count`, `.size`, `.length` calls on associations
+- **CLI Interface**: Full-featured command line tool with options:
+  - `--format json|console`: Output format selection
+  - `--exclude PATTERN`: Exclude files matching glob patterns
+  - `--only DETECTORS`: Run specific detectors only
+  - `--no-fail`: Exit with 0 even when issues found
+  - `--no-color`: Disable colored output
+  - `--version`, `--help`: Standard CLI options
+- **Rails Integration**:
+  - Railtie with `rake eager_eye:analyze` and `rake eager_eye:json` tasks
+  - Install generator: `rails g eager_eye:install`
+  - Support for `.eager_eye.yml` configuration file
+- **Reporters**:
+  - Console reporter with colored, human-readable output
+  - JSON reporter for CI integration
+- **Configuration System**:
+  - `excluded_paths`: Glob patterns to exclude from analysis
+  - `enabled_detectors`: Select which detectors to run
+  - `app_path`: Base path for analysis (default: "app")
+  - `fail_on_issues`: Control exit code behavior
+- **GitHub Actions**: CI workflow with Ruby 3.1, 3.2, 3.3 matrix testing
+- **Comprehensive Test Suite**: 140 examples with 95.8% code coverage
+
+### Technical Details
+
+- Minimum Ruby version: 3.1.0
+- Dependencies: `parser ~> 3.3`, `ast ~> 2.4`
+- License: MIT

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 hamzagedikkaya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,310 @@
+# EagerEye
+
+[![CI](https://github.com/hamzagedikkaya/eager_eye/actions/workflows/main.yml/badge.svg)](https://github.com/hamzagedikkaya/eager_eye/actions/workflows/main.yml)
+[![Gem Version](https://badge.fury.io/rb/eager_eye.svg)](https://badge.fury.io/rb/eager_eye)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Static analysis tool for detecting N+1 queries in Rails applications.**
+
+EagerEye analyzes your Ruby code without running it, using AST (Abstract Syntax Tree) parsing to find potential N+1 query issues before they hit production.
+
+## Why EagerEye?
+
+Unlike runtime tools like Bullet, EagerEye:
+
+- **Runs without executing code** - Works in CI pipelines without a test suite
+- **Catches more patterns** - Detects serializer N+1s and missing counter caches
+- **Proactive detection** - Finds issues at code review time, not after deployment
+
+| Feature | EagerEye | Bullet |
+|---------|----------|--------|
+| Detection method | Static analysis | Runtime |
+| Requires test suite | No | Yes |
+| Serializer N+1 detection | Yes | Limited |
+| Counter cache suggestions | Yes | No |
+| CI integration | Native | Requires tests |
+| False positive rate | Higher | Lower |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "eager_eye", group: :development
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install standalone:
+
+```bash
+gem install eager_eye
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Analyze default app/ directory
+eager_eye
+
+# Analyze 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
+
+# Exclude paths
+eager_eye --exclude "app/legacy/**"
+```
+
+### Rails Integration
+
+```bash
+# Generate config file
+rails g eager_eye:install
+
+# Run via rake
+rake eager_eye:analyze
+
+# JSON output
+rake eager_eye:json
+```
+
+## Detected Issues
+
+### 1. Loop Association (N+1 in iterations)
+
+Detects association calls inside loops that may cause N+1 queries.
+
+```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
+
+# Good - Eager load associations
+posts.includes(:author, :comments).each do |post|
+  post.author.name      # No additional query
+  post.comments.count   # No additional query
+end
+```
+
+### 2. Serializer Nesting (N+1 in serializers)
+
+Detects nested association access in serializer blocks.
+
+```ruby
+# Bad - N+1 in serializer
+class PostSerializer < ActiveModel::Serializer
+  attribute :author_name do
+    object.author.name  # Query for each serialized post!
+  end
+end
+
+# Good - Eager load in controller
+class PostsController < ApplicationController
+  def index
+    @posts = Post.includes(:author)
+    render json: @posts, each_serializer: PostSerializer
+  end
+end
+```
+
+Supports multiple serializer libraries:
+- ActiveModel::Serializers
+- Blueprinter
+- Alba
+
+### 3. Missing Counter Cache
+
+Detects `.count` or `.size` calls on associations that could benefit from counter caches.
+
+```ruby
+# Bad - COUNT query every time
+post.comments.count
+post.comments.size
+
+# Good - Add counter cache
+# In Comment model:
+belongs_to :post, counter_cache: true
+
+# Then this is a simple column read:
+post.comments_count
+```
+
+## Configuration
+
+### Config File (.eager_eye.yml)
+
+```yaml
+# 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
+```
+
+### Programmatic Configuration
+
+```ruby
+EagerEye.configure do |config|
+  config.excluded_paths = ["app/legacy/**"]
+  config.enabled_detectors = [:loop_association, :serializer_nesting]
+  config.app_path = "app"
+  config.fail_on_issues = true
+end
+```
+
+## CI Integration
+
+### 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
+
+```
+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)
+        --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"
+    }
+  ]
+}
+```
+
+## 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
+
+For best results, use EagerEye alongside runtime tools like Bullet for comprehensive N+1 detection.
+
+## 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.
+
+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
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 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).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/github_action.yml

@@ -0,0 +1,75 @@
+# 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

data/exe/eager_eye

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "eager_eye"
+
+exit EagerEye::CLI.new.run