rspec-turbo 0.1.0

data/lib/rspec_turbo/display.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module RSpecTurbo
+  # Owns every line printed to the terminal: the live per-worker spinner
+  # (TTY), the plain CI worker roster, and the final report — failures plus
+  # the slowest folders/files (fed by slow_profile.rb in each worker log).
+  class Display
+    def initialize(planner)
+      @planner = planner
+    end
+
+    # Folder label string for a batch's units, e.g. "models · requests".
+    def self.folder_labels(batch_units, with_counts: false, max_len: nil)
+      counts = Hash.new(0)
+      batch_units.each { |unit| counts[folder_for(unit)] += 1 }
+      label = counts.map { |folder, n| with_counts ? "#{folder}(#{n})" : folder }.join(" · ")
+
+      return label unless max_len
+
+      label.slice(0, max_len).then { |slice| (slice.length < label.length) ? "#{slice}…" : slice }
+    end
+
+    def self.folder_for(unit)
+      path = unit.is_a?(Array) ? unit.first.split("[").first.delete_prefix("./spec/") : unit
+      parts = path.split("/")
+
+      return parts[0] if parts.size <= 1 || parts[1].end_with?("_spec.rb")
+
+      "#{parts[0]}/#{parts[1]}"
+    end
+
+    def print_plan
+      total = @planner.counts.values.sum
+
+      puts
+      puts "  Found #{@planner.batches.flatten.size} spec files (#{total} examples) → #{@planner.batches.size} batches"
+      puts
+
+      @planner.batches.each_with_index do |batch, i|
+        label = format("worker/%02d", i + 1)
+        folders = Display.folder_labels(batch)
+
+        puts format("  %-10s  %3d files  ~%-4d ex   %s", label, batch.size, @planner.example_count(batch), folders)
+      end
+
+      puts
+    end
+
+    def print_report(results, wall_total, n_workers)
+      sum_total = results.sum { |r| r[:duration] }
+      speedup = sum_total.positive? ? (sum_total.to_f / wall_total).round(2) : 0
+      total_ex = results.sum { |r| @planner.example_count(r[:units]) }
+      file_data = parse_profiler_data(results.map { |r| Config.log_path(r[:label]) })
+      failed = results.select { |r| r[:status] == "FAIL" }
+
+      puts
+      puts Terminal::SEP_THICK
+      puts "  RSpec Turbo Report"
+      puts Terminal::SEP_THICK
+
+      # On a TTY you watch failures scroll by live, so show them first. In CI
+      # the log is read top-to-bottom afterwards, so push failures to the very
+      # end where they sit right above the one-line summary — easy to find.
+      if Config::TTY
+        print_failures(failed)
+        print_slowest(file_data)
+      else
+        print_slowest(file_data)
+        print_failures(failed)
+      end
+
+      print_summary(failed, total_ex, wall_total, sum_total, speedup, n_workers)
+    end
+
+    # Consolidated, sorted PASS/FAIL roster — printed once after every worker
+    # finishes (CI path) so the per-worker results form one clean block.
+    def print_worker_summary(results)
+      return if results.empty?
+
+      puts
+      puts Terminal::SEP_THICK
+      puts "  Workers"
+      puts Terminal::SEP_THICK
+      puts
+
+      results.sort_by { |r| r[:label] }.each do |r|
+        icon = (r[:status] == "PASS") ? "✓" : "✗"
+        code = (r[:status] == "PASS") ? "32" : "31"
+        line = format("#{icon} %-10s  %-7s  %-6s   %s",
+          r[:label], Terminal.fmt_duration(r[:duration]), r[:status], Display.folder_labels(r[:units]))
+
+        puts Terminal.c(code, line)
+      end
+    end
+
+    def spinner_line(state, frame)
+      folders = Display.folder_labels(state[:units], max_len: 55)
+
+      case state[:status]
+      when :pending
+        "  \e[90m○ #{state[:label]}\e[0m"
+      when :running
+        elapsed = state[:started] ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) - state[:started]).round : 0
+        spin = Terminal::SPINNER_FRAMES[frame % Terminal::SPINNER_FRAMES.size]
+        total = @planner.example_count(state[:units])
+
+        "  \e[36m#{spin} #{state[:label]}\e[0m  ~#{total} ex  #{Terminal.fmt_duration(elapsed)}   #{folders}"
+      when :done
+        color = (state[:result] == "PASS") ? "\e[32m" : "\e[31m"
+        icon = (state[:result] == "PASS") ? "✓" : "✗"
+
+        "  #{color}#{icon} #{state[:label]}  #{Terminal.fmt_duration(state[:duration])}  #{state[:result]}   #{folders}\e[0m"
+      end
+    end
+
+    private
+
+    def print_summary(failed, total_ex, wall_total, sum_total, speedup, n_workers)
+      pending_count = @planner.pending_count
+      pass_fail = failed.empty? ? Terminal.c("32", "✓ All passed") : Terminal.c("31", "✗ #{failed.size} failed")
+      wall_str = Terminal.c("33", format("wall %-7s", Terminal.fmt_duration(wall_total)))
+      sum_str = Terminal.c("90", "sum #{Terminal.fmt_duration(sum_total)}")
+      spd_str = Terminal.c("1", "#{speedup}x")
+      pending_str = pending_count.positive? ? "  ·  #{Terminal.c("33", "#{pending_count} pending")}" : ""
+
+      puts
+      puts "  #{pass_fail}  ·  #{total_ex} examples#{pending_str}  ·  #{n_workers} workers  ·  #{wall_str}  #{sum_str}  #{spd_str}"
+      puts
+      puts Terminal::SEP_THICK
+    end
+
+    def print_failures(failed)
+      return if failed.empty?
+
+      puts "  #{Terminal.c("31", "✗ #{failed.size} worker(s) failed: #{failed.map { |r| r[:label] }.join(", ")}")}"
+
+      failed.each do |r|
+        content = clean_log(Config.log_path(r[:label]))
+        next unless content
+
+        puts
+        puts Terminal.c("31", Terminal::SEP_THIN)
+        puts Terminal.c("31", "  Failures in #{r[:label]}")
+        puts Terminal.c("31", Terminal::SEP_THIN)
+        puts extract_failures(content)
+      end
+
+      puts "  #{Terminal::SEP_THIN}"
+    end
+
+    def extract_failures(content)
+      start = content.index("\nFailures:\n") ||
+        content.index("\nAn error occurred while loading") ||
+        content.index("\nFailed examples:")
+
+      return content.lines.last(30).join.strip unless start
+
+      finish = content.index("\nFinished in") ||
+        content.index(/\nTop \d/) ||
+        content.length
+
+      content[start...finish].strip
+    end
+
+    def print_slowest(file_data)
+      return if file_data.empty?
+
+      puts "  #{Terminal.c("1", "Slowest folders")}  #{Terminal.c("90", "↳ optimize these first")}"
+      puts
+
+      folder_times = aggregate_by_folder(file_data)
+      max_s = folder_times.first&.last.to_f
+
+      folder_times.first(8).each do |folder, seconds|
+        bar_width = max_s.positive? ? [(seconds / max_s * 20).round, 1].max : 1
+
+        puts format("  %-45s  %6s  %s", folder, Terminal.fmt_duration(seconds.round), slowest_bar(bar_width))
+      end
+
+      puts "  #{Terminal::SEP_THIN}"
+      puts "  #{Terminal.c("1", "Slowest files")}"
+      puts
+
+      file_data.sort_by { |e| -e[:seconds] }.first(5).each do |e|
+        puts format("  %-60s  %s", e[:file].delete_prefix("spec/"), Terminal.fmt_duration(e[:seconds].round))
+      end
+
+      puts "  #{Terminal::SEP_THIN}"
+    end
+
+    def slowest_bar(width)
+      return "#{"#" * width}#{"." * (20 - width)}" unless Config::TTY
+
+      "\e[37m#{"▓" * width}\e[90m#{"░" * (20 - width)}\e[0m"
+    end
+
+    # Parse "TOP N FILES BY TIME" sections (emitted by slow_profile.rb) from
+    # every worker log and flatten them into [{seconds:, file:}].
+    def parse_profiler_data(log_files)
+      log_files.filter_map { |log| clean_log(log) }.flat_map do |content|
+        section = content[/TOP \d+ FILES BY TIME.*?(?=\n\n|\z)/m]
+        next [] unless section
+
+        section.each_line.filter_map do |line|
+          m = line.match(%r{^\s*([\d.]+)s\s+\d+\s+(spec/.+)$})
+          m && {seconds: m[1].to_f, file: m[2].strip}
+        end
+      end
+    end
+
+    # Aggregate file times by their immediate parent folder (relative to spec/).
+    def aggregate_by_folder(file_data)
+      sums = Hash.new(0.0)
+
+      file_data.each do |e|
+        parts = e[:file].delete_prefix("spec/").split("/")
+        folder = (parts.size > 1) ? parts[0..-2].join("/") : parts[0]
+        sums[folder] += e[:seconds]
+      end
+
+      sums.sort_by { |_, seconds| -seconds }
+    end
+
+    # Read a worker log, scrub invalid bytes and strip ANSI colour codes.
+    def clean_log(path)
+      return nil unless File.exist?(path)
+
+      Terminal.strip_ansi(File.binread(path).force_encoding("UTF-8").scrub)
+    end
+  end
+end

