binpacker 0.2.0 → 0.4.0

data/sig/binpacker/skills.rbs

@@ -0,0 +1,10 @@
+module Binpacker
+  module Skills
+    ROOT: String
+
+    def self.list: () -> Array[Hash[Symbol, String]]
+    def self.exist?: (untyped) -> bool
+    def self.path: (untyped) -> String?
+    def self.body: (untyped) -> String
+  end
+end

data/sig/binpacker/test_discovery.rbs

@@ -0,0 +1,15 @@
+module Binpacker
+  def key: () -> [untyped, String]
+  class TestDiscovery
+    def initialize: (untyped) -> void
+    def enumerate: () -> Array[Binpacker::Test]
+  end
+  class RSpecDiscovery < TestDiscovery
+    def enumerate: () -> Array[Binpacker::Test]
+  end
+  class MinitestDiscovery < TestDiscovery
+    def enumerate: () -> Array[Binpacker::Test]
+  end
+  class Test
+  end
+end

data/sig/binpacker/test_runner.rbs

@@ -0,0 +1,13 @@
+module Binpacker
+  class TestRunner
+    def self.runner_name: () -> bot
+    def self.for: (untyped) -> (singleton(Binpacker::MinitestRunner) | singleton(Binpacker::RSpecRunner))
+  end
+  class RSpecRunner
+    def self.runner_name: () -> "rspec"
+    def self.discovery_command: (untyped) -> Array[untyped]
+  end
+  class MinitestRunner
+    def self.runner_name: () -> "minitest"
+  end
+end

data/sig/binpacker/timing.rbs

@@ -0,0 +1,17 @@
+module Binpacker
+  class Timing
+    def initialize: (untyped) -> void
+    DEFAULT_WEIGHT: Float
+    MAX_SAMPLES_PER_TEST: Integer
+    def calibrated?: () -> bool
+    def load_with_fallback: (untyped) -> Hash[untyped, Float]
+    def load_raw: () -> (Hash[[String, untyped], untyped] | {})
+    def load_per_file: () -> (Hash[String, untyped] | {})
+    def normalize_path: (untyped) -> String
+    def measured?: (file: untyped, name: untyped) -> bool
+    def compact!: () -> nil
+    def append_all: (untyped) -> nil
+    class Entry
+    end
+  end
+end

data/sig/binpacker/worker.rbs

@@ -0,0 +1,12 @@
+module Binpacker
+  class Worker
+    def initialize: (untyped, untyped, ?passthrough: untyped, ?quiet: untyped) -> void
+    def start: () -> Binpacker::Worker
+    def send_test: (untyped) -> nil
+    def batch_done: () -> nil
+    def wait_for_batch: () -> (nil | { timings: [], exit_code: 0 | 1, examples: untyped, passed: untyped } | { timings: [], exit_code: untyped, examples: untyped, passed: untyped })
+    def collect_results: () -> :finished
+    def timings: () -> Array[untyped]
+    def status: () -> (:crashed | :created | :error | :finished | :ready | :running)
+  end
+end

data/sig/binpacker/worker_queue.rbs

@@ -0,0 +1,8 @@
+module Binpacker
+  class WorkerQueue
+    def initialize: (untyped, ?untyped) -> void
+    def empty?: () -> (false | true)
+    def pop: () -> untyped
+    def total_weight: (Hash[untyped, Float]) -> Float
+  end
+end

