2.1: delete the legacy namespace trees and the driver abstraction

[pftg]

Draft. Nothing ships until the 2.1 plan is approved. No version bump, no CHANGELOG entry, no release.

Supersedes snap-diff#240, which was opened before snap-diff#242/snap-diff#245/snap-diff#246/snap-diff#247/snap-diff#248 landed and before the scope grew to include the driver abstraction. Redone from current origin/master (1cd89c9) rather than rebased — see Rebase or redo.

2.0 is the transitional release: both APIs work and everything that dies warns. 2.1 is the single cleanup release. There is no 3.0.

---

Migrating from 2.0 to 2.1

Measured, not imagined: a real consumer (a Jekyll/Rails site with committed visual baselines, running its suite in Docker) was upgraded end to end against this deletion. 17 lines, two files, zero blockers — 38 runs, 0 failures, 55 screenshots compared, byte-identical before and after. Every v1 API had a canonical equivalent.

That validation covered the namespace half. The driver half is new in this PR and is the part most likely to touch your config — read Drivers and image processing even if you never used the v1 names.

1. Namespaces

Requires

before	after
require "capybara_screenshot_diff/minitest"	require "snap_diff/integrations/minitest"
require "capybara_screenshot_diff/rspec"	require "snap_diff/integrations/rspec"
require "capybara_screenshot_diff/cucumber"	require "snap_diff/integrations/cucumber"
require "capybara_screenshot_diff/reporters/html"	require "snap_diff/reporters/html"
require "capybara/screenshot/diff"	require "snap_diff"
gem "capybara-screenshot-diff" (Bundler auto-require)	gem "snap_diff-capybara"

Configuration

Both v1 holders collapse into one object. SnapDiff.configure is the single config entry point (ADR-008).

before	after
Capybara::Screenshot.<setting> = …	SnapDiff.config.<setting> = …
Capybara::Screenshot::Diff.<setting> = …	SnapDiff.config.<setting> = …
Capybara::Screenshot::Diff.configure { |screenshot, diff| … }	SnapDiff.configure { |config| … }
SnapDiff.start { |screenshot, diff| … }	SnapDiff.configure { |config| … }

SnapDiff.start yielded the two v1 holders, so it could not outlive them — removed, not renamed. Same for SnapDiff.silence_deprecations and SNAP_DIFF_SILENCE_DEPRECATIONS: with no deprecations left to emit there is nothing to silence.

Constants and includes

before	after
Capybara::Screenshot::Os.name	SnapDiff::Os.name
Capybara::Screenshot::Diff::ImageCompare	SnapDiff::Comparison
CapybaraScreenshotDiff::Reporters::HTML	SnapDiff::Reporters::HTML
CapybaraScreenshotDiff::ScreenshotAssertion	SnapDiff::ScreenshotAssertion
include CapybaraScreenshotDiff::DSL include CapybaraScreenshotDiff::Minitest::Assertions	include SnapDiff::Minitest::Assertions — the two collapse into one

Capybara::Screenshot::Os is the one to grep for. In the real upgrade it was the only hard crash: on 2.0 it raises NameError from the shim internals once the require line has been migrated but the constant has not — a partially-migrated setup looks fine (config setters keep working) until Os aborts the whole suite before a single test runs. On 2.1 it is simply gone.

2. Drivers and image processing

libvips is now the only backend, and ruby-vips is a gemspec runtime dependency (>= 2.0, < 3). You no longer add it yourself; Bundler installs it. libvips itself is still a system package (brew install vips, apt-get install libvips), and without it the gem cannot compare images at all.

Making it a real dependency is the point: before this, neither driver was declared, so a box without either got a runtime error deep in a test run. Now it is a resolver error at bundle install.

before	after
gem "ruby-vips" in your Gemfile	delete it (harmless to keep)
SnapDiff.config.driver = :vips / = :auto / = :chunky_png	delete the line
screenshot "index", driver: :vips	delete the option
shift_distance_limit (anywhere)	no equivalent — see below
SnapDiff::Drivers.available to branch on what is installed	nothing to branch on
SnapDiff::Drivers.loaded[:mine] = MyDriver	no replacement
include SnapDiff::Driver in your own driver	no replacement

What breaks loudly vs. quietly

Worth knowing before you upgrade:

