next_rails 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5a701cf48bef3ed14539987e1bad23b85972578c0f9db2194a7a073679d44ac
-  data.tar.gz: 0bbb57bb3f628b4638e61e1ec40ba84365142ba236f520dbb39bfa879009623c
+  metadata.gz: 7ef709432bba364ea112d6d8774d0c51b8bf1959b48ede86437b7ae801c7ea3b
+  data.tar.gz: f568512b09f8d16199ec4fb1800964f6a8067a3fb3d36eeaf48a335e117d56c5
 SHA512:
-  metadata.gz: c879317b36a0afe079c194700fc2007b0fb7a3d4e5a68fa22c75c12f04dbc457dd0883e2641543e8a474fec3a795176d2cba0e4f39afbc9d728fb459096d911f
-  data.tar.gz: 17bb529e77fc546e39916c9264d7b02a6d51f21586aefd2aee26e2d6815ae5bb5ebb7ad79a33653add34e32158a79887e747949853271e2af0cc4541b818b9bf
+  metadata.gz: a2b296e5306c8ab34b7f5b38801785ecfb3a6039a6a48310533ffc02033634a9d67ca2c03f6531c0dc05725a44cffe06d9dc65071f947bc6ec5c6bdd2892a6f9
+  data.tar.gz: cba5e3a34b3127fdcb2bfa28775250b5d7b2f8e0bdb5fb453976c6304f34ca1e272c4b6abee61eb12fe01c0e0cb4c22ea838d7d94164c40f57d7e039ecd7db51

data/.github/workflows/main.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ["3.4", "3.3", "3.2", "3.1", "3.0", "2.7", "2.6", "2.5", "2.4", "2.3"]
+        ruby-version: ["4.0", "3.4", "3.3", "3.2", "3.1", "3.0", "2.7", "2.6", "2.5", "2.4", "2.3"]
 
     steps:
       - uses: actions/checkout@v4

data/.rspec

@@ -1,3 +1,4 @@
 --format documentation
 --color
 --require spec_helper
+--order=random

data/CHANGELOG.md

