rubocop 1.18.1 → 1.22.3

data/lib/rubocop/cop/style/case_like_if.rb

@@ -6,6 +6,11 @@ module RuboCop
       # This cop identifies places where `if-elsif` constructions
       # can be replaced with `case-when`.
       #
+      # @safety
+      #   This cop is unsafe. `case` statements use `===` for equality,
+      #   so if the original conditional used a different equality operator, the
+      #   behaviour may be different.
+      #
       # @example
       #   # bad
       #   if status == :active

data/lib/rubocop/cop/style/class_and_module_children.rb

@@ -6,6 +6,15 @@ module RuboCop
       # This cop checks the style of children definitions at classes and
       # modules. Basically there are two different styles:
       #
+      # @safety
+      #   Autocorrection is unsafe.
+      #
+      #   Moving from compact to nested children requires knowledge of whether the
+      #   outer parent is a module or a class. Moving from nested to compact requires
+      #   verification that the outer parent is defined elsewhere. Rubocop does not
+      #   have the knowledge to perform either operation safely and thus requires
+      #   manual oversight.
+      #
       # @example EnforcedStyle: nested (default)
       #   # good
       #   # have each child on its own line

data/lib/rubocop/cop/style/collection_compact.rb

@@ -6,11 +6,13 @@ module RuboCop
       # This cop checks for places where custom logic on rejection nils from arrays
       # and hashes can be replaced with `{Array,Hash}#{compact,compact!}`.
       #
-      # It is marked as unsafe by default because false positives may occur in the
-      # nil check of block arguments to the receiver object.
-      # For example, `[[1, 2], [3, nil]].reject { |first, second| second.nil? }`
-      # and `[[1, 2], [3, nil]].compact` are not compatible. This will work fine
-      # when the receiver is a hash object.
+      # @safety
+      #   It is unsafe by default because false positives may occur in the
+      #   `nil` check of block arguments to the receiver object.
+      #
+      #   For example, `[[1, 2], [3, nil]].reject { |first, second| second.nil? }`
+      #   and `[[1, 2], [3, nil]].compact` are not compatible. This will work fine
+      #   when the receiver is a hash object.
       #
       # @example
       #   # bad

data/lib/rubocop/cop/style/collection_methods.rb

@@ -6,10 +6,6 @@ module RuboCop
       # This cop enforces the use of consistent method names
       # from the Enumerable module.
       #
-      # Unfortunately we cannot actually know if a method is from
-      # Enumerable or not (static analysis limitation), so this cop
-      # can yield some false positives.
-      #
       # You can customize the mapping from undesired method to desired method.
       #
       # e.g. to use `detect` over `find`:
@@ -18,9 +14,14 @@ module RuboCop
       #     PreferredMethods:
       #       find: detect
       #
-      # The default mapping for `PreferredMethods` behaves as follows.
+      # @safety
+      #   This cop is unsafe because it finds methods by name, without actually
+      #   being able to determine if the receiver is an Enumerable or not, so
+      #   this cop may register false positives.
       #
       # @example
+      #   # These examples are based on the default mapping for `PreferredMethods`.
+      #
       #   # bad
       #   items.collect
       #   items.collect!
@@ -68,7 +69,8 @@ module RuboCop
           return false unless node.arguments.any?
 
           node.last_argument.block_pass_type? ||
-            node.last_argument.sym_type? && methods_accepting_symbol.include?(node.method_name.to_s)
+            (node.last_argument.sym_type? &&
+            methods_accepting_symbol.include?(node.method_name.to_s))
         end
 
         def message(node)

data/lib/rubocop/cop/style/combinable_loops.rb

@@ -7,8 +7,9 @@ module RuboCop
       # can be combined into a single loop. It is very likely that combining them
       # will make the code more efficient and more concise.
       #
-      # It is marked as unsafe, because the first loop might modify
-      # a state that the second loop depends on; these two aren't combinable.
+      # @safety
+      #   The cop is unsafe, because the first loop might modify state that the
+      #   second loop depends on; these two aren't combinable.
       #
       # @example
       #   # bad

data/lib/rubocop/cop/style/comment_annotation.rb

@@ -6,13 +6,16 @@ module RuboCop
       # This cop checks that comment annotation keywords are written according
       # to guidelines.
       #