• SnapDiff.config.driver = :vips raises NoMethodError: undefined method 'driver=' at config time, before any test runs. Loud, greppable, one line to delete.
• screenshot "index", driver: :vips is silently ignored — per-screenshot options are a free-form hash, so an unknown key is inert. It does not change behaviour (there is one backend), but nothing tells you the line is dead. Grep for it.
• shift_distance_limit behaves the same way: NoMethodError on the config object, silently ignored per screenshot.

shift_distance_limit has no replacement

It was implemented only by the chunky_png driver, and libvips has no shift-distance comparison. Use one of:

instead	why
median_filter_window_size	the same idea and far faster — smooths the image before comparing
tolerance	allows a ratio of pixels to differ, wherever they are
color_distance_limit	allows each pixel to differ by a colour distance

Numbers in failure messages change

If you assert on comparison output, note that libvips reports differently from chunky_png: area_size and region come out as floats, and there is no max_color_distance. For the a/c test fixtures:

before (chunky_png):  ({"area_size":629,"region":[11,3,48,20],"max_color_distance":187.4})
after  (libvips):     ({"area_size":684.0,"region":[11.0,3.0,49.0,21.0]})

This only surfaced now because a Comparison built without an explicit driver: defaulted to chunky_png (Drivers.for did fetch(:driver, :chunky_png)). Anyone going through the normal DSL was already on libvips via driver: :auto.

Custom drivers: there is no migration path

The abstraction is removed whole — the SnapDiff::Driver mixin, the SnapDiff::Drivers registry (.loaded, .available, .for, .registry, .detect_available), AVAILABLE_DRIVERS, Utils.detect_available_drivers, and :auto selection. A third-party driver stops working on 2.1 and nothing replaces it. This is a deliberate call, not an oversight: one backend is what keeps every option meaning one thing. If you maintain one, say so on the issue tracker — that is the only thing that can reopen it.

SnapDiff::Drivers::VipsDriver survives, and SnapDiff::Drivers survives as its namespace — not as a registry.

---

The driver: setting: removed, and why

The open question was whether driver: survives as an accept-and-ignore knob. Removed. Reasoning:

1. Accept-and-ignore is exactly the dead knob this release exists to delete. Worse: a config reading driver: :chunky_png would keep comparing on libvips, i.e. actively lie about which backend runs.
2. Removal fails at the right moment. NoMethodError: undefined method 'driver=' fires at config time, before a single test, naming the exact line. An ignored setting fails nowhere and is discovered when someone wonders why tuning it does nothing.
3. Almost nobody set it to something that mattered. :vips and :auto-with-libvips-present already selected what 2.1 does unconditionally; the real-world validation consumer never set it at all. The two values that did change behaviour (:chunky_png, :auto falling back to chunky) are precisely the ones 2.0 warns about.
4. The migration is one deleted line, documented above.

The honest caveat is in What breaks loudly vs. quietly: the per-screenshot driver: form is silently ignored rather than raising, because per-screenshot options are a free-form hash. Adding validation there would be a new feature in a deletion release; it is documented instead.

---

A bug the deletion exposed (and fixes)

libvips served stale images. libvips caches loader operations keyed on filename + mtime, and mtime has one-second resolution — so rewriting a screenshot path and re-reading it within the same second handed back the previous image. This gem does exactly that: the screenshoter writes <name>.png, checkout_base_screenshot writes <name>.base.png from VCS, and the comparison then reads both.

It was latent because comparisons built without an explicit driver defaulted to chunky_png, which always re-reads. With libvips as the only backend it became the only behaviour — and it turned identical images into "different" and vice versa. Reproduced directly:

load1 avg=160.370664   # b.png
load2 avg=160.370664   # after overwriting the path with a.png -- STALE
direct a.png avg=160.664102

Fix: VipsDriver#from_file passes revalidate: true (libvips 8.15+, gated on Vips.at_least_libvips?(8, 15)). Two cache-flush workarounds that had been papering over this — Vips.cache_set_max(0); Vips.cache_set_max(1000) in test/system_test_case.rb and vips_driver_test.rb teardowns — are deleted. A regression test pins it, and goes red when revalidate is removed.

---

What this deletes

lib/capybara/, lib/capybara_screenshot_diff/, lib/capybara-screenshot-diff.rb, lib/capybara_screenshot_diff.rb, lib/snap_diff/legacy_shims.rb, lib/snap_diff/deprecation.rb, lib/snap_diff/removal.rb, lib/snap_diff/driver.rb, lib/snap_diff/drivers.rb, lib/snap_diff/drivers/chunky_png_driver.rb, lib/snap_diff/utils.rb, test/legacy/, and six driver/deprecation test files.

