render-guardian 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a2c5c9770d5548095d968a3e1b4973a20812c0ef9ba48377b0be83ff74403b0b
+  data.tar.gz: fdf4c0dd27fe96857553d6e281726735b7b32ba219a30e9d63e71be189a8b43b
+SHA512:
+  metadata.gz: 01c27d30f1a8813570bbf786277c42820f42ef886c3abdf2e0b09a8108d3b4317116c1d4c18970ed772635b8e6f59927a82e3bf2ffbcc90bd7c96643da54c5b8
+  data.tar.gz: 5ebef982c4571283cfa13299477ada423eaa4ba42c3ae659cd4346286832ab717be336f3c99a310ef66d9330ff23c7e39560f5812c8ed4505a8c8ebaf5051b1c

data/README.md

@@ -0,0 +1,40 @@
+# Render Guardian
+
+Render conservation guardian — template budgets, partial profiling, N+1 query detection, and helper method cost tracking for Ruby web applications.
+
+## Installation
+
+```bash
+gem install render-guardian
+```
+
+## Usage
+
+```ruby
+require "render_guardian"
+
+# Analyze render events
+report = RenderGuardian.analyze(
+  render_log: [
+    { template: "index", partial: "_row", duration_ms: 200,
+      db_queries: ["SELECT * FROM items WHERE id=1"],
+      helpers_called: [{ name: "format_price", time_ms: 5 }] },
+    # ... more events
+  ]
+)
+
+puts report
+puts report.summary
+```
+
+## Features
+
+- **Render Budget** — max time per template/partial
+- **Partial Profiling** — stats by template and partial
+- **N+1 Detection** — repeated queries and high query-per-partial ratios
+- **Helper Cost Tracking** — find slow helper methods
+- **Conservation Reports** — human and machine-readable
+
+## License
+
+MIT

data/lib/render_guardian/budget.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RenderGuardian
+  class Budget
+    DEFAULTS = {
+      max_template_time_ms:     100,
+      max_partial_time_ms:      50,
+      max_helper_time_ms:       20,
+      max_db_queries_per_partial: 3,
+      n_plus_one_threshold:     5
+    }.freeze
+
+    attr_reader :limits
+
+    def initialize(limits = {})
+      @limits = DEFAULTS.merge(limits.transform_keys(&:to_sym))
+    end
+
+    def limit_for(key)
+      @limits[key.to_sym]
+    end
+  end
+end

data/lib/render_guardian/helper_tracker.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RenderGuardian
+  class HelperTracker
+    def initialize(profiler)
+      @profiler = profiler
+    end
+
+    def analyze
+      helper_stats = Hash.new { |h, k| h[k] = { count: 0, total_ms: 0, templates: [] } }
+      max_ms = @profiler.budget.limit_for(:max_helper_time_ms)
+
+      # Track helper calls from events that have helper timing data
+      @profiler.events.each do |event|
+        Array(event.helpers_called).each do |h|
+          name = h.is_a?(Hash) ? h[:name].to_s : h.to_s
+          time = h.is_a?(Hash) ? h[:time_ms].to_f : 0
+          helper_stats[name][:count] += 1
+          helper_stats[name][:total_ms] += time
+          helper_stats[name][:templates] << event.template unless helper_stats[name][:templates].include?(event.template)
+        end
+      end
+
+      findings = []
+      helper_stats.each do |name, stats|
+        avg = stats[:total_ms] / stats[:count]
+        if avg > max_ms
+          findings << {
+            type:       :slow_helper,
+            severity:   :medium,
+            helper:     name,
+            avg_ms:     avg.round(2),
+            total_ms:   stats[:total_ms].round(2),
+            count:      stats[:count],
+            templates:  stats[:templates],
+            message:    "Helper '#{name}' averages #{avg.round(2)}ms (limit: #{max_ms}ms), called #{stats[:count]} times"
+          }
+        end
+      end
+
+      findings
+    end
+  end
+end

data/lib/render_guardian/n_plus_one_detector.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RenderGuardian
+  class NPlusOneDetector
+    def initialize(profiler)
+      @profiler = profiler
+    end
+
+    def detect
+      findings = []
+      threshold = @profiler.budget.limit_for(:n_plus_one_threshold)
+
+      # Check per-partial query counts
+      @profiler.stats_by_partial.each do |partial, stats|
+        if stats[:total_queries] / stats[:count] > @profiler.budget.limit_for(:max_db_queries_per_partial)
+          findings << {
+            type:           :n_plus_one_suspected,
+            severity:       :high,
+            partial:        partial,
+            avg_queries:    (stats[:total_queries].to_f / stats[:count]).round(2),
+            threshold:      @profiler.budget.limit_for(:max_db_queries_per_partial),
+            render_count:   stats[:count],
+            message:        "Partial '#{partial}' averages #{(stats[:total_queries].to_f / stats[:count]).round(2)} DB queries per render (threshold: #{@profiler.budget.limit_for(:max_db_queries_per_partial)})"
+          }
+        end
+      end
+
+      # Detect repeated identical queries across events (classic N+1 pattern)
+      query_counts = Hash.new(0)
+      @profiler.events.each do |event|
+        event.db_queries.each { |q| query_counts[q] += 1 }
+      end
+
+      query_counts.select { |_, count| count >= threshold }.each do |query, count|
+        findings << {
+          type:     :repeated_query,
+          severity: :high,
+          query:    query,
+          count:    count,
+          message:  "Query executed #{count} times across renders — possible N+1: '#{query[0..80]}'"
+        }
+      end
+
+      findings
+    end
+  end
+end

