Include rubocop-faker autocorrect in deprecation

Follow up #1714.

This is a proposal to make it easy to convert positional arguments to
keyword arguments.

This approach is based on the experience that factory_bot has provided
for upgrades.

- thoughtbot/factory_bot@dabacda
- thoughtbot/factory_bot#1135

First, I prepared rubocop-faker gem for upgrading with auto-correction.
https://github.com/koic/rubocop-faker

This PR includes rubocop-faker autocorrect in deprecation.
The following is an example.

```console
% cat example.rb
require 'faker'

Faker::Lorem.words(10000, true)
```

## Before

```console
% bundle exec ruby example.rb
example.rb:3: Passing `number` with the 1st argument of `Lorem.words` is
deprecated. Use keyword argument like `Lorem.words(number: ...)`
instead.
example.rb:3: Passing `supplemental` with the 2nd argument of
`Lorem.words` is deprecated. Use keyword argument like
`Lorem.words(supplemental: ...)` instead.
```

## After

```console
% bundle exec ruby example.rb
example.rb:3: Passing `number` with the 1st argument of `words` is
deprecated. Use keyword argument like `words(number: ...)` instead.
example.rb:3: Passing `supplemental` with the 2nd argument of `words` is
deprecated. Use keyword argument like `words(supplemental: ...)`
instead.

To automatically update from positional arguments to keyword arguments,
install rubocop-faker and run:

rubocop \
  --require rubocop-faker \
  --only Faker/DeprecatedArguments \
  --auto-correct
```

Basically, users can update by copying and pasting the command displayed
in the warning, so the upgrade is easy.

lib/faker.rb

@@ -251,6 +251,40 @@ def disable_enforce_available_locales
 
       private
 
