runtime_groups 0.1.0

data/lib/runtime_groups/grouping.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module RuntimeGroups
+  # Raised when runtime grouping cannot proceed because the runtime log does
+  # not cover enough of the given files (the `allowed_missing` budget).
+  class RuntimeLogTooSmallError < Error; end
+
+  # Balanced grouping of test files into worker groups.
+  #
+  # Mirrors the semantics of `parallel_tests` 3.5.2 through 5.8.0 (identical
+  # across those versions for this surface): weights come from a {RuntimeLog}
+  # when present, files missing from the log get the average of the known
+  # runtimes (or 1.0 when nothing is known) once the `allowed_missing` budget
+  # permits, and groups are balanced largest-smallest — every file, in
+  # descending weight order, goes to the group with the smallest accumulated
+  # weight. Tie-breaking by filename makes the split deterministic
+  # (`parallel_tests` tie order is unspecified).
+  module Grouping
+    module_function
+
+    # Compute a weight for every file.
+    #
+    # @param files [Array<String>] test file paths
+    # @param group_by [:runtime, :filesize, :found]
+    # @param runtime_log [String, nil] runtime log path (for :runtime)
+    # @param allowed_missing [Float] fraction of files allowed to be missing
+    #   from the runtime log before {RuntimeLogTooSmallError} is raised
+    # @return [Hash{String => Float}] file => weight
+    # @raise [RuntimeGroups::RuntimeLogTooSmallError] when too many files are
+    #   missing from the runtime log
+    def with_size(files, group_by: :runtime, runtime_log: nil, allowed_missing: 1.0)
+      case group_by
+      when :found
+        files.each_with_object({}) { |file, memo| memo[file] = 1.0 }
+      when :filesize
+        files.each_with_object({}) { |file, memo| memo[file] = File.stat(file).size.to_f }
+      when :runtime
+        runtime_weights(files, runtime_log, allowed_missing)
+      else
+        raise Error, "invalid group-by mode #{group_by.inspect}; expected one of: runtime, filesize, found"
+      end
+    end
+
+    # Split files into balanced groups.
+    #
+    # @param files [Array<String>] test file paths
+    # @param num_groups [Integer] positive group count; groups may be empty
+    #   when there are fewer files than groups
+    # @param group_by [:runtime, :filesize, :found] weighting mode
+    # @param runtime_log [String, nil] runtime log path (for :runtime)
+    # @param allowed_missing [Float] fraction of files allowed to be missing
+    #   from the runtime log
+    # @return [Array<Array<String>>] exactly `num_groups` arrays of file paths
+    # @raise [RuntimeGroups::Error] when num_groups or group_by is invalid
+    def in_groups(files, num_groups, group_by: :runtime, runtime_log: nil, allowed_missing: 1.0)
+      groups = Array.new(RuntimeGroups.parse_count!(num_groups)) { { weight: 0.0, files: [] } }
+      weights = with_size(files, group_by: group_by, runtime_log: runtime_log, allowed_missing: allowed_missing)
+
+      files.sort_by { |file| [-weights[file], file] }.each do |file|
+        target = groups.min_by { |group| group[:weight] }
+        target[:weight] += weights[file]
+        target[:files] << file
+      end
+
+      groups.map { |group| group[:files] }
+    end
+
+    # Runtime weights with the missing-file budget and average-fill semantics
+    # retained from `parallel_tests`.
+    #
+    # @return [Hash{String => Float}]
+    def runtime_weights(files, runtime_log, allowed_missing)
+      budget = files.size * allowed_missing
+      runtimes = RuntimeLog.read(runtime_log)
+      known, unknown = [], []
+
+      files.each do |file|
+        if runtimes.key?(file)
+          known << [file, runtimes[file]]
+        else
+          budget -= 1
+          if budget.negative?
+            raise RuntimeLogTooSmallError,
+              "Runtime log file '#{runtime_log}' does not contain sufficient data to sort #{files.size} test files, please update or remove it."
+          end
+          unknown << file
+        end
+      end
+
+      weights = known.each_with_object({}) { |(file, seconds), memo| memo[file] = seconds }
+      fill = known.empty? ? 1.0 : known.map(&:last).sum / known.size
+      unknown.each { |file| weights[file] = fill }
+      weights
+    end
+  end
+end

