binpacker 0.1.0 → 0.3.0

data/lib/binpacker/orchestrator.rb

@@ -2,16 +2,20 @@
 
 module Binpacker
   class Orchestrator
-    def initialize(config, passthrough: [])
+    BATCH_SIZE = 10
+
+    def initialize(config, passthrough: [], quiet: false, report_path: nil)
       @config = config
       @passthrough = passthrough
+      @quiet = quiet
+      @report_path = report_path
     end
 
     def run
       tests = discover
-
       timing = Timing.new(@config.timing_file)
       timings = timing.load_with_fallback(tests)
+      @timings = timings
 
       scheduler = Scheduler.for(@config.scheduler["algorithm"])
       queues = scheduler.partition(
@@ -20,21 +24,53 @@ module Binpacker
         timings: timings
       )
 
+      # Capture predicted per-Worker loads before execution drains the queues.
+      @predicted_loads = queues.map { |q| q.total_weight(timings) }
+
       runner_class = TestRunner.for(@config.test_runner)
       workers = queues.map.with_index do |queue, idx|
-        Worker.new(idx, runner_class, passthrough: @passthrough).tap(&:start)
+        Worker.new(idx, runner_class, passthrough: @passthrough, quiet: @quiet).tap(&:start)
       end
 
+      if @config.scheduler["steal_enabled"]
+        run_dynamic(workers, queues, timing, tests)
+      else
+        run_static(workers, queues, timing, tests)
+      end
+    end
+
+    private
+
+    def discover
+      case @config.test_runner
+      when "rspec"
+        RSpecDiscovery.new(@config).enumerate
+      when "minitest"
+        MinitestDiscovery.new(@config).enumerate
+      else
+        raise ConfigError, "unsupported runner: #{@config.test_runner}"
+      end
+    end
+
+    def run_static(workers, queues, timing, tests)
+      queue_totals = queues.map(&:size)
+      progress = ProgressDisplay.new(workers.size)
+
       workers.zip(queues).each do |worker, queue|
         worker.send_tests(queue.remaining)
+        progress.update(worker.id, done: 0, total: queue_totals[worker.id], file: queue.remaining.first&.file || "")
       end
+      progress.refresh
+
+      workers.each(&:signal_done)
 
       all_timings = []
       all_passed = true
       total_examples = 0
       passed_examples = 0
-
-      workers.each(&:signal_done)
+      worker_time = Array.new(workers.size, 0.0)
+      worker_examples = Array.new(workers.size, 0)
+      worker_passed = Array.new(workers.size, 0)
 
       workers.each do |worker|
         worker.collect_results
@@ -42,6 +78,11 @@ module Binpacker
         all_passed &&= worker.success?
         total_examples += worker.example_count
         passed_examples += worker.passed_count
+        worker_examples[worker.id] = worker.example_count
+        worker_passed[worker.id] = worker.passed_count
+        worker_time[worker.id] = worker.timings.sum { |t| t[:time] }
+        progress.update(worker.id, done: queue_totals[worker.id], total: queue_totals[worker.id], file: "done")
+        progress.refresh
       rescue WorkerError => e
         $stderr.puts "worker #{worker.id} error: #{e.message}"
         all_passed = false
@@ -49,26 +90,178 @@ module Binpacker
         worker.cleanup
       end
 