data/lib/render_guardian/profiler.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RenderGuardian
+  RenderEvent = Struct.new(
+    :template, :partial, :duration_ms, :db_queries, :helpers_called, :timestamp,
+    keyword_init: true
+  )
+
+  class Profiler
+    attr_reader :budget, :events
+
+    def initialize(budget)
+      @budget = budget
+      @events = []
+    end
+
+    def ingest(events)
+      Array(events).each do |e|
+        @events << RenderEvent.new(
+          template:       e[:template].to_s,
+          partial:        e[:partial].to_s,
+          duration_ms:    e[:duration_ms].to_f,
+          db_queries:     Array(e[:db_queries]),
+          helpers_called: Array(e[:helpers_called]),
+          timestamp:      e[:timestamp] || Time.now
+        )
+      end
+    end
+
+    def stats_by_template
+      @events.group_by(&:template).transform_values do |evts|
+        durations = evts.map(&:duration_ms)
+        {
+          count:       durations.size,
+          total_ms:    durations.sum,
+          avg_ms:      durations.sum / durations.size,
+          max_ms:      durations.max,
+          min_ms:      durations.min,
+          total_queries: evts.sum { |e| e.db_queries.size }
+        }
+      end
+    end
+
+    def stats_by_partial
+      @events.select { |e| !e.partial.empty? }.group_by(&:partial).transform_values do |evts|
+        durations = evts.map(&:duration_ms)
+        {
+          count:       durations.size,
+          total_ms:    durations.sum,
+          avg_ms:      durations.sum / durations.size,
+          max_ms:      durations.max,
+          total_queries: evts.sum { |e| e.db_queries.size }
+        }
+      end
+    end
+
+    def slow_templates
+      max_ms = @budget.limit_for(:max_template_time_ms)
+      @events.select { |e| e.template && e.duration_ms > max_ms }
+    end
+
+    def slow_partials
+      max_ms = @budget.limit_for(:max_partial_time_ms)
+      @events.select { |e| !e.partial.empty? && e.duration_ms > max_ms }
+    end
+  end
+end

data/lib/render_guardian/report.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RenderGuardian
+  class Report
+    attr_reader :budget, :profiler, :n_plus_one_findings, :helper_findings
+
+    def initialize(budget, profiler, n_plus_one_findings, helper_findings)
+      @budget              = budget
+      @profiler            = profiler
+      @n_plus_one_findings = n_plus_one_findings
+      @helper_findings     = helper_findings
+    end
+
+    def summary
+      {
+        total_renders:     @profiler.events.size,
+        templates:         @profiler.stats_by_template.size,
+        slow_templates:    @profiler.slow_templates.size,
+        slow_partials:     @profiler.slow_partials.size,
+        n_plus_one_issues: @n_plus_one_findings.size,
+        slow_helpers:      @helper_findings.size
+      }
+    end
+
+    def to_h
+      {
+        summary:         summary,
+        template_stats:  @profiler.stats_by_template,
+        partial_stats:   @profiler.stats_by_partial,
+        n_plus_one:      @n_plus_one_findings,
+        helpers:         @helper_findings
+      }
+    end
+
+    def to_s
+      lines = []
+      lines << "=== Render Guardian Report ==="
+      s = summary
+      lines << "Renders: #{s[:total_renders]} | Templates: #{s[:templates]}"
+      lines << "Slow templates: #{s[:slow_templates]} | Slow partials: #{s[:slow_partials]}"
+      lines << "N+1 issues: #{s[:n_plus_one_issues]} | Slow helpers: #{s[:slow_helpers]}"
+      lines << ""
+
+      if @n_plus_one_findings.any?
+        lines << "--- N+1 Issues ---"
+        @n_plus_one_findings.each { |f| lines << "  [#{f[:severity].upcase}] #{f[:message]}" }
+        lines << ""
+      end
+
+      if @helper_findings.any?
+        lines << "--- Slow Helpers ---"
+        @helper_findings.each { |f| lines << "  [#{f[:severity].upcase}] #{f[:message]}" }
+        lines << ""
+      end
+
+      if s[:slow_templates].zero? && s[:n_plus_one_issues].zero? && s[:slow_helpers].zero?
+        lines << "✅ All renders within budget!"
+      end
+
+      lines.join("\n")
+    end
+  end
+end

data/lib/render_guardian.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "render_guardian/budget"
+require_relative "render_guardian/profiler"
+require_relative "render_guardian/n_plus_one_detector"
+require_relative "render_guardian/helper_tracker"
+require_relative "render_guardian/report"
+
+module RenderGuardian
+  class Error < StandardError; end
+
+  def self.analyze(render_log:, budget: nil)
+    budget   ||= Budget.new
+    profiler = Profiler.new(budget)
+    profiler.ingest(render_log)
+
+    n_plus_one = NPlusOneDetector.new(profiler).detect
+    helpers    = HelperTracker.new(profiler).analyze
+
+    Report.new(budget, profiler, n_plus_one, helpers)
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: render-guardian
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SuperInstance
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-02 00:00:00.000000000 Z
+dependencies: []
+description: Track render budgets, profile partial performance, detect N+1 queries
+  in views, and measure helper method costs for Ruby web applications.
+email:
+- team@superinstance.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/render_guardian.rb
+- lib/render_guardian/budget.rb
+- lib/render_guardian/helper_tracker.rb
+- lib/render_guardian/n_plus_one_detector.rb
+- lib/render_guardian/profiler.rb
+- lib/render_guardian/report.rb
+homepage: https://github.com/SuperInstance/gem-render-guardian
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.5
+signing_key: 
+specification_version: 4
+summary: Render conservation guardian — template budgets, partial profiling, N+1 detection
+test_files: []