binpacker 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98842f3601fe059ff372b62a214ee73e5e96d0b2c01cf5b651063f04e3f00184
-  data.tar.gz: 94e73ac26474bf1da1942509f35618e8576d230b685ee69fe09579d4b9387898
+  metadata.gz: ae35133b41b6a8423c8caa45b91a4153498099d2f04c790aeada3fb1e4e0d52a
+  data.tar.gz: 5e537cf525779a2783db551b1bf86f7525ce34558f16ce8c2eab253712454b8e
 SHA512:
-  metadata.gz: 6a983e121b41c7a9e62dad700ee5541813b84c2553e7fc479c3dbedf996358669a9508d2fd7f3eb8df21831c583421ee91382a453ac73a60beead9bf03da0675
-  data.tar.gz: 657ac41276da7094a5ea54d53936a9237b1b3139f53b741c954427b57f2d781dca56df91746972e33e93f49edb7a93a2155d5b92561653d672f87ca73373669a
+  metadata.gz: ab3dd9a1c6993908e7e646c697d649745d029f15c6a77981ec8b2dd3735afebf92f6194a97e60e2923acc5500fa475e2f7118673cc6c18e2c49ba0a4aa7a7dc1
+  data.tar.gz: ad30734e5dbadb596dd753f90ff1163bbc0a12fa60f8d080baad357f9ed2be3ac8a9667d2ed8a52dab2ced6e3e76d2931a1368613976f0a4e2a5af3fd1c4a8da

data/lib/binpacker/cli.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "optparse"
+require 'optparse'
 
 module Binpacker
   class CLI
@@ -21,27 +21,32 @@ module Binpacker
       @skill_path = false
       @skill_describe = false
       @skill_name = nil
+      # A CI matrix sets env vars far more easily than it rewrites the command a Makefile target runs, so
+      # BINPACKER_SHARD is a first-class way in; an explicit --shard still wins over it.
+      @shard_spec = ENV.fetch('BINPACKER_SHARD', nil)
       parse!
     end
 
     def run
       case @command
-      when "calibrate"
+      when 'calibrate'
         cmd_calibrate
-      when "run"
+      when 'run'
         cmd_run
-      when "init"
+      when 'shards-check'
+        cmd_shards_check
+      when 'init'
         cmd_init
-      when "skill"
+      when 'skill'
         cmd_skill
-      when "describe"
+      when 'describe'
         cmd_describe
-      when "--version", "-v"
+      when '--version', '-v'
         puts "binpacker #{Binpacker::VERSION}"
-      when "--help", "-h", nil
+      when '--help', '-h', nil
         print_help
       else
-        $stderr.puts "unknown command: #{@command}"
+        warn "unknown command: #{@command}"
         print_help
         exit 1
       end
@@ -51,47 +56,51 @@ module Binpacker
 
     def parse!
       parser = OptionParser.new do |opts|
-        opts.banner = "Usage: binpacker <command> [options]"
+        opts.banner = 'Usage: binpacker <command> [options]'
 
-        opts.on("--profile PROFILE", "Profile name from binpacker.yml") do |v|
+        opts.on('--profile PROFILE', 'Profile name from binpacker.yml') do |v|
           @profile = v
         end
 
-        opts.on("--version", "Show version") do
-          @command ||= "--version"
+        opts.on('--version', 'Show version') do
+          @command ||= '--version'
         end
 
-        opts.on("--help", "Show help") do
-          @command ||= "--help"
+        opts.on('--help', 'Show help') do
+          @command ||= '--help'
         end
 
-        opts.on("--quiet", "Suppress worker output") do
+        opts.on('--quiet', 'Suppress worker output') do
           @quiet = true
         end
 
-        opts.on("--incremental", "Calibrate only tests without timing data") do
+        opts.on('--incremental', 'Calibrate only tests without timing data') do
           @incremental = true
         end
 
