rubocop 1.53.0 → 1.90.0

data/lib/rubocop/cop/variable_force/variable.rb

@@ -29,14 +29,25 @@ module RuboCop
         end
 
         def assign(node)
-          @assignments << Assignment.new(node, self)
+          assignment = Assignment.new(node, self)
+
+          mark_last_as_reassigned!(assignment)
+
+          @assignments << assignment
+        end
+
+        def mark_last_as_reassigned!(assignment)
+          return if captured_by_block?
+          return unless assignment.branch == @assignments.last&.branch
+
+          @assignments.last&.reassigned!
         end
 
         def referenced?
           !@references.empty?
         end
 
-        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def reference!(node)
           reference = Reference.new(node, @scope)
           @references << reference
@@ -52,7 +63,7 @@ module RuboCop
             # if/unless keyword. A preceding assignment is needed to put the
             # variable in scope. For this reason we skip to the next assignment
             # here.
-            next if in_modifier_conditional?(assignment)
+            next if in_modifier_conditional?(assignment, node)
 
             break if !assignment.branch || assignment.branch == reference.branch
 
@@ -61,14 +72,25 @@ module RuboCop
             end
           end
         end
-        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
-        def in_modifier_conditional?(assignment)
-          parent = assignment.node.parent
-          parent = parent.parent if parent&.begin_type?
-          return false if parent.nil?
+        def in_modifier_conditional?(assignment, reference_node)
+          conditional = modifier_conditional_of(assignment.node)
+          return false unless conditional
+
+          # The out-of-scope problem only affects a reference in the modifier body (to the
+          # left of the keyword); a reference after the modifier is put in scope by the
+          # condition's assignment, so an earlier assignment there is genuinely useless.
+          covers?(conditional, reference_node) && !covers?(conditional.condition, reference_node)
+        end
+
+        def modifier_conditional_of(node)
+          node.each_ancestor(:if, :while, :until).find do |conditional|
+            conditional.modifier_form? && covers?(conditional.condition, node)
+          end
+        end
 
-          (parent.if_type? || parent.while_type? || parent.until_type?) && parent.modifier_form?
+        def covers?(container, node)
+          container.equal?(node) || container.source_range.contains?(node.source_range)
         end
 
         def capture_with_block!
@@ -96,7 +118,7 @@ module RuboCop
         end
 
         def method_argument?
-          argument? && %i[def defs].include?(@scope.node.type)
+          argument? && @scope.node.any_def_type?
         end
 
         def block_argument?

data/lib/rubocop/cop/variable_force/variable_table.rb

@@ -61,8 +61,8 @@ module RuboCop
                   "at #{node.source_range}, #{node.inspect}"
           end
 
-          variable.assign(node)
           mark_variable_as_captured_by_block_if_so(variable)
+          variable.assign(node)
         end
 
         def reference_variable(name, node)
@@ -87,8 +87,8 @@ module RuboCop
           # So just skip.
           return unless variable
 
-          variable.reference!(node)
           mark_variable_as_captured_by_block_if_so(variable)
+          variable.reference!(node)
         end
 
         def find_variable(name)
@@ -100,7 +100,7 @@ module RuboCop
 
             # Only block scope allows referencing outer scope variables.
             node = scope.node
-            return nil unless node.block_type? || node.numblock_type?
+            return nil unless node.any_block_type?
           end
 
           nil
@@ -113,14 +113,14 @@ module RuboCop
         def accessible_variables
           scope_stack.reverse_each.with_object([]) do |scope, variables|
             variables.concat(scope.variables.values)
-            break variables unless scope.node.block_type? || scope.node.numblock_type?
+            break variables unless scope.node.any_block_type?
           end
         end
 
         private
 
         def mark_variable_as_captured_by_block_if_so(variable)
-          return unless current_scope.node.block_type? || current_scope.node.numblock_type?
+          return unless current_scope.node.any_block_type?
           return if variable.scope == current_scope
 
           variable.capture_with_block!

data/lib/rubocop/cop/variable_force.rb

@@ -27,7 +27,10 @@ module RuboCop
     class VariableForce < Force # rubocop:disable Metrics/ClassLength
       VARIABLE_ASSIGNMENT_TYPE = :lvasgn
       REGEXP_NAMED_CAPTURE_TYPE = :match_with_lvasgn
