rubocop 1.9.1 → 1.22.3

data/lib/rubocop/cop/naming/inclusive_language.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Naming
+      # This cops recommends the use of inclusive language instead of problematic terms.
+      # The cop can check the following locations for offenses:
+      # - identifiers
+      # - constants
+      # - variables
+      # - strings
+      # - symbols
+      # - comments
+      # - file paths
+      # Each of these locations can be individually enabled/disabled via configuration,
+      # for example CheckIdentifiers = true/false.
+      #
+      # Flagged terms are configurable for the cop. For each flagged term an optional
+      # Regex can be specified to identify offenses. Suggestions for replacing a flagged term can
+      # be configured and will be displayed as part of the offense message.
+      # An AllowedRegex can be specified for a flagged term to exempt allowed uses of the term.
+      # `WholeWord: true` can be set on a flagged term to indicate the cop should only match when
+      # a term matches the whole word (partial matches will not be offenses).
+      #
+      # @example FlaggedTerms: { whitelist: { Suggestions: ['allowlist'] } }
+      #   # Suggest replacing identifier whitelist with allowlist
+      #
+      #   # bad
+      #   whitelist_users = %w(user1 user1)
+      #
+      #   # good
+      #   allowlist_users = %w(user1 user2)
+      #
+      # @example FlaggedTerms: { master: { Suggestions: ['main', 'primary', 'leader'] } }
+      #   # Suggest replacing master in an instance variable name with main, primary, or leader
+      #
+      #   # bad
+      #   @master_node = 'node1.example.com'
+      #
+      #   # good
+      #   @primary_node = 'node1.example.com'
+      #
+      # @example FlaggedTerms: { whitelist: { Regex: !ruby/regexp '/white[-_\s]?list' } }
+      #   # Identify problematic terms using a Regexp
+      #
+      #   # bad
+      #   white_list = %w(user1 user2)
+      #
+      #   # good
+      #   allow_list = %w(user1 user2)
+      #
+      # @example FlaggedTerms: { master: { AllowedRegex: 'master\'?s degree' } }
+      #   # Specify allowed uses of the flagged term as a string or regexp.
+      #
+      #   # bad
+      #   # They had a masters
+      #
+      #   # good
+      #   # They had a master's degree
+      #
+      # @example FlaggedTerms: { slave: { WholeWord: true } }
+      #   # Specify that only terms that are full matches will be flagged.
+      #
+      #   # bad
+      #   Slave
+      #
+      #   # good (won't be flagged despite containing `slave`)
+      #   TeslaVehicle
+      class InclusiveLanguage < Base
+        include RangeHelp
+
+        EMPTY_ARRAY = [].freeze
+        MSG = "Consider replacing '%<term>s'%<suffix>s."
+        MSG_FOR_FILE_PATH = "Consider replacing '%<term>s' in file path%<suffix>s."
+
+        WordLocation = Struct.new(:word, :position)
+
+        def initialize(config = nil, options = nil)
+          super
+          @flagged_term_hash = {}
+          @flagged_terms_regex = nil
+          @allowed_regex = nil
+          @check_token = preprocess_check_config
+          preprocess_flagged_terms
+        end
+
+        def on_new_investigation
+          investigate_filepath if cop_config['CheckFilepaths']
+          investigate_tokens
+        end
+
+        private
+
+        def investigate_tokens
+          processed_source.each_token do |token|
+            next unless check_token?(token.type)
+
+            word_locations = scan_for_words(token.text)
+            next if word_locations.empty?
+
+            add_offenses_for_token(token, word_locations)
+          end
+        end
+
+        def add_offenses_for_token(token, word_locations)
+          word_locations.each do |word_location|
+            start_position = token.pos.begin_pos + token.pos.source.index(word_location.word)
+            range = range_between(start_position, start_position + word_location.word.length)
+            add_offense(range, message: create_message(word_location.word))
+          end
+        end
+
+        def check_token?(type)
+          !!@check_token[type]
+        end
+
+        def preprocess_check_config # rubocop:disable Metrics/AbcSize
+          {
+            tIDENTIFIER: cop_config['CheckIdentifiers'],
+            tCONSTANT: cop_config['CheckConstants'],
+            tIVAR: cop_config['CheckVariables'],
+            tCVAR: cop_config['CheckVariables'],
+            tGVAR: cop_config['CheckVariables'],
+            tSYMBOL: cop_config['CheckSymbols'],
+            tSTRING: cop_config['CheckStrings'],
+            tSTRING_CONTENT: cop_config['CheckStrings'],
+            tCOMMENT: cop_config['CheckComments']
+          }.freeze
+        end
+
+        def preprocess_flagged_terms
+          allowed_strings = []
+          flagged_term_strings = []
+          cop_config['FlaggedTerms'].each do |term, term_definition|
+            next if term_definition.nil?
+
+            allowed_strings.concat(process_allowed_regex(term_definition['AllowedRegex']))
+            regex_string = ensure_regex_string(extract_regexp(term, term_definition))
+            flagged_term_strings << regex_string
+
+            add_to_flagged_term_hash(regex_string, term, term_definition)
+          end
+
+          set_regexes(flagged_term_strings, allowed_strings)
+        end
+
+        def extract_regexp(term, term_definition)
+          return term_definition['Regex'] if term_definition['Regex']
+          return /(?:\b|(?<=[\W_]))#{term}(?:\b|(?=[\W_]))/ if term_definition['WholeWord']
+
+          term
+        end
+
+        def add_to_flagged_term_hash(regex_string, term, term_definition)
+          @flagged_term_hash[Regexp.new(regex_string, Regexp::IGNORECASE)] =
+            term_definition.merge('Term' => term,
+                                  'SuggestionString' =>
+                                    preprocess_suggestions(term_definition['Suggestions']))
+        end
+
+        def set_regexes(flagged_term_strings, allowed_strings)
+          @flagged_terms_regex = array_to_ignorecase_regex(flagged_term_strings)
+          @allowed_regex = array_to_ignorecase_regex(allowed_strings) unless allowed_strings.empty?
+        end
+
+        def process_allowed_regex(allowed)
+          return EMPTY_ARRAY if allowed.nil?
+
+          Array(allowed).map do |allowed_term|
+            next if allowed_term.is_a?(String) && allowed_term.strip.empty?
+
+            ensure_regex_string(allowed_term)
+          end
+        end
+
+        def ensure_regex_string(regex)
+          regex.is_a?(Regexp) ? regex.source : regex
+        end
+
+        def array_to_ignorecase_regex(strings)
+          Regexp.new(strings.join('|'), Regexp::IGNORECASE)
+        end
+
+        def investigate_filepath
+          word_locations = scan_for_words(processed_source.file_path)
+
+          case word_locations.length
+          when 0
+            return
+          when 1
+            message = create_single_word_message_for_file(word_locations.first.word)
+          else
+            words = word_locations.map(&:word)
+            message = create_multiple_word_message_for_file(words)
+          end
+
+          range = source_range(processed_source.buffer, 1, 0)
+          add_offense(range, message: message)
+        end
+
+        def create_single_word_message_for_file(word)
+          create_message(word, MSG_FOR_FILE_PATH)
+        end
+
+        def create_multiple_word_message_for_file(words)
+          format(MSG_FOR_FILE_PATH, term: words.join("', '"), suffix: ' with other terms')
+        end
+
+        def scan_for_words(input)
+          mask_input(input).enum_for(:scan, @flagged_terms_regex).map do
+            match = Regexp.last_match
+            WordLocation.new(match.to_s, match.offset(0).first)
+          end
+        end
+
+        def mask_input(str)
+          return str if @allowed_regex.nil?
+
+          safe_str = if str.valid_encoding?
+                       str
+                     else
+                       str.encode('UTF-8', invalid: :replace, undef: :replace)
+                     end
+          safe_str.gsub(@allowed_regex) { |match| '*' * match.size }
+        end
+
+        def create_message(word, message = MSG)
+          flagged_term = find_flagged_term(word)
+          suggestions = flagged_term['SuggestionString']
+          suggestions = ' with another term' if suggestions.blank?
+
+          format(message, term: word, suffix: suggestions)
+        end
+
+        def find_flagged_term(word)
+          _regexp, flagged_term = @flagged_term_hash.find do |key, _term|
+            key.match?(word)
+          end
+          flagged_term
+        end
+
+        def preprocess_suggestions(suggestions)
+          return '' if suggestions.nil? ||
+                       (suggestions.is_a?(String) && suggestions.strip.empty?) || suggestions.empty?
+
+          format_suggestions(suggestions)
+        end
+
+        def format_suggestions(suggestions)
+          quoted_suggestions = Array(suggestions).map { |word| "'#{word}'" }
+          suggestion_str = case quoted_suggestions.size
+                           when 1
+                             quoted_suggestions.first
+                           when 2
+                             quoted_suggestions.join(' or ')
+                           else
+                             last_quoted = quoted_suggestions.pop
+                             quoted_suggestions << "or #{last_quoted}"
+                             quoted_suggestions.join(', ')
+                           end
+          " with #{suggestion_str}"
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/naming/memoized_instance_variable_name.rb