+      # Annotation keywords can be specified by overriding the cop's `Keywords`
+      # configuration. Keywords are allowed to be single words or phrases.
+      #
       # NOTE: With a multiline comment block (where each line is only a
       # comment), only the first line will be able to register an offense, even
       # if an annotation keyword starts another line. This is done to prevent
       # incorrect registering of keywords (eg. `review`) inside a paragraph as an
       # annotation.
       #
-      # @example
+      # @example RequireColon: true (default)
       #   # bad
       #   # TODO make better
       #
@@ -36,14 +39,35 @@ module RuboCop
       #
       #   # good
       #   # OPTIMIZE: does not work
+      #
+      # @example RequireColon: false
+      #   # bad
+      #   # TODO: make better
+      #
+      #   # good
+      #   # TODO make better
+      #
+      #   # bad
+      #   # fixme does not work
+      #
+      #   # good
+      #   # FIXME does not work
+      #
+      #   # bad
+      #   # Optimize does not work
+      #
+      #   # good
+      #   # OPTIMIZE does not work
       class CommentAnnotation < Base
-        include AnnotationComment
         include RangeHelp
         extend AutoCorrector
 
-        MSG = 'Annotation keywords like `%<keyword>s` should be all ' \
-              'upper case, followed by a colon, and a space, ' \
-              'then a note describing the problem.'
+        MSG_COLON_STYLE = 'Annotation keywords like `%<keyword>s` should be all ' \
+                          'upper case, followed by a colon, and a space, ' \
+                          'then a note describing the problem.'
+        MSG_SPACE_STYLE = 'Annotation keywords like `%<keyword>s` should be all ' \
+                          'upper case, followed by a space, ' \
+                          'then a note describing the problem.'
         MISSING_NOTE = 'Annotation comment, with keyword `%<keyword>s`, is missing a note.'
 
         def on_new_investigation
@@ -51,25 +75,27 @@ module RuboCop
             next unless first_comment_line?(processed_source.comments, index) ||
                         inline_comment?(comment)
 
-            margin, first_word, colon, space, note = split_comment(comment)
-            next unless annotation?(comment) && !correct_annotation?(first_word, colon, space, note)
+            annotation = AnnotationComment.new(comment, keywords)
+            next unless annotation.annotation? && !annotation.correct?(colon: requires_colon?)
 
-            range = annotation_range(comment, margin, first_word, colon, space)
-
-            register_offense(range, note, first_word)
+            register_offense(annotation)
           end
         end
 
         private
 
-        def register_offense(range, note, first_word)
-          add_offense(
-            range,
-            message: format(note ? MSG : MISSING_NOTE, keyword: first_word)
-          ) do |corrector|
-            next if note.nil?
+        def register_offense(annotation)
+          range = annotation_range(annotation)
+          message = if annotation.note
+                      requires_colon? ? MSG_COLON_STYLE : MSG_SPACE_STYLE
+                    else
+                      MISSING_NOTE
+                    end
+
+          add_offense(range, message: format(message, keyword: annotation.keyword)) do |corrector|
+            next if annotation.note.nil?
 
-            corrector.replace(range, "#{first_word.upcase}: ")
+            correct_offense(corrector, range, annotation.keyword)
           end
         end
 
@@ -81,18 +107,22 @@ module RuboCop
           !comment_line?(comment.loc.expression.source_line)
         end
 
-        def annotation_range(comment, margin, first_word, colon, space)
-          start = comment.loc.expression.begin_pos + margin.length
-          length = concat_length(first_word, colon, space)
-          range_between(start, start + length)
+        def annotation_range(annotation)
+          range_between(*annotation.bounds)
+        end
+
+        def correct_offense(corrector, range, keyword)
+          return corrector.replace(range, "#{keyword.upcase}: ") if requires_colon?
+
+          corrector.replace(range, "#{keyword.upcase} ")
         end
 
-        def concat_length(*args)
-          args.reduce(0) { |acc, elem| acc + elem.to_s.length }
+        def requires_colon?
+          cop_config['RequireColon']
         end
 
-        def correct_annotation?(first_word, colon, space, note)
-          keyword?(first_word) && (colon && space && note || !colon && !note)
+        def keywords
+          cop_config['Keywords']
         end
       end
     end

