parallel_specs 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31a954499f658d2d18df5d6126b522cf299985b33f68e5016d8a19de4e1369bd
+  data.tar.gz: 80789703549b936ae3b97309b0979a72d6799f10cd3ab604f11b7f3ed316509c
+SHA512:
+  metadata.gz: f994089098548075cccb2591e4e56dee64aee54fd861b92a30573a62e1358323b1bbf300af645f8aab23e6a5334c0f0b27cd834f61ffc118575f8c3e4737c83f
+  data.tar.gz: b6cf4496f6703d1d11d9375408bf718b7adf5c74327c8a9f12212b2956e17aabbb234f752092dbe44f4a97f5f9510351b32b5733f4f4646d8cd80ca6388bdbcb

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Watermasysk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,54 @@
+# Parallel Specs
+
+![Parallel Specs social preview](assets/github-social-preview-rspecish.png)
+
+A focused extraction of the RSpec pieces from `parallel_tests` with only the parts this gem actually needs:
+
+- a live local dashboard
+- a plain-text CI / LLM friendly summary
+- runtime-log generation for balanced spec splitting
+- modern Ruby only
+
+## Commands
+
+```bash
+bundle exec parallel_specs
+bundle exec parallel_specs -n 6
+bundle exec parallel_specs --test-options='--tag ~type:system'
+bundle exec parallel_specs --record-runtime
+```
+
+Local TTY runs render the interactive dashboard. CI and other non-TTY runs automatically fall back to the plain text summary.
+
+## Runtime balancing
+
+Regular runs automatically use `tmp/parallel_runtime_rspec.log` when it contains enough data.
+
+Generate or refresh that file with:
+
+```bash
+bundle exec parallel_specs --record-runtime
+```
+
+Runtime logs are replaced only after a successful, complete run where every worker produces its runtime log. Failed, interrupted, incomplete, or no-spec runs preserve the previous runtime log.
+
+Or point at a custom file:
+
+```bash
+bundle exec parallel_specs --record-runtime --runtime-log tmp/my_runtime.log
+```
+
+`--runtime-log PATH` is used as the input path for balancing and, with `--record-runtime`, as the output destination for the completed run.
+
+## Environment variables
+
+The supported environment variables are:
+
+- `PARALLEL_SPECS_PROCESSORS` sets the default worker count when `-n` is not provided.
+- `PARALLEL_SPECS_DASHBOARD_MODE` can be `interactive` or `plain` to override automatic dashboard selection.
+- `PARALLEL_SPECS_HEARTBEAT_INTERVAL` sets the plain-dashboard heartbeat interval in seconds.
+- `CI` makes dashboard output default to plain mode.
+
+Worker processes continue to receive `TEST_ENV_NUMBER` for compatibility with existing test-environment isolation setup.
+
+This gem does not intentionally preserve the old `parallel_tests` executable names, formatter paths, or environment variable aliases.

data/bin/parallel_specs

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+root = File.expand_path('..', __dir__)
+$LOAD_PATH.unshift("#{root}/lib") if File.exist?("#{root}/parallel_specs.gemspec")
+
+require 'parallel_specs'
+
+ParallelSpecs::CLI.new.run(ARGV)

data/lib/parallel_specs/cli/dashboard.rb

