Module: SnapDiff::Deprecation Private

Defined in:
lib/snap_diff/deprecation.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.

Internal until the v2 namespace transition; not a public contract.

Warn-once-per-subject deprecation engine for the legacy-namespace shims: snap_diff/legacy_shims routes every const_missing hit on an old Capybara::Screenshot::Diff / CapybaraScreenshotDiff constant through Deprecation.warn, so each deprecated name warns exactly once per process (ADR-004's v2 namespace transition).

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 referenced the deprecated name (same filtering idea as BacktraceFilter in error_with_filtered_backtrace).

File.expand_path("..", __dir__) + File::SEPARATOR
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.

Emission channel: Kernel#warn, not a direct $stderr.puts.

Kernel#warn delegates to Warning.warn (Ruby >= 2.4), so anything that hooks Warning.warn -- a test suite that raises on warnings, a custom log formatter, Ruby's own -W flag -- sees these messages the same way it sees every other Ruby warning. Writing straight to $stderr would bypass that hook entirely and be invisible to any caller who has customized Warning behavior.

Mutex.new
MIGRATION_NOTICE =

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 line a v1 user gets, whichever door they came through. Most of the v1 surface cannot warn per use -- the config accessors are plain delegators and the eager aliases never reach const_missing -- so without this a 2.x app is completely silent right up to the bare NameError it gets on 2.1. Deliberately generic and once per process: an actionable signal, not per-call stderr noise.

"[snap_diff deprecation] This process uses the v1 `Capybara::Screenshot*` / " \
"`CapybaraScreenshotDiff*` API. It still works in 2.0 and is REMOVED in 2.1 -- " \
"see docs/UPGRADING.md for the SnapDiff replacements. Silence with " \
"`SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. " \
"(shown once per process)"

Class Method Summary collapse

Class Method Details

.canonical_entry_point! ⇒ 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.

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.



90
91
92
 
# File 'lib/snap_diff/deprecation.rb', line 90

def canonical_entry_point!
  @canonical_entry = true
end

.legacy_entry_point! ⇒ 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.

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!.



78
79
80
 
# File 'lib/snap_diff/deprecation.rb', line 78

def legacy_entry_point!
  notice unless @canonical_entry
end

.notice ⇒ 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 MIGRATION_NOTICE, exactly once per process. Called from every v1 entry that can be hooked: the const_missing shims (via warn), the generated legacy config accessors, and include Capybara::Screenshot[::Diff].



57
58
59
60
61
62
 
# File 'lib/snap_diff/deprecation.rb', line 57

def notice
  return if @notified || @notice_suppressed || SnapDiff.silence_deprecations?

  first_time = MUTEX.synchronize { @notified ? false : (@notified = true) }
  Kernel.warn(MIGRATION_NOTICE) if first_time
end

.reset! ⇒ 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.

Clears the seen-set. For tests only -- lets each example assert "warns once" from a clean slate instead of leaking state across the suite.



134
135
136
137
138
139
 
# File 'lib/snap_diff/deprecation.rb', line 134

def reset!
  MUTEX.synchronize do
    @seen.clear
    @notified = false
  end
end

.suppress_migration_notice! ⇒ 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.

Suppresses MIGRATION_NOTICE for the rest of the process, without touching the per-constant warnings. For hosts that ARE the v1 surface rather than users of it -- this gem's own test suite, which configures through Capybara::Screenshot.* by design and would otherwise print the notice on every run. Deliberately survives reset!, which exists to give a single test a clean slate.



103
104
105
 
# File 'lib/snap_diff/deprecation.rb', line 103

def suppress_migration_notice!
  MUTEX.synchronize { @notice_suppressed = true }
end

.warn(subject, replacement) ⇒ 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 a deprecation warning for subject, exactly once per unique subject per process -- preceded, the first time round, by MIGRATION_NOTICE.

Parameters:

  • subject (String) —

    the deprecated old-namespace name being referenced, e.g. "Capybara::Screenshot::Diff::ImageCompare"

  • replacement (String) —

    the new-namespace name to use instead



115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/snap_diff/deprecation.rb', line 115

def warn(subject, replacement)
  return if SnapDiff.silence_deprecations?

  notice

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

  Kernel.warn(message_for(subject, replacement, caller_locations(1)))
end