feat: everything 2.1 removes warns in 2.0, and nothing is silent

docs/UPGRADING.md

@@ -172,8 +172,13 @@ This means you can migrate your codebase incrementally **now**, before opting in
 
 ### Deprecation Warnings
 
-v2.0 emits three different things, and it is worth knowing which is which. The first two are
-about the old namespaces; the third is about the driver features 2.1 removes.
+v2.0 emits four different things, and it is worth knowing which is which. The first two are
+about the old namespaces; the third is about the driver features 2.1 removes; the fourth is
+about options that never did anything.
+
+Everything 2.1 removes warns in 2.0, and every warning names 2.1. Nothing you can still write
+in 2.0 does nothing quietly — if a setting is on its way out, or was never read at all, you
+hear about it once per process.
 
 #### 1. The migration notice — one line per process
 
@@ -185,12 +190,29 @@ The first time a process touches *any* hookable legacy API, you get a single lin
 
 It fires once and never again, whichever door you came through:
 
+- **requiring a v1-named entry point** — `require "capybara/screenshot/diff"`,
+  `"capybara-screenshot-diff"`, `"capybara_screenshot_diff"`, or any of
+  `capybara_screenshot_diff/{dsl,minitest,rspec,cucumber}`. With `gem "capybara-screenshot-diff"`
+  in the Gemfile, `Bundler.require` opens this door for you at boot.
 - a legacy config accessor — `Capybara::Screenshot.window_size = ...`, `Capybara::Screenshot::Diff.tolerance`
 - a lazily shimmed legacy constant (see below)
 - `include Capybara::Screenshot` / `include Capybara::Screenshot::Diff`
 
 It exists because most of the v1 surface **cannot** warn per use, so without it a 2.x app could
-be entirely silent right up to the bare `NameError` it would get on 2.1.
+be entirely silent right up to the bare `NameError` it would get on 2.1. The require door is
+what makes the rest of the list a safety net rather than the only mechanism: a suite that
+requires the gem and only calls `screenshot` touches none of the other four.
+
+The canonical entry points — `require "snap_diff"`, `"snap_diff-capybara"`, `"snap_diff/dsl"`,
+`"snap_diff/integrations/*"` — never fire it, even though `snap_diff-capybara` loads the v1
+compatibility files internally.
+
+> **Silencing a require-time notice needs the env var.** `SnapDiff.silence_deprecations = true`
+> only takes effect from the line that sets it, and you cannot set it before the require that
+> defines `SnapDiff`. Under `Bundler.require` there is no earlier moment at all. Use
+> `SNAP_DIFF_SILENCE_DEPRECATIONS=1` in the environment, or
+> `require "snap_diff/deprecation"; SnapDiff.silence_deprecations = true` ahead of everything
+> else.
 
 #### 2. Per-constant warnings — one line per lazily shimmed constant
 
@@ -227,19 +249,15 @@ warns once per process per subject, through the same channel and the same silenc
 | read `SnapDiff::Drivers.loaded` (the custom-driver registry) | the registry | nothing — custom drivers are removed, see below |
 | read `SnapDiff::Drivers.available` | driver detection | require `ruby-vips` instead of branching on a detected list |
 | `include SnapDiff::Driver` in your own driver class | the driver mixin | nothing — see below |
+| set a driver **at all** — `SnapDiff.config.driver =`, the legacy `Capybara::Screenshot::Diff.driver =`, or `screenshot "index", driver: …` | the `driver` setting and the `driver:` option | delete the line. With libvips the only backend there is nothing to select |
 