-        opts.on("--report PATH", "(run) Write a JSON run report to PATH") do |v|
+        opts.on('--report PATH', '(run) Write a JSON run report to PATH') do |v|
           @report_path = v
         end
 
-        opts.on("--list", "(skill) List bundled skills") do
+        opts.on('--shard K/N', '(run) Run only shard K of N (1-based)') do |v|
+          @shard_spec = v
+        end
+
+        opts.on('--list', '(skill) List bundled skills') do
           @skill_list = true
         end
 
-        opts.on("--path", "(skill) Print the SKILL.md path for <name>") do
+        opts.on('--path', '(skill) Print the SKILL.md path for <name>') do
           @skill_path = true
         end
 
-        opts.on("--describe", "(skill) Report project state and next skill") do
+        opts.on('--describe', '(skill) Report project state and next skill') do
           @skill_describe = true
         end
       end
 
       # Extract passthrough arguments after "--"
-      if (split_idx = @args.index("--"))
+      if (split_idx = @args.index('--'))
         @passthrough = @args[(split_idx + 1)..] || []
         @args = @args[0...split_idx]
       end
@@ -100,11 +109,14 @@ module Binpacker
       # A positional command wins; otherwise keep any command an option set
       # (e.g. --version), so `binpacker --version` isn't clobbered to nil.
       @command = remaining.shift || @command
-      @skill_name = remaining.shift
+      @skill_name = remaining.first
+      # `shards-check` takes a list of run-report paths, so the positionals stay available in full rather
+      # than being consumed into the single-name slot `skill` uses.
+      @shard_reports = remaining
     end
 
     def cmd_init
-      config_path = Pathname.pwd.join("binpacker.yml")
+      config_path = Pathname.pwd.join('binpacker.yml')
       if config_path.exist?
         puts "binpacker.yml already exists at #{config_path}"
         exit 1
@@ -112,11 +124,11 @@ module Binpacker
 
       framework = detect_framework
       unless ProjectState::SUPPORTED_FRAMEWORKS.include?(framework)
-        $stderr.puts "Detected #{framework} — binpacker supports rspec and minitest only."
-        $stderr.puts "No binpacker.yml was created."
+        warn "Detected #{framework} — binpacker supports rspec and minitest only."
+        warn 'No binpacker.yml was created.'
         exit 1
       end
-      pattern = framework == "minitest" ? "test/**/*_test.rb" : "spec/**/*_spec.rb"
+      pattern = framework == 'minitest' ? 'test/**/*_test.rb' : 'spec/**/*_spec.rb'
       runner = framework
 
       yaml = <<~YAML
@@ -137,15 +149,15 @@ module Binpacker
       config_path.write(yaml)
       puts "Created #{config_path}"
       puts "Detected test framework: #{framework}"
-      puts ""
-      puts "Next steps:"
-      puts "  1. binpacker calibrate   (seed timing data)"
-      puts "  2. binpacker run          (run in parallel)"
+      puts ''
+      puts 'Next steps:'
+      puts '  1. binpacker calibrate   (seed timing data)'
+      puts '  2. binpacker run          (run in parallel)'
     end
 
     def cmd_calibrate
       config = Config.new(profile: @profile)
-      discovery_klass = config.test_runner == "rspec" ? RSpecDiscovery : MinitestDiscovery
+      discovery_klass = config.test_runner == 'rspec' ? RSpecDiscovery : MinitestDiscovery
       tests = discovery_klass.new(config).enumerate
 
       cal = Calibration.new(config)
@@ -175,7 +187,7 @@ module Binpacker
         if path
           puts path
         else
-          $stderr.puts "unknown skill: #{@skill_name}"
+          warn "unknown skill: #{@skill_name}"
           exit 1
         end
       elsif @skill_name && !@skill_list
@@ -187,12 +199,12 @@ module Binpacker
 
     def cmd_describe
       state = ProjectState.new
