rails_vitals 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85f8d6772f3f10badb2a598143172c1e11375eb017affe72007fe893e2f6d241
-  data.tar.gz: 072320c0d3826677abacc3d36cbfd22843be687a955e41c9f924cb07bba640f0
+  metadata.gz: 0e310ba646b2f5168dec1765754ead900d1341fcfb229820afc9c75e4e6be8fb
+  data.tar.gz: a38f8d572a5b5a00a45d21239d9b07669c9dca818f7d75bcd9d7d9cfeea06e79
 SHA512:
-  metadata.gz: d6648831e36ed7b41615af2636939d1f1dace58b270a311486820ee5d9e48581a5d617d590622855dbf6430dfdbc3ed1716721bb6d03f58e1af8dda8a2fcd969
-  data.tar.gz: 204fab1e081f960f358295b56f42666800867133c14eafdcc6074524694110a5de0cef994e65647f504ffea3d90aab42620b861ce1c00e3de31b32e929c40278
+  metadata.gz: c5708c964e928d6400375f2e1d98024a05f9e089066fb3fb65c32ae61c39cbb69a4589d4ed901cbb6a8e491657ec438ec60b419dbff27bbdfbef9d8517c789b3
+  data.tar.gz: 88155cc28f07138987841604882c728068c9031fb25566ac8fc00efc824e3139a77352fd109a42b1d6861db466d1aae9dab2920412a860947de651456fb0d486

data/README.md