-      VARIABLE_ASSIGNMENT_TYPES = [VARIABLE_ASSIGNMENT_TYPE, REGEXP_NAMED_CAPTURE_TYPE].freeze
+      PATTERN_MATCH_VARIABLE_TYPE = :match_var
+      VARIABLE_ASSIGNMENT_TYPES = [
+        VARIABLE_ASSIGNMENT_TYPE, REGEXP_NAMED_CAPTURE_TYPE, PATTERN_MATCH_VARIABLE_TYPE
+      ].freeze
 
       ARGUMENT_DECLARATION_TYPES = [
         :arg, :optarg, :restarg,
@@ -51,7 +54,7 @@ module RuboCop
 
       ZERO_ARITY_SUPER_TYPE = :zsuper
 
-      TWISTED_SCOPE_TYPES = %i[block numblock class sclass defs module].freeze
+      TWISTED_SCOPE_TYPES = %i[block numblock itblock class sclass defs module].freeze
       SCOPE_TYPES = (TWISTED_SCOPE_TYPES + [:def]).freeze
 
       SEND_TYPE = :send
@@ -68,6 +71,8 @@ module RuboCop
         end
       end
 
+      BRANCH_NODES = %i[if case case_match rescue].freeze
+
       def variable_table
         @variable_table ||= VariableTable.new(self)
       end
@@ -112,6 +117,7 @@ module RuboCop
       NODE_HANDLER_METHOD_NAMES = [
         [VARIABLE_ASSIGNMENT_TYPE, :process_variable_assignment],
         [REGEXP_NAMED_CAPTURE_TYPE, :process_regexp_named_captures],
+        [PATTERN_MATCH_VARIABLE_TYPE, :process_pattern_match_variable],
         [MULTIPLE_ASSIGNMENT_TYPE, :process_variable_multiple_assignment],
         [VARIABLE_REFERENCE_TYPE, :process_variable_referencing],
         [RESCUE_TYPE, :process_rescue],
@@ -175,6 +181,14 @@ module RuboCop
         skip_children!
       end
 
+      def process_pattern_match_variable(node)
+        name = node.children.first
+
+        variable_table.declare_variable(name, node) unless variable_table.variable_exist?(name)
+
+        skip_children!
+      end
+
       def regexp_captured_names(node)
         regexp = node.to_regexp
 
@@ -182,15 +196,10 @@ module RuboCop
       end
 
       def process_variable_operator_assignment(node)
-        if LOGICAL_OPERATOR_ASSIGNMENT_TYPES.include?(node.type)
-          asgn_node, rhs_node = *node
-        else
-          asgn_node, _operator, rhs_node = *node
-        end
-
+        asgn_node = node.lhs
         return unless asgn_node.lvasgn_type?
 
-        name = asgn_node.children.first
+        name = asgn_node.name
 
         variable_table.declare_variable(name, asgn_node) unless variable_table.variable_exist?(name)
 
@@ -210,7 +219,7 @@ module RuboCop
         # before processing rhs nodes.
 
         variable_table.reference_variable(name, node)
-        process_node(rhs_node)
+        process_node(node.rhs)
         variable_table.assign_to_variable(name, asgn_node)
 
         skip_children!
@@ -229,11 +238,16 @@ module RuboCop
       end
 
       def process_loop(node)
-        if POST_CONDITION_LOOP_TYPES.include?(node.type)
+        if node.post_condition_loop?
           # See the comment at the end of file for this behavior.
           condition_node, body_node = *node
           process_node(body_node)
           process_node(condition_node)
+        elsif node.for_type?
+          # In `for item in items` the rightmost expression is evaluated first.
+          process_node(node.collection)
+          process_node(node.variable)
+          process_node(node.body) if node.body
         else
           process_children(node)
         end
@@ -289,7 +303,7 @@ module RuboCop
         variable_table.accessible_variables.each { |variable| variable.reference!(node) }
       end
 
-      # Mark all assignments which are referenced in the same loop
+      # Mark last assignments which are referenced in the same loop
       # as referenced by ignoring AST order since they would be referenced
       # in next iteration.
       def mark_assignments_as_referenced_in_loop(node)
@@ -301,13 +315,12 @@ module RuboCop
           # would be skipped here.
           next unless variable
 
-          variable.assignments.each do |assignment|
-            next if assignment_nodes_in_loop.none? do |assignment_node|
-                      assignment_node.equal?(assignment.node)
-                    end
-
-            assignment.reference!(node)
+          loop_assignments = variable.assignments.select do |assignment|
+            assignment_nodes_in_loop.include?(assignment.node)
           end
+          next unless loop_assignments.any?
+
+          reference_assignments(loop_assignments, node)
         end
       end
 
@@ -343,9 +356,19 @@ module RuboCop
         when :lvasgn
           AssignmentReference.new(node)
         when *OPERATOR_ASSIGNMENT_TYPES
-          asgn_node = node.children.first
-          VariableReference.new(asgn_node.children.first) if asgn_node.lvasgn_type?
+          VariableReference.new(node.lhs.name) if node.lhs.lvasgn_type?
+        end
+      end
+
+      def reference_assignments(loop_assignments, loop_node)
+        # If inside a branching statement, mark all as referenced.
+        # Otherwise, mark only the last assignment as referenced.
+        # Note that `rescue` must be considered as branching because of
+        # the `retry` keyword.
+        loop_assignments.each do |assignment|
+          assignment.reference!(loop_node) if assignment.node.each_ancestor(*BRANCH_NODES).any?
         end
+        loop_assignments.last&.reference!(loop_node)
       end
 
       def scanned_node?(node)

data/lib/rubocop/cops_documentation_generator.rb

@@ -1,23 +1,61 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'yard'
 
 # Class for generating documentation of all cops departments
 # @api private
 class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
-  include ::RuboCop::Cop::Documentation
+  include RuboCop::Cop::Documentation
+
+  CopData = Struct.new(
+    :cop, :description, :example_objects, :safety_objects, :see_objects, :config, keyword_init: true
+  )
+
+  STRUCTURE = {
+    name:                  ->(data) { cop_header(data.cop) },
+    required_ruby_version: ->(data) { required_ruby_version(data.cop) },
+    properties:            ->(data) { properties(data.cop) },
+    description:           ->(data) { "#{data.description}\n" },
+    safety:                ->(data) { safety_object(data.safety_objects, data.cop) },
+    examples:              ->(data) { examples(data.example_objects, data.cop) },
+    configuration:         ->(data) { configurations(data.cop.department, data.cop, data.config) },
+    references:            ->(data) { references(data.cop, data.see_objects) }
+  }.freeze
+
   # This class will only generate documentation for cops that belong to one of
   # the departments given in the `departments` array. E.g. if we only wanted
   # documentation for Lint cops:
   #
   #   CopsDocumentationGenerator.new(departments: ['Lint']).call
   #
-  def initialize(departments: [])
+  # For plugin extensions, specify `:plugin_name` keyword as follows:
+  #
+  #   CopsDocumentationGenerator.new(
+  #     departments: ['Performance'], plugin_name: 'rubocop-performance'
+  #   ).call
+  #
+  # You can append additional information:
+  #
+  #   callback = ->(data) { required_rails_version(data.cop) }
+  #   CopsDocumentationGenerator.new(extra_info: { ruby_version: callback }).call
+  #
+  # This will insert the string returned from the lambda _after_ the section from RuboCop itself.
+  # See `CopsDocumentationGenerator::STRUCTURE` for available sections.
+  #
+  def initialize(departments: [], extra_info: {}, base_dir: Dir.pwd, plugin_name: nil)
     @departments = departments.map(&:to_sym).sort!
+    @extra_info = extra_info
     @cops = RuboCop::Cop::Registry.global
     @config = RuboCop::ConfigLoader.default_configuration
-    @docs_path = "#{Dir.pwd}/docs/modules/ROOT/pages/"
-    FileUtils.mkdir_p(@docs_path)
+    # NOTE: For example, this prevents excessive plugin loading before another task executes,
+    # in cases where plugins are already loaded by `internal_investigation`.
+    if plugin_name && @config.loaded_plugins.none? { |plugin| plugin.about.name == plugin_name }
+      RuboCop::Plugin.integrate_plugins(RuboCop::Config.new, [plugin_name])
+    end
+    @base_dir = base_dir
+    @docs_path = "#{base_dir}/docs/modules/ROOT"
+    FileUtils.mkdir_p("#{@docs_path}/pages")
   end
 
   def call
@@ -37,24 +75,21 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
     cops.with_department(department).sort!
   end
 
-  def cops_body(cop, description, examples_objects, safety_objects, see_objects, pars) # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
-    check_examples_to_have_the_default_enforced_style!(examples_objects, cop)
-
-    content = h2(cop.cop_name)
-    content << required_ruby_version(cop)
-    content << properties(cop)
-    content << "#{description}\n"
-    content << safety_object(safety_objects) if safety_objects.any? { |s| !s.text.blank? }
-    content << examples(examples_objects) if examples_objects.any?
-    content << configurations(cop.department, pars)
-    content << references(cop, see_objects)
+  def cops_body(data)
+    check_examples_to_have_the_default_enforced_style!(data.example_objects, data.cop)
+
+    content = +''
+    STRUCTURE.each do |section, block|
+      content << instance_exec(data, &block)
+      content << @extra_info[section].call(data) if @extra_info[section]
+    end
     content
   end
 
-  def check_examples_to_have_the_default_enforced_style!(examples_object, cop)
-    return if examples_object.none?
+  def check_examples_to_have_the_default_enforced_style!(example_objects, cop)
+    return if example_objects.none?
 
-    examples_describing_enforced_style = examples_object.map(&:name).grep(/EnforcedStyle:/)
+    examples_describing_enforced_style = example_objects.map(&:name).grep(/EnforcedStyle:/)
     return if examples_describing_enforced_style.none?
 
     if examples_describing_enforced_style.index { |name| name.match?('default') }.nonzero?
@@ -66,16 +101,20 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
     raise "Specify the default EnforcedStyle for #{cop.cop_name}"
   end
 
-  def examples(examples_object)
-    examples_object.each_with_object(h3('Examples').dup) do |example, content|
+  def examples(example_objects, cop)
+    return '' if example_objects.none?
+
+    example_objects.each_with_object(cop_subsection('Examples', cop).dup) do |example, content|
       content << "\n" unless content.end_with?("\n\n")
-      content << h4(example.name) unless example.name == ''
+      content << example_header(example.name, cop) unless example.name == ''
       content << code_example(example)
     end
   end
 
-  def safety_object(safety_object_objects)
-    safety_object_objects.each_with_object(h3('Safety').dup) do |safety_object, content|
+  def safety_object(safety_objects, cop)
+    return '' if safety_objects.all? { |s| s.text.blank? }
+
+    safety_objects.each_with_object(cop_subsection('Safety', cop).dup) do |safety_object, content|
       next if safety_object.text.blank?
 
       content << "\n" unless content.end_with?("\n\n")
@@ -87,17 +126,27 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
   def required_ruby_version(cop)
     return '' unless cop.respond_to?(:required_minimum_ruby_version)
 
-    "NOTE: Required Ruby version: #{cop.required_minimum_ruby_version}\n\n"
+    if cop.required_minimum_ruby_version
+      requirement = cop.required_minimum_ruby_version
+    elsif cop.required_maximum_ruby_version
+      requirement = "<= #{cop.required_maximum_ruby_version}"
+    else
+      return ''
+    end
+
+    "NOTE: Requires Ruby version #{requirement}\n\n"
   end
 
-  # rubocop:disable Metrics/MethodLength
+  # rubocop:disable-next Metrics/MethodLength
   def properties(cop)
     header = [
       'Enabled by default', 'Safe', 'Supports autocorrection', 'Version Added',
       'Version Changed'
     ]
     autocorrect = if cop.support_autocorrect?
-                    "Yes#{' (Unsafe)' unless cop.new(config).safe_autocorrect?}"
+                    context = cop.new.always_autocorrect? ? 'Always' : 'Command-line only'
+
+                    "#{context}#{' (Unsafe)' unless cop.new(config).safe_autocorrect?}"
                   else
                     'No'
                   end
@@ -111,24 +160,26 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
     ]]
     "#{to_table(header, content)}\n"
   end
