rails_benchmark_suite 0.2.9 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c48ce5faaa5348bcd47cdd9c88ba9b1441d0f7bcd0a6fa601d84b36014673d1a
-  data.tar.gz: f39f188c55fe6749a5b9ba4ae9c5c44e926bd5d6588737f689192ab841deda92
+  metadata.gz: 150b032cfebbd12d60c2a407a292cf04367c4b821d44541aa21c7b01243b5288
+  data.tar.gz: 5fcffc2550db42c299f3c417abb11c9b2d8c3bdea7a27ecf3f8fd7c1d624bf31
 SHA512:
-  metadata.gz: 28f32ff03be6cbd83aabb1c3f8750316f5c3e2cb69de127885f96a4ef27841b12ee916999c2dea59c314605a6755f0aee34d0c610338c596bbff2789120a7ce0
-  data.tar.gz: 2e4f5a17c66e0caed9a95a46cdc3e0049783eea603f9cd263d699f492d49440f7ceaab45bf4c469b8b05fc316ca999052d12705dfe29b0edf54b032160fc2966
+  metadata.gz: 785219aa58ac8b7353bf67920c4f419bf628d92f2fc539f02bd09408fb7aac13a6352d5aa68a09f0c60a7f1d95c34e016d12bb4ab015544ecf6962ca0c72aa54
+  data.tar.gz: 81706842da33247fbace2b62c4dee9f42332ff83a9ed1ab905960296f4954f6915c4055abe97910d9a2e572472d9454ebe7e01fce17dba0b604cd4b43f2f4988

data/.gitignore

@@ -1,4 +1,4 @@
-*.gem
+
 .bundle/
 vendor/bundle/
 Gemfile.lock

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.3.0] - 2025-01-03
+
+### Major Architectural Refactor (SRP)
+- **Runner Split**: Dismantled the monolithic `Runner` class (260+ lines) into three specialized modules:
+  - `DatabaseManager`: Handles ActiveRecord connection, schema loading, and SQLite PRAGMA optimizations
+  - `WorkloadRunner`: Manages benchmark execution engine with BASE_WEIGHTS normalization and complete payload generation
+  - `Formatter`: Centralized UI rendering, ANSI colors, insights engine, and output formatting
+- **Runner Coordinator**: `Runner` is now a minimal 23-line coordinator delegating to the three modules
+
+### Normalized RHI Math Engine
+- **BASE_WEIGHTS**: Defined workload weights (Active Record: 0.4, View: 0.2, Solid Queue: 0.2, Cache: 0.1, Image: 0.1)
+- **Dynamic Weight Redistribution**: When workloads are skipped (e.g., missing libvips), weights are normalized proportionally to maintain 100% scale
+- **Formula**: `RHI Score = Σ (4T_IPS × Adjusted_Weight)` where adjusted weights always sum to 1.0
+
+### Performance Insights Engine
+- **Scaling Analysis**: Warns when multi-threading scaling < 0.8x, indicating SQLite lock contention or Ruby GIL saturation
+- **YJIT Detection**: Displays hint to enable YJIT when disabled (typical 15-25% boost)
+- **Memory Monitoring**: Alerts when workload memory growth exceeds 20MB, suggesting heavy object allocation
+- **Hardware Tiering**: Provides comparison labels (Entry/Dev < 50, Production-Ready 50-200, High-Performance > 200)
+
+### UI/UX Enhancements
+- **Box Alignment**: Fixed header and final score boxes with proper text length calculation (60-char width)
+- **Table Spacing**: Added separator line between progress logs and results table for better readability
+- **Insights Display**: Integrated insights below summary table with emoji indicators (💡, 📊)
+- **Enhanced Number Formatting**: Smart k/M suffixes for readability (e.g., "15.3k", "1.2M")
+- **YJIT Hints**: Helpful reminder `(run with RUBY_OPT="--yjit" for max perf)` when YJIT is disabled
+- Silent migrations: Added `ActiveRecord::Migration.verbose = false` to reduce noise
+- Cross-platform install instructions for libvips (macOS and Linux)
+
+### 🐛 Fixes
+- Fixed `.gitignore` to properly track `gemspec` file for gem distribution
+- **JSON Guard**: Ensures clean JSON output without any UI noise when `--json` flag is used
+- Improved CLI output suppression in JSON mode
+
+### 📖 Documentation
+- **Calculation Formula**: Added "How It's Calculated" section with RHI formula: `Σ (4-Thread IPS × Weight)`
+- **Workload Weights Table**: Documented weights (Active Record 40%, View 20%, Jobs 20%, Cache 10%, Image 10%)
+- **Hardware Tiers**: Explained tier classification system
+- Complete README rewrite with four execution methods:
+  - Standard: `bundle exec rails_benchmark_suite`
+  - High Performance: `RUBY_OPT="--yjit" bundle exec rails_benchmark_suite` 
+  - JSON Export: `bundle exec rails_benchmark_suite --json > report.json`
+  - Standalone: `bin/rails_benchmark_suite`
+- Added comprehensive System Requirements section
+- Updated all terminology from "Suite" to "Workload"
+
 ## [0.2.0] - 2025-12-31
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rails_benchmark_suite (0.2.6)
+    rails_benchmark_suite (0.3.0)
       actionview (~> 8.1)
       activerecord (~> 8.1)
       activestorage (~> 8.1)
