specbandit 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e9239010371ceb4ec5c34c959413de19ecb62d31004010c4cccd74a7f558f96
-  data.tar.gz: 740235b2c5e7174b0b0b5aba2f0da1632db3b789a9deca1800ee3f61568bf0be
+  metadata.gz: bde3099f7c42b0d8c294590f4523aaaddee09f4057c42d368c4f5cc4f6855a58
+  data.tar.gz: a8c5648df12c5f5103937f89fd9869c19a4d94aae0124ae116467438346434c9
 SHA512:
-  metadata.gz: 7446e60aee84c46d4ea8e1c5c59307c7bd9593b2ba082b9f30dc4835e531b5343291cd1f42be8015f48c808faf8f65f93cd43610a799133ebffda4723b7e1a92
-  data.tar.gz: 6a698f1ccb2e6fd7840171f97ad1ffaad5b2f1e00a66349e6bcc4ea79b34768c821516bd3552ef82188c6d8cb6abc2b1218859c7981850e39ac52950b81444df
+  metadata.gz: e87c4f5952982592627f71b22c2b433289cc28a5a94bd6138d67e411fce4d4609708da129fd649d4d2675c2c082990872642f359527edb6100906cf68bce4158
+  data.tar.gz: ffc87b7b36a8249f62d104545aac53ab192d7f815711fd98e179441dcb20e2742e15ae6e6c95cbebb4b37f783c2d3f7034bf2fa8325b77083e34ae4e855d3794

data/README.md

@@ -4,13 +4,13 @@
 
 # specbandit
 
-Distributed RSpec runner using Redis as a work queue. One process pushes spec file paths to a Redis list; multiple CI runners atomically steal batches and execute them in-process via `RSpec::Core::Runner`.
+Distributed test runner using Redis as a work queue. One process pushes test file paths to a Redis list; multiple CI runners atomically steal batches and execute them via a pluggable adapter.
 
 ```
 CI Job 1 (push):    RPUSH key f1 f2 f3 ... fN  -->  [Redis List]
-CI Job 2 (worker):  LPOP key 5  <--  [Redis List]  -->  RSpec
-CI Job 3 (worker):  LPOP key 5  <--  [Redis List]  -->  RSpec
-CI Job N (worker):  LPOP key 5  <--  [Redis List]  -->  RSpec
+CI Job 2 (worker):  LPOP key 5  <--  [Redis List]  -->  adapter (cli/rspec)
+CI Job 3 (worker):  LPOP key 5  <--  [Redis List]  -->  adapter (cli/rspec)
+CI Job N (worker):  LPOP key 5  <--  [Redis List]  -->  adapter (cli/rspec)
 ```
 
 `LPOP` with a count argument (Redis 6.2+) is atomic -- multiple workers calling it concurrently will never receive the same file.
@@ -31,11 +31,70 @@ gem install specbandit
 
 **Requirements**: Ruby >= 3.0, Redis >= 6.2
 
+## Adapters
+
+specbandit v0.7.0 introduces a pluggable adapter architecture. Two adapters ship out of the box:
+
+| Adapter | Default? | How it runs | Best for |
+|---------|----------|-------------|----------|
+| `cli` | Yes | Spawns a shell command per batch | Any test runner (Jest, pytest, Go test, etc.) |
+| `rspec` | No | Runs `RSpec::Core::Runner` in-process | RSpec (fastest, richest reporting) |
+
+### CLI adapter (default)
+
+The CLI adapter spawns a shell command for each batch, appending file paths as arguments. It works with any test runner.
+
+```bash
+# Run RSpec via CLI adapter
+specbandit work --key KEY --command "bundle exec rspec"
+
+# Run with extra options
+specbandit work --key KEY --command "bundle exec rspec" --command-opts "--format documentation"
+
+# Run Jest
+specbandit work --key KEY --command "npx jest"
+
+# Forward args after -- (merged with --command-opts)
+specbandit work --key KEY --command "bundle exec rspec" -- --format documentation
+```
+
+### RSpec adapter
+
+The RSpec adapter runs `RSpec::Core::Runner.run` in-process with `RSpec.clear_examples` between batches. No subprocess forking overhead. Provides rich reporting with per-example details, failure messages, and JSON accumulation.
+
+```bash
+specbandit work --key KEY --adapter rspec
+
+# With RSpec options
+specbandit work --key KEY --adapter rspec --rspec-opts "--format documentation"
+
+# JSON output for CI artifact collection
+specbandit work --key KEY --adapter rspec -- --format json --out results.json
+```
+
+### Migration from v0.6.x
+
+In v0.6.x, RSpec was the only execution method and was always used implicitly. In v0.7.0, the default adapter changed to `cli`. To keep the previous behavior, add `--adapter rspec`:
+
+```bash
+# v0.6.x
+specbandit work --key KEY
+
+# v0.7.0 equivalent
+specbandit work --key KEY --adapter rspec
+```
+
+Or set the environment variable:
+
+```bash
+export SPECBANDIT_ADAPTER=rspec
+```
+
 ## Usage
 
-### 1. Push spec files to Redis
+### 1. Push test files to Redis
 
-A single CI job enqueues all spec file paths before workers start.
+A single CI job enqueues all test file paths before workers start.
 
 ```bash
 # Via glob pattern (resolved in Ruby, avoids shell ARG_MAX limits)
@@ -55,12 +114,16 @@ File input priority: **stdin > --pattern > direct args**.
 Each CI runner steals batches and runs them. Start as many runners as you want -- they'll divide the work automatically.
 
 ```bash
