binpacker 0.2.0 → 0.4.0

data/lib/binpacker/progress.rb

@@ -7,7 +7,7 @@ module Binpacker
     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 } }
+      @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
@@ -32,8 +32,9 @@ module Binpacker
       end
     end
 
-    def finish(worker_stats = [])
+    def finish(_worker_stats = [])
       return unless @tty
+
       redraw
       $stdout.puts
     end
@@ -42,12 +43,13 @@ module Binpacker
       active = worker_stats.reject { |s| s[:files] == 0 && s[:examples] == 0 }
       return if active.empty?
 
-      active.each_with_index do |s, i|
+      worker_stats.each_with_index do |s, wid|
+        next if s[:files] == 0 && s[:examples] == 0
+
         t = format_time(s[:total_time])
-        wid = worker_stats.index(s)
-        $stdout.puts "  Worker #{wid}: #{s[:files]} files, #{t} | #{s[:examples]} examples, #{s[:passed]} passed"
+        $stdout.puts "  Worker #{wid}: #{s[:files]} tests, #{t} | #{s[:examples]} examples, #{s[:passed]} passed"
       end
-      total_files = active.sum { |s| s[:files] }
+      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] }
@@ -55,8 +57,8 @@ module Binpacker
       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_files} files, #{format_time(total_time)} | #{total_examples} examples"
+      $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
 
@@ -67,7 +69,7 @@ module Binpacker
         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..] || ""
+          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
@@ -76,13 +78,15 @@ module Binpacker
 
     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
+      return '[----------]' if total == 0
+
       width = 10
       filled = (done.to_f / total * width).round
       "[#{'█' * filled}#{'░' * (width - filled)}]"
@@ -96,21 +100,21 @@ module Binpacker
     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|
-        if w[:total] > 0 && w[:done] >= w[:total]
-          "W#{i}: done"
-        else
-          "W#{i}: #{w[:done]}/#{w[:total]}"
-        end
+        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
+      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"

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/skills.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Binpacker
+  # Registry for the gem-shipped, user-facing agent skills. Skills live in the
+  # gem's top-level skills/ directory, each as skills/<name>/SKILL.md.
+  # See docs/adr/0003-agent-driven-install-and-skills.md.
+  module Skills
+    ROOT = File.expand_path("../../skills", __dir__)
+
+    module_function
+
+    # [{ name:, path: }], sorted by name.
+    def list
+      Dir.glob(File.join(ROOT, "*", "SKILL.md")).sort.map do |file|
+        { name: File.basename(File.dirname(file)), path: file }
+      end
+    end
+
+    def exist?(name)
+      !path(name).nil?
+    end
+
+    # Absolute path of a skill's SKILL.md, or nil when unknown.
+    def path(name)
+      file = File.join(ROOT, name, "SKILL.md")
+      File.file?(file) ? file : nil
+    end
+
+    # The SKILL.md body for a skill.
+    def body(name)
+      file = path(name)
+      raise Error, "unknown skill: #{name}" unless file
+      File.read(file)
+    end
+  end
+end

data/lib/binpacker/test_discovery.rb

@@ -69,7 +69,13 @@ module Binpacker
 
   class MinitestDiscovery < TestDiscovery
     def enumerate
-      require "minitest"
+      begin
+        require "minitest"
+      rescue LoadError
+        raise DiscoveryError,
+          "minitest is not available. binpacker supports rspec and minitest; " \
+          "test-unit and other frameworks are not supported."
+      end
       add_project_load_paths
       def Minitest.autorun; end
       Minitest.seed = 42

data/lib/binpacker/timing.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "json"
+require 'json'
 
 module Binpacker
   class Timing
@@ -8,70 +8,173 @@ module Binpacker
 
     DEFAULT_WEIGHT = 1.0
 
