deprecation_toolkit 1.0.0

data/.rubocop.yml

@@ -0,0 +1,5 @@
+inherit_from:
+  - https://shopify.github.io/ruby-style-guide/rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 2.3

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :deployment do
+  gem 'rake'
+  gem 'rubocop'
+end

data/Gemfile.lock

@@ -0,0 +1,53 @@
+PATH
+  remote: .
+  specs:
+    deprecation_toolkit (1.0.0)
+      activesupport (>= 5.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (5.2.0)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    ast (2.4.0)
+    concurrent-ruby (1.0.5)
+    i18n (1.0.1)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.1)
+    minitest (5.11.3)
+    parallel (1.12.1)
+    parser (2.5.1.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    rainbow (2.2.2)
+      rake
+    rake (10.5.0)
+    rubocop (0.58.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.9.0)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  deprecation_toolkit!
+  minitest (~> 5.0)
+  rake
+  rubocop
+
+BUNDLED WITH
+   1.16.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Shopify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,99 @@
+# ⚒ Deprecation Toolkit ⚒
+
+## Introduction
+
+The Deprecation Toolkit is a gem to help you get rid of deprecations in your codebase.
+Having deprecations in your application is usually a sign that something will break whenever a third dependency will get updated. The sooner the better to fix them!
+Fixing all deprecations at once might be though depending on how big your app is and how much deprecations needs to be fixed. You might have to progressively resolve them while making sure your team doesn't add new one ➰. This is where this gem comes handy!
+
+
+## How it works
+
+The Deprecation Toolkit gem works by using a [shitlist approach](https://confreaks.tv/videos/reddotrubyconf2017-shitlist-driven-development-and-other-tricks-for-working-on-large-codebases).
+First, all current existing deprecations in your codebase are recorded into `.yml` files. When running a test that has non-recorded deprecations, the Deprecation Toolkit gem will trigger a behavior of your choice (by default raise an error).
+
+## Recording Deprecations
+
+As said above, the Deprecation Toolkit works by using a shitlist approach. You have two ways to record deprecations.
+Either set `DeprecationToolkit::Configuration.behavior` to `DeprecationToolkit::Behaviors::Record` (see the Configuration Reference below)
+Or run your tests with the `--record-deprecations` flag (or simply the `-r` shortcut)
+```sh
+rails test <path_to_my_test.rb> -r
+```
+
+## Configuration Reference
+
+### 🔨 `#DeprecationToolkit::Configuration#deprecation_path`
+
+You can control where the recorded deprecations are read and write into. By default, deprecations will be recorded in the `test/deprecations` folder.
+
+The `deprecation_path` either accepts a string or a proc. When using a proc, the proc will be passed an argument which is the path of the test file being run.
+
+```ruby
+DeprecationToolkit::Configuration.deprecation_path = 'test/deprecations'
+DeprecationToolkit::Configuration.deprecation_path = -> (test_location) do
+  if test_location == 'admin_test.rb'
+    'test/deprecations/admin'
+  else
+    'test/deprecations/storefront'
+  end
+end
+```
+
+### 🔨 `#DeprecationToolkit::Configuration#behavior`
+
+Behaviors defines what will happen when a non-recorded deprecations is encountered.
+
+Behaviors are class that responds to the `trigger` message.
+
+This gem provides 3 behaviors, the default one being `DeprecationToolkit::Behaviors::Raise`.
+
+* `DeprecationToolkit::Behaviors::Raise` will raise either:
+  - `DeprecationToolkit::DeprecationIntroduced` error if a new deprecation is introduced.
+  - `DeprecationToolkit::DeprecationRemoved` error if a deprecation was removed (compare to the one recorded in the shitlist).
+* `DeprecationToolkit::Behaviors::Record` will record deprecations.
+* `DeprecationToolkit::Behaviors::Disabled` will do nothing.
+  - This is useful if you want to disable this gem for a moment without removing the gem from your Gemfile.
+
+```ruby
+DeprecationToolkit::Configuration.behavior = DeprecationToolkit::Behaviors::Record
+```
+
+You can also create your own behavior class and perform the logic you want. Your behavior needs to respond to the `.trigger` message.
+
+```ruby
+class StatsdBehavior
+  def self.trigger(test, deprecations, recorded_deprecations)
+     # Could send some statsd event for example
+  end
+end
+
+DeprecationToolkit::Configuration.behavior = StatsdBehavior
+```
+
+### 🔨 `#DeprecationToolkit::Configuration#allowed_deprecations`
+
+If you want to allow some deprecations, this is where you'll configure it. The `allowed_deprecations` configuration accepts an
+array of Regexp.
+
+Whenever a deprecation matches one of the regex, the deprecation will be ignored
+
+```ruby
+DeprecationToolkit::Configuration.allowed_deprecations = [/Hello World/]
+
+# Let's imagine a third dependency adds a deprecation like this,
+# the Deprecation Toolkit will simply ignore it.
+ActiveSupport::Deprecation.warn('Hello World')
+```
+
+### 🔨 `#DeprecationToolkit::Configuration#warnings_treated_as_deprecation`
+
+Most gems doesn't use `ActiveSupport::Deprecation` to deprecate their code but instead just uses `Kernel#warn` to output
+a message in the console.
+
+The DeprecationToolkit gem allows you to configure which warnings should be treated as deprecations in order for you
+to keep track of them as if they were regular deprecations.
+
+## License
+
+Deprecation Toolkit is lincensed under the [MIT license](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.warning = true
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/deprecation_toolkit.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "deprecation_toolkit/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "deprecation_toolkit"
+  spec.version = DeprecationToolkit::VERSION
+  spec.authors = %w(Shopify)
+  spec.email = ["rails@shopify.com"]
+
+  spec.summary = "Deprecation Toolkit around ActiveSupport::Deprecation"
+  spec.homepage = "https://github.com/shopify/deprecation_toolkit"
+  spec.license = "MIT"
+
+  spec.required_ruby_version = '>= 2.3'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test)/})
+  end
+  spec.require_paths = %w(lib)
+
+  spec.add_runtime_dependency 'activesupport', '>= 5.0'
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