@@ -1,9 +1,17 @@
-# main [(unreleased)](https://github.com/fastruby/next_rails/compare/v1.5.0...main)
+# main [(unreleased)](https://github.com/fastruby/next_rails/compare/v1.6.0...main)
 
 - [BUGFIX: example](https://github.com/fastruby/next_rails/pull/<number>)
 
 * Your changes/patches go here.
 
+# v1.6.0 / 2026-05-07 [(commits)](https://github.com/fastruby/next_rails/compare/v1.5.0...v1.6.0)
+
+- [CHORE: Drop `rainbow` gem dependency in favor of a native `NextRails::Tint` ANSI wrapper](https://github.com/fastruby/next_rails/pull/183)
+- [BUGFIX: Compare mode now checks only buckets the current process ran, fixing parallel test support](https://github.com/fastruby/next_rails/pull/179)
+- [FEATURE: Add `deprecations merge` command to combine parallel CI shards](https://github.com/fastruby/next_rails/pull/177)
+- [FEATURE: Add parallel CI support for DeprecationTracker](https://github.com/fastruby/next_rails/pull/176)
+- [CHORE: Add Ruby 4.0 to the test matrix](https://github.com/fastruby/next_rails/pull/178)
+
 # v1.5.0 / 2026-04-01 [(commits)](https://github.com/fastruby/next_rails/compare/v1.4.8...v1.5.0)
 
 - [FEATURE: Add `NextRails.current?` as the inverse of `NextRails.next?`](https://github.com/fastruby/next_rails/pull/174)

data/CONTRIBUTING.md

@@ -34,6 +34,10 @@ To run all of the tests, simply run:
 bundle exec rake
 ```
 
+### Testing against specific Ruby versions
+
+See the [Docker Development Environment for Old Ruby Versions](https://github.com/fastruby/next_rails/wiki/Docker-Development-Environment-for-Old-Ruby-Versions) wiki page for setup and examples.
+
 ## A word on the changelog
 
 You may also notice that we have a changelog in the form of [CHANGELOG.md](CHANGELOG.md). We use a format based on [Keep A Changelog](https://keepachangelog.com/en/1.0.0/).

data/README.md

@@ -1,83 +1,117 @@
 # Next Rails
 
 [![Continuous Integration](https://github.com/fastruby/next_rails/actions/workflows/main.yml/badge.svg)](https://github.com/fastruby/next_rails/actions/workflows/main.yml)
+[![Gem Version](https://badge.fury.io/rb/next_rails.svg)](https://rubygems.org/gems/next_rails)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
 
-This is a toolkit to upgrade your next Rails application. It will help you
-set up dual booting, track deprecation warnings, and get a report on outdated
-dependencies for any Rails application.
+A toolkit to upgrade your next Rails application. It helps you set up **dual booting**, **track deprecation warnings**, and get a **compatibility report** on outdated dependencies for any Rails application. [Learn more](https://www.fastruby.io/blog/next-rails-gem.html).
 
-This project is a fork of [`ten_years_rails`](https://github.com/clio/ten_years_rails)
+## Features
 
-## History
+- **Dual Boot** — Run your app against two sets of dependencies (e.g. Rails 7.1 and Rails 7.2) side by side
+- **Deprecation Tracking** — Capture and compare deprecation warnings across test runs (RSpec & Minitest)
+- **Bundle Report** — Check gem compatibility with a target Rails or Ruby version
+- **Ruby Check** — Find the minimum Ruby version compatible with a target Rails version
 
-This gem started as a companion to the "[Ten Years of Rails Upgrades](https://www.youtube.com/watch?v=6aCfc0DkSFo)"
-conference talk by Jordan Raine.
+## Installation
 
-> You'll find various utilities that we use at Clio to help us prepare for and
-> complete Rails upgrades.
+Add this line to your application's Gemfile:
 
-> These scripts are still early days and may not work in every environment or app.
+> [!WARNING]
+> We recommend adding `next_rails` in the root of your Gemfile, not inside a group.
+> This ensures `NextRails.next?` and `NextRails.current?` are available everywhere in your codebase.
 
-> I wouldn't recommend adding this to your Gemfile long-term. Rather, try out
-> the scripts and use them as a point of reference. Feel free to tweak them to
-> better fit your environment.
+```ruby
+gem 'next_rails'
+```
 
-## Usage
+Then run:
 
-### `bundle_report`
+```bash
+bundle install
+```
 
-Learn about your Gemfile and see what needs updating.
+## Dual Boot
 
-```bash
-# Show all out-of-date gems
-bundle_report outdated
+We recommend upgrading **one minor version at a time** (e.g. 7.1 → 7.2, not 6.1 → 7.0). This keeps changes small and manageable.
 
-# Show five oldest, out-of-date gems
-bundle_report outdated | head -n 5
+### Setup
 
-# Show all out-of-date gems in machine readable JSON format
-bundle_report outdated --json
+> [!NOTE]
+> The `next_rails --init` command will add a `next?` helper method to the top of your Gemfile, which you can use to conditionally set gem versions.
 
-# Show gems that don't work with Rails 5.2.0
-bundle_report compatibility --rails-version=5.2.0
+```bash
+# Initialize dual boot (creates Gemfile.next and Gemfile.next.lock)
+next_rails --init
 
-# Show gems that don't work with Ruby 3.0
-bundle_report compatibility --ruby-version=3.0
+# Edit your Gemfile to conditionally set gem versions using `next?`
+vim Gemfile
 
-# Find minimum compatible ruby version with Rails 7.0.0
-bundle_report ruby_check --rails-version=7.0.0
+# Install dependencies for the next version
+next bundle install
 
-# Show the usual help message
-bundle_report --help
+# Start your server using the next Gemfile
+next rails s
 ```
 
-### Application usage
+### Conditional code
 
-Every now and then it will be necessary to add code like this to your
-application:
+When your Gemfile targets two versions, you may need to branch application code as well:
 
 ```ruby
 if NextRails.next?
-  # Do things "the Rails 7 way"
+  # Do things "the Rails 7.2 way"
 else
-  # Do things "the Rails 6.1 way"
+  # Do things "the Rails 7.1 way"
 end
 ```
 
-The `NextRails.next?` method will use your environment
-(e.g. `ENV['BUNDLE_GEMFILE]`) to determine whether your application is
-running with the next set of dependencies or the current set of dependencies.
+Or use `NextRails.current?` for the inverse check:
+
+```ruby
+if NextRails.current?
+  # Do things "the Rails 7.1 way"
+else
+  # Do things "the Rails 7.2 way"
+end
+```
 
-This might come in handy if you need to inject
-[Ruby or Rails shims](https://www.fastruby.io/blog/rails/upgrades/rails-upgrade-shims.html).
+Both methods check your environment (e.g. `ENV['BUNDLE_GEMFILE']`) to determine which dependency set is active. This is useful for injecting [Ruby or Rails shims](https://www.fastruby.io/blog/rails/upgrades/rails-upgrade-shims.html).
 
-### Deprecation tracking
+## Bundle Report
 
-If you're using RSpec, add this snippet to `rails_helper.rb` or `spec_helper.rb` (whichever loads Rails).
+Inspect your Gemfile and check compatibility with a target Rails or Ruby version.
+
+```bash
+# Show all out-of-date gems
+bundle_report outdated
+
+# Show all out-of-date gems in JSON format
+bundle_report outdated --json
+
+# Show gems incompatible with Rails 7.2
+bundle_report compatibility --rails-version=7.2
+
+# Show gems incompatible with Ruby 3.3
+bundle_report compatibility --ruby-version=3.3
+
+# Find minimum Ruby version compatible with Rails 7.2
+bundle_report ruby_check --rails-version=7.2
+
+# Help
+bundle_report --help
+```
+
+## Deprecation Tracking
+
+Track deprecation warnings in your test suite so you can monitor and fix them incrementally.
+
+### RSpec
+
+Add to `rails_helper.rb` or `spec_helper.rb`:
 
 ```ruby
 RSpec.configure do |config|
-  # Tracker deprecation messages in each file
   if ENV["DEPRECATION_TRACKER"]
     DeprecationTracker.track_rspec(
       config,
@@ -89,10 +123,11 @@ RSpec.configure do |config|
 end
 ```
 
-If using minitest, add this somewhere close to the top of your `test_helper.rb`:
+### Minitest
+
+Add near the top of `test_helper.rb`:
 
 ```ruby
-# Tracker deprecation messages in each file
 if ENV["DEPRECATION_TRACKER"]
   DeprecationTracker.track_minitest(
     shitlist_path: "test/support/deprecation_warning.shitlist.json",
@@ -102,105 +137,125 @@ if ENV["DEPRECATION_TRACKER"]
 end
 ```
 
-> Keep in mind this is currently not compatible with the `minitest/parallel_fork` gem!
+> [!NOTE]
+> This is currently not compatible with the `minitest/parallel_fork` gem.
 
-Once you have that, you can start using deprecation tracking in your tests:
+### Running deprecation tracking
 
 ```bash
-# Run your tests and save the deprecations to the shitlist
+# Save current deprecations to the shitlist
 DEPRECATION_TRACKER=save rspec
-# Run your tests and raise an error when the deprecations change
+
+# Fail if deprecations have changed since the last save
 DEPRECATION_TRACKER=compare rspec
 ```
 
-#### `deprecations` command
+### Parallel CI support
 
-Once you have stored your deprecations, you can use `deprecations` to display common warnings, run specs, or update the shitlist file.
+When running tests across parallel CI nodes, each node can write to its own shard file to avoid conflicts. The tracker auto-detects the node index from common CI environment variables (`CI_NODE_INDEX`, `CIRCLE_NODE_INDEX`, `BUILDKITE_PARALLEL_JOB`, `SEMAPHORE_JOB_INDEX`, `CI_NODE_INDEX` for GitLab), or you can set it explicitly via the `node_index` option.
 
-```bash
-deprecations info
-deprecations info --pattern "ActiveRecord::Base"
-deprecations run
-deprecations --help # For more options and examples
+#### RSpec
+
+```ruby
+RSpec.configure do |config|
+  if ENV["DEPRECATION_TRACKER"]
+    DeprecationTracker.track_rspec(
+      config,
+      node_index: ENV["CI_NODE_INDEX"]
+    )
+  end
+end
 ```
 
-Right now, the path to the shitlist is hardcoded so make sure you store yours at `spec/support/deprecation_warning.shitlist.json`.
+The `node_index` option is only used in save mode. When set, the tracker writes to a shard file (e.g. `deprecation_warning.shitlist.node-0.json`) instead of the canonical file. Compare mode does not support `node_index` and will raise an error if passed—compare should only run after merging shards on the final canonical shitlist.
 
-#### `next_rails` command
+#### Merging shards
 
-You can use `next_rails` to fetch the version of the gem installed.
+After all parallel nodes finish saving, merge shards into the canonical file:
 
 ```bash
-next_rails --version
-next_rails --help # For more options and examples
-```
+# Merge all shard files and remove them afterwards
+deprecations merge --delete-shards
 
-### Dual-boot Rails next
+# Or use --next to merge shards for the next Rails version
+deprecations merge --next --delete-shards
+```
 
-This command helps you dual-boot your application.
+You can also merge shards programmatically:
 
-```bash
-next_rails --init    # Create Gemfile.next and Gemfile.next.lock
-vim Gemfile         # Tweak your dependencies conditionally using `next?`
-next bundle install # Install new gems
-next rails s        # Start server using Gemfile.next
+```ruby
+DeprecationTracker.merge_shards(
+  "spec/support/deprecation_warning.shitlist.json",
+  delete_shards: true
+)
 ```
 
-## Installation
+#### Example CI workflow
 
-Add this line to your application's Gemfile
+```yaml
+# 1. Save phase — each parallel node writes its own shard
+#    (runs on every node)
+DEPRECATION_TRACKER=save CI_NODE_INDEX=$NODE bundle exec rspec <subset>
 
-> NOTE: If you add this gem to a group, make sure it is the test env group
+# 2. Merge phase — fan-in step, runs once after all nodes finish
+deprecations merge --delete-shards
 
-```ruby
-gem 'next_rails'
+# 3. Compare phase — each parallel node checks only its own buckets
+#    against the merged canonical file (no CI_NODE_INDEX needed)
+DEPRECATION_TRACKER=compare bundle exec rspec <subset>
 ```
 
-And then execute:
+### `deprecations` command
 
-    $ bundle
+View, filter, and manage stored deprecation warnings:
 
-Or install it yourself as:
+```bash
+deprecations info
+deprecations info --pattern "ActiveRecord::Base"
+deprecations merge --delete-shards
+deprecations run
+deprecations --help
+```
 
-    $ gem install next_rails
+## CLI Reference
 
-## Setup
+```bash
+bundle exec next_rails --init    # Set up dual boot
+bundle exec next_rails --version # Show gem version
+bundle exec next_rails --help    # Show help
+```
 
-Execute:
+## Contributing
 
-    $ next_rails --init
+Bug reports and pull requests are welcome! See the [Contributing guide](CONTRIBUTING.md) for setup instructions and guidelines.
 
-Init will create a Gemfile.next and an initialized Gemfile.next.lock.
-The Gemfile.next.lock is initialized with the contents of your existing
-Gemfile.lock lock file. We initialize the Gemfile.next.lock to prevent
-major version jumps when running the next version of Rails.
+## Releases
 
-## Contributing
+`next_rails` follows [Semantic Versioning](https://semver.org). Given a version number `MAJOR.MINOR.PATCH`, we increment the:
 
-Have a fix for a problem you've been running into or an idea for a new feature you think would be useful? Want to see how you can support `next_rails`?
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for backwards-compatible new functionality
+- **PATCH** version for backwards-compatible bug fixes
 
-Take a look at the [Contributing document](CONTRIBUTING.md) for instructions to set up the repo on your machine!
+### Steps to release a new version
 
-## Releases
+1. Update the version number in `lib/next_rails/version.rb`
+2. Update `CHANGELOG.md` with the appropriate headers and entries
+3. Commit your changes to a `release/v1.x.x` branch
+4. Push your changes and submit a pull request `Release v1.x.x`
+5. Merge your pull request to the `main` branch
+6. Tag the latest version on `main`: `git tag v1.x.x`
+7. Push the tag to GitHub: `git push --tags`
+8. Build the gem: `gem build next_rails.gemspec`
+9. Push to RubyGems: `gem push next_rails-1.x.x.gem`
 
-`next_rails` adheres to [semver](https://semver.org). So given a version number MAJOR.MINOR.PATCH, we will increment the:
+## Maintainers
 
-1. MAJOR version when you make incompatible API changes,
-2. MINOR version when you add functionality in a backwards compatible manner, and
-3. PATCH version when you make backwards compatible bug fixes.
+Maintained by [OmbuLabs / FastRuby.io](https://www.fastruby.io).
 
-Here are the steps to release a new version:
+## History
 
-1. Update the `version.rb` file with the proper version number
-2. Update `CHANGELOG.md` to have the right headers
-3. Commit your changes to a `release/v-1-1-0` branch
-4. Push your changes and submit a pull request
-5. Merge your pull request to the `main` branch
-6. Git tag the latest version of the `main` branch (`git tag v1.1.0`)
-7. Push tags to GitHub (`git push --tags`)
-8. Build the gem (`gem build next_rails.gemspec`)
-9. Push the .gem package to Rubygems.org (`gem push next_rails-1.1.0.gem`)
-10. You are all done!
+This gem started as a fork of [`ten_years_rails`](https://github.com/clio/ten_years_rails), a companion to the "[Ten Years of Rails Upgrades](https://www.youtube.com/watch?v=6aCfc0DkSFo)" conference talk by Jordan Raine.
 
 ## License
 

data/exe/deprecations

@@ -3,6 +3,7 @@ require "json"
 require "rainbow"
 require "optparse"
 require "set"
+require_relative "../lib/deprecation_tracker/shard_merger"
 
 def run_tests(deprecation_warnings, opts = {})
   tracker_mode = opts[:tracker_mode]
@@ -49,6 +50,7 @@ option_parser = OptionParser.new do |opts|
       bin/deprecations --next info # Show top ten deprecations for Rails 5
       bin/deprecations --pattern "ActiveRecord::Base" --verbose info # Show full details on deprecations matching pattern
       bin/deprecations --tracker-mode save --pattern "pass" run # Run tests that output deprecations matching pattern and update shitlist
+      bin/deprecations merge --delete-shards # Merge parallel CI shards and remove shard files
 
     Modes:
       info
@@ -57,6 +59,9 @@ option_parser = OptionParser.new do |opts|
       run
         Run tests that are known to cause deprecation warnings. Use --pattern to filter what tests are run.
 
+      merge
+        Merge parallel CI shard files into the canonical shitlist. Use with --delete-shards to remove shard files after merging.
+
     Options:
   MESSAGE
 
@@ -76,6 +81,10 @@ option_parser = OptionParser.new do |opts|
     options[:verbose] = true
   end
 
+  opts.on("--delete-shards", "Delete shard files after merging") do
+    options[:delete_shards] = true
+  end
+
   opts.on_tail("-h", "--help", "Prints this help") do
     puts opts
     exit
@@ -87,24 +96,34 @@ option_parser.parse!
 options[:mode] = ARGV.last
 path = options[:next] ? "spec/support/deprecation_warning.next.shitlist.json" : "spec/support/deprecation_warning.shitlist.json"
 
-pattern_string = options.fetch(:pattern, ".+")
-pattern = /#{pattern_string}/
-
-deprecation_warnings = JSON.parse(File.read(path)).each_with_object({}) do |(test_file, messages), hash|
-  filtered_messages = messages.select {|message| message.match(pattern) }
-  hash[test_file] = filtered_messages if !filtered_messages.empty?
-end
+case options[:mode]
+when "merge"
+  output = DeprecationTracker::ShardMerger.new(path, delete_shards: !!options[:delete_shards]).merge
+  shards = output[:shards]
+  result = output[:result]
+  total_messages = result.values.map(&:size).reduce(0, :+)
+  puts "Merged #{shards} shard files into #{path} (#{result.size} buckets, #{total_messages} deprecation messages)"
+when "run", "info"
+  pattern_string = options.fetch(:pattern, ".+")
+  pattern = /#{pattern_string}/
+
+  deprecation_warnings = JSON.parse(File.read(path)).each_with_object({}) do |(test_file, messages), hash|
+    filtered_messages = messages.select {|message| message.match(pattern) }
+    hash[test_file] = filtered_messages if !filtered_messages.empty?
+  end
 
-if deprecation_warnings.empty?
-  abort "No test files with deprecations matching #{pattern.inspect}."
-  exit 2
-end
+  if deprecation_warnings.empty?
+    abort "No test files with deprecations matching #{pattern.inspect}."
+    exit 2
+  end
 
-case options.fetch(:mode, "info")
-when "run" then run_tests(deprecation_warnings, next_mode: options[:next], tracker_mode: options[:tracker_mode])
-when "info" then print_info(deprecation_warnings, verbose: options[:verbose])
+  if options[:mode] == "run"
+    run_tests(deprecation_warnings, next_mode: options[:next], tracker_mode: options[:tracker_mode])
+  else
+    print_info(deprecation_warnings, verbose: options[:verbose])
+  end
 when nil
-  STDERR.puts Rainbow("Must pass a mode: run or info").red
+  STDERR.puts Rainbow("Must pass a mode: run, info, or merge").red
   puts option_parser
   exit 1
 else

data/lib/deprecation_tracker/shard_merger.rb

@@ -0,0 +1,64 @@
+require "json"
+require "fileutils"
+
+class DeprecationTracker
+  class ShardMerger
+    attr_reader :base_path, :delete_shards
+
+    def initialize(base_path, delete_shards: false)
+      @base_path = base_path
+      @delete_shards = delete_shards
+    end
+
+    def merge
+      dirname = File.dirname(base_path)
+      unless File.directory?(dirname)
+        warn "Directory does not exist: #{dirname}"
+        return { shards: 0, result: {} }
+      end
+
+      shard_files = Dir.glob(shard_glob).sort
+
+      if shard_files.empty?
+        warn "No shards found at #{shard_glob}"
+        return { shards: 0, result: {} }
+      end
+
+      merged = {}
+      shard_files.each do |file|
+        parse_shard(file).each do |bucket, messages|
+          merged[bucket] = (merged[bucket] || []).concat(Array(messages))
+        end
+      end
+
+      result = {}
+      merged.sort.each do |k, v|
+        result[k] = v.sort
+      end
+
+      begin
+        File.write(base_path, JSON.pretty_generate(result))
+      rescue Errno::EACCES => e
+        raise "Cannot write to #{base_path}: #{e.message}"
+      end
+
+      shard_files.each { |f| File.delete(f) } if delete_shards
+
+      { shards: shard_files.size, result: result }
+    end
+
+    private
+
+    def shard_glob
+      "#{base_path.chomp('.json')}.node-*.json"
+    end
+
+    def parse_shard(file)
+      JSON.parse(File.read(file))
+    rescue Errno::ENOENT
+      raise "Shard file not found: #{file}"
+    rescue JSON::ParserError => e
+      raise "Invalid JSON in shard file #{file}: #{e.message}"
+    end
+  end
+end

data/lib/deprecation_tracker.rb

@@ -1,4 +1,4 @@
-require "rainbow"
+require "next_rails/tint"
 require "json"
 
 # A shitlist for deprecation warnings during test runs. It has two modes: "save" and "compare"
@@ -73,11 +73,14 @@ class DeprecationTracker
     end
   end
 
+  DEFAULT_PATH = "spec/support/deprecation_warning.shitlist.json"
+
   def self.init_tracker(opts = {})
-    shitlist_path = opts[:shitlist_path]
-    mode = opts[:mode]
+    shitlist_path = opts[:shitlist_path] || DEFAULT_PATH
+    mode = opts[:mode] || ENV["DEPRECATION_TRACKER"] || :save
     transform_message = opts[:transform_message]
-    deprecation_tracker = DeprecationTracker.new(shitlist_path, transform_message, mode)
+    node_index = opts[:node_index]
+    deprecation_tracker = DeprecationTracker.new(shitlist_path, transform_message, mode, node_index: node_index)
     # Since Rails 7.1 the preferred way to track deprecations is to use the deprecation trackers via
     # `Rails.application.deprecators`.
     # We fallback to tracking deprecations via the ActiveSupport singleton object if Rails.application.deprecators is
@@ -126,13 +129,35 @@ class DeprecationTracker
     ActiveSupport::TestCase.include(MinitestExtension.new(tracker))
   end
 
-  attr_reader :deprecation_messages, :shitlist_path, :transform_message, :bucket, :mode
+  def self.merge_shards(base_path, delete_shards: false)
+    require_relative "deprecation_tracker/shard_merger"
+    ShardMerger.new(base_path, delete_shards: delete_shards).merge[:result]
+  end
+
+  attr_reader :deprecation_messages, :shitlist_path, :transform_message, :bucket, :mode, :node_index
 
-  def initialize(shitlist_path, transform_message = nil, mode = :save)
+  def initialize(shitlist_path, transform_message = nil, mode = :save, node_index: nil)
     @shitlist_path = shitlist_path
     @transform_message = transform_message || -> (message) { message }
     @deprecation_messages = {}
-    @mode = mode.to_sym
+    @mode = mode ? mode.to_sym : :save
+    if @mode == :compare && node_index
+      raise ArgumentError, "node_index cannot be used with compare mode"
+    end
+    @node_index = node_index
+  end
+
+  def parallel?
+    !@node_index.nil?
+  end
+
+  def shard_path
+    ext = File.extname(shitlist_path)
+    "#{shitlist_path.chomp(ext)}.node-#{node_index}#{ext}"
+  end
+
+  def target_path
+    parallel? ? shard_path : shitlist_path
   end
 
   def add(message)
@@ -155,16 +180,17 @@ class DeprecationTracker
   end
 
   def compare
-    shitlist = read_shitlist
+    stored = read_json(shitlist_path)
 
     changed_buckets = []
+
     normalized_deprecation_messages.each do |bucket, messages|
-      if shitlist[bucket] != messages
+      if stored[bucket] != messages
         changed_buckets << bucket
       end
     end
 
-    if changed_buckets.length > 0
+    if changed_buckets.any?
       message = <<-MESSAGE
         ⚠️  Deprecation warnings have changed!
 
@@ -183,33 +209,33 @@ class DeprecationTracker
         See \e[4;37mdev-docs/testing/deprecation_tracker.md\e[0;31m for more information.
       MESSAGE
 
-      raise UnexpectedDeprecations, Rainbow(message).red
+      raise UnexpectedDeprecations, NextRails::Tint(message).red
     end
   end
 
   def diff
-    new_shitlist = create_temp_shitlist
-    `git diff --no-index #{shitlist_path} #{new_shitlist.path}`
+    temp_file = create_temp_file
+    `git diff --no-index #{shitlist_path} #{temp_file.path}`
   ensure
-    new_shitlist.delete
+    temp_file.delete
   end
 
   def save
-    new_shitlist = create_temp_shitlist
-    create_if_shitlist_path_does_not_exist
-    FileUtils.cp(new_shitlist.path, shitlist_path)
+    temp_file = create_temp_file
+    create_if_path_does_not_exist(target_path)
+    FileUtils.cp(temp_file.path, target_path)
   ensure
-    new_shitlist.delete if new_shitlist
+    temp_file.delete if temp_file
   end
 
-  def create_if_shitlist_path_does_not_exist
-    dirname = File.dirname(shitlist_path)
+  def create_if_path_does_not_exist(path)
+    dirname = File.dirname(path)
     unless File.directory?(dirname)
       FileUtils.mkdir_p(dirname)
     end
   end
 
-  def create_temp_shitlist
+  def create_temp_file
     temp_file = Tempfile.new("temp-deprecation-tracker-shitlist")
     temp_file.write(JSON.pretty_generate(normalized_deprecation_messages))
     temp_file.flush
@@ -219,22 +245,24 @@ class DeprecationTracker
 
   # Normalize deprecation messages to reduce noise from file output and test files to be tracked with separate test runs
   def normalized_deprecation_messages
-    normalized = read_shitlist.merge(deprecation_messages).each_with_object({}) do |(bucket, messages), hash|
-      hash[bucket] = messages.sort
-    end
+    @normalized_deprecation_messages ||= begin
+      normalized = read_json(target_path).merge(deprecation_messages).each_with_object({}) do |(bucket, messages), hash|
+        hash[bucket] = messages.sort
+      end
 
-    # not using `to_h` here to support older ruby versions
-    {}.tap do |h|
-      normalized.reject {|_key, value| value.empty? }.sort_by {|key, _value| key }.each do |k ,v|
-        h[k] = v
+      # not using `to_h` here to support older ruby versions
+      {}.tap do |h|
+        normalized.reject {|_key, value| value.empty? }.sort_by {|key, _value| key }.each do |k ,v|
+          h[k] = v
+        end
       end
     end
   end
 
-  def read_shitlist
-    return {} unless File.exist?(shitlist_path)
-    JSON.parse(File.read(shitlist_path))
+  def read_json(path)
+    return {} unless File.exist?(path)
+    JSON.parse(File.read(path))
   rescue JSON::ParserError => e
-    raise "#{shitlist_path} is not valid JSON: #{e.message}"
+    raise "#{path} is not valid JSON: #{e.message}"
   end
 end

data/lib/next_rails/bundle_report/cli.rb

@@ -3,6 +3,7 @@
 require "optparse"
 require "next_rails"
 require "next_rails/bundle_report"
+require "next_rails/tint"
 
 class NextRails::BundleReport::CLI
   def initialize(argv)
@@ -89,7 +90,7 @@ class NextRails::BundleReport::CLI
     begin
       option_parser.parse!(@argv)
     rescue OptionParser::ParseError => e
-      warn Rainbow(e.message).red
+      warn NextRails::Tint(e.message).red
       puts option_parser
       exit 1
     end

data/lib/next_rails/bundle_report/rails_version_compatibility.rb

@@ -1,3 +1,5 @@
+require "next_rails/tint"
+
 class NextRails::BundleReport::RailsVersionCompatibility
   def initialize(gems: NextRails::GemInfo.all, options: {})
     @gems = gems
@@ -20,8 +22,8 @@ class NextRails::BundleReport::RailsVersionCompatibility
   def erb_output
     template = <<-ERB
 <% if incompatible_gems_by_state[:found_compatible] -%>
-<%= Rainbow("=> Incompatible with Rails #{rails_version} (with new versions that are compatible):").white.bold %>
-<%= Rainbow("These gems will need to be upgraded before upgrading to Rails #{rails_version}.").italic %>
+<%= NextRails::Tint("=> Incompatible with Rails #{rails_version} (with new versions that are compatible):").white.bold %>
+<%= NextRails::Tint("These gems will need to be upgraded before upgrading to Rails #{rails_version}.").italic %>
 
 <% incompatible_gems_by_state[:found_compatible].each do |gem| -%>
 <%= gem_header(gem) %> - upgrade to <%= gem.latest_compatible_version.version %>
@@ -29,8 +31,8 @@ class NextRails::BundleReport::RailsVersionCompatibility
 
 <% end -%>
 <% if incompatible_gems_by_state[:incompatible] -%>
-<%= Rainbow("=> Incompatible with Rails #{rails_version} (with no new compatible versions):").white.bold %>
-<%= Rainbow("These gems will need to be removed or replaced before upgrading to Rails #{rails_version}.").italic %>
+<%= NextRails::Tint("=> Incompatible with Rails #{rails_version} (with no new compatible versions):").white.bold %>
+<%= NextRails::Tint("These gems will need to be removed or replaced before upgrading to Rails #{rails_version}.").italic %>
 
 <% incompatible_gems_by_state[:incompatible].each do |gem| -%>
 <%= gem_header(gem) %> - new version, <%= gem.latest_version.version %>, is not compatible with Rails #{rails_version}
@@ -38,16 +40,16 @@ class NextRails::BundleReport::RailsVersionCompatibility
 
 <% end -%>
 <% if incompatible_gems_by_state[:no_new_version] -%>
-<%= Rainbow("=> Incompatible with Rails #{rails_version} (with no new versions):").white.bold %>
-<%= Rainbow("These gems will need to be upgraded by us or removed before upgrading to Rails #{rails_version}.").italic %>
-<%= Rainbow("This list is likely to contain internal gems, like Cuddlefish.").italic %>
+<%= NextRails::Tint("=> Incompatible with Rails #{rails_version} (with no new versions):").white.bold %>
+<%= NextRails::Tint("These gems will need to be upgraded by us or removed before upgrading to Rails #{rails_version}.").italic %>
+<%= NextRails::Tint("This list is likely to contain internal gems, like Cuddlefish.").italic %>
 
 <% incompatible_gems_by_state[:no_new_version].each do |gem| -%>
 <%= gem_header(gem) %> - new version not found
 <% end -%>
 
 <% end -%>
-<%= Rainbow(incompatible_gems.length.to_s).red %> gems incompatible with Rails <%= rails_version %>
+<%= NextRails::Tint(incompatible_gems.length.to_s).red %> gems incompatible with Rails <%= rails_version %>
     ERB
 
     erb_version = ERB.version
@@ -63,9 +65,9 @@ class NextRails::BundleReport::RailsVersionCompatibility
   end
 
   def gem_header(_gem)
-    header = Rainbow("#{_gem.name} #{_gem.version}").bold
-    header << Rainbow(" (loaded from git)").magenta if _gem.sourced_from_git?
-    header
+    parts = [NextRails::Tint("#{_gem.name} #{_gem.version}").bold]
+    parts << NextRails::Tint(" (loaded from git)").magenta if _gem.sourced_from_git?
+    parts.join
   end
 
   def incompatible_gems

data/lib/next_rails/bundle_report/ruby_version_compatibility.rb

@@ -1,4 +1,4 @@
-require "rainbow"
+require "next_rails/tint"
 
 class NextRails::BundleReport::RubyVersionCompatibility
   MINIMAL_VERSION = 1.0
@@ -10,20 +10,20 @@ class NextRails::BundleReport::RubyVersionCompatibility
   end
 
   def generate
-    return invalid_message unless valid?
-
-    message
+    (valid? ? message : invalid_message).to_s
   end
 
   private
 
   def message
-    output = Rainbow("=> Incompatible gems with Ruby #{ruby_version}:").white.bold
+    noun = incompatible.one? ? "gem" : "gems"
+    parts = [NextRails::Tint("=> Incompatible gems with Ruby #{ruby_version}:").white.bold]
     incompatible.each do |gem|
-      output += Rainbow("\n#{gem.name} - required Ruby version: #{gem.gem_specification.required_ruby_version}").magenta
+      parts << NextRails::Tint("#{gem.name} - required Ruby version: #{gem.gem_specification.required_ruby_version}").magenta
     end
-    output += Rainbow("\n\n#{incompatible.length} incompatible #{incompatible.one? ? 'gem' : 'gems' } with Ruby #{ruby_version}").red
-    output
+    parts << ""
+    parts << NextRails::Tint("#{incompatible.length} incompatible #{noun} with Ruby #{ruby_version}").red
+    parts.join("\n")
   end
 
   def incompatible
@@ -35,7 +35,7 @@ class NextRails::BundleReport::RubyVersionCompatibility
   end
 
   def invalid_message
-    Rainbow("=> Invalid Ruby version: #{options[:ruby_version]}.").red.bold
+    NextRails::Tint("=> Invalid Ruby version: #{options[:ruby_version]}.").red.bold
   end
 
   def valid?

data/lib/next_rails/bundle_report.rb

@@ -1,4 +1,4 @@
-require "rainbow"
+require "next_rails/tint"
 require "cgi"
 require "erb"
 require "json"
@@ -105,14 +105,14 @@ module NextRails
         header = "#{gem.name} #{gem.version}"
 
         puts <<-MESSAGE
-          #{Rainbow(header).bold.white}: released #{gem.age} (latest version, #{gem.latest_version.version}, released #{gem.latest_version.age})
+          #{NextRails::Tint(header).bold.white}: released #{gem.age} (latest version, #{gem.latest_version.version}, released #{gem.latest_version.age})
         MESSAGE
       end
 
       percentage_out_of_date = ((out_of_date_gems.count / total_gem_count.to_f) * 100).round
       footer = <<-MESSAGE
-        #{Rainbow(sourced_from_git_count.to_s).yellow} gems are sourced from git
-        #{Rainbow(out_of_date_gems.count.to_s).red} of the #{total_gem_count} gems are out-of-date (#{percentage_out_of_date}%)
+        #{NextRails::Tint(sourced_from_git_count.to_s).yellow} gems are sourced from git
+        #{NextRails::Tint(out_of_date_gems.count.to_s).red} of the #{total_gem_count} gems are out-of-date (#{percentage_out_of_date}%)
       MESSAGE
 
       puts ''

data/lib/next_rails/tint.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module NextRails
+  # Lightweight ANSI color/style wrapper with chainable style methods.
+  # Wrap a string with `NextRails::Tint("text")` then chain styles:
+  #
+  #   NextRails::Tint("hello").red.bold
+  #
+  # Instances are effectively immutable: each style method returns a new
+  # `Tint` rather than mutating the receiver, so a reference can be reused
+  # without styles accumulating across chains.
+  class Tint
+    CODES = {
+      bold: 1,
+      italic: 3,
+      red: 31,
+      green: 32,
+      yellow: 33,
+      blue: 34,
+      magenta: 35,
+      cyan: 36,
+      white: 37
+    }.freeze
+
+    def initialize(string, codes = [])
+      @string = string.to_s
+      @codes = codes
+    end
+
+    CODES.each_key do |style|
+      define_method(style) do
+        self.class.new(@string, @codes + [CODES[style]])
+      end
+    end
+
+    def to_s
+      return @string if @codes.empty?
+
+      "\e[#{@codes.join(";")}m#{@string}\e[0m"
+    end
+    alias_method :to_str, :to_s
+  end
+
+  def self.Tint(string)
+    Tint.new(string)
+  end
+end

data/lib/next_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NextRails
-  VERSION = "1.5.0"
+  VERSION = "1.6.0"
 end

data/next_rails.gemspec

@@ -22,8 +22,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "rainbow", ">= 3"
-  spec.add_development_dependency "bundler", ">= 1.16", "< 3.0"
+  spec.add_development_dependency "bundler", ">= 1.16"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "simplecov", "~> 0.17.1"

metadata

@@ -1,29 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: next_rails
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Ernesto Tagwerker
 - Luis Sagastume
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-02 00:00:00.000000000 Z
+date: 2026-05-07 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: rainbow
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -31,9 +18,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.16'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -41,9 +25,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.16'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -194,6 +175,7 @@ files:
 - exe/next.sh
 - exe/next_rails
 - lib/deprecation_tracker.rb
+- lib/deprecation_tracker/shard_merger.rb
 - lib/next_rails.rb
 - lib/next_rails/bundle_report.rb
 - lib/next_rails/bundle_report/cli.rb
@@ -201,6 +183,7 @@ files:
 - lib/next_rails/bundle_report/ruby_version_compatibility.rb
 - lib/next_rails/gem_info.rb
 - lib/next_rails/init.rb
+- lib/next_rails/tint.rb
 - lib/next_rails/version.rb
 - next_rails.gemspec
 - pull_request_template.md
@@ -208,6 +191,7 @@ homepage: https://github.com/fastruby/next_rails
 licenses:
 - MIT
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -222,7 +206,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: A toolkit to upgrade your next Rails application
 test_files: []