rails_benchmark_suite 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 150b032cfebbd12d60c2a407a292cf04367c4b821d44541aa21c7b01243b5288
-  data.tar.gz: 5fcffc2550db42c299f3c417abb11c9b2d8c3bdea7a27ecf3f8fd7c1d624bf31
+  metadata.gz: 473aa21869380dae81d4f9ee8668ccf161721923fd6c453cc711caf9d6303fd1
+  data.tar.gz: 5101bb8d63885263dc3fcbb8851d52f3ed48a1f919b0abfab38d43dc3f3df2a2
 SHA512:
-  metadata.gz: 785219aa58ac8b7353bf67920c4f419bf628d92f2fc539f02bd09408fb7aac13a6352d5aa68a09f0c60a7f1d95c34e016d12bb4ab015544ecf6962ca0c72aa54
-  data.tar.gz: 81706842da33247fbace2b62c4dee9f42332ff83a9ed1ab905960296f4954f6915c4055abe97910d9a2e572472d9454ebe7e01fce17dba0b604cd4b43f2f4988
+  metadata.gz: 11311aa76df4c103c8b3ea2e12a803ddeb339cd454127b246557341ddd5c7872fa01c4ff00f4c14ae711d95b48f0d84b148ec7f8b0a39fda7ab70cac0d070bad
+  data.tar.gz: 3f141277e2daae966aa4d7d7be684e112889fa757282e36a4f35ac34d60ac91ca76903281d9e091b9549ef567d6e8b7a26b13221326bf8273c3c33fe7e6082fc

data/.gitignore

@@ -3,3 +3,5 @@
 vendor/bundle/
 Gemfile.lock
 .ruby-lsp/
+*.gem
+rails_benchmark_report.html

data/CHANGELOG.md

@@ -1,4 +1,23 @@
 # Changelog
+## [0.3.1] - 2026-01-04
+*Major Architectural Repair & TTY Overhaul*
+
+### Added
+- **--html**: Static HTML Reporter with Chart.js visualization.
+- **--profile**: Automated "Scaling Efficiency" calculation (1T vs MaxT).
+- **--db**: Real database integration (Postgres/MySQL support).
+- **Hardware Awareness**: Auto-detection of CPU cores for thread defaults.
+- **UI**: Rich terminal output using `tty-spinner`, `tty-table`, and `tty-box` for a dashboard-style report.
+- **Architecture**: Implemented the standard `lib/dummy` Rails Engine pattern for internal tests.
+
+### Changed
+- **Refactor**: Complete structural overhaul. Moved monolithic logic from `lib/rails_benchmark_suite.rb` into a proper namespace (`lib/rails_benchmark_suite/`).
+- **Concurrency**: Default thread count is now dynamic (`Etc.nprocessors`) instead of hardcoded to 4.
+- **Safety**: Renamed internal test model from `User` to `BenchmarkUser` to prevent collisions when running inside host apps.
+
+### Fixed
+- **CLI**: Fixed the non-functional `--help` flag (now implemented via `OptionParser`).
+- **Reporting**: Restored the "Scaling (x)" column in the final report to correctly visualize performance degradation.
 
 ## [0.3.0] - 2025-01-03
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rails_benchmark_suite (0.3.0)
+    rails_benchmark_suite (0.3.1)
       actionview (~> 8.1)
       activerecord (~> 8.1)
       activestorage (~> 8.1)
@@ -9,7 +9,11 @@ PATH
       concurrent-ruby (~> 1.3)
       get_process_mem (~> 1.0)
       image_processing (~> 1.14)
+      pastel (~> 0.8)
       sqlite3 (~> 2.8)
+      tty-box (~> 0.7)
+      tty-spinner (~> 0.9)
+      tty-table (~> 0.12)
 
 GEM
   remote: https://rubygems.org/
@@ -117,6 +121,8 @@ GEM
     nokogiri (1.19.0-x86_64-linux-musl)
       racc (~> 1.4)
     ostruct (0.6.3)
+    pastel (0.8.0)
+      tty-color (~> 0.5)
     racc (1.8.1)
     rack (3.2.4)
     rack-session (2.1.1)
@@ -146,9 +152,29 @@ GEM
     sqlite3 (2.9.0-x86_64-darwin)
     sqlite3 (2.9.0-x86_64-linux-gnu)
     sqlite3 (2.9.0-x86_64-linux-musl)