-  # rubocop:enable Metrics/MethodLength
 
-  def h2(title)
+  def cop_header(cop)
     content = +"\n"
-    content << "== #{title}\n"
+    content << "[##{to_anchor(cop.cop_name)}]\n"
+    content << "== #{cop.cop_name}\n"
     content << "\n"
     content
   end
 
-  def h3(title)
+  def cop_subsection(title, cop)
     content = +"\n"
+    content << "[##{to_anchor(title)}-#{to_anchor(cop.cop_name)}]\n"
     content << "=== #{title}\n"
     content << "\n"
     content
   end
 
-  def h4(title)
-    content = +"==== #{title}\n"
+  def example_header(title, cop)
+    content = +"[##{to_anchor(title)}-#{to_anchor(cop.cop_name)}]\n"
+    content << "==== #{title}\n"
     content << "\n"
     content
   end
@@ -140,22 +191,22 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
     content
   end
 
-  def configurations(department, pars)
-    return '' if pars.empty?
-
+  def configurations(department, cop, cop_config)
     header = ['Name', 'Default value', 'Configurable values']
-    configs = pars
-              .each_key
-              .reject { |key| key.start_with?('Supported') }
-              .reject { |key| key.start_with?('AllowMultipleStyles') }
+    configs = cop_config.each_key.reject do |key|
+      key == 'AllowMultipleStyles' ||
+        (key != 'SupportedTypes' && key.start_with?('Supported'))
+    end
+    return '' if configs.empty?
+
     content = configs.map do |name|