data/lib/rubocop/cop/style/commented_keyword.rb

@@ -13,6 +13,10 @@ module RuboCop
       # Auto-correction removes comments from `end` keyword and keeps comments
       # for `class`, `module`, `def` and `begin` above the keyword.
       #
+      # @safety
+      #   Auto-correction is unsafe because it may remove a comment that is
+      #   meaningful.
+      #
       # @example
       #   # bad
       #   if condition
@@ -48,9 +52,11 @@ module RuboCop
         ALLOWED_COMMENTS = %w[:nodoc: :yields: rubocop:disable rubocop:todo].freeze
         ALLOWED_COMMENT_REGEXES = ALLOWED_COMMENTS.map { |c| /#\s*#{c}/ }.freeze
 
+        REGEXP = /(?<keyword>\S+).*#/.freeze
+
         def on_new_investigation
           processed_source.comments.each do |comment|
-            next unless (match = line(comment).match(/(?<keyword>\S+).*#/)) && offensive?(comment)
+            next unless offensive?(comment) && (match = source_line(comment).match(REGEXP))
 
             register_offense(comment, match[:keyword])
           end
@@ -72,12 +78,12 @@ module RuboCop
         end
 
         def offensive?(comment)
-          line = line(comment)
+          line = source_line(comment)
           KEYWORD_REGEXES.any? { |r| r.match?(line) } &&
             ALLOWED_COMMENT_REGEXES.none? { |r| r.match?(line) }
         end
 
-        def line(comment)
+        def source_line(comment)
           comment.location.expression.source_line
         end
       end

data/lib/rubocop/cop/style/conditional_assignment.rb

@@ -26,7 +26,7 @@ module RuboCop
         # `when` nodes contain the entire branch including the condition.
         # We only need the contents of the branch, not the condition.
         def expand_when_branches(when_branches)
-          when_branches.map { |branch| branch.children[1] }
+          when_branches.map(&:body)
         end
 
         def tail(branch)
@@ -272,6 +272,16 @@ module RuboCop
           check_node(node, branches)
         end
 
+        def on_case_match(node)
+          return unless style == :assign_to_condition
+          return unless node.else_branch
+
+          in_pattern_branches = expand_when_branches(node.in_pattern_branches)
+          branches = [*in_pattern_branches, node.else_branch]
+
+          check_node(node, branches)
+        end
+
         private
 
         def check_assignment_to_condition(node)
@@ -297,7 +307,7 @@ module RuboCop
         end
 
         # @!method candidate_condition?(node)
-        def_node_matcher :candidate_condition?, '[{if case} !#allowed_ternary?]'
+        def_node_matcher :candidate_condition?, '[{if case case_match} !#allowed_ternary?]'
 
         def allowed_ternary?(assignment)
           assignment.if_type? && assignment.ternary? && !include_ternary?
@@ -319,7 +329,7 @@ module RuboCop
         end
 
         def move_assignment_outside_condition(corrector, node)
-          if node.case_type?
+          if node.case_type? || node.case_match_type?
             CaseCorrector.correct(corrector, self, node)
           elsif node.ternary?
             TernaryCorrector.correct(corrector, node)
@@ -333,7 +343,7 @@ module RuboCop
 
           if ternary_condition?(condition)
             TernaryCorrector.move_assignment_inside_condition(corrector, node)
-          elsif condition.case_type?
+          elsif condition.case_type? || condition.case_match_type?
             CaseCorrector.move_assignment_inside_condition(corrector, node)
           elsif condition.if_type?
             IfCorrector.move_assignment_inside_condition(corrector, node)
@@ -631,7 +641,11 @@ module RuboCop
           end
 
           def extract_branches(case_node)
-            when_branches = expand_when_branches(case_node.when_branches)
+            when_branches = if case_node.case_type?
+                              expand_when_branches(case_node.when_branches)
+                            else
+                              expand_when_branches(case_node.in_pattern_branches)
+                            end
 
             [when_branches, case_node.else_branch]
           end

data/lib/rubocop/cop/style/date_time.rb

@@ -9,6 +9,11 @@ module RuboCop
       # replaceable in certain situations when dealing with multiple timezones
       # and/or DST.
       #
+      # @safety
+      #   Autocorrection is not safe, because `DateTime` and `Time` do not have
+      #   exactly the same behaviour, although in most cases the autocorrection
+      #   will be fine.
+      #
       # @example
       #
       #   # bad - uses `DateTime` for current time

data/lib/rubocop/cop/style/document_dynamic_eval_definition.rb

@@ -86,7 +86,7 @@ module RuboCop
 
           return unless arg_node&.dstr_type? && interpolated?(arg_node)
           return if inline_comment_docs?(arg_node) ||
-                    arg_node.heredoc? && comment_block_docs?(arg_node)
+                    (arg_node.heredoc? && comment_block_docs?(arg_node))
 
           add_offense(node.loc.selector)
         end

data/lib/rubocop/cop/style/documentation.rb

@@ -71,8 +71,9 @@ module RuboCop
       #
       class Documentation < Base
         include DocumentationComment
+        include RangeHelp
 
-        MSG = 'Missing top-level %<type>s documentation comment.'
+        MSG = 'Missing top-level documentation comment for `%<type>s %<identifier>s`.'
 
         # @!method constant_definition?(node)
         def_node_matcher :constant_definition?, '{class module casgn}'
@@ -88,33 +89,35 @@ module RuboCop
         def on_class(node)
           return unless node.body
 
-          check(node, node.body, :class)
+          check(node, node.body)
         end
 
         def on_module(node)
-          check(node, node.body, :module)
+          check(node, node.body)
         end
 
         private
 
-        def check(node, body, type)
+        def check(node, body)
           return if namespace?(body)
           return if documentation_comment?(node)
           return if constant_allowed?(node)
           return if nodoc_self_or_outer_module?(node)
           return if macro_only?(body)
 
-          add_offense(node.loc.keyword, message: format(MSG, type: type))
+          range = range_between(node.loc.expression.begin_pos, node.loc.name.end_pos)
+          message = format(MSG, type: node.type, identifier: identifier(node))
+          add_offense(range, message: message)
         end
 
         def nodoc_self_or_outer_module?(node)
           nodoc_comment?(node) ||
-            compact_namespace?(node) && nodoc_comment?(outer_module(node).first)
+            (compact_namespace?(node) && nodoc_comment?(outer_module(node).first))
         end
 
         def macro_only?(body)
-          body.respond_to?(:macro?) && body.macro? ||
-            body.respond_to?(:children) && body.children&.all? { |child| macro_only?(child) }
+          (body.respond_to?(:macro?) && body.macro?) ||
+            (body.respond_to?(:children) && body.children&.all? { |child| macro_only?(child) })
         end
 
         def namespace?(node)
@@ -165,6 +168,18 @@ module RuboCop
         def allowed_constants
           @allowed_constants ||= cop_config.fetch('AllowedConstants', []).map(&:intern)
         end
+
+        def identifier(node)
+          # Get the fully qualified identifier for a class/module
+          nodes = [node, *node.each_ancestor(:class, :module)]
+          nodes.reverse_each.flat_map { |n| qualify_const(n.identifier) }.join('::')
+        end
+
+        def qualify_const(node)
+          return if node.nil?
+
+          [qualify_const(node.namespace), node.short_name].compact
+        end
       end
     end
   end

data/lib/rubocop/cop/style/double_cop_disable_directive.rb

@@ -36,13 +36,7 @@ module RuboCop
             next unless comment.text.scan(/# rubocop:(?:disable|todo)/).size > 1
 
             add_offense(comment) do |corrector|
-              prefix = if comment.text.start_with?('# rubocop:disable')
-                         '# rubocop:disable'
-                       else
-                         '# rubocop:todo'
-                       end
-
-              corrector.replace(comment, comment.text[/#{prefix} \S+/])
+              corrector.replace(comment, comment.text.gsub(%r{ # rubocop:(disable|todo)}, ','))
             end
           end
         end

data/lib/rubocop/cop/style/double_negation.rb

@@ -9,6 +9,21 @@ module RuboCop
       # that use boolean as a return value. When using `EnforcedStyle: forbidden`, double negation
       # should be forbidden always.
       #
+      # NOTE: when `something` is a boolean value
+      # `!!something` and `!something.nil?` are not the same thing.
+      # As you're unlikely to write code that can accept values of any type
+      # this is rarely a problem in practice.
+      #
+      # @safety
+      #   Autocorrection is unsafe when the value is `false`, because the result
+      #   of the expression will change.
+      #
+      #   [source,ruby]
+      #   ----
+      #   !!false     #=> false
+      #   !false.nil? #=> true
+      #   ----
+      #
       # @example
       #   # bad
       #   !!something
@@ -27,11 +42,6 @@ module RuboCop
       #   def foo?
       #     !!return_value
       #   end
-      #
-      # Please, note that when something is a boolean value
-      # !!something and !something.nil? are not the same thing.
-      # As you're unlikely to write code that can accept values of any type
-      # this is rarely a problem in practice.
       class DoubleNegation < Base
         include ConfigurableEnforcedStyle
         extend AutoCorrector
@@ -62,7 +72,7 @@ module RuboCop
         def end_of_method_definition?(node)
           return false unless (def_node = find_def_node_from_ascendant(node))
 
-          last_child = def_node.child_nodes.last
+          last_child = find_last_child(def_node.body)
 
           last_child.last_line == node.last_line
         end
@@ -73,6 +83,17 @@ module RuboCop
 
           find_def_node_from_ascendant(node.parent)
         end
+
+        def find_last_child(node)
+          case node.type
+          when :rescue
+            find_last_child(node.body)
+          when :ensure
+            find_last_child(node.child_nodes.first)
+          else
+            node.child_nodes.last
+          end
+        end
       end
     end
   end

data/lib/rubocop/cop/style/empty_method.rb

@@ -62,7 +62,7 @@ module RuboCop
         end
 
         def correct_style?(node)
-          compact_style? && compact?(node) || expanded_style? && expanded?(node)
+          (compact_style? && compact?(node)) || (expanded_style? && expanded?(node))
         end
 
         def corrected(node)

data/lib/rubocop/cop/style/encoding.rb

@@ -13,38 +13,49 @@ module RuboCop
         include RangeHelp
         extend AutoCorrector
 
-        MSG_UNNECESSARY = 'Unnecessary utf-8 encoding comment.'
+        MSG = 'Unnecessary utf-8 encoding comment.'
         ENCODING_PATTERN = /#.*coding\s?[:=]\s?(?:UTF|utf)-8/.freeze
         SHEBANG = '#!'
 
         def on_new_investigation
           return if processed_source.buffer.source.empty?
 
-          line_number = encoding_line_number(processed_source)
-          return unless (@message = offense(processed_source, line_number))
+          comments.each do |line_number, comment|
+            next unless offense?(comment)
 
-          range = processed_source.buffer.line_range(line_number + 1)
-          add_offense(range, message: @message) do |corrector|
-            corrector.remove(range_with_surrounding_space(range: range, side: :right))
+            register_offense(line_number, comment)
           end
         end
 
         private
 
-        def offense(processed_source, line_number)
-          line = processed_source[line_number]
+        def comments
+          processed_source.lines.each.with_index.with_object({}) do |(line, line_number), comments|
+            next if line.start_with?(SHEBANG)
 
-          MSG_UNNECESSARY if encoding_omitable?(line)
+            comment = MagicComment.parse(line)
+            return comments unless comment.valid?
+
+            comments[line_number + 1] = comment
+          end
         end
 
-        def encoding_omitable?(line)
-          ENCODING_PATTERN.match?(line)
+        def offense?(comment)
+          comment.encoding_specified? && comment.encoding.casecmp('utf-8').zero?
         end
 
-        def encoding_line_number(processed_source)
-          line_number = 0
-          line_number += 1 if processed_source[line_number].start_with?(SHEBANG)
-          line_number
+        def register_offense(line_number, comment)
+          range = processed_source.buffer.line_range(line_number)
+
+          add_offense(range) do |corrector|
+            text = comment.without(:encoding)
+
+            if text.blank?
+              corrector.remove(range_with_surrounding_space(range: range, side: :right))
+            else
+              corrector.replace(range, text)
+            end
+          end
         end
       end
     end

data/lib/rubocop/cop/style/eval_with_location.rb

@@ -43,7 +43,7 @@ module RuboCop
       #   RUBY
       #
       # This cop works only when a string literal is given as a code string.
-      # No offence is reported if a string variable is given as below:
+      # No offense is reported if a string variable is given as below:
       #
       # @example
       #   # not checked