@@ -14,6 +14,11 @@ module RuboCop
       # convention that is used to implicitly indicate that an ivar should not
       # be set or referenced outside of the memoization method.
       #
+      # @safety
+      #   This cop relies on the pattern `@instance_var ||= ...`,
+      #   but this is sometimes used for other purposes than memoization
+      #   so this cop is considered unsafe.
+      #
       # @example EnforcedStyleForLeadingUnderscores: disallowed (default)
       #   # bad
       #   # Method foo is memoized using an instance variable that is
@@ -143,11 +148,12 @@ module RuboCop
         include ConfigurableEnforcedStyle
 
         MSG = 'Memoized variable `%<var>s` does not match ' \
-          'method name `%<method>s`. Use `@%<suggested_var>s` instead.'
+              'method name `%<method>s`. Use `@%<suggested_var>s` instead.'
         UNDERSCORE_REQUIRED = 'Memoized variable `%<var>s` does not start ' \
-          'with `_`. Use `@%<suggested_var>s` instead.'
+                              'with `_`. Use `@%<suggested_var>s` instead.'
         DYNAMIC_DEFINE_METHODS = %i[define_method define_singleton_method].to_set.freeze
 
+        # @!method method_definition?(node)
         def_node_matcher :method_definition?, <<~PATTERN
           ${
             (block (send _ %DYNAMIC_DEFINE_METHODS ({sym str} $_)) ...)
@@ -179,6 +185,7 @@ module RuboCop
         end
         # rubocop:enable Metrics/AbcSize
 
+        # @!method defined_memoized?(node, ivar)
         def_node_matcher :defined_memoized?, <<~PATTERN
           (begin
             (if (defined $(ivar %1)) (return $(ivar %1)) nil?)
@@ -241,8 +248,7 @@ module RuboCop
         def message(variable)
           variable_name = variable.to_s.sub('@', '')
 
-          return UNDERSCORE_REQUIRED if style == :required &&
-                                        !variable_name.start_with?('_')
+          return UNDERSCORE_REQUIRED if style == :required && !variable_name.start_with?('_')
 
           MSG
         end
@@ -254,7 +260,7 @@ module RuboCop
         end
 
         def variable_name_candidates(method_name)
-          no_underscore = method_name.sub(/\A_/, '')
+          no_underscore = method_name.delete_prefix('_')
           with_underscore = "_#{method_name}"
           case style
           when :required

data/lib/rubocop/cop/naming/method_name.rb

@@ -35,7 +35,10 @@ module RuboCop
 
         MSG = 'Use %<style>s for method names.'
 
+        # @!method sym_name(node)
         def_node_matcher :sym_name, '(sym $_name)'
+
+        # @!method str_name(node)
         def_node_matcher :str_name, '(str $_name)'
 
         def on_send(node)
@@ -50,8 +53,7 @@ module RuboCop
         end
 
         def on_def(node)
-          return if node.operator_method? ||
-                    matches_ignored_pattern?(node.method_name)
+          return if node.operator_method? || matches_ignored_pattern?(node.method_name)
 
           check_name(node, node.method_name, node.loc.name)
         end

data/lib/rubocop/cop/naming/predicate_name.rb

@@ -30,6 +30,7 @@ module RuboCop
       class PredicateName < Base
         include AllowedMethods
 
+        # @!method dynamic_method_define(node)
         def_node_matcher :dynamic_method_define, <<~PATTERN
           (send nil? #method_definition_macros
             (sym $_)
@@ -43,8 +44,7 @@ module RuboCop
 
               add_offense(
                 node.first_argument.loc.expression,
-                message: message(method_name,
-                                 expected_name(method_name.to_s, prefix))
+                message: message(method_name, expected_name(method_name.to_s, prefix))
               )
             end
           end

data/lib/rubocop/cop/naming/rescued_exceptions_variable_name.rb

@@ -9,6 +9,11 @@ module RuboCop
       # The `PreferredName` config option takes a `String`. It represents
       # the required name of the variable. Its default is `e`.
       #
+      # NOTE: This cop does not consider nested rescues because it cannot
+      # guarantee that the variable from the outer rescue is not used within
+      # the inner rescue (in which case, changing the inner variable would
+      # shadow the outer variable).
+      #
       # @example PreferredName: e (default)
       #   # bad
       #   begin
@@ -62,9 +67,17 @@ module RuboCop
           offending_name = variable_name(node)
           return unless offending_name
 
+          # Handle nested rescues by only requiring the outer one to use the
+          # configured variable name, so that nested rescues don't use the same
+          # variable.
+          return if node.each_ancestor(:resbody).any?
+
           preferred_name = preferred_name(offending_name)
           return if preferred_name.to_sym == offending_name
 
+          # check variable shadowing for exception variable
+          return if shadowed_variable_name?(node)
+
           range = offense_range(node)
           message = message(node)
 
@@ -140,6 +153,10 @@ module RuboCop
           preferred_name = preferred_name(offending_name)
           format(MSG, preferred: preferred_name, bad: offending_name)
         end
+
+        def shadowed_variable_name?(node)
+          node.each_descendant(:lvar).any? { |n| n.children.first.to_s == preferred_name(n) }
+        end
       end
     end
   end

data/lib/rubocop/cop/offense.rb

@@ -7,8 +7,7 @@ module RuboCop
       include Comparable
 
       # @api private
-      COMPARISON_ATTRIBUTES = %i[line column cop_name
-                                 message severity].freeze
+      COMPARISON_ATTRIBUTES = %i[line column cop_name message severity].freeze
 
       # @api public
       #
@@ -141,9 +140,7 @@ module RuboCop
       # @return [Parser::Source::Range]
       #   the range of the code that is highlighted
       def highlighted_area
-        Parser::Source::Range.new(source_line,
-                                  column,
-                                  column + column_length)
+        Parser::Source::Range.new(source_line, column, column + column_length)
       end
 
       # @api private
@@ -220,9 +217,7 @@ module RuboCop
       alias eql? ==
 
       def hash
-        COMPARISON_ATTRIBUTES.reduce(0) do |hash, attribute|
-          hash ^ public_send(attribute).hash
-        end
+        COMPARISON_ATTRIBUTES.reduce(0) { |hash, attribute| hash ^ public_send(attribute).hash }
       end
 
       # @api public

data/lib/rubocop/cop/registry.rb

@@ -10,12 +10,7 @@ module RuboCop
 
       def initialize(name, origin, badges)
         super(
-          format(
-            MSG,
-            name: name,
-            origin: origin,
-            options: badges.to_a.join(' or ')
-          )
+          format(MSG, name: name, origin: origin, options: badges.to_a.join(' or '))
         )
       end
     end
@@ -64,6 +59,11 @@ module RuboCop
         with(without_department.values.flatten)
       end
 
+      # @return [Boolean] Checks if given name is department
+      def department?(name)
+        departments.include? name.to_sym
+      end
+
       def contains_cop_matching?(names)
         cops.any? { |cop| cop.match?(names) }
       end
@@ -150,16 +150,13 @@ module RuboCop
       end
 
       def enabled(config, only = [], only_safe: false)
-        select do |cop|
-          only.include?(cop.cop_name) || enabled?(cop, config, only_safe)
-        end
+        select { |cop| only.include?(cop.cop_name) || enabled?(cop, config, only_safe) }
       end
 
       def enabled?(cop, config, only_safe)
         cfg = config.for_cop(cop)
 
-        cop_enabled = cfg.fetch('Enabled') == true ||
-                      enabled_pending_cop?(cfg, config)
+        cop_enabled = cfg.fetch('Enabled') == true || enabled_pending_cop?(cfg, config)
 
         if only_safe
           cop_enabled && cfg.fetch('Safe', true)
@@ -179,13 +176,17 @@ module RuboCop
         cops.map(&:cop_name)
       end
 
+      def names_for_department(department)
+        cops.select { |cop| cop.department == department.to_sym }.map(&:cop_name)
+      end
+
       def ==(other)
         cops == other.cops
       end
 
       def sort!
         clear_enrollment_queue
-        @registry = Hash[@registry.sort_by { |badge, _| badge.cop_name }]
+        @registry = @registry.sort_by { |badge, _| badge.cop_name }.to_h
 
         self
       end

data/lib/rubocop/cop/security/eval.rb

@@ -15,6 +15,7 @@ module RuboCop
         MSG = 'The use of `eval` is a serious security risk.'
         RESTRICT_ON_SEND = %i[eval].freeze
 
+        # @!method eval?(node)
         def_node_matcher :eval?, <<~PATTERN
           (send {nil? (send nil? :binding)} :eval $!str ...)
         PATTERN

data/lib/rubocop/cop/security/io_methods.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Security
+      # Checks for the first argument to `IO.read`, `IO.binread`, `IO.write`, `IO.binwrite`,
+      # `IO.foreach`, and `IO.readlines`.
+      #
+      # If argument starts with a pipe character (`'|'`) and the receiver is the `IO` class,
+      # a subprocess is created in the same way as `Kernel#open`, and its output is returned.
+      # `Kernel#open` may allow unintentional command injection, which is the reason these
+      # `IO` methods are a security risk.
+      # Consider to use `File.read` to disable the behavior of subprocess invocation.
+      #
+      # @safety
+      #   This cop is unsafe because false positive will occur if the variable passed as
+      #   the first argument is a command that is not a file path.
+      #
+      # @example
+      #
+      #   # bad
+      #   IO.read(path)
+      #   IO.read('path')
+      #
+      #   # good
+      #   File.read(path)
+      #   File.read('path')
+      #   IO.read('| command') # Allow intentional command invocation.
+      #
+      class IoMethods < Base
+        extend AutoCorrector
+
+        MSG = '`File.%<method_name>s` is safer than `IO.%<method_name>s`.'
+        RESTRICT_ON_SEND = %i[read binread write binwrite foreach readlines].freeze
+
+        def on_send(node)
+          return unless (receiver = node.receiver) && receiver.source == 'IO'
+
+          argument = node.first_argument
+          return if argument.respond_to?(:value) && argument.value.strip.start_with?('|')
+
+          add_offense(node, message: format(MSG, method_name: node.method_name)) do |corrector|
+            corrector.replace(receiver, 'File')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/security/json_load.rb

@@ -6,13 +6,14 @@ module RuboCop
       # This cop checks for the use of JSON class methods which have potential
       # security issues.
       #
-      # Autocorrect is disabled by default because it's potentially dangerous.
-      # If using a stream, like `JSON.load(open('file'))`, it will need to call
-      # `#read` manually, like `JSON.parse(open('file').read)`.
-      # If reading single values (rather than proper JSON objects), like
-      # `JSON.load('false')`, it will need to pass the `quirks_mode: true`
-      # option, like `JSON.parse('false', quirks_mode: true)`.
-      # Other similar issues may apply.
+      # @safety
+      #   This cop's autocorrection is unsafe because it's potentially dangerous.
+      #   If using a stream, like `JSON.load(open('file'))`, it will need to call
+      #   `#read` manually, like `JSON.parse(open('file').read)`.
+      #   If reading single values (rather than proper JSON objects), like
+      #   `JSON.load('false')`, it will need to pass the `quirks_mode: true`
+      #   option, like `JSON.parse('false', quirks_mode: true)`.
+      #   Other similar issues may apply.
       #
       # @example
       #   # bad
@@ -28,6 +29,7 @@ module RuboCop
         MSG = 'Prefer `JSON.parse` over `JSON.%<method>s`.'
         RESTRICT_ON_SEND = %i[load restore].freeze
 
+        # @!method json_load(node)
         def_node_matcher :json_load, <<~PATTERN
           (send (const {nil? cbase} :JSON) ${:load :restore} ...)
         PATTERN

data/lib/rubocop/cop/security/marshal_load.rb

@@ -22,6 +22,7 @@ module RuboCop
         MSG = 'Avoid using `Marshal.%<method>s`.'
         RESTRICT_ON_SEND = %i[load restore].freeze
 
+        # @!method marshal_load(node)
         def_node_matcher :marshal_load, <<~PATTERN
           (send (const {nil? cbase} :Marshal) ${:load :restore}
           !(send (const {nil? cbase} :Marshal) :dump ...))

data/lib/rubocop/cop/security/open.rb

@@ -11,6 +11,10 @@ module RuboCop
       # the argument of `Kernel#open` and `URI.open`. It would be better to use
       # `File.open`, `IO.popen` or `URI.parse#open` explicitly.
       #
+      # @safety
+      #   This cop could register false positives if `open` is redefined
+      #   in a class and then used without a receiver in that class.
+      #
       # @example
       #   # bad
       #   open(something)
@@ -24,6 +28,7 @@ module RuboCop
         MSG = 'The use of `%<receiver>sopen` is a serious security risk.'
         RESTRICT_ON_SEND = %i[open].freeze
 
+        # @!method open?(node)
         def_node_matcher :open?, <<~PATTERN
           (send ${nil? (const {nil? cbase} :URI)} :open $!str ...)
         PATTERN

data/lib/rubocop/cop/security/yaml_load.rb

@@ -7,6 +7,10 @@ module RuboCop
       # potential security issues leading to remote code execution when
       # loading from an untrusted source.
       #
+      # @safety
+      #   The behaviour of the code might change depending on what was
+      #   in the YAML payload, since `YAML.safe_load` is more restrictive.
+      #
       # @example
       #   # bad
       #   YAML.load("--- foo")
@@ -21,6 +25,7 @@ module RuboCop
         MSG = 'Prefer using `YAML.safe_load` over `YAML.load`.'
         RESTRICT_ON_SEND = %i[load].freeze
 
+        # @!method yaml_load(node)
         def_node_matcher :yaml_load, <<~PATTERN
           (send (const {nil? cbase} :YAML) :load ...)
         PATTERN

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

@@ -47,7 +47,7 @@ module RuboCop
       #
       #   end
       #
-      # @example AllowModifiersOnSymbols: true
+      # @example AllowModifiersOnSymbols: true (default)
       #   # good
       #   class Foo
       #
@@ -77,8 +77,9 @@ module RuboCop
 
         RESTRICT_ON_SEND = %i[private protected public module_function].freeze
 
+        # @!method access_modifier_with_symbol?(node)
         def_node_matcher :access_modifier_with_symbol?, <<~PATTERN
-          (send nil? {:private :protected :public} (sym _))
+          (send nil? {:private :protected :public :module_function} (sym _))
         PATTERN
 
         def on_send(node)
@@ -87,9 +88,7 @@ module RuboCop
           return if allow_modifiers_on_symbols?(node)
 
           if offense?(node)
-            add_offense(node.loc.selector) do
-              opposite_style_detected
-            end
+            add_offense(node.loc.selector) { opposite_style_detected }
           else
             correct_style_detected
           end