-      configurable = configurable_values(pars, name)
-      default = format_table_value(pars[name])
+      configurable = configurable_values(cop_config, name)
+      default = format_table_value(cop_config[name])
 
       [configuration_name(department, name), default, configurable]
     end
 
-    h3('Configurable attributes') + to_table(header, content)
+    cop_subsection('Configurable attributes', cop) + to_table(header, content)
   end
 
   def configuration_name(department, name)
@@ -165,18 +216,18 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
     "xref:#{filename}#allowmultilinefinalelement[AllowMultilineFinalElement]"
   end
 
-  # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
-  def configurable_values(pars, name)
+  # rubocop:disable-next Metrics/CyclomaticComplexity,Metrics/MethodLength
+  def configurable_values(cop_config, name)
     case name
     when /^Enforced/
       supported_style_name = RuboCop::Cop::Util.to_supported_styles(name)
-      format_table_value(pars[supported_style_name])
+      format_table_value(cop_config[supported_style_name])
     when 'IndentationWidth'
       'Integer'
     when 'Database'
-      format_table_value(pars['SupportedDatabases'])
+      format_table_value(cop_config['SupportedDatabases'])
     else
-      case pars[name]
+      case cop_config[name]
       when String
         'String'
       when Integer
@@ -192,7 +243,6 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
       end
     end
   end