-> **The one removal on this list that 2.0 cannot warn you about: the `driver:` setting
-> itself.** `SnapDiff.config.driver = :vips` and the legacy
-> `Capybara::Screenshot::Diff.driver = :vips` are **silent** in 2.0 and raise
-> `NoMethodError: undefined method 'driver='` in 2.1, at config time before any test runs.
-> The per-screenshot form — `screenshot "index", driver: :vips` — is silent in 2.0 **and**
-> in 2.1: per-screenshot options are a free-form hash, so an unknown key is simply inert.
-> Warning on any of this would fire on the recommended configuration, so this note is the
-> warning: **delete the line, and grep for the per-screenshot one.** With libvips the only
-> backend there is nothing to select, and the default just works. The same goes for
-> `driver: :auto` on a machine that *has* `ruby-vips` — the `:auto` warning above only
-> fires when `:auto` actually falls back to ChunkyPNG, because that is the case where 2.1
-> stops the process comparing at all.
+> **`driver: :vips` warns too, and that is deliberate.** The warning is not about the *value*
+> you picked — it is about the setting existing. `SnapDiff.config.driver = :vips` raises
+> `NoMethodError: undefined method 'driver='` in 2.1, at config time before any test runs, and
+> `screenshot "index", driver: :vips` becomes an `ArgumentError` for an unknown option. Both
+> are lines to delete, not lines to change. `driver: :auto` on a machine that *has* libvips is
+> the one place the option still says something — and the `:auto` row above covers the case
+> that matters, where `:auto` silently lands on ChunkyPNG.
 
 ```
 [snap_diff deprecation] `driver: :auto` selected chunky_png because libvips is not available in this process. The chunky_png driver is REMOVED in 2.1, when libvips (the `ruby-vips` gem) becomes required -- install it now, or this setup stops comparing on 2.1. See docs/drivers.md. Silence with `SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. (shown once per process) (called from /app/test/test_helper.rb:12)
@@ -259,12 +277,27 @@ so warning there would fire on setups that are not affected by anything on this
 detection (`SnapDiff::Drivers.detect_available` / `SnapDiff::Utils.detect_available_drivers`)
 runs at load, before any user code.
 