+    strings (0.2.1)
+      strings-ansi (~> 0.2)
+      unicode-display_width (>= 1.5, < 3.0)
+      unicode_utils (~> 1.4)
+    strings-ansi (0.2.0)
     timeout (0.6.0)
+    tty-box (0.7.0)
+      pastel (~> 0.8)
+      strings (~> 0.2.0)
+      tty-cursor (~> 0.7)
+    tty-color (0.6.0)
+    tty-cursor (0.7.1)
+    tty-screen (0.8.2)
+    tty-spinner (0.9.3)
+      tty-cursor (~> 0.7)
+    tty-table (0.12.0)
+      pastel (~> 0.8)
+      strings (~> 0.2.0)
+      tty-screen (~> 0.8)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
+    unicode-display_width (2.6.0)
+    unicode_utils (1.4.0)
     uri (1.1.1)
     useragent (0.16.11)
 

data/README.md

@@ -26,6 +26,19 @@ The Heft Score is a weighted metric representing a machine's ability to handle R
 | **150+** | 🚀 High Performance | Apple M-series Pro/Max, Ryzen 5000+ |
 | **300+** | ⚡ Blazing | Server-grade Metal, M3 Ultra |
 
+### 📊 Visual Reports (HTML)
+
+Visualize your threading efficiency and bottlenecks with a self-contained dashboard:
+
+```bash
+bundle exec rails_benchmark_suite -t 8 --html
+```
+
+This generates `rails_benchmark_report.html` containing:
+- **Scaling Curve**: Interactive bar chart comparing 1-thread vs Max-thread throughput.
+- **Efficiency Heatmap**: Score cards identifying which workloads are Gil-bound vs CPU-bound.
+- **Detailed Metrics**: Raw IPS and detailed scaling factors.
+
 ---
 
 ## 🚀 Quick Start
@@ -89,10 +102,34 @@ 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
+### 📊 Visual Diagnostics (HTML Report)
+
+![Rails Benchmark Suite Report](docs/images/report_v0_3_1.png)
+
+To diagnose scaling bottlenecks, run the tool in Profile Mode (`--profile`) and generate the HTML Report (`--html`). This compares Single-Thread vs Multi-Thread performance side-by-side.
+
+```bash
+bundle exec rails_benchmark_suite --profile --html
+```
+
+**Opening the Report**:
+- **Local:** `open tmp/rails_benchmark_report.html`
+- **Remote:** `scp user@server:/current/path/tmp/rails_benchmark_report.html .`
+
+### Command Line Options
+
+| Flag | Description |
+| :--- | :--- |
+| `--html` | Generates a visual dashboard (`tmp/rails_benchmark_report.html`). **Best used with `--profile`.** |
+| `--profile` | **Diagnostic Mode.** Runs the benchmark twice (1 Thread vs Max Threads) to calculate "Scaling Efficiency." Required to populate the "Scaling Curve" charts. |
+| `--db` | Uses your local `config/database.yml` (Postgres/MySQL) instead of the synthetic in-memory SQLite. |
+| `-t [N]` | Manually set the thread count (Default: Auto-detects CPU cores). |
+
+### Configuration Flags
+- `--json`: Output results in JSON format
 - `--skip-rails`: Run in isolated mode without loading Rails environment
 - `--version`: Display gem version
-- `--help`: Show all available options
+- `-h` / `--help`: Show usage help
 
 ### Standalone Usage
 

data/bin/rails_benchmark_suite

@@ -2,11 +2,13 @@
 # frozen_string_literal: true
 
 require "optparse"
+require "etc"
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "rails_benchmark_suite"
 require "rails_benchmark_suite/version"
 
-options = {}
+config = RailsBenchmarkSuite::Configuration.new
+
 OptionParser.new do |opts|
   opts.banner = "Usage: rails_benchmark_suite [options]"
 
@@ -15,12 +17,28 @@ OptionParser.new do |opts|
     exit 0
   end
 
+  opts.on("-t", "--threads N", Integer, "Number of threads (default: auto set to #{Etc.nprocessors} cores)") do |n|
+    config.threads = n
+  end
+
+  opts.on("-p", "--profile", "Enable scaling efficiency profile mode") do
+    config.profile = true
+  end
+
+  opts.on("-d", "--db", "Use real database from config/database.yml instead of in-memory SQLite") do
+    config.db = true
+  end
+
   opts.on("--skip-rails", "Skip Rails environment loading") do
-    options[:skip_rails] = true
+    config.skip_rails = true
   end
 
   opts.on("-j", "--json", "Output results as JSON") do
