specbandit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bc3e7d15445689d7dfb61865891f47958e87c89cf65052b7351c4ec788bec5d2
+  data.tar.gz: 2b54637983a2e0cac8beb4d4521d0f7722819a0ef211b5089dc51915275c26e8
+SHA512:
+  metadata.gz: 3268930d24a06356a28c8fe472a180d8ae0a84c4cd1ee7fbf33e9ae36f2cfe5b34d2d86746c1a165e7a284e0e2ba731f52036210198d1073da96cf5313a9ec89
+  data.tar.gz: 22bd3603d6038e55d8540fc1a155182e71dfe95bdb21328a3c369e677185931a4fe9427b5d12286dcf2113f492323c199c97577fac8691f3e5bcbbc94f8f9ef7

data/README.md

@@ -0,0 +1,313 @@
+<p align="center">
+  <img src="specbandit.png" alt="specbandit logo" width="200">
+</p>
+
+# 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`.
+
+```
+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
+```
+
+`LPOP` with a count argument (Redis 6.2+) is atomic -- multiple workers calling it concurrently will never receive the same file.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "specbandit"
+```
+
+Or install directly:
+
+```bash
+gem install specbandit
+```
+
+**Requirements**: Ruby >= 3.0, Redis >= 6.2
+
+## Usage
+
+### 1. Push spec files to Redis
+
+A single CI job enqueues all spec file paths before workers start.
+
+```bash
+# Via glob pattern (resolved in Ruby, avoids shell ARG_MAX limits)
+specbandit push --key pr-123-run-456 --pattern 'spec/**/*_spec.rb'
+
+# Via stdin pipe (for large file lists or custom filtering)
+find spec -name '*_spec.rb' | specbandit push --key pr-123-run-456
+
+# Via direct arguments (for small lists)
+specbandit push --key pr-123-run-456 spec/models/user_spec.rb spec/models/order_spec.rb
+```
+
+File input priority: **stdin > --pattern > direct args**.
+
+### 2. Steal and run from multiple workers
+
+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
+```
+
+Each worker loops:
+1. `LPOP` N file paths from Redis (atomic)
+2. Run them in-process via `RSpec::Core::Runner`
+3. Repeat until the queue is empty
+4. Exit 0 if all batches passed, 1 if any failed
+
+A failing batch does **not** stop the worker. It continues stealing remaining work so other runners aren't blocked waiting on files that will never be consumed.
+
+### CLI reference
+
+```
+specbandit push [options] [files...]
+  --key KEY              Redis queue key (required)
+  --pattern PATTERN      Glob pattern for file discovery
+  --redis-url URL        Redis URL (default: redis://localhost:6379)
+  --key-ttl SECONDS      TTL for the Redis key (default: 21600 / 6 hours)
+
+specbandit work [options]
+  --key KEY              Redis queue key (required)
+  --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)
+```
+
+### Environment variables
+
+All CLI options can be set via environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `SPECBANDIT_KEY` | Redis queue key | _(required)_ |
+| `SPECBANDIT_REDIS_URL` | Redis connection URL | `redis://localhost:6379` |
+| `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_KEY_RERUN` | Per-runner rerun key | _(none)_ |
+| `SPECBANDIT_KEY_RERUN_TTL` | Rerun key expiry in seconds | `604800` (1 week) |
+
+CLI flags take precedence over environment variables.
+
+### Ruby API
+
+```ruby
+require "specbandit"
+
+Specbandit.configure do |c|
+  c.redis_url      = "redis://my-redis:6379"
+  c.key            = "pr-123-run-456"
+  c.batch_size     = 10
+  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
+exit_code = worker.run
+```
+
+## Example: GitHub Actions (basic)
+
+```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 }}" \
+            --batch-size 10
+```
+
+## Re-running failed CI jobs
+
+### The problem
+
+When you use specbandit to distribute tests across multiple CI runners (e.g. a GitHub Actions matrix with 4 runners), each runner **steals** a random subset of spec files from the shared Redis queue. The distribution is non-deterministic -- which runner gets which files depends on timing.
+
+This creates a subtle but serious problem with CI re-runs:
+
+1. **First run**: Runner #3 steals and executes files X, Y, Z. File Y fails. The shared queue is now empty (all files were consumed across all runners).
+2. **Re-run of runner #3**: GitHub Actions re-runs only the failed runner. It starts `specbandit work` again with the same `--key`, but the shared queue is already empty. Runner #3 sees nothing to do and **exits 0 -- the failing test silently passes**.
+
+This happens because GitHub Actions re-runs **reuse the same `run_id`**, so the key resolves to the same (now empty) Redis list.
+
+### The solution: `--key-rerun`
+
+The `--key-rerun` flag gives each matrix runner its own "memory" in Redis. It enables specbandit to **record** which files each runner executed, and **replay** exactly those files on a re-run.
+
+Each runner gets a unique rerun key (typically including the matrix index):
+
+```bash
+specbandit work \
+  --key "pr-42-run-100" \
+  --key-rerun "pr-42-run-100-runner-3" \
+  --batch-size 10
+```
+
+### How it works: three operating modes
+
+Specbandit detects the mode automatically based on the state of `--key-rerun`:
+
+| `--key-rerun` provided? | Rerun key in Redis | Mode | Behavior |
+|---|---|---|---|
+| No | -- | **Steal** | Original behavior. Steal from shared queue, run, done. |
+| Yes | Empty | **Record** | Steal from shared queue + record each batch to the rerun key. |
+| Yes | Has data | **Replay** | Ignore shared queue entirely. Re-run exactly the recorded files. |
+
+**On first run**, the rerun key doesn't exist yet (empty), so specbandit enters **record mode**:
+
+```
+┌──────────────────┐   LPOP N    ┌──────────────────┐   RPUSH    ┌──────────────────────────────┐
+│  Redis            │ ─────────> │  Runner #3        │ ────────> │  Redis                        │
+│  --key            │            │                   │           │  --key-rerun                   │
+│  (shared queue)   │            │  steal + record   │           │  (per-runner memory)           │
+│                   │            │  + run specs      │           │                                │
+│  [f1,f2,...,fN]   │            │                   │           │  [f5,f6,f7] ← what #3 stole   │
+└──────────────────┘            └──────────────────┘           └──────────────────────────────┘
+```
+
+**On re-run**, the rerun key already contains the files from the first run, so specbandit enters **replay mode**:
+
+```
+                                ┌──────────────────┐  LRANGE    ┌──────────────────────────────┐
+   --key NOT touched            │  Runner #3        │ <──────── │  Redis                        │
+                                │                   │           │  --key-rerun                   │
+                                │  replay specs     │           │  (per-runner memory)           │
+                                │  f5, f6, f7       │           │                                │
+                                └──────────────────┘           │  [f5,f6,f7] ← still there      │
+                                                               └──────────────────────────────┘
+```
+
+Key details:
+
+- **Replay reads non-destructively** (`LRANGE`, not `LPOP`). The rerun key is never consumed. If you re-run the same runner multiple times, it replays the same files every time.
+- **The shared queue is never touched in replay mode**. Other runners are unaffected.
+- **Each runner has its own rerun key**. Only the re-run runner enters replay mode; runners that aren't re-run don't start at all.
+
+### Complete GitHub Actions example with re-run support
+
+```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 }}" \
+            --key-rerun "pr-${{ github.event.number }}-${{ github.run_id }}-runner-${{ matrix.runner }}" \
+            --redis-url "${{ secrets.REDIS_URL }}" \
+            --batch-size 10
+```
+
+The only difference from the basic example is the addition of `--key-rerun`. The key structure:
+
+- `--key` = `pr-42-run-100` -- **shared** across all 4 runners, same on re-run (because `run_id` is reused)
+- `--key-rerun` = `pr-42-run-100-runner-3` -- **unique per runner**, same on re-run
+
+### Walk-through: what happens step by step
+
+**First run (all 4 runners start fresh):**
+
+| Runner | Mode | What happens |
+|---|---|---|
+| Runner 1 | Record | Steals files A, B, C from shared queue. Records them to `...-runner-1`. |
+| Runner 2 | Record | Steals files D, E from shared queue. Records them to `...-runner-2`. |
+| Runner 3 | Record | Steals files F, G, H from shared queue. File G fails. Records them to `...-runner-3`. |
+| Runner 4 | Record | Steals files I, J from shared queue. Records them to `...-runner-4`. |
+
+**Re-run of runner 3 only:**
+
+| Runner | Mode | What happens |
+|---|---|---|
+| Runner 3 | Replay | Reads F, G, H from `...-runner-3`. Runs exactly those files. G still fails = correctly reported. |
+
+Runners 1, 2, 4 are not started at all.
+
+### Rerun key TTL
+
+The rerun key defaults to a **1 week TTL** (`604800` seconds). This is intentionally longer than the shared queue TTL (6 hours) because re-runs can happen hours or even days after the original CI run.
+
+Override via `--key-rerun-ttl` or `SPECBANDIT_KEY_RERUN_TTL`:
+
+```bash
+# Set rerun key to expire after 3 days
+specbandit work \
+  --key "pr-42-run-100" \
+  --key-rerun "pr-42-run-100-runner-3" \
+  --key-rerun-ttl 259200
+```
+
+## How it works
+
+- **Push** uses `RPUSH` to append all file paths to a Redis list in a single command, then sets `EXPIRE` on the key (default: 6 hours) to ensure stale queues are automatically cleaned up.
+- **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.
+- **Exit code** is 0 if every batch passed (or the queue was already empty), 1 if any batch had failures.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec                    # unit tests (no Redis needed)
+bundle exec rspec spec/integration/  # integration tests (requires Redis on localhost:6379)
+```
+
+## License
+
+MIT

data/bin/specbandit

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "specbandit"
+require "specbandit/cli"
+
+exit Specbandit::CLI.run(ARGV)

data/lib/specbandit/cli.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Specbandit
+  class CLI
+    COMMANDS = %w[push work].freeze
+
+    def self.run(argv = ARGV)
+      new(argv).execute
+    end
+
+    attr_reader :argv
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def execute
+      command = argv.shift
+
+      case command
+      when 'push'
+        run_push
+      when 'work'
+        run_work
+      when nil, '-h', '--help'
+        print_usage
+        0
+      when '-v', '--version'
+        puts "specbandit #{VERSION}"
+        0
+      else
+        warn "Unknown command: #{command}"
+        print_usage
+        1
+      end
+    rescue Specbandit::Error => e
+      warn "[specbandit] Error: #{e.message}"
+      1
+    rescue Redis::BaseError => e
+      warn "[specbandit] Redis error: #{e.message}"
+      1
+    end
+
+    private
+
+    def run_push
+      options = { pattern: nil }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: specbandit push [options] [files...]'
+
+        opts.on('--key KEY', 'Redis queue key (required, or set SPECBANDIT_KEY)') do |v|
+          Specbandit.configuration.key = v
+        end
+
+        opts.on('--pattern PATTERN', "Glob pattern to resolve files (e.g. 'spec/**/*_spec.rb')") do |v|
+          options[:pattern] = v
+        end
+
+        opts.on('--redis-url URL', 'Redis URL (default: redis://localhost:6379)') do |v|
+          Specbandit.configuration.redis_url = v
+        end
+
+        opts.on('--key-ttl SECONDS', Integer, 'TTL for the Redis key in seconds (default: 21600 / 6 hours)') do |v|
+          Specbandit.configuration.key_ttl = v
+        end
+
+        opts.on('-h', '--help', 'Show this help') do
+          puts opts
+          return 0
+        end
+      end
+
+      parser.parse!(argv)
+      Specbandit.configuration.validate!
+
+      publisher = Publisher.new
+      files_arg = argv.empty? ? [] : argv
+      count = publisher.publish(files: files_arg, pattern: options[:pattern])
+
+      count.positive? ? 0 : 1
+    end
+
+    def run_work
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: specbandit work [options]'
+
+        opts.on('--key KEY', 'Redis queue key (required, or set SPECBANDIT_KEY)') do |v|
+          Specbandit.configuration.key = v
+        end
+
+        opts.on('--batch-size N', Integer, 'Number of files to steal per batch (default: 5)') do |v|
+          Specbandit.configuration.batch_size = v
+        end
+
+        opts.on('--redis-url URL', 'Redis URL (default: redis://localhost:6379)') do |v|
+          Specbandit.configuration.redis_url = v
+        end
+
+        opts.on('--rspec-opts OPTS', 'Extra options to pass to RSpec (space-separated)') do |v|
+          Specbandit.configuration.rspec_opts = v.split
+        end
+
+        opts.on('--key-rerun KEY', 'Per-runner rerun key for re-run support') do |v|
+          Specbandit.configuration.key_rerun = v
+        end
+
+        opts.on('--key-rerun-ttl SECONDS', Integer, 'TTL for rerun key in seconds (default: 604800 / 1 week)') do |v|
+          Specbandit.configuration.key_rerun_ttl = v
+        end
+
+        opts.on('-h', '--help', 'Show this help') do
+          puts opts
+          return 0
+        end
+      end
+
+      parser.parse!(argv)
+      Specbandit.configuration.validate!
+
+      worker = Worker.new
+      worker.run
+    end
+
+    def print_usage
+      puts <<~USAGE
+        specbandit v#{VERSION} - Distributed RSpec runner using Redis
+
+        Usage:
+          specbandit push [options] [files...]    Enqueue spec files into Redis
+          specbandit work [options]               Steal and run spec 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)
+
+        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)
+
+        Environment variables:
+          SPECBANDIT_KEY              Queue key
+          SPECBANDIT_REDIS_URL        Redis URL
+          SPECBANDIT_BATCH_SIZE       Batch size
+          SPECBANDIT_KEY_TTL          Key TTL in seconds (default: 21600)
+          SPECBANDIT_RSPEC_OPTS       RSpec options
+          SPECBANDIT_KEY_RERUN        Per-runner rerun key
+          SPECBANDIT_KEY_RERUN_TTL    Rerun key TTL in seconds (default: 604800)
+
+        File input priority for push:
+          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
+      USAGE
+    end
+  end
+end

data/lib/specbandit/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Specbandit
+  class Configuration
+    attr_accessor :redis_url, :batch_size, :key, :rspec_opts, :key_ttl,
+                  :key_rerun, :key_rerun_ttl
+
+    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
+
+    def initialize
+      @redis_url = ENV.fetch('SPECBANDIT_REDIS_URL', DEFAULT_REDIS_URL)
+      @batch_size = Integer(ENV.fetch('SPECBANDIT_BATCH_SIZE', DEFAULT_BATCH_SIZE))
+      @key = ENV.fetch('SPECBANDIT_KEY', nil)
+      @rspec_opts = parse_rspec_opts(ENV.fetch('SPECBANDIT_RSPEC_OPTS', nil))
+      @key_ttl = Integer(ENV.fetch('SPECBANDIT_KEY_TTL', DEFAULT_KEY_TTL))
+      @key_rerun = ENV.fetch('SPECBANDIT_KEY_RERUN', nil)
+      @key_rerun_ttl = Integer(ENV.fetch('SPECBANDIT_KEY_RERUN_TTL', DEFAULT_KEY_RERUN_TTL))
+    end
+
+    def validate!
+      raise Error, 'key is required (set via --key or SPECBANDIT_KEY)' if key.nil? || key.empty?
+      raise Error, 'batch_size must be a positive integer' unless batch_size.positive?
+      raise Error, 'key_ttl must be a positive integer' unless key_ttl.positive?
+      raise Error, 'key_rerun_ttl must be a positive integer' unless key_rerun_ttl.positive?
+    end
+
+    private
+
+    def parse_rspec_opts(opts)
+      return [] if opts.nil? || opts.empty?
+
+      opts.split
+    end
+  end
+end

data/lib/specbandit/publisher.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Specbandit
+  class Publisher
+    attr_reader :queue, :key, :key_ttl, :output
+
+    def initialize(key: Specbandit.configuration.key, key_ttl: Specbandit.configuration.key_ttl, queue: nil,
+                   output: $stdout)
+      @key = key
+      @key_ttl = key_ttl
+      @queue = queue || RedisQueue.new
+      @output = output
+    end
+
+    # Resolve files from the three input sources (priority: stdin > pattern > args)
+    # and push them onto the Redis queue.
+    #
+    # Returns the number of files enqueued.
+    def publish(files: [], pattern: nil)
+      resolved = resolve_files(files: files, pattern: pattern)
+
+      if resolved.empty?
+        output.puts '[specbandit] No files to enqueue.'
+        return 0
+      end
+
+      queue.push(key, resolved, ttl: key_ttl)
+      output.puts "[specbandit] Enqueued #{resolved.size} files onto key '#{key}' (TTL: #{key_ttl}s)."
+      resolved.size
+    end
+
+    private
+
+    def resolve_files(files:, pattern:)
+      # Priority 1: stdin (if not a TTY)
+      return $stdin.each_line.map(&:strip).reject(&:empty?) unless $stdin.tty?
+
+      # Priority 2: --pattern flag (Dir.glob in Ruby, no shell expansion)
+      return Dir.glob(pattern).sort if pattern && !pattern.empty?
+
+      # Priority 3: direct file arguments
+      Array(files)
+    end
+  end
+end

data/lib/specbandit/redis_queue.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'redis'
+
+module Specbandit
+  class RedisQueue
+    attr_reader :redis
+
+    def initialize(redis_url: Specbandit.configuration.redis_url)
+      @redis = Redis.new(url: redis_url)
+    end
+
+    # Push file paths onto the queue and set an expiry on the key.
+    # Returns the new length of the list.
+    def push(key, files, ttl: nil)
+      return 0 if files.empty?
+
+      count = redis.rpush(key, files)
+      redis.expire(key, ttl) if ttl
+      count
+    end
+
+    # Atomically steal up to `count` file paths from the queue.
+    # Returns an array of file paths (empty array when exhausted).
+    #
+    # Uses LPOP with count argument (Redis 6.2+).
+    def steal(key, count)
+      result = redis.lpop(key, count)
+
+      # LPOP returns nil when the key doesn't exist or list is empty,
+      # and returns a single string (not array) when count is 1 on some versions.
+      case result
+      when nil then []
+      when String then [result]
+      else Array(result)
+      end
+    end
+
+    # Returns the current length of the queue.
+    def length(key)
+      redis.llen(key)
+    end
+
+    # Read all file paths from the list non-destructively.
+    # Returns an array of file paths (empty array when key doesn't exist).
+    def read_all(key)
+      redis.lrange(key, 0, -1)
+    end
+
+    def close
+      redis.close
+    end
+  end
+end

data/lib/specbandit/version.rb

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

data/lib/specbandit/worker.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'rspec/core'
+
+module Specbandit
+  class Worker
+    attr_reader :queue, :key, :batch_size, :rspec_opts, :key_rerun, :key_rerun_ttl, :output
+
+    def initialize(
+      key: Specbandit.configuration.key,
+      batch_size: Specbandit.configuration.batch_size,
+      rspec_opts: Specbandit.configuration.rspec_opts,
+      key_rerun: Specbandit.configuration.key_rerun,
+      key_rerun_ttl: Specbandit.configuration.key_rerun_ttl,
+      queue: nil,
+      output: $stdout
+    )
+      @key = key
+      @batch_size = batch_size
+      @rspec_opts = Array(rspec_opts)
+      @key_rerun = key_rerun
+      @key_rerun_ttl = key_rerun_ttl
+      @queue = queue || RedisQueue.new
+      @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
+      if key_rerun
+        rerun_files = queue.read_all(key_rerun)
+        if rerun_files.any?
+          run_replay(rerun_files)
+        else
+          run_steal(record: true)
+        end
+      else
+        run_steal(record: false)
+      end
+    end
+
+    private
+
+    # Replay mode: run a known list of files in local batches.
+    # Used when re-running a failed CI job -- the rerun key already
+    # contains the exact files this runner executed previously.
+    def run_replay(files)
+      output.puts "[specbandit] Replay mode: found #{files.size} files in rerun key '#{key_rerun}'."
+      output.puts '[specbandit] Running previously recorded files (not touching shared queue).'
+
+      failed = false
+      batch_num = 0
+
+      files.each_slice(batch_size) do |batch|
+        batch_num += 1
+        output.puts "[specbandit] Batch ##{batch_num}: running #{batch.size} files"
+        batch.each { |f| output.puts "  #{f}" }
+
+        exit_code = run_rspec_batch(batch)
+        if exit_code != 0
+          output.puts "[specbandit] Batch ##{batch_num} FAILED (exit code: #{exit_code})"
+          failed = true
+        else
+          output.puts "[specbandit] Batch ##{batch_num} passed."
+        end
+      end
+
+      output.puts "[specbandit] Replay finished: #{batch_num} batches. #{failed ? 'SOME FAILED' : 'All passed.'}"
+      failed ? 1 : 0
+    end
+
+    # Steal mode: atomically pop batches from the shared queue.
+    # When record is true, each stolen batch is also pushed to the
+    # rerun key so this runner can replay them on a re-run.
+    def run_steal(record:)
+      mode_label = record ? 'Record' : 'Steal'
+      output.puts "[specbandit] #{mode_label} mode: stealing batches from '#{key}'."
+      output.puts "[specbandit] Recording stolen files to rerun key '#{key_rerun}'." if record
+
+      failed = false
+      batch_num = 0
+
+      loop do
+        files = queue.steal(key, batch_size)
+
+        if files.empty?
+          output.puts '[specbandit] Queue exhausted. No more files to run.'
+          break
+        end
+
+        # Record the stolen batch so this runner can replay on re-run
+        queue.push(key_rerun, files, ttl: key_rerun_ttl) if record
+
+        batch_num += 1
+        output.puts "[specbandit] Batch ##{batch_num}: running #{files.size} files"
+        files.each { |f| output.puts "  #{f}" }
+
+        exit_code = run_rspec_batch(files)
+        if exit_code != 0
+          output.puts "[specbandit] Batch ##{batch_num} FAILED (exit code: #{exit_code})"
+          failed = true
+        else
+          output.puts "[specbandit] Batch ##{batch_num} passed."
+        end
+      end
+
+      if batch_num.zero?
+        output.puts '[specbandit] Nothing to do (queue was empty).'
+      else
+        output.puts "[specbandit] Finished #{batch_num} batches. #{failed ? 'SOME FAILED' : 'All passed.'}"
+      end
+
+      failed ? 1 : 0
+    end
+
+    def run_rspec_batch(files)
+      # Clear example state from previous batches so RSpec can run cleanly
+      # in the same process. This preserves configuration but resets
+      # the world (example groups, examples, shared groups, etc.).
+      RSpec.clear_examples
+
+      args = files + rspec_opts
+      err = StringIO.new
+      out = StringIO.new
+
+      RSpec::Core::Runner.run(args, err, out)
+    ensure
+      # Print RSpec output through our output stream
+      rspec_output = out&.string
+      output.print(rspec_output) unless rspec_output.nil? || rspec_output.empty?
+
+      rspec_err = err&.string
+      output.print(rspec_err) unless rspec_err.nil? || rspec_err.empty?
+    end
+  end
+end

data/lib/specbandit.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'specbandit/version'
+require 'specbandit/configuration'
+require 'specbandit/redis_queue'
+require 'specbandit/publisher'
+require 'specbandit/worker'
+
+module Specbandit
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: specbandit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ferran Basora
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.
+email:
+executables:
+- specbandit
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/specbandit
+- lib/specbandit.rb
+- lib/specbandit/cli.rb
+- lib/specbandit/configuration.rb
+- lib/specbandit/publisher.rb
+- lib/specbandit/redis_queue.rb
+- lib/specbandit/version.rb
+- lib/specbandit/worker.rb
+homepage: https://github.com/factorialco/specbandit
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Distributed RSpec runner using Redis as a work queue
+test_files: []