data/lib/rspec_turbo/executor.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module RSpecTurbo
+  # Runs the planned batches across a fixed pool of slots: one Worker per free
+  # slot at a time, slots recycled as workers finish until the queue drains.
+  #
+  # Renders a live multi-line dashboard on a TTY (per-worker spinner lines plus
+  # a global progress bar) and periodic single-line [progress] updates on CI.
+  class Executor
+    attr_reader :wall_started
+
+    def initialize(planner, display, rspec_options)
+      @planner = planner
+      @display = display
+      @rspec_options = rspec_options
+      @labels = planner.batches.each_index.map { |i| format("worker/%02d", i + 1) }
+      @slots = (1..planner.batches.size).to_a
+      @total_examples = planner.counts.values.sum
+    end
+
+    def run
+      pending = Queue.new
+      @planner.batches.each_with_index { |units, i| pending << [@labels[i], units] }
+
+      results = []
+      @wall_started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      if Config::TTY
+        run_tty(pending, results)
+      else
+        run_plain(pending, results)
+      end
+
+      results
+    end
+
+    private
+
+    def run_tty(pending, results)
+      n = @labels.size
+      live = live_state
+      mutex = Mutex.new
+      frame = 0
+      spinning = true
+      max_done = 0
+
+      (n + 2).times { puts }  # reserve N worker lines + blank + progress bar
+
+      print "\e[?25l"
+      Signal.trap("INT") {
+        print "\e[?25h"
+        exit 130
+      }
+      Signal.trap("TERM") {
+        print "\e[?25h"
+        exit 143
+      }
+
+      spinner = Thread.new do
+        while spinning
+          sleep 0.1
+          mutex.synchronize do
+            done = @slots.sum { |s| read_progress(Config.progress_path(s)) }
+            max_done = done if done > max_done
+            repaint(live, frame, n, max_done)
+            frame += 1
+          end
+        end
+      end
+
+      run_pool(pending, results) do |event, worker, result|
+        mutex.synchronize do
+          case event
+          when :started then live[worker.label].merge!(status: :running, started: worker.started)
+          when :done then live[worker.label].merge!(status: :done, duration: result[:duration], result: result[:status])
+          end
+        end
+      end
+
+      spinning = false
+      spinner.join
+      mutex.synchronize { repaint(live, frame, n, @total_examples) }
+      cleanup_progress
+      print "\e[?25h"
+    end
+
+    def run_plain(pending, results)
+      total_workers = @planner.batches.size
+      active = true
+      interval = Config.progress_interval
+      completed = 0
+
+      puts Terminal::SEP_THICK
+      puts "  RSpec Turbo - CI Progress"
+      puts Terminal::SEP_THICK
+      puts
+      puts "  [progress] 0s  0/#{@total_examples} examples  0%  (0/#{total_workers} workers done)"
+      $stdout.flush
+
+      ticker = Thread.new do
+        ticks = 0
+
+        while active
+          sleep 1
+          ticks += 1
+          next unless (ticks % interval).zero?
+
+          done = @slots.sum { |s| read_progress(Config.progress_path(s)) }
+          pct = @total_examples.positive? ? "#{(done.to_f / @total_examples * 100).round}%" : "?"
+          wall = Terminal.fmt_duration(elapsed_since(@wall_started))
+          puts "  [progress] #{wall}  #{done}/#{@total_examples} examples  #{pct}  (#{completed}/#{total_workers} workers done)"
+          $stdout.flush
+        end
+      end
+
+      run_pool(pending, results) { |event, _worker, _result| completed += 1 if event == :done }
+    ensure
+      active = false
+      ticker&.join
+      @display.print_worker_summary(results)
+    end
+
+    # Shared scheduling loop: keep every free slot busy, reap finished workers,
+    # recycle their slot, record the result, and yield lifecycle events.
+    def run_pool(pending, results)
+      in_flight = {}
+      free_slots = @slots.dup
+
+      loop do
+        while !free_slots.empty? && !pending.empty?
+          label, units = pending.pop
+          slot = free_slots.shift
+          worker = Worker.spawn(label: label, units: units, slot: slot, rspec_options: @rspec_options)
+          in_flight[worker.pid] = worker
+          yield(:started, worker)
+        end
+
+        break if in_flight.empty?
+
+        pid, status = Process.wait2
+        next unless (worker = in_flight.delete(pid))
+
+        free_slots.push(worker.slot)
+        result = {label: worker.label, units: worker.units, status: status.success? ? "PASS" : "FAIL", duration: worker.duration}
+        results << result
+        yield(:done, worker, result)
+      end
+    end
+
+    def live_state
+      @labels.each_with_index.to_h do |label, i|
+        [label, {label: label, status: :pending, units: @planner.batches[i], started: nil, duration: nil, result: nil}]
+      end
+    end
+
+    def repaint(live, frame, n, done)
+      print "\e[#{n + 2}A"
+      @labels.each { |label| print "\e[2K#{@display.spinner_line(live[label], frame)}\n" }
+      print "\e[2K\n"
+      print "\e[2K#{progress_bar(done, @total_examples)}\n"
+    end
+
+    def cleanup_progress
+      @slots.each do |slot|
+        File.delete(Config.progress_path(slot))
+      rescue
+        nil
+      end
+    end
+
+    def elapsed_since(start_time) = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time).round
+
+    def read_progress(file)
+      return 0 unless file && File.exist?(file)
+
+      Integer(File.read(file).strip)
+    rescue
+      0
+    end
+
+    def progress_bar(done, total, width: 36)
+      return "" if total.zero?
+
+      pct = (done.to_f / total * 100).round
+      filled = (done.to_f / total * width).round
+      bar = "\e[37m#{"▓" * filled}\e[90m#{"░" * (width - filled)}\e[0m"
+
+      "  #{bar}  \e[36m#{done}/#{total}\e[0m  \e[1m#{pct}%\e[0m"
+    end
+  end
+end

