rspec-turbo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e75805ec30e8c00d22ab5db21967fb3ddfdeb0ab8f6edabad1047f6b8d3d895
+  data.tar.gz: 3081d8c6f070131b441e4d00c368396b3e19cd48a2d79ed13b60a427a30c0033
+SHA512:
+  metadata.gz: 6f29717c3d1da16330b2019c4ff0cd7043f846ac0bc803716ddd86bdc338b382c41037c58ed68b9182a9fcad66ac0406d1ca994f76c3c3e2402e2533bff767b0
+  data.tar.gz: e66d30be4d8d35ba555cd4da8b5d950f19bf88fcdbd5df1c9feff10c14aab6956dbbd244d83cb82e3783264cfaedb58fd2ea80d05a7536f94691e684d808f78e

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [0.1.0] - 2026-06-12
+
+Initial extraction from the single-file `turbo.rb` runner into a gem.
+
+### Added
+- Parallel RSpec runner with dry-run-based example counting and LPT bin-packing.
+- Splitting of oversized spec files across workers by example ID.
+- Schema-fingerprinted test DB setup caching (Rails).
+- Live TTY dashboard and CI-friendly periodic progress mode.
+- Slowest folders/files report fed by the bundled `slow_profile` profiler,
+  enabled by default (disable with `RSPEC_TURBO_NO_PROFILE=1`) and safe outside
+  Rails (times examples without counting SQL when ActiveSupport is absent).
+- JUnit XML output (`JUNIT_DIR`) and SimpleCov coverage merging (`COVERAGE=1`).
+- Three entry points: the `rspec-turbo` binary plus a `spec:turbo` Rake task
+  (reachable as both `rake spec:turbo` and `rails spec:turbo`), registered in
+  Rails apps through a Railtie.
+- `coverage:merge` Rake task that collates per-worker SimpleCov result files
+  with `SimpleCov.collate`, emitting JSON on CI (`JSONFormatter`) and HTML
+  locally (`HTMLFormatter`); glob overridable via `RSPEC_TURBO_COVERAGE_GLOB`.
+
+### Fixed (versus the original script)
+- `DbSetup#show_log` referenced an undefined `w` variable on failure.
+- Missing `require "set"` for `FileDiscovery`.
+- A dead `Process.clock_gettime` call in `DbSetup#run!`.
+- `"\nTop \d"` string literal that was meant to be a regular expression.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 thadeu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,287 @@
+# ⚡ rspec-turbo
+
+[![Gem Version](https://img.shields.io/gem/v/rspec-turbo)](https://rubygems.org/gems/rspec-turbo)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-CC342D)](https://www.ruby-lang.org)
+[![Style](https://img.shields.io/badge/code_style-standard-brightgreen)](https://github.com/standardrb/standard)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE.txt)
+
+**Run your whole RSpec suite in parallel — with zero config.**
+
+`rspec-turbo` spreads your specs across every core, balancing the load by the
+**actual number of examples** (not file size, not a stale timing log) and even
+splitting a single oversized file across workers. One command, a live progress
+dashboard, and a report that tells you exactly which folders are slowing you
+down.
+
+```sh
+bundle add rspec-turbo --group test
+bundle exec rspec-turbo
+```
+
+That's it. No runtime logs to maintain, no grouping flags to tune.
+
+---
+
+## 🏎️ See it run
+
+```text
+====================================================================
+  RSpec Turbo - Parallel
+====================================================================
+
+  ✓ 8 DB(s) ready (0s)
+  ✓ 4210 examples · 312 files · 8 batches (~526 each) (3s)
+
+  ✓ worker/01  1m02s  PASS   requests/v1
+  ✓ worker/02  58s    PASS   models · services
+  ⠹ worker/03  ~520 ex  46s   jobs · mailers
+  ...
+
+  ▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░  2731/4210  65%
+
+====================================================================
+  RSpec Turbo Report
+====================================================================
+
+  Slowest folders  ↳ optimize these first
+
+  requests/v1                                     1m12s  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
+  models                                            48s  ▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░
+  services                                          31s  ▓▓▓▓▓▓▓▓░░░░░░░░░░░░░
+
+  ✓ All passed  ·  4210 examples  ·  8 workers  ·  wall 1m04s  sum 7m58s  7.4x
+```
+
+*(Illustrative output — your speedup scales with your cores.)*
+
+---
+
+## Why not just use `parallel_tests`?
+
+[`parallel_tests`](https://github.com/grosser/parallel_tests) is a great,
+battle-tested tool — and if you run Minitest, Cucumber, Test::Unit **and**
+RSpec, its multi-framework reach is exactly what you want.
+
+But if your project is **RSpec-only**, that generality costs you. `rspec-turbo`
+does one thing and tunes hard for it:
+
+| | `parallel_tests` | **`rspec-turbo`** |
+|---|---|---|
+| **Scope** | Multi-framework (RSpec, Minitest, Cucumber…) | RSpec only — focused and lean |
+| **Default balancing** | By file **size** (bytes) — a rough proxy for time | By **actual example count** from one `rspec --dry-run` |
+| **Best-case balancing** | `--group-by runtime`, needs a runtime log you record and keep fresh | Recomputed every run from the dry-run — **always current, nothing to maintain** |
+| **Unit of work** | A whole file — one giant `*_spec.rb` stalls a process | A file **or** example-ID slices — **splits big files across workers** |
+| **Config to balance well** | Generate + commit `tmp/parallel_runtime_rspec.log` | **None** — good distribution out of the box |
+| **Live output** | Per-process stdout, interleaved | Live TTY dashboard (spinner per worker + global bar) / clean CI progress |
+| **Final report** | Concatenated process outputs | **One consolidated report**: failures per worker, speedup, slowest folders/files |
+| **Slow-test insight** | DIY (`--profile` per process, aggregate yourself) | **Built in, on by default** — per-file time + SQL query counts, aggregated |
+| **Test-DB setup** | `rake parallel:prepare` (you decide when to re-run) | Automatic, **schema-fingerprint cached** — skipped when the schema hasn't changed |
+| **JUnit / coverage merge** | Extra wiring | Built in (`JUNIT_DIR`, `COVERAGE=1`) |
+
+### What that means in practice
+
+- **Better balance, no homework.** `parallel_tests`' file-size grouping puts a
+  500-line file with 3 slow examples in the same weight class as a 500-line file
+  with 80 fast ones. `rspec-turbo` counts the *examples* (via a fast dry-run) and
+  packs them with a longest-processing-time-first heuristic — and it does this
+  every run, so it never goes stale and there's no runtime log to commit.
+- **No single-file bottleneck.** When one mega `*_spec.rb` holds 20% of your
+  suite, a file-based splitter leaves one process grinding while the rest idle.
+  `rspec-turbo` slices that file by example ID across workers.
+- **Answers, not just speed.** Every run ends with a ranked "slowest folders /
+  files" report (and SQL query counts under Rails), so you know *what* to
+  optimize next — not just that the suite is slow.
+
+---
+
+## Install
+
+Add it to the `:test` group of your Gemfile:
+
+```ruby
+group :test do
+  gem "rspec-turbo"
+end
+```
+
+```sh
+bundle install
+```
+
+## Usage
+
+```sh
+bundle exec rspec-turbo                              # all of spec/
+bundle exec rspec-turbo spec/models lib              # specific folders
+bundle exec rspec-turbo spec/models/project_spec.rb  # a single file
+bundle exec rspec-turbo --exclude-pattern "spec/requests/**/*"
+bundle exec rspec-turbo --fail-fast spec/models
+
+RSPEC_TURBO_MAX=6 bundle exec rspec-turbo            # cap workers
+RSPEC_TURBO_FORCE_SETUP=1 bundle exec rspec-turbo    # recreate test DBs
+```
+
+Any RSpec flag you pass through (`--tag`, `--seed`, `--order`, …) is forwarded
+to every worker.
+
+### Three ways to launch it
+
+```sh
+bundle exec rspec-turbo       # the binary — full control (paths, flags)
+bundle exec rails spec:turbo  # the same task, via the Rails CLI
+bundle exec rake spec:turbo   # Rake task — runs the whole suite
+```
+
+In a Rails app the `spec:turbo` task is registered automatically (via a
+Railtie), and `rails spec:turbo` works because Rails routes unknown commands to
+Rake. The `rake`/`rails` forms run the **entire** suite — ideal for CI; for
+specific folders or RSpec flags, reach for the `rspec-turbo` binary.
+
+## How it works
+
+```
+parse argv → DbSetup → FileDiscovery → BatchPlanner → Executor (pool) → Report
+```
+
+1. **DbSetup** — spawns one `rails db:drop db:create db:schema:load db:seed` per
+   worker slot (each with its own `TEST_ENV_NUMBER`). Cached by a fingerprint of
+   `db/schema.rb` + `db/seeds.rb` and the worker count, so repeat runs skip it.
+2. **FileDiscovery** — globs `*_spec.rb`, applies `--exclude-pattern`.
+3. **BatchPlanner** — one `rspec --dry-run --format json` counts examples per
+   file, then bin-packs files into balanced batches (Longest-Processing-Time
+   first). Files heavier than a batch's fair share are split into example-ID
+   slices so no single file bottlenecks a worker.
+4. **Executor** — a fixed pool of slots; each finished slot is recycled until
+   the queue drains. Live dashboard on a TTY, periodic `[progress]` lines on CI.
+5. **Report** — failures, slowest folders/files, and a one-line summary with
+   wall time, summed CPU time and the resulting speedup.
+
+## Requirements
+
+- **Rails** — `DbSetup` uses `rails db:*`. (Non-Rails projects can still run if
+  the databases already exist; set `RSPEC_TURBO_FORCE_SETUP=0`, the default, and
+  the setup is skipped on a cache hit.)
+- **`rspec_junit_formatter`** — only when `JUNIT_DIR` is set.
+- **`simplecov` + `simplecov_json_formatter`** — only when `COVERAGE=1`
+  (see [Coverage](#coverage-optional) below).
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `RSPEC_TURBO_MAX` | nproc | Number of parallel workers |
+| `RSPEC_TURBO_LOG_DIR` | `tmp/rspec-turbo` | Where per-worker logs live |
+| `RSPEC_TURBO_FORCE_SETUP` | off | `1` recreates the test DBs even if cached |
+| `RSPEC_TURBO_PROGRESS_INTERVAL` | `30` | Seconds between CI progress lines |
+| `COVERAGE` | `0` | `1` merges SimpleCov results after the run |
+| `JUNIT_DIR` | — | Emit one JUnit XML per worker into this dir |
+| `CI` | — | Forces the plain (non-TTY) progress mode |
+
+### Slowest-files report (on by default)
+
+The "Slowest folders / Slowest files" section is fed by the bundled
+`slow_profile` hook, loaded into every worker. It is **on by default**: each
+worker times every example, and under Rails it also counts SQL queries via
+`ActiveSupport::Notifications`. Outside Rails it degrades gracefully — it just
+times examples and reports zero queries.
+
+Turn it off with the master kill switch:
+
+```sh
+RSPEC_TURBO_NO_PROFILE=1 bundle exec rspec-turbo
+```
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `RSPEC_TURBO_NO_PROFILE` | off | `1` disables profiling entirely (master kill switch) |
+| `RSPEC_PROFILE_THRESHOLD_TIME` | `0.2` | Seconds an example must exceed to make the "slow examples" list |
+| `RSPEC_PROFILE_THRESHOLD_QUERIES` | `30` | Query count an example must exceed to make that list |
+| `RSPEC_PROFILE_GROUP_BY` | — | `1`/`auto`, a base path, or a comma list of folders to bucket by |
+
+### Coverage (optional)
+
+With `COVERAGE=1`, each worker records coverage under its own `TEST_ENV_NUMBER`
+and rspec-turbo merges the results into a single report when the run ends, via
+the bundled `coverage:merge` task — **JSON on CI**
+(`SimpleCov::Formatter::JSONFormatter`), **HTML locally**
+(`SimpleCov::Formatter::HTMLFormatter`).
+
+1. Add the formatters to your Gemfile:
+
+   ```ruby
+   group :test do
+     gem "simplecov", require: false
+     gem "simplecov_json_formatter", require: false
+   end
+   ```
+
+2. Have each worker write its **own** result file (so parallel workers don't
+   clobber each other), keyed by `TEST_ENV_NUMBER` — at the very top of
+   `spec/spec_helper.rb`, before your app is required:
+
+   ```ruby
+   if ENV["COVERAGE"] == "1"
+     require "simplecov"
+     SimpleCov.command_name "worker_#{ENV["TEST_ENV_NUMBER"]}"
+     SimpleCov.coverage_dir "coverage/#{ENV["TEST_ENV_NUMBER"]}"
+     SimpleCov.start "rails"
+   end
+   ```
+
+3. Run it:
+
+   ```sh
+   COVERAGE=1 bundle exec rspec-turbo
+   ```
+
+The merge collates `coverage/**/.resultset.json` (override with
+`RSPEC_TURBO_COVERAGE_GLOB`) and writes the combined report to `coverage/`. You
+can also run it on its own: `bundle exec rake coverage:merge`.
+
+## Architecture
+
+```
+lib/rspec_turbo/
+├── config.rb            # env-driven settings + derived log paths
+├── terminal.rb          # colour, duration formatting, spinner, separators
+├── options.rb           # split ARGV into rspec flags vs folders
+├── db_setup.rb          # cached parallel test-DB creation (Rails)
+├── file_discovery.rb    # find + filter *_spec.rb files
+├── batch_planner.rb     # dry-run counting + LPT bin-packing
+├── display.rb           # live spinner + final report + log parsing
+├── worker.rb            # spawn one rspec process per batch
+├── executor.rb          # the slot pool + TTY/CI run loops
+├── runner.rb            # top-level orchestration
+├── progress_reporter.rb # formatter injected into workers (progress bar)
+├── slow_profile.rb      # profiler injected into workers (slow report)
+├── railtie.rb           # registers the spec:turbo task in Rails apps
+└── tasks.rake           # the rake spec:turbo / rails spec:turbo task
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake          # runs the specs + Standard
+bundle exec rspec         # specs only
+bundle exec standardrb    # lint
+bundle exec standardrb --fix
+```
+
+Style is enforced by [Standard Ruby](https://github.com/standardrb/standard).
+The `.rubocop.yml` simply loads Standard's ruleset so editors and tooling that
+speak RuboCop pick up the same rules; the canonical runner is `standardrb`.
+VS Code is pre-wired (`.vscode/settings.json`) to format on save with Standard
+via the Ruby LSP extension.
+
+## Contributing
+
+Issues and pull requests are welcome. Run `bundle exec rake` before opening a
+PR — it must be green (specs + Standard).
+
+**If `rspec-turbo` shaves minutes off your CI, drop a ⭐ on the repo** — it helps
+other RSpec teams find it.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/exe/rspec-turbo

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rspec_turbo"
+
+RSpecTurbo::Runner.new(ARGV).run

data/lib/rspec-turbo.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Alias so `require "rspec-turbo"` (matching the gem name) works too.
+require_relative "rspec_turbo"

data/lib/rspec_turbo/batch_planner.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RSpecTurbo
+  # Runs `rspec --dry-run --format json` to count examples per file, then packs
+  # the files into N balanced batches using the Longest-Processing-Time first
+  # (LPT) greedy heuristic. Files heavier than a single batch's fair share are
+  # split into slices of individual example IDs so one huge file can't bottle-
+  # neck a worker.
+  #
+  # If the dry-run fails for any reason it falls back to equal-weight packing.
+  class BatchPlanner
+    attr_reader :counts, :batches, :pending_count, :dry_run_elapsed
+
+    def initialize(files, num_workers:, rspec_options: [])
+      @files = files
+      @n = num_workers
+      @rspec_options = rspec_options
+      @counts = {}
+      @batches = []
+      @pending_count = 0
+      @dry_run_elapsed = 0
+    end
+
+    def plan!
+      result = dry_run
+      @counts = result[:counts]
+      @pending_count = result[:pending_count]
+      units = build_units(@files, @counts, result[:ids])
+      @batches = bin_pack(units)
+
+      self
+    end
+
+    def example_count(units) = units.sum { |unit| unit_weight(unit) }
+
+    private
+
+    def dry_run
+      return empty_result if @files.empty?
+
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      raw = capture_dry_run
+      @dry_run_elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0).round
+
+      json_start = raw.index("{")
+      raise "No JSON in dry-run output" unless json_start
+
+      parse_examples(JSON.parse(raw[json_start..]))
+    rescue => e
+      warn "  ⚠ dry-run failed (#{e.message}) — using equal-weight distribution"
+      log_dry_run_error
+
+      empty_result
+    end
+
+    def capture_dry_run
+      File.open(Config.dry_run_log, "w") do |err_file|
+        IO.popen(
+          # COVERAGE=0 keeps SimpleCov from contaminating the JSON on stdout.
+          [{"COVERAGE" => "0", "TEST_ENV_NUMBER" => "1"},
+            "bundle", "exec", "rspec", "--dry-run", "--format", "json",
+            *@rspec_options, *@files.map { |f| "spec/#{f}" }],
+          err: err_file, &:read
+        )
+      end
+    end
+
+    def parse_examples(parsed)
+      counts = Hash.new(0)
+      ids = Hash.new { |hash, key| hash[key] = [] }
+
+      parsed["examples"].each do |example|
+        file = example["file_path"].delete_prefix("./spec/")
+        counts[file] += 1
+        ids[file] << example["id"]
+      end
+
+      {counts: counts, ids: ids, pending_count: parsed.dig("summary", "pending_count").to_i}
+    end
+
+    def empty_result = {counts: {}, ids: {}, pending_count: 0}
+
+    def log_dry_run_error
+      return unless File.exist?(Config.dry_run_log)
+
+      last_err = File.readlines(Config.dry_run_log).last(10).join.strip
+      warn "  Dry-run stderr:\n#{last_err}" unless last_err.empty?
+    end
+
+    def unit_weight(unit) = unit.is_a?(Array) ? unit.size : (@counts[unit] || 1)
+
+    # A "unit" is either a whole file (a String) or a slice of example IDs
+    # (an Array) carved out of a file too heavy to fit in one batch.
+    def build_units(files, counts, ids)
+      total = files.sum { |f| counts[f] || 1 }
+      threshold = [(total.to_f / @n).ceil, 1].max
+
+      files.flat_map do |file|
+        file_ids = ids[file].to_a
+
+        if (counts[file] || 1) > threshold && file_ids.size > 1
+          file_ids.each_slice(threshold).to_a
+        else
+          [file]
+        end
+      end
+    end
+
+    def bin_pack(units)
+      n = [@n, units.size].min
+
+      return [units] if n <= 1
+
+      buckets = Array.new(n) { [0, []] }
+
+      units.sort_by { |unit| -unit_weight(unit) }.each do |unit|
+        bucket = buckets.min_by { |total, _| total }
+        bucket[1] << unit
+        bucket[0] += unit_weight(unit)
+      end
+
+      buckets.reject { |_, packed| packed.empty? }.map { |_, packed| packed }
+    end
+  end
+end

data/lib/rspec_turbo/config.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module RSpecTurbo
+  # Central place for environment-driven settings and derived log paths.
+  #
+  # All tuning happens through environment variables so the runner stays a
+  # single zero-config binary:
+  #
+  #   RSPEC_TURBO_MAX               number of parallel workers (default: nproc)
+  #   RSPEC_TURBO_LOG_DIR           where per-worker logs live
+  #   RSPEC_TURBO_FORCE_SETUP=1     recreate test DBs even if cached
+  #   RSPEC_TURBO_PROGRESS_INTERVAL seconds between CI progress lines
+  #   COVERAGE=1                    merge SimpleCov results after the run
+  #   JUNIT_DIR=path                emit JUnit XML per worker into this dir
+  #
+  # Slow-test profiling is opt-in and feeds the "Slowest folders/files" report
+  # (see slow_profile.rb): RSPEC_PROFILE_SLOW=1, RSPEC_PROFILE_GROUP_BY, etc.
+  module Config
+    module_function
+
+    TTY = $stdout.tty? && !ENV["CI"]
+
+    def tty? = TTY
+
+    def workers
+      Integer(ENV.fetch("RSPEC_TURBO_MAX") { ENV.fetch("RSPEC_PARALLEL_MAX", Etc.nprocessors) })
+    end
+
+    def force_setup?
+      flag = ENV["RSPEC_TURBO_FORCE_SETUP"] || ENV["RSPEC_PARALLEL_FORCE_SETUP"]
+
+      %w[1 true yes].include?(flag.to_s.downcase)
+    end
+
+    def progress_interval = Integer(ENV.fetch("RSPEC_TURBO_PROGRESS_INTERVAL", "30"))
+
+    def coverage? = %w[1 true].include?(ENV.fetch("COVERAGE", "0").downcase)
+
+    def junit_dir = ENV["JUNIT_DIR"]
+
+    # Slow-test profiling is on by default; RSPEC_TURBO_NO_PROFILE=1 is the
+    # master kill switch. See slow_profile.rb and Worker.profile_env.
+    def profile? = !%w[1 true yes].include?(ENV["RSPEC_TURBO_NO_PROFILE"].to_s.downcase)
+
+    # ── Derived paths ──────────────────────────────────────────────────────
+
+    def log_dir = ENV.fetch("RSPEC_TURBO_LOG_DIR") { ENV.fetch("RSPEC_LOG_DIR", "tmp/rspec-turbo") }
+
+    def setup_marker_dir = File.join(log_dir, "setup")
+
+    def log_path(label) = File.join(log_dir, "#{label.tr("/", "_")}.log")
+
+    def progress_path(slot) = File.join(log_dir, "progress_#{slot}.txt")
+
+    def setup_log_path(slot) = File.join(log_dir, "setup_slot#{slot}.log")
+
+    def dry_run_log = File.join(log_dir, "dry_run_stderr.log")
+
+    def coverage_merge_log = File.join(log_dir, "coverage_merge.log")
+  end
+end

data/lib/rspec_turbo/db_setup.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+
+module RSpecTurbo
+  # Ensures N test databases exist, one per worker slot, by spawning a Rails
+  # db setup process per slot (each with its own TEST_ENV_NUMBER).
+  #
+  # The result is cached by a fingerprint of db/schema.rb + db/seeds.rb plus
+  # the worker count, so repeat runs skip setup entirely. Set
+  # RSPEC_TURBO_FORCE_SETUP=1 to force recreation.
+  class DbSetup
+    FINGERPRINT_FILES = ["db/schema.rb", "db/seeds.rb"].freeze
+    SETUP_COMMAND = ["bundle", "exec", "rails", "db:drop", "db:create", "db:schema:load", "db:seed"].freeze
+
+    def initialize(num_workers, force: Config.force_setup?)
+      @n = num_workers
+      @force = force
+    end
+
+    def run!
+      return true if !@force && cached?
+
+      FileUtils.mkdir_p(Config.log_dir)
+      failed = wait_all(spawn_all)
+
+      return write_marker && true if failed.empty?
+
+      failed.each { |worker| show_log(worker) }
+      false
+    end
+
+    def cached? = File.exist?(marker_path)
+
+    private
+
+    def spawn_all
+      (1..@n).map do |slot|
+        log = Config.setup_log_path(slot)
+        pid = Process.spawn(
+          {"TEST_ENV_NUMBER" => slot.to_s, "RAILS_ENV" => "test"},
+          *SETUP_COMMAND,
+          out: log, err: [:child, :out]
+        )
+
+        {pid: pid, slot: slot, log: log}
+      end
+    end
+
+    def wait_all(workers)
+      workers.filter_map do |worker|
+        _, status = Process.waitpid2(worker[:pid])
+
+        status.success? ? nil : worker
+      end
+    end
+
+    def show_log(worker)
+      return unless File.exist?(worker[:log])
+
+      warn "\n── slot #{worker[:slot]} output ──"
+      warn File.read(worker[:log]).lines.last(15).join
+    end
+
+    def write_marker
+      FileUtils.mkdir_p(Config.setup_marker_dir)
+      FileUtils.touch(marker_path)
+    end
+
+    def marker_path
+      File.join(Config.setup_marker_dir, "slots-#{@n}-schema-#{schema_fingerprint}")
+    end
+
+    def schema_fingerprint
+      digest = Digest::SHA256.new
+
+      FINGERPRINT_FILES.each do |path|
+        digest.update(path)
+        digest.update(File.exist?(path) ? File.read(path) : "")
+      end
+
+      digest.hexdigest[0, 12]
+    end
+  end
+end