@@ -61,6 +61,11 @@ Any `SELECT` query in Request Detail can be sent directly to PostgreSQL's `EXPLA
 
 ![EXPLAIN Visualizer](https://github.com/user-attachments/assets/e3547822-17ce-40e8-a468-714bbff01cd9)
 
+### 🧪 N+1 Fix Playground
+Try eager-loading fixes against your real app data before changing application code. Enter any ActiveRecord expression such as `Post.includes(:likes)`, optionally simulate association access to reproduce N+1 behavior, and RailsVitals runs it in a read-only sandbox with a 100-record cap and 2s timeout. Each run compares before vs. after score, query count, duration, and N+1 count, then shows the exact SQL fired with full Query DNA so you can verify that the fix actually batches queries.
+
+![Playground](https://github.com/user-attachments/assets/7df1bfbe-1576-4048-810d-465e52115d19)
+
 ### 🎭 Callback Map
 Every ActiveRecord callback (`before_save`, `after_create`, `before_validation`, etc.) is timed and grouped by model in the Request Detail view. Expensive callbacks surface immediately — including hidden side effects like callbacks that trigger additional queries.
 
@@ -149,6 +154,7 @@ Navigate to `/rails_vitals` to access the full admin interface.
 | N+1 Patterns | `/rails_vitals/n_plus_ones` | Cross-request N+1 aggregation with fix suggestions |
 | Association Map | `/rails_vitals/associations` | Live SVG model graph with N+1 and index annotations |
 | EXPLAIN Visualizer | `/rails_vitals/requests/:request_id/explain/:query_index` | Interactive PostgreSQL EXPLAIN ANALYZE tree with warnings and fix suggestions |
+| Playground | `/rails_vitals/playgrounds` | Read-only sandbox for testing eager-loading fixes against real app data |
 
 ---
 
@@ -276,12 +282,21 @@ rails_vitals/
         ├── models/
         ├── n_plus_ones/
         ├── associations/
-        └── live/
+        ├── explains/
+        ├── playgrounds/
+        └── shared/                            # Reusable partials
+            ├── _page_header.html.erb
+            ├── _empty_state.html.erb
+            ├── _score_badge.html.erb
+            └── _n1_indicator.html.erb
 ```
 
 **Key architectural decisions:**
 
 - **Zero JS dependencies** — no Chartkick, no D3, no Chart.js. Tables for data, SVG for diagrams, vanilla JS for interactions.
+- **Single CSS/JS asset file** — all styles in `app/assets/stylesheets/rails_vitals/application.css`, all behaviour in `app/assets/javascripts/rails_vitals/application.js`. No inline `<style>` or `<script>` blocks in views.
+- **Shared view partials** — common UI patterns (`_page_header`, `_empty_state`, `_score_badge`, `_n1_indicator`) live in `app/views/rails_vitals/shared/` and are reused across all views.
+- **Centralised helpers** — all color logic, heat colors, and formatting live in `ApplicationHelper`. Views never define inline color hashes or call `.round(1).to_s + "ms"` directly; they use `format_ms()`, `risk_color()`, `badge_class()`, etc.
 - **Thread-local Collector** — instrumentation state is stored per-thread, never shared between concurrent requests.
 - **In-memory ring buffer** — the Store keeps the last N requests in memory. No database writes, no schema migrations.
 - **Module prepend for callbacks** — callback instrumentation wraps `ActiveRecord::Base#run_callbacks` via `Module#prepend`. No TracePoint, no monkey-patching.

data/app/assets/javascripts/rails_vitals/application.js

@@ -159,3 +159,32 @@ function badge(color, text) {
          'font-size:9px;padding:1px 5px;border-radius:3px;margin-left:4px;">' +
          text + '</span>';
 }
+
+// ─── playgrounds/index ───────────────────────────────────────────────────────
+(function () {
+  var form = document.getElementById('playground-form');
+  if (!form) return;
+
+  // Disable the run button on submit to prevent double-runs
+  form.addEventListener('submit', function () {
+    var btn = document.getElementById('run-btn');
+    if (btn) {
+      btn.disabled    = true;
+      btn.textContent = '⏳ Running...';
+    }
+  });
+
+  // Pre-fill expression textarea from ?expression= URL param (deep-link from N+1 page)
+  var params = new URLSearchParams(window.location.search);
+  var expr   = params.get('expression');
+  if (expr) {
+    var ta = document.querySelector("textarea[name='expression']");
+    if (ta) ta.value = decodeURIComponent(expr);
+  }
+}());
+
+function toggleAssocLabel(assoc, checked) {
+  var label = document.getElementById('label_' + assoc);
+  if (!label) return;
+  label.classList.toggle('assoc-tag-active', checked);
+}

data/app/assets/stylesheets/rails_vitals/application.css

@@ -276,6 +276,7 @@ tr:hover td { background: #1e2535; }
 
 /* ─── Component utilities ──────────────────────────────────────────────────── */
 .section-label {
+  display: block;
   color: #a0aec0;
   font-size: 11px;
   font-weight: bold;
@@ -353,3 +354,191 @@ tr:hover td { background: #1e2535; }
   margin-right: 4px;
   vertical-align: middle;
 }
+
+/* ─── Gap utilities ──────────────────────────────────────────────────────────── */
+.gap-4  { gap: 4px; }
+.gap-6  { gap: 6px; }
+.gap-8  { gap: 8px; }
+.gap-12 { gap: 12px; }
+.gap-16 { gap: 16px; }
+.gap-24 { gap: 24px; }
+
+/* ─── Grid utilities ─────────────────────────────────────────────────────────── */
+.grid-5 {
+  display: grid;
+  grid-template-columns: repeat(5, 1fr);
+  gap: 12px;
+  margin-bottom: 24px;
+}
+
+.grid-4 {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 12px;
+  margin-bottom: 20px;
+}
+
+/* ─── Stat box variant (dark surface) ───────────────────────────────────────── */
+.stat-grid-box {
+  background: #2d3748;
+  border-radius: 6px;
+  padding: 16px;
+  text-align: center;
+}
+
+/* ─── Playground ─────────────────────────────────────────────────────────────── */
+.run-btn {
+  background: #2d6a2d;
+  border: 1px solid #68d391;
+  color: #68d391;
+  padding: 10px 24px;
+  border-radius: 6px;
+  font-size: 14px;
+  font-weight: bold;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+.run-btn:hover    { background: #3a8a3a; }
+.run-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+
+@keyframes fadeIn {
+  from { opacity: 0; transform: translateY(6px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+.result-fade { animation: fadeIn 0.3s ease forwards; }
+
+.playground-textarea {
+  width: 100%;
+  background: #1a202c;
+  border: 1px solid #4a5568;
+  color: #e2e8f0;
+  padding: 12px;
+  border-radius: 4px;
+  font-family: ui-monospace, monospace;
+  font-size: 13px;
+  resize: vertical;
+  box-sizing: border-box;
+}
+
+.assoc-tag {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  background: #2d3748;
+  border: 1px solid #4a5568;
+  border-radius: 4px;
+  padding: 6px 12px;
+  cursor: pointer;
+  font-size: 12px;
+  font-family: ui-monospace, monospace;
+  color: #e2e8f0;
+  transition: background 0.15s;
+}
+.assoc-tag-active {
+  background: #1a2d1a;
+  border-color: rgba(104, 211, 145, 0.4);
+}
+
+.assoc-pill {
+  background: #2d3748;
+  color: #a0aec0;
+  font-size: 10px;
+  font-family: ui-monospace, monospace;
+  padding: 2px 6px;
+  border-radius: 3px;
+}
+.assoc-pill-active {
+  background: #1a3a1a;
+  color: #68d391;
+  font-size: 10px;
+  font-family: ui-monospace, monospace;
+  padding: 2px 6px;
+  border-radius: 3px;
+}
+
+.compare-box {
+  background: #1a202c;
+  border-radius: 6px;
+  padding: 12px 16px;
+}
+.compare-box-after {
+  background: #1a2d1a;
+  border-radius: 6px;
+  padding: 12px 16px;
+}
+
+.compare-arrow { text-align: center; }
+.compare-delta {
+  font-size: 12px;
+  font-family: ui-monospace, monospace;
+  font-weight: bold;
+}
+
+.stat-value-22 {
+  font-size: 22px;
+  font-weight: bold;
+  font-family: ui-monospace, monospace;
+}
+
+.summary-line {
+  margin-top: 12px;
+  padding: 10px 16px;
+  background: #1a202c;
+  border-radius: 4px;
+  font-size: 13px;
+  font-family: ui-monospace, monospace;
+}
+
+.error-card {
+  background: #2d1515;
+  border: 1px solid rgba(252, 129, 129, 0.4);
+  border-radius: 6px;
+  padding: 16px;
+  color: #fc8181;
+  font-size: 13px;
+  margin-bottom: 20px;
+}
+
+.n1-alert {
+  background: #2d1515;
+  border: 1px solid rgba(252, 129, 129, 0.27);
+  border-radius: 6px;
+  padding: 12px 16px;
+  margin-bottom: 20px;
+}
+
+/* ─── Score display (big number on request detail) ───────────────────────────── */
+.score-display {
+  font-size: 42px;
+  font-weight: bold;
+}
+
+/* ─── EXPLAIN plan tree ──────────────────────────────────────────────────────── */
+.plan-node {
+  border-left: 2px solid #4a5568;
+  margin-left: 16px;
+  padding-left: 16px;
+  margin-top: 8px;
+}
+.plan-node:first-child {
+  margin-left: 0;
+  padding-left: 0;
+  border-left: none;
+}
+.node-box {
+  border-radius: 6px;
+  padding: 12px 16px;
+  margin-bottom: 4px;
+  cursor: pointer;
+  transition: opacity 0.15s;
+}
+.node-box:hover { opacity: 0.85; }
+
+/* ─── EXPLAIN warning/interpretation block ───────────────────────────────────── */
+.interpret-block {
+  border-radius: 6px;
+  padding: 12px 16px;
+  font-size: 13px;
+  background: #1a202c;
+  margin-bottom: 16px;
+}

data/app/controllers/rails_vitals/playgrounds_controller.rb

@@ -0,0 +1,120 @@
+module RailsVitals
+  class PlaygroundsController < ApplicationController
+    def index
+      @default_query = default_query
+      @default_model = default_model_name
+      @available_assocs = associations_for_model(@default_model)
+      @prechecked_assocs = prechecked_associations
+    end
+
+    def create
+      expression = params[:expression].to_s.strip
+      clean_expr = clean_expression(expression)
+      access_associations = Array(params[:access_associations]).reject(&:blank?)
+
+      result = Playground::Sandbox.run(
+        expression,
+        access_associations: access_associations
+      )
+
+      model_name = Playground::Sandbox.extract_model_name(expression)
+      @available_assocs = associations_for_model(model_name)
+      @prechecked_assocs = access_associations
+
+      @expression = clean_expr
+      @result = result
+      @previous = session_previous
+      @query_dna = build_dna(result.queries)
+
+      session[:playground_previous] = serialize_result(result, clean_expr, access_associations)
+
+      render :index
+    end
+
+    private
+
+    def discover_models
+      Analyzers::AssociationMapper.discover_models.map(&:name)
+    end
+
+    def worst_n1_pattern
+      records = RailsVitals.store.all
+      return nil if records.empty?
+
+      Analyzers::NPlusOneAggregator.aggregate(records).first
+    end
+
+    def session_previous
+      raw = session[:playground_previous]
+      return nil unless raw
+
+      JSON.parse(raw, symbolize_names: true)
+    rescue
+      nil
+    end
+
+    def default_model_name
+      pattern = worst_n1_pattern
+      return discover_models.first unless pattern
+
+      pattern[:fix_suggestion]&.dig(:owner_model) || discover_models.first
+    end
+
+    def associations_for_model(model_name)
+      return [] unless model_name
+
+      Playground::Sandbox.associations_for(model_name)
+    end
+
+    def prechecked_associations
+      pattern = worst_n1_pattern
+      return [] unless pattern
+
+      # Pre-check the association from the worst N+1 pattern
+      table = pattern[:table]
+      return [] unless table
+
+      assoc_name = table  # table name is usually the association name
+      [ @available_assocs.find { |a| a == assoc_name || a == assoc_name.singularize } ].compact
+    end
+
+    def default_query
+      pattern = worst_n1_pattern
+      return "" unless pattern
+
+      fix = pattern[:fix_suggestion]&.dig(:code)
+      return "" unless fix
+
+      "# Worst N+1 detected in your app:\n# Fix: #{fix}\n\n#{fix.split('.').first}.all"
+    end
+
+    def serialize_result(result, expression, access_associations = [])
+      {
+        expression:         expression,
+        query_count:        result.query_count,
+        score:              result.score,
+        duration_ms:        result.duration_ms,
+        n1_count:           result.n1_patterns.size,
+        access_associations: access_associations,
+        error:              result.error
+      }.to_json
+    end
+
+    def clean_expression(expression)
+      expression
+        .lines
+        .reject { |l| l.strip.start_with?("#") }
+        .join
+        .strip
+    end
+
+    def build_dna(queries)
+      queries.map do |q|
+        {
+          query: q,
+          dna:   Analyzers::SqlTokenizer.tokenize(q[:sql], all_queries: queries)
+        }
+      end
+    end
+  end
+end

data/app/helpers/rails_vitals/application_helper.rb

@@ -11,7 +11,9 @@ module RailsVitals
     COLOR_ORANGE = "#f6ad55"
     COLOR_LIGHT_GREEN = "#68d391"
 
-    def score_color(color)
+    # Module-level helper so plain Ruby classes (e.g. PanelRenderer) can resolve
+    # a score color without needing a helper instance.
+    def self.score_color_for(color)
       case color
       when "green" then COLOR_GREEN
       when "blue"  then COLOR_BLUE
@@ -20,6 +22,10 @@ module RailsVitals
       end
     end
 
+    def score_color(color)
+      RailsVitals::ApplicationHelper.score_color_for(color)
+    end
+
     def score_label_to_color(score)
       case score
       when 90..100 then "healthy"
@@ -87,5 +93,41 @@ module RailsVitals
       else                      COLOR_LIGHT_RED
       end
     end
+
+    # Returns a hex color for a DNA risk level symbol (:healthy, :neutral, :warning, :danger)
+    def risk_color(risk)
+      {
+        healthy: COLOR_LIGHT_GREEN,
+        neutral: COLOR_NEUTRAL,
+        warning: COLOR_ORANGE,
+        danger:  COLOR_LIGHT_RED
+      }[risk.to_sym] || COLOR_NEUTRAL
+    end
+
+    # Returns a readable hex text color for a numeric health score (0-100)
+    def score_text_color(score)
+      case score.to_i
+      when 90..100 then COLOR_LIGHT_GREEN
+      when 70..89  then "#4299e1"
+      when 50..69  then COLOR_ORANGE
+      else              COLOR_LIGHT_RED
+      end
+    end
+
+    # Returns the full badge CSS class string for a score color label.
+    def badge_class(color)
+      "badge badge-#{color}"
+    end
+
+    def format_ms(value)
+      return "0ms" unless value
+
+      "#{value.to_f.round(1)}ms"
+    end
+
+    # Calculates a percentage of count over total, returning 0 when total is zero.
+    def percentage(count, total)
+      total.to_f > 0 ? ((count.to_f / total) * 100).round(1) : 0
+    end
   end
 end

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

@@ -20,6 +20,7 @@
     <%= link_to "Models", rails_vitals.models_path %>
     <%= link_to "N+1 Patterns", rails_vitals.n_plus_ones_path %>
     <%= link_to "Association Map", rails_vitals.associations_path %>
+    <%= link_to "Playground", rails_vitals.playgrounds_path %>
   </nav>
   <div class="container">
     <%= yield %>

data/app/views/rails_vitals/dashboard/index.html.erb

@@ -1,4 +1,4 @@
-<div class="page-title">Dashboard</div>
+<%= render "rails_vitals/shared/page_header", title: "Dashboard" %>
 
 <div class="grid-3">
   <div class="stat-card">
@@ -34,20 +34,14 @@
         <tr>
           <td><%= r.endpoint %></td>
           <td>
-            <span class="badge badge-<%= r.color %>">
-              <%= r.score %> <%= r.label %>
-            </span>
+            <%= render "rails_vitals/shared/score_badge", color: r.color, score: r.score, label: r.label %>
           </td>
           <td><%= r.total_query_count %></td>
-          <td><%= r.total_db_time_ms.round(1) %>ms</td>
+          <td><%= format_ms(r.total_db_time_ms) %></td>
           <td>
-            <% if r.n_plus_one_patterns.any? %>
-              <span class="n1-badge"><%= r.n_plus_one_patterns.size %></span>
-            <% else %>
-              <span class="text-healthy">None</span>
-            <% end %>
+            <%= render "rails_vitals/shared/n1_indicator", patterns: r.n_plus_one_patterns %>
           </td>
-          <td><%= r.duration_ms&.round(1) %>ms</td>
+          <td><%= format_ms(r.duration_ms) %></td>
           <td><%= link_to "→", rails_vitals.request_path(r.id) %></td>
         </tr>
       <% end %>
@@ -74,7 +68,7 @@
           <td><%= stats[:count] %></td>
           <td><%= stats[:avg_score] %></td>
           <td><%= stats[:avg_queries] %></td>
-          <td><%= stats[:avg_db_time_ms].round(1) %>ms</td>
+          <td><%= format_ms(stats[:avg_db_time_ms]) %></td>
         </tr>
       <% end %>
     </tbody>
@@ -100,7 +94,7 @@
               <td><%= label %></td>
               <td><%= count %></td>
               <td class="text-muted">
-                <%= @total > 0 ? ((count.to_f / @total) * 100).round(1) : 0 %>%
+                <%= percentage(count, @total) %>%
               </td>
             </tr>
           <% end %>
@@ -122,9 +116,7 @@
             <tr>
               <td class="text-muted text-sm"><%= endpoint %></td>
               <td>
-                <span class="badge badge-<%= score_label_to_color(score) %>">
-                  <%= score %>
-                </span>
+                <%= render "rails_vitals/shared/score_badge", color: score_label_to_color(score), score: score %>
               </td>
             </tr>
           <% end %>

data/app/views/rails_vitals/explains/show.html.erb

@@ -1,34 +1,12 @@
-<style>
-  .plan-node {
-    border-left: 2px solid #4a5568;
-    margin-left: 16px;
-    padding-left: 16px;
-    margin-top: 8px;
-  }
-  .plan-node:first-child {
-    margin-left: 0;
-    padding-left: 0;
-    border-left: none;
-  }
-  .node-box {
-    border-radius: 6px;
-    padding: 12px 16px;
-    margin-bottom: 4px;
-    cursor: pointer;
-    transition: opacity 0.15s;
-  }
-  .node-box:hover { opacity: 0.85; }
-</style>
-
 <%# Header %>
 <div class="mb-20">
   <% if @record %>
-    <a href="<%= rails_vitals.request_path(@record.id) %>" class="text-blue" style="font-size:13px;">
-      ← Back to Request Detail
-    </a>
+    <%= link_to "← Back to Request Detail",
+                rails_vitals.request_path(@record.id),
+                class: "back-link text-sm" %>
   <% end %>
 
-  <h2 class="page-heading" style="margin:8px 0;">
+  <h2 class="page-heading mb-8">
     EXPLAIN Visualizer
   </h2>
 
@@ -38,15 +16,12 @@
 </div>
 
 <% if @result.error %>
-  <div
-    class="text-danger"
-    style="background:#2d1515;border:1px solid #fc818166;border-radius:6px;padding:16px;font-size:13px;"
-  >
+  <div class="error-card">
     <%= @result.error %>
   </div>
 <% else %>
   <%# Summary stats row %>
-  <div style="display:grid;grid-template-columns:repeat(5,1fr);gap:12px;margin-bottom:24px;">
+  <div class="grid-5">
     <% stats = [
         { label: "Total Cost",    value: @result.total_cost,               color: cost_color(@result.total_cost) },
         { label: "Actual Time",   value: "#{@result.actual_time_ms}ms",    color: time_color(@result.actual_time_ms) },
@@ -149,16 +124,10 @@
 
   <%# Interpretation summary %>
   <% if @result.interpretation %>
+    <% interp_color = @result.warnings.any? ? "#f6ad55" : "#68d391" %>
     <div
-      class="mb-16 line-relaxed"
-      style="
-        background:#1a202c;
-        border-radius:6px;
-        padding:12px 16px;
-        font-size:13px;
-        color:<%= @result.warnings.any? ? '#f6ad55' : '#68d391' %>;
-        border-left:3px solid <%= @result.warnings.any? ? '#f6ad55' : '#68d391' %>;
-      "
+      class="interpret-block mb-16 line-relaxed"
+      style="color:<%= interp_color %>;border-left:3px solid <%= interp_color %>;"
     >
       <%= @result.interpretation %>
     </div>

data/app/views/rails_vitals/heatmap/index.html.erb

@@ -29,7 +29,7 @@
                     class: "text-accent" %>
             </td>
             <td>
-              <span class="badge badge-<%= color %>">
+              <span class="<%= badge_class(color) %>">
                 <%= row[:avg_score] %>
               </span>
             </td>
@@ -60,7 +60,6 @@
     </table>
   </div>
 <% else %>
-  <div class="card empty-state">
-    No requests recorded yet. Visit your app to generate data.
-  </div>
+  <%= render "rails_vitals/shared/empty_state",
+             message: "No requests recorded yet. Visit your app to generate data." %>
 <% end %>

data/app/views/rails_vitals/models/index.html.erb

@@ -94,7 +94,6 @@
     </div>
   <% end %>
 <% else %>
-  <div class="card empty-state">
-    No data recorded yet. Visit your app to generate data.
-  </div>
+  <%= render "rails_vitals/shared/empty_state",
+             message: "No data recorded yet. Visit your app to generate data." %>
 <% end %>

data/app/views/rails_vitals/n_plus_ones/index.html.erb

@@ -15,6 +15,7 @@
           <th>Affected Endpoints</th>
           <th>Fix</th>
           <th></th>
+          <th></th>
         </tr>
       </thead>
       <tbody>
@@ -37,13 +38,18 @@
                     n_plus_one_path(pattern_id(p)),
                     class: "text-accent" %>
             </td>
+            <td>
+              <%= link_to "Try in Playground →",
+                    rails_vitals.playgrounds_path(
+                      expression: p[:fix_suggestion]&.dig(:code)
+                    ),
+                    class: "text-accent" %>
+            </td>
           </tr>
         <% end %>
       </tbody>
     </table>
   </div>
 <% else %>
-  <div class="card empty-state">
-    No N+1 patterns detected yet.
-  </div>
+  <%= render "rails_vitals/shared/empty_state", message: "No N+1 patterns detected yet." %>
 <% end %>