and_one 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f74cbffeb954bdf743f6028d005244aa5d4f76c229f7543145d3e77f2b468398
-  data.tar.gz: 418273820bcdb2b8a86a3d8b76922ba97b0540bd48b6a6ac5c3e3317fe3ac703
+  metadata.gz: f97b3753e3181eb460649cb7624c9744d03df8dfb6205bae46f8069cc47d3448
+  data.tar.gz: 815b5b9c7f5617faae5f77ac11e87ee4aa6653933a5c475a4fa5c5283ec1765d
 SHA512:
-  metadata.gz: 159e5753a847aa025f9168c9962cdb47d53489ccd0b81272b81039f6784be1cd2b3ecc9ec7537a19245b030602f539e7578d52d05dcdd28abcc45101a47d2a44
-  data.tar.gz: 9885b04b8ed1b4aded500bb673ac5f4526ea834b96c3beee407a7e3e165fa2a3eea9100edd5d67c4d0c6a78cde3940557b77a2609f283249afd1d6ce7f73b936
+  metadata.gz: 1c3a672c29fffc69baadee284fc973e335fa1a64086369a7e3852f71e7c49fa3402ab86c0d3b8d79e1ca69be380a14a8d7eafda0de17686daa23ff8e67be62ec
+  data.tar.gz: eeaa76d8407541c4668bc211a1aacba0eb528917ae36ae093948cd12514974a6df7c611a5de64880aa59ee9f4115cda22ecac9525e36e2081662c640360afbb9

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.3.1] - 2026-03-05
+
+### Added
+
+- **Configurable toast position** — `AndOne.dev_toast_position` accepts `:top_right` (default), `:top_left`, `:bottom_right`, or `:bottom_left`. The slide-in animation direction adjusts automatically to match.
+
+## [0.3.0] - 2026-03-05
+
+### Removed
+
+- **`aggregate_mode` configuration option** — Deduplication and aggregate tracking are now always-on when AndOne is enabled. The dev toast and dashboard both depend on the aggregate, so having it off was a bug in disguise (detections would show in the toast but never appear on the dashboard). If you had `AndOne.aggregate_mode = true` in an initializer, simply remove the line.
+
+### Fixed
+
+- N+1 detections now always appear on the `/__and_one` dashboard. Previously, detections would show in the toast notification but not on the dashboard unless `aggregate_mode` was explicitly enabled.
+
 ## [0.2.0] - 2026-03-02
 
 ### Added

data/README.md

@@ -14,7 +14,7 @@ AndOne stays completely invisible until it detects an N+1 query — then it tell
 - **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
+- **Automatic deduplication** — each unique N+1 is reported 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 toast notifications** — in-page toast on every page that triggers an N+1, with a link to the dashboard
 - **Dev UI dashboard** — browse `/__and_one` in development for a live N+1 overview
@@ -132,14 +132,9 @@ This is especially useful for **N+1s coming from gems** where you can't add `.in
 | `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
+## Deduplication
 
-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
-```
+In development, the same N+1 can fire on every request, flooding your logs. AndOne automatically deduplicates — each unique pattern is reported only once per server session. Subsequent occurrences are silently counted.
 
 You can check the session summary at any time:
 
@@ -157,11 +152,12 @@ When an N+1 is detected during a request, AndOne injects a small toast notificat
 
 This is enabled by default in development — no configuration needed. The toast auto-dismisses after 8 seconds, but hovering over it keeps it open.
 
-To disable it:
+To change the position or disable it:
 
 ```ruby
 # config/initializers/and_one.rb
-AndOne.dev_toast = false
+AndOne.dev_toast_position = :bottom_right  # :top_right (default), :top_left, :bottom_right, :bottom_left
+AndOne.dev_toast = false                   # disable entirely
 ```
 
 The toast only appears on HTML responses with a 200 status, so it won't interfere with API endpoints, redirects, or error pages.
@@ -170,13 +166,6 @@ The toast only appears on HTML responses with a 200 status, so it won't interfer
 
 Browse `/__and_one` in development for a full overview of every unique N+1 detected in the current server session. The dashboard shows the query, origin, fix location, and suggested `.includes()` call for each detection.
 
-The dashboard requires aggregate mode to track detections across requests:
-
-```ruby
-# config/initializers/and_one.rb
-AndOne.aggregate_mode = true
-```
-
 Both features work together: the toast gives you immediate feedback on the page you're looking at, and the dashboard link takes you to the full picture.
 
 ## Test Matchers
@@ -245,12 +234,13 @@ AndOne.configure do |config|
   # 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
-
   # In-page toast notifications (default: true in development)
   config.dev_toast = true
 
+  # Toast position (default: :top_right)
+  # Options: :top_right, :top_left, :bottom_right, :bottom_left
+  config.dev_toast_position = :top_right
+
   # Path to ignore file (default: Rails.root/.and_one_ignore)
   config.ignore_file_path = Rails.root.join(".and_one_ignore").to_s
 

data/lib/and_one/aggregate.rb

@@ -2,12 +2,9 @@
 
 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.
+  # 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: } }

data/lib/and_one/dev_toast.rb

@@ -8,9 +8,19 @@ module AndOne
   # or can be enabled manually:
   #   AndOne.dev_toast = true
   #