data/lib/runtime_groups/options.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RuntimeGroups
+  # Options-file discovery for RSpec option passthrough, mirroring
+  # `ParallelTests::RSpec::Runner.spec_opts` (identical in parallel_tests
+  # 3.5.2 through 5.8.0). Exposed here as public API so runners no longer
+  # need to reach into parallel_tests internals.
+  module Options
+    # Options files checked, in priority order.
+    SPEC_OPTS_FILES = [".rspec_parallel", "spec/parallel_spec.opts", "spec/spec.opts"].freeze
+
+    module_function
+
+    # First existing options file, in priority order.
+    #
+    # @param files [Array<String>] candidate paths (defaults to
+    #   {SPEC_OPTS_FILES})
+    # @return [String, nil]
+    def options_file(files = SPEC_OPTS_FILES)
+      files.detect { |file| File.file?(file) }
+    end
+
+    # RSpec argument string selecting the options file.
+    #
+    # @param files [Array<String>] candidate paths (defaults to
+    #   {SPEC_OPTS_FILES})
+    # @return [String, nil] e.g. "-O .rspec_parallel", or nil when no
+    #   options file exists
+    def spec_opts(files = SPEC_OPTS_FILES)
+      found = options_file(files)
+      "-O #{found}" if found
+    end
+  end
+end

data/lib/runtime_groups/pids.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RuntimeGroups
+  # A file-backed ledger of live worker pids.
+  #
+  # Unlike the pid bookkeeping in `parallel_tests` (whose `Pids` instances do
+  # not read before writing, so every fresh instance overwrites the file with
+  # an empty in-memory list), every mutation here re-reads the file first and
+  # writes the merged set. The file can therefore be shared safely between
+  # the parent process and any number of tracking call sites.
+  class Pids
+    attr_reader :path
+
+    # @param path [String] file path backing the ledger
+    def initialize(path)
+      @path = path
+    end
+
+    # @return [Array<Integer>] the pids currently recorded, deduplicated and
+    #   sorted ascending; empty when the file does not exist yet
+    def to_a
+      return [] unless File.file?(@path)
+
+      File.readlines(@path).map do |line|
+        begin
+          Integer(line.strip, 10)
+        rescue ArgumentError
+          nil
+        end
+      end.compact.uniq.sort
+    end
+
+    # Record a pid. Idempotent.
+    #
+    # @param pid [Integer]
+    # @return [Array<Integer>] the recorded pids after the add
+    def add(pid)
+      current = to_a
+      return current if current.include?(pid)
+
+      write(current + [pid])
+    end
+
+    # Remove a pid. Missing pids are ignored.
+    #
+    # @param pid [Integer]
+    # @return [Array<Integer>] the recorded pids after the delete
+    def delete(pid)
+      write(to_a - [pid])
+    end
+
+    # Remove every recorded pid.
+    #
+    # @return [Array<Integer>] always empty
+    def clear
+      write([])
+    end
+
+    private
+
+    def write(pids)
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.open(@path, "w") do |f|
+        pids.uniq.sort.each { |pid| f.puts(pid) }
+      end
+      pids
+    end
+  end
+
+  # Scoped management of a pid ledger file for the duration of a parallel
+  # fan-out.
+  module PidFile
+    module_function
+
+    # Default ledger path, unique per process.
+    #
+    # @param dir [String, nil] directory for the file (default: Dir.tmpdir)
+    # @return [String]
+    def path(dir: nil)
+      require "tmpdir"
+      File.join(dir || Dir.tmpdir, "runtime_groups_pids_#{Process.pid}")
+    end
+
+    # Create (or truncate) a pid ledger file, yield its path for worker
+    # spawning, then always remove the file.
+    #
+    # @param dir [String, nil] directory for the file (default: Dir.tmpdir)
+    # @yieldparam path [String] the ledger path to hand to {Pids}
+    # @return [Object] the block's return value
+    def with(dir: nil)
+      path = path(dir: dir)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, "")
+      yield path
+    ensure
+      File.delete(path) if File.exist?(path)
+    end
+  end
+end

data/lib/runtime_groups/runtime_log.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RuntimeGroups
+  # Reader and writer for a runtime log: `path:seconds` per line, recording
+  # how long each test file took in a previous run. The log is what makes
+  # {Grouping} balance groups by measured runtime instead of file size.
+  #
+  # The writer merges with the minimum: a recorded runtime only gets slower
+  # in the log when a subsequent run of that file is actually slower, so one
+  # slow run (GC pause, cold cache) does not permanently poison the balance.
+  class RuntimeLog
+    # Read a runtime log.
+    #
+    # @param path [String, nil] log file path; nil or a missing file reads as
+    #   an empty hash
+    # @return [Hash{String => Float}] file path => recorded seconds
+    def self.read(path)
+      return {} if path.nil? || !File.file?(path)
+
+      File.readlines(path).each_with_object({}) do |line, memo|
+        file, seconds = line.strip.split(":", 2)
+        next if file.nil? || file.empty? || seconds.nil? || seconds.empty?
+
+        begin
+          memo[file] = Float(seconds)
+        rescue ArgumentError
+          next
+        end
+      end
+    end
+
+    # @param path [String] log file path
+    def initialize(path)
+      @path = path
+    end
+
+    # Record a runtime for a file, merged as the minimum of the recorded and
+    # given values. Creates the file (and its parent directory) on first use.
+    #
+    # @param file [String] test file path (the key later read back)
+    # @param seconds [Numeric]
+    # @return [Float] the recorded value after the merge
+    def log(file, seconds)
+      current = self.class.read(@path)
+      merged = current.key?(file) ? [current[file], seconds.to_f].min : seconds.to_f
+      current[file] = merged
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.open(@path, "w") do |f|
+        current.keys.sort.each { |key| f.puts("#{key}:#{current[key]}") }
+      end
+      merged
+    end
+  end
+end