-  # rubocop:enable Metrics/CyclomaticComplexity,Metrics/MethodLength
 
   def to_table(header, content)
     table = ['|===', "| #{header.join(' | ')}\n\n"].join("\n")
@@ -216,7 +266,7 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
       else
         wrap_backtick(val.nil? ? '<none>' : val)
       end
-    value.gsub("#{Dir.pwd}/", '').rstrip
+    value.gsub("#{@base_dir}/", '').rstrip
   end
 
   def wrap_backtick(value)
@@ -233,7 +283,7 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
     urls = RuboCop::Cop::MessageAnnotator.new(config, cop.name, cop_config, {}).urls
     return '' if urls.empty? && see_objects.empty?
 
-    content = h3('References')
+    content = cop_subsection('References', cop)
     content << urls.map { |url| "* #{url}" }.join("\n")
     content << "\n" unless urls.empty?
     content << see_objects.map { |see| "* #{see.name}" }.join("\n")
@@ -245,18 +295,27 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
     return '' unless department == :Layout
 
     filename = "#{department_to_basename(department)}_footer.adoc"
-    file = "#{Dir.pwd}/docs/modules/ROOT/partials/#{filename}"
+    file = "#{docs_path}/partials/#{filename}"
     return '' unless File.exist?(file)
 
     "\ninclude::../partials/#{filename}[]\n"
   end
 