data/skills/binpacker-improve/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: binpacker-improve
+description: Tune an already-configured binpacker project from real CI data — fetch recent run reports, analyze the gap between predicted and actual durations, and propose binpacker.yml adjustments. Use when binpacker is set up and running in CI and the user wants to reduce makespan, fix worker imbalance, or refresh stale timing data. Propose-only — never apply changes without confirmation.
+---
+
+# Binpacker Improve
+
+A recurring, **propose-only** workflow. It reads real CI data and proposes config changes; it never edits `binpacker.yml`, commits, or pushes without explicit user confirmation.
+
+Run `binpacker describe` first. If it recommends `binpacker-setup`, the project isn't configured yet — use that skill instead.
+
+## 1. Gather CI data
+
+Fetch recent run reports (see `docs/design/run-report-format.md` for the schema) from CI artifacts:
+
+```sh
+gh run list --workflow <ci-workflow> --limit 10
+gh run download <run-id> --name <report-artifact>
+```
+
+Collect several recent reports so you can see trends, not just one run. Each report holds `predicted_makespan`, `actual_makespan`, per-worker predicted/actual durations, `balance`, and the worst-drift Tests.
+
+## 2. Analyze
+
+Look for patterns across the reports:
+
+- **Persistent worker skew** — the same worker is consistently slowest → the partition or worker count is off.
+- **Predicted vs actual gap** — `actual_makespan` far above `predicted_makespan` → timing data is stale; the scheduler is planning against wrong Weights.
+- **Recurring high-drift files** — the same files top the `drift` list every run → their timing data is stale or they are outliers.
+- **Cache-miss frequency** — if CI logs show frequent timing-cache misses (e.g. after dependency bumps), the runtime cache isn't helping cold starts.
+
+## 3. Propose
+
+Present a concrete `binpacker.yml` diff and/or commands, with the evidence behind each change. Typical levers:
+
+- **`workers`** — raise/lower the `ci` worker count when actual makespan shows consistent under- or over-utilisation.
+- **`scheduler.algorithm`** — `lpt` ↔ `multifit`. Prefer `multifit` for tighter balance; only suggest `lpt` if `multifit` isn't helping.
+- **`scheduler.steal_enabled`** — enable when static balance is poor but runtime stealing would recover it.
+- **Re-calibrate** — when drift is high or timing is stale, recommend `binpacker calibrate --incremental` to refresh the drifting Tests.
+- **Commit a baseline** — when the cache misses often (dependency-bump churn) or timings have stabilised, recommend committing `binpacker.timings` as a durable baseline (cold-start floor). See `docs/adr/0005-two-tier-timing-persistence.md`.
+
+## 4. Confirm and apply
+
+- Show the diff. Explain the expected effect (e.g. "should cut max deviation from 6% toward <3%").
+- Apply only what the user approves. Committing a baseline or editing config both require confirmation.
+- If the user wants, open a PR with `gh`; otherwise leave the working tree changes for them to review.
+
+## Done when
+
+- The user has seen the predicted-vs-actual analysis with evidence.
+- A concrete, confirmed set of changes (or an explicit "no change needed") has been reached.
+- Any commit / PR was made only with confirmation.