-    options[:json] = true
+    config.json = true
+  end
+
+  opts.on("--html", "Generate a visual HTML report (rails_benchmark_report.html)") do
+    config.html = true
   end
 
   opts.on("-h", "--help", "Prints this help") do
@@ -29,20 +47,21 @@ OptionParser.new do |opts|
   end
 end.parse!
 
-unless options[:json]
+unless config.json
   puts "RailsBenchmarkSuite v#{RailsBenchmarkSuite::VERSION}"
+  puts "Configuration: Threads=#{config.threads} | Profile=#{config.profile} | Local DB=#{config.db}"
 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..." unless options[:json]
+if !config.skip_rails && File.exist?(rails_env_path)
+  puts "Rails environment detected at #{rails_env_path}. Loading..." unless config.json
   require rails_env_path
-  puts "Rails loaded successfully." unless options[:json]
+  puts "Rails loaded successfully." unless config.json
 else
-  unless options[:json]
-    if options[:skip_rails]
+  unless config.json
+    if config.skip_rails
       puts "Skipping Rails loading (requested via --skip-rails)."
     else
       puts "No Rails environment detected (config/environment.rb not found)."
@@ -50,4 +69,4 @@ else
   end
 end
 
-RailsBenchmarkSuite.run(json: options[:json])
+RailsBenchmarkSuite::Runner.new(config).run

data/lib/dummy/app/models/benchmark_job.rb

@@ -0,0 +1,7 @@
+module RailsBenchmarkSuite
+  module Dummy
+    class BenchmarkJob < ActiveRecord::Base
+      self.table_name = "simulated_jobs" # Keep table name consistent or rename? Let's use simulated_jobs as it's descriptive
+    end
+  end
+end

data/lib/dummy/app/models/benchmark_post.rb

@@ -0,0 +1,9 @@
+module RailsBenchmarkSuite
+  module Dummy
+    class BenchmarkPost < ActiveRecord::Base
+      self.table_name = "benchmark_posts"
+
+      belongs_to :user, class_name: "RailsBenchmarkSuite::Dummy::BenchmarkUser", foreign_key: "benchmark_user_id"
+    end
+  end
+end

data/lib/dummy/app/models/benchmark_user.rb

@@ -0,0 +1,9 @@
+module RailsBenchmarkSuite
+  module Dummy
+    class BenchmarkUser < ActiveRecord::Base
+      self.table_name = "benchmark_users"
+
+      has_many :posts, class_name: "RailsBenchmarkSuite::Dummy::BenchmarkPost", foreign_key: "benchmark_user_id"
+    end
+  end
+end

data/lib/dummy/app/views/rails_benchmark_suite/heft_view.html.erb

@@ -0,0 +1,11 @@
+<h1>Dashboard for <%= user.name %></h1>
+<ul>
+  <% posts.each do |post| %>
+    <li>
+      <strong><%= post.title %></strong>
+      <p><%= post.body.truncate(50) %></p>
+      <small>Views: <%= number_with_delimiter(post.views) %></small>
+    </li>
+  <% end %>
+</ul>
+<footer>Generated at <%= Time.now.to_s %></footer>

data/lib/dummy/config/benchmark_database.yml

@@ -0,0 +1,16 @@
+# Dummy DB Config for isolated benchmarking
+test:
+  adapter: sqlite3
+  database: ":memory:"
+  pool: 50
+  timeout: 5000
+
+development:
+  adapter: sqlite3
+  database: "file:dummy_bench.sqlite3?mode=memory&cache=shared"
+  pool: 50
+  timeout: 30000 
+  # High performance settings
+  variables:
+    journal_mode: WAL
+    synchronous: NORMAL

data/lib/rails_benchmark_suite/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module RailsBenchmarkSuite
+  class Configuration
+    attr_accessor :threads, :profile, :db, :skip_rails, :json, :html
+
+    def initialize
+      @threads = Etc.nprocessors
+      @profile = false
+      @db = false
+      @skip_rails = false
+      @json = false
+      @html = false
+    end
+
+    def db_mode
+      @db ? "Local DB" : "SQLite (Memory)"
+    end
+  end
+end

data/lib/rails_benchmark_suite/database_manager.rb

@@ -1,38 +1,56 @@
 # frozen_string_literal: true
 
 require "active_record"
+require "yaml"
 
 module RailsBenchmarkSuite
   class DatabaseManager
     SETUP_MUTEX = Mutex.new
 
-    def setup
+    def setup(use_local_db: false)
       # 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