+      progress.finish
+
+      worker_stats = workers.map.with_index do |w, i|
+        {
+          files: queue_totals[i],
+          total_time: worker_time[i],
+          examples: worker_examples[i],
+          passed: worker_passed[i]
+        }
+      end
+      progress.summary(worker_stats)
+      write_report(worker_stats, all_timings)
+
+      finalize(timing, all_timings, all_passed, total_examples, passed_examples, tests)
+    end
+
+    def run_dynamic(workers, queues, timing, tests)
+      all_timings = []
+      all_passed = true
+      total_examples = 0
+      passed_examples = 0
+      active = []
+
+      queue_totals = queues.map(&:size)
+      worker_done = Array.new(workers.size, 0)
+      batch_sizes = Array.new(workers.size, 0)
+      worker_time = Array.new(workers.size, 0.0)
+      worker_examples = Array.new(workers.size, 0)
+      worker_passed = Array.new(workers.size, 0)
+
+      progress = ProgressDisplay.new(workers.size)
+
+      workers.zip(queues).each do |worker, queue|
+        batch = drain_batch(queue)
+        if batch.empty?
+          worker.signal_done
+          worker.collect_results
+          all_timings.concat(worker.timings)
+          all_passed &&= worker.success?
+          total_examples += worker.example_count
+          passed_examples += worker.passed_count
+          worker_examples[worker.id] = worker.example_count
+          worker_passed[worker.id] = worker.passed_count
+          worker.cleanup
+          worker_done[worker.id] = queue_totals[worker.id]
+          progress.update(worker.id, done: worker_done[worker.id], total: queue_totals[worker.id], file: "done")
+        else
+          worker.send_tests(batch)
+          worker.batch_done
+          active << worker
+          batch_sizes[worker.id] = batch.size
+          current_file = batch.first&.file || ""
+          progress.update(worker.id, done: 0, total: queue_totals[worker.id], file: current_file)
+        end
+      end
+
+      until active.empty?
+        ready = active.find { |w| w.wait_for_batch }
+        unless ready
+          active.reject! { |w| w.status == :crashed || w.status == :error }
+          sleep 0.1
+          next
+        end
+
+        begin
+          all_passed &&= ready.success?
+          total_examples += ready.example_count
+          passed_examples += ready.passed_count
+
+          worker_done[ready.id] += batch_sizes[ready.id]
+          worker_examples[ready.id] = ready.example_count
+          worker_passed[ready.id] = ready.passed_count
+
+          own_queue = queues[ready.id]
+          next_batch = drain_batch(own_queue)
+
+          if next_batch.empty?
+            donor = queues.reject(&:empty?).max_by(&:size)
+            next_batch = drain_batch(donor) if donor
+          end
+
+          if next_batch.any?
+            ready.send_tests(next_batch)
+            ready.batch_done
+            batch_sizes[ready.id] = next_batch.size
+            current_file = next_batch.first&.file || ""
+            progress.update(ready.id, done: worker_done[ready.id], total: queue_totals[ready.id], file: current_file)
+            progress.refresh
+          else
+            ready.signal_done
+            all_timings.concat(ready.timings)
+            active.delete(ready)
+            worker_done[ready.id] = queue_totals[ready.id]
+            progress.update(ready.id, done: queue_totals[ready.id], total: queue_totals[ready.id], file: "done")
+            progress.refresh
+          end
+        rescue WorkerError => e
+          $stderr.puts "worker #{ready.id} error: #{e.message}"
+          all_passed = false
+          active.delete(ready)
+        end
+      end
+
+      progress.finish
+
+      worker_stats = workers.map.with_index do |w, i|
+        tw = w.timings.sum { |t| t[:time] }
+        {
+          files: queue_totals[i],
+          total_time: tw > 0 ? tw : worker_time[i],
+          examples: worker_examples[i],
+          passed: worker_passed[i]
+        }
+      end
+      progress.summary(worker_stats)
+      write_report(worker_stats, all_timings)
+
+      workers.each(&:cleanup)
+      finalize(timing, all_timings, all_passed, total_examples, passed_examples, tests)
+    end
+
+    def write_report(worker_stats, all_timings)
+      return unless @report_path
+
+      Report.new(
+        profile: @config.profile,
+        algorithm: @config.scheduler["algorithm"],
+        predicted_loads: @predicted_loads,
+        worker_stats: worker_stats,
+        all_timings: all_timings,
+        timings: @timings
+      ).write(@report_path)
+    end
+
+    def drain_batch(queue)
+      return [] if queue.nil? || queue.empty?
+      batch = []
+      BATCH_SIZE.times do
+        test = queue.pop
+        break unless test
+        batch << test
+      end
+      batch
+    end
+
+    def finalize(timing, all_timings, all_passed, total_examples, passed_examples, tests)
       timing.append_all(all_timings) unless all_timings.empty?
+      empty_filter = minitest_empty_filter?(tests, total_examples)
+      all_passed = false if empty_filter
 
       {
         passed: all_passed,
         total: total_examples,
         passed_count: passed_examples,
-        timings: all_timings
+        timings: all_timings,
+        empty_filter: empty_filter
       }
     end
 
-    private
+    def minitest_empty_filter?(tests, total_examples)
+      return false unless @config.test_runner == "minitest"
+      return false unless tests.any?
+      return false unless total_examples.zero?
 
-    def discover
-      case @config.test_runner
-      when "rspec"
-        RSpecDiscovery.new(@config).enumerate
-      when "minitest"
-        MinitestDiscovery.new(@config).enumerate
-      else
-        raise ConfigError, "unsupported runner: #{@config.test_runner}"
+      minitest_include_filter?
+    end
+
+    def minitest_include_filter?
+      @passthrough.any? do |arg|
+        %w[--name --include -n -i].include?(arg) ||
+          arg.start_with?("--name=", "--include=") ||
+          (arg.start_with?("-n", "-i") && arg.length > 2)
       end
     end
   end

