Add deprecations merge command to combine parallel CI shards

[JuanVqz]

Summary

Adds a deprecations merge CLI command and DeprecationTracker::ShardMerger class to combine shard files produced by parallel CI nodes into a single canonical shitlist file.

This is the companion to #176 (parallel CI support). When each CI node writes its own shard (e.g. deprecation_warning.shitlist.node-0.json), a fan-in step is needed to merge them before the compare phase.

Changes

• DeprecationTracker::ShardMerger — new class in lib/deprecation_tracker/shard_merger.rb with deep-merge logic (concatenates arrays for overlapping buckets), fixing the data loss bug from Adds support to print info for multiple files. #83 where inject(:merge) silently dropped warnings when multiple shards shared the same keys.
• deprecations merge CLI subcommand — with --delete-shards to clean up after merging and --next for the next Rails shitlist.
• DeprecationTracker.merge_shards — convenience class method that delegates to ShardMerger.
• Error handling — clear messages for missing shard files, invalid JSON, and write permission errors.
• 8 specs in dedicated spec/shard_merger_spec.rb covering: multiple shards, overlapping buckets, no shards, single shard, delete/preserve shards, sort order, and invalid JSON.
• README updated with parallel CI docs, merge command usage, and example CI workflow.
• CHANGELOG updated for both Add parallel CI support for DeprecationTracker #176 and this PR.

Example CI workflow

# 1. Save phase (each parallel node)
DEPRECATION_TRACKER=save CI_NODE_INDEX=$NODE bundle exec rspec <subset>

# 2. Merge phase (fan-in, runs once)
deprecations merge --delete-shards

# 3. Compare phase (each parallel node)
DEPRECATION_TRACKER=compare CI_NODE_INDEX=$NODE bundle exec rspec <subset>

Test plan

• bundle exec rspec spec/deprecation_tracker_spec.rb spec/shard_merger_spec.rb — 42 examples, 0 failures
• Manual test with 3 shard files containing overlapping buckets — all deprecation messages preserved
• --delete-shards removes shard files, canonical file remains
• CI passes

[JuanVqz]

If you want to test locally, here you have some fake deprecation warnings shitlist.zip

[arielj]

can these files have any extension other than json? I understand this gem generates json files and if they are anything other than json this would fail to parse them, just thinking this code gives the impression that other extensions might be supported, not sure if that's a real usecase

[arielj]

Is there a reason this block is here? there's a case statement to handle different mode values in https://github.com/fastruby/next_rails/pull/177/changes#diff-783442139b98c9b57ce8c777eba311b67f52d1e560f4d75db2190ab290ce4d10R121

also line 125 should be updated to mention the merge mode too https://github.com/fastruby/next_rails/pull/177/changes#diff-783442139b98c9b57ce8c777eba311b67f52d1e560f4d75db2190ab290ce4d10R125

[arielj]

can this ever happen? I mean, if the directory does not exist then there will not be shards to merge either since the code looks for them inside the base_path directory, so nothing to write either (it would write an empty {} json file)

I wonder if it's better instead to print some output saying the are no shards to merge (or even that the directory does not exist) instead, that could help users identify typos for example (instead of having to figure out why they have an empty file we could say "The .... path does not exist" and "No shards found at ...", since they are using the merge mode they probably meant to have shards here)

[arielj]

is there a reason to require this file inside the if block? looks kinda weird, we don't do that anywhere else in the project

I would get it if it was something really expensive to require in terms of loading a bunch of extra stuff that we don't need, but it's a super simple file