+    # Samples retained per test by #compact! and consulted by the
+    # median in #load_per_file. Three samples make a single anomalous
+    # run (GC pause, noisy CI neighbour) unable to move the weight.
+    MAX_SAMPLES_PER_TEST = 3
+
     def initialize(path)
       @path = Pathname(path)
     end
 
+    # True once any timing samples exist, i.e. the project has been
+    # calibrated at least once. Callers use this to tell a measured
+    # run (weights in seconds) from a pure cold start (fallbacks only).
+    def calibrated?
+      !samples_by_test.empty?
+    end
+
     def load_with_fallback(tests)
       per_file = load_per_file
+      coefficient = seconds_per_kb(per_file)
       tests.each_with_object({}) do |test, hash|
         key = normalize_path(test.file)
-        hash[test.key] = per_file.fetch(key) { filesize_weight(test.file) }
+        hash[test.key] = per_file.fetch(key) { fallback_weight(test.file, coefficient) }
       end
     end
 
     def load_raw
-      return {} unless @path.exist?
-
-      @path.each_line(encoding: "UTF-8")
-        .map { |line| parse_line(line) }
-        .compact
-        .group_by { |e| [normalize_path(e.file), e.name] }
-        .transform_values { |entries| entries.last.time }
+      @load_raw ||= samples_by_test.transform_values(&:last)
     end
 
+    # Predicted weight per file: the median of each test's recent
+    # samples, summed per file. The append-only history must NOT be
+    # summed wholesale — a file present in N historical runs would
+    # weigh ~N times its true cost, so long-lived files dominate and
+    # newly added ones are starved, skewing the partition.
     def load_per_file
-      return {} unless @path.exist?
+      samples_by_test.each_with_object({}) do |((file, _name), times), per_file|
+        weight = median(times.last(MAX_SAMPLES_PER_TEST))
+        per_file[file] = per_file.fetch(file, 0.0) + weight
+      end
+    end
 
-      @path.each_line(encoding: "UTF-8")
-        .map { |line| parse_line(line) }
-        .compact
-        .group_by { |e| normalize_path(e.file) }
-        .transform_values { |entries| entries.sum(&:time) }
+    # Rewrites the timing file keeping only the most recent
+    # MAX_SAMPLES_PER_TEST samples per test, so the append-only
+    # history (and any CI cache built from it) stays bounded instead
+    # of growing by one run per invocation.
+    def compact!
+      samples = samples_by_test
+      return if samples.empty?
+
+      tmp = Pathname("#{@path}.tmp")
+      tmp.open('w', encoding: 'UTF-8') do |io|
+        samples.each do |(file, name), times|
+          times.last(MAX_SAMPLES_PER_TEST).each do |time|
+            io.puts JSON.generate({ file: file, name: name, time: time })
+          end
+        end
+      end
+      File.rename(tmp.to_s, @path.to_s)
+      invalidate
     end
 
     def normalize_path(path)