data/lib/binpacker/progress.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Binpacker
+  class ProgressDisplay
+    CI_INTERVAL = 15 # seconds between CI output lines
+
+    def initialize(worker_count, tty: $stdout.tty?)
+      @worker_count = worker_count
+      @tty = tty
+      @workers = Array.new(worker_count) { { done: 0, total: 0, file: "", elapsed: 0.0 } }
+      @start = Time.now
+      @last_ci_output = Time.at(Time.now.to_f - CI_INTERVAL)
+      @lines_written = 0
+      @mutex = Mutex.new
+    end
+
+    def update(worker_id, done:, total:, file:, elapsed: 0.0)
+      @mutex.synchronize do
+        w = @workers[worker_id]
+        w[:done] = done
+        w[:total] = total
+        w[:file] = file
+        w[:elapsed] = elapsed
+      end
+    end
+
+    def refresh
+      if @tty
+        redraw
+      else
+        periodic_output
+      end
+    end
+
+    def finish(worker_stats = [])
+      return unless @tty
+      redraw
+      $stdout.puts
+    end
+
+    def summary(worker_stats)
+      active = worker_stats.reject { |s| s[:files] == 0 && s[:examples] == 0 }
+      return if active.empty?
+
+      active.each_with_index do |s, i|
+        t = format_time(s[:total_time])
+        wid = worker_stats.index(s)
+        $stdout.puts "  Worker #{wid}: #{s[:files]} tests, #{t} | #{s[:examples]} examples, #{s[:passed]} passed"
+      end
+      total_tests = active.sum { |s| s[:files] }
+      total_time = active.sum { |s| s[:total_time] }
+      total_examples = active.sum { |s| s[:examples] }
+      times = active.map { |s| s[:total_time] }
+      mean = total_time / active.size
+      max_dev = times.map { |t| (t - mean).abs }.max
+      dev_pct = mean > 0 ? (max_dev / mean * 100).round(1) : 0
+
+      $stdout.puts "  ──"
+      $stdout.puts "  Total: #{total_tests} tests, #{format_time(total_time)} | #{total_examples} examples"
+      $stdout.puts "  Balance: max deviation #{format_time(max_dev)} (#{dev_pct}%)"
+    end
+
+    private
+
+    def redraw
+      @mutex.synchronize do
+        clear_lines
+        @workers.each_with_index do |w, i|
+          bar = build_bar(w[:done], w[:total])
+          status = w[:total] > 0 && w[:done] >= w[:total] ? "done" : w[:file][-50..] || ""
+          $stdout.puts format_line(i, bar, w[:done], w[:total], status, w[:elapsed])
+        end
+        @lines_written = @worker_count
+      end
+    end
+
+    def clear_lines
+      return if @lines_written == 0
+      @lines_written.times do
+        $stdout.print "\033[A\033[K"
+      end
+    end
+
+    def build_bar(done, total)
+      return "[----------]" if total == 0
+      width = 10
+      filled = (done.to_f / total * width).round
+      "[#{'█' * filled}#{'░' * (width - filled)}]"
+    end
+
+    def format_line(idx, bar, done, total, file, elapsed)
+      ts = format_time(elapsed)
+      "W#{idx} #{bar} #{done.to_s.rjust(3)}/#{total.to_s.ljust(3)} #{file.ljust(50)} #{ts}"
+    end
+
+    def periodic_output
+      now = Time.now
+      return if now - @last_ci_output < CI_INTERVAL
+      @last_ci_output = now
+
+      parts = @workers.map.with_index do |w, i|
+        ratio = w[:total] > 0 ? "#{w[:done]}/#{w[:total]}" : "0/?"
+        "W#{i}: #{ratio}"
+      end
+      elapsed = (now - @start).round(1)
+      $stdout.puts "[binpacker #{elapsed}s] #{parts.join(' | ')}"
+      $stdout.flush
+    end
+
+    def format_time(seconds)
+      return "  0.0s" if seconds < 0.001
+      m = (seconds / 60).floor
+      s = (seconds % 60).round(1)
+      m > 0 ? "#{m}m#{s.to_s.rjust(4, '0')}s" : "#{s.to_s.rjust(5)}s"
+    end
+  end
+end