data/lib/runtime_groups/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RuntimeGroups
+  # Version namespace for this gem.
+  module Version
+    # Current gem version.
+    VERSION = "0.1.0"
+  end
+  # Current gem version exposed at the traditional constant location.
+  VERSION = Version::VERSION # Traditional Constant Location
+end

data/lib/runtime_groups.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "etc"
+require_relative "runtime_groups/version"
+
+module RuntimeGroups
+  class Error < StandardError; end
+
+  # Environment variable checked for a default worker process count, kept
+  # identical to the `parallel_tests` convention so an existing CI
+  # configuration keeps working when a runner switches to this gem.
+  DEFAULT_PROC_COUNT_ENV = "PARALLEL_TEST_PROCESSORS"
+
+  module_function
+
+  # Resolve the worker process count for a parallel run.
+  #
+  # Resolution order:
+  # 1. An explicit `count` argument (must be a positive Integer, or a String
+  #    parseable as one).
+  # 2. `ENV[env_key]` (defaults to "PARALLEL_TEST_PROCESSORS"); blank values
+  #    are ignored.
+  # 3. `Etc.nprocessors` — the machine's core count. Works on every engine
+  #    (MRI, JRuby, TruffleRuby): JRuby reports the JVM's available
+  #    processors.
+  #
+  # The caller is responsible for resource budgeting: on JVM engines each
+  # worker is a full JVM whose default heap can be 1/4 of machine RAM, so
+  # the core-count default can exhaust a constrained runner. Cap it
+  # explicitly there (see turbo_tests2's resource-constrained CI docs).
+  #
+  # @param count [Integer, String, nil]
+  # @param env [Hash] environment mapping (defaults to ENV)
+  # @param env_key [String]
+  # @return [Integer] positive worker count
+  # @raise [RuntimeGroups::Error] when an explicit count or env value is not
+  #   a positive integer
+  def process_count(count = nil, env: ENV, env_key: DEFAULT_PROC_COUNT_ENV)
+    return parse_count!(count) unless count.nil?
+
+    from_env = env[env_key]
+    return parse_count!(from_env) unless from_env.nil? || from_env.strip.empty?
+
+    Etc.nprocessors
+  end
+
+  # Parse and validate a worker count value.
+  #
+  # @param value [Integer, String]
+  # @return [Integer] positive worker count
+  # @raise [RuntimeGroups::Error] when the value is not a positive integer
+  def parse_count!(value)
+    count = value.is_a?(Integer) ? value : Integer(value, 10)
+    return count if count.positive?
+
+    raise Error, "invalid worker count #{value.inspect}; expected a positive integer"
+  rescue ArgumentError
+    raise Error, "invalid worker count #{value.inspect}; expected a positive integer"
+  end
+end
+
+require_relative "runtime_groups/pids"
+require_relative "runtime_groups/runtime_log"
+require_relative "runtime_groups/options"
+require_relative "runtime_groups/grouping"
+
+RuntimeGroups::Version.class_eval do
+  extend VersionGem::Basic
+end

data/sig/runtime_groups.rbs

@@ -0,0 +1,6 @@
+module RuntimeGroups
+  module Version
+    VERSION: String
+  end
+  VERSION: String
+end

data.tar.gz.sig

@@ -0,0 +1,2 @@
+��Ҧ�r�������dGƝ��'���-�ϰE��Ҍ�p�����~�9��A�b?�#�n��=�f�����	0n��K�%�S�u��1����1i�^��28�����Tܸ��d�W:<w���;e�f�V�]�+GQ�K
+��(
�?���]�J����Z��`�w���|�TV��JQ°����ʬ,���qIo3�-@��g�����gV�d����^��ᰞ\�r$�܅‡�#�.�J�.�	�/1�������+�|>�$zò@�m/�|�TI6��%=o�����0�<Ɵ�_�N�1��8�i�Q�G�ZK�Q�K�*����W��y��