n_plus_insight 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b64b2190f32d5bd69dc972654ccb46add8d3a2a4bacc9938a3e0bf5b7035004f
-  data.tar.gz: 9af66e38cdbe1676aece5a7cf193f6eae284589163b845e58adf9bef36a5ef66
+  metadata.gz: 3c665e58752b93be9ca53334439c3ed74166a40d7ec564a0c48f652d05850541
+  data.tar.gz: 8216f64ce6620fcd2faf3a072314ac5d2798d90526ee3455f0db3f58dcf0fe28
 SHA512:
-  metadata.gz: e6ed0f4ad2dacf35a5e9c52ba9d7597c6d536d05f2930d1798082da89bd811d4e6bb7b63a60b1f9f10608c63b2fbbc982b799038410acf5b46d2b5224c862170
-  data.tar.gz: f9c71aa555d723bb1b2d109e572c8f49458c361196de2ee48d6f734158ba55bafba84d4ef0fe418aea10559f994ef751eb3407ac29d4035a0923d54e56ae837b
+  metadata.gz: d02624df18c5889892dee85c63ea7839aa782a2620e8aa8124625cad15b122af1af92b5a0516e29ce757681af07d888ea58481c8b4e45f3cfd5289c93f2ac160
+  data.tar.gz: 7e33bc27f3ca6623d70737dc15d3e01f6deecc6b56518f5ce16600b8d7c870873fb1df04454795e697fb8cdb5c61b1b499764ed173ba0c884df61b082abb0c67

data/CHANGELOG.md

@@ -3,9 +3,15 @@
 ## 0.1.0 - 2026-07-28
 
 - Detect repeated Active Record query shapes within a request.
+- Combine multiple repeated query shapes attributed to the same source line.
 - Identify relevant application source files, line numbers, and code excerpts.
-- Visualize affected models and associations.
-- Recommend eager-loading and strict-loading remediations.
+- Visualize multi-model associations as nested trees.
+- Recommend combined eager-loading and strict-loading remediations for the
+  complete association tree.
 - Provide an optional on-page status indicator and findings panel.
 - Provide a full mounted findings dashboard.
+- Allow operators to clear stored findings from the dashboard.
+- Roll off the oldest dashboard findings according to `max_events`.
+- Publish canonical GitHub, documentation, changelog, and issue-tracker
+  metadata.
 - Support environment-neutral activation and deployment.

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 NPlusInsight contributors
+Copyright (c) 2026 Jory Leech
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,70 +1,367 @@
 # NPlusInsight
 