-      )
+      if use_local_db
+        setup_real_database
+      else
+        setup_dummy_database
+      end
+    end
+
+    private
 
-      # The 'Busy Timeout' Hammer - force it directly on the raw connection
-      ActiveRecord::Base.connection.raw_connection.busy_timeout = 10000
+    def setup_real_database
+      config_path = File.join(Dir.pwd, "config", "database.yml")
+      unless File.exist?(config_path)
+        raise "Database config not found at #{config_path} (required for --db option)"
+      end
+
+      db_config = YAML.load_file(config_path)
+      env = defined?(Rails) ? Rails.env : "development"
       
-      # Setup Schema once safely with Mutex
+      ActiveRecord::Base.establish_connection(db_config[env])
+      puts "Connected to local database (#{env})"
+    end
+
+    def setup_dummy_database
+      # Load internal dummy config
+      config_path = File.expand_path("../dummy/config/benchmark_database.yml", __dir__)
+      db_config = YAML.load_file(config_path)
+      
+      # Use "development" profile which has the PRAGMA optimizations
+      ActiveRecord::Base.establish_connection(db_config["development"])
+
+      # Apply manual optimizations if needed (though config should handle it)
+      conn = ActiveRecord::Base.connection.raw_connection
+      conn.busy_timeout = 10000
+      
+      # Setup Schema once safely
       SETUP_MUTEX.synchronize do