data/lib/binpacker/project_state.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Binpacker
+  # Inspects the working directory to report binpacker's setup state and
+  # recommend the next skill. Backs `binpacker describe`.
+  # See docs/design/agent-workflows.md.
+  class ProjectState
+    CONFIG_FILE = "binpacker.yml"
+    DEFAULT_TIMING_FILE = "binpacker.timings"
+    SUPPORTED_FRAMEWORKS = %w[rspec minitest].freeze
+    TESTUNIT_HINT = %r{test-unit|test/unit}
+
+    def config_present?
+      File.exist?(CONFIG_FILE)
+    end
+
+    def timing_present?
+      File.exist?(timing_file)
+    end
+
+    # "rspec", "minitest", "test-unit", or nil. Minitest and test-unit share
+    # the *_test.rb convention, so they are told apart by dependency hints.
+    def framework
+      return minitest_family if minitest_globs?
+      return "rspec" if Dir.glob("spec/**/*_spec.rb").any?
+      nil
+    end
+
+    # binpacker ships runners for rspec and minitest only. A detected framework
+    # outside that set (e.g. test-unit) is unsupported; nil is merely unknown.
+    def supported_framework?
+      fw = framework
+      fw.nil? || SUPPORTED_FRAMEWORKS.include?(fw)
+    end
+
+    def ci_wired?
+      Dir.glob(".github/workflows/*.{yml,yaml}").any? do |wf|
+        File.read(wf).include?("binpacker run")
+      end
+    end
+
+    # The skill the agent should run next.
+    def recommendation
+      return "binpacker-setup" unless config_present? && timing_present?
+      "binpacker-improve"
+    end
+
+    def to_h
+      {
+        config_present: config_present?,
+        timing_present: timing_present?,
+        framework: framework,
+        ci_wired: ci_wired?,
+        recommendation: recommendation
+      }
+    end
+
+    private
+
+    def minitest_globs?
+      Dir.glob("test*/**/*_test.rb").any? || Dir.glob("test*/**/test_*.rb").any?
+    end
+
+    def minitest_family
+      testunit_hinted? ? "test-unit" : "minitest"
+    end
+
+    def testunit_hinted?
+      sources = Dir.glob("Gemfile") + Dir.glob("*.gemspec") + Dir.glob("test*/**/*_test.rb").first(5)
+      sources.any? { |file| File.read(file).match?(TESTUNIT_HINT) }
+    rescue StandardError
+      false
+    end
+
+    def timing_file
+      return DEFAULT_TIMING_FILE unless config_present?
+      Config.new.timing_file
+    rescue StandardError
+      DEFAULT_TIMING_FILE
+    end
+  end
+end

data/lib/binpacker/report.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Binpacker
+  # Builds the machine-readable Run report: predicted versus actual per-Worker
+  # durations plus the worst per-Test Drift. See docs/design/run-report-format.md.
+  class Report
+    SCHEMA = 1
+    DRIFT_LIMIT = 10
+
+    def initialize(profile:, algorithm:, predicted_loads:, worker_stats:, all_timings:, timings:)
+      @profile = profile
+      @algorithm = algorithm
+      @predicted_loads = predicted_loads
+      @worker_stats = worker_stats
+      @all_timings = all_timings
+      @timings = timings
+    end
+
+    def to_h
+      predicted = @predicted_loads
+      actual = @worker_stats.map { |s| s[:total_time] }
+
+      {
+        schema: SCHEMA,
+        profile: @profile,
+        algorithm: @algorithm,
+        worker_count: @worker_stats.size,
+        predicted_makespan: round(predicted.max || 0.0),
+        actual_makespan: round(actual.max || 0.0),
+        workers: workers,
+        balance: {
+          predicted_deviation_pct: deviation_pct(predicted),
+          actual_deviation_pct: deviation_pct(actual)
+        },
+        drift: drift
+      }
+    end
+
+    def write(path)
+      File.write(path, JSON.pretty_generate(to_h))
+    end
+
+    private
+
+    def workers
+      @worker_stats.map.with_index do |s, i|
+        {
+          id: i,
+          predicted: round(@predicted_loads[i] || 0.0),
+          actual: round(s[:total_time]),
+          tests: s[:files],
+          examples: s[:examples]
+        }
+      end
+    end
+
+    # Drift is reported per file (the scheduling unit), so predicted and actual
+    # are compared at the same granularity even when timings are recorded
+    # per example. Both sides are aggregated to normalized file paths.
+    def drift
+      actual = aggregate_by_file(@all_timings.map { |e| [e[:file], e[:time]] })
+      predicted = aggregate_by_file(@timings.map { |(file, _name), weight| [file, weight] })
+
+      (actual.keys | predicted.keys)
+        .map { |file| drift_entry(file, predicted[file], actual[file]) }
+        .sort_by { |d| -(d[:actual] - d[:predicted]).abs }
+        .first(DRIFT_LIMIT)
+    end
+
+    def drift_entry(file, predicted, actual)
+      {
+        file: file,
+        predicted: round(predicted || Timing::DEFAULT_WEIGHT),
+        actual: round(actual || 0.0)
+      }
+    end
+
+    def aggregate_by_file(pairs)
+      pairs.each_with_object(Hash.new(0.0)) do |(file, time), acc|
+        acc[normalize_file(file)] += time
+      end
+    end
+
+    def normalize_file(file)
+      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
+
+    def round(value)
+      value.to_f.round(3)
+    end
+  end
+end