+#### 4. Unknown screenshot options — warned in 2.0, raised in 2.1
+
+Per-screenshot options used to be a free-form hash: anything the gem did not read was frozen,
+carried around, and ignored. A misspelt `tolerence:` bought you a green suite that compared
+nothing and never said so. 2.0 warns once per unknown key; 2.1 raises `ArgumentError`.
+
+```
+[snap_diff deprecation] `:tolerence` is not a recognised screenshot option, so it does nothing. 2.1 raises ArgumentError for it. Check the spelling against the option list in docs/configuration.md. Silence with `SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. (shown once per process) (called from /app/test/features/home_test.rb:14)
+```
+
+It applies to every route into a comparison — `screenshot`, `assert_matches_screenshot`,
+`capture_screenshot` and `SnapDiff.compare`. Recognised keys are `area_size_limit`,
+`capybara_screenshot_options`, `color_distance_limit`, `crop`, `delayed`, `driver`,
+`median_filter_window_size`, `perceptual_threshold`, `screenshot_format`,
+`shift_distance_limit`, `skip_area`, `stability_time_limit`, `tolerance` and `wait`.
+
 #### Silent by design
 
 Some legacy names never warn individually, and that is deliberate — the migration notice above is
 the signal for all of them:
 
-- **Requiring the gem.** `require "capybara_screenshot_diff/minitest"` etc. is not deprecated.
 - **The DSL.** `screenshot`, `assert_matches_screenshot`, `capture_screenshot` are never deprecated.
 - **Settings access.** `Capybara::Screenshot.blur_active_element`, `Capybara::Screenshot::Diff.tolerance=`
   and the `Diff.configure` block are plain delegators onto `SnapDiff.config`. There is no
@@ -363,7 +396,7 @@ All settings and baselines are compatible with v1.x. Simply pin your Gemfile bac
 - [ ] Run your system tests (`bin/rails test:system`, not `rake test`) to verify no regressions
 - [ ] Read the warnings it prints — each one names something 2.1 removes
 - [ ] Add `gem "ruby-vips"` if you are not already on it (2.1 makes libvips the only backend)
-- [ ] Drop `driver:` from your config — it is silent in 2.0 and gone in 2.1
+- [ ] Drop `driver:` from your config and your `screenshot` calls — 2.0 warns about it, 2.1 removes it
 - [ ] (Optional, but do it before 2.1) Migrate config and constants to the `SnapDiff` namespace
 - [ ] (Optional) Silence deprecation warnings if not ready to migrate
 - [ ] Report anything surprising on [the issue tracker](https://github.com/snap-diff/snap_diff-capybara/issues)

lib/capybara-screenshot-diff.rb

@@ -3,4 +3,10 @@
 # Bundler.require entry point for `gem "capybara-screenshot-diff"` -- the v1
 # gem name, deleted in 3.0. The surviving name owns the logic (including the
 # minitest feature detection this door needs just as much).
+#
+# The marker goes BEFORE that require: snap_diff-capybara claims the process
+# as canonical, and a marker after it would be swallowed.
+require "snap_diff/deprecation"
+SnapDiff::Deprecation.legacy_entry_point!
+
 require "snap_diff-capybara"

lib/capybara_screenshot_diff.rb

@@ -1,5 +1,12 @@
 # frozen_string_literal: true
 
+# The v1 umbrella, and the file every legacy entry point except
+# capybara_screenshot_diff/dsl reaches. Marked here rather than in each of
+# them; snap_diff-capybara.rb (which loads this umbrella for canonical
+# users) claims the process first, so this stays quiet for them.
+require "snap_diff/deprecation"
+SnapDiff::Deprecation.legacy_entry_point!
+
 require "capybara/dsl"
 require "capybara/screenshot/diff/config_legacy"
 require "capybara/screenshot/diff/version"

lib/capybara_screenshot_diff/dsl.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# The one legacy entry point that does NOT go through the umbrella, so it
+# carries its own marker.
+require "snap_diff/deprecation"
+SnapDiff::Deprecation.legacy_entry_point!
+
 require "snap_diff/dsl"
 
 # Deliberately EAGER and silent (v2 step 6 exception): DSL is an advertised

lib/snap_diff-capybara.rb

@@ -18,6 +18,12 @@
 # zero-require Rails path and still activates the assertions. Absent gets a
 # line saying so -- a gem that loads and then does nothing, silently, is its
 # own bug report.
+# This IS the canonical door, and it loads the v1 umbrella below -- so claim
+# the process before that require, or every canonical user is told to
+# migrate off an API they never touched.
+require "snap_diff/deprecation"
+SnapDiff::Deprecation.canonical_entry_point!
+
 require "capybara_screenshot_diff"
 
 begin

lib/snap_diff.rb

@@ -65,6 +65,10 @@ module SnapDiff
   # Note the argument order swap: callers pass baseline first (reading
   # "compare baseline against current"), Comparison takes current first.
   def self.compare(baseline_path, current_path, **options)
+    # BEFORE the merge, which is the last moment `driver:` still means "the
+    # caller asked for a backend" rather than "config.default_options
+    # carries the key for everyone".
+    Removal.warn_once(:driver_setting, Removal::DRIVER_REMOVED) if options.key?(:driver)
     Comparison.new(current_path, baseline_path, config.default_options.merge(options))
   end
 

lib/snap_diff/comparison.rb

@@ -43,6 +43,31 @@ def skip_area
 
     TOLERABLE_OPTIONS = [:tolerance, :color_distance_limit, :shift_distance_limit, :area_size_limit].freeze
 
+    # Every key anything downstream of here actually reads -- capture
+    # options included, because ScreenshotMatcher hands the same hash to the
+    # screenshoter and only carves :crop / :stability_time_limit / :wait out
+    # of the copy it passes on.
+    #
+    # Written out rather than derived from Config#default_options: that hash
+    # is what the gem merges in, so deriving from it would make the check
+    # agree with itself and validate nothing about the keys a USER adds.
+    KNOWN_OPTIONS = %i[
+      area_size_limit
+      capybara_screenshot_options
+      color_distance_limit
+      crop
+      delayed
+      driver
+      median_filter_window_size
+      perceptual_threshold
+      screenshot_format
+      shift_distance_limit
+      skip_area
+      stability_time_limit
+      tolerance
+      wait
+    ].freeze
+
     attr_reader :driver, :driver_options
     attr_reader :image_path, :base_image_path
     attr_reader :difference, :error_message
@@ -54,6 +79,13 @@ def initialize(image_path, base_image_path, options = {})
       ensure_files_exist!
 
       @driver_options = options.freeze
+      # THE no-silent-no-op check (ADR-010). Every option hash in the gem
+      # reaches this constructor, so a key nothing reads is caught here
+      # whichever entry point produced it. Frozen-but-unvalidated is how a
+      # misspelt `tolerence:` bought a green suite that compared nothing.
+      (options.keys - KNOWN_OPTIONS).each do |key|
+        Removal.warn_once(:"unknown_option_#{key}", Removal.unknown_option(key))
+      end
       # The per-comparison half of the shift_distance_limit removal (the
       # global half is Config#shift_distance_limit=). Presence is not enough:
       # config.default_options carries the key on EVERY comparison, nil for

lib/snap_diff/config.rb

@@ -79,11 +79,12 @@ class Config
       manager
     ].freeze
 
-    # shift_distance_limit is excluded from the generated writers and hand
-    # written below (it announces its 2.1 removal); generating it here too
-    # would print Ruby's "method redefined" warning on every load.
-    attr_accessor(*(SETTINGS - %i[root shift_distance_limit]))
-    attr_reader :root, :shift_distance_limit
+    # shift_distance_limit and driver are excluded from the generated
+    # writers and hand written below (they announce their 2.1 removal);
+    # generating them here too would print Ruby's "method redefined"
+    # warning on every load.
+    attr_accessor(*(SETTINGS - %i[root shift_distance_limit driver]))
+    attr_reader :root, :shift_distance_limit, :driver
 
     def initialize
       # Every setting gets its ivar up front (nil-defaulted ones included)
@@ -126,6 +127,15 @@ def shift_distance_limit=(value)
       @shift_distance_limit = value
     end
 
+    # Same shape, same reason: the writer only. #default_options reads
+    # +driver+ on every comparison for everyone, and #initialize seeds the
+    # +:auto+ default straight into the ivar, so only a user deliberately
+    # picking a backend hears about it.
+    def driver=(value)
+      Removal.warn_once(:driver_setting, Removal::DRIVER_REMOVED)
+      @driver = value
+    end
+
     # --- Derived config (ADR-008 step 7b) -------------------------------
     # Read-only values computed from the storage above. They used to live
     # on the legacy modules; those now one-line forward here.

lib/snap_diff/deprecation.rb

@@ -33,6 +33,7 @@ module Deprecation
     @seen = {}
     @notified = false
     @notice_suppressed = false
+    @canonical_entry = false
 
     # The ONE line a v1 user gets, whichever door they came through. Most of
     # the v1 surface cannot warn per use -- the config accessors are plain
@@ -60,6 +61,36 @@ def notice
         Kernel.warn(MIGRATION_NOTICE) if first_time
       end
 
+      # @api private
+      #
+      # Called at the TOP of every v1-NAMED entry file, before that file's
+      # own requires. Requiring one of those paths IS use of the v1 API,
+      # and it is the ONE door a suite that merely calls `screenshot` goes
+      # through: every other door ({LEGACY_DOORS} in the probe test) needs
+      # the user to call something, which is how beta3 shipped a v1-only
+      # app that produced zero deprecation output.
+      #
+      # Position matters. The marker must run before the file's requires,
+      # because lib/capybara-screenshot-diff.rb reaches the canonical entry
+      # point below on its way in, and a marker placed after that require
+      # would be swallowed by {canonical_entry_point!}.
+      # @return [void]
+      def legacy_entry_point!
+        notice unless @canonical_entry
+      end
+
+      # @api private
+      #
+      # Claimed by lib/snap_diff-capybara.rb -- the canonical gem-name
+      # entry -- which loads the v1 umbrella itself. Without this, "the v1
+      # files got loaded" would be indistinguishable from "a v1 user", and
+      # every `gem "snap_diff-capybara"` app would be told to migrate off
+      # an API it never touched.
+      # @return [void]
+      def canonical_entry_point!
+        @canonical_entry = true
+      end
+
       # @api private
       #
       # Suppresses {MIGRATION_NOTICE} for the rest of the process, without

lib/snap_diff/removal.rb

@@ -40,6 +40,25 @@ module Removal
       "driver, which is removed with it. libvips has no shift-distance comparison -- drop the " \
       "option and tune `tolerance` / `color_distance_limit` instead. See docs/configuration.md."
 
+    # Also one subject with several call sites -- the setting's writer
+    # (Config) and the raw per-screenshot / per-compare option hashes.
+    # Deliberately value-blind: `driver: :vips` warns too. It is the knob
+    # that picks between implementations, and 2.1 leaves one implementation,
+    # so the line goes whatever it currently says.
+    DRIVER_REMOVED =
+      "The `driver` setting and the per-screenshot `driver:` option are REMOVED in 2.1: libvips " \
+      "becomes the only backend, so there is nothing left to select. Drop the option and depend " \
+      "on the `ruby-vips` gem instead. See docs/drivers.md."
+
+    # Not a removal: 2.0 announces it and 2.1 turns it into an ArgumentError.
+    # The whole reason unrecognised keys need announcing is that the options
+    # hash was frozen but never validated, so a typo -- or a v1 option that
+    # no longer exists -- configured nothing, silently, forever.
+    def self.unknown_option(key)
+      "`#{key.inspect}` is not a recognised screenshot option, so it does nothing. 2.1 raises " \
+        "ArgumentError for it. Check the spelling against the option list in docs/configuration.md."
+    end
+
     MUTEX = Mutex.new
     @seen = {}
     @suppressed = false