59 files deleted (3 751 lines). Whole diff: 101 files, +680 / −4 494 — a net 3 814 lines removed.

area	change
lib/	52 files, +88 / −1 605
test/	37 files, +438 / −2 594
docs/ + README	5 files, +110 / −219

lib/ is down to 34 packaged files.

Fallout beyond the deletions

• test/test_helper.rb — SnapDiff::Deprecation.suppress_migration_notice!, SnapDiff::Removal.suppress! and the Warning guard that raised on any [snap_diff deprecation] line all go; the channel that emitted them no longer exists. The DriverCoverage banner/abort goes too: it guarded against a silent fallback to chunky_png, and a missing libvips is now a require "vips" LoadError at boot.
• Rakefile — test:canonical was "everything except test/legacy/", which is now exactly test; the two converged and the second name is deleted rather than kept as an alias for one thing. rake test is THE gate. test:benchmark is deleted: it required scripts/benchmark/find_region_benchmark, which is not in this repo, so it raised LoadError on every invocation, and its body named a v1 constant.
• .github/workflows/test.yml — the screenshot-driver: [vips, chunky_png] matrix axis is gone (half the cells, same coverage), as is SCREENSHOT_DRIVER everywhere. The job id matrix-screenshot-driver is renamed matrix-capybara-driver. ⚠️ Matrix check names change regardless (2 dimensions → 1), so branch protection needs a look.
• scripts/generate_sample_report.rb (rake report:sample) and bin/console loaded v1 entry points; repointed and both verified running.
• gems.rb — chunky_png, oily_png and the explicit ruby-vips line removed (the last is now a gemspec runtime dep).
• ImagePreprocessor — the driver.supports?(:filter_image_with_median) probe and its warning fallback are deleted. They existed because chunky_png did not implement median filtering; libvips does, so the branch was unreachable. supports? went with the mixin.

Gate dispositions

gate	disposition	why
test/legacy/legacy_tree_is_alias_only_test.rb	dies	it proved the v1 trees held no logic; the trees are gone
test/unit/legacy_deletion_test.rb	replaced	it simulated the deletion (copy lib/, rm, probe in a subprocess) because the trees were still there. They are not, and support_load_probe_test.rb already runs the same entry-point and advertised-constant tables against the real lib/ on every run
test/unit/removed_surface_test.rb	new	keeps the one claim nothing else makes — absence
test/unit/core_tree_has_no_legacy_deps_test.rb	kept, repurposed	a legacy require in lib/ now fails by itself, but a docstring or user-facing message naming Capybara::Screenshot.* survives the deletion and starts lying. Its exclusion list is empty (both files were deleted, not exempted) and it gained a REMOVED_SURFACE pattern for the driver half
test/unit/canonical_suite_has_no_legacy_refs_test.rb	kept, repurposed	same reasoning for the test tree; it stopped predicting a future deletion and now catches removed names in strings, heredocs and messages. Its pattern list grew to cover SnapDiff::Removal, SnapDiff::Driver, the registry methods and silence_deprecations
test/unit/support_load_probe_test.rb	kept, unchanged	it already measured the real lib/

Gate line discipline

removed_surface_test.rb runs a subprocess, so it carries a gate line that runs before any absence assertion. The trap here is the inverse of the one that bit us twice: the subject is the real lib/, so the risk is measuring an installed copy of the gem, or measuring nothing at all — "the constant is gone" and "nothing was ever loaded" look identical. The gate asserts snap_diff files were loaded, that every one came from this repo's lib/ (anchored on the library path, not a bare /snap_diff/ substring — CI checks out into a directory of that name), and two positive controls. It chdirs to a tmpdir and scrubs RUBYOPT/BUNDLE_GEMFILE/RUBYLIB, because with the cwd inside the project RubyGems re-adds -rbundler/setup and the gemspec unshifts lib/ ahead of any -I. A dedicated test proves the gate line rejects a process that loaded nothing.

Mutation checks (every gate broken, watched to fail, restored)

mutation	gate	result
touch lib/snap_diff/removal.rb	removed-path check	RED — Expected ["snap_diff/removal.rb"] to be empty
add def self.start to snap_diff.rb	fresh-process absence	RED — still defined: SnapDiff.start
put shift_distance_limit in a lib/ string	core_tree_has_no_legacy_deps	RED — config.rb:98: names a surface 2.1 removed
drop revalidate: from from_file	vips staleness regression	RED — vips served the cached b.png after the path was overwritten