+  # rubocop:disable-next Metrics/MethodLength
   def print_cops_of_department(department)
     selected_cops = cops_of_department(department)
-    content = +"= #{department}\n"
+    content = +<<~HEADER
+      ////
+        Do NOT edit this file by hand directly, as it is automatically generated.
+
+        Please make any necessary changes to the cop documentation within the source files themselves.
+      ////
+
+      = #{department}
+    HEADER
     selected_cops.each { |cop| content << print_cop_with_doc(cop) }
     content << footer_for_department(department)
-    file_name = "#{docs_path}/#{department_to_basename(department)}.adoc"
+    file_name = "#{docs_path}/pages/#{department_to_basename(department)}.adoc"
     File.open(file_name, 'w') do |file|
       puts "* generated #{file_name}"
       file.write("#{content.strip}\n")
@@ -266,19 +325,25 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
   def print_cop_with_doc(cop) # rubocop:todo Metrics/AbcSize, Metrics/MethodLength
     cop_config = config.for_cop(cop)
     non_display_keys = %w[
-      Description Enabled StyleGuide Reference Safe SafeAutoCorrect VersionAdded
-      VersionChanged
+      Enabled
+      Description
+      StyleGuide
+      Reference References
+      Safe SafeAutoCorrect AutoCorrect
+      VersionAdded VersionChanged
     ]
-    pars = cop_config.reject { |k| non_display_keys.include? k }
+    parameters = cop_config.reject { |k| non_display_keys.include? k }
     description = 'No documentation'
-    examples_object = safety_object = see_object = []
+    example_objects = safety_objects = see_objects = []
     cop_code(cop) do |code_object|
       description = code_object.docstring unless code_object.docstring.blank?
-      examples_object = code_object.tags('example')
-      safety_object = code_object.tags('safety')
-      see_object = code_object.tags('see')
+      example_objects = code_object.tags('example')
+      safety_objects = code_object.tags('safety')
+      see_objects = code_object.tags('see')
     end
-    cops_body(cop, description, examples_object, safety_object, see_object, pars)
+    data = CopData.new(cop: cop, description: description, example_objects: example_objects,
+                       safety_objects: safety_objects, see_objects: see_objects, config: parameters)
+    cops_body(data)
   end
 
   def cop_code(cop)
@@ -294,7 +359,7 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
     filename = "#{department_to_basename(department)}.adoc"
     content = +"=== Department xref:#{filename}[#{type_title}]\n\n"
     cops_of_department(department).each do |cop|
-      anchor = cop.cop_name.sub('/', '').downcase
+      anchor = to_anchor(cop.cop_name)
       content << "* xref:#{filename}##{anchor}[#{cop.cop_name}]\n"
     end
 
@@ -302,7 +367,7 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
   end
 
   def print_table_of_contents
-    path = "#{docs_path}/cops.adoc"
+    path = "#{docs_path}/pages/cops.adoc"
 
     File.write(path, table_contents) and return unless File.exist?(path)
 
@@ -326,4 +391,13 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
 
     status == 'pending' ? 'Pending' : 'Enabled'
   end
+
+  # HTML anchor are somewhat limited in what characters they can contain, just
+  # accept a known-good subset. As long as it's consistent it doesn't matter.
+  #
+  # Style/AccessModifierDeclarations => styleaccessmodifierdeclarations
+  # OnlyFor: [] (default) => onlyfor_-__-_default_
+  def to_anchor(title)
+    title.delete('/').tr(' ', '-').gsub(/[^a-zA-Z0-9-]/, '_').downcase
+  end
 end

data/lib/rubocop/core_ext/string.rb

@@ -9,12 +9,8 @@ class String
     # @return [Boolean] true is the string is blank, false otherwise
     #
     # @example
-    #   ''.blank? #=> true
-    #
-    # @example
-    #   '    '.blank? #=> true
-    #
-    # @example
+    #   ''.blank?       #=> true
+    #   '    '.blank?   #=> true
     #   '  test'.blank? #=> false
     def blank?
       empty? || lstrip.empty?