lib/snap_diff/screenshot_matcher.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "snap_diff/removal"
 require "snap_diff/snap_manager"
 require_relative "screenshoter"
 require_relative "stable_screenshoter"
@@ -15,6 +16,9 @@ class ScreenshotMatcher
 
     def initialize(screenshot_full_name, options = {})
       @screenshot_full_name = screenshot_full_name
+      # BEFORE the merge below -- see SnapDiff.compare. Afterwards `:driver`
+      # is present for every caller and proves nothing.
+      Removal.warn_once(:driver_setting, Removal::DRIVER_REMOVED) if options.key?(:driver)
       @driver_options = SnapDiff.config.default_options.merge(options)
 
       @screenshot_format = @driver_options[:screenshot_format]

test/legacy/legacy_namespace_deprecation_test.rb

@@ -146,10 +146,18 @@ def capture_warnings
 
       _out, err, status = Open3.capture3(RbConfig.ruby, "-Ilib", "-e", body, chdir: PROJECT_ROOT)
 
+      # ADR-010: requiring a v1-named entry point is itself use of the v1
+      # API and now announces itself once. That line is the ENTRY's, not
+      # internal code's -- what this test is about is a per-constant warning,
+      # which can only come from the gem naming an old constant internally.
+      # Canonical entries stay held to zero output of any kind.
+      noise = err.lines.grep(/deprecation/)
+      noise = noise.grep_v(/This process uses the v1/) if kind == :legacy
+
       if !status.success?
         "require \"#{entry}\": probe failed:\n#{err}"
-      elsif err.include?("deprecation")
-        "require \"#{entry}\": internal use emitted deprecation output:\n#{err}"
+      elsif !noise.empty?
+        "require \"#{entry}\": internal use emitted deprecation output:\n#{noise.join}"
       end
     end
 

test/legacy/legacy_tree_is_alias_only_test.rb

@@ -77,7 +77,12 @@ class LegacyTreeIsAliasOnlyTest < ActiveSupport::TestCase
     private\z |
     (extend|include)\s |
     [A-Z]\w*\s*=\s |          # constant alias: Foo = SnapDiff::Foo
-    def_delegators?\s
+    def_delegators?\s |
+    # The v1 entry-point marker (ADR-010). Deliberately spelled out to the
+    # exact two calls rather than admitting bare method calls generally:
+    # these files must stay `git rm`-able, and announcing "a v1 door was
+    # used" is compatibility plumbing that dies with the door.
+    SnapDiff::Deprecation\.(legacy|canonical)_entry_point!\z
   )/x
 
   test "every legacy file is aliases and forwarders only" do