-      Pathname(path).cleanpath.to_s.sub(/\A\.\//, "")
+      Pathname(path).cleanpath.to_s.sub(%r{\A\./}, '')
     end
 
-    def weight_for(file:, name:)
-      measured = load_raw
-      measured.fetch([file, name]) { filesize_weight(file) }
+    # True when a measured Weight already exists for this Test.
+    def measured?(file:, name:)
+      load_raw.key?([normalize_path(file), name])
     end
 
     def append(file:, name:, time:)
       @path.dirname.mkpath unless @path.dirname.directory?
-      @path.open("a", encoding: "UTF-8") { |io| io.puts JSON.generate({ file: file, name: name, time: time }) }
+      @path.open('a', encoding: 'UTF-8') { |io| io.puts JSON.generate({ file: file, name: name, time: time }) }
+      invalidate
     end
 
     def append_all(entries)
       return if entries.empty?
+
       @path.dirname.mkpath unless @path.dirname.directory?
-      @path.open("a", encoding: "UTF-8") do |io|
+      @path.open('a', encoding: 'UTF-8') do |io|
         entries.each { |e| io.puts JSON.generate({ file: e[:file], name: e[:name], time: e[:time] }) }
       end
+      invalidate
     end
 
     private
 
+    # [normalized file, name] => [sample, ...] in append (= run) order.
+    def samples_by_test
+      @samples_by_test ||= begin
+        samples = Hash.new { |h, k| h[k] = [] }
+        if @path.exist?
+          @path.each_line(encoding: 'UTF-8') do |line|
+            entry = parse_line(line)
+            samples[[normalize_path(entry.file), entry.name]] << entry.time if entry
+          end
+        end
+        samples.default_proc = nil
+        samples
+      end
+    end
+
+    def invalidate
+      @samples_by_test = nil
+      @load_raw = nil
+    end
+
+    def median(values)
+      sorted = values.sort
+      mid = sorted.size / 2
+      sorted.size.odd? ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2.0
+    end
+
     def filesize_weight(file)
       path = Pathname(file)
       path.exist? ? [path.size / 1024.0, DEFAULT_WEIGHT].max : DEFAULT_WEIGHT
     end
 
+    # Seconds-per-KB coefficient used to scale filesize fallbacks onto
+    # the same axis as measured Weights. Measured Weights are seconds;
+    # the raw filesize fallback is KB, so mixing them (batch floors,
+    # donor selection) compares apples to oranges — 30s of predicted
+    # work reads as "30 KB of files". We estimate a conversion from
+    # the files we DO have timings for: for each measured file that
+    # still exists on disk with size > 0, take measured_seconds /
+    # size_kb, and use the median of those ratios (robust to a few
+    # outlier files that are unusually fast or slow for their size).
+    # nil when nothing can be estimated (no measurements, or none of
+    # the measured files exist on disk) — callers then keep raw KB.
+    def seconds_per_kb(per_file)
+      ratios = per_file.filter_map do |file, seconds|
+        kb = size_kb(file)
+        next if kb.nil? || kb <= 0
+
+        seconds / kb
+      end
+      ratios.empty? ? nil : median(ratios)
+    end
+
+    # Predicted Weight for an unmeasured Test. Without a coefficient we
+    # keep the legacy raw-KB behavior (floored at 1.0). With one we
+    # scale filesize into seconds: an existing file becomes
+    # size_kb * coefficient (floored at 0.01 to avoid degenerate zero
+    # weights, but NOT at 1.0 — sub-second predictions are meaningful
+    # now that the unit is seconds); a missing/unreadable file falls
+    # back to DEFAULT_WEIGHT as a plausible seconds-scale default.
+    def fallback_weight(file, coefficient)
+      return filesize_weight(file) if coefficient.nil?
+
+      kb = size_kb(file)
+      return DEFAULT_WEIGHT if kb.nil?
+
+      [kb * coefficient, 0.01].max
+    end
+
+    # File size in KB, or nil when the file does not exist / is unreadable.
+    def size_kb(file)
+      path = Pathname(file)
+      path.exist? ? path.size / 1024.0 : nil
+    rescue SystemCallError
+      nil
+    end
+
     def parse_line(line)
       data = JSON.parse(line.strip)
-      Entry.new(file: data["file"], name: data["name"], time: data["time"])
+      Entry.new(file: data['file'], name: data['name'], time: data['time'])
     rescue JSON::ParserError
       nil
     end

data/lib/binpacker/version.rb

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

data/lib/binpacker/worker_queue.rb

@@ -37,7 +37,7 @@ module Binpacker
     end
 
     def total_weight(timings)
-      remaining.sum { |t| timings.fetch(t.key, Timing::DEFAULT_WEIGHT) }
+      remaining.sum(0.0) { |t| timings.fetch(t.key, Timing::DEFAULT_WEIGHT) }
     end
 
     def push(test)

data/lib/binpacker.rb

@@ -9,6 +9,9 @@ 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"
 

data/sig/binpacker/calibration.rbs

@@ -0,0 +1,6 @@
+module Binpacker
+  class Calibration
+    def initialize: (untyped) -> void
+    def run: (untyped, ?incremental: bool) -> Array[untyped]
+  end
+end

data/sig/binpacker/cli.rbs

@@ -0,0 +1,7 @@
+module Binpacker
+  class CLI
+    def self.start: (untyped) -> nil
+    def initialize: (untyped) -> void
+    def run: () -> nil
+  end
+end

data/sig/binpacker/config.rbs

@@ -0,0 +1,13 @@
+module Binpacker
+  class Config
+    def initialize: (?profile: untyped, ?config_path: untyped) -> void
+    def worker_count: () -> Integer
+    def test_runner: () -> String
+    def timing_file: () -> String
+    def test_pattern: () -> String
+    def test_exclude: () -> Array[String]
+    def test_granularity: () -> String
+    def report_file: () -> String?
+    def profile: () -> String
+  end
+end

data/sig/binpacker/orchestrator.rbs

@@ -0,0 +1,28 @@
+module Binpacker
+  class Orchestrator
+    MIN_BATCH_WEIGHT: Float
+    COLD_START_BATCHES_PER_WORKER: Integer
+
+    @config: untyped
+    @passthrough: untyped
+    @quiet: untyped
+    @report_path: untyped
+    @timings: Hash[untyped, Float]
+    @predicted_loads: Array[Float]
+
+    def initialize: (untyped, ?passthrough: untyped, ?quiet: untyped, ?report_path: untyped) -> void
+    def run: () -> { passed: untyped, total: untyped, passed_count: untyped, timings: Array[untyped], empty_filter: untyped }
+
+    private
+
+    def discover: () -> untyped
+    def run_static: (untyped, untyped, Binpacker::Timing, untyped) -> untyped
+    def run_dynamic: (untyped, untyped, Binpacker::Timing, untyped, Float) -> untyped
+    def write_report: (untyped, Array[untyped]) -> void
+    def min_batch_weight: (Binpacker::Timing, Hash[untyped, Float]) -> Float
+    def drain_batch: (Binpacker::WorkerQueue?, Float) -> Array[untyped]
+    def finalize: (Binpacker::Timing, Array[untyped], untyped, untyped, untyped, untyped) -> { passed: untyped, total: untyped, passed_count: untyped, timings: Array[untyped], empty_filter: untyped }
+    def minitest_empty_filter?: (untyped, untyped) -> bool
+    def minitest_include_filter?: () -> bool
+  end
+end

data/sig/binpacker/progress.rbs

@@ -0,0 +1,5 @@
+module Binpacker
+  class ProgressDisplay
+    def initialize: (untyped, ?tty: untyped) -> void
+  end
+end

data/sig/binpacker/project_state.rbs

@@ -0,0 +1,16 @@
+module Binpacker
+  class ProjectState
+    CONFIG_FILE: String
+    DEFAULT_TIMING_FILE: String
+    SUPPORTED_FRAMEWORKS: Array[String]
+    TESTUNIT_HINT: Regexp
+
+    def config_present?: () -> bool
+    def timing_present?: () -> bool
+    def framework: () -> String?
+    def supported_framework?: () -> bool
+    def ci_wired?: () -> bool
+    def recommendation: () -> String
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+end

data/sig/binpacker/report.rbs

@@ -0,0 +1,10 @@
+module Binpacker
+  class Report
+    SCHEMA: Integer
+    DRIFT_LIMIT: Integer
+
+    def initialize: (profile: untyped, algorithm: untyped, predicted_loads: untyped, worker_stats: untyped, all_timings: untyped, timings: untyped) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+    def write: (untyped) -> untyped
+  end
+end

data/sig/binpacker/scheduler.rbs

@@ -0,0 +1,5 @@
+module Binpacker
+  class Scheduler
+    def self.for: (untyped) -> (Binpacker::LptScheduler | Binpacker::MultifitScheduler)
+  end
+end