rails_benchmark_suite 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4dba673f286e0a526b602537257364dda4b7477eed8698d7f69a0993b3b0ff5
-  data.tar.gz: 344f0dd405e3249068746359edff5d9b1578bdf2bb736861f27548283f64d91d
+  metadata.gz: 150b032cfebbd12d60c2a407a292cf04367c4b821d44541aa21c7b01243b5288
+  data.tar.gz: 5fcffc2550db42c299f3c417abb11c9b2d8c3bdea7a27ecf3f8fd7c1d624bf31
 SHA512:
-  metadata.gz: 65ae4cd0975954f2d7ccb3e5b60d25c587eb76d7ea3d3bfc771b1e879c6ccf5b6749b823323506973c500c49c415b2050b12bacdc7b497fc4d3e9791c1ac9943
-  data.tar.gz: d1af906dc1e84f78d92b74c27f74156aa8fd25d92016a317d342a084f5657bc72d2eb2f6b6e10a822e46073c71f886a1563e8f52d2ee5f68764b5e68c41a4a35
+  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

@@ -1,29 +1,44 @@
-# Rails Benchmark Suite
+# Rails Benchmark Suite 🚀
+
+**Standardized Hardware Benchmarking for Rails 8.1+**
 
 A standardized performance suite designed to measure the "Heft" of a machine using realistic, high-throughput Rails 8+ workloads.
 
-Unlike synthetic CPU benchmarks, **Rails Benchmark Suite** simulates Active Record object allocation, SQL query complexity, ActionView rendering, and background job throughput.
+## 🛠 What is this?
+
+Think of this as a **"Test Track" for Rails servers**. Unlike profilers that measure your specific application code, this gem runs a **fixed, standardized set of Rails operations** (Active Record object allocation, SQL query complexity, ActionView rendering, and background job throughput) to measure the raw performance of your server and Ruby configuration.
+
+To ensure a level playing field, the gem boots an **isolated, in-memory SQLite environment**. It creates its own schema and records, meaning it **never touches your production data** and returns comparable results across any machine.
 
 ## 📊 The "Heft" Score
 
-The Heft Score is a weighted metric representing a machine's ability to handle Rails tasks. 
-- **Baseline:** A score of **100** is calibrated to represent an **AWS c6g.large** (ARM) instance.
-- **Objective:** To provide a simple, comparable number for evaluating different computing platforms (Cloud VMs, bare-metal, or local dev rigs).
+The Heft Score is a weighted metric representing a machine's ability to handle Rails tasks.
+* **Baseline:** A score of **100** is calibrated to represent an **AWS c6g.large** (ARM) instance.
+* **Objective:** To provide a simple, comparable number for evaluating different computing platforms (Cloud VMs, bare-metal, or local dev rigs).
 
 ### Baseline Comparisons
+
 | Score | Classification | Comparable Hardware |
 | :--- | :--- | :--- |
-| < 40 | 🐢 Sluggish | Older Intel Macs, Entry-level VPS |
-| 60 | 🚙 Capable | Standard Cloud VM (c5.large/standard) |
-| **100** | **🏎️ Baseline** | **AWS c6g.large (2 vCPU ARM)** |
-| 150+ | 🚀 High Performance | Apple M-series Pro/Max, Ryzen 5000+ |
-| 300+ | ⚡ Blazing | Server-grade Metal, M3 Ultra |
+| **< 40** | 🐢 Sluggish | Older Intel Macs, Entry-level VPS |
+| **60** | 🚙 Capable | Standard Cloud VM (c5.large/standard) |
+| **100** | 🏎️ Baseline | AWS c6g.large (2 vCPU ARM) |
+| **150+** | 🚀 High Performance | Apple M-series Pro/Max, Ryzen 5000+ |
+| **300+** | ⚡ Blazing | Server-grade Metal, M3 Ultra |
+
+---
+
+## 🚀 Quick Start
+
+Ensure you are in your Rails root directory and run:
 