-      puts "binpacker project state:"
+      puts 'binpacker project state:'
       puts "  config (binpacker.yml): #{state.config_present? ? 'present' : 'missing'}"
       puts "  timing data:            #{state.timing_present? ? 'present' : 'missing'}"
       puts "  test framework:         #{state.framework || 'not detected'}"
       puts "  CI wired for binpacker: #{state.ci_wired? ? 'yes' : 'no'}"
-      puts ""
+      puts ''
 
       unless state.supported_framework?
         puts "binpacker supports rspec and minitest; #{state.framework} is not supported yet."
@@ -208,45 +220,52 @@ module Binpacker
     def list_skills
       skills = Skills.list
       if skills.empty?
-        puts "No bundled skills found."
+        puts 'No bundled skills found.'
         return
       end
-      puts "Bundled skills:"
+      puts 'Bundled skills:'
       skills.each { |s| puts "  #{s[:name]}" }
-      puts ""
+      puts ''
       puts "Print a skill's instructions with `binpacker skill <name>`."
     end
 
     def print_skill(name)
       unless Skills.exist?(name)
-        $stderr.puts "unknown skill: #{name}"
-        $stderr.puts "Run `binpacker skill` to list bundled skills."
+        warn "unknown skill: #{name}"
+        warn 'Run `binpacker skill` to list bundled skills.'
         exit 1
       end
 
       puts "# Skill: #{name}"
       puts "# Source: #{Skills.path(name)}"
-      puts ""
+      puts ''
       puts Skills.body(name)
     end
 
     def cmd_run
       config = Config.new(profile: @profile)
       report_path = @report_path || config.report_file
+      shard = Shard.parse(@shard_spec)
       orchestrator = Orchestrator.new(
-        config, passthrough: @passthrough, quiet: @quiet, report_path: report_path
+        config, passthrough: @passthrough, quiet: @quiet, report_path: report_path, shard: shard
       )
 
-      puts "binpacker starting (#{config.worker_count} workers, profile: #{config.profile})"
+      start_line = "binpacker starting (#{config.worker_count} workers, profile: #{config.profile}"
+      start_line += ", shard: #{shard}" if shard
+      puts "#{start_line})"
       result = orchestrator.run
       puts "Run report written to #{report_path}" if report_path
       unit = test_unit_label(config)
+      # Named in the summary because a sharded run's totals are its slice's, not the suite's — a reader
+      # comparing "10203 examples" with "3401 examples" needs to see which of the two this was.
+      scope = shard ? " (shard #{shard})" : ''
 
       if result[:passed]
-        puts "All #{result[:total]} #{pluralize(result[:total], unit)} passed across #{config.worker_count} workers."
+        puts "All #{result[:total]} #{pluralize(result[:total], unit)} passed across " \
+             "#{config.worker_count} workers#{scope}."
         exit 0
       elsif result[:empty_filter]
-        puts "No tests matched the Minitest filter."
+        puts 'No tests matched the Minitest filter.'
         exit 1
       else
         failed = result[:total] - result[:passed_count]
@@ -255,8 +274,23 @@ module Binpacker
       end
     end
 
+    # Run after a sharded matrix, over every shard's `--report`. A shard cannot tell "not mine" from "does
+    # not exist", so this is the only place a partition that dropped tests can be caught.
+    def cmd_shards_check
+      result = ShardCheck.call(@shard_reports)
+
+      if result.ok?
+        puts result.summary
+        exit 0
+      end
+
+      warn result.summary
+      result.problems.each { |problem| warn "  #{problem}" }
+      exit 1
+    end
+
     def test_unit_label(config)
-      config.test_runner == "rspec" ? "example" : "test"
+      config.test_runner == 'rspec' ? 'example' : 'test'
     end
 
     def pluralize(count, word)
@@ -269,6 +303,7 @@ module Binpacker
 
         Commands:
           run          Execute tests across worker processes
+          shards-check Verify a sharded matrix's run reports cover the whole suite
           calibrate    Run tests serially to generate timing data
           init         Create binpacker.yml with auto-detected settings
           describe     Report project state and recommend the next skill
