Add option OnlyFor to the Bundler/GemComment cop.

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### New features
 
+* [#7978](https://github.com/rubocop-hq/rubocop/pull/7978): Add new option `OnlyWhenUsingAnyOf` to the `Bumdler/GemComment` cop. ([@ric2b][])
 * [#7735](https://github.com/rubocop-hq/rubocop/issues/7735): `NodePattern` and `AST` classes have been moved to the [`rubocop-ast` gem](https://github.com/rubocop-hq/rubocop-ast). ([@marcandre][])
 * [#7950](https://github.com/rubocop-hq/rubocop/pull/7950): Add new `Lint/DeprecatedOpenSSLConstant` cop. ([@bdewater][])
 
@@ -4524,3 +4525,4 @@
 [@jeffcarbs]: https://github.com/jeffcarbs
 [@laurmurclar]: https://github.com/laurmurclar
 [@jethrodaniel]: https://github.com/jethrodaniel
+[@ric2b]: https://github.com/ric2b

config/default.yml

@@ -159,6 +159,7 @@ Bundler/GemComment:
     - '**/Gemfile'
     - '**/gems.rb'
   IgnoredGems: []
+  OnlyWhenUsingAnyOf: []
 
 Bundler/InsecureProtocolSource:
   Description: >-

lib/rubocop/cop/bundler/gem_comment.rb

@@ -5,7 +5,13 @@ module Cop
     module Bundler
       # Add a comment describing each gem in your Gemfile.
       #
-      # @example
+      # Optionally, the "OnlyWhenUsingAnyOf" configuration
+      # can be used to only register offenses when the gems
+      # use certain options or have version specifiers.
+      # Add "with_version_specifiers" and/or the option names
+      # (e.g. 'required', 'github', etc) you want to check.
+      #
+      # @example OnlyWhenUsingAnyOf: [] (default)
       #   # bad
       #
       #   gem 'foo'
@@ -15,17 +21,45 @@ module Bundler
       #   # Helpers for the foo things.
       #   gem 'foo'
       #
+      # @example OnlyWhenUsingAnyOf: ['with_version_specifiers']
+      #   # bad
+      #
+      #   gem 'foo', '< 2.1'
+      #
+      #   # good
+      #
+      #   # Version 2.1 introduces breaking change baz
+      #   gem 'foo', '< 2.1'
+      #
+      # @example OnlyWhenUsingAnyOf: ['with_version_specifiers', 'github']
+      #   # bad
+      #
+      #   gem 'foo', github: 'some_account/some_fork_of_foo'
+      #
+      #   gem 'bar', '< 2.1'
+      #
+      #   # good
+      #
+      #   # Using this fork because baz
+      #   gem 'foo', github: 'some_account/some_fork_of_foo'
+      #
+      #   # Version 2.1 introduces breaking change baz
+      #   gem 'bar', '< 2.1'
+      #
       class GemComment < Cop
         include DefNode
 
         MSG = 'Missing gem description comment.'
+        CHECKED_OPTIONS_CONFIG = 'OnlyWhenUsingAnyOf'
+        VERSION_SPECIFIERS_OPTION = 'with_version_specifiers'
 
         def_node_matcher :gem_declaration?, '(send nil? :gem str ...)'
 
         def on_send(node)
           return unless gem_declaration?(node)
           return if ignored_gem?(node)
           return if commented?(node)
+          return if cop_config[CHECKED_OPTIONS_CONFIG].any? && !checked_options_present?(node)
 
           add_offense(node)
         end
@@ -58,6 +92,28 @@ def ignored_gem?(node)
           ignored_gems = Array(cop_config['IgnoredGems'])
           ignored_gems.include?(node.first_argument.value)
         end
+
+        def checked_options_present?(node)
+          cop_config[CHECKED_OPTIONS_CONFIG].include?(VERSION_SPECIFIERS_OPTION) && version_specified_gem?(node) \
+          or contains_checked_options?(node)
+        end
+
+        # Besides the gem name, all other *positional* arguments to `gem` are version specifiers,
+        # as long as it has one we know there's at least one version specifier.
+        def version_specified_gem?(node)
+          # arguments[0] is the gem name
+          node.arguments[1]&.str_type? == true
+        end
+
+        def contains_checked_options?(node)
+          (Array(cop_config[CHECKED_OPTIONS_CONFIG]) & gem_options(node).map(&:to_s)).any?
+        end
+
+        def gem_options(node)
+          return [] unless node.arguments.last&.type == :hash
+
+          node.arguments.last.keys.map(&:value)
+        end
       end
     end
   end

manual/cops_bundler.md

@@ -47,8 +47,16 @@ Disabled | Yes | No | 0.59 | 0.77
 
 Add a comment describing each gem in your Gemfile.
 
+Optionally, the "OnlyWhenUsingAnyOf" configuration
+can be used to only register offenses when the gems
+use certain options or have version specifiers.
+Add "with_version_specifiers" and/or the option names
+(e.g. 'required', 'github', etc) you want to check.
+
 ### Examples
 
+#### OnlyWhenUsingAnyOf: [] (default)
+
 ```ruby
 # bad
 
@@ -59,13 +67,43 @@ gem 'foo'
 # Helpers for the foo things.
 gem 'foo'
 ```
+#### OnlyWhenUsingAnyOf: ['with_version_specifiers']
+
+```ruby
+# bad
+
+gem 'foo', '< 2.1'
+
+# good
+
+# Version 2.1 introduces breaking change baz
+gem 'foo', '< 2.1'
+```
+#### OnlyWhenUsingAnyOf: ['with_version_specifiers', 'github']
+
+```ruby
+# bad
+
+gem 'foo', github: 'some_account/some_fork_of_foo'
+
+gem 'bar', '< 2.1'
+
+# good
+
+# Using this fork because baz
+gem 'foo', github: 'some_account/some_fork_of_foo'
+
+# Version 2.1 introduces breaking change baz
+gem 'bar', '< 2.1'
+```
 
 ### Configurable attributes
 
 Name | Default value | Configurable values
 --- | --- | ---
 Include | `**/*.gemfile`, `**/Gemfile`, `**/gems.rb` | Array
 IgnoredGems | `[]` | Array
+OnlyWhenUsingAnyOf | `[]` | Array
 
 ## Bundler/InsecureProtocolSource
 

spec/rubocop/cop/bundler/gem_comment_spec.rb

@@ -6,7 +6,8 @@
   let(:cop_config) do
     {
       'Include' => ['**/Gemfile'],
-      'IgnoredGems' => ['rake']
+      'IgnoredGems' => ['rake'],
+      'OnlyWhenUsingAnyOf' => []
     }
   end
 
@@ -63,5 +64,76 @@
         GEM
       end
     end
+
+    context 'and the OnlyWhenUsingAnyOf option is set' do
+      before { cop_config['OnlyWhenUsingAnyOf'] = checked_options }
+
+      context 'and version specifiers are checked' do
+        let(:checked_options) { ['with_version_specifiers'] }
+
+        it 'does not register an offense if a gem is commented' do
+          expect_no_offenses(<<~RUBY, 'Gemfile')
+            # Style-guide enforcer.
+            gem 'rubocop'
+          RUBY
+        end
+
+        it 'does not register an offense if an uncommented gem has no options' do
+          expect_no_offenses(<<-GEM, 'Gemfile')
+            gem 'rubocop'
+          GEM
+        end
+
+        it 'does not register an offense if an uncommented gem has options but no version specifiers' do
+          expect_no_offenses(<<-GEM, 'Gemfile')
+            gem 'rubocop', group: development
+          GEM
+        end
+
+        it 'registers an offense if an uncommented gem has a version specifier' do
+          expect_offense(<<-GEM, 'Gemfile')
+              gem 'rubocop', '~> 12.0'
+              ^^^^^^^^^^^^^^^^^^^^^^^^ Missing gem description comment.
+          GEM
+        end
+
+        it 'registers an offense if an uncommented gem has multiple version specifiers' do
+          expect_offense(<<-GEM, 'Gemfile')
+              gem 'rubocop', '~> 12.0', '>= 11.0'
+              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Missing gem description comment.
+          GEM
+        end
+
+        it 'registers an offense if an uncommented gem has version specifiers and unrelated options' do
+          expect_offense(<<-GEM, 'Gemfile')
+            gem 'rubocop', '~> 12.0', required: true
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Missing gem description comment.
+          GEM
+        end
+      end
+
+      context 'and some other options are checked' do
+        let(:checked_options) { %w[github required] }
+
+        it 'registers an offense if an uncommented gem has one of the checked options' do
+          expect_offense(<<-GEM, 'Gemfile')
+            gem 'rubocop', github: 'some_user/some_fork'
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Missing gem description comment.
+          GEM
+        end
+
+        it 'does not register an offense if an uncommented gem has version specifiers but no other options' do
+          expect_no_offenses(<<-GEM, 'Gemfile')
+            gem 'rubocop', '~> 12.0'
+          GEM
+        end
+
+        it 'does not register an offense if an uncommented gem has only unchecked options' do
+          expect_no_offenses(<<-GEM, 'Gemfile')
+            gem 'rubocop', group: development
+          GEM
+        end
+      end
+    end
   end
 end