-  # The toast appears as a fixed-position badge in the bottom-right corner
-  # and auto-dismisses after 8 seconds (click to keep open).
+  # The toast appears as a fixed-position badge and auto-dismisses after
+  # 8 seconds (click to keep open).
+  #
+  # Position is configurable via `AndOne.dev_toast_position`:
+  #   :top_right (default), :top_left, :bottom_right, :bottom_left
   module DevToast
+    POSITIONS = {
+      top_right: { vertical: "top", horizontal: "right", slide_from: "-1rem" },
+      top_left: { vertical: "top", horizontal: "left", slide_from: "-1rem" },
+      bottom_right: { vertical: "bottom", horizontal: "right", slide_from: "1rem" },
+      bottom_left: { vertical: "bottom", horizontal: "left", slide_from: "1rem" }
+    }.freeze
+
     module_function
 
     # Injects toast HTML/JS/CSS before </body> in an HTML response.
@@ -33,6 +43,7 @@ module AndOne
       end.first(5)
 
       extra = count > 5 ? "<div class=\"and-one-toast-extra\">...and #{count - 5} more</div>" : ""
+      pos = POSITIONS[AndOne.dev_toast_position || :top_right] || POSITIONS[:top_right]
 
       <<~HTML
         <div id="and-one-toast" class="and-one-toast" role="status" aria-live="polite">
@@ -50,8 +61,8 @@ module AndOne
         <style>
           .and-one-toast {
             position: fixed;
-            bottom: 1rem;
-            right: 1rem;
+            #{pos[:vertical]}: 1rem;
+            #{pos[:horizontal]}: 1rem;
             z-index: 999999;
             background: #1a1a2e;
             color: #e0e0e0;
@@ -120,8 +131,8 @@ module AndOne
             text-decoration: underline;
           }
           @keyframes and-one-slide-in {
-            from { transform: translateY(1rem); opacity: 0; }
-            to   { transform: translateY(0);    opacity: 1; }
+            from { transform: translateY(#{pos[:slide_from]}); opacity: 0; }
+            to   { transform: translateY(0);                   opacity: 1; }
           }
         </style>
         <script>

data/lib/and_one/dev_ui.rb

@@ -5,12 +5,10 @@ module AndOne
   # session. Mount at `/__and_one` in development to get a mini dashboard
   # for N+1 queries with fix suggestions.
   #
-  # Requires `aggregate_mode = true` to collect detections across requests.
-  #
   # Usage (manual):
   #   app.middleware.use AndOne::DevUI
   #
-  # Or it's auto-mounted by the Railtie in development when aggregate_mode is on.
+  # Or it's auto-mounted by the Railtie in development.
   class DevUI
     MOUNT_PATH = "/__and_one"
 
@@ -29,7 +27,7 @@ module AndOne
     private
 
     def serve_dashboard(_env)
-      entries = AndOne.aggregate_mode ? AndOne.aggregate.detections : {}
+      entries = AndOne.aggregate.detections
 
       html = render_html(entries)
       [200, { "content-type" => "text/html; charset=utf-8" }, [html]]
@@ -41,7 +39,6 @@ module AndOne
                  <tr>
                    <td colspan="6" class="empty">
                      No N+1 queries detected yet.
-                     #{"<br><strong>Tip:</strong> Set <code>AndOne.aggregate_mode = true</code> to collect detections across requests." unless AndOne.aggregate_mode}
                    </td>
                  </tr>
                HTML

data/lib/and_one/railtie.rb

@@ -14,7 +14,7 @@ module AndOne
         app.middleware.insert_before(0, AndOne::Middleware)
 
         if Rails.env.development?
-          # Dev UI dashboard for N+1 overview (requires aggregate_mode)
+          # Dev UI dashboard for N+1 overview
           app.middleware.use(AndOne::DevUI)
 
           # Dev toast: show in-page N+1 notifications (default on in development)

data/lib/and_one/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AndOne
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/and_one.rb

@@ -14,9 +14,9 @@ module AndOne
   class << self
     attr_accessor :enabled, :raise_on_detect, :backtrace_cleaner,
                   :allow_stack_paths, :ignore_queries, :ignore_callers,
-                  :min_n_queries, :notifications_callback, :aggregate_mode,
+                  :min_n_queries, :notifications_callback,
                   :ignore_file_path, :json_logging, :env_thresholds,
-                  :dev_toast
+                  :dev_toast, :dev_toast_position
 
     def configure
       yield self
@@ -160,11 +160,9 @@ module AndOne
 
       return if detections.empty?
 
-      # In aggregate mode, only report NEW unique detections
-      if aggregate_mode
-        detections = detections.select { |d| aggregate.record(d) }
-        return if detections.empty?
-      end
+      # Record to aggregate and only report NEW unique detections
+      detections = detections.select { |d| aggregate.record(d) }
+      return if detections.empty?
 
       cleaner = backtrace_cleaner || default_backtrace_cleaner
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: and_one
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Keith Thompson
@@ -66,7 +66,6 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- TODO.md
 - lib/and_one.rb
 - lib/and_one/active_job_hook.rb
 - lib/and_one/aggregate.rb

data/TODO.md

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