-### Quick Start
 ```bash
 ruby --yjit -S bundle exec rails_benchmark_suite
 ```
-**Note:** `bundle exec` is required for Rails environment stability and to prevent Minitest version conflicts.
+
+**Note:** `bundle exec` is mandatory for Rails environment stability and to prevent Minitest version conflicts.
+
+---
 
 ## 🛠 Technical Philosophy
 
@@ -32,17 +47,55 @@ Rails Benchmark Suite prioritizes **Benchmarking** (via `benchmark-ips`) over **
 * **Benchmarking:** Focuses on macro-throughput—"How many iterations can the hardware handle?" This provides the final Heft Score.
 * **Why no Profiling?** Profiling tools (like `StackProf` or `Vernier`) introduce instrumentation overhead that skews hardware metrics. We aim for "Conceptual Compression"—one clear number to inform infrastructure decisions.
 
+---
+
 ## 🚀 Installation & Usage
 
 ### Requirements
-- **Ruby**: 3.3+ (Ruby with YJIT support highly recommended for accurate performance measurement)
+* **Ruby:** 3.3+ (Ruby with YJIT support highly recommended)
+* **Rails:** 8.1+
+* **Database:** SQLite3
+
+## 📋 System Requirements
+
+### Required
+- **Ruby**: 3.3+ (3.4+ recommended for YJIT)
+- **Rails**: 8.0+  
 - **Database**: SQLite3
 
-### Prerequisites
-* **Ruby:** 3.4.1+ (Recommended for latest YJIT/Prism performance)
-* **Database:** SQLite3
+### 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.
+
+### 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
+
 If you want to test hardware performance without an existing application:
 
 ```bash
@@ -52,93 +105,84 @@ bundle install
 bin/rails_benchmark_suite
 ```
 
-### Use within a Rails Application
-Rails Benchmark Suite is "Rails-aware." Adding it to your app allows you to benchmark your specific configuration and custom suites.
+---
+
+## 📐 How It's Calculated
 
-Add to your Gemfile:
+The **Rails Heft Index (RHI)** measures your hardware's ability to handle Rails workloads using this formula:
 