data/lib/rspec_turbo/file_discovery.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RSpecTurbo
+  # Discovers *_spec.rb files under the given folders (or all of spec/ if none
+  # are given), de-duplicates them and applies --exclude-pattern glob filters.
+  #
+  # Returned paths are relative to spec/ (e.g. "models/user_spec.rb").
+  class FileDiscovery
+    FNMATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+    def initialize(folders, exclude_patterns: [])
+      @folders = folders
+      @exclude_patterns = exclude_patterns
+    end
+
+    def files
+      raw = collect_files
+
+      return raw if @exclude_patterns.empty?
+
+      raw.reject do |file|
+        @exclude_patterns.any? { |pattern| File.fnmatch(pattern, "spec/#{file}", FNMATCH_FLAGS) }
+      end
+    end
+
+    private
+
+    def collect_files
+      seen = Set.new
+      found = []
+      bases = @folders.empty? ? [""] : @folders
+
+      bases.each do |folder|
+        folder = folder.delete_prefix("spec/")
+        folder = "" if folder == "spec"  # bare "spec" means the whole spec/ tree
+        base = folder.empty? ? "spec" : File.join("spec", folder)
+
+        if File.file?(base)
+          found << folder if seen.add?(folder)
+        elsif File.directory?(base)
+          Dir.glob("#{base}/**/*_spec.rb").sort.each do |path|
+            rel = path.delete_prefix("spec/")
+            found << rel if seen.add?(rel)
+          end
+        else
+          warn "▶ Skipping #{base} (not found)"
+        end
+      end
+
+      found
+    end
+  end
+end