data/lib/binpacker/scheduler.rb

@@ -2,7 +2,6 @@
 
 module Binpacker
   class Scheduler
-    # Returns Array<WorkerQueue> one per worker.
     def partition(tests:, worker_count:, timings:)
       raise NotImplementedError
     end
@@ -10,28 +9,94 @@ module Binpacker
     def self.for(strategy)
       case strategy.to_s
       when "lpt" then LptScheduler.new
+      when "multifit" then MultifitScheduler.new
       else
         raise SchedulerError, "unknown scheduling algorithm: #{strategy}"
       end
     end
+
+    private
+
+    def weight(test, timings)
+      timings.fetch(test.key, Timing::DEFAULT_WEIGHT)
+    end
+
+    def sorted_by_weight(tests, timings)
+      tests.sort_by { |t| -weight(t, timings) }
+    end
   end
 
   class LptScheduler < Scheduler
-    # Longest Processing Time first.
-    # Sort tests by descending weight, assign each to the least-loaded worker.
     def partition(tests:, worker_count:, timings:)
       queues = Array.new(worker_count) { |i| WorkerQueue.new(i) }
       loads = Array.new(worker_count, 0.0)
 
-      # Sort by weight descending; unknown tests get default weight
-      sorted = tests.sort_by { |t|
-        -timings.fetch(t.key, Timing::DEFAULT_WEIGHT)
-      }
-
-      sorted.each do |test|
+      sorted_by_weight(tests, timings).each do |test|
         min_idx = loads.each_with_index.min_by { |load, _| load }.last
         queues[min_idx].push(test)
-        loads[min_idx] += timings.fetch(test.key, Timing::DEFAULT_WEIGHT)
+        loads[min_idx] += weight(test, timings)
+      end
+
+      queues
+    end
+  end
+
+  class MultifitScheduler < Scheduler
+    ITERATIONS = 7
+
+    def partition(tests:, worker_count:, timings:)
+      sorted = sorted_by_weight(tests, timings)
+
+      upper = lpt_makespan(sorted, worker_count, timings)
+      lower = [max_weight(sorted, timings), total_weight(sorted, timings) / worker_count.to_f].max
+
+      best_queues = nil
+      ITERATIONS.times do
+        mid = (upper + lower) / 2.0
+        queues = first_fit_decreasing(sorted, worker_count, mid, timings)
+
+        if queues
+          best_queues = queues
+          upper = mid
+        else
+          lower = mid
+        end
+      end
+
+      best_queues || LptScheduler.new.partition(tests: tests, worker_count: worker_count, timings: timings)
+    end
+
+    private
+
+    def lpt_makespan(sorted, worker_count, timings)
+      loads = Array.new(worker_count, 0.0)
+      sorted.each do |test|
+        min_idx = loads.each_with_index.min_by { |l, _| l }.last
+        loads[min_idx] += weight(test, timings)
+      end
+      loads.max
+    end
+
+    def max_weight(sorted, timings)
+      sorted.map { |t| weight(t, timings) }.max || 0.0
+    end
+
+    def total_weight(sorted, timings)
+      sorted.sum { |t| weight(t, timings) }
+    end
+
+    def first_fit_decreasing(sorted, worker_count, capacity, timings)
+      queues = Array.new(worker_count) { |i| WorkerQueue.new(i) }
+      loads = Array.new(worker_count, 0.0)
+
+      sorted.each do |test|
+        w = weight(test, timings)
+        idx = loads.each_with_index.find { |l, _| l + w <= capacity }&.last
+
+        return nil unless idx
+
+        queues[idx].push(test)
+        loads[idx] += w
       end
 
       queues