@@ -116,6 +116,7 @@ GEM
       racc (~> 1.4)
     nokogiri (1.19.0-x86_64-linux-musl)
       racc (~> 1.4)
+    ostruct (0.6.3)
     racc (1.8.1)
     rack (3.2.4)
     rack-session (2.1.1)
@@ -166,6 +167,7 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 2.5)
   minitest (~> 5.0)
+  ostruct (~> 0.6)
   rails_benchmark_suite!
   rake (~> 13.0)
 

data/README.md

@@ -56,19 +56,43 @@ Rails Benchmark Suite prioritizes **Benchmarking** (via `benchmark-ips`) over **
 * **Rails:** 8.1+
 * **Database:** SQLite3
 
-### Use within a Rails Application
+## 📋 System Requirements
 
-Add to your Gemfile:
+### Required
+- **Ruby**: 3.3+ (3.4+ recommended for YJIT)
+- **Rails**: 8.0+  
+- **Database**: SQLite3
 
-```ruby
-gem "rails_benchmark_suite", group: :development
+### Optional (for Image Heft workload)
+- **macOS**: `brew install vips`
+- **Linux (Ubuntu/Debian)**: `sudo apt install libvips-dev`
+
+---
+
+## 🚀 Usage
+
+### Standard Execution
+```bash
+bundle exec rails_benchmark_suite
 ```
+The easy way - run the benchmark with your current Ruby configuration.
 
-### Usage Flags
-* `--yjit`: Enables the Ruby JIT compiler (significant for Rails 8+ performance).
-* `-S`: Corrects the path to look for the executable in your current bundle.
-* `--json`: For programmatic consumption of results.
-* `--skip-rails`: To ignore the host application and run in isolated mode.
+### High Performance (Recommended)
+```bash
+RUBY_OPT="--yjit" bundle exec rails_benchmark_suite
+```
+Enable YJIT for maximum performance measurement accuracy. This is the recommended method for Rails 8+ benchmarking.
+
+### JSON Export (Automation)
+```bash
+bundle exec rails_benchmark_suite --json > report.json
+```
+Perfect for CI/CD pipelines and programmatic analysis. Outputs clean JSON without any UI elements.
+
+### Additional Options
+- `--skip-rails`: Run in isolated mode without loading Rails environment
+- `--version`: Display gem version
+- `--help`: Show all available options
 
 ### Standalone Usage
 
@@ -83,7 +107,39 @@ bin/rails_benchmark_suite
 
 ---
 
-## 🧪 The "Heft" Suites
+## 📐 How It's Calculated
+
+The **Rails Heft Index (RHI)** measures your hardware's ability to handle Rails workloads using this formula:
+
+```
+RHI Score = Σ (4-Thread IPS × Weight)
+```
+
+### Workload Weights
+
+| Workload | Weight | Rationale |
+|----------|--------|-----------|  
+| **Active Record** | 40% | Database operations are the core of most Rails apps |
+| **View Rendering** | 20% | ERB/ActionView processing |
+| **Solid Queue** | 20% | Background job throughput |
+| **Cache Operations** | 10% | Memory store performance |
+| **Image Processing** | 10% | Optional - requires libvips |
+
+**Why 4-Thread IPS?** We use 4-thread performance to simulate production concurrency where multiple requests are handled simultaneously.
+
+**Dynamic Weight Redistribution:** If a workload is skipped (e.g., Image Processing without libvips), its weight is redistributed proportionally among remaining workloads to maintain a 100% scale.
+
+### Hardware Tiers
+
+Your RHI score maps to these performance tiers:
+
+- **< 50**: Entry/Dev - Suitable for local development
+- **50-200**: Production-Ready - Handles moderate production traffic
+- **> 200**: High-Performance - Optimized for high-traffic applications
+
+---
+
+## 🧪 The "Heft" Workloads
 
 The gem measures performance across critical Rails subsystems using a dedicated, isolated schema:
 

data/bin/rails_benchmark_suite

@@ -29,20 +29,24 @@ OptionParser.new do |opts|
   end
 end.parse!
 
-puts "RailsBenchmarkSuite v#{RailsBenchmarkSuite::VERSION}"
+unless options[:json]
+  puts "RailsBenchmarkSuite v#{RailsBenchmarkSuite::VERSION}"
+end
 
 # Rails Detection
 rails_env_path = File.join(Dir.pwd, "config", "environment.rb")
 
 if !options[:skip_rails] && File.exist?(rails_env_path)
-  puts "Rails environment detected at #{rails_env_path}. Loading..."
+  puts "Rails environment detected at #{rails_env_path}. Loading..." unless options[:json]
   require rails_env_path
-  puts "Rails loaded successfully."
+  puts "Rails loaded successfully." unless options[:json]
 else
-  if options[:skip_rails]
-    puts "Skipping Rails loading (requested via --skip-rails)."
-  else
-    puts "No Rails environment detected (config/environment.rb not found)."
+  unless options[:json]
+    if options[:skip_rails]
+      puts "Skipping Rails loading (requested via --skip-rails)."
+    else
+      puts "No Rails environment detected (config/environment.rb not found)."
+    end
   end
 end
 

data/lib/rails_benchmark_suite/database_manager.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module RailsBenchmarkSuite
+  class DatabaseManager
+    SETUP_MUTEX = Mutex.new
+
+    def setup
+      # Silence migrations
+      ActiveRecord::Migration.verbose = false
+
+      # Ultimate Hardening: Massive pool and timeout for zero lock contention (v0.3.0)
+      ActiveRecord::Base.establish_connection(
+        adapter: "sqlite3",
+        database: "file:heft_db?mode=memory&cache=shared",
+        pool: 50,
+        timeout: 30000
+      )
+
+      # The 'Busy Timeout' Hammer - force it directly on the raw connection
+      ActiveRecord::Base.connection.raw_connection.busy_timeout = 10000
+      
+      # Setup Schema once safely with Mutex
+      SETUP_MUTEX.synchronize do
+        # Verify if schema already loaded by checking for a table
+        unless ActiveRecord::Base.connection.table_exists?(:users)
+          RailsBenchmarkSuite::Schema.load
+        end
+      end
+
+      # High-Performance Pragmas for WAL + NORMAL sync
+      ActiveRecord::Base.connection.raw_connection.execute("PRAGMA journal_mode = WAL")
+      ActiveRecord::Base.connection.raw_connection.execute("PRAGMA synchronous = NORMAL")
+      ActiveRecord::Base.connection.raw_connection.execute("PRAGMA mmap_size = 268435456") # 256MB - reduce disk I/O
+    end
+  end
+end

data/lib/rails_benchmark_suite/db_setup.rb

@@ -5,3 +5,6 @@ require "sqlite3"
 
 # Silence ActiveRecord logs during benchmarks to avoid IO bottlenecks
 ActiveRecord::Base.logger = nil
+
+# Silence migration output
+ActiveRecord::Migration.verbose = false

data/lib/rails_benchmark_suite/formatter.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RailsBenchmarkSuite
+  module Formatter
+    # ANSI Color Codes
+    RED = "\e[31m"
+    YELLOW = "\e[33m"
+    GREEN = "\e[32m"
+    BLUE = "\e[34m"
+    BOLD = "\e[1m"
+    RESET = "\e[0m"
+
+    module_function
+
+    def header(info)
+      box_width = 60  # Internal width
+      
+      # Line 1: Simple text
+      line1 = "Rails Heft Index (RHI) v0.3.0"
+      
+      # Line 2: Build without colors first to measure
+      yjit_status = info[:yjit] ? 'ON' : 'OFF'
+      yjit_hint_text = info[:yjit] ? "" : " (use RUBY_OPT=\"--yjit\")"
+      line2_plain = "Ruby #{info[:ruby_version]} • #{info[:processors]} Cores • YJIT: #{yjit_status}#{yjit_hint_text}"
+      
+      # Now build with colors
+      yjit_color = info[:yjit] ? GREEN : RED
+      yjit_hint_colored = info[:yjit] ? "" : " #{YELLOW}(use RUBY_OPT=\"--yjit\")#{RESET}"
+      line2 = "Ruby #{info[:ruby_version]} • #{info[:processors]} Cores • YJIT: #{yjit_color}#{yjit_status}#{RESET}#{yjit_hint_colored}"
+      
+      puts "\n"
+      puts "#{BLUE}┌#{'─' * box_width}┐#{RESET}"
+      puts "#{BLUE}│#{RESET}  #{BOLD}#{line1}#{RESET}#{' ' * (box_width - 2 - line1.length)}#{BLUE}│#{RESET}"
+      puts "#{BLUE}│#{RESET}  #{line2}#{' ' * (box_width - 2 - line2_plain.length)}#{BLUE}│#{RESET}"
+      puts "#{BLUE}└#{'─' * box_width}┘#{RESET}"
+      puts ""
+    end
+
+    def render_progress(num, total, name, state)
+      if state == "Running"
+        print "[#{num}/#{total}] Running #{name}... "
+      else
+        puts state
+      end
+    end
+
+    def summary_with_insights(payload)
+      results = payload[:results]
+      total_score = payload[:total_score]
+      tier = payload[:tier]
+      
+      # Add spacing and separator before table
+      puts "\n"
+      puts "─" * 72
+      puts ""
+      
+      # Table header
+      printf "#{BOLD}%-28s %10s %10s %10s %7s#{RESET}\n", "Workload", "1T IPS", "4T IPS", "Scaling", "Weight"
+      puts "─" * 72
+      
+      # Table rows
+      results.each do |data|
+        report = data[:report]
+        entries = report.entries
+        
+        entry_1t = entries.find { |e| e.label.include?("(1 thread)") }
+        entry_4t = entries.find { |e| e.label.include?("(4 threads)") }
+        
+        ips_1t = entry_1t ? entry_1t.ips : 0
+        ips_4t = entry_4t ? entry_4t.ips : 0
+        
+        scaling = ips_1t > 0 ? (ips_4t / ips_1t) : 0
+        
+        # Color scaling based on performance
+        scaling_color = if scaling >= 0.6
+          GREEN
+        elsif scaling >= 0.3
+          YELLOW
+        else
+          RED
+        end
+        
+        printf "%-28s %10s %10s #{scaling_color}%9.2fx#{RESET} %7.1f\n",
+          data[:name],
+          humanize(ips_1t),
+          humanize(ips_4t),
+          scaling,
+          data[:adjusted_weight]
+      end
+      
+      # Display insights
+      check_scaling_insights(results)
+      check_yjit_insight
+      check_memory_insights(results)
+      
+      # Display final score
+      render_final_score(total_score)
+      
+      # Display tier comparison
+      show_hardware_tier(tier)
+    end
+
+    def check_scaling_insights(results)
+      #Extract scaling from results
+      poor_scaling = results.select do |r|
+        entries = r[:report].entries
+        entry_1t = entries.find { |e| e.label.include?("(1 thread)") }
+        entry_4t = entries.find { |e| e.label.include?("(4 threads)") }
+        ips_1t = entry_1t ? entry_1t.ips : 0
+        ips_4t = entry_4t ? entry_4t.ips : 0
+        scaling = ips_1t > 0 ? (ips_4t / ips_1t) : 0
+        scaling < 0.8
+      end
+      
+      if poor_scaling.any?
+        puts "\n💡 Insight (Scaling): Scaling below 1.0x detected."
+        puts "   This indicates SQLite lock contention or Ruby GIL saturation."
+      end
+    end
+
+    def check_yjit_insight
+      unless defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled?
+        puts "\n💡 Insight (YJIT): YJIT is OFF."
+        puts "   Run with RUBY_OPT=\"--yjit\" for ~20% boost."
+      end
+    end
+
+    def check_memory_insights(results)
+      high_memory = results.select { |r| r[:memory_delta_mb] > 20 }
+      high_memory.each do |r|
+        puts "\n💡 Insight (Memory): High growth in #{r[:name]} (#{r[:memory_delta_mb].round(1)}MB)"
+        puts "   Suggests heavy object allocation."
+      end
+    end
+
+    def show_hardware_tier(tier)
+      comparison = case tier
+      when "Entry/Dev"
+        "📊 Performance Tier: Entry-Level (Suitable for dev/testing, may struggle with high production traffic)"
+      when "Production-Ready"
+        "📊 Performance Tier: Professional-Grade (Matches the throughput of dedicated production cloud instances)"
+      else
+        "📊 Performance Tier: High-Performance (Exceptional throughput, comparable to bare-metal or high-end workstations)"
+      end
+      
+      puts "\n#{comparison}\n"
+    end
+
+    def render_final_score(score)
+      box_width = 60  # Same as header
+      
+      # Build text without colors to measure
+      score_text = "RAILS HEFT INDEX (RHI): #{score.round(0)}"
+      
+      # Build with colors
+      score_colored = "#{GREEN}#{BOLD}RAILS HEFT INDEX (RHI): #{score.round(0)}#{RESET}"
+      
+      puts ""
+      puts "#{BLUE}┌#{'─' * box_width}┐#{RESET}"
+      puts "#{BLUE}│#{RESET}  #{score_colored}#{' ' * (box_width - 2 - score_text.length)}#{BLUE}│#{RESET}"
+      puts "#{BLUE}└#{'─' * box_width}┘#{RESET}"
+      puts ""
+    end
+
+    def as_json(payload)
+      out = {
+        system: RailsBenchmarkSuite::Reporter.system_info,
+        total_score: payload[:total_score].round(0),
+        tier: payload[:tier],
+        workloads: []
+      }
+      
+      payload[:results].each do |data|
+        entries = data[:report].entries
+        entry_1t = entries.find { |e| e.label.include?("(1 thread)") }
+        entry_4t = entries.find { |e| e.label.include?("(4 threads)") }
+        ips_1t = entry_1t ? entry_1t.ips : 0
+        ips_4t = entry_4t ? entry_4t.ips : 0
+        
+        out[:workloads] << {
+          name: data[:name],
+          adjusted_weight: data[:adjusted_weight],
+          ips_1t: ips_1t,
+          ips_4t: ips_4t,
+          scaling: ips_1t > 0 ? (ips_4t / ips_1t) : 0,
+          memory_delta_mb: data[:memory_delta_mb]
+        }
+      end
+      
+      puts out.to_json
+    end
+
+    def humanize(ips)
+      return "0" if ips.nil? || ips == 0
+      if ips >= 1_000_000
+        "#{(ips / 1_000_000.0).round(1)}M"
+      elsif ips >= 1_000
+        "#{(ips / 1_000.0).round(1)}k"
+      else
+        ips.round(1).to_s
+      end
+    end
+  end
+end

data/lib/rails_benchmark_suite/runner.rb

@@ -1,211 +1,23 @@
 # frozen_string_literal: true
 
-require "benchmark/ips"
-require "get_process_mem"
-
 module RailsBenchmarkSuite
   class Runner
-    def initialize(suites, json: false)
-      @suites = suites
+    def initialize(workloads, json: false)
+      @workloads = workloads
       @json_output = json
     end
 
-    def register(name, &block)
-      @suites << { name: name, block: block }
-    end
-
-    SETUP_MUTEX = Mutex.new
-
     def run
-      # Ultimate Hardening: Massive pool and timeout for zero lock contention (v0.2.9)
-      ActiveRecord::Base.establish_connection(
-        adapter: "sqlite3",
-        database: "file:heft_db?mode=memory&cache=shared",
-        pool: 50,
-        timeout: 30000
-      )
-
-      # The 'Busy Timeout' Hammer - force it directly on the raw connection
-      ActiveRecord::Base.connection.raw_connection.busy_timeout = 10000
+      DatabaseManager.new.setup
+      Formatter.header(Reporter.system_info) unless @json_output
       
-      # Setup Schema once safely with Mutex
-      SETUP_MUTEX.synchronize do
-        # Verify if schema already loaded by checking for a table
-        unless ActiveRecord::Base.connection.table_exists?(:users)
-          RailsBenchmarkSuite::Schema.load
-        end
-      end
-
-      # High-Performance Pragmas for WAL + NORMAL sync
-      ActiveRecord::Base.connection.raw_connection.execute("PRAGMA journal_mode = WAL")
-      ActiveRecord::Base.connection.raw_connection.execute("PRAGMA synchronous = NORMAL")
-      ActiveRecord::Base.connection.raw_connection.execute("PRAGMA mmap_size = 268435456") # 256MB - reduce disk I/O
-
-      puts "Running RailsBenchmarkSuite Benchmarks..." unless @json_output
-      puts system_report unless @json_output
-      puts "\n" unless @json_output
-
-      results = {}
-
-      @suites.each do |suite|
-        puts "== Running Suite: #{suite[:name]} ==" unless @json_output
-        
-        # Capture memory before
-        mem_before = GetProcessMem.new.mb
-
-        # Run benchmark
-        report = Benchmark.ips do |x|
-          x.config(:time => 5, :warmup => 2)
-          
-          # Single Threaded
-          x.report("#{suite[:name]} (1 thread)") do
-            with_retries { suite[:block].call }
-          end
-
-          # Multi Threaded (4 threads)
-          x.report("#{suite[:name]} (4 threads)") do
-            threads = 4.times.map do
-              Thread.new do
-                # Ensure each thread gets a dedicated connection
-                ActiveRecord::Base.connection_pool.with_connection do
-                  with_retries { suite[:block].call }
-                end
-              end
-            end
-            threads.each(&:join)
-          end
-
-          x.compare!
-        end
-
-        # Capture memory after
-        mem_after = GetProcessMem.new.mb
-        
-        results[suite[:name]] = {
-          report: report,
-          memory_delta_mb: mem_after - mem_before,
-          weight: suite[:weight]
-        }
-        
-        puts "Memory Footprint: #{mem_after.round(2)} MB (+#{(mem_after - mem_before).round(2)} MB)" unless @json_output
-        puts "\n" unless @json_output
-      end
+      # Delegate ALL math and execution to the WorkloadRunner
+      payload = WorkloadRunner.new(@workloads, show_progress: !@json_output).execute
       
-      print_summary(results)
-      results
-    end
-
-    private
-
-    def with_retries
-      yield
-    rescue ActiveRecord::StatementInvalid => e
-      if e.message =~ /locked/i
-        # Specifically drop the lock for THIS connection only
-        ActiveRecord::Base.connection.reset!
-        sleep(rand(0.01..0.05))
-        retry
-      else
-        raise e
-      end
-    end
-
-    def system_report
-      info = RailsBenchmarkSuite::Reporter.system_info
-      yjit_status = if defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled?
-        "Enabled"
-      else
-        "Disabled (Requires Ruby with YJIT support for best results)"
-      end
-      "System: Ruby #{info[:ruby_version]} (#{info[:platform]}), #{info[:processors]} Cores. YJIT: #{yjit_status}. Libvips: #{info[:libvips]}"
-    end
-
-    def print_summary(results)
       if @json_output
-        print_json(results)
-        return
-      end
-
-      puts "\n"
-      puts "=========================================================================================="
-      puts "| %-25s | %-25s | %-12s | %-15s |" % ["Suite", "IPS (1t / 4t)", "Scaling", "Mem Delta"]
-      puts "=========================================================================================="
-      
-      total_score = 0
-      
-      results.each do |name, data|
-        report = data[:report]
-        entries = report.entries
-        
-        entry_1t = entries.find { |e| e.label.include?("(1 thread)") }
-        entry_4t = entries.find { |e| e.label.include?("(4 threads)") }
-        
-        ips_1t = entry_1t ? entry_1t.ips : 0
-        ips_4t = entry_4t ? entry_4t.ips : 0
-        
-        scaling = ips_1t > 0 ? (ips_4t / ips_1t) : 0
-        mem = data[:memory_delta_mb]
-        
-        # Heft Score: Weighted Sum of 4t IPS
-        weight = data[:weight] || 1.0
-        weighted_score = ips_4t * weight
-        total_score += weighted_score
-        
-        puts "| %-25s | %-25s | x%-11.2f | +%-14.2fMB |" % [
-          name + " (w: #{weight})", 
-          "#{humanize(ips_1t)} / #{humanize(ips_4t)}",
-          scaling, 
-          mem
-        ]
-      end
-      puts "=========================================================================================="
-      puts "\n"
-      puts "  >>> FINAL HEFT SCORE: #{total_score.round(0)} <<<"
-      puts "\n"
-    end
-
-    def print_json(results)
-      require "json"
-      
-      out = {
-        system: RailsBenchmarkSuite::Reporter.system_info,
-        total_score: 0,
-        suites: []
-      }
-      
-      total_score = 0
-      
-      results.each do |name, data|
-        weight = data[:weight] || 1.0
-        
-        # Parse reports
-        ips_1t = data[:report].entries.find { |e| e.label.include?("(1 thread)") }&.ips || 0
-        ips_4t = data[:report].entries.find { |e| e.label.include?("(4 threads)") }&.ips || 0
-        
-        weighted_score = ips_4t * weight
-        total_score += weighted_score
-        
-        out[:suites] << {
-          name: name,
-          weight: weight,
-          ips_1t: ips_1t,
-          ips_4t: ips_4t,
-          scaling: ips_1t > 0 ? (ips_4t / ips_1t) : 0,
-          memory_delta_mb: data[:memory_delta_mb],
-          score: weighted_score
-        }
-      end
-      
-      out[:total_score] = total_score.round(0)
-      puts out.to_json
-    end
-
-    def humanize(ips)
-      return "0" if ips.nil?
-      if ips > 1000
-        "%.1fk" % (ips / 1000.0)
+        Formatter.as_json(payload)
       else
-        "%.1f" % ips
+        Formatter.summary_with_insights(payload)
       end
     end
   end

data/lib/rails_benchmark_suite/version.rb

@@ -1,3 +1,3 @@
 module RailsBenchmarkSuite
-  VERSION = "0.2.9"
+  VERSION = "0.3.0"
 end

data/lib/rails_benchmark_suite/workload_runner.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "get_process_mem"
+
+module RailsBenchmarkSuite
+  class WorkloadRunner
+    # Base weights for each workload
+    BASE_WEIGHTS = {
+      "Active Record Heft" => 0.4,
+      "View Heft" => 0.2,
+      "Solid Queue Heft" => 0.2,
+      "Cache Heft" => 0.1,
+      "Image Heft" => 0.1
+    }.freeze
+
+    def initialize(workloads, show_progress: true)
+      @workloads = workloads
+      @show_progress = show_progress
+    end
+
+    def execute
+      # Run all workloads and collect results
+      results = @workloads.map.with_index do |w, index|
+        if @show_progress
+          Formatter.render_progress(index + 1, @workloads.size, w[:name], "Running")
+        end
+        
+        result = run_single_workload(w)
+        
+        if @show_progress
+          Formatter.render_progress(index + 1, @workloads.size, w[:name], "Done ✓")
+        end
+        
+        result
+      end
+      
+      # Calculate normalized weights
+      weight_pool = results.sum { |r| BASE_WEIGHTS[r[:name]] || 0 }
+      
+      results.each do |r|
+        base_weight = BASE_WEIGHTS[r[:name]] || 1.0
+        r[:adjusted_weight] = base_weight / weight_pool
+      end
+      
+      # Calculate total score
+      total_score = results.sum do |r|
+        entries = r[:report].entries
+        entry_4t = entries.find { |e| e.label.include?("(4 threads)") }
+        ips_4t = entry_4t ? entry_4t.ips : 0
+        ips_4t * r[:adjusted_weight]
+      end
+      
+      # Determine tier
+      tier = if total_score < 50
+        "Entry/Dev"
+      elsif total_score < 200
+        "Production-Ready"
+      else
+        "High-Performance"
+      end
+      
+      # Return complete payload
+      {
+        results: results,
+        total_score: total_score,
+        tier: tier
+      }
+    end
+
+    private
+
+    def run_single_workload(workload)
+      mem_before = GetProcessMem.new.mb
+
+      # Run benchmark
+      report = Benchmark.ips do |x|
+        x.config(:time => 5, :warmup => 2)
+        
+        # Single Threaded
+        x.report("#{workload[:name]} (1 thread)") do
+          with_retries { workload[:block].call }
+        end
+
+        # Multi Threaded (4 threads)
+        x.report("#{workload[:name]} (4 threads)") do
+          threads = 4.times.map do
+            Thread.new do
+              ActiveRecord::Base.connection_pool.with_connection do
+                with_retries { workload[:block].call }
+              end
+            end
+          end
+          threads.each(&:join)
+        end
+
+        x.compare!
+      end
+
+      mem_after = GetProcessMem.new.mb
+      
+      {
+        name: workload[:name],
+        report: report,
+        memory_delta_mb: mem_after - mem_before
+      }
+    end
+
+    def with_retries
+      yield
+    rescue ActiveRecord::StatementInvalid => e
+      if e.message =~ /locked/i
+        ActiveRecord::Base.connection.reset!
+        sleep(rand(0.01..0.05))
+        retry
+      else
+        raise e
+      end
+    end
+  end
+end

data/lib/rails_benchmark_suite/{suites/active_record_suite.rb → workloads/active_record_workload.rb}

@@ -2,8 +2,8 @@
 
 require "active_record"
 
-# Benchmark Suite
-RailsBenchmarkSuite.register_suite("Active Record Heft", weight: 0.4) do
+# Benchmark Workload
+RailsBenchmarkSuite.register_workload("Active Record Heft", weight: 0.4) do
   # Workload: Create User with Posts, Join Query, Update
   # Use transaction rollback to keep the DB clean and avoid costly destroy callbacks
   ActiveRecord::Base.transaction do

data/lib/rails_benchmark_suite/{suites/cache_heft_suite.rb → workloads/cache_heft_workload.rb}

@@ -3,8 +3,8 @@
 require "active_support/cache"
 require "securerandom"
 
-# Benchmark Suite
-RailsBenchmarkSuite.register_suite("Cache Heft", weight: 0.1) do
+# Benchmark Workload
+RailsBenchmarkSuite.register_workload("Cache Heft", weight: 0.1) do
   # Simulate SolidCache using MemoryStore
   @cache ||= ActiveSupport::Cache::MemoryStore.new
   

data/lib/rails_benchmark_suite/{suites/image_heft_suite.rb → workloads/image_heft_workload.rb}

@@ -11,7 +11,7 @@ begin
   SAMPLE_IMAGE = File.join(ASSET_DIR, "sample.jpg")
 
   # Only register if vips is actually available
-  RailsBenchmarkSuite.register_suite("Image Heft", weight: 0.1) do
+  RailsBenchmarkSuite.register_workload("Image Heft", weight: 0.1) do
     # Gracefully handle missing dependencies
     if File.exist?(SAMPLE_IMAGE)
       ImageProcessing::Vips
@@ -25,7 +25,6 @@ begin
   end
 
 rescue LoadError, StandardError
-  # Don't register the suite at all if vips is unavailable
-  puts "⚠️  Skipping Image Heft: libvips not available. Install with: brew install vips (macOS)"
+  # Don't register the workload at all if vips is unavailable
+  puts "⚠️  Skipping Image Workload: libvips not available. Install with: 'brew install vips' (macOS) or 'sudo apt install libvips-dev' (Linux)"
 end
-

data/lib/rails_benchmark_suite/{suites/job_heft_suite.rb → workloads/job_heft_workload.rb}

@@ -4,7 +4,7 @@ require "active_record"
 require "json"
 
 
-RailsBenchmarkSuite.register_suite("Solid Queue Heft", weight: 0.2) do
+RailsBenchmarkSuite.register_workload("Solid Queue Heft", weight: 0.2) do
   # Simulation: Enqueue 100 jobs, then work them off
   
   # 1. Enqueue Loop

data/lib/rails_benchmark_suite/{suites/view_heft_suite.rb → workloads/view_heft_workload.rb}

@@ -3,17 +3,17 @@
 require "action_view"
 require "ostruct"
 
-# Benchmark Suite
+# Benchmark Workload
 
 
-# Helper for the suite
+# Helper for the workload
 module RailsBenchmarkSuiteNumberHelper
   def self.number_with_delimiter(number)
     number.to_s.gsub(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1,")
   end
 end
 
-  RailsBenchmarkSuite.register_suite("View Heft", weight: 0.2) do
+  RailsBenchmarkSuite.register_workload("View Heft", weight: 0.2) do
     # Setup context once
     @view_renderer ||= begin
       lookup_context = ActionView::LookupContext.new([File.expand_path(__dir__)])

data/lib/rails_benchmark_suite.rb

@@ -3,6 +3,9 @@
 require "concurrent"
 require "rails_benchmark_suite/version"
 require "rails_benchmark_suite/reporter"
+require "rails_benchmark_suite/database_manager"
+require "rails_benchmark_suite/workload_runner"
+require "rails_benchmark_suite/formatter"
 require "rails_benchmark_suite/runner"
 require "rails_benchmark_suite/db_setup"
 require "rails_benchmark_suite/schema"
@@ -11,17 +14,17 @@ require "rails_benchmark_suite/models/post"
 require "rails_benchmark_suite/models/simulated_job"
 
 module RailsBenchmarkSuite
-  @suites = []
+  @workloads = []
 
-  def self.register_suite(name, weight: 1.0, &block)
-    @suites << { name: name, weight: weight, block: block }
+  def self.register_workload(name, weight: 1.0, &block)
+    @workloads << { name: name, weight: weight, block: block }
   end
 
   def self.run(json: false)
-    # Load suites
-    Dir[File.join(__dir__, "rails_benchmark_suite", "suites", "*.rb")].each { |f| require f }
+    # Load workloads
+    Dir[File.join(__dir__, "rails_benchmark_suite", "workloads", "*.rb")].each { |f| require f }
     
-    runner = Runner.new(@suites, json: json)
+    runner = Runner.new(@workloads, json: json)
     runner.run
   end
 end

data/rails_benchmark_suite.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["RailsBenchmarkSuite Contributors"]
   spec.email         = ["team@rails.org"]
 
-  spec.summary       = "Rails-style functionality & performance benchmark tool"
-  spec.description   = "Measures the 'Heft' (processing power) of a machine using realistic Rails workloads."
+  spec.summary       = "Rails Heft Index (RHI) - Hardware benchmarking using realistic workloads"
+  spec.description   = "Measures the Rails Heft Index (RHI), a weighted performance score based on realistic Rails 8+ workloads across Active Record, caching, views, jobs, and image processing."
   spec.homepage      = "https://github.com/overnet/rails_benchmark_suite"
   spec.license       = "MIT"
 
@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 2.5"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "ostruct", "~> 0.6"
 
   spec.required_ruby_version = ">= 3.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_benchmark_suite
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.0
 platform: ruby
 authors:
 - RailsBenchmarkSuite Contributors
@@ -163,8 +163,23 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-description: Measures the 'Heft' (processing power) of a machine using realistic Rails
-  workloads.
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description: Measures the Rails Heft Index (RHI), a weighted performance score based
+  on realistic Rails 8+ workloads across Active Record, caching, views, jobs, and
+  image processing.
 email:
 - team@rails.org
 executables:
@@ -182,19 +197,22 @@ files:
 - Rakefile
 - bin/rails_benchmark_suite
 - lib/rails_benchmark_suite.rb
+- lib/rails_benchmark_suite/database_manager.rb
 - lib/rails_benchmark_suite/db_setup.rb
+- lib/rails_benchmark_suite/formatter.rb
 - lib/rails_benchmark_suite/models/post.rb
 - lib/rails_benchmark_suite/models/simulated_job.rb
 - lib/rails_benchmark_suite/models/user.rb
 - lib/rails_benchmark_suite/reporter.rb
 - lib/rails_benchmark_suite/runner.rb
 - lib/rails_benchmark_suite/schema.rb
-- lib/rails_benchmark_suite/suites/active_record_suite.rb
-- lib/rails_benchmark_suite/suites/cache_heft_suite.rb
-- lib/rails_benchmark_suite/suites/image_heft_suite.rb
-- lib/rails_benchmark_suite/suites/job_heft_suite.rb
-- lib/rails_benchmark_suite/suites/view_heft_suite.rb
 - lib/rails_benchmark_suite/version.rb
+- lib/rails_benchmark_suite/workload_runner.rb
+- lib/rails_benchmark_suite/workloads/active_record_workload.rb
+- lib/rails_benchmark_suite/workloads/cache_heft_workload.rb
+- lib/rails_benchmark_suite/workloads/image_heft_workload.rb
+- lib/rails_benchmark_suite/workloads/job_heft_workload.rb
+- lib/rails_benchmark_suite/workloads/view_heft_workload.rb
 - rails_benchmark_suite.gemspec
 homepage: https://github.com/overnet/rails_benchmark_suite
 licenses:
@@ -219,5 +237,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: Rails-style functionality & performance benchmark tool
+summary: Rails Heft Index (RHI) - Hardware benchmarking using realistic workloads
 test_files: []