data/lib/rspec_turbo/options.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RSpecTurbo
+  # Splits the raw ARGV into RSpec options and target folders/files, and pulls
+  # out --exclude-pattern values for the file discovery step.
+  #
+  # The tricky part is knowing which flags consume the next token as a value
+  # (so it is not mistaken for a folder); OPTIONS_WITH_VALUES lists those.
+  class Options
+    OPTIONS_WITH_VALUES = Set.new(%w[
+      --exclude-pattern --pattern --format --require --order --seed
+      --tag --failure-exit-code --backtrace-exclusion-pattern
+    ]).freeze
+
+    attr_reader :rspec_options, :folders, :exclude_patterns
+
+    def initialize(argv)
+      @rspec_options, @folders = parse(argv)
+      @exclude_patterns = extract_exclude_patterns(@rspec_options)
+    end
+
+    private
+
+    def parse(argv)
+      options = []
+      folders = []
+      i = 0
+
+      while i < argv.length
+        arg = argv[i]
+
+        unless arg.start_with?("-")
+          folders << arg
+          i += 1
+          next
+        end
+
+        options << arg
+
+        if takes_value?(arg, argv[i + 1])
+          options << argv[i + 1]
+          i += 2
+        else
+          i += 1
+        end
+      end
+
+      [options, folders]
+    end
+
+    def takes_value?(arg, next_arg)
+      !arg.include?("=") &&
+        OPTIONS_WITH_VALUES.include?(arg.split("=").first) &&
+        next_arg && !next_arg.start_with?("-")
+    end
+
+    def extract_exclude_patterns(options)
+      patterns = []
+
+      options.each_with_index do |opt, idx|
+        if opt.start_with?("--exclude-pattern=")
+          patterns << opt.delete_prefix("--exclude-pattern=")
+        elsif opt == "--exclude-pattern"
+          patterns << options[idx + 1] if options[idx + 1]
+        end
+      end
+
+      patterns
+    end
+  end
+end