data/lib/deprecation_toolkit/behaviors/disabled.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module DeprecationToolkit
+  module Behaviors
+    class Disabled
+      def self.trigger(*)
+      end
+    end
+  end
+end

data/lib/deprecation_toolkit/behaviors/raise.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module DeprecationToolkit
+  module Behaviors
+    class Raise
+      def self.trigger(_test, current_deprecations, recorded_deprecations)
+        error_class = if current_deprecations > recorded_deprecations
+          DeprecationIntroduced
+        else
+          DeprecationRemoved
+        end
+
+        raise error_class.new(current_deprecations, recorded_deprecations)
+      end
+    end
+
+    DeprecationException = Class.new(StandardError)
+
+    class DeprecationIntroduced < DeprecationException
+      def initialize(current_deprecations, recorded_deprecations)
+        introduced_deprecations = current_deprecations - recorded_deprecations
+
+        message = <<~EOM
+          You have introduced new deprecations in the codebase. Fix or record them in order to discard this error.
+          You can record deprecations by adding the `--record-deprecations` flag when running your tests.
+
+          #{introduced_deprecations.join("\n")}
+        EOM
+
+        super(message)
+      end
+    end
+
+    class DeprecationRemoved < DeprecationException
+      def initialize(current_deprecations, recorded_deprecations)
+        removed_deprecations = recorded_deprecations - current_deprecations
+
+        message = <<~EOM
+          You have removed deprecations from the codebase. Thanks for being an awesome person.
+          The recorded deprecations needs to be updated to reflect your changes.
+          You can re-record deprecations by adding the `--record-deprecations` flag when running your tests.
+
+          #{removed_deprecations.join("\n")}
+        EOM
+
+        super(message)
+      end
+    end
+  end
+end