-specbandit work --key pr-123-run-456 --batch-size 10
+# Using CLI adapter (default) -- works with any test runner
+specbandit work --key pr-123-run-456 --command "bundle exec rspec" --batch-size 10
+
+# Using RSpec adapter -- in-process, fastest for RSpec
+specbandit work --key pr-123-run-456 --adapter rspec --batch-size 10
 ```
 
 Each worker loops:
 1. `LPOP` N file paths from Redis (atomic)
-2. Run them in-process via `RSpec::Core::Runner`
+2. Execute them via the configured adapter
 3. Repeat until the queue is empty
 4. Exit 0 if all batches passed, 1 if any failed
 
@@ -75,13 +138,20 @@ specbandit push [options] [files...]
   --redis-url URL        Redis URL (default: redis://localhost:6379)
   --key-ttl SECONDS      TTL for the Redis key (default: 21600 / 6 hours)
 
-specbandit work [options]
+specbandit work [options] [-- extra-opts...]
   --key KEY              Redis queue key (required)
+  --adapter TYPE         Adapter type: 'cli' (default) or 'rspec'
+  --command CMD          Command to run (required for cli adapter)
+  --command-opts OPTS    Extra options forwarded to the command (space-separated)
+  --rspec-opts OPTS      Extra options forwarded to RSpec (for rspec adapter)
   --batch-size N         Files per batch (default: 5)
   --redis-url URL        Redis URL (default: redis://localhost:6379)
-  --rspec-opts OPTS      Extra options forwarded to RSpec
   --key-rerun KEY        Per-runner rerun key for re-run support (see below)
   --key-rerun-ttl SECS   TTL for rerun key (default: 604800 / 1 week)
+  --verbose              Show per-batch file list and full command output
+
+Arguments after -- are forwarded to the adapter. They are merged with
+--command-opts (cli adapter) or --rspec-opts (rspec adapter).
 ```
 
 ### Environment variables
@@ -92,11 +162,15 @@ All CLI options can be set via environment variables:
 |---|---|---|
 | `SPECBANDIT_KEY` | Redis queue key | _(required)_ |
 | `SPECBANDIT_REDIS_URL` | Redis connection URL | `redis://localhost:6379` |
+| `SPECBANDIT_ADAPTER` | Adapter type (`cli` or `rspec`) | `cli` |
+| `SPECBANDIT_COMMAND` | Command to run (cli adapter) | _(none)_ |
+| `SPECBANDIT_COMMAND_OPTS` | Space-separated command options | _(none)_ |
 | `SPECBANDIT_BATCH_SIZE` | Files per steal | `5` |
 | `SPECBANDIT_KEY_TTL` | Key expiry in seconds | `21600` (6 hours) |
-| `SPECBANDIT_RSPEC_OPTS` | Space-separated RSpec options | _(none)_ |
+| `SPECBANDIT_RSPEC_OPTS` | Space-separated RSpec options (rspec adapter) | _(none)_ |
 | `SPECBANDIT_KEY_RERUN` | Per-runner rerun key | _(none)_ |
 | `SPECBANDIT_KEY_RERUN_TTL` | Rerun key expiry in seconds | `604800` (1 week) |
+| `SPECBANDIT_VERBOSE` | Enable verbose output (`1`/`true`/`yes`) | _(false)_ |
 
 CLI flags take precedence over environment variables.
 
@@ -112,20 +186,68 @@ Specbandit.configure do |c|
   c.key_ttl        = 7200 # 2 hours (default: 21600 / 6 hours)
   c.key_rerun      = "pr-123-run-456-runner-3"
   c.key_rerun_ttl  = 604_800 # 1 week (default)
-  c.rspec_opts     = ["--format", "documentation"]
 end
 
 # Push
 publisher = Specbandit::Publisher.new
 publisher.publish(pattern: "spec/**/*_spec.rb")
 
-# Work (will auto-detect steal/record/replay mode based on key_rerun state)
-worker = Specbandit::Worker.new
+# Work with CLI adapter (default)
+adapter = Specbandit::CliAdapter.new(
+  command: "bundle exec rspec",
+  command_opts: ["--format", "documentation"]
+)
+worker = Specbandit::Worker.new(adapter: adapter)
+exit_code = worker.run
+
+# Work with RSpec adapter (in-process)
+adapter = Specbandit::RspecAdapter.new(
+  rspec_opts: ["--format", "documentation"]
+)
+worker = Specbandit::Worker.new(adapter: adapter)
+exit_code = worker.run
+
+# Legacy: passing rspec_opts directly still works (auto-creates RspecAdapter)
+worker = Specbandit::Worker.new(rspec_opts: ["--format", "documentation"])
 exit_code = worker.run
 ```
 
 ## Example: GitHub Actions (basic)
 
+### Using RSpec adapter (in-process)
+
+```yaml
+jobs:
+  push-specs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: bundle install
+      - run: |
+          specbandit push \
+            --key "pr-${{ github.event.number }}-${{ github.run_id }}" \
+            --redis-url "${{ secrets.REDIS_URL }}" \
+            --pattern 'spec/**/*_spec.rb'
+
+  run-specs:
+    runs-on: ubuntu-latest
+    needs: push-specs
+    strategy:
+      matrix:
+        runner: [1, 2, 3, 4]
+    steps:
+      - uses: actions/checkout@v4
+      - run: bundle install
+      - run: |
+          specbandit work \
+            --key "pr-${{ github.event.number }}-${{ github.run_id }}" \
+            --redis-url "${{ secrets.REDIS_URL }}" \
+            --adapter rspec \
+            --batch-size 10
+```
+
+### Using CLI adapter (any test runner)
+
 ```yaml
 jobs:
   push-specs:
@@ -152,6 +274,7 @@ jobs:
           specbandit work \
             --key "pr-${{ github.event.number }}-${{ github.run_id }}" \
             --redis-url "${{ secrets.REDIS_URL }}" \
+            --command "bundle exec rspec" \
             --batch-size 10
 ```
 
@@ -250,6 +373,7 @@ jobs:
             --key "pr-${{ github.event.number }}-${{ github.run_id }}" \
             --key-rerun "pr-${{ github.event.number }}-${{ github.run_id }}-runner-${{ matrix.runner }}" \
             --redis-url "${{ secrets.REDIS_URL }}" \
+            --adapter rspec \
             --batch-size 10
 ```
 