-        # Verify if schema already loaded by checking for a table
-        unless ActiveRecord::Base.connection.table_exists?(:users)
+        unless ActiveRecord::Base.connection.table_exists?(:benchmark_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/models/user.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
+require "rails_benchmark_suite/dummy/app/models/benchmark_user"
+require "rails_benchmark_suite/dummy/app/models/benchmark_post"
+
 module RailsBenchmarkSuite
   module Models
-    class User < ActiveRecord::Base
-      has_many :posts, class_name: "RailsBenchmarkSuite::Models::Post", dependent: :destroy
-    end
+    # Proxy or Legacy support if needed, but primary logic is now in Dummy namespace
   end
 end

data/lib/rails_benchmark_suite/reporter.rb

@@ -1,15 +1,28 @@
 # frozen_string_literal: true
 
+require "json"
+require "tty-table"
+require "tty-box"
+require "pastel"
+require "tty-cursor"
+
 module RailsBenchmarkSuite
   module Reporter
     module_function
 
+    def pastel
+      @pastel ||= Pastel.new
+    end
+
+    def cursor
+      @cursor ||= TTY::Cursor
+    end
+
     def system_info
       {
         ruby_version: RUBY_VERSION,
         platform: RUBY_PLATFORM,
-        processors: Concurrent.processor_count,
-        libvips: libvips?,
+        processors: defined?(Etc) ? Etc.nprocessors : Concurrent.processor_count,
         yjit: yjit_enabled?
       }
     end
@@ -18,9 +31,206 @@ module RailsBenchmarkSuite
       defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled?
     end
 
-    def libvips?
-      # Naive check for libvips presence
-      system("vips --version", out: File::NULL, err: File::NULL)
+    def header(info)
+      print cursor.hide
+      # Build YJIT Status
+      yjit_status = info[:yjit] ? pastel.green("ON") : pastel.red("OFF")
+      yjit_hint = info[:yjit] ? "" : " (use RUBY_OPT=\"--yjit\")"
+      
+      content = [
+        "System: #{info[:processors]} Cores | Ruby #{info[:ruby_version]}",
+        "DB: #{info[:db_mode] || 'SQLite (Memory)'} | YJIT: #{yjit_status}#{yjit_hint}"
+      ].join("\n")
+
+      print TTY::Box.frame(
+        width: 80, 
+        title: { top_left: " Rails Benchmark Suite v#{RailsBenchmarkSuite::VERSION} " },
+        padding: 1,
+        style: {
+          fg: :white,
+          border: { fg: :bright_blue }
+        }
+      ) { content }
+      puts ""
+    end
+
+    def render(payload)
+      results = payload[:results]
+      total_score = payload[:total_score]
+      tier = payload[:tier]
+      threads = payload[:threads] || 4
+      
+      puts ""
+      
+      # 1. Comparison Table
+      rows = results.map do |data|
+        report = data[:report]
+        entries = report.entries
+        
+        entry_1t = entries.find { |e| e.label.include?("(1 thread)") }
+        entry_mt = entries.find { |e| e.label.match?(/\(\d+ threads\)/) }
+        
+        ips_1t = entry_1t ? entry_1t.ips : 0
+        ips_mt = entry_mt ? entry_mt.ips : 0
+        
+        scaling = ips_1t > 0 ? (ips_mt / ips_1t) : 0
+        efficiency = (ips_mt / (ips_1t * threads)) * 100 if ips_1t > 0 && threads > 0
+        efficiency ||= 0
+        
+        # Color coding
+        eff_color = if efficiency >= 75
+          :green
+        elsif efficiency >= 50
+          :yellow
+        else
+          :red
+        end
+        
+        # Colorize scaling (Simple heuristic per user request)
+        scale_str = "%.2fx" % scaling
+        if scaling >= 1.0
+          scale_str = pastel.green(scale_str)
+        else
+          scale_str = pastel.red(scale_str)
+        end
+
+        [
+          data[:name],
+          humanize(ips_1t),
+          humanize(ips_mt),
+          scale_str,
+          pastel.decorate("#{efficiency.round(1)}%", eff_color),
+          data[:adjusted_weight].round(2)
+        ]
+      end
+
+      table = TTY::Table.new(
+        header: ["Workload", "1T IPS", "MaxT IPS", "Scaling", "Efficiency", "Weight"], 
+        rows: rows
+      )
+      
+      puts table.render(:unicode, padding: [0, 1]) do |renderer|
+        renderer.border.separator = :each_row
+        renderer.border.style = :blue
+      end
+      
+      # 2. Insights List
+      puts ""
+      check_scaling_insights(results)
+      check_yjit_insight
+      check_memory_insights(results)
+      
+      # 3. Final Score Dashboard
+      render_final_score(total_score)
+      show_hardware_tier(tier)
+    end
+
+    def check_scaling_insights(results)
+      poor_scaling = results.select do |r|
+        entries = r[:report].entries
+        entry_1t = entries.find { |e| e.label.include?("(1 thread)") }
+        entry_mt = entries.find { |e| e.label.match?(/\(\d+ threads\)/) }
+        
+        ips_1t = entry_1t ? entry_1t.ips : 0
+        ips_mt = entry_mt ? entry_mt.ips : 0 
+        scaling = ips_1t > 0 ? (ips_mt / ips_1t) : 0
+        scaling < 0.8
+      end
+      
+      if poor_scaling.any?
+        puts pastel.yellow.bold("💡 Insight (Scaling):") + " Scaling below 1.0x detected."
+        puts "   This indicates SQLite lock contention or Ruby GIL saturation."
+      end
+    end
+
+    def check_yjit_insight
+      unless yjit_enabled?
+        puts ""
+        puts pastel.yellow.bold("💡 Insight (YJIT):") + " YJIT is OFF."
+        puts "   Run with RUBY_OPT=\"--yjit\" for ~20% boost."
+      end
+    end
+
+    def check_memory_insights(results)
+      results.select { |r| r[:memory_delta_mb] > 20 }.each do |r|
+        puts ""
+        puts pastel.yellow.bold("💡 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"
+        "Entry-Level (Suitable for dev/testing)"
+      when "Production-Ready"
+        "Professional-Grade (Matches dedicated instances)"
+      else
+        "High-Performance (Bare-metal speed)"
+      end
+      
+      puts ""
+      puts pastel.bold("📊 Performance Tier: ") + comparison
+      puts ""
+      print cursor.show
+    end
+
+    def render_final_score(score)
+      score_str = "#{score.round(0)}"
+      puts ""
+      
+      print TTY::Box.frame(
+        width: 40,
+        height: 5,
+        align: :center,
+        padding: 1,
+        title: { top_left: " RAILS HEFT INDEX " },
+        style: { border: { fg: :green }, fg: :green }
+      ) {
+        pastel.bold(score_str)
+      }
+    end
+
+    def as_json(payload)
+      out = {
+        system: 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_mt = entries.find { |e| e.label.match?(/\(\d+ threads\)/) }
+        
+        ips_1t = entry_1t ? entry_1t.ips : 0
+        ips_mt = entry_mt ? entry_mt.ips : 0
+        
+        out[:workloads] << {
+          name: data[:name],
+          adjusted_weight: data[:adjusted_weight],
+          ips_1t: ips_1t,
+          ips_mt: ips_mt,
+          threads: payload[:threads],
+          scaling: ips_1t > 0 ? (ips_mt / ips_1t) : 0,
+          efficiency: data[:efficiency],
+          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