@@ -0,0 +1,415 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'io/console'
+require 'uri'
+
+module ParallelSpecs
+  class CLI
+    class Dashboard
+      WorkerState = Struct.new(
+        :label,
+        :files_count,
+        :example_total,
+        :passed,
+        :failed,
+        :pending,
+        :current_example,
+        :started_at,
+        :finished_at,
+        :exit_status
+      )
+
+      SPINNER = ['-', '\\', '|', '/'].freeze
+      PROGRESS_BAR_WIDTH = 24
+      REFRESH_INTERVAL = 0.1
+
+      attr_reader :workers
+
+      def plain?
+        @mode == :plain
+      end
+
+      def initialize(groups:, event_files:, output: $stdout, use_colors: true, mode: :interactive, now: -> { ParallelSpecs.now }, width: nil, refresh_interval: REFRESH_INTERVAL)
+        @workers = groups.each_with_index.map do |group, index|
+          WorkerState.new(index + 1, group.size, nil, 0, 0, 0, nil, nil, nil, nil)
+        end
+        @event_files = event_files
+        @output = output
+        @use_colors = use_colors
+        @mode = mode
+        @now = now
+        @width = width
+        @refresh_interval = refresh_interval
+        @mutex = Mutex.new
+        @event_offsets = Hash.new(0)
+        @event_remainders = Hash.new { |hash, key| hash[key] = +"" }
+        @spinner_index = 0
+        @rendered_lines = 0
+        @dirty = true
+      end
+
+      def start
+        @mutex.synchronize do
+          @started_at = @now.call
+          render if interactive?
+        end
+
+        return unless interactive?
+
+        @running = true
+        @refresh_thread = Thread.new do
+          Thread.current.report_on_exception = false if Thread.current.respond_to?(:report_on_exception=)
+
+          begin
+            while @running
+              sleep @refresh_interval
+              @mutex.synchronize do
+                poll_once
+                @spinner_index += 1
+                render if @dirty
+              end
+            end
+          rescue StandardError => e
+            @running = false
+            warn "parallel_specs: dashboard refresh failed while polling #{event_file_context}: #{e.class}: #{e.message}"
+          end
+        end
+      end
+
+      def stop
+        @running = false
+        @refresh_thread&.join
+
+        @mutex.synchronize do
+          begin
+            poll_once
+          rescue StandardError => e
+            warn "parallel_specs: dashboard final poll failed while polling #{event_file_context}: #{e.class}: #{e.message}"
+          end
+          render
+          @output.puts if interactive?
+          @output.flush if @output.respond_to?(:flush)
+        end
+      end
+
+      def worker_started(process_number)
+        synchronize do
+          worker = @workers.fetch(process_number)
+          worker.started_at ||= @now.call
+          @dirty = true
+        end
+      end
+
+      def worker_finished(process_number, exit_status:)
+        synchronize do
+          worker = @workers.fetch(process_number)
+          worker.started_at ||= @now.call
+          worker.finished_at = @now.call
+          worker.exit_status = exit_status
+          @dirty = true
+        end
+      end
+
+      def process_event(process_number, event)
+        worker = @workers.fetch(process_number)
+        worker.started_at ||= @now.call
+
+        case event.fetch('event')
+        when 'start'
+          worker.example_total = event['total']
+        when 'example_started'
+          worker.current_example = event['example']
+        when 'example_passed'
+          worker.passed += 1
+          worker.current_example = event['example']
+        when 'example_pending'
+          worker.pending += 1
+          worker.current_example = event['example']
+        when 'example_failed'
+          worker.failed += 1
+          worker.current_example = event['example']
+        end
+
+        @dirty = true
+      end
+
+      def poll_once
+        @event_files.each do |process_number, path|
+          next unless File.exist?(path)
+
+          File.open(path, 'r') do |file|
+            file.seek(@event_offsets[process_number])
+            chunk = file.read.to_s
+            @event_offsets[process_number] = file.pos
+            next if chunk.empty?
+
+            buffer = @event_remainders[process_number] << chunk
+            lines = buffer.split("\n", -1)
+            @event_remainders[process_number] = lines.pop.to_s
+
+            lines.each do |line|
+              next if line.empty?
+
+              process_event(process_number, JSON.parse(line))
+            end
+          end
+        end
+      end
+
+      def frame
+        lines = if interactive?
+          [header_line, *workers.map { |worker| worker_line(worker) }]
+        else
+          [plain_header_line, *workers.map { |worker| plain_worker_line(worker) }]
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      def synchronize(&block)
+        @mutex.synchronize(&block)
+      end
+
+      def event_file_context
+        @event_files.map { |process_number, path| "worker #{process_number + 1}=#{path}" }.join(', ')
+      end
+
+      def render
+        if interactive?
+          render_interactive
+        else
+          render_plain
+        end
+        @dirty = false
+      end
+
+      def render_interactive
+        output = frame
+        if @rendered_lines > 0
+          @output.print("\e[#{@rendered_lines}A")
+          @output.print("\r\e[J")
+        end
+        @output.print(output)
+        @output.flush if @output.respond_to?(:flush)
+        @rendered_lines = output.lines.count
+      end
+
+      def render_plain
+        @output.print(frame)
+        @output.flush if @output.respond_to?(:flush)
+      end
+
+      def header_line
+        running = workers.count { |worker| status_for(worker) == :running }
+        passed = workers.count { |worker| status_for(worker) == :passed }
+        failed = workers.count { |worker| [:failing, :failed].include?(status_for(worker)) }
+        examples_seen = workers.sum { |worker| examples_seen_for(worker) }
+        total_examples = workers.filter_map(&:example_total)
+        example_summary = if total_examples.empty?
+          "examples: #{examples_seen}"
+        else
+          summary = "examples: #{examples_seen}/#{total_examples.sum}"
+          summary += ' known' unless total_examples.size == workers.size
+          summary
+        end
+
+        truncate(
+          [
+            'Parallel RSpec dashboard',
+            "workers: #{workers.size}",
+            "running: #{running}",
+            "passed: #{passed}",
+            "failed: #{failed}",
+            example_summary,
+            "elapsed: #{format_duration(elapsed_seconds)}"
+          ].join(' | '),
+          terminal_width
+        )
+      end
+
+      def worker_line(worker)
+        plain_status = status_text_for(worker)
+        colored_status = colorize(plain_status.ljust(9), status_color_for(worker))
+        line = format(
+          "[%<label>2d] %<status>s %<bar>s %<summary>9s p:%<passed>3d f:%<failed>3d pend:%<pending>3d",
+          label: worker.label,
+          status: colored_status,
+          bar: progress_bar_for(worker),
+          summary: progress_summary_for(worker),
+          passed: worker.passed,
+          failed: worker.failed,
+          pending: worker.pending
+        )
+        line += " | #{worker.current_example}" if worker.current_example
+        truncate(line, terminal_width)
+      end
+
+      def plain_header_line
+        running = workers.count { |worker| status_for(worker) == :running }
+        passed = workers.count { |worker| status_for(worker) == :passed }
+        failed = workers.count { |worker| [:failing, :failed].include?(status_for(worker)) }
+        examples_seen = workers.sum { |worker| examples_seen_for(worker) }
+        total_examples = workers.filter_map(&:example_total)
+
+        parts = [
+          'dashboard',
+          "workers=#{workers.size}",
+          "running=#{running}",
+          "passed=#{passed}",
+          "failed=#{failed}",
+          "examples_seen=#{examples_seen}",
+          "elapsed=#{format_duration(elapsed_seconds)}"
+        ]
+
+        unless total_examples.empty?
+          parts << "examples_total=#{total_examples.sum}"
+          parts << "examples_known=#{total_examples.size == workers.size}"
+        end
+
+        parts.join(' ')
+      end
+
+      def plain_worker_line(worker)
+        parts = [
+          "worker=#{worker.label}",
+          "status=#{plain_status_text_for(worker)}",
+          "passed=#{worker.passed}",
+          "failed=#{worker.failed}",
+          "pending=#{worker.pending}",
+          "current_example=#{encode_plain_value(worker.current_example.to_s)}"
+        ]
+
+        if worker.example_total
+          parts << "completed=#{examples_seen_for(worker)}"
+          parts << "total=#{worker.example_total}"
+        else
+          parts << "files=#{worker.files_count}"
+        end
+
+        parts.join(' ')
+      end
+
+      def progress_summary_for(worker)
+        if worker.example_total
+          format('%<completed>d/%<total>d', completed: examples_seen_for(worker), total: worker.example_total)
+        else
+          format('files:%<count>3d', count: worker.files_count)
+        end
+      end
+
+      def progress_bar_for(worker)
+        return "[#{'.' * PROGRESS_BAR_WIDTH}]" unless worker.example_total
+
+        total = worker.example_total
+        completed = [examples_seen_for(worker), total].min
+        filled = if total == 0
+          PROGRESS_BAR_WIDTH
+        else
+          [(completed.to_f / total * PROGRESS_BAR_WIDTH).round, PROGRESS_BAR_WIDTH].min
+        end
+        empty = PROGRESS_BAR_WIDTH - filled
+        "[#{'#' * filled}#{'-' * empty}]"
+      end
+
+      def examples_seen_for(worker)
+        worker.passed + worker.failed + worker.pending
+      end
+
+      def status_for(worker)
+        if worker.finished_at
+          if worker.failed > 0 || worker.exit_status.to_i != 0
+            :failed
+          else
+            :passed
+          end
+        elsif worker.failed > 0
+          :failing
+        elsif worker.started_at
+          :running
+        else
+          :queued
+        end
+      end
+
+      def status_text_for(worker)
+        case status_for(worker)
+        when :queued then '· queued'
+        when :running then "#{SPINNER[@spinner_index % SPINNER.length]} running"
+        when :failing then '! failing'
+        when :failed then '✗ failed'
+        when :passed then '✓ passed'
+        end
+      end
+
+      def plain_status_text_for(worker)
+        case status_for(worker)
+        when :queued then 'queued'
+        when :running then 'running'
+        when :failing then 'failing'
+        when :failed then 'failed'
+        when :passed then 'passed'
+        end
+      end
+
+      def status_color_for(worker)
+        case status_for(worker)
+        when :queued then 90
+        when :running then 33
+        when :failing, :failed then 31
+        when :passed then 32
+        end
+      end
+
+      def encode_plain_value(value)
+        URI.encode_www_form_component(value)
+      end
+
+      def colorize(text, color)
+        return text unless @use_colors
+
+        "\e[#{color}m#{text}\e[0m"
+      end
+
+      def interactive?
+        @mode == :interactive
+      end
+
+      def elapsed_seconds
+        return 0 unless @started_at
+
+        (@now.call - @started_at).to_i
+      end
+
+      def format_duration(seconds)
+        hours = seconds / 3600
+        minutes = (seconds % 3600) / 60
+        remaining_seconds = seconds % 60
+
+        if hours > 0
+          format('%<hours>d:%<minutes>02d:%<seconds>02d', hours: hours, minutes: minutes, seconds: remaining_seconds)
+        else
+          format('%<minutes>02d:%<seconds>02d', minutes: minutes, seconds: remaining_seconds)
+        end
+      end
+
+      def terminal_width
+        @terminal_width ||= @width || begin
+          console = IO.console
+          console&.winsize&.last || 120
+        rescue StandardError
+          120
+        end
+      end
+
+      def truncate(text, max_length)
+        return '' if max_length <= 0
+        return text if text.length <= max_length
+        return text[0, max_length] if max_length <= 1
+
+        "#{text[0, max_length - 1]}…"
+      end
+    end
+  end
+end