data/skills/binpacker-setup/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: binpacker-setup
+description: Bring a project from zero to a working parallel test run with binpacker — detect the framework, generate config, calibrate timing data, validate a parallel run, and wire CI. Use when binpacker is installed but not yet set up (no binpacker.yml, or no timing data), or when the user asks to set up / configure / adopt binpacker.
+---
+
+# Binpacker Setup
+
+A one-time workflow that takes a project from zero to a working parallel test run. Run `binpacker describe` first — if it recommends `binpacker-improve`, the project is already set up and you want that skill instead.
+
+Assess state as you go and **ask the user at each decision point** rather than assuming. Do not run destructive or outward-facing steps (committing, opening a PR) without explicit confirmation.
+
+## 1. Detect
+
+- Confirm binpacker is installed: `binpacker --version`.
+- Run `binpacker describe` to read current state (config present? timing data? framework? CI wired?).
+- Determine the test framework (rspec / minitest) and the test glob. If `binpacker describe` reports one, trust it; otherwise inspect the repo.
+
+## 2. Config
+
+If `binpacker.yml` is absent, create it with `binpacker init` (it auto-detects the framework and writes `default` + `ci` profiles). Then review the generated file with the user and adjust:
+
+- `workers` — `auto` locally; a fixed number (e.g. `4`) for the `ci` profile matching the CI runner.
+- `test_pattern` / `test_exclude` — match the project's real layout.
+- `scheduler.algorithm` — `multifit` (default) unless there's a reason to use `lpt`.
+- `scheduler.steal_enabled` — `true` to let idle workers steal at runtime.
+- `report_file` (on the `ci` profile) — e.g. `binpacker-report.json`, so CI always emits a run report.
+
+## 3. Calibrate
+
+Seed timing data so the scheduler has real Weights:
+
+```sh
+binpacker calibrate
+```
+
+If some timing data already exists, measure only the gaps:
+
+```sh
+binpacker calibrate --incremental
+```
+
+## 4. Validate
+
+Run the suite in parallel and confirm it is green and balanced:
+
+```sh
+binpacker run
+```
+
+Check the summary's `Balance: max deviation`. A large deviation on the first run is expected before timing data accumulates; note it and move on.
+
+## 5. Wire CI
+
+Add (or extend) a CI workflow so the suite runs under binpacker. The workflow should:
+
+- Install binpacker (via the project's dependency manager or `gem install binpacker`).
+- Restore and save `binpacker.timings` with `actions/cache` (key includes OS + a hash of the test files). This is the runtime timing layer.
+- Run `binpacker run --profile ci` (which emits the run report via `report_file`).
+- Upload the run report with `actions/upload-artifact` so `binpacker-improve` can read it later.
+
+Propose the workflow YAML and let the user review it before writing.
+
+## 6. Handoff
+
+Only after the user confirms:
+
+- Create a branch, commit `binpacker.yml`, the CI workflow, and (if the user wants a committed baseline) `binpacker.timings`.
+- Open a PR with `gh`, summarising what was set up.
+- After CI runs, point the user at `binpacker-improve` to tune from real CI data.
+
+## Done when
+
+- `binpacker run` passes locally across workers.
+- `binpacker.yml` reflects the project's framework, layout, and CI worker count.
+- CI runs `binpacker run` and uploads a run report.
+- The user has confirmed any commit / PR.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: binpacker
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - megurine
@@ -9,8 +9,9 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A test runner wrapper that manages worker processes and distributes tests
-  among them using LPT scheduling with optional work-stealing.
+description: A test runner wrapper that models test distribution as an identical-machines
+  scheduling problem and assigns tests to worker processes using LPT scheduling, with
+  optional work-stealing.
 executables:
 - binpacker
 extensions: []
@@ -25,13 +26,32 @@ files:
 - lib/binpacker/config.rb
 - lib/binpacker/orchestrator.rb
 - lib/binpacker/progress.rb
+- lib/binpacker/project_state.rb
+- lib/binpacker/report.rb
 - lib/binpacker/scheduler.rb
+- lib/binpacker/skills.rb
 - lib/binpacker/test_discovery.rb
 - lib/binpacker/test_runner.rb
 - lib/binpacker/timing.rb
 - lib/binpacker/version.rb
 - lib/binpacker/worker.rb
 - lib/binpacker/worker_queue.rb
+- sig/binpacker/calibration.rbs
+- sig/binpacker/cli.rbs
+- sig/binpacker/config.rbs
+- sig/binpacker/orchestrator.rbs
+- sig/binpacker/progress.rbs
+- sig/binpacker/project_state.rbs
+- sig/binpacker/report.rbs
+- sig/binpacker/scheduler.rbs
+- sig/binpacker/skills.rbs
+- sig/binpacker/test_discovery.rbs
+- sig/binpacker/test_runner.rbs
+- sig/binpacker/timing.rbs
+- sig/binpacker/worker.rbs
+- sig/binpacker/worker_queue.rbs
+- skills/binpacker-improve/SKILL.md
+- skills/binpacker-setup/SKILL.md
 homepage: https://github.com/rigortype/binpacker
 licenses:
 - MPL-2.0
@@ -54,6 +74,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Minimize CI test-suite makespan by solving an identical-machines scheduling
-  problem
+summary: Reduce CI test-suite makespan via identical-machines scheduling
 test_files: []