@@ -278,6 +313,7 @@ module Binpacker
           --profile NAME   Select profile from binpacker.yml
           --incremental    (calibrate) Measure only tests without timing data
           --report PATH    (run) Write a JSON run report to PATH
+          --shard K/N      (run) Run only shard K of N (1-based; env: BINPACKER_SHARD)
           --list           (skill) List bundled skills
           --path           (skill) Print the SKILL.md path for <name>
           --describe       (skill) Report project state and next skill
@@ -287,6 +323,8 @@ module Binpacker
           binpacker init
           binpacker run --profile ci
           binpacker run -- --tag ~slow
+          binpacker run --shard 2/3 --report shard-2.json
+          binpacker shards-check shard-*.json
           binpacker calibrate --incremental
           binpacker describe
           binpacker skill binpacker-setup
@@ -294,7 +332,7 @@ module Binpacker
     end
 
     def detect_framework
-      ProjectState.new.framework || "rspec"
+      ProjectState.new.framework || 'rspec'
     end
   end
 end

data/lib/binpacker/orchestrator.rb

@@ -24,20 +24,27 @@ module Binpacker
     # worker that gave the best makespan in the PR #12 simulation.
     COLD_START_BATCHES_PER_WORKER = 5
 
-    def initialize(config, passthrough: [], quiet: false, report_path: nil)
+    def initialize(config, passthrough: [], quiet: false, report_path: nil, shard: nil)
       @config = config
       @passthrough = passthrough
       @quiet = quiet
       @report_path = report_path
+      @shard = shard
     end
 
     def run
       tests = discover
       timing = Timing.new(@config.timing_file)
+      # Weights are computed over the WHOLE suite before slicing, so every shard cuts against the same
+      # numbers and the partition they agree on covers every test exactly once.
       timings = timing.load_with_fallback(tests)
       @timings = timings
 
       scheduler = Scheduler.for(@config.scheduler['algorithm'])
+      @discovered_count = tests.size
+      tests = @shard.select(tests: tests, timings: timings, scheduler: scheduler) if @shard
+      @selected_count = tests.size
+
       queues = scheduler.partition(
         tests: tests,
         worker_count: @config.worker_count,
@@ -244,7 +251,10 @@ module Binpacker
         predicted_loads: @predicted_loads,
         worker_stats: worker_stats,
         all_timings: all_timings,
-        timings: @timings
+        timings: @timings,
+        shard: @shard,
+        discovered: @discovered_count,
+        selected: @selected_count
       ).write(@report_path)
     end
 

data/lib/binpacker/report.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "json"
+require 'json'
 
 module Binpacker
   # Builds the machine-readable Run report: predicted versus actual per-Worker
@@ -9,13 +9,17 @@ module Binpacker
     SCHEMA = 1
     DRIFT_LIMIT = 10
 
-    def initialize(profile:, algorithm:, predicted_loads:, worker_stats:, all_timings:, timings:)
+    def initialize(profile:, algorithm:, predicted_loads:, worker_stats:, all_timings:, timings:,
+                   shard: nil, discovered: nil, selected: nil)
       @profile = profile
       @algorithm = algorithm
       @predicted_loads = predicted_loads
       @worker_stats = worker_stats
       @all_timings = all_timings
       @timings = timings
+      @shard = shard
+      @discovered = discovered
+      @selected = selected
     end
 
     def to_h
@@ -26,6 +30,7 @@ module Binpacker
         schema: SCHEMA,
         profile: @profile,
         algorithm: @algorithm,
+        shard: shard_section,
         worker_count: @worker_stats.size,
         predicted_makespan: round(predicted.max || 0.0),
         actual_makespan: round(actual.max || 0.0),
@@ -44,6 +49,29 @@ module Binpacker
 
     private
 