data/lib/rspec_turbo/progress_reporter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require "rspec/core/formatters/base_formatter"
+
+module RSpecTurbo
+  # RSpec formatter loaded inside each worker process. Its only job is to write
+  # the running example count to RSPEC_TURBO_PROGRESS_FILE after every example,
+  # so the parent runner can sum the slots and draw a live progress bar.
+  #
+  # Deliberately self-contained (no dependency on the rest of the gem) so it can
+  # be required by absolute path inside the spawned `rspec` process. The slowest
+  # files report is produced separately by slow_profile.rb.
+  class ProgressReporter < RSpec::Core::Formatters::BaseFormatter
+    RSpec::Core::Formatters.register self, :example_finished
+
+    def initialize(output)
+      super
+      @count = 0
+      @progress_file = ENV["RSPEC_TURBO_PROGRESS_FILE"]
+    end
+
+    def example_finished(_notification)
+      @count += 1
+      return unless @progress_file
+
+      File.write(@progress_file, @count.to_s)
+    rescue
+      nil
+    end
+  end
+end

data/lib/rspec_turbo/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module RSpecTurbo
+  # Registers the `spec:turbo` Rake task in host Rails apps, so the suite can be
+  # launched via `rake spec:turbo` or `rails spec:turbo` (Rails routes unknown
+  # commands to Rake) in addition to the `rspec-turbo` binary.
+  #
+  # Only loaded when Rails is present (see the guard in lib/rspec_turbo.rb).
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("tasks.rake", __dir__)
+    end
+  end
+end