@@ -297,7 +421,9 @@ specbandit work \
 - **Steal** uses `LPOP key count` (Redis 6.2+), which atomically pops up to N elements. No Lua scripts, no locks, no race conditions.
 - **Record** (when `--key-rerun` is set): after each steal, the batch is also `RPUSH`ed to the per-runner rerun key with its own TTL (default: 1 week).
 - **Replay** (when `--key-rerun` has data): reads all files from the rerun key via `LRANGE` (non-destructive), splits into batches, and runs them locally. The shared queue is never touched.
-- **Run** uses `RSpec::Core::Runner.run` in-process with `RSpec.clear_examples` between batches to reset example state while preserving configuration. No subprocess forking overhead.
+- **Run** delegates to the configured adapter:
+  - **CLI adapter**: spawns a shell command per batch via `Open3`, appending file paths as arguments. Works with any test runner.
+  - **RSpec adapter**: uses `RSpec::Core::Runner.run` in-process with `RSpec.clear_examples` between batches to reset example state while preserving configuration. No subprocess forking overhead.
 - **Exit code** is 0 if every batch passed (or the queue was already empty), 1 if any batch had failures.
 
 ## Development

data/lib/specbandit/adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Specbandit
+  # Result of running a single batch of test files.
+  # Adapters return instances of this (or a subclass) from #run_batch.
+  BatchResult = Struct.new(:batch_num, :files, :exit_code, :duration, keyword_init: true)
+
+  # Adapter interface for executing test batches.
+  #
+  # specbandit supports pluggable execution strategies:
+  # - CliAdapter: spawns a shell command for each batch (works with any test runner)
+  # - RspecAdapter: runs RSpec programmatically in-process (maximum performance)
+  #
+  # To implement a custom adapter, define a class that responds to:
+  #   #setup           - One-time initialization before any batches run
+  #   #run_batch(files, batch_num) - Execute a batch, return a BatchResult
+  #   #teardown        - Cleanup after all batches are done
+  module Adapter
+  end
+end

data/lib/specbandit/cli.rb

@@ -85,12 +85,24 @@ module Specbandit
 
     def run_work
       parser = OptionParser.new do |opts|
-        opts.banner = 'Usage: specbandit work [options]'
+        opts.banner = 'Usage: specbandit work [options] [-- extra-opts...]'
 
         opts.on('--key KEY', 'Redis queue key (required, or set SPECBANDIT_KEY)') do |v|
           Specbandit.configuration.key = v
         end
 
+        opts.on('--adapter TYPE', 'Adapter type: cli (default) or rspec') do |v|
+          Specbandit.configuration.adapter = v
+        end
+
+        opts.on('--command CMD', 'Command to run with file paths (required for cli adapter)') do |v|
+          Specbandit.configuration.command = v
+        end
+
+        opts.on('--command-opts OPTS', 'Extra options forwarded to the command (space-separated)') do |v|
+          Specbandit.configuration.command_opts = v.split
+        end
+
         opts.on('--batch-size N', Integer, 'Number of files to steal per batch (default: 5)') do |v|
           Specbandit.configuration.batch_size = v
         end
@@ -99,7 +111,7 @@ module Specbandit
           Specbandit.configuration.redis_url = v
         end
 
-        opts.on('--rspec-opts OPTS', 'Extra options to pass to RSpec (space-separated)') do |v|
+        opts.on('--rspec-opts OPTS', 'Extra options to pass to RSpec (for rspec adapter, space-separated)') do |v|
           Specbandit.configuration.rspec_opts = v.split
         end
 
@@ -111,7 +123,7 @@ module Specbandit
           Specbandit.configuration.key_rerun_ttl = v
         end
 
-        opts.on('--verbose', 'Show per-batch file list and full RSpec output (default: quiet)') do
+        opts.on('--verbose', 'Show per-batch file list and full command output (default: quiet)') do
           Specbandit.configuration.verbose = true
         end
 
@@ -122,46 +134,91 @@ module Specbandit
       end
 
       parser.parse!(argv)
-      Specbandit.configuration.validate!
 
-      # Remaining args after `--` are treated as extra rspec options.
-      # This allows: specbandit work --key KEY -- --format json --out results.json
-      Specbandit.configuration.rspec_opts = argv if argv.any?
+      # Remaining args after `--` are forwarded to the adapter.
+      # They are merged with --command-opts or --rspec-opts depending on the adapter.
+      extra_opts = argv.any? ? argv : []
+
+      config = Specbandit.configuration
+      adapter = build_adapter(config, extra_opts)
 
-      worker = Worker.new
+      config.validate!
+
+      worker = Worker.new(adapter: adapter)
       worker.run
     end
 
+    # Build the appropriate adapter based on configuration.
+    #
+    # --adapter rspec  -> RspecAdapter (runs RSpec programmatically in-process)
+    # --adapter cli    -> CliAdapter (default, spawns shell commands)
+    # (no --adapter)   -> CliAdapter (backward compatible with specbanditjs)
+    def build_adapter(config, extra_opts)
+      adapter_type = config.adapter.downcase
+
+      case adapter_type
+      when 'rspec'
+        rspec_opts = config.rspec_opts + extra_opts
+        RspecAdapter.new(
+          rspec_opts: rspec_opts,
+          verbose: config.verbose,
+          output: $stdout
+        )
+      when 'cli'
+        unless config.command
+          raise Error, 'command is required for CLI adapter (set via --command or SPECBANDIT_COMMAND)'
+        end
+
+        command_opts = config.command_opts + extra_opts
+        CliAdapter.new(
+          command: config.command,
+          command_opts: command_opts,
+          verbose: config.verbose,
+          output: $stdout
+        )
+      else
+        raise Error, "Unknown adapter: #{adapter_type}. Supported: cli, rspec"
+      end
+    end
+
     def print_usage
       puts <<~USAGE
-        specbandit v#{VERSION} - Distributed RSpec runner using Redis
+        specbandit v#{VERSION} - Distributed test runner using Redis
 
         Usage:
-          specbandit push [options] [files...]    Enqueue spec files into Redis
-          specbandit work [options]               Steal and run spec file batches
+          specbandit push [options] [files...]           Enqueue test files into Redis
+          specbandit work [options] [-- extra-opts...]   Steal and run test file batches
 
         Push options:
-          --key KEY            Redis queue key (required, or set SPECBANDIT_KEY)
-          --pattern PATTERN    Glob pattern for file discovery (e.g. 'spec/**/*_spec.rb')
-          --redis-url URL      Redis URL (default: redis://localhost:6379)
-          --key-ttl SECONDS    TTL for the Redis key (default: 21600 / 6 hours)
+          --key KEY              Redis queue key (required, or set SPECBANDIT_KEY)
+          --pattern PATTERN      Glob pattern for file discovery (e.g. 'spec/**/*_spec.rb')
+          --redis-url URL        Redis URL (default: redis://localhost:6379)
+          --key-ttl SECONDS      TTL for the Redis key (default: 21600 / 6 hours)
 
         Work options:
-          --key KEY            Redis queue key (required, or set SPECBANDIT_KEY)
-          --batch-size N       Files per batch (default: 5, or set SPECBANDIT_BATCH_SIZE)
-          --redis-url URL      Redis URL (default: redis://localhost:6379)
-          --rspec-opts OPTS    Extra options forwarded to RSpec
-          --key-rerun KEY      Per-runner rerun key for re-run support
-          --key-rerun-ttl N    TTL for rerun key (default: 604800 / 1 week)
-          --verbose            Show per-batch file list and full RSpec output
-          -- OPTS...           Pass remaining args as RSpec options (alternative to --rspec-opts)
+          --key KEY              Redis queue key (required, or set SPECBANDIT_KEY)
+          --adapter TYPE         Adapter type: 'cli' (default) or 'rspec'
+          --command CMD          Command to run with file paths (required for cli adapter)
+          --command-opts OPTS    Extra options forwarded to the command (space-separated)
+          --rspec-opts OPTS      Extra options forwarded to RSpec (for rspec adapter)
+          --batch-size N         Files per batch (default: 5, or set SPECBANDIT_BATCH_SIZE)
+          --redis-url URL        Redis URL (default: redis://localhost:6379)
+          --key-rerun KEY        Per-runner rerun key for re-run support
+          --key-rerun-ttl N      TTL for rerun key (default: 604800 / 1 week)
+          --verbose              Show per-batch file list and full command output
+
+          Arguments after -- are forwarded to the adapter (rspec opts, command opts, etc.).
+          They are merged with --command-opts or --rspec-opts if both are provided.
 
         Environment variables:
           SPECBANDIT_KEY              Queue key
           SPECBANDIT_REDIS_URL        Redis URL
+          SPECBANDIT_ADAPTER          Adapter type (cli/rspec)
+          SPECBANDIT_COMMAND          Command to run (cli adapter)
+          SPECBANDIT_COMMAND_OPTS     Command options (space-separated)
           SPECBANDIT_BATCH_SIZE       Batch size
           SPECBANDIT_KEY_TTL          Key TTL in seconds (default: 21600)
-          SPECBANDIT_RSPEC_OPTS       RSpec options
+          SPECBANDIT_RSPEC_OPTS       RSpec options (rspec adapter)
           SPECBANDIT_KEY_RERUN        Per-runner rerun key
           SPECBANDIT_KEY_RERUN_TTL    Rerun key TTL in seconds (default: 604800)
           SPECBANDIT_VERBOSE          Enable verbose output (1/true/yes)
@@ -170,6 +227,12 @@ module Specbandit
           1. stdin (piped)     echo "spec/a_spec.rb" | specbandit push --key KEY
           2. --pattern         specbandit push --key KEY --pattern 'spec/**/*_spec.rb'
           3. direct args       specbandit push --key KEY spec/a_spec.rb spec/b_spec.rb
+
+        Adapters:
+          cli   (default) Spawns a shell command for each batch. Works with any test runner.
+                Requires --command.
+          rspec Runs RSpec programmatically in-process. No process startup overhead per batch.
+                Requires rspec-core ~> 3.0.
       USAGE
     end
   end

data/lib/specbandit/cli_adapter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Specbandit
+  # CLI adapter: spawns a shell command for each batch.
+  #
+  # Works with any test runner. The command string is split on whitespace,
+  # and file paths are appended as arguments:
+  #
+  #   <executable> [...command_args] [...command_opts] [...file_paths]
+  #
+  # Example: command="bundle exec rspec", command_opts=["--format", "documentation"]
+  #   -> system("bundle", "exec", "rspec", "--format", "documentation", "file1.rb", "file2.rb")
+  class CliAdapter
+    include Adapter
+
+    attr_reader :command, :command_opts, :verbose, :output
+
+    def initialize(command:, command_opts: [], verbose: false, output: $stdout)
+      @command = command
+      @command_opts = Array(command_opts)
+      @verbose = verbose
+      @output = output
+    end
+
+    # No-op for CLI adapter.
+    def setup; end
+
+    # Spawn the command with file paths appended as arguments.
+    # Returns a BatchResult with the exit code and timing.
+    def run_batch(files, batch_num)
+      command_parts = command.split(/\s+/)
+      args = command_parts + command_opts + files
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      if verbose
+        # Inherit stdio so user sees output in real-time
+        system(*args)
+        exit_code = $?.exitstatus || 1
+      else
+        stdout, stderr, status = Open3.capture3(*args)
+        exit_code = status.exitstatus || 1
+
+        # Print stderr on failure
+        output.puts stderr if exit_code != 0 && stderr && !stderr.strip.empty?
+
+        # Print stdout if any
+        output.print(stdout) if stdout && !stdout.empty?
+      end
+
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+      BatchResult.new(
+        batch_num: batch_num,
+        files: files,
+        exit_code: exit_code,
+        duration: duration
+      )
+    end
+
+    # No-op for CLI adapter.
+    def teardown; end
+  end
+end

data/lib/specbandit/configuration.rb

@@ -3,12 +3,14 @@
 module Specbandit
   class Configuration
     attr_accessor :redis_url, :batch_size, :key, :rspec_opts, :key_ttl,
-                  :key_rerun, :key_rerun_ttl, :verbose
+                  :key_rerun, :key_rerun_ttl, :verbose,
+                  :adapter, :command, :command_opts
 
     DEFAULT_REDIS_URL = 'redis://localhost:6379'
     DEFAULT_BATCH_SIZE = 5
     DEFAULT_KEY_TTL = 21_600 # 6 hours in seconds
     DEFAULT_KEY_RERUN_TTL = 604_800 # 1 week in seconds
+    DEFAULT_ADAPTER = 'cli'
 
     def initialize
       @redis_url = ENV.fetch('SPECBANDIT_REDIS_URL', DEFAULT_REDIS_URL)
@@ -19,6 +21,9 @@ module Specbandit
       @key_rerun = ENV.fetch('SPECBANDIT_KEY_RERUN', nil)
       @key_rerun_ttl = Integer(ENV.fetch('SPECBANDIT_KEY_RERUN_TTL', DEFAULT_KEY_RERUN_TTL))
       @verbose = env_truthy?('SPECBANDIT_VERBOSE')
+      @adapter = ENV.fetch('SPECBANDIT_ADAPTER', DEFAULT_ADAPTER)
+      @command = ENV.fetch('SPECBANDIT_COMMAND', nil)
+      @command_opts = parse_space_separated(ENV.fetch('SPECBANDIT_COMMAND_OPTS', nil))
     end
 
     def validate!
@@ -36,6 +41,12 @@ module Specbandit
       opts.split
     end
 
+    def parse_space_separated(value)
+      return [] if value.nil? || value.empty?
+
+      value.split
+    end
+
     def env_truthy?(name)
       %w[1 true yes].include?(ENV.fetch(name, '').downcase)
     end

data/lib/specbandit/rspec_adapter.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'json'
+require 'tempfile'
+require 'rspec/core'
+
+module Specbandit
+  # RSpec-specific batch result that extends BatchResult with the path
+  # to the JSON output file. The Worker uses this to accumulate
+  # per-example results for rich reporting (failed spec details, etc.).
+  class RspecBatchResult < BatchResult
+    attr_accessor :json_path
+  end
+
+  # RSpec adapter: runs RSpec programmatically in-process.
+  #
+  # Each batch calls RSpec::Core::Runner.run with careful state cleanup
+  # between batches. This avoids process startup overhead and is the
+  # fastest way to run RSpec batches in a single process.
+  #
+  # The adapter injects a JSON formatter writing to a tempfile so the
+  # Worker can accumulate structured results. User-provided rspec_opts
+  # (e.g. --format documentation) are preserved and prepended.
+  class RspecAdapter
+    include Adapter
+
+    attr_reader :rspec_opts, :verbose, :output
+
+    def initialize(rspec_opts: [], verbose: false, output: $stdout)
+      @rspec_opts = Array(rspec_opts)
+      @verbose = verbose
+      @output = output
+    end
+
+    # No-op for RSpec adapter — RSpec is already loaded.
+    def setup; end
+
+    # Run a batch of spec files via RSpec::Core::Runner.run.
+    #
+    # Returns an RspecBatchResult with exit_code, duration, and json_path
+    # pointing to a tempfile containing the JSON output. The caller is
+    # responsible for reading and cleaning up the tempfile.
+    def run_batch(files, batch_num)
+      reset_rspec_state
+
+      batch_json = Tempfile.new(['specbandit-batch', '.json'])
+      args = files + rspec_opts + ['--format', 'json', '--out', batch_json.path]
+
+      err = StringIO.new
+      out = StringIO.new
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      exit_code = RSpec::Core::Runner.run(args, err, out)
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+      result = RspecBatchResult.new(
+        batch_num: batch_num,
+        files: files,
+        exit_code: exit_code,
+        duration: duration
+      )
+      result.json_path = batch_json.path
+      result
+    ensure
+      # Print RSpec output through our output stream
+      rspec_output = out&.string
+      output.print(rspec_output) if verbose && rspec_output && !rspec_output.empty?
+
+      rspec_err = err&.string
+      output.print(rspec_err) if verbose && rspec_err && !rspec_err.empty?
+
+      # Don't unlink the tempfile here — the Worker needs to read it.
+      # The Worker is responsible for cleanup after accumulation.
+      batch_json&.close
+    end
+
+    # No-op for RSpec adapter.
+    def teardown; end
+
+    private
+
+    # Reset RSpec state between batches so each batch runs cleanly.
+    #
+    # RSpec.clear_examples resets example groups, the reporter, filters, and
+    # the start-time clock -- but it leaves three critical pieces of state
+    # that cause cascading failures when running multiple batches in the
+    # same process:
+    #
+    # 1. output_stream -- After batch #1, Runner#configure sets
+    #    output_stream to a StringIO. On batch #2+, the guard
+    #    `if output_stream == $stdout` is permanently false, so the new
+    #    `out` is never used. All RSpec output silently goes to the stale
+    #    batch-1 StringIO.
+    #
+    # 2. wants_to_quit -- If any batch triggers a load error or fail-fast,
+    #    this flag is set to true. On subsequent batches, Runner#setup
+    #    returns immediately and Runner#run does exit_early -- specs are
+    #    never loaded or run.
+    #
+    # 3. non_example_failure -- Once set, exit_code() unconditionally
+    #    returns the failure exit code, even if all examples passed.
+    #
+    def reset_rspec_state
+      RSpec.clear_examples
+      RSpec.world.wants_to_quit = false
+      RSpec.world.non_example_failure = false
+      RSpec.configuration.output_stream = $stdout
+    end
+  end
+end

data/lib/specbandit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Specbandit
-  VERSION = '0.7.0'
+  VERSION = '0.9.0'
 end

data/lib/specbandit/worker.rb

@@ -2,41 +2,51 @@
 
 require 'stringio'
 require 'json'
-require 'tempfile'
-require 'rspec/core'
 
 module Specbandit
   class Worker
-    attr_reader :queue, :key, :batch_size, :rspec_opts, :key_rerun, :key_rerun_ttl, :output, :verbose
+    attr_reader :queue, :key, :batch_size, :adapter, :key_rerun, :key_rerun_ttl, :output, :verbose
 
     def initialize(
       key: Specbandit.configuration.key,
       batch_size: Specbandit.configuration.batch_size,
-      rspec_opts: Specbandit.configuration.rspec_opts,
+      adapter: nil,
       key_rerun: Specbandit.configuration.key_rerun,
       key_rerun_ttl: Specbandit.configuration.key_rerun_ttl,
       verbose: Specbandit.configuration.verbose,
       queue: nil,
-      output: $stdout
+      output: $stdout,
+      # Legacy parameter for backward compatibility.
+      # When adapter is not provided, rspec_opts is used to build an RspecAdapter.
+      rspec_opts: nil
     )
       @key = key
       @batch_size = batch_size
-      @rspec_opts = Array(rspec_opts)
       @key_rerun = key_rerun
       @key_rerun_ttl = key_rerun_ttl
       @verbose = verbose
       @queue = queue || RedisQueue.new
       @output = output
-      @batch_durations = []
+      @batch_results = []
       @accumulated_examples = []
       @accumulated_summary = { duration: 0.0, example_count: 0, failure_count: 0, pending_count: 0,
                                errors_outside_of_examples_count: 0 }
+
+      # Support both new adapter-based and legacy rspec_opts-based construction.
+      # If no adapter is provided, fall back to RspecAdapter for backward compatibility.
+      @adapter = adapter || RspecAdapter.new(
+        rspec_opts: rspec_opts || Specbandit.configuration.rspec_opts,
+        verbose: verbose,
+        output: output
+      )
     end
 
     # Main entry point. Detects the operating mode and dispatches accordingly.
     #
     # Returns 0 if all batches passed (or nothing to do), 1 if any batch failed.
     def run
+      adapter.setup
+
       exit_code = if key_rerun
                     rerun_files = queue.read_all(key_rerun)
                     if rerun_files.any?
@@ -48,11 +58,13 @@ module Specbandit
                     run_steal(record: false)
                   end
 
-      print_summary if @batch_durations.any?
+      print_summary if @batch_results.any?
       merge_json_results
       write_github_step_summary if ENV['GITHUB_STEP_SUMMARY']
 
       exit_code
+    ensure
+      adapter.teardown
     end
 
     private
@@ -72,9 +84,11 @@ module Specbandit
         output.puts "[specbandit] Batch ##{batch_num}: running #{batch.size} files"
         batch.each { |f| output.puts "  #{f}" } if verbose
 
-        exit_code = run_rspec_batch(batch)
-        if exit_code != 0
-          output.puts "[specbandit] Batch ##{batch_num} FAILED (exit code: #{exit_code})"
+        result = adapter.run_batch(batch, batch_num)
+        process_batch_result(result)
+
+        if result.exit_code != 0
+          output.puts "[specbandit] Batch ##{batch_num} FAILED (exit code: #{result.exit_code})"
           failed = true
         else
           output.puts "[specbandit] Batch ##{batch_num} passed."
@@ -111,9 +125,11 @@ module Specbandit
         output.puts "[specbandit] Batch ##{batch_num}: running #{files.size} files"
         files.each { |f| output.puts "  #{f}" } if verbose
 
-        exit_code = run_rspec_batch(files)
-        if exit_code != 0
-          output.puts "[specbandit] Batch ##{batch_num} FAILED (exit code: #{exit_code})"
+        result = adapter.run_batch(files, batch_num)
+        process_batch_result(result)
+
+        if result.exit_code != 0
+          output.puts "[specbandit] Batch ##{batch_num} FAILED (exit code: #{result.exit_code})"
           failed = true
         else
           output.puts "[specbandit] Batch ##{batch_num} passed."
@@ -129,71 +145,42 @@ module Specbandit
       failed ? 1 : 0
     end
 
-    def run_rspec_batch(files)
-      reset_rspec_state
+    # Process a BatchResult: store it, and for RSpec batches,
+    # read the JSON output for rich reporting.
+    def process_batch_result(result)
+      @batch_results << result
 
-      # Always write JSON to a tempfile so we can accumulate structured results
-      # regardless of whether the user passed --format json --out.
-      batch_json = Tempfile.new(['specbandit-batch', '.json'])
-      args = files + rspec_opts + ['--format', 'json', '--out', batch_json.path]
+      # If the adapter returned an RspecBatchResult with a json_path,
+      # accumulate the structured results for rich reporting.
+      return unless result.is_a?(RspecBatchResult) && result.json_path
 
-      err = StringIO.new
-      out = StringIO.new
+      accumulate_json_results(result.json_path)
 
-      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      exit_code = RSpec::Core::Runner.run(args, err, out)
-      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-      @batch_durations << duration
-
-      accumulate_json_results(batch_json.path)
-      exit_code
-    ensure
-      # Print RSpec output through our output stream
-      rspec_output = out&.string
-      output.print(rspec_output) if verbose && rspec_output && !rspec_output.empty?
+      # Clean up the tempfile now that we've read it
+      File.delete(result.json_path) if File.exist?(result.json_path)
+    rescue StandardError
+      # Never fail because of tempfile cleanup
+      nil
+    end
 
-      rspec_err = err&.string
-      output.print(rspec_err) if verbose && rspec_err && !rspec_err.empty?
+    # --- Reporting helpers ---
 
-      batch_json&.close
-      batch_json&.unlink
+    def batch_durations
+      @batch_results.map(&:duration)
     end
 
-    # Reset RSpec state between batches so each batch runs cleanly.
-    #
-    # RSpec.clear_examples resets example groups, the reporter, filters, and
-    # the start-time clock -- but it leaves three critical pieces of state
-    # that cause cascading failures when running multiple batches in the
-    # same process:
-    #
-    # 1. output_stream -- After batch #1, Runner#configure sets
-    #    output_stream to a StringIO. On batch #2+, the guard
-    #    `if output_stream == $stdout` is permanently false, so the new
-    #    `out` is never used. All RSpec output silently goes to the stale
-    #    batch-1 StringIO.
-    #
-    # 2. wants_to_quit -- If any batch triggers a load error or fail-fast,
-    #    this flag is set to true. On subsequent batches, Runner#setup
-    #    returns immediately and Runner#run does exit_early -- specs are
-    #    never loaded or run.
-    #
-    # 3. non_example_failure -- Once set, exit_code() unconditionally
-    #    returns the failure exit code, even if all examples passed.
-    #
-    def reset_rspec_state
-      RSpec.clear_examples
-      RSpec.world.wants_to_quit = false
-      RSpec.world.non_example_failure = false
-      RSpec.configuration.output_stream = $stdout
+    def has_rspec_results?
+      @accumulated_examples.any? || @accumulated_summary[:example_count] > 0
     end
 
-    # --- Reporting helpers ---
-
-    # Extract the --out file path from rspec_opts.
+    # Extract the --out file path from rspec_opts (when using RspecAdapter).
     # RSpec accepts: --out FILE or -o FILE
     def json_output_path
-      rspec_opts.each_with_index do |opt, i|
-        return rspec_opts[i + 1] if ['--out', '-o'].include?(opt) && rspec_opts[i + 1]
+      return nil unless adapter.is_a?(RspecAdapter)
+
+      opts = adapter.rspec_opts
+      opts.each_with_index do |opt, i|
+        return opts[i + 1] if ['--out', '-o'].include?(opt) && opts[i + 1]
       end
       nil
     end
@@ -238,11 +225,11 @@ module Specbandit
         'summary_line' => summary_line,
         'examples' => @accumulated_examples,
         'batch_timings' => {
-          'count' => @batch_durations.size,
-          'min' => @batch_durations.min&.round(2),
-          'avg' => @batch_durations.empty? ? 0 : (@batch_durations.sum / @batch_durations.size).round(2),
-          'max' => @batch_durations.max&.round(2),
-          'all' => @batch_durations.map { |d| d.round(2) }
+          'count' => batch_durations.size,
+          'min' => batch_durations.min&.round(2),
+          'avg' => batch_durations.empty? ? 0 : (batch_durations.sum / batch_durations.size).round(2),
+          'max' => batch_durations.max&.round(2),
+          'all' => batch_durations.map { |d| d.round(2) }
         }
       }
 
@@ -255,33 +242,54 @@ module Specbandit
       output.puts '=' * 60
       output.puts '[specbandit] Summary'
       output.puts '=' * 60
-      output.puts "  Batches:  #{@batch_durations.size}"
-      output.puts "  Examples: #{@accumulated_summary[:example_count]}"
-      output.puts "  Failures: #{@accumulated_summary[:failure_count]}"
-      output.puts "  Pending:  #{@accumulated_summary[:pending_count]}"
+      output.puts "  Batches:  #{batch_durations.size}"
+
+      if has_rspec_results?
+        # Rich RSpec-specific summary
+        output.puts "  Examples: #{@accumulated_summary[:example_count]}"
+        output.puts "  Failures: #{@accumulated_summary[:failure_count]}"
+        output.puts "  Pending:  #{@accumulated_summary[:pending_count]}"
+      else
+        # Generic batch-level summary (CLI adapter or no JSON data)
+        total_files = @batch_results.sum { |r| r.files.size }
+        failed_batches = @batch_results.count { |r| r.exit_code != 0 }
+        output.puts "  Files:          #{total_files}"
+        output.puts "  Failed batches: #{failed_batches}"
+      end
 
       output.puts ''
       output.puts format(
         '  Batch timing: min %.1fs | avg %.1fs | max %.1fs',
-        @batch_durations.min || 0,
-        @batch_durations.empty? ? 0 : @batch_durations.sum / @batch_durations.size,
-        @batch_durations.max || 0
+        batch_durations.min || 0,
+        batch_durations.empty? ? 0 : batch_durations.sum / batch_durations.size,
+        batch_durations.max || 0
       )
 
-      failed_examples = @accumulated_examples.select { |e| e['status'] == 'failed' }
-      if failed_examples.any?
-        output.puts ''
-        output.puts "  Failed specs (#{failed_examples.size}):"
-        failed_examples.each do |ex|
-          location = ex.dig('file_path') || 'unknown'
-          line = ex.dig('line_number')
-          location = "#{location}:#{line}" if line
-          desc = ex.dig('full_description') || ex.dig('description') || ''
-          message = ex.dig('exception', 'message') || ''
-          # Truncate long messages
-          message = "#{message[0, 120]}..." if message.length > 120
-          output.puts "    #{location} - #{desc}"
-          output.puts "      #{message}" unless message.empty?
+      if has_rspec_results?
+        failed_examples = @accumulated_examples.select { |e| e['status'] == 'failed' }
+        if failed_examples.any?
+          output.puts ''
+          output.puts "  Failed specs (#{failed_examples.size}):"
+          failed_examples.each do |ex|
+            location = ex.dig('file_path') || 'unknown'
+            line = ex.dig('line_number')
+            location = "#{location}:#{line}" if line
+            desc = ex.dig('full_description') || ex.dig('description') || ''
+            message = ex.dig('exception', 'message') || ''
+            # Truncate long messages
+            message = "#{message[0, 120]}..." if message.length > 120
+            output.puts "    #{location} - #{desc}"
+            output.puts "      #{message}" unless message.empty?
+          end
+        end
+      else
+        failed_batch_results = @batch_results.select { |r| r.exit_code != 0 }
+        if failed_batch_results.any?
+          output.puts ''
+          output.puts "  Failed batches (#{failed_batch_results.size}):"
+          failed_batch_results.each do |r|
+            output.puts "    Batch ##{r.batch_num} (exit code #{r.exit_code}): #{r.files.join(', ')}"
+          end
         end
       end
 
@@ -302,44 +310,85 @@ module Specbandit
       return unless path
 
       md = StringIO.new
-      md.puts '### 🏴‍☠️ Specbandit Results'
+
+      if has_rspec_results?
+        write_rspec_github_summary(md)
+      else
+        write_generic_github_summary(md)
+      end
+
+      File.open(path, 'a') { |f| f.write(md.string) }
+    rescue StandardError
+      # Never fail the build because of summary writing
+      nil
+    end
+
+    def write_rspec_github_summary(md)
+      md.puts '### Specbandit Results'
       md.puts ''
       md.puts '| Metric | Value |'
       md.puts '|--------|-------|'
-      md.puts "| Batches | #{@batch_durations.size} |"
+      md.puts "| Batches | #{batch_durations.size} |"
       md.puts "| Examples | #{@accumulated_summary[:example_count]} |"
       md.puts "| Failures | #{@accumulated_summary[:failure_count]} |"
       md.puts "| Pending | #{@accumulated_summary[:pending_count]} |"
 
-      md.puts format('| Batch time (min) | %.1fs |', @batch_durations.min || 0)
+      md.puts format('| Batch time (min) | %.1fs |', batch_durations.min || 0)
       md.puts format('| Batch time (avg) | %.1fs |',
-                     @batch_durations.empty? ? 0 : @batch_durations.sum / @batch_durations.size)
-      md.puts format('| Batch time (max) | %.1fs |', @batch_durations.max || 0)
+                     batch_durations.empty? ? 0 : batch_durations.sum / batch_durations.size)
+      md.puts format('| Batch time (max) | %.1fs |', batch_durations.max || 0)
       md.puts ''
 
       failed_examples = @accumulated_examples.select { |e| e['status'] == 'failed' }
-      if failed_examples.any?
-        md.puts "<details><summary>❌ #{failed_examples.size} failed specs</summary>"
-        md.puts ''
-        md.puts '| Location | Description | Error |'
-        md.puts '|----------|-------------|-------|'
-        failed_examples.each do |ex|
-          location = ex['file_path'] || 'unknown'
-          line = ex['line_number']
-          location = "#{location}:#{line}" if line
-          desc = (ex['full_description'] || ex['description'] || '').gsub('|', '\\|')
-          message = (ex.dig('exception', 'message') || '').gsub('|', '\\|').gsub("\n", ' ')
-          message = "#{message[0, 100]}..." if message.length > 100
-          md.puts "| `#{location}` | #{desc} | #{message} |"
-        end
-        md.puts ''
-        md.puts '</details>'
+      return unless failed_examples.any?
+
+      md.puts "<details><summary>#{failed_examples.size} failed specs</summary>"
+      md.puts ''
+      md.puts '| Location | Description | Error |'
+      md.puts '|----------|-------------|-------|'
+      failed_examples.each do |ex|
+        location = ex['file_path'] || 'unknown'
+        line = ex['line_number']
+        location = "#{location}:#{line}" if line
+        desc = (ex['full_description'] || ex['description'] || '').gsub('|', '\\|')
+        message = (ex.dig('exception', 'message') || '').gsub('|', '\\|').gsub("\n", ' ')
+        message = "#{message[0, 100]}..." if message.length > 100
+        md.puts "| `#{location}` | #{desc} | #{message} |"
       end
+      md.puts ''
+      md.puts '</details>'
+    end
 
-      File.open(path, 'a') { |f| f.write(md.string) }
-    rescue StandardError
-      # Never fail the build because of summary writing
-      nil
+    def write_generic_github_summary(md)
+      total_files = @batch_results.sum { |r| r.files.size }
+      failed_batch_results = @batch_results.select { |r| r.exit_code != 0 }
+
+      md.puts '### Specbandit Results'
+      md.puts ''
+      md.puts '| Metric | Value |'
+      md.puts '|--------|-------|'
+      md.puts "| Batches | #{batch_durations.size} |"
+      md.puts "| Files | #{total_files} |"
+      md.puts "| Failed batches | #{failed_batch_results.size} |"
+
+      md.puts format('| Batch time (min) | %.1fs |', batch_durations.min || 0)
+      md.puts format('| Batch time (avg) | %.1fs |',
+                     batch_durations.empty? ? 0 : batch_durations.sum / batch_durations.size)
+      md.puts format('| Batch time (max) | %.1fs |', batch_durations.max || 0)
+      md.puts ''
+
+      return unless failed_batch_results.any?
+
+      md.puts "<details><summary>#{failed_batch_results.size} failed batches</summary>"
+      md.puts ''
+      md.puts '| Batch | Exit Code | Files |'
+      md.puts '|-------|-----------|-------|'
+      failed_batch_results.each do |r|
+        files_str = r.files.map { |f| "`#{f}`" }.join(', ')
+        md.puts "| ##{r.batch_num} | #{r.exit_code} | #{files_str} |"
+      end
+      md.puts ''
+      md.puts '</details>'
     end
   end
 end

data/lib/specbandit.rb

@@ -2,6 +2,9 @@
 
 require 'specbandit/version'
 require 'specbandit/configuration'
+require 'specbandit/adapter'
+require 'specbandit/rspec_adapter'
+require 'specbandit/cli_adapter'
 require 'specbandit/redis_queue'
 require 'specbandit/publisher'
 require 'specbandit/worker'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: specbandit
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Ferran Basora
@@ -71,9 +71,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: A work-stealing distributed RSpec runner. Push spec file paths to a Redis
-  list, then multiple CI runners atomically steal batches and execute them in-process
-  via RSpec::Core::Runner.
+description: A work-stealing distributed test runner. Push test file paths to a Redis
+  list, then multiple CI runners atomically steal batches and execute them via a pluggable
+  adapter (CLI for any test runner, or in-process RSpec for maximum performance).
 executables:
 - specbandit
 extensions: []
@@ -82,10 +82,13 @@ files:
 - README.md
 - bin/specbandit
 - lib/specbandit.rb
+- lib/specbandit/adapter.rb
 - lib/specbandit/cli.rb
+- lib/specbandit/cli_adapter.rb
 - lib/specbandit/configuration.rb
 - lib/specbandit/publisher.rb
 - lib/specbandit/redis_queue.rb
+- lib/specbandit/rspec_adapter.rb
 - lib/specbandit/version.rb
 - lib/specbandit/worker.rb
 homepage: https://github.com/factorialco/specbandit
@@ -108,5 +111,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: Distributed RSpec runner using Redis as a work queue
+summary: Distributed test runner using Redis as a work queue
 test_files: []