+    # The audit trail for a sharded run, and the reason `discovered` is recorded at all.
+    #
+    # Shards never talk to each other: each computes the same N-way partition and trusts the others to have
+    # computed it identically. They do so only while they agree on the timing data the partition is cut
+    # from, which in CI means every shard restoring the same timing cache. A shard that restores a
+    # different one — a cache miss where its siblings hit — partitions differently, and the failure is
+    # silent: tests land in no shard at all and the build stays green.
+    #
+    # `discovered` is the whole-suite count before slicing, so it agrees across shards that see the same
+    # repository. `selected` is this shard's slice. Summing `selected` over a matrix's reports and
+    # comparing to the shared `discovered` turns that silent skip into a failure —
+    # `binpacker shards-check` does exactly that.
+    def shard_section
+      return nil unless @shard
+
+      {
+        index: @shard.index,
+        total: @shard.total,
+        discovered_tests: @discovered,
+        selected_tests: @selected
+      }
+    end
+
     def workers
       @worker_stats.map.with_index do |s, i|
         {
@@ -84,13 +112,15 @@ module Binpacker
     end
 
     def normalize_file(file)
-      file.to_s.sub(%r{\A\./}, "")
+      file.to_s.sub(%r{\A\./}, '')
     end
 
     def deviation_pct(loads)
       return 0.0 if loads.empty?
+
       mean = loads.sum / loads.size
       return 0.0 unless mean.positive?
+
       max_dev = loads.map { |t| (t - mean).abs }.max
       round(max_dev / mean * 100)
     end

data/lib/binpacker/shard.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Binpacker
+  # One slice of the suite, for splitting a run across independent machines.
+  #
+  # Workers divide a suite across the cores of ONE machine and share its wall clock; a shard divides it
+  # across machines that have no wall clock in common. So the two compose rather than compete: a CI matrix
+  # of N jobs each passing `--shard k/N` runs `worker_count` workers over its own slice, and the suite's
+  # wall time becomes roughly the slowest shard rather than the whole.
+  #
+  # The slice is cut by the SAME weight-balanced partitioner that assigns work to workers, over the same
+  # measured timings — shards are just a coarser bin-packing of the same problem, so an equal-count split
+  # would balance no better than round-robin. That also makes the cut deterministic: given one timing file,
+  # every shard computes the identical N-way partition and takes only its own bin, so no shard needs to
+  # know what the others decided, and every test lands in exactly one shard.
+  class Shard
+    attr_reader :index, :total
+
+    # Parses the `k/n` form used by `--shard` and BINPACKER_SHARD. `k` is 1-based, so a matrix can pass its
+    # own 1-based job number straight through.
+    #
+    # @param spec [String, nil]
+    # @return [Shard, nil] nil when `spec` is nil or empty, i.e. an unsharded run.
+    def self.parse(spec)
+      return nil if spec.nil? || spec.to_s.strip.empty?
+
+      match = %r{\A\s*(\d+)\s*/\s*(\d+)\s*\z}.match(spec.to_s)
+      raise ConfigError, "invalid shard #{spec.inspect}: expected the form K/N, e.g. 1/3" unless match
+
+      new(index: Integer(match[1]), total: Integer(match[2]))
+    end
+
+    def initialize(index:, total:)
+      raise ConfigError, "shard count must be at least 1, got #{total}" if total < 1
+      raise ConfigError, "shard index must be between 1 and #{total}, got #{index}" unless (1..total).cover?(index)
+
+      @index = index
+      @total = total
+      freeze
+    end
+
+    def to_s
+      "#{index}/#{total}"
+    end
+
+    # Whole-suite runs still construct no Shard, so this is only ever true for an explicit `--shard 1/1`.
+    def whole_suite?
+      total == 1
+    end
+
+    # @param tests [Array<Test>] every test discovered, before any slicing
+    # @param timings [Hash] predicted weight per test key, as `Timing#load_with_fallback` returns
+    # @param scheduler [Scheduler] the same partitioner the run uses for workers
+    # @return [Array<Test>] the tests belonging to this shard
+    def select(tests:, timings:, scheduler:)
+      return tests if whole_suite?
+
+      bins = scheduler.partition(tests: tests, worker_count: total, timings: timings)
+      bins[index - 1].remaining
+    end
+  end
+end

data/lib/binpacker/shard_check.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Binpacker
+  # Fan-in audit for a sharded matrix: did the shards, between them, actually run the whole suite?
+  #
+  # Shards never coordinate. Each cuts the same N-way partition from the timing data it loaded and takes
+  # its own bin, which is correct exactly as long as they all loaded the SAME data. In CI that means every
+  # shard job restoring the same timing cache — and the failure mode when one does not is the bad one:
+  # it partitions differently, some tests land in no shard, and every job still reports success. Nothing
+  # inside a single shard can notice, because a shard cannot tell "not mine" from "does not exist".
+  #
+  # So the check belongs after the matrix, over the run reports it produced. Point it at every shard's
+  # report and it fails unless the reports describe one coherent split of one suite.
+  class ShardCheck
+    Result = Struct.new(:ok, :problems, :summary, keyword_init: true) do
+      def ok? = ok
+    end
+
+    def self.call(paths) = new(paths).call
+
+    def initialize(paths)
+      @paths = Array(paths)
+    end
+
+    def call
+      return failure(['no run reports given']) if @paths.empty?
+
+      reports, unreadable = load_reports
+      return failure(unreadable) unless unreadable.empty?
+
+      shards = reports.filter_map { |path, data| shard_of(path, data) }
+      missing = reports.map(&:first) - shards.map { |s| s[:path] }
+      return failure(missing.map { |p| "#{p}: no `shard` section — was it run with --shard?" }) unless missing.empty?
+
+      problems = check(shards)
+      problems.empty? ? success(shards) : failure(problems)
+    end
+
+    private
+
+    def load_reports
+      reports = []
+      unreadable = []
+      @paths.each do |path|
+        reports << [path, JSON.parse(File.read(path))]
+      rescue Errno::ENOENT
+        unreadable << "#{path}: no such file"
+      rescue JSON::ParserError => e
+        unreadable << "#{path}: not valid JSON (#{e.message})"
+      end
+      [reports, unreadable]
+    end
+
+    def shard_of(path, data)
+      section = data['shard']
+      return nil unless section.is_a?(Hash)
+
+      {
+        path: path,
+        index: section['index'],
+        total: section['total'],
+        discovered: section['discovered_tests'],
+        selected: section['selected_tests']
+      }
+    end
+
+    def check(shards)
+      problems = []
+      problems.concat(agreement_problems(shards, :total, 'shard count'))
+      problems.concat(agreement_problems(shards, :discovered, 'discovered test count'))
+      problems.concat(completeness_problems(shards))
+      problems.concat(coverage_problems(shards))
+      problems
+    end
+
+    # Every report must describe the same matrix. Disagreement here means the reports were not produced by
+    # one run, and no coverage conclusion drawn from them would mean anything.
+    def agreement_problems(shards, field, label)
+      values = shards.map { |s| s[field] }.uniq
+      return [] if values.size <= 1
+
+      ["shards disagree on #{label}: #{values.sort_by(&:to_s).inspect}"]
+    end
+
+    # A matrix that lost a job silently drops that job's slice, which looks exactly like a smaller suite.
+    def completeness_problems(shards)
+      total = shards.first[:total]
+      return [] if total.nil?
+
+      seen = shards.map { |s| s[:index] }
+      duplicates = seen.tally.select { |_, n| n > 1 }.keys.sort
+      problems = []
+      problems << "shard #{duplicates.join(', ')} reported more than once" unless duplicates.empty?
+
+      absent = (1..total).to_a - seen
+      problems << "no report for shard #{absent.join(', ')} of #{total}" unless absent.empty?
+      problems
+    end
+
+    # The check this class exists for: the slices must add up to the suite.
+    def coverage_problems(shards)
+      discovered = shards.first[:discovered]
+      return [] if discovered.nil?
+
+      selected = shards.sum { |s| s[:selected].to_i }
+      return [] if selected == discovered
+
+      verb = selected < discovered ? 'ran no shard' : 'ran in more than one shard'
+      ["shards cover #{selected} of #{discovered} tests — #{(discovered - selected).abs} #{verb}. " \
+       'The shards partitioned different timing data; make every shard load the same timing file.']
+    end
+
+    def success(shards)
+      Result.new(
+        ok: true,
+        problems: [],
+        summary: "#{shards.size} shards cover all #{shards.first[:discovered]} tests"
+      )
+    end
+
+    def failure(problems)
+      Result.new(ok: false, problems: problems, summary: 'shard coverage check failed')
+    end
+  end
+end

data/lib/binpacker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Binpacker
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/binpacker.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
-require_relative "binpacker/version"
-require_relative "binpacker/config"
-require_relative "binpacker/timing"
-require_relative "binpacker/test_discovery"
-require_relative "binpacker/worker_queue"
-require_relative "binpacker/scheduler"
-require_relative "binpacker/worker"
-require_relative "binpacker/test_runner"
-require_relative "binpacker/calibration"
-require_relative "binpacker/report"
-require_relative "binpacker/skills"
-require_relative "binpacker/project_state"
-require_relative "binpacker/orchestrator"
-require_relative "binpacker/progress"
+require_relative 'binpacker/version'
+require_relative 'binpacker/config'
+require_relative 'binpacker/timing'
+require_relative 'binpacker/test_discovery'
+require_relative 'binpacker/worker_queue'
+require_relative 'binpacker/scheduler'
+require_relative 'binpacker/shard'
+require_relative 'binpacker/shard_check'
+require_relative 'binpacker/worker'
+require_relative 'binpacker/test_runner'
+require_relative 'binpacker/calibration'
+require_relative 'binpacker/report'
+require_relative 'binpacker/skills'
+require_relative 'binpacker/project_state'
+require_relative 'binpacker/orchestrator'
+require_relative 'binpacker/progress'
 
 module Binpacker
   Error = Class.new(StandardError)

data/sig/binpacker/orchestrator.rbs

@@ -7,10 +7,13 @@ module Binpacker
     @passthrough: untyped
     @quiet: untyped
     @report_path: untyped
+    @shard: Binpacker::Shard?
+    @discovered_count: Integer
+    @selected_count: Integer
     @timings: Hash[untyped, Float]
     @predicted_loads: Array[Float]
 
-    def initialize: (untyped, ?passthrough: untyped, ?quiet: untyped, ?report_path: untyped) -> void
+    def initialize: (untyped, ?passthrough: untyped, ?quiet: untyped, ?report_path: untyped, ?shard: Binpacker::Shard?) -> void
     def run: () -> { passed: untyped, total: untyped, passed_count: untyped, timings: Array[untyped], empty_filter: untyped }
 
     private

data/sig/binpacker/report.rbs

@@ -3,7 +3,8 @@ module Binpacker
     SCHEMA: Integer
     DRIFT_LIMIT: Integer
 
-    def initialize: (profile: untyped, algorithm: untyped, predicted_loads: untyped, worker_stats: untyped, all_timings: untyped, timings: untyped) -> void
+    def initialize: (profile: untyped, algorithm: untyped, predicted_loads: untyped, worker_stats: untyped, all_timings: untyped, timings: untyped, ?shard: Binpacker::Shard?, ?discovered: Integer?, ?selected: Integer?) -> void
+    def shard_section: () -> Hash[Symbol, untyped]?
     def to_h: () -> Hash[Symbol, untyped]
     def write: (untyped) -> untyped
   end

data/sig/binpacker/scheduler.rbs

@@ -1,5 +1,16 @@
 module Binpacker
   class Scheduler
     def self.for: (untyped) -> (Binpacker::LptScheduler | Binpacker::MultifitScheduler)
+
+    # Declared on the base so a caller holding a `Scheduler` can partition; the base body raises
+    # NotImplementedError and every concrete scheduler overrides it.
+    def partition: (tests: Array[untyped], worker_count: Integer, timings: Hash[untyped, Float]) -> Array[Binpacker::WorkerQueue]
+  end
+
+  class LptScheduler < Scheduler
+  end
+
+  class MultifitScheduler < Scheduler
+    ITERATIONS: Integer
   end
 end

data/sig/binpacker/shard.rbs

@@ -0,0 +1,13 @@
+module Binpacker
+  class Shard
+    attr_reader index: Integer
+    attr_reader total: Integer
+
+    def self.parse: (String?) -> Binpacker::Shard?
+
+    def initialize: (index: Integer, total: Integer) -> void
+    def to_s: () -> String
+    def whole_suite?: () -> bool
+    def select: (tests: Array[untyped], timings: Hash[untyped, Float], scheduler: Binpacker::Scheduler) -> Array[untyped]
+  end
+end

data/sig/binpacker/shard_check.rbs

@@ -0,0 +1,29 @@
+module Binpacker
+  class ShardCheck
+    class Result
+      attr_accessor ok: bool
+      attr_accessor problems: Array[String]
+      attr_accessor summary: String
+
+      def ok?: () -> bool
+    end
+
+    @paths: Array[String]
+
+    def self.call: (Array[String]) -> Binpacker::ShardCheck::Result
+
+    def initialize: (Array[String]) -> void
+    def call: () -> Binpacker::ShardCheck::Result
+
+    private
+
+    def load_reports: () -> [Array[[String, untyped]], Array[String]]
+    def shard_of: (String, untyped) -> Hash[Symbol, untyped]?
+    def check: (Array[Hash[Symbol, untyped]]) -> Array[String]
+    def agreement_problems: (Array[Hash[Symbol, untyped]], Symbol, String) -> Array[String]
+    def completeness_problems: (Array[Hash[Symbol, untyped]]) -> Array[String]
+    def coverage_problems: (Array[Hash[Symbol, untyped]]) -> Array[String]
+    def success: (Array[Hash[Symbol, untyped]]) -> Binpacker::ShardCheck::Result
+    def failure: (Array[String]) -> Binpacker::ShardCheck::Result
+  end
+end

data/sig/binpacker/worker_queue.rbs

@@ -1,8 +1,17 @@
 module Binpacker
   class WorkerQueue
+    include Enumerable[untyped]
+
+    attr_reader worker_id: Integer
+
     def initialize: (untyped, ?untyped) -> void
     def empty?: () -> (false | true)
     def pop: () -> untyped
+    def peek: () -> untyped
+    def size: () -> Integer
+    def remaining: () -> Array[untyped]
     def total_weight: (Hash[untyped, Float]) -> Float
+    def push: (untyped) -> untyped
+    def each: () { (untyped) -> void } -> void
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: binpacker
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - megurine
@@ -29,6 +29,8 @@ files:
 - lib/binpacker/project_state.rb
 - lib/binpacker/report.rb
 - lib/binpacker/scheduler.rb
+- lib/binpacker/shard.rb
+- lib/binpacker/shard_check.rb
 - lib/binpacker/skills.rb
 - lib/binpacker/test_discovery.rb
 - lib/binpacker/test_runner.rb
@@ -44,6 +46,8 @@ files:
 - sig/binpacker/project_state.rbs
 - sig/binpacker/report.rbs
 - sig/binpacker/scheduler.rbs
+- sig/binpacker/shard.rbs
+- sig/binpacker/shard_check.rbs
 - sig/binpacker/skills.rbs
 - sig/binpacker/test_discovery.rbs
 - sig/binpacker/test_runner.rbs