+      def warn_for_deprecated_arguments
+        keywords = []
+        yield(keywords)
+
+        return if keywords.empty?
+
+        method_name = caller.first.match(/`(?<method_name>.*)'/)[:method_name]
+
+        keywords.each.with_index(1) do |keyword, index|
+          i = case index
+              when 1 then '1st'
+              when 2 then '2nd'
+              when 3 then '3rd'
+              else "#{index}th"
+              end
+
+          warn_with_uplevel(<<~MSG, uplevel: 5)
+            Passing `#{keyword}` with the #{i} argument of `#{method_name}` is deprecated. Use keyword argument like `#{method_name}(#{keyword}: ...)` instead.
+          MSG
+        end
+
+        warn(<<~MSG)
+
+          To automatically update from positional arguments to keyword arguments,
+          install rubocop-faker and run:
+
+          rubocop \\
+            --require rubocop-faker \\
+            --only Faker/DeprecatedArguments \\
+            --auto-correct
+
+        MSG
+      end
+
       # Workaround for emulating `warn '...', uplevel: 1` in Ruby 2.4 or lower.
       def warn_with_uplevel(message, uplevel: 1)
         at = parse_caller(caller[uplevel]).join(':')

lib/faker/books/dune.rb

@@ -20,9 +20,8 @@ def planet
         end
 
         def quote(legacy_character = NOT_GIVEN, character: nil)
-          if legacy_character != NOT_GIVEN
-            warn_with_uplevel 'Passing `character` with the 1st argument of `Dune.quote` is deprecated. Use keyword argument like `Dune.quote(character: ...)` instead.', uplevel: 1
-            character = legacy_character
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :character if legacy_character != NOT_GIVEN
           end
 
           quoted_characters = translate('faker.dune.quotes').keys
@@ -42,9 +41,8 @@ def quote(legacy_character = NOT_GIVEN, character: nil)
         end
 
         def saying(legacy_source = NOT_GIVEN, source: nil)
-          if legacy_source != NOT_GIVEN
-            warn_with_uplevel 'Passing `source` with the 1st argument of `Dune.saying` is deprecated. Use keyword argument like `Dune.saying(source: ...)` instead.', uplevel: 1
-            source = legacy_source
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :source if legacy_source != NOT_GIVEN
           end
 
           sourced_sayings = translate('faker.dune.sayings').keys

lib/faker/books/lovecraft.rb

@@ -9,9 +9,8 @@ def location
         end
 
         def fhtagn(legacy_number = NOT_GIVEN, number: 1)
-          if legacy_number != NOT_GIVEN
-            warn_with_uplevel 'Passing `number` with the 1st argument of `Lovecraft.fhtagn` is deprecated. Use keyword argument like `Lovecraft.fhtagn(number: ...)` instead.', uplevel: 1
-            number = legacy_number
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :number if legacy_number != NOT_GIVEN
           end
 
           Array.new(number) { fetch('lovecraft.fhtagn') }.join('. ')
@@ -26,13 +25,9 @@ def tome
         end
 
         def sentence(legacy_word_count = NOT_GIVEN, legacy_random_words_to_add = NOT_GIVEN, word_count: 4, random_words_to_add: 6)
-          if legacy_word_count != NOT_GIVEN
-            warn_with_uplevel 'Passing `word_count` with the 1st argument of `Lovecraft.sentence` is deprecated. Use keyword argument like `Lovecraft.sentence(word_count: ...)` instead.', uplevel: 1
-            word_count = legacy_word_count
-          end
-          if legacy_random_words_to_add != NOT_GIVEN
-            warn_with_uplevel 'Passing `random_words_to_add` with the 2nd argument of `Lovecraft.sentence` is deprecated. Use keyword argument like `Lovecraft.sentence(random_words_to_add: ...)` instead.', uplevel: 1
-            random_words_to_add = legacy_random_words_to_add
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :word_count if legacy_word_count != NOT_GIVEN
+            keywords << :random_words_to_add if legacy_random_words_to_add != NOT_GIVEN
           end
 
           words(number: word_count + rand(random_words_to_add.to_i).to_i, spaces_allowed: true).join(' ').capitalize + '.'
@@ -44,13 +39,9 @@ def word
         end
 
         def words(legacy_number = NOT_GIVEN, legacy_spaces_allowed = NOT_GIVEN, number: 3, spaces_allowed: false)
-          if legacy_number != NOT_GIVEN
-            warn_with_uplevel 'Passing `number` with the 1st argument of `Lovecraft.words` is deprecated. Use keyword argument like `Lovecraft.words(number: ...)` instead.', uplevel: 1
-            number = legacy_number
-          end
-          if legacy_spaces_allowed != NOT_GIVEN
-            warn_with_uplevel 'Passing `spaces_allowed` with the 2nd argument of `Lovecraft.words` is deprecated. Use keyword argument like `Lovecraft.words(spaces_allowed: ...)` instead.', uplevel: 1
-            spaces_allowed = legacy_spaces_allowed
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :number if legacy_number != NOT_GIVEN
+            keywords << :spaces_allowed if legacy_spaces_allowed != NOT_GIVEN
           end
 
           resolved_num = resolve(number)
@@ -64,9 +55,8 @@ def words(legacy_number = NOT_GIVEN, legacy_spaces_allowed = NOT_GIVEN, number:
         end
 
         def sentences(legacy_number = NOT_GIVEN, number: 3)
-          if legacy_number != NOT_GIVEN
-            warn_with_uplevel 'Passing `number` with the 1st argument of `Lovecraft.sentences` is deprecated. Use keyword argument like `Lovecraft.sentences(number: ...)` instead.', uplevel: 1
-            number = legacy_number
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :number if legacy_number != NOT_GIVEN
           end
 
           [].tap do |sentences|
@@ -77,22 +67,17 @@ def sentences(legacy_number = NOT_GIVEN, number: 3)
         end
 
         def paragraph(legacy_sentence_count = NOT_GIVEN, legacy_random_sentences_to_add = NOT_GIVEN, sentence_count: 3, random_sentences_to_add: 3)
-          if legacy_sentence_count != NOT_GIVEN
-            warn_with_uplevel 'Passing `sentence_count` with the 1st argument of `Lovecraft.paragraph` is deprecated. Use keyword argument like `Lovecraft.paragraph(sentence_count: ...)` instead.', uplevel: 1
-            sentence_count = legacy_sentence_count
-          end
-          if legacy_random_sentences_to_add != NOT_GIVEN
-            warn_with_uplevel 'Passing `random_sentences_to_add` with the 2nd argument of `Lovecraft.paragraph` is deprecated. Use keyword argument like `Lovecraft.paragraph(random_sentences_to_add: ...)` instead.', uplevel: 1
-            random_sentences_to_add = legacy_random_sentences_to_add
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :sentence_count if legacy_sentence_count != NOT_GIVEN
+            keywords << :random_sentences_to_add if legacy_random_sentences_to_add != NOT_GIVEN
           end
 
           sentences(number: resolve(sentence_count) + rand(random_sentences_to_add.to_i).to_i).join(' ')
         end
 
         def paragraphs(legacy_number = NOT_GIVEN, number: 3)
-          if legacy_number != NOT_GIVEN
-            warn_with_uplevel 'Passing `number` with the 1st argument of `Lovecraft.paragraphs` is deprecated. Use keyword argument like `Lovecraft.paragraphs(number: ...)` instead.', uplevel: 1
-            number = legacy_number
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :number if legacy_number != NOT_GIVEN
           end
 
           [].tap do |paragraphs|
@@ -103,9 +88,8 @@ def paragraphs(legacy_number = NOT_GIVEN, number: 3)
         end
 
         def paragraph_by_chars(legacy_characters = NOT_GIVEN, characters: 256)
-          if legacy_characters != NOT_GIVEN
-            warn_with_uplevel 'Passing `characters` with the 1st argument of `Lovecraft.paragraph_by_chars` is deprecated. Use keyword argument like `Lovecraft.paragraph_by_chars(characters: ...)` instead.', uplevel: 1
-            characters = legacy_characters
+          warn_for_deprecated_arguments do |keywords|
+            keywords << :characters if legacy_characters != NOT_GIVEN
           end
 
           paragraph = paragraph(sentence_count: 3)

lib/faker/default/address.rb

@@ -6,9 +6,8 @@ class Address < Base
 
     class << self
       def city(legacy_options = NOT_GIVEN, options: {})
-        if legacy_options != NOT_GIVEN
-          warn_with_uplevel 'Passing `options` with the 1st argument of `Address.city` is deprecated. Use keyword argument like `Address.city(options: ...)` instead.', uplevel: 1
-          options = legacy_options
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :options if legacy_options != NOT_GIVEN
         end
 
         parse(options[:with_state] ? 'address.city_with_state' : 'address.city')
@@ -19,9 +18,8 @@ def street_name
       end
 
       def street_address(legacy_include_secondary = NOT_GIVEN, include_secondary: false)
-        if legacy_include_secondary != NOT_GIVEN
-          warn_with_uplevel 'Passing `include_secondary` with the 1st argument of `Address.street_address` is deprecated. Use keyword argument like `Address.street_address(include_secondary: ...)` instead.', uplevel: 1
-          include_secondary = legacy_include_secondary
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :include_secondary if legacy_include_secondary != NOT_GIVEN
         end
 
         numerify(parse('address.street_address') + (include_secondary ? ' ' + secondary_address : ''))
@@ -40,9 +38,8 @@ def community
       end
 
       def zip_code(legacy_state_abbreviation = NOT_GIVEN, state_abbreviation: '')
-        if legacy_state_abbreviation != NOT_GIVEN
-          warn_with_uplevel 'Passing `state_abbreviation` with the 1st argument of `Address.zip_code` is deprecated. Use keyword argument like `Address.zip_code(state_abbreviation: ...)` instead.', uplevel: 1
-          state_abbreviation = legacy_state_abbreviation
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :state_abbreviation if legacy_state_abbreviation != NOT_GIVEN
         end
 
         if state_abbreviation.empty?
@@ -87,18 +84,16 @@ def country
       end
 
       def country_by_code(legacy_code = NOT_GIVEN, code: 'US')
-        if legacy_code != NOT_GIVEN
-          warn_with_uplevel 'Passing `code` with the 1st argument of `Address.country_by_code` is deprecated. Use keyword argument like `Address.country_by_code(code: ...)` instead.', uplevel: 1
-          code = legacy_code
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :code if legacy_code != NOT_GIVEN
         end
 
         fetch('address.country_by_code.' + code)
       end
 
       def country_name_to_code(legacy_name = NOT_GIVEN, name: 'united_states')
-        if legacy_name != NOT_GIVEN
-          warn_with_uplevel 'Passing `name` with the 1st argument of `Address.country_name_to_code` is deprecated. Use keyword argument like `Address.country_name_to_code(name: ...)` instead.', uplevel: 1
-          name = legacy_name
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :name if legacy_name != NOT_GIVEN
         end
 
         fetch('address.country_by_name.' + name)

lib/faker/default/alphanumeric.rb

@@ -6,9 +6,8 @@ class Alphanumeric < Base
 
     class << self
       def alpha(legacy_number = NOT_GIVEN, number: 32)
-        if legacy_number != NOT_GIVEN
-          warn_with_uplevel 'Passing `number` with the 1st argument of `Alphanumeric.alpha` is deprecated. Use keyword argument like `Alphanumeric.alpha(number: ...)` instead.', uplevel: 1
-          number = legacy_number
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
         end
         char_count = resolve(number)
         return '' if char_count.to_i < 1
@@ -31,9 +30,8 @@ def alpha(legacy_number = NOT_GIVEN, number: 32)
       #
       # @faker.version 2.1.3
       def alphanumeric(legacy_number = NOT_GIVEN, number: 32, min_alpha: 0, min_numeric: 0)
-        if legacy_number != NOT_GIVEN
-          warn_with_uplevel 'Passing `number` with the 1st argument of `Alphanumeric.alphanumeric` is deprecated. Use keyword argument like `Alphanumeric.alphanumeric(number: ...)` instead.', uplevel: 1
-          number = legacy_number
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
         end
         char_count = resolve(number)
         return '' if char_count.to_i < 1

lib/faker/default/app.rb

@@ -18,17 +18,10 @@ def author
       # rubocop:disable Metrics/ParameterLists
       def semantic_version(legacy_major = NOT_GIVEN, legacy_minor = NOT_GIVEN, legacy_patch = NOT_GIVEN, major: 0..9, minor: 0..9, patch: 1..9)
         # rubocop:enable Metrics/ParameterLists
-        if legacy_major != NOT_GIVEN
-          warn_with_uplevel 'Passing `major` with the 1st argument of `App.semantic_version` is deprecated. Use keyword argument like `App.semantic_version(major: ...)` instead.', uplevel: 1
-          major = legacy_major
-        end
-        if legacy_minor != NOT_GIVEN
-          warn_with_uplevel 'Passing `minor` with the 2nd argument of `App.semantic_version` is deprecated. Use keyword argument like `App.semantic_version(minor: ...)` instead.', uplevel: 1
-          minor = legacy_minor
-        end
-        if legacy_patch != NOT_GIVEN
-          warn_with_uplevel 'Passing `patch` with the 3rd argument of `App.semantic_version` is deprecated. Use keyword argument like `App.semantic_version(patch: ...)` instead.', uplevel: 1
-          patch = legacy_patch
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :major if legacy_major != NOT_GIVEN
+          keywords << :minor if legacy_minor != NOT_GIVEN
+          keywords << :patch if legacy_patch != NOT_GIVEN
         end
 
         [major, minor, patch].map { |chunk| sample(Array(chunk)) }.join('.')

lib/faker/default/avatar.rb

@@ -8,25 +8,12 @@ class << self
       # rubocop:disable Metrics/ParameterLists
       def image(legacy_slug = NOT_GIVEN, legacy_size = NOT_GIVEN, legacy_format = NOT_GIVEN, legacy_set = NOT_GIVEN, legacy_bgset = NOT_GIVEN, slug: nil, size: '300x300', format: 'png', set: 'set1', bgset: nil)
         # rubocop:enable Metrics/ParameterLists
-        if legacy_slug != NOT_GIVEN
-          warn_with_uplevel 'Passing `slug` with the 1st argument of `Avatar.image` is deprecated. Use keyword argument like `Avatar.image(slug: ...)` instead.', uplevel: 1
-          slug = legacy_slug
-        end
-        if legacy_size != NOT_GIVEN
-          warn_with_uplevel 'Passing `size` with the 2nd argument of `Avatar.image` is deprecated. Use keyword argument like `Avatar.image(size: ...)` instead.', uplevel: 1
-          size = legacy_size
-        end
-        if legacy_format != NOT_GIVEN
-          warn_with_uplevel 'Passing `format` with the 3rd argument of `Avatar.image` is deprecated. Use keyword argument like `Avatar.image(format: ...)` instead.', uplevel: 1
-          format = legacy_format
-        end
-        if legacy_set != NOT_GIVEN
-          warn_with_uplevel 'Passing `set` with the 4th argument of `Avatar.image` is deprecated. Use keyword argument like `Avatar.image(set: ...)` instead.', uplevel: 1
-          set = legacy_set
-        end
-        if legacy_bgset != NOT_GIVEN
-          warn_with_uplevel 'Passing `bgset` with the 5th argument of `Avatar.image` is deprecated. Use keyword argument like `Avatar.image(bgset: ...)` instead.', uplevel: 1
-          bgset = legacy_bgset
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :slug if legacy_slug != NOT_GIVEN
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :format if legacy_format != NOT_GIVEN
+          keywords << :set if legacy_set != NOT_GIVEN
+          keywords << :bgset if legacy_bgset != NOT_GIVEN
         end
 
         raise ArgumentError, 'Size should be specified in format 300x300' unless size =~ /^[0-9]+x[0-9]+$/

lib/faker/default/bank.rb

@@ -6,9 +6,8 @@ class Bank < Base
 
     class << self
       def account_number(legacy_digits = NOT_GIVEN, digits: 10)
-        if legacy_digits != NOT_GIVEN
-          warn_with_uplevel 'Passing `digits` with the 1st argument of `Bank.account_number` is deprecated. Use keyword argument like `Bank.account_number(digits: ...)` instead.', uplevel: 1
-          digits = legacy_digits
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
         end
 
         output = ''
@@ -22,9 +21,8 @@ def iban(legacy_country_code = NOT_GIVEN, country_code: 'GB')
         # Each country has it's own format for bank accounts
         # Many of them use letters in certain parts of the account
         # Using regex patterns we can create virtually any type of bank account
-        if legacy_country_code != NOT_GIVEN
-          warn_with_uplevel 'Passing `country_code` with the 1st argument of `Bank.iban` is deprecated. Use keyword argument like `Bank.iban(country_code: ...)` instead.', uplevel: 1
-          country_code = legacy_country_code
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :country_code if legacy_country_code != NOT_GIVEN
         end
 
         begin

lib/faker/default/boolean.rb

@@ -4,9 +4,8 @@ module Faker
   class Boolean < Base
     class << self
       def boolean(legacy_true_ratio = NOT_GIVEN, true_ratio: 0.5)
-        if legacy_true_ratio != NOT_GIVEN
-          warn_with_uplevel 'Passing `true_ratio` with the 1st argument of `Boolean.boolean` is deprecated. Use keyword argument like `Boolean.boolean(true_ratio: ...)` instead.', uplevel: 1
-          true_ratio = legacy_true_ratio
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :true_ratio if legacy_true_ratio != NOT_GIVEN
         end
 
         (rand < true_ratio)

lib/faker/default/chile_rut.rb

@@ -7,13 +7,9 @@ class << self
 
       # Fixed param added for testing a specific RUT and check digit combination.
       def rut(legacy_min_rut = NOT_GIVEN, legacy_fixed = NOT_GIVEN, min_rut: 1, fixed: false)
-        if legacy_min_rut != NOT_GIVEN
-          warn_with_uplevel 'Passing `min_rut` with the 1st argument of `ChileRut.rut` is deprecated. Use keyword argument like `ChileRut.rut(min_rut: ...)` instead.', uplevel: 1
-          min_rut = legacy_min_rut
-        end
-        if legacy_fixed != NOT_GIVEN
-          warn_with_uplevel 'Passing `fixed` with the 2nd argument of `ChileRut.rut` is deprecated. Use keyword argument like `ChileRut.rut(fixed: ...)` instead.', uplevel: 1
-          fixed = legacy_fixed
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :min_rut if legacy_min_rut != NOT_GIVEN
+          keywords << :fixed if legacy_fixed != NOT_GIVEN
         end
 
         @last_rut = fixed ? min_rut : rand_in_range(min_rut, 99_999_999)
@@ -44,13 +40,9 @@ def check_digit
       end
 
       def full_rut(legacy_min_rut = NOT_GIVEN, legacy_fixed = NOT_GIVEN, min_rut: 0, fixed: false)
-        if legacy_min_rut != NOT_GIVEN
-          warn_with_uplevel 'Passing `min_rut` with the 1st argument of `ChileRut.full_rut` is deprecated. Use keyword argument like `ChileRut.full_rut(min_rut: ...)` instead.', uplevel: 1
-          min_rut = legacy_min_rut
-        end
-        if legacy_fixed != NOT_GIVEN
-          warn_with_uplevel 'Passing `fixed` with the 2nd argument of `ChileRut.full_rut` is deprecated. Use keyword argument like `ChileRut.full_rut(fixed: ...)` instead.', uplevel: 1
-          fixed = legacy_fixed
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :min_rut if legacy_min_rut != NOT_GIVEN
+          keywords << :fixed if legacy_fixed != NOT_GIVEN
         end
 
         "#{rut(min_rut: min_rut, fixed: fixed)}-#{dv}"