data/lib/deprecation_toolkit/behaviors/record.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module DeprecationToolkit
+  module Behaviors
+    class Record
+      extend ReadWriteHelper
+
+      def self.trigger(test, collector, _)
+        write(test, collector.deprecations_without_stacktrace)
+      end
+    end
+  end
+end

data/lib/deprecation_toolkit/collector.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/class/attribute"
+
+module DeprecationToolkit
+  class Collector
+    include Comparable
+    extend ReadWriteHelper
+
+    class_attribute :deprecations
+    self.deprecations = []
+
+    class << self
+      def collect(message)
+        deprecations << message
+      end
+
+      def load(test)
+        new(read(test))
+      end
+
+      def reset!
+        deprecations.clear
+      end
+    end
+
+    def initialize(deprecations)
+      self.deprecations = deprecations
+    end
+
+    def <=>(other)
+      deprecations_without_stacktrace <=> other.deprecations_without_stacktrace
+    end
+
+    def deprecations_without_stacktrace
+      deprecations.map { |deprecation| deprecation.sub(/ \(called from .*\)$/, "") }
+    end
+
+    def -(other)
+      difference = deprecations.dup
+      current = deprecations_without_stacktrace
+      other = other.deprecations_without_stacktrace
+
+      other.each do |deprecation|
+        index = current.index(deprecation)
+
+        if index
+          current.delete_at(index)
+          difference.delete_at(index)
+        end
+      end
+
+      difference
+    end
+  end
+end

data/lib/deprecation_toolkit/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "active_support/configurable"
+
+module DeprecationToolkit
+  class Configuration
+    include ActiveSupport::Configurable
+
+    config_accessor(:behavior) { Behaviors::Raise }
+    config_accessor(:allowed_deprecations) { [] }
+    config_accessor(:deprecation_path) { "test/deprecations" }
+    config_accessor(:attach_to) { [:rails] }
+    config_accessor(:warnings_treated_as_deprecation) { [] }
+  end
+end

data/lib/deprecation_toolkit/deprecation_subscriber.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "active_support/subscriber"
+
+module DeprecationToolkit
+  class DeprecationSubscriber < ActiveSupport::Subscriber
+    def deprecation(event)
+      message = event.payload[:message]
+
+      Collector.collect(message) unless deprecation_allowed?(message)
+    end
+
+    private
+
+    def deprecation_allowed?(message)
+      Configuration.allowed_deprecations.any? { |regex| regex =~ message }
+    end
+  end
+end

data/lib/deprecation_toolkit/minitest_hook.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "minitest"
+
+module DeprecationToolkit
+  module Minitest
+    def trigger_deprecation_toolkit_behavior
+      current_deprecations = Collector.new(Collector.deprecations)
+      recorded_deprecations = Collector.load(self)
+      if current_deprecations != recorded_deprecations
+        Configuration.behavior.trigger(self, current_deprecations, recorded_deprecations)
+      end
+    ensure
+      Collector.reset!
+    end
+  end
+end
+
+module Minitest
+  class Test
+    include DeprecationToolkit::Minitest
+
+    TEARDOWN_METHODS << "trigger_deprecation_toolkit_behavior"
+  end
+end