-```ruby
-gem "rails_benchmark_suite", group: :development
+```
+RHI Score = Σ (4-Thread IPS × Weight)
 ```
 
-## Usage
+### Workload Weights
 
-To get the most accurate 'Heft' score, run with YJIT enabled:
+| 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 |
 
-```bash
-ruby --yjit -S bundle exec rails_benchmark_suite
-```
+**Why 4-Thread IPS?** We use 4-thread performance to simulate production concurrency where multiple requests are handled simultaneously.
 
-**Why these 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.
-- `bundle exec`: Prevents version conflicts (e.g., Minitest) between the gem and your host application.
+**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.
 
-**Standalone Usage:**
-If running outside a Rails project:
+### Hardware Tiers
 
-```bash
-bin/rails_benchmark_suite
-```
-
-**JSON Output:**
-For programmatic consumption:
+Your RHI score maps to these performance tiers:
 
-```bash
-ruby --yjit -S bundle exec rails_benchmark_suite --json
-```
+- **< 50**: Entry/Dev - Suitable for local development
+- **50-200**: Production-Ready - Handles moderate production traffic
+- **> 200**: High-Performance - Optimized for high-traffic applications
 
-> **Note:** Use `--skip-rails` to ignore the host application and run in isolated mode.
+---
 
-## Performance
+## 🧪 The "Heft" Workloads
 
-**Understanding YJIT Status:**
+The gem measures performance across critical Rails subsystems using a dedicated, isolated schema:
 
-If you see `YJIT: Disabled`, this is a result of your Ruby binary build, not the gem itself. The gem will work perfectly fine without YJIT, but performance measurements will be more accurate with YJIT enabled.
+* **Active Record Heft:** Standardized CRUD: Creation, indexing, and complex querying.
+* **Cache Heft:** High-frequency read/writes to the Rails memory store.
+* **Solid Queue Heft:** Background job enqueuing and database-backed polling stress.
+* **View Heft:** Partial rendering overhead and ActionView throughput.
+* **Image Heft:** Image processing performance (requires libvips).
 
-To enable YJIT, you need Ruby compiled with YJIT support (requires Rust compiler during Ruby installation). See the Troubleshooting section below for installation instructions.
+---
 
-## Troubleshooting
+## ⚠️ Troubleshooting
 
 ### YJIT Shows "Disabled"
 
-If you see `YJIT: Disabled (Requires Ruby with YJIT support for best results)`, it means your Ruby was not compiled with YJIT support. To get the best performance:
+If you see `YJIT: Disabled`, it means your Ruby was not compiled with YJIT support.
 
-1. Ensure `rustc` (Rust compiler) is installed on your system
-2. Reinstall Ruby with YJIT support:
-   ```bash
-   # Using rbenv
-   RUBY_CONFIGURE_OPTS="--enable-yjit" rbenv install 3.4.1
-   
-   # Using rvm
-   rvm install 3.4.1 --enable-yjit
-   ```
-3. Verify YJIT is available: `ruby --yjit -e "puts RubyVM::YJIT.enabled?"`
+* **Fix (rbenv):** `RUBY_CONFIGURE_OPTS="--enable-yjit" rbenv install 3.4.1`
+* **Fix (rvm):** `rvm install 3.4.1 --enable-yjit`
 
 ### SQLite Lock Errors
 
-If you encounter `SQLite3::BusyException` or "database table is locked" errors, ensure you're running the latest version of the gem (v0.2.7+) which includes automatic concurrency retries with smart backoff.
+Version 0.2.9+ includes surgical connection resets and randomized backoffs to handle SQLite concurrency. If issues persist, ensure no other processes are accessing the benchmark database.
 
-**v0.2.7+** includes:
-- Automatic retry logic with sleep backoff
-- Per-thread unique identifiers to prevent conflicts
-- Optimized busy timeout settings (10 seconds)
-
-If issues persist, try reducing concurrency or ensuring no other processes are accessing the benchmark database.
+---
 
 ## 🏗 Architecture
+
 * **Engine:** Built on `benchmark-ips`.
-* **Database:** Uses In-Memory SQLite with `cache=shared` for multi-threaded accuracy.
-* **Isolation:** Uses transactional rollbacks (`ActiveRecord::Rollback`) to ensure test isolation without the overhead of row deletion.
-* **Threading:** Supports 1-thread and 4-thread scaling tests to measure vertical efficiency.
-* **Modern Stack:** Optimized for Rails 8+ defaults, including Solid Queue simulation and YJIT detection.
+* **Database:** Uses In-Memory SQLite with `cache=shared` and a 50-connection pool for multi-threaded accuracy.
+* **Isolation:** Uses transactional rollbacks and Mutex-wrapped schema creation.
+* **Threading:** Supports 1-thread and 4-thread scaling tests.
+
+---
 
 ## 📜 Credits
-This project is a functional implementation of the performance benchmark vision discussed in the Rails community.
 
 * **Vision:** Inspired by @dhh in [rails/rails#50451](https://github.com/rails/rails/issues/50451).
 * **Initial Roadmap:** Based on suggestions by @JoeDupuis.
 * **Implementation:** The Rails Community.
 
+---
+
 ## 📄 License
+
 The gem is available as open source under the terms of the MIT License.

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.8)
-      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.8"
+  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,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rails_benchmark_suite
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.3.0
 platform: ruby
 authors:
 - RailsBenchmarkSuite Contributors
 bindir: bin
 cert_chain: []
-date: 2026-01-02 00:00:00.000000000 Z
+date: 2026-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
@@ -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: []