-NPlusInsight is a Rails gem that detects repeated query
-shapes within a request and turns them into a useful debugging report:
+[![Ruby 3.1+](https://img.shields.io/badge/Ruby-3.1%2B-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![Rails 7–8](https://img.shields.io/badge/Rails-7.0%E2%80%938.x-D30001?logo=rubyonrails&logoColor=white)](https://rubyonrails.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-2563EB.svg)](LICENSE.txt)
 
-- the exact application file and line that issued the query;
-- a model/association graph for the tables involved;
-- normalized SQL, repetition count, and total query time;
-- suggested `includes` and `strict_loading` fixes.
+[Source code](https://github.com/joryleech/NPlusInsight) ·
+[Issue tracker](https://github.com/joryleech/NPlusInsight/issues) ·
+[Changelog](CHANGELOG.md)
 
-## Install
+NPlusInsight detects N+1 queries in Ruby on Rails applications and turns them
+into actionable, source-level diagnostics.
 
-Add the gem in every environment where you may enable it:
+For each finding, NPlusInsight shows:
+
+- the application file, line number, and surrounding source code;
+- the repeated SQL shape, query count, and cumulative duration;
+- the Active Record models and associations involved;
+- suggested eager-loading and strict-loading remediations;
+- an optional on-page alert and a mounted findings dashboard.
+
+NPlusInsight is environment-neutral. Enable it anywhere you need diagnostics,
+including development, test, staging, or a controlled production environment.
+
+## Table of contents
+
+- [Why NPlusInsight?](#why-nplusinsight)
+- [Screenshots](#screenshots)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Dashboard and on-page inspector](#dashboard-and-on-page-inspector)
+- [How detection works](#how-detection-works)
+- [Security and privacy](#security-and-privacy)
+- [Operational considerations](#operational-considerations)
+- [CI and test environments](#ci-and-test-environments)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Releasing](#releasing)
+- [License](#license)
+
+## Why NPlusInsight?
+
+Rails logs make repeated queries visible, but they do not always make the cause
+obvious. NPlusInsight connects runtime query evidence to the application code
+that triggered it, then presents the affected model relationship and a
+candidate fix in one place.
+
+The gem is designed to keep the feedback loop short:
+
+1. Exercise an application page.
+2. See the on-page alert when repeated query patterns are detected.
+3. Open the finding to inspect the responsible source line and model graph.
+4. Apply eager loading.
+5. Reload the page and confirm that the finding is gone.
+
+## Screenshots
+
+### On-page alert
+
+The corner indicator turns red and displays the number of N+1 query patterns
+detected while rendering the current page.
+
+![NPlusInsight on-page N+1 alert](docs/images/on-page-alert.png)
+
+### On-page findings inspector
+
+Open the indicator to inspect relevant source lines, affected models, and
+remediation suggestions without leaving the page.
+
+![NPlusInsight grouped query patterns and multi-model tree in the on-page inspector](docs/images/on-page-popout-modeled.png)
+
+### Mounted findings dashboard
+
+The mounted dashboard collects recent findings across requests for deeper
+inspection.
+
+![NPlusInsight full findings dashboard](docs/images/full-dashboard.png)
+
+## Requirements
+
+| Dependency | Supported versions |
+| --- | --- |
+| Ruby | 3.1 or newer |
+| Ruby on Rails | 7.0 through 8.x |
+| Active Record | Provided by the Rails application |
+
+## Installation
+
+Add NPlusInsight to the environments where it must be available:
 
 ```ruby
+# Gemfile
 gem "n_plus_insight"
 ```
 
-Run `bundle install`, then configure NPlusInsight for the environments where it
-should be active.
+Install dependencies:
+
+```sh
+bundle install
+```
+
+The Rails engine registers its middleware and mounts its dashboard
+automatically. No route declaration is required.
 
-Then configure activation from the environment rather than tying it to a Rails
-environment name:
+## Quick start
+
+Enable NPlusInsight in the Rails environment where you want to use it:
+
+```ruby
+# config/environments/development.rb
+NPlusInsight.configure do |config|
+  config.enabled = true
+end
+```
+
+Keep shared settings in an initializer:
+
+```ruby
+# config/initializers/n_plus_insight.rb
+NPlusInsight.configure do |config|
+  config.minimum_repetitions = 2
+  config.max_events = 100
+  config.mount_path = "/n_plus_insight"
+  config.on_page = true
+  config.raise_on_detection = false
+end
+```
+
+Start Rails, exercise the application, and visit:
+
+```text
+http://localhost:3000/n_plus_insight
+```
+
+### Environment-variable activation
+
+For containerized or remotely managed deployments, activation can be driven by
+an environment variable:
 
 ```ruby
 # config/initializers/n_plus_insight.rb
-if Rails.env.development?
-  NPlusInsight.configure do |config|
-    config.minimum_repetitions = 2
-    config.mount_path = "/n_plus_insight"
-    config.on_page = true
-    config.max_events = 100
-    config.raise_on_detection = false
-  end
+NPlusInsight.configure do |config|
+  config.enabled = ENV.fetch("NPLUS_INSIGHT_ENABLED", "false")
+    .match?(/\A(?:1|true|yes|on)\z/i)
+end
+```
+
+The gem uses the same `NPLUS_INSIGHT_ENABLED` parsing when `enabled` is not set
+explicitly. Its default value is `false`.
+
+## Configuration
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `enabled` | `NPLUS_INSIGHT_ENABLED`, otherwise `false` | Enables request-level query collection and analysis. |
+| `minimum_repetitions` | `2` | Number of matching query shapes required to create a finding. |
+| `max_events` | `100` | Maximum number of findings retained for the dashboard. The oldest findings are removed first. |
+| `mount_path` | `"/n_plus_insight"` | Path used for the mounted dashboard and overlay assets. Configure this before the application finishes booting. |
+| `on_page` | `true` | Injects the status indicator and findings inspector into HTML responses. |
+| `raise_on_detection` | `false` | Raises when a request produces at least one finding. Useful in controlled tests or CI. |
+| `ignore_paths` | Asset and Active Storage paths | Array of regular expressions for request paths that should not be analyzed. |
+| `ignore_sql` | Transactions and Rails metadata | Array of regular expressions for SQL statements that should be ignored. |
+
+### Ignoring application paths
+
+```ruby
+NPlusInsight.configure do |config|
+  config.ignore_paths += [
+    %r{\A/health\z},
+    %r{\A/metrics\z}
+  ]
 end
 ```
-With `on_page` enabled, every HTML page also gets a small status circle in the
-bottom-right corner. It turns red and shows a count when the current request
-contains N+1 query patterns. Select it to inspect source lines, the affected
-model graph, and suggested fixes without leaving the page. Set
-`config.on_page = false` to remove the on-page tool while retaining collection
-and the full dashboard.
+
+### Ignoring known query patterns
+
+```ruby
+NPlusInsight.configure do |config|
+  config.ignore_sql += [
+    /FROM "audit_events"/i
+  ]
+end
+```
+
+## Dashboard and on-page inspector
+
+### On-page inspector
+
+When `on_page` is enabled, NPlusInsight injects a small status indicator into
+HTML responses:
+
+- green means no repeated query pattern was detected for that request;
+- red means one or more patterns were detected;
+- the badge shows the number of findings;
+- selecting the indicator opens source, model, and remediation details.
+
+Set `config.on_page = false` to disable response injection while continuing to
+collect findings for the mounted dashboard.
+
+### Mounted dashboard
+
+The dashboard is available at `mount_path`, which defaults to
+`/n_plus_insight`. It lists the most recent findings stored by the current Rails
+process and links to a detailed report for each finding. Use **Clear** to remove
+all stored findings. The dashboard retains at most `max_events`
+findings, rolling off the oldest finding whenever the configured limit is
+exceeded.
 
 ## How detection works
 
-The gem listens to `sql.active_record` events during each web request. It
-removes literal values from SQL and groups matching shapes. A shape repeated at
-least `minimum_repetitions` times is reported. Framework, gem, schema, cached,
-transaction, and asset requests are excluded.
+NPlusInsight subscribes to `sql.active_record` notifications while a web
+request is being processed.
+
+For each uncached `SELECT` query, it:
 
-This deliberately reports evidence rather than patching source automatically.
-Suggested fixes should be reviewed because scopes, polymorphic associations,
-and intentionally lazy-loaded data can change the best eager-loading strategy.
+1. captures the first relevant application stack frame;
+2. extracts tables referenced by `FROM` and `JOIN`;
+3. replaces literal strings and numbers with placeholders;
+4. groups queries with the same normalized shape;
+5. keeps shapes meeting `minimum_repetitions`;
+6. combines repeated shapes attributed to the same application source line into
+   one finding;
+7. inspects Active Record reflections to infer every relevant model association;
+8. renders the affected associations as a model tree;
+9. generates combined eager-loading and strict-loading suggestions for the
+   complete tree.
 
-## CI mode
+For example, if one serializer line lazily loads both `post.comments` and
+`post.likes`, NPlusInsight reports one finding with two query patterns, a
+`Post` tree branching to `Comment` and `Like`, and a combined remediation such
+as `Post.includes(:comments, :likes)`. Deeper paths are represented with nested
+`includes`, such as `User.includes({ posts: [:comments, :likes] })`.
 
-To turn findings into failures in a test or staging environment:
+Cached queries, schema activity, Rails metadata queries, transaction statements,
+and ignored requests are excluded.
+
+NPlusInsight reports evidence and candidate remediations; it does not modify
+application source code automatically.
+
+## Security and privacy
+
+Findings can contain:
+
+- local source paths and source-code excerpts;
+- normalized SQL shapes;
+- controller paths and request methods;
+- model and association names.
+
+The dashboard is intentionally not restricted to a specific Rails environment.
+If NPlusInsight is enabled on an internet-facing deployment, protect
+`mount_path` with application authentication, a VPN, network policy, or
+reverse-proxy access controls.
+
+NPlusInsight stores findings in process memory. It does not persist findings to
+a database or transmit them to an external service.
+
+## Operational considerations
+
+- **Process-local storage:** each Rails process maintains its own findings.
+  Findings are not shared between Puma workers, containers, or hosts.
+- **Ephemeral history:** findings are cleared when the Rails process restarts.
+- **HTML buffering:** the on-page inspector buffers eligible HTML responses so
+  it can inject the overlay before `</body>`.
+- **Non-HTML responses:** JSON, files, streams, and other response types are not
+  modified.
+- **Compressed responses:** responses already carrying `Content-Encoding` are
+  not modified by the on-page inspector.
+- **Heuristic detection:** repeated queries can be intentional. Review each
+  finding before changing loading behavior.
+- **Heuristic suggestions:** polymorphic relationships, custom scopes, and
+  indirect associations may require a different preload strategy than the
+  suggested code.
+
+For high-traffic production deployments, begin with `on_page = false`, use a
+small `max_events`, and evaluate overhead under representative load.
+
+## CI and test environments
+
+Enable `raise_on_detection` to turn a finding into a request failure:
 
 ```ruby
-config.raise_on_detection = true
+# config/environments/test.rb
+NPlusInsight.configure do |config|
+  config.enabled = true
+  config.on_page = false
+  config.raise_on_detection = true
+end
 ```
 
-The dashboard is not restricted to a particular Rails environment. If it is
-enabled on an internet-facing deployment, protect `/n_plus_insight` with your
-application's authentication, authorization, VPN, or reverse-proxy access
-controls because findings contain source paths, code excerpts, and SQL shapes.
+Use this mode selectively. Test setup, factories, and intentionally repeated
+queries can otherwise produce noisy failures.
+
+## Troubleshooting
+
+### The indicator does not appear
+
+Confirm that:
+
+- `config.enabled` and `config.on_page` are both `true`;
+- the response has a `text/html` content type;
+- the response is not already compressed;
+- the request path does not match `ignore_paths`;
+- the application's Content Security Policy permits same-origin scripts and
+  styles.
+
+### The indicator is green, but repeated queries appear in the Rails log
+
+Check whether the queries:
+
+- occur fewer times than `minimum_repetitions`;
+- are served from the Active Record query cache;
+- are not `SELECT` statements;
+- match an `ignore_sql` pattern;
+- execute outside the lifecycle of an HTTP request.
+
+### The dashboard is empty in a multi-process deployment
+
+The store is process-local. A request served by one worker is not visible in a
+dashboard request served by another worker.
+
+### Findings point to the correct line but suggest the wrong association
+
+Association inference is heuristic. Use the source location, SQL shape, and
+model graph as evidence, then apply the eager-loading strategy appropriate for
+the relation that feeds that code.
+
+## Development
+
+Install dependencies and run the test suite:
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+Build the gem locally:
+
+```sh
+bundle exec rake build
+```
+
+The built package is written to `pkg/`.
+
+## Contributing
+
+[Bug reports](https://github.com/joryleech/NPlusInsight/issues/new/choose) and
+[pull requests](https://github.com/joryleech/NPlusInsight/pulls) are welcome.
+
+When proposing a change:
+
+1. include a focused reproduction or test;
+2. keep detection behavior deterministic;
+3. preserve environment-neutral configuration;
+4. verify both the mounted dashboard and on-page inspector when changing UI;
+5. run `bundle exec rake test`.
+
+Please avoid including production SQL, source code, credentials, or other
+sensitive application data in public issues.
 
 ## License
 
-MIT
+NPlusInsight is maintained by
+[Jory Leech](https://github.com/joryleech) and available under the
+[MIT License](LICENSE.txt).

data/app/assets/n_plus_insight/overlay.css

@@ -100,14 +100,22 @@
 #n1v-root .n1v-heading { margin: 0 0 8px !important; color: var(--n1v-text) !important; font: 650 13px/1.3 ui-sans-serif, system-ui, sans-serif !important; }
 #n1v-root .n1v-location { margin: 0 0 8px !important; color: var(--n1v-muted) !important; overflow-wrap: anywhere !important; font: 12px/1.4 ui-monospace, SFMono-Regular, Consolas, monospace !important; }
 #n1v-root .n1v-code { display: block !important; max-width: 100% !important; margin: 0 !important; padding: 10px 0 !important; overflow: auto !important; border-radius: 8px !important; background: var(--n1v-code) !important; color: #e4e7ec !important; font: 12px/1.5 ui-monospace, SFMono-Regular, Consolas, monospace !important; white-space: pre !important; }
+#n1v-root .n1v-code > code { display: block !important; margin: 0 !important; padding: 0 12px !important; border: 0 !important; border-radius: 0 !important; background: transparent !important; color: inherit !important; font: inherit !important; white-space: inherit !important; }
 #n1v-root .n1v-line { display: grid !important; grid-template-columns: 38px minmax(0, 1fr) !important; min-width: max-content !important; padding: 0 12px !important; }
 #n1v-root .n1v-line.n1v-active { background: rgba(217, 45, 32, .28) !important; }
 #n1v-root .n1v-line-number { color: #98a2b3 !important; user-select: none !important; }
-#n1v-root .n1v-graph { display: flex !important; align-items: center !important; gap: 7px !important; min-height: 74px !important; overflow-x: auto !important; padding: 8px 0 !important; }
-#n1v-root .n1v-node { flex: 0 0 auto !important; min-width: 130px !important; padding: 10px 12px !important; border: 1px solid var(--n1v-accent) !important; border-radius: 9px !important; background: var(--n1v-accent-soft) !important; color: var(--n1v-text) !important; text-align: center !important; }
+#n1v-root .n1v-graph { min-height: 74px !important; overflow: auto !important; padding: 4px 0 !important; }
+#n1v-root .n1v-tree { margin: 0 !important; padding: 0 !important; list-style: none !important; }
+#n1v-root .n1v-tree .n1v-tree { margin-left: 18px !important; padding-left: 18px !important; border-left: 1px solid var(--n1v-border) !important; }
+#n1v-root .n1v-tree-item { position: relative !important; margin: 9px 0 !important; list-style: none !important; }
+#n1v-root .n1v-tree .n1v-tree > .n1v-tree-item::before { content: "" !important; position: absolute !important; left: -18px !important; top: 27px !important; width: 18px !important; border-top: 1px solid var(--n1v-border) !important; }
+#n1v-root .n1v-node { display: inline-grid !important; min-width: 130px !important; padding: 10px 12px !important; border: 1px solid var(--n1v-accent) !important; border-radius: 9px !important; background: var(--n1v-accent-soft) !important; color: var(--n1v-text) !important; text-align: center !important; }
 #n1v-root .n1v-node strong, #n1v-root .n1v-node small { display: block !important; color: inherit !important; }
 #n1v-root .n1v-node small { margin-top: 2px !important; color: var(--n1v-muted) !important; font-size: 11px !important; }
-#n1v-root .n1v-edge { flex: 0 0 auto !important; color: var(--n1v-muted) !important; text-align: center !important; font-size: 11px !important; }
+#n1v-root .n1v-edge { display: block !important; margin: 0 0 4px !important; color: var(--n1v-muted) !important; font-size: 11px !important; }
+#n1v-root .n1v-query { margin: 0 !important; padding: 8px 0 !important; border-top: 1px solid var(--n1v-border) !important; }
+#n1v-root .n1v-query:first-of-type { padding-top: 0 !important; border-top: 0 !important; }
+#n1v-root .n1v-query-meta { margin: 0 0 5px !important; color: var(--n1v-muted) !important; font: 11px/1.4 ui-sans-serif, system-ui, sans-serif !important; }
 #n1v-root .n1v-fix { margin: 0 !important; padding: 12px 0 !important; border-top: 1px solid var(--n1v-border) !important; }
 #n1v-root .n1v-fix:first-of-type { padding-top: 0 !important; border-top: 0 !important; }
 #n1v-root .n1v-fix-title { margin: 0 0 4px !important; color: var(--n1v-text) !important; font: 650 13px/1.4 ui-sans-serif, system-ui, sans-serif !important; }

data/app/assets/n_plus_insight/overlay.js

@@ -23,10 +23,33 @@
     }
   }
 
+  function queryGroupsFor(finding) {
+    if ((finding.query_groups || []).length) return finding.query_groups;
+    return [{
+      sql: finding.sql,
+      query_count: finding.query_count,
+      total_ms: finding.total_ms,
+      tables: []
+    }];
+  }
+
   var findings = decodePayload(root.dataset.payload || "");
+  var initialFindingIndex = findings.reduce(function (bestIndex, finding, index) {
+    var best = findings[bestIndex];
+    var patternCount = queryGroupsFor(finding).length;
+    var bestPatternCount = best ? queryGroupsFor(best).length : -1;
+
+    if (patternCount > bestPatternCount) return index;
+    if (patternCount === bestPatternCount && finding.query_count > best.query_count) return index;
+    return bestIndex;
+  }, 0);
+  var patternCount = findings.reduce(function (total, finding) {
+    return total + queryGroupsFor(finding).length;
+  }, 0);
+
   var launcher = element("button", "n1v-launcher" + (findings.length ? " n1v-has-alert" : ""), "N+1");
   launcher.type = "button";
-  launcher.setAttribute("aria-label", findings.length ? "Open NPlusInsight: " + findings.length + " detected" : "Open NPlusInsight: no detections");
+  launcher.setAttribute("aria-label", findings.length ? "Open NPlusInsight: " + findings.length + " affected source locations" : "Open NPlusInsight: no detections");
   launcher.setAttribute("aria-expanded", "false");
 
   if (findings.length) {
@@ -44,7 +67,14 @@
   var header = element("div", "n1v-header");
   var headingWrap = element("div");
   headingWrap.appendChild(element("h2", "n1v-title", findings.length ? "N+1 detected" : "No N+1 queries"));
-  headingWrap.appendChild(element("p", "n1v-subtitle", findings.length ? findings.length + " repeated query pattern" + (findings.length === 1 ? "" : "s") + " on this page" : "This request is clear"));
+  headingWrap.appendChild(element(
+    "p",
+    "n1v-subtitle",
+    findings.length ?
+      findings.length + " affected source location" + (findings.length === 1 ? "" : "s") +
+        " · " + patternCount + " query pattern" + (patternCount === 1 ? "" : "s") :
+      "This request is clear"
+  ));
   header.appendChild(headingWrap);
 
   var close = element("button", "n1v-close", "×");
@@ -70,6 +100,7 @@
       container.appendChild(section);
       return;
     }
+
     section.appendChild(element("p", "n1v-location", finding.location.path + ":" + finding.location.line));
     var pre = element("pre", "n1v-code");
     var code = element("code");
@@ -84,22 +115,60 @@
     container.appendChild(section);
   }
 
+  function renderQueries(container, finding) {
+    var section = element("section", "n1v-section");
+    section.appendChild(element("h3", "n1v-heading", "Repeated query patterns"));
+    queryGroupsFor(finding).forEach(function (group, index) {
+      var query = element("div", "n1v-query");
+      var tables = (group.tables || []).join(", ");
+      var metadata = "Pattern " + (index + 1) + " · " + group.query_count +
+        " queries · " + group.total_ms + " ms" + (tables ? " · " + tables : "");
+      query.appendChild(element("p", "n1v-query-meta", metadata));
+      appendCode(query, group.sql);
+      section.appendChild(query);
+    });
+    container.appendChild(section);
+  }
+
+  function renderTreeNode(entry) {
+    var item = element("li", "n1v-tree-item");
+    if (entry.association) {
+      item.appendChild(element(
+        "span",
+        "n1v-edge",
+        entry.association + (entry.macro ? " (" + entry.macro + ")" : "")
+      ));
+    }
+
+    var node = element("div", "n1v-node");
+    node.appendChild(element("strong", "", entry.name));
+    node.appendChild(element("small", "", entry.table));
+    item.appendChild(node);
+
+    if ((entry.children || []).length) {
+      var children = element("ul", "n1v-tree");
+      entry.children.forEach(function (child) {
+        children.appendChild(renderTreeNode(child));
+      });
+      item.appendChild(children);
+    }
+    return item;
+  }
+
   function renderGraph(container, finding) {
     var section = element("section", "n1v-section");
-    section.appendChild(element("h3", "n1v-heading", "Affected models"));
+    section.appendChild(element("h3", "n1v-heading", "Affected model tree"));
     var graph = element("div", "n1v-graph");
     graph.setAttribute("role", "img");
-    graph.setAttribute("aria-label", "Model associations involved in the repeated query");
-    (finding.models || []).forEach(function (model, index) {
-      if (index > 0) {
-        var edge = (finding.edges || [])[index - 1];
-        graph.appendChild(element("span", "n1v-edge", (edge && edge.association ? edge.association + " " : "") + "→"));
-      }
-      var node = element("div", "n1v-node");
-      node.appendChild(element("strong", "", model.name));
-      node.appendChild(element("small", "", model.table));
-      graph.appendChild(node);
+    graph.setAttribute("aria-label", "Tree of models and associations involved in the repeated queries");
+    var tree = element("ul", "n1v-tree");
+    var roots = finding.tree || (finding.models || []).map(function (model) {
+      return { name: model.name, table: model.table, children: [] };
+    });
+    roots.forEach(function (entry) {
+      tree.appendChild(renderTreeNode(entry));
     });
+    graph.appendChild(tree);
     section.appendChild(graph);
     container.appendChild(section);
   }
@@ -112,6 +181,7 @@
       var copy = element("button", "n1v-copy", "Copy");
       copy.type = "button";
       copy.addEventListener("click", function () {
+        if (!navigator.clipboard) return;
         navigator.clipboard.writeText(suggestion.code).then(function () {
           copy.textContent = "Copied";
           window.setTimeout(function () { copy.textContent = "Copy"; }, 1200);
@@ -136,7 +206,12 @@
       var tabs = element("div", "n1v-tabs");
       tabs.setAttribute("role", "tablist");
       findings.forEach(function (finding, tabIndex) {
-        var tab = element("button", "n1v-tab", "#" + (tabIndex + 1) + " · " + finding.query_count + " queries");
+        var groupCount = queryGroupsFor(finding).length;
+        var tab = element(
+          "button",
+          "n1v-tab",
+          "#" + (tabIndex + 1) + " · " + groupCount + " pattern" + (groupCount === 1 ? "" : "s")
+        );
         tab.type = "button";
         tab.setAttribute("role", "tab");
         tab.setAttribute("aria-selected", String(tabIndex === index));
@@ -149,6 +224,7 @@
     var finding = findings[index];
     renderSource(body, finding);
     renderGraph(body, finding);
+    renderQueries(body, finding);
     renderFixes(body, finding);
   }
 
@@ -167,7 +243,7 @@
     if (event.key === "Escape" && panel.getAttribute("aria-hidden") === "false") setOpen(false);
   });
 
-  renderFinding(0);
+  renderFinding(initialFindingIndex);
   root.appendChild(panel);
   root.appendChild(launcher);
 }());

data/app/controllers/n_plus_insight/detections_controller.rb

@@ -8,5 +8,10 @@ module NPlusInsight
       @detection = Store.find(params[:id])
       return head :not_found unless @detection
     end
+
+    def clear
+      Store.clear
+      redirect_to root_path, status: :see_other, notice: "Stored detections cleared."
+    end
   end
 end

data/app/views/layouts/n_plus_insight/application.html.erb

@@ -19,21 +19,38 @@
       .list { display:grid; gap:12px; } .card { display:block; background:var(--panel); border:1px solid var(--line); border-radius:12px; padding:18px; color:var(--text); text-decoration:none; }
       .card:hover { border-color:var(--accent); } .row { display:flex; align-items:flex-start; justify-content:space-between; gap:16px; }
       .badge { display:inline-flex; padding:2px 8px; border-radius:999px; background:var(--accent-soft); color:var(--text); font-size:12px; }
+      .dashboard-actions { display:flex; align-items:center; gap:10px; }
+      .button { appearance:none; border:1px solid var(--line); border-radius:8px; padding:7px 11px; background:var(--panel); color:var(--text); cursor:pointer; font:600 13px/1 ui-sans-serif,system-ui,-apple-system,sans-serif; }
+      .button:hover { border-color:var(--bad); color:var(--bad); }
+      .button:disabled { cursor:not-allowed; opacity:.5; }
+      .notice { margin:0 0 18px; padding:10px 12px; border:1px solid var(--accent); border-radius:8px; background:var(--accent-soft); }
       .danger { color:var(--bad); font-weight:650; } .meta { display:flex; flex-wrap:wrap; gap:8px 18px; color:var(--muted); font-size:13px; }
       .grid { display:grid; grid-template-columns:minmax(0,1.25fr) minmax(280px,.75fr); gap:20px; align-items:start; }
       .stack { display:grid; gap:16px; } section { background:var(--panel); border:1px solid var(--line); border-radius:12px; padding:20px; }
       pre { margin:0; overflow:auto; padding:14px; border-radius:8px; background:var(--code); color:#e5e7eb; font:13px/1.55 ui-monospace,SFMono-Regular,Consolas,monospace; }
       .source { padding:0; } .source div { display:grid; grid-template-columns:44px 1fr; padding:1px 14px; }
       .source div.active { background:rgba(180,35,24,.28); } .source b { color:#9ca3af; font-weight:400; user-select:none; }
-      .graph { width:100%; min-height:240px; } .graph line { stroke:var(--line); stroke-width:2; }
-      .graph rect { fill:var(--accent-soft); stroke:var(--accent); } .graph text { fill:var(--text); font:13px ui-sans-serif,system-ui; }
+      .query-pattern + .query-pattern { border-top:1px solid var(--line); padding-top:18px; margin-top:18px; }
+      .query-pattern h3 { margin-bottom:8px; }
+      .tree-wrap { overflow:auto; padding:4px 0; }
+      .model-tree { list-style:none; margin:0; padding:0; }
+      .model-tree .model-tree { margin-left:22px; padding-left:20px; border-left:1px solid var(--line); }
+      .model-tree li { position:relative; margin:12px 0; }
+      .model-tree .model-tree > li::before { content:""; position:absolute; left:-20px; top:30px; width:20px; border-top:1px solid var(--line); }
+      .tree-node { display:inline-grid; min-width:170px; padding:10px 12px; border:1px solid var(--accent); border-radius:9px; background:var(--accent-soft); text-align:center; }
+      .tree-node strong,.tree-node small { display:block; }
+      .tree-node small { color:var(--muted); }
+      .tree-edge { display:block; margin:0 0 5px; color:var(--muted); font-size:12px; }
       .suggestion + .suggestion { border-top:1px solid var(--line); padding-top:18px; margin-top:18px; }
       .crumb { display:inline-block; margin-bottom:18px; }
       @media (max-width:760px) { .grid { grid-template-columns:1fr; } main, header div { width:min(100% - 20px,1120px); } .row { flex-direction:column; } }
     </style>
   </head>
   <body>
-    <header><div><a class="brand" href="<%= root_path %>">NPlusInsight</a><span class="badge">Development only</span></div></header>
-    <main><%= yield %></main>
+    <header><div><a class="brand" href="<%= root_path %>">NPlusInsight</a><span class="badge">Active</span></div></header>
+    <main>
+      <% if notice %><p class="notice"><%= notice %></p><% end %>
+      <%= yield %>
+    </main>
   </body>
 </html>

data/app/views/n_plus_insight/detections/index.html.erb

@@ -1,9 +1,17 @@
 <div class="row">
   <div>
     <h1>Detected N+1 queries</h1>
-    <p class="muted">Repeated query shapes grouped by request, with the application frame that triggered them.</p>
+    <p class="muted">Repeated query patterns grouped by request and source location.</p>
+  </div>
+  <div class="dashboard-actions">
+    <span class="badge"><%= @detections.length %> finding<%= "s" unless @detections.one? %></span>
+    <%= button_to "Clear",
+      clear_detections_path,
+      method: :delete,
+      class: "button",
+      disabled: @detections.empty?,
+      form: { onsubmit: "return window.confirm('Clear all stored N+1 detections?')" } %>
   </div>
-  <span class="badge"><%= @detections.length %> finding<%= "s" unless @detections.one? %></span>
 </div>
 
 <% if @detections.empty? %>
@@ -17,14 +25,18 @@
       <a class="card" href="<%= detection_path(detection.id) %>">
         <div class="row">
           <div>
-            <div><span class="danger"><%= detection.query_count %> repeated queries</span> on <strong><%= detection.method %> <%= detection.path %></strong></div>
+            <div>
+              <span class="danger"><%= detection.query_count %> repeated queries</span>
+              across <%= detection.query_groups.length %> pattern<%= "s" unless detection.query_groups.one? %>
+              on <strong><%= detection.method %> <%= detection.path %></strong>
+            </div>
             <div class="meta">
               <span><%= detection.total_ms %> ms</span>
               <% if detection.location %><span><%= detection.location.path %>:<%= detection.location.line %></span><% end %>
-              <span><%= detection.models.map { |model| model[:name] }.join(" → ") %></span>
+              <span><%= detection.models.map { |model| model[:name] }.join(", ") %></span>
             </div>
           </div>
-          <span aria-hidden="true">→</span>
+          <span aria-hidden="true">&rarr;</span>
         </div>
       </a>
     <% end %>

data/app/views/n_plus_insight/detections/show.html.erb

@@ -1,8 +1,13 @@
-<a class="crumb" href="<%= root_path %>">← All detections</a>
+<a class="crumb" href="<%= root_path %>">&larr; All detections</a>
 <div class="row">
   <div>
     <h1><%= @detection.method %> <%= @detection.path %></h1>
-    <p class="muted"><%= @detection.query_count %> repeated queries · <%= @detection.total_ms %> ms total · <%= @detection.created_at %></p>
+    <p class="muted">
+      <%= @detection.query_count %> repeated queries
+      &middot; <%= @detection.query_groups.length %> query pattern<%= "s" unless @detection.query_groups.one? %>
+      &middot; <%= @detection.total_ms %> ms total
+      &middot; <%= @detection.created_at %>
+    </p>
   </div>
   <span class="badge">N+1 detected</span>
 </div>
@@ -15,13 +20,24 @@
         <p><%= @detection.location.path %>:<%= @detection.location.line %></p>
         <pre class="source"><% @detection.location.snippet.each do |line| %><div class="<%= "active" if line[:active] %>"><b><%= line[:line] %></b><span><%= line[:text] %></span></div><% end %></pre>
       <% else %>
-        <p class="muted">The query was captured, but no application stack frame was available.</p>
+        <p class="muted">The queries were captured, but no application stack frame was available.</p>
       <% end %>
     </section>
 
     <section>
-      <h2>Repeated SQL shape</h2>
-      <pre><%= @detection.sql %></pre>
+      <h2>Repeated query patterns</h2>
+      <div class="query-patterns">
+        <% @detection.query_groups.each_with_index do |group, index| %>
+          <div class="query-pattern">
+            <div class="row">
+              <h3>Pattern <%= index + 1 %></h3>
+              <span class="badge"><%= group[:query_count] %> queries &middot; <%= group[:total_ms] %> ms</span>
+            </div>
+            <p class="muted"><%= group[:tables].join(", ") %></p>
+            <pre><%= group[:sql] %></pre>
+          </div>
+        <% end %>
+      </div>
     </section>
 
     <section>
@@ -37,20 +53,29 @@
   </div>
 
   <section>
-    <h2>Affected model graph</h2>
-    <% models = @detection.models.presence || [{ name: "Unknown model", table: "unknown" }] %>
-    <% height = [models.length * 100, 240].max %>
-    <svg class="graph" viewBox="0 0 360 <%= height %>" role="img" aria-label="Models involved in the repeated query">
-      <% models.each_with_index do |model, index| %>
-        <% y = 25 + index * 100 %>
-        <% if index.positive? %><line x1="180" y1="<%= y - 50 %>" x2="180" y2="<%= y %>"/><% end %>
-        <rect x="70" y="<%= y %>" width="220" height="58" rx="9"/>
-        <text x="180" y="<%= y + 25 %>" text-anchor="middle"><%= model[:name] %></text>
-        <text x="180" y="<%= y + 44 %>" text-anchor="middle" opacity=".65"><%= model[:table] %></text>
+    <h2>Affected model tree</h2>
+    <% render_tree = lambda do |nodes| %>
+      <% content_tag(:ul, class: "model-tree") do %>
+        <% safe_join(nodes.map do |node| %>
+          <% content_tag(:li) do %>
+            <% parts = [] %>
+            <% if node[:association] %>
+              <% parts << content_tag(:span, "#{node[:association]} (#{node[:macro]})", class: "tree-edge") %>
+            <% end %>
+            <% parts << content_tag(:div, class: "tree-node") do %>
+              <% safe_join([
+                content_tag(:strong, node[:name]),
+                content_tag(:small, node[:table])
+              ]) %>
+            <% end %>
+            <% parts << render_tree.call(node[:children]) if node[:children].any? %>
+            <% safe_join(parts) %>
+          <% end %>
+        <% end) %>
       <% end %>
-      <% @detection.edges.each_with_index do |edge, index| %>
-        <text x="190" y="<%= 20 + (index + 1) * 100 %>" opacity=".7"><%= edge[:association] %></text>
-      <% end %>
-    </svg>
+    <% end %>
+    <div class="tree-wrap" role="img" aria-label="Tree of models and associations involved in the repeated queries">
+      <%= render_tree.call(@detection.tree) %>
+    </div>
   </section>
 </div>

data/config/routes.rb

@@ -2,5 +2,6 @@ NPlusInsight::Engine.routes.draw do
   root "detections#index"
   get "assets/overlay.css", to: "assets#stylesheet"
   get "assets/overlay.js", to: "assets#script"
+  delete "detections", to: "detections#clear", as: :clear_detections
   resources :detections, only: [:show]
 end

data/lib/n_plus_insight/analyzer.rb

@@ -6,24 +6,45 @@ module NPlusInsight
     end
 
     def call
-      groups = @queries.group_by(&:binds_signature)
-      groups.filter_map do |_shape, queries|
-        next if queries.length < NPlusInsight.configuration.minimum_repetitions
-        build_detection(queries)
+      repeated_shapes = @queries.group_by { |query| repeated_shape_key(query) }.values.select do |queries|
+        queries.length >= NPlusInsight.configuration.minimum_repetitions
       end
+
+      repeated_shapes
+        .group_by { |queries| location_key(dominant_location(queries), queries.first.binds_signature) }
+        .map { |_key, query_groups| build_detection(query_groups) }
     end
 
     private
 
-    def build_detection(queries)
-      tables = queries.flat_map(&:tables).uniq
-      model_map = model_map_for(tables)
-      location = queries.filter_map(&:location).group_by { |item| [item.path, item.line] }.max_by { |_key, values| values.length }&.last&.first
-      inferred = infer_owner(model_map.values, location)
-      graph_models = ([inferred&.fetch(:owner, nil)] + model_map.values).compact.uniq
-      models = graph_models.map { |model| { table: model.table_name, name: model.name, primary: tables.include?(model.table_name) } }
-      models = tables.map { |table| { table: table, name: table.classify, primary: true } } if models.empty?
-      edges = inferred ? [{ from: inferred[:owner].name, to: inferred[:target].name, association: inferred[:reflection].name, macro: inferred[:reflection].macro }] : association_edges(model_map)
+    def repeated_shape_key(query)
+      location = query.location
+      [query.binds_signature, location&.path, location&.line]
+    end
+
+    def build_detection(query_groups)
+      location = dominant_location(query_groups.flatten)
+      graph_models = {}
+      graph_edges = []
+
+      serialized_groups = query_groups.map do |queries|
+        tables = queries.flat_map(&:tables).uniq
+        model_map = model_map_for(tables)
+        inferred = infer_owner(model_map.values, location)
+
+        add_models(graph_models, tables, model_map, inferred)
+        graph_edges.concat(edges_for(model_map, inferred))
+
+        {
+          sql: queries.first.normalized_sql,
+          query_count: queries.length,
+          total_ms: queries.sum(&:duration_ms).round(2),
+          tables: tables
+        }
+      end
+
+      edges = graph_edges.uniq { |edge| [edge[:from], edge[:to], edge[:association]] }
+      models = graph_models.values
 
       Detection.new(
         id: SecureRandom.uuid,
@@ -31,19 +52,73 @@ module NPlusInsight
         method: @request[:method],
         path: @request[:path],
         created_at: Time.now.utc.iso8601,
-        query_count: queries.length,
-        total_ms: queries.sum(&:duration_ms).round(2),
-        sql: queries.first.normalized_sql,
+        query_count: serialized_groups.sum { |group| group[:query_count] },
+        total_ms: serialized_groups.sum { |group| group[:total_ms] }.round(2),
+        sql: serialized_groups.first[:sql],
+        query_groups: serialized_groups,
         location: location,
         models: models,
         edges: edges,
-        suggestions: suggestions(model_map, tables, location, inferred)
+        tree: build_forest(models, edges),
+        suggestions: suggestions(edges, location)
       )
     end
 
+    def dominant_location(queries)
+      queries
+        .filter_map(&:location)
+        .group_by { |item| [item.path, item.line] }
+        .max_by { |_key, values| values.length }
+        &.last
+        &.first
+    end
+
+    def location_key(location, fallback)
+      location ? [location.path, location.line] : [:query_shape, fallback]
+    end
+
+    def add_models(graph_models, tables, model_map, inferred)
+      tables.each do |table|
+        model = model_map[table]
+        name = model&.name || table.classify
+        graph_models[name] ||= { table: table, name: name, primary: false }
+        graph_models[name][:primary] = true
+      end
+
+      return unless inferred
+
+      [inferred[:owner], inferred[:target]].each do |model|
+        graph_models[model.name] ||= {
+          table: model.table_name,
+          name: model.name,
+          primary: tables.include?(model.table_name)
+        }
+      end
+    end
+
+    def edges_for(model_map, inferred)
+      if inferred
+        [{
+          from: inferred[:owner].name,
+          to: inferred[:target].name,
+          association: inferred[:reflection].name,
+          macro: inferred[:reflection].macro
+        }]
+      else
+        association_edges(model_map)
+      end
+    end
+
     def model_map_for(tables)
       return {} unless defined?(ActiveRecord::Base)
-      Rails.application.eager_load! if Rails.application.config.eager_load && ActiveRecord::Base.descendants.empty?
+
+      if defined?(Rails) &&
+          Rails.respond_to?(:application) &&
+          Rails.application&.config&.eager_load &&
+          ActiveRecord::Base.descendants.empty?
+        Rails.application.eager_load!
+      end
+
       ActiveRecord::Base.descendants.each_with_object({}) do |model, map|
         map[model.table_name] = model unless model.abstract_class?
       rescue StandardError
@@ -56,13 +131,20 @@ module NPlusInsight
         model.reflect_on_all_associations.filter_map do |reflection|
           target = reflection.klass rescue nil
           next unless target && model_map.value?(target)
-          { from: model.name, to: target.name, association: reflection.name, macro: reflection.macro }
+
+          {
+            from: model.name,
+            to: target.name,
+            association: reflection.name,
+            macro: reflection.macro
+          }
         end
       end.uniq
     end
 
     def infer_owner(targets, location)
       return unless defined?(ActiveRecord::Base)
+
       candidates = ActiveRecord::Base.descendants.flat_map do |owner|
         owner.reflect_on_all_associations.filter_map do |reflection|
           target = reflection.klass rescue nil
@@ -71,47 +153,113 @@ module NPlusInsight
       rescue StandardError
         []
       end
+
       source = location&.snippet.to_a.map { |line| line[:text] }.join(" ")
       receiver_match = candidates.find do |item|
         owner_name = item[:owner].model_name.element
         association_name = item[:reflection].name
         source.match?(/(?:@|\b)#{Regexp.escape(owner_name)}\.#{Regexp.escape(association_name.to_s)}\b/i)
       end
+
       receiver_match ||
-        candidates.find { |item| source.match?(/\b#{Regexp.escape(item[:reflection].name.to_s)}\b/) } ||
-        candidates.first
+        candidates.find do |item|
+          source.match?(/\.\s*#{Regexp.escape(item[:reflection].name.to_s)}\b/)
+        end ||
+        candidates.min_by { |item| item[:reflection].macro == :belongs_to ? 1 : 0 }
+    end
+
+    def build_forest(models, edges)
+      models_by_name = models.to_h { |model| [model[:name], model] }
+      children = edges.group_by { |edge| edge[:from] }
+      child_names = edges.map { |edge| edge[:to] }
+      roots = models.map { |model| model[:name] }.reject { |name| child_names.include?(name) }
+      roots = [models.first[:name]] if roots.empty? && models.any?
+
+      roots.filter_map do |name|
+        build_tree_node(name, models_by_name, children, [])
+      end
+    end
+
+    def build_tree_node(name, models_by_name, children, ancestors, association = nil, macro = nil)
+      return if ancestors.include?(name)
+
+      model = models_by_name[name] || { name: name, table: name.to_s.tableize }
+      next_ancestors = ancestors + [name]
+      {
+        name: model[:name],
+        table: model[:table],
+        association: association,
+        macro: macro,
+        children: children.fetch(name, []).filter_map do |edge|
+          build_tree_node(
+            edge[:to],
+            models_by_name,
+            children,
+            next_ancestors,
+            edge[:association],
+            edge[:macro]
+          )
+        end
+      }
     end
 
-    def suggestions(model_map, tables, location, inferred)
-      edges = inferred ? [{ from: inferred[:owner].name, association: inferred[:reflection].name }] : association_edges(model_map)
-      association = edges.first&.fetch(:association, nil)
-      owner = edges.first&.fetch(:from, nil)
-      relation = owner || "ParentModel"
-      eager_load = association ? "#{relation}.includes(:#{association})" : "ParentModel.includes(:association)"
+    def suggestions(edges, location)
+      roots = (edges.map { |edge| edge[:from] } - edges.map { |edge| edge[:to] }).uniq
+      roots = [edges.first[:from]] if roots.empty? && edges.any?
+      eager_load = roots.map { |root| eager_load_for(root, edges) }.compact.join("\n")
+      eager_load = "ParentModel.includes(:association)" if eager_load.empty?
+      strict_loading = roots.any? ? roots.map { |root| "#{root}.strict_loading" }.join("\n") : "ParentModel.strict_loading"
+      association_count = edges.map { |edge| [edge[:from], edge[:association]] }.uniq.length
 
       results = [
         {
-          title: "Eager-load the association",
+          title: association_count > 1 ? "Eager-load all affected associations" : "Eager-load the association",
           code: eager_load,
-          explanation: "Load related rows in a bounded number of queries before the loop renders them.",
-          confidence: association ? "high" : "medium"
+          explanation: association_count > 1 ?
+            "Preload the complete association tree before this source line executes." :
+            "Load related rows in a bounded number of queries before the loop renders them.",
+          confidence: edges.any? ? "high" : "medium"
         },
         {
           title: "Use strict loading to prevent regressions",
-          code: "#{relation}.strict_loading",
+          code: strict_loading,
           explanation: "Rails will raise when code lazily loads an association that was not preloaded.",
           confidence: "medium"
         }
       ]
+
       if location
         results.unshift(
-          title: "Change the relation feeding this line",
+          title: association_count > 1 ? "Change the relation feeding this call site" : "Change the relation feeding this line",
           code: "# #{location.path}:#{location.line}\n#{eager_load}",
-          explanation: "Apply eager loading where the parent relation is constructed, not inside the iteration.",
-          confidence: association ? "high" : "medium"
+          explanation: "Apply eager loading where the root relation is constructed, not inside the iteration.",
+          confidence: edges.any? ? "high" : "medium"
         )
       end
+
       results
     end
+
+    def eager_load_for(root, edges)
+      children = edges.group_by { |edge| edge[:from] }
+      associations = format_associations(root, children, [])
+      return if associations.empty?
+
+      "#{root}.includes(#{associations.join(', ')})"
+    end
+
+    def format_associations(model_name, children, ancestors)
+      return [] if ancestors.include?(model_name)
+
+      children.fetch(model_name, []).map do |edge|
+        nested = format_associations(edge[:to], children, ancestors + [model_name])
+        if nested.empty?
+          ":#{edge[:association]}"
+        else
+          value = nested.one? ? nested.first : "[#{nested.join(', ')}]"
+          "{ #{edge[:association]}: #{value} }"
+        end
+      end
+    end
   end
 end

data/lib/n_plus_insight/detection.rb

@@ -1,7 +1,8 @@
 module NPlusInsight
   Detection = Struct.new(
     :id, :request_id, :method, :path, :created_at, :query_count, :total_ms,
-    :sql, :location, :models, :edges, :suggestions, keyword_init: true
+    :sql, :query_groups, :location, :models, :edges, :tree, :suggestions,
+    keyword_init: true
   ) do
     def as_json(*)
       members.to_h { |member| [member, public_send(member)] }

data/lib/n_plus_insight/overlay.rb

@@ -22,9 +22,11 @@ module NPlusInsight
           query_count: detection.query_count,
           total_ms: detection.total_ms,
           sql: detection.sql,
+          query_groups: detection.query_groups,
           location: detection.location&.as_json,
           models: detection.models,
           edges: detection.edges,
+          tree: detection.tree,
           suggestions: detection.suggestions
         }
       end

data/lib/n_plus_insight/version.rb

@@ -1,3 +1,3 @@
 module NPlusInsight
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: n_plus_insight
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
-- NPlusInsight contributors
+- Jory Leech
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -30,10 +30,11 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
-description: A Rails engine that detects repeated query shapes per request, pinpoints
-  the application code responsible, visualizes affected Active Record models, and
-  recommends eager-loading fixes.
+description: A Rails engine that groups N+1 query patterns by source line, visualizes
+  affected Active Record associations as trees in an on-page inspector and dashboard,
+  and recommends eager-loading fixes.
 email:
+- joryleech@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -41,7 +42,6 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- RELEASING.md
 - app/assets/n_plus_insight/overlay.css
 - app/assets/n_plus_insight/overlay.js
 - app/controllers/n_plus_insight/application_controller.rb
@@ -51,6 +51,9 @@ files:
 - app/views/n_plus_insight/detections/index.html.erb
 - app/views/n_plus_insight/detections/show.html.erb
 - config/routes.rb
+- docs/images/full-dashboard.png
+- docs/images/on-page-alert.png
+- docs/images/on-page-popout-modeled.png
 - lib/n_plus_insight.rb
 - lib/n_plus_insight/analyzer.rb
 - lib/n_plus_insight/configuration.rb
@@ -64,12 +67,17 @@ files:
 - lib/n_plus_insight/store.rb
 - lib/n_plus_insight/subscriber.rb
 - lib/n_plus_insight/version.rb
-homepage:
+homepage: https://github.com/joryleech/NPlusInsight
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/joryleech/NPlusInsight
+  source_code_uri: https://github.com/joryleech/NPlusInsight/tree/master
+  documentation_uri: https://github.com/joryleech/NPlusInsight/blob/master/README.md
+  changelog_uri: https://github.com/joryleech/NPlusInsight/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/joryleech/NPlusInsight/issues
 post_install_message:
 rdoc_options: []
 require_paths:

data/RELEASING.md

@@ -1,47 +0,0 @@
-# Releasing NPlusInsight
-
-## First release
-
-1. Create or sign in to your account at https://rubygems.org.
-2. Enable MFA for the account.
-3. Confirm that `n_plus_insight` is still available:
-
-   ```sh
-   gem search --remote --exact n_plus_insight
-   ```
-
-   No output means there is no published gem with that exact name.
-
-4. Authenticate without putting an API key in the repository:
-
-   ```sh
-   gem signin
-   ```
-
-5. Run the tests and build the package:
-
-   ```sh
-   bundle install
-   bundle exec rake test
-   bundle exec rake build
-   ```
-
-6. Publish the built package:
-
-   ```sh
-   gem push pkg/n_plus_insight-0.1.0.gem
-   ```
-
-7. Verify the release:
-
-   ```sh
-   gem info n_plus_insight --remote
-   ```
-
-## Later releases
-
-Update `NPlusInsight::VERSION` in `lib/n_plus_insight/version.rb`, add the
-release notes to `CHANGELOG.md`, rerun the tests, build, and push the new
-version. RubyGems does not allow replacing an existing version.
-
-Never commit `.gem/credentials`, an API key, or an OTP recovery code.