Normalize paths in deprecation messages

Author: sambostock

Diff for: CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## main (unreleased)
 
+* [#60](https://github.com/Shopify/deprecation_toolkit/pull/60): Normalize paths in deprecation messages. (@sambostock)
+
 ## 2.0.0 (2022-03-16)
 
 * [#58](https://github.com/Shopify/deprecation_toolkit/pull/58): Drop support for Ruby < 2.6 & Active Support < 5.2. (@sambostock)

Diff for: README.md

@@ -120,6 +120,38 @@ This setting accepts an array of regular expressions. To match on all warnings,
 DeprecationToolkit::Configuration.warnings_treated_as_deprecation = [//]
 ```
 
+### 🔨 `#DeprecationToolkit::Configuration#message_normalizers`
+
+Deprecation Toolkit allows the normalization of deprecation warnings by registering message normalizers.
+
+Out-of-the-box, various path normalizers are included, to ensure that any paths included in deprecation warnings are consistent from machine to machine (see [`lib/deprecation_toolkit/configuration.rb`](lib/deprecation_toolkit/configuration.rb) for details).
+
+### Customizing normalization
+
+Additional normalizers can be added by appending then to the array:
+
+```ruby
+DeprecationToolkit::Configuration.message_normalizers << ->(msg) { msg.downcase }
+```
+
+Normalizers are expected to respond to `.call`, accepting a `String` and returning a normalized `String`, and are applied in order of registration.
+
+If you wish to normalize a custom path, you can create your own `DeprecationToolkit::PathPrefixNormalizer`:
+
+```ruby
+DeprecationToolkit::Configuration.message_normalizers <<
+  DeprecationToolkit::PathPrefixNormalizer.new(
+    '/path/to/something',
+    replacement: 'optional replacement string',
+  )
+```
+
+You may optionally disable any or all normalizers by mutating or replacing the array.
+
+```ruby
+DeprecationToolkit::Configuration.message_normalizers = [] # remove all normalizers
+```
+
 ## RSpec
 
 By default Deprecation Toolkit uses Minitest as its test runner. To use Deprecation Toolkit with RSpec you'll have to configure it.

Diff for: lib/deprecation_toolkit/configuration.rb

@@ -12,5 +12,35 @@ class Configuration
     config_accessor(:deprecation_path) { "test/deprecations" }
     config_accessor(:test_runner) { :minitest }
     config_accessor(:warnings_treated_as_deprecation) { [] }
+
+    config_accessor(:message_normalizers) do
+      normalizers = []
+
+      normalizers << PathPrefixNormalizer.new(Rails.root) if defined?(Rails)
+      normalizers << PathPrefixNormalizer.new(Bundler.root) if defined?(Bundler)
+
+      if defined?(Gem)
+        Gem.loaded_specs.each_value do |spec|
+          normalizers << PathPrefixNormalizer.new(spec.bin_dir, replacement: "<GEM_BIN_DIR:#{spec.name}>")
+          normalizers << PathPrefixNormalizer.new(spec.extension_dir, replacement: "<GEM_EXTENSION_DIR:#{spec.name}>")
+          normalizers << PathPrefixNormalizer.new(spec.gem_dir, replacement: "<GEM_DIR:#{spec.name}>")
+        end
+        normalizers << PathPrefixNormalizer.new(*Gem.path, replacement: "<GEM_PATH>")
+      end
+
+      begin
+        require "rbconfig"
+        normalizers << PathPrefixNormalizer.new(
+          *RbConfig::CONFIG.values_at('prefix', 'sitelibdir', 'rubylibdir'),
+          replacement: "<RUBY_INTERNALS>",
+        )
+      rescue LoadError
+        # skip normalizing ruby internal paths
+      end
+
+      normalizers << PathPrefixNormalizer.new(Dir.pwd)
+
+      normalizers
+    end
   end
 end

Diff for: lib/deprecation_toolkit/deprecation_subscriber.rb

@@ -9,18 +9,24 @@ def self.already_attached?
     end
 
     def deprecation(event)
-      message = event.payload[:message]
+      message = normalize_message(event.payload[:message])
 
-      Collector.collect(message) unless deprecation_allowed?(event.payload)
+      Collector.collect(message) unless deprecation_allowed?(message, event.payload[:callstack])
     end
 
     private
 
-    def deprecation_allowed?(payload)
+    def deprecation_allowed?(message, callstack)
       allowed_deprecations, procs = Configuration.allowed_deprecations.partition { |el| el.is_a?(Regexp) }
 
-      allowed_deprecations.any? { |regex| regex =~ payload[:message] } ||
-        procs.any? { |proc| proc.call(payload[:message], payload[:callstack]) }
+      allowed_deprecations.any? { |regex| regex =~ message } ||
+        procs.any? { |proc| proc.call(message, callstack) }
+    end
+
+    def normalize_message(message)
+      Configuration
+        .message_normalizers
+        .reduce(message) { |message, normalizer| normalizer.call(message) }
     end
   end
 end

Diff for: test/deprecation_toolkit/warning_test.rb

@@ -82,5 +82,128 @@ class WarningTest < ActiveSupport::TestCase
       assert_match(/Using the last argument as keyword parameters/, error.message)
       assert_match(/The called method/, error.message)
     end
+
+    test "'Ruby 2.7 last argument as keyword parameters' real deprecation warning is handled with normalized paths" do
+      Configuration.warnings_treated_as_deprecation = [/Using the last argument as keyword parameters/]
+
+      error = assert_raises(Behaviors::DeprecationIntroduced) do
+        warn("#{Dir.pwd}/path/to/caller.rb:1: warning: Using the last argument as keyword parameters is deprecated; " \
+          "maybe ** should be added to the call")
+        warn("#{Dir.pwd}/path/to/callee.rb:1: warning: The called method `method_name' is defined here")
+
+        trigger_deprecation_toolkit_behavior
+      end
+
+      assert_match(%r{^DEPRECATION WARNING: path/to/caller\.rb:1: warning: Using the last},
+        error.message)
+      assert_match(%r{^path/to/callee\.rb:1: warning: The called method}, error.message)
+    end
+
+    test "`assert_nil` real deprecation warning is handled with normalized paths" do
+      Configuration.warnings_treated_as_deprecation = [/Use assert_nil if expecting nil/]
+
+      error = assert_raises(Behaviors::DeprecationIntroduced) do
+        warn("Use assert_nil if expecting nil from #{Dir.pwd}/path/to/file.rb:1. This will fail in Minitest 6.")
+
+        trigger_deprecation_toolkit_behavior
+      end
+
+      assert_match(
+        %r{^DEPRECATION WARNING: Use assert_nil if expecting nil from path/to/file\.rb:1}, error.message
+      )
+    end
+
+    test "the path to warn itself is handled too" do
+      Configuration.warnings_treated_as_deprecation = [/boom/]
+
+      error = assert_raises(Behaviors::DeprecationIntroduced) do
+        warn("boom")
+
+        trigger_deprecation_toolkit_behavior
+      end
+
+      assert_includes(error.message, <<~MESSAGE.chomp)
+        DEPRECATION WARNING: boom
+         (called from call at <RUBY_INTERNALS>/rubygems/core_ext/kernel_warn.rb:22)
+      MESSAGE
+    end
+
+    test "Rails.root is normalized in deprecation messages" do
+      rails_stub = Object.new
+      rails_stub.define_singleton_method(:inspect) { "Rails (stub)" }
+      rails_stub.define_singleton_method(:root) { "/path/to/rails/root" }
+
+      original_rails = defined?(::Rails) && ::Rails
+      Object.const_set(:Rails, rails_stub)
+
+      assert_normalizes(
+        from: "#{Rails.root}/app/models/whatever.rb",
+        to: "app/models/whatever.rb",
+      )
+    ensure
+      if original_rails.nil?
+        Object.send(:remove_const, :Rails)
+      else
+        Object.const_set(:Rails, original_rails)
+      end
+    end
+
+    test "Bundler.root is normalized in deprecation messages" do
+      assert_normalizes(
+        from: "#{Bundler.root}/lib/whatever.rb",
+        to: "lib/whatever.rb",
+      )
+    end
+
+    test "Gem spec gem_dirs are normalized in deprecation messages" do
+      spec = Gem.loaded_specs.each_value.first
+      assert_normalizes(
+        from: "#{spec.gem_dir}/lib/whatever.rb",
+        to: "<GEM_DIR:#{spec.name}>/lib/whatever.rb",
+      )
+    end
+
+    test "Gem spec extension_dirs are normalized in deprecation messages" do
+      spec = Gem.loaded_specs.each_value.first
+      assert_normalizes(
+        from: "#{spec.extension_dir}/lib/whatever.rb",
+        to: "<GEM_EXTENSION_DIR:#{spec.name}>/lib/whatever.rb",
+      )
+    end
+
+    test "Gem spec bin_dirs are normalized in deprecation messages" do
+      spec = Gem.loaded_specs.each_value.first
+      assert_normalizes(
+        from: "#{spec.bin_dir}/lib/whatever.rb",
+        to: "<GEM_BIN_DIR:#{spec.name}>/lib/whatever.rb",
+      )
+    end
+
+    test "Gem paths are normalized in deprecation messages" do
+      paths = Gem.path
+      assert_normalizes(
+        from: paths.map.with_index { |path, index| "#{path}/file-#{index}" }.join("\n"),
+        to: Array.new(paths.length) { |index| "<GEM_PATH>/file-#{index}" }.join("\n"),
+      )
+    end
+
+    test "RbConfig paths are normalized in deprecation messages" do
+      paths = RbConfig::CONFIG.values_at('prefix', 'sitelibdir', 'rubylibdir').compact
+      assert_normalizes(
+        from: paths.map.with_index { |path, index| "#{path}/file-#{index}" }.join("\n"),
+        to: Array.new(paths.length) { |index| "<RUBY_INTERNALS>/file-#{index}" }.join("\n"),
+      )
+    end
+
+    private
+
+    def assert_normalizes(from:, to:)
+      Configuration.warnings_treated_as_deprecation = [/test deprecation/]
+      error = assert_raises(Behaviors::DeprecationIntroduced) do
+        warn("test deprecation: #{from}.")
+        trigger_deprecation_toolkit_behavior
+      end
+      assert_includes(error.message, to)
+    end
   end
 end