and_one 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ee084901a4915dba0065a11cf14a6996f277d6ca5fba2efd388b27ddc2f349a
+  data.tar.gz: 05d02c49d473359e70ba9b300711e6d15f52d391ab48e22ca1ddb8651e3eb7bc
+SHA512:
+  metadata.gz: 5f59a82aac0fc38ef5f9d2d11b633a1b881378124834d8d8ec0dd4ecb85e887d16aec5feee30225205df60ab90cb1577eb02ebca0306685736231faad0e53799
+  data.tar.gz: '0663708679e397440e6e1fe26bee567e868e1909e1138cfb94d3da085cabdc4da8808005f72a610aa6f99fde5f262ffead6ff57bd4bc21e0b685c9c07195df0b'

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-02-27
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"and_one" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["keiththomps@hey.com"](mailto:"keiththomps@hey.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Keith Thompson
+
+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,287 @@
+# 🏀 AndOne
+
+Detect N+1 queries in Rails applications with zero configuration and actionable fix suggestions.
+
+AndOne stays completely invisible until it detects an N+1 query — then it tells you exactly what's wrong and how to fix it. No external dependencies beyond Rails itself.
+
+## Features
+
+- **Zero configuration** — Railtie auto-setup in development and test
+- **Actionable fix suggestions** — suggests the exact `.includes()`, `.preload()`, or `.eager_load()` call
+- **Smart location detection** — identifies both the origin (where the N+1 fires) and the fix location (where to add `.includes`)
+- **Clean error handling** — never corrupts backtraces or interferes with exception propagation
+- **No external dependencies** — only Rails itself
+- **Auto-raises in test** — N+1s fail your test suite by default
+- **Background job support** — ActiveJob (`around_perform`) and Sidekiq server middleware, with double-scan protection
+- **Ignore file** — `.and_one_ignore` with `gem:`, `path:`, `query:`, and `fingerprint:` rules
+- **Aggregate mode** — report each unique N+1 once per server session with occurrence counts
+- **Test matchers** — Minitest (`assert_no_n_plus_one`) and RSpec (`expect { }.not_to cause_n_plus_one`)
+- **Dev UI dashboard** — browse `/__and_one` in development for a live N+1 overview
+- **Rails console integration** — auto-scans in `rails console` and prints warnings inline
+- **Structured JSON logging** — JSON output mode for Datadog, Splunk, and other log aggregation services
+- **Per-environment thresholds** — different `min_n_queries` for development vs test
+- **GitHub Actions annotations** — N+1s appear as warning annotations on PR diffs
+- **`strict_loading` suggestions** — also suggests model-level prevention as an alternative
+- **`has_many :through` and polymorphic support** — resolves complex association chains
+- **Thread-safe under Puma** — per-thread isolation verified with concurrent stress tests
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+group :development, :test do
+  gem "and_one"
+end
+```
+
+That's it. AndOne automatically activates in development and test environments via a Railtie.
+
+## What You'll See
+
+When an N+1 is detected, you get output like:
+
+```
+──────────────────────────────────────────────────────────────────────────
+ 🏀 And One! 1 N+1 query detected
+──────────────────────────────────────────────────────────────────────────
+
+  1) 9x repeated query on `comments`
+     fingerprint: a1b2c3d4e5f6
+
+  Query:
+    SELECT "comments".* FROM "comments" WHERE "comments"."post_id" = ?
+
+  Origin (where the N+1 is triggered):
+  → app/views/posts/index.html.erb:5
+
+  Fix here (where to add .includes):
+  ⇒ app/controllers/posts_controller.rb:8
+
+  Call stack:
+    app/views/posts/index.html.erb:5
+    app/controllers/posts_controller.rb:8
+
+  💡 Suggestion:
+    Add `.includes(:comments)` to your Post query
+
+  To ignore, add to .and_one_ignore:
+    fingerprint:a1b2c3d4e5f6
+
+──────────────────────────────────────────────────────────────────────────
+```
+
+## Background Jobs
+
+### ActiveJob (any backend)
+
+Automatically hooked via `around_perform`. Works with **every** ActiveJob backend:
+Sidekiq, GoodJob, SolidQueue, Delayed Job, Resque, and anything else that uses ActiveJob.
+
+No configuration needed — the Railtie handles it.
+
+### Sidekiq (direct usage)
+
+For jobs that use Sidekiq directly (bypassing ActiveJob), AndOne installs a server middleware automatically when Sidekiq is detected.
+
+If you need manual installation:
+
+```ruby
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add AndOne::SidekiqMiddleware
+  end
+end
+```
+
+When both hooks are active (ActiveJob job running through Sidekiq), the Sidekiq middleware detects the existing scan from ActiveJobHook and passes through — no double-scanning.
+
+## Ignoring N+1s
+
+### The `.and_one_ignore` file
+
+Create a `.and_one_ignore` file in your project root to permanently silence known N+1s. Supports four rule types:
+
+```bash
+# Ignore N+1s originating from a specific gem
+# (matches against raw backtrace paths, e.g. /gems/devise-4.9.0/)
+gem:devise
+gem:administrate
+
+# Ignore N+1s whose call stack matches a path pattern (supports * globs)
+path:app/views/admin/*
+path:lib/legacy/**
+
+# Ignore N+1s matching a SQL pattern
+query:schema_migrations
+query:pg_catalog
+
+# Ignore a specific detection by its fingerprint (shown in output)
+fingerprint:a1b2c3d4e5f6
+```
+
+This is especially useful for **N+1s coming from gems** where you can't add `.includes()` to the source. Instead of littering your code with `AndOne.pause` blocks, add a `gem:` rule.
+
+### When to use each rule type
+
+| Rule | Use when... |
+|---|---|
+| `gem:devise` | A gem you depend on has an N+1 you can't fix |
+| `path:app/views/admin/*` | An area of your app has known N+1s you've accepted |
+| `query:some_table` | A specific query pattern should always be ignored |
+| `fingerprint:abc123` | You want to silence one specific detection (shown in output) |
+
+## Aggregate Mode
+
+In development, the same N+1 can fire on every request, flooding your logs. Aggregate mode reports each unique pattern only once per server session:
+
+```ruby
+# config/initializers/and_one.rb
+AndOne.aggregate_mode = true
+```
+
+You can check the session summary at any time:
+
+```ruby
+AndOne.aggregate.summary    # formatted string of all unique N+1s
+AndOne.aggregate.size       # number of unique patterns
+AndOne.aggregate.reset!     # clear and start fresh
+```
+
+## Test Matchers
+
+### Minitest
+
+```ruby
+class PostsControllerTest < ActionDispatch::IntegrationTest
+  include AndOne::MinitestHelper
+
+  test "index does not cause N+1 queries" do
+    assert_no_n_plus_one do
+      get posts_path
+    end
+  end
+
+  test "known N+1 is documented" do
+    detections = assert_n_plus_one do
+      get legacy_report_path
+    end
+    assert_equal "comments", detections.first.table_name
+  end
+end
+```
+
+### RSpec
+
+```ruby
+# In spec_helper.rb or rails_helper.rb
+require "and_one/rspec"
+
+# Then in your specs
+RSpec.describe "Posts" do
+  it "loads posts efficiently" do
+    expect {
+      Post.includes(:comments).each { |p| p.comments.to_a }
+    }.not_to cause_n_plus_one
+  end
+
+  it "has a known N+1" do
+    expect {
+      Post.all.each { |p| p.comments.to_a }
+    }.to cause_n_plus_one
+  end
+end
+```
+
+The matchers temporarily disable `raise_on_detect` internally, so they work correctly regardless of your global configuration.
+
+## Behavior by Environment
+
+- **Development**: Logs N+1 warnings to Rails logger and stderr
+- **Test**: Raises `AndOne::NPlus1Error` so N+1s fail your test suite
+- **Production**: Completely disabled (not even loaded)
+
+## Configuration
+
+AndOne works out of the box, but you can customize:
+
+```ruby
+# config/initializers/and_one.rb
+AndOne.configure do |config|
+  # Raise on detection (default: true in test, false in development)
+  config.raise_on_detect = false
+
+  # Minimum repeated queries to trigger (default: 2)
+  config.min_n_queries = 3
+
+  # Aggregate mode — only report each unique N+1 once per session
+  config.aggregate_mode = true
+
+  # Path to ignore file (default: Rails.root/.and_one_ignore)
+  config.ignore_file_path = Rails.root.join(".and_one_ignore").to_s
+
+  # Allow specific patterns (won't flag these call stacks)
+  config.allow_stack_paths = [
+    /admin_controller/,
+    /some_legacy_code/
+  ]
+
+  # Ignore specific query patterns
+  config.ignore_queries = [
+    /pg_catalog/,
+    /schema_migrations/
+  ]
+
+  # Custom backtrace cleaner
+  config.backtrace_cleaner = Rails.backtrace_cleaner
+
+  # Custom callback for integrations (logging services, etc.)
+  config.notifications_callback = ->(detections, message) {
+    # detections is an array of AndOne::Detection objects
+    # message is the formatted string
+    MyLogger.warn(message)
+  }
+end
+```
+
+## Manual Scanning
+
+You can also scan specific blocks:
+
+```ruby
+# In a test
+detections = AndOne.scan do
+  posts = Post.all
+  posts.each { |p| p.comments.to_a }
+end
+
+assert_empty detections
+
+# Pause/resume within a scan
+AndOne.scan do
+  # This is scanned
+  posts.each { |p| p.comments.to_a }
+
+  AndOne.pause do
+    # This is NOT scanned
+    legacy_code_with_known_n_plus_ones
+  end
+
+  # Scanning resumes automatically after the pause block
+end
+```
+
+## How It Works
+
+1. **Subscribe** to `sql.active_record` notifications (built into Rails)
+2. **Group** queries by call stack fingerprint
+3. **Fingerprint** SQL to detect same-shape queries with different bind values
+4. **Resolve** table names back to ActiveRecord models and associations
+5. **Suggest** the exact `.includes()` call to fix the N+1
+6. **Filter** against the `.and_one_ignore` file and aggregate tracker
+
+The middleware is designed to **never interfere with error propagation**. If your app raises an exception during a request, AndOne silently stops scanning and re-raises the original exception with its backtrace completely intact.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/TODO.md

@@ -0,0 +1,52 @@
+# AndOne — Feature Roadmap
+
+## ✅ Completed
+
+- [x] Core detection engine using `sql.active_record` notifications
+- [x] SQL fingerprinting without external dependencies
+- [x] Association resolver that suggests exact `.includes()` fixes
+- [x] Rich formatted output with query, call stack, and fix suggestions
+- [x] Rack middleware that never corrupts error backtraces
+- [x] Railtie for zero-config auto-setup in dev/test
+- [x] Raises in test env, warns in dev, disabled in production
+- [x] Pause/resume support for known N+1s
+- [x] ActiveJob `around_perform` hook (works with any backend)
+- [x] Sidekiq server middleware (for jobs bypassing ActiveJob)
+- [x] `ScanHelper` shared module to DRY up scan lifecycle across entry points
+- [x] Double-scan protection (ActiveJob + Sidekiq don't conflict)
+
+## 🎯 High Value — Completed
+
+- [x] **Auto-detect the "fix location"** — Walks the backtrace to identify two key frames: the "origin" (where the N+1 is triggered inside a loop) and the "fix location" (the outer frame where `.includes()` should be added). Both are highlighted in the output.
+
+- [x] **Ignore file (`.and_one_ignore`)** — Supports four rule types: `gem:` (for N+1s from gems like devise/administrate you can't fix), `path:` (glob patterns for app areas), `query:` (SQL patterns), and `fingerprint:` (specific detections). Checked into source control.
+
+- [x] **Aggregate mode for development** — `AndOne.aggregate_mode = true` reports each unique N+1 only once per server session. Tracks occurrence counts. `AndOne.aggregate.summary` shows a session overview. Thread-safe.
+
+- [x] **RSpec / Minitest matchers** — `assert_no_n_plus_one { ... }` / `assert_n_plus_one { ... }` for Minitest. `expect { ... }.not_to cause_n_plus_one` for RSpec. Matchers temporarily disable `raise_on_detect` internally so they work regardless of config.
+
+## ✅ Medium Value — Polish & Power User Features (Completed)
+
+- [x] **`strict_loading` suggestion** — When an N+1 is detected, also suggest the `strict_loading` approach as an alternative: "You could also add `has_many :comments, strict_loading: true` to prevent this at the model level."
+
+- [x] **Query count in test failure messages** — "N+1 detected: 47 queries to `comments` (expected 1). Add `.includes(:comments)` to reduce to 1 query." Makes severity immediately obvious.
+
+- [x] **Dev UI endpoint** — A tiny Rack endpoint (e.g., `/__and_one`) in development that shows all N+1s detected in the current server session with fix suggestions. Like a mini BetterErrors for N+1s.
+
+- [x] **GitHub Actions / CI annotations** — When `GITHUB_ACTIONS` env var is set, output detections in `::warning file=...` format so they appear as annotations on the PR diff.
+
+- [x] **Ignore by caller pattern** — In addition to `ignore_queries` (SQL patterns), support `ignore_callers` to suppress detections originating from specific paths: "ignore any N+1 from `app/views/admin/*`".
+
+- [x] **`has_many :through` and polymorphic support** — Extend the association resolver to handle `has_many :through` join chains and polymorphic associations, which are common sources of confusing N+1s.
+
+- [x] **`preload` vs `includes` vs `eager_load` recommendation** — Suggest the optimal loading strategy based on the query pattern (e.g., `eager_load` when there's a WHERE on the association).
+
+## ✅ Lower Priority — Nice to Have (Completed)
+
+- [x] **Structured JSON logging** — A JSON output mode for log aggregation services (Datadog, Splunk, etc.). Set `AndOne.json_logging = true`. Uses `JsonFormatter` which outputs structured JSON with event, table, fingerprint, query count, suggestion, and backtrace. Also provides `format_hashes` for integrations that accept Ruby hashes directly.
+
+- [x] **Thread-safety audit for Puma** — Formal audit and stress test suite complete. Found and fixed a **critical cross-thread contamination bug** in `Detector#subscribe`: the `ActiveSupport::Notifications` callback closure captured `self`, causing SQL from one thread to be recorded in another thread's Detector. Fixed by checking `Thread.current[:and_one_detector].object_id` in the callback. Also added Mutex protection for lazy singletons (`aggregate`, `ignore_list`), `AssociationResolver.@table_model_cache`, and report output serialization. 14 concurrent stress tests verify isolation, atomicity, and correctness under Puma-like load.
+
+- [x] **Rails console integration** — Auto-scan in `rails console` sessions and print warnings inline. Activated automatically by the Railtie in development, or manually via `AndOne::Console.activate!`. Hooks into IRB (via `Context#evaluate` prepend) and Pry (via `:after_eval` hook) to cycle scans between commands.
+
+- [x] **Configurable per-environment thresholds** — Different `min_n_queries` for dev vs test. Configure via `AndOne.env_thresholds = { "development" => 3, "test" => 2 }`. Falls back to global `min_n_queries` when no env-specific threshold is set. Supports both string and symbol keys.

data/lib/and_one/active_job_hook.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AndOne
+  # Hooks into ActiveJob's around_perform callback to scan every job for N+1 queries.
+  # Works with any ActiveJob backend: Sidekiq, GoodJob, SolidQueue, Delayed Job, etc.
+  #
+  # Automatically installed by the Railtie. Can also be installed manually:
+  #
+  #   ActiveJob::Base.include(AndOne::ActiveJobHook)
+  #
+  module ActiveJobHook
+    extend ActiveSupport::Concern
+    include ScanHelper
+
+    included do
+      around_perform :and_one_scan
+    end
+
+    private
+
+    def and_one_scan
+      and_one_wrap { yield }
+    end
+  end
+end

data/lib/and_one/aggregate.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module AndOne
+  # Tracks unique N+1 detections across requests/jobs in a server session.
+  # In aggregate mode, each unique N+1 (by fingerprint) is only reported once.
+  # Subsequent occurrences are silently counted.
+  #
+  # Usage:
+  #   AndOne.aggregate_mode = true
+  #
+  # The aggregate can be queried at any time:
+  #   AndOne.aggregate.summary   # => formatted string
+  #   AndOne.aggregate.detections # => { fingerprint => { detection:, count:, first_seen_at: } }
+  #   AndOne.aggregate.reset!
+  #
+  class Aggregate
+    Entry = Struct.new(:detection, :occurrences, :first_seen_at, :last_seen_at, keyword_init: true)
+
+    def initialize
+      @mutex = Mutex.new
+      @entries = {}
+    end
+
+    # Record a detection. Returns true if this is a NEW unique detection
+    # (first time seeing this fingerprint), false if it's a repeat.
+    def record(detection)
+      fp = detection.fingerprint
+
+      @mutex.synchronize do
+        if @entries.key?(fp)
+          @entries[fp].occurrences += 1
+          @entries[fp].last_seen_at = Time.now
+          false
+        else
+          @entries[fp] = Entry.new(
+            detection: detection,
+            occurrences: 1,
+            first_seen_at: Time.now,
+            last_seen_at: Time.now
+          )
+          true
+        end
+      end
+    end
+
+    def detections
+      @mutex.synchronize { @entries.dup }
+    end
+
+    def size
+      @mutex.synchronize { @entries.size }
+    end
+
+    def empty?
+      @mutex.synchronize { @entries.empty? }
+    end
+
+    def reset!
+      @mutex.synchronize { @entries.clear }
+    end
+
+    def summary
+      @mutex.synchronize do
+        return "No N+1 queries detected this session." if @entries.empty?
+
+        lines = []
+        lines << ""
+        lines << "🏀 AndOne Session Summary: #{@entries.size} unique N+1 pattern#{'s' if @entries.size != 1}"
+        lines << "─" * 60
+
+        @entries.each_with_index do |(fp, entry), i|
+          det = entry.detection
+          lines << "  #{i + 1}) #{det.table_name || 'unknown'} — #{entry.occurrences} occurrence#{'s' if entry.occurrences != 1}"
+          lines << "     #{det.sample_query[0, 120]}"
+          lines << "     origin: #{det.origin_frame}" if det.origin_frame
+          lines << "     fingerprint: #{fp}"
+          lines << ""
+        end
+
+        lines << "─" * 60
+        lines.join("\n")
+      end
+    end
+  end
+end