What remains of driver-contract coverage

test/support/driver_contract_tests.rb is kept, with one includer instead of two. It stops being a shared contract and becomes the pin on the interface Comparison, ImagePreprocessor, Screenshoter and AnnotationService all call — signatures, arity, and load_images slot order, all of which would break those callers silently if they drifted. Behavioural option coverage (tolerance, color_distance_limit, skip_area, resize, missing-file errors) is still meaningful against one driver.

What is honestly lost: the value of running identical expectations against two implementations, which is what a contract test is normally for. And supports?(feature) is gone — it existed so ImagePreprocessor could ask whether a driver implemented median filtering, a question with one answer now. filter_image_with_median was added to the interface list to compensate, since nothing else asserts it exists.

Deleted outright: chunky_png_driver_test.rb, drivers_test.rb (registry/detection), drivers/utils_test.rb (detection), driver_coverage_test.rb + test/support/driver_coverage.rb, removed_in_2_1_deprecation_test.rb (its six warnings are what this release makes true).

---

Suites

$ mise x ruby@4.0.6 -- bundle exec rake test
Finished in 34.783017s, 8.9124 runs/s, 24.9835 assertions/s.
310 runs, 869 assertions, 0 failures, 0 errors, 1 skips

$ mise x ruby@4.0.6 -- bundle exec rake test:unit
Finished in 24.697212s, 11.4183 runs/s, 33.3641 assertions/s.
282 runs, 824 assertions, 0 failures, 0 errors, 0 skips

$ mise x ruby@4.0.6 -- bundle exec rake test:integration
Finished in 18.676421s, 1.4992 runs/s, 2.4095 assertions/s.
28 runs, 45 assertions, 0 failures, 0 errors, 1 skips

$ mise x ruby@4.0.6 -- bundle exec standardrb
102 files inspected, no offenses detected

$ mise x ruby@4.0.6 -- bundle exec rake test:canonical
Don't know how to build task 'test:canonical'   # collapsed into `test`

Baseline on origin/master (1cd89c9) was 613 runs, 0 failures, 1 skip for rake test, 585 for test:unit and 482/0/1 for test:canonical. The drop is test/legacy/ (9 files), the deletion simulation, and the driver/deprecation tests leaving, minus the new gate arriving. The one skip is BrowserScreenshotTest#test_animated_example, an optional_test — the same skip as baseline.

Also verified: gem build succeeds and packages 34 lib/ files with capybara and ruby-vips as runtime dependencies; rake report:sample and bin/console both run against the repointed entry points.

---

Rebase or redo

Redone from scratch. snap-diff#240's diff touched files that snap-diff#246/snap-diff#247/snap-diff#248 subsequently rewrote — removal.rb did not exist when it was opened, deletion_3_0_test.rb was renamed and its constants with it, the Rakefile header was rewritten — so nearly every file it touched would have conflicted. The scope also roughly doubled (drivers, chunky_png, shift_distance_limit, the gemspec dependency). Starting from current origin/master was the smaller job.

Deliberately not done here: the v1 docs sweep

The driver half of the docs is updated: docs/drivers.md is rewritten as "Image Processing" (libvips only), docs/configuration.md loses the shift_distance_limit section and the ChunkyPNG comparison columns, docs/snapdiff.md's custom-driver section becomes the no-migration-path note, docs/architecture.md's driver layer and file layout are corrected, and the README's install/requirements blocks are updated.

The v1 namespace half is left out to keep this diff reviewable — same call snap-diff#240 made. Still describing the old surface as present, by match count: docs/UPGRADING.md · docs/migration-guide.md · docs/framework-setup.md · docs/architecture.md (lines 5, 219, 293) · docs/configuration.md (the legacy two-holder config block) · docs/organization.md · docs/thread_safety.md · docs/reporters.md · CONTRIBUTING.md. Not all are wrong — a migration guide must name the old API — but every one needs a read.

For the reviewer

Removing a public API in a MINOR departs from semver. It does. The mitigation is that it is announced rather than surprising: 2.0's release notes, docs/UPGRADING.md and the runtime migration notice all say "removed in 2.1" explicitly, so the contract is published before it is enforced. On 2.0 a v1 user gets working legacy names, a per-constant warning carrying their own file:line, and one migration notice per process pointing at the guide — and since snap-diff#246, six more warnings covering exactly the driver half this PR removes.

[pftg]

Opened against the wrong remote by mistake; the upstream is snap-diff/snap_diff-capybara. Reopening there.