data/lib/deprecation_toolkit/read_write_helper.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "yaml"
+
+module DeprecationToolkit
+  module ReadWriteHelper
+    def read(test)
+      deprecation_file = recorded_deprecations_path(test)
+      YAML.load(deprecation_file.read).fetch(test.name, [])
+    rescue Errno::ENOENT
+      []
+    end
+
+    def write(test, deprecations)
+      deprecation_file = recorded_deprecations_path(test)
+      create_deprecation_file(deprecation_file) unless deprecation_file.exist?
+
+      content = YAML.load_file(deprecation_file)
+      if deprecations.any?
+        content[test.name] = deprecations
+      else
+        content.delete(test.name)
+      end
+
+      if content.any?
+        deprecation_file.write(YAML.dump(content))
+      else
+        deprecation_file.delete
+      end
+    end
+
+    private
+
+    def create_deprecation_file(deprecation_file)
+      deprecation_file.dirname.mkpath
+      deprecation_file.write(YAML.dump({}))
+    end
+
+    def recorded_deprecations_path(test)
+      deprecation_folder = if Configuration.deprecation_path.is_a?(Proc)
+        Configuration.deprecation_path.call(test_location(test))
+      else
+        Configuration.deprecation_path
+      end
+
+      Bundler.root.join(deprecation_folder, "#{test.class.name.underscore}.yml")
+    end
+
+    def test_location(test)
+      test.method(test.name).source_location[0]
+    rescue NameError
+      "unknown"
+    end
+  end
+end

data/lib/deprecation_toolkit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DeprecationToolkit
+  VERSION = "1.0.0"
+end

data/lib/deprecation_toolkit/warning.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module DeprecationToolkit
+  module Warning
+    def warn(str)
+      if DeprecationToolkit::Configuration.warnings_treated_as_deprecation.any? { |warning| warning =~ str }
+        ActiveSupport::Deprecation.warn(str)
+      else
+        super
+      end
+    end
+  end
+end
+
+Warning.singleton_class.prepend(DeprecationToolkit::Warning)
+
+# https://bugs.ruby-lang.org/issues/12944
+if RUBY_VERSION <= '2.5.0' && RUBY_ENGINE == 'ruby'
+  module Kernel
+    remove_method :warn
+
+    def warn(*messages)
+      Array(messages.flatten).each { |msg| Warning.warn(msg) }
+    end
+  end
+end

data/lib/deprecation_toolkit.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module DeprecationToolkit
+  autoload :DeprecationSubscriber,     "deprecation_toolkit/deprecation_subscriber"
+  autoload :Configuration,             "deprecation_toolkit/configuration"
+  autoload :Collector,                 "deprecation_toolkit/collector"
+  autoload :ReadWriteHelper,           "deprecation_toolkit/read_write_helper"
+
+  module Behaviors
+    autoload :Disabled,                "deprecation_toolkit/behaviors/disabled"
+    autoload :Raise,                   "deprecation_toolkit/behaviors/raise"
+    autoload :Record,                  "deprecation_toolkit/behaviors/record"
+  end
+end
+
+require "deprecation_toolkit/minitest_hook"
+require "deprecation_toolkit/warning"

data/lib/minitest/deprecation_toolkit_plugin.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Minitest
+  extend self
+
+  def plugin_deprecation_toolkit_options(opts, options)
+    opts.on "-r", "--record-deprecations", "Record deprecations" do
+      options[:record_deprecations] = true
+    end
+  end
+
+  def plugin_deprecation_toolkit_init(options)
+    if options[:record_deprecations]
+      DeprecationToolkit::Configuration.behavior = DeprecationToolkit::Behaviors::Record
+    end
+
+    add_notify_behavior
+    attach_subscriber
+  end
+
+  private
+
+  def add_notify_behavior
+    notify = ActiveSupport::Deprecation::DEFAULT_BEHAVIORS[:notify]
+    behaviors = ActiveSupport::Deprecation.behavior
+
+    unless behaviors.find { |behavior| behavior == notify }
+      ActiveSupport::Deprecation.behavior = behaviors << notify
+    end
+  end
+
+  def attach_subscriber
+    DeprecationToolkit::Configuration.attach_to.each do |gem_name|
+      DeprecationToolkit::DeprecationSubscriber.attach_to gem_name
+    end
+  end
+end

data/shipit.rubygems.yml

@@ -0,0 +1 @@
+# using the default shipit config