Module: SnapDiff::Removal Private

Defined in:
lib/snap_diff/removal.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Announces what 2.1 REMOVES, from the 2.0 line that still supports it: the chunky_png driver, shift_distance_limit (chunky-only, it dies with it) and the driver abstraction (+SnapDiff::Driver+, SnapDiff::Drivers.loaded / .available, driver: :auto) -- libvips becomes the only backend. 2.0 is the transitional release: the contract is published before it is enforced.

Same shape and same silencing switches as Deprecation, which announces the other half (the v1 namespaces), but a file of its own: the legacy shims and their deprecation channel are themselves part of what is removed, while the call sites here -- utils, config, drivers -- are core files that outlive them, so they cannot depend on a doomed file. That is also why silence_deprecations lives HERE rather than in deprecation.rb: it is the one switch that silences both halves.

Deliberately not a warn-per-call channel: one line per subject per process is an actionable signal, N lines per comparison is noise people learn to filter out.

Constant Summary collapse

GEM_LIB_DIR =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Everything under lib/ is "the gem"; the first caller frame outside it is the user code that touched the doomed API.

File.expand_path("..", __dir__) + File::SEPARATOR
SILENCE_HINT =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Appended to every message, so the individual messages can stay about the thing being removed.

"Silence with `SnapDiff.silence_deprecations = true` or " \
"SNAP_DIFF_SILENCE_DEPRECATIONS=1. (shown once per process)"
SHIFT_DISTANCE_LIMIT_REMOVED =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

The one message with two call sites -- the setting's writer (Config) and the per-comparison option (Comparison) -- so it lives here rather than in either of them. One subject, one warning, whichever fires.

"`shift_distance_limit` is REMOVED in 2.1: it is implemented only by the chunky_png " \
"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."
DRIVER_REMOVED =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

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.

"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."
FAIL_IF_NEW_REMOVED =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

--- the new-screenshot booleans, superseded by record: (#259) -----

Three separate settings, each answering some part of "what happens when there is no baseline / when there is a difference", none of them naming the action the user actually wants. 2.0 adds the verb -- SnapDiff.config.record -- and 2.1 removes the booleans. Each message names the mode that replaces THAT setting, and nothing more: record: supersedes the missing-baseline half squarely and the other two only obliquely, and a message that overclaims is a message that misroutes.

"`fail_if_new` is REMOVED in 2.1: the record modes replace it. `SnapDiff.config.record = :none` " \
"is `fail_if_new = true`, `= :once` is `fail_if_new = false` -- and unlike the boolean, a mode " \
"means the same thing on CI and off it. See docs/configuration.md."
PENDING_IF_NEW_REMOVED =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

"`pending_if_new` is REMOVED in 2.1: it skips the test instead of saying what to do about the " \
"missing baseline. `SnapDiff.config.record = :none` fails with the `git add` command attached; " \
"`= :once` records it and reports it in the end-of-run summary. See docs/configuration.md."
FAIL_ON_DIFFERENCE_REMOVED =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

"`fail_on_difference` is REMOVED in 2.1: a screenshot that differs from its baseline fails, " \
"which is what the gem is for. To ACCEPT a difference, re-record it -- " \
"`SnapDiff.config.record = :all` -- and commit the result. See docs/configuration.md."
MUTEX =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

Mutex.new

Class Method Summary collapse

Class Method Details

.suppress! ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Silences these warnings for the rest of the process, without touching the v1-namespace ones. For hosts that exercise the doomed APIs BY DESIGN rather than depending on them -- this gem's own suite runs the whole comparison matrix on chunky_png and sets shift_distance_limit, and its test_helper raises on any deprecation output.



115
116
117
 
# File 'lib/snap_diff/removal.rb', line 115

def suppress!
  MUTEX.synchronize { @suppressed = true }
end

.unknown_option(key) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



82
83
84
85
 
# File 'lib/snap_diff/removal.rb', line 82

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

.warn_once(subject, message) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Emit message once per subject per process, via Kernel#warn (so anything hooking Warning.warn sees it like any other Ruby warning).

Parameters:

  • subject (Symbol) —

    dedup key -- the doomed API, not the call site

  • message (String) —

    what is removed, when, and what to do instead



98
99
100
101
102
103
104
105
 
# File 'lib/snap_diff/removal.rb', line 98

def warn_once(subject, message)
  return if @suppressed || SnapDiff.silence_deprecations?

  first_time = MUTEX.synchronize { @seen.key?(subject) ? false : (@seen[subject] = true) }
  return unless first_time

  Kernel.warn(with_origin("[snap_diff deprecation] #{message} #{SILENCE_HINT}", caller_locations(1)))
end