rubocop-grantbirki 1.75.2

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# rubocop:disable Lint/RedundantCopDisableDirective
+
+module RuboCop
+  module Cop
+    module Style
+      # Detects comments to enable/disable RuboCop.
+      # This is useful if want to make sure that every RuboCop error gets fixed
+      # and not quickly disabled with a comment.
+      #
+      # Specific cops can be allowed with the `AllowedCops` configuration. Note that
+      # if this configuration is set, `rubocop:disable all` is still disallowed.
+      #
+      # @example
+      #   # bad
+      #   # rubocop:disable Metrics/AbcSize
+      #   def foo
+      #   end
+      #   # rubocop:enable Metrics/AbcSize
+      #
+      #   # good
+      #   def foo
+      #   end
+      #
+      # @example AllowedCops: [Metrics/AbcSize]
+      #   # good
+      #   # rubocop:disable Metrics/AbcSize
+      #   def foo
+      #   end
+      #   # rubocop:enable Metrics/AbcSize
+      #
+      class DisableCopsWithinSourceCodeDirective < Base
+        extend AutoCorrector
+
+        # rubocop:enable Lint/RedundantCopDisableDirective
+        MSG = 'RuboCop disable/enable directives are not permitted.'
+        MSG_FOR_COPS = 'RuboCop disable/enable directives for %<cops>s are not permitted.'
+
+        def on_new_investigation
+          processed_source.comments.each do |comment|
+            directive_cops = directive_cops(comment)
+            disallowed_cops = directive_cops - allowed_cops
+
+            next unless disallowed_cops.any?
+
+            register_offense(comment, directive_cops, disallowed_cops)
+          end
+        end
+
+        private
+
+        def register_offense(comment, directive_cops, disallowed_cops)
+          message = if any_cops_allowed?
+                      format(MSG_FOR_COPS, cops: "`#{disallowed_cops.join('`, `')}`")
+                    else
+                      MSG
+                    end
+
+          add_offense(comment, message: message) do |corrector|
+            replacement = ''
+
+            if directive_cops.length != disallowed_cops.length
+              replacement = comment.text.sub(/#{Regexp.union(disallowed_cops)},?\s*/, '')
+                                   .sub(/,\s*$/, '')
+            end
+
+            corrector.replace(comment, replacement)
+          end
+        end
+
+        def directive_cops(comment)
+          match_captures = DirectiveComment.new(comment).match_captures
+          match_captures && match_captures[1] ? match_captures[1].split(',').map(&:strip) : []
+        end
+
+        def allowed_cops
+          Array(cop_config['AllowedCops'])
+        end
+
+        def any_cops_allowed?
+          allowed_cops.any?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Style
+      # When using `class_eval` (or other `eval`) with string interpolation,
+      # add a comment block showing its appearance if interpolated (a practice used in Rails code).
+      #
+      # @example
+      #   # from activesupport/lib/active_support/core_ext/string/output_safety.rb
+      #
+      #   # bad
+      #   UNSAFE_STRING_METHODS.each do |unsafe_method|
+      #     if 'String'.respond_to?(unsafe_method)
+      #       class_eval <<-EOT, __FILE__, __LINE__ + 1
+      #         def #{unsafe_method}(*params, &block)
+      #           to_str.#{unsafe_method}(*params, &block)
+      #         end
+      #
+      #         def #{unsafe_method}!(*params)
+      #           @dirty = true
+      #           super
+      #         end
+      #       EOT
+      #     end
+      #   end
+      #
+      #   # good, inline comments in heredoc
+      #   UNSAFE_STRING_METHODS.each do |unsafe_method|
+      #     if 'String'.respond_to?(unsafe_method)
+      #       class_eval <<-EOT, __FILE__, __LINE__ + 1
+      #         def #{unsafe_method}(*params, &block)       # def capitalize(*params, &block)
+      #           to_str.#{unsafe_method}(*params, &block)  #   to_str.capitalize(*params, &block)
+      #         end                                         # end
+      #
+      #         def #{unsafe_method}!(*params)              # def capitalize!(*params)
+      #           @dirty = true                             #   @dirty = true
+      #           super                                     #   super
+      #         end                                         # end
+      #       EOT
+      #     end
+      #   end
+      #
+      #   # good, block comments in heredoc
+      #   class_eval <<-EOT, __FILE__, __LINE__ + 1
+      #     # def capitalize!(*params)
+      #     #   @dirty = true
+      #     #   super
+      #     # end
+      #
+      #     def #{unsafe_method}!(*params)
+      #       @dirty = true
+      #       super
+      #     end
+      #   EOT
+      #
+      #   # good, block comments before heredoc
+      #   class_eval(
+      #     # def capitalize!(*params)
+      #     #   @dirty = true
+      #     #   super
+      #     # end
+      #
+      #     <<-EOT, __FILE__, __LINE__ + 1
+      #       def #{unsafe_method}!(*params)
+      #         @dirty = true
+      #         super
+      #       end
+      #     EOT
+      #   )
+      #
+      #   # bad - interpolated string without comment
+      #   class_eval("def #{unsafe_method}!(*params); end")
+      #
+      #   # good - with inline comment or replace it with block comment using heredoc
+      #   class_eval("def #{unsafe_method}!(*params); end # def capitalize!(*params); end")
+      class DocumentDynamicEvalDefinition < Base
+        BLOCK_COMMENT_REGEXP = /^\s*#(?!{)/.freeze
+        COMMENT_REGEXP = /\s*#(?!{).*/.freeze
+        MSG = 'Add a comment block showing its appearance if interpolated.'
+
+        RESTRICT_ON_SEND = %i[eval class_eval module_eval instance_eval].freeze
+
+        def on_send(node)
+          arg_node = node.first_argument
+
+          return unless arg_node&.dstr_type? && interpolated?(arg_node)
+          return if inline_comment_docs?(arg_node) ||
+                    (arg_node.heredoc? && comment_block_docs?(arg_node))
+
+          add_offense(node.loc.selector)
+        end
+
+        private
+
+        def interpolated?(arg_node)
+          arg_node.each_child_node(:begin).any?
+        end
+
+        def inline_comment_docs?(node)
+          node.each_child_node(:begin).all? do |begin_node|
+            source_line = processed_source.lines[begin_node.first_line - 1]
+            source_line.match?(COMMENT_REGEXP)
+          end
+        end
+
+        def comment_block_docs?(arg_node)
+          comments = heredoc_comment_blocks(arg_node.loc.heredoc_body.line_span)
+                     .concat(preceding_comment_blocks(arg_node.parent))
+
+          return false if comments.none?
+
+          regexp = comment_regexp(arg_node)
+          comments.any?(regexp) || regexp.match?(comments.join)
+        end
+
+        def preceding_comment_blocks(node)
+          # Collect comments in the method call, but outside the heredoc
+          comments = processed_source.each_comment_in_lines(node.source_range.line_span)
+
+          comments.each_with_object({}) do |comment, hash|
+            merge_adjacent_comments(comment.text, comment.loc.line, hash)
+          end.values
+        end
+
+        def heredoc_comment_blocks(heredoc_body)
+          # Collect comments inside the heredoc
+          line_range = (heredoc_body.begin - 1)..(heredoc_body.end - 1)
+          lines = processed_source.lines[line_range]
+
+          lines.each_with_object({}).with_index(line_range.begin) do |(line, hash), index|
+            merge_adjacent_comments(line, index, hash)
+          end.values
+        end
+
+        def merge_adjacent_comments(line, index, hash)
+          # Combine adjacent comment lines into a single string
+          return unless (line = line.dup.gsub!(BLOCK_COMMENT_REGEXP, ''))
+
+          hash[index] = if hash.keys.last == index - 1
+                          [hash.delete(index - 1), line].join("\n")
+                        else
+                          line
+                        end
+        end
+
+        def comment_regexp(arg_node)
+          # Replace the interpolations with wildcards
+          regexp_parts = arg_node.child_nodes.map do |n|
+            n.begin_type? ? /.+/ : source_to_regexp(n.source)
+          end
+
+          Regexp.new(regexp_parts.join)
+        end
+
+        def source_to_regexp(source)
+          # Get the source in the heredoc being `eval`ed, without any comments
+          # and turn it into a regexp
+          return /\s+/ if source.blank?
+
+          source = source.gsub(COMMENT_REGEXP, '')
+          return if source.blank?
+
+          /\s*#{Regexp.escape(source.strip)}/
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Style
+      # Checks for missing top-level documentation of classes and
+      # modules. Classes with no body are exempt from the check and so are
+      # namespace modules - modules that have nothing in their bodies except
+      # classes, other modules, constant definitions or constant visibility
+      # declarations.
+      #
+      # The documentation requirement is annulled if the class or module has
+      # a `#:nodoc:` comment next to it. Likewise, `#:nodoc: all` does the
+      # same for all its children.
+      #
+      # @example
+      #   # bad
+      #   class Person
+      #     # ...
+      #   end
+      #
+      #   module Math
+      #   end
+      #
+      #   # good
+      #   # Description/Explanation of Person class
+      #   class Person
+      #     # ...
+      #   end
+      #
+      #   # allowed
+      #   # Class without body
+      #   class Person
+      #   end
+      #
+      #   # Namespace - A namespace can be a class or a module
+      #   # Containing a class
+      #   module Namespace
+      #     # Description/Explanation of Person class
+      #     class Person
+      #       # ...
+      #     end
+      #   end
+      #
+      #   # Containing constant visibility declaration
+      #   module Namespace
+      #     class Private
+      #     end
+      #
+      #     private_constant :Private
+      #   end
+      #
+      #   # Containing constant definition
+      #   module Namespace
+      #     Public = Class.new
+      #   end
+      #
+      #   # Macro calls
+      #   module Namespace
+      #     extend Foo
+      #   end
+      #
+      # @example AllowedConstants: ['ClassMethods']
+      #
+      #    # good
+      #    module A
+      #      module ClassMethods
+      #        # ...
+      #      end
+      #    end
+      #
+      class Documentation < Base
+        include DocumentationComment
+        include RangeHelp
+
+        MSG = 'Missing top-level documentation comment for `%<type>s %<identifier>s`.'
+
+        # @!method constant_definition?(node)
+        def_node_matcher :constant_definition?, '{class module casgn}'
+
+        # @!method outer_module(node)
+        def_node_search :outer_module, '(const (const nil? _) _)'
+
+        # @!method constant_visibility_declaration?(node)
+        def_node_matcher :constant_visibility_declaration?, <<~PATTERN
+          (send nil? {:public_constant :private_constant} ({sym str} _))
+        PATTERN
+
+        # @!method include_statement?(node)
+        def_node_matcher :include_statement?, <<~PATTERN
+          (send nil? {:include :extend :prepend} const)
+        PATTERN
+
+        def on_class(node)
+          return unless node.body
+
+          check(node, node.body)
+        end
+
+        def on_module(node)
+          check(node, node.body)
+        end
+
+        private
+
+        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 include_statement_only?(body)
+
+          range = range_between(node.source_range.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))
+        end
+
+        def include_statement_only?(body)
+          return true if include_statement?(body)
+
+          body.respond_to?(:children) && body.children.all? { |node| include_statement_only?(node) }
+        end
+
+        def namespace?(node)
+          return false unless node
+
+          if node.begin_type?
+            node.children.all? { |child| constant_declaration?(child) }
+          else
+            constant_definition?(node)
+          end
+        end
+
+        def constant_declaration?(node)
+          constant_definition?(node) || constant_visibility_declaration?(node)
+        end
+
+        def constant_allowed?(node)
+          allowed_constants.include?(node.identifier.short_name)
+        end
+
+        def compact_namespace?(node)
+          node.loc.name.source.include?('::')
+        end
+
+        # First checks if the :nodoc: comment is associated with the
+        # class/module. Unless the element is tagged with :nodoc:, the search
+        # proceeds to check its ancestors for :nodoc: all.
+        # Note: How end-of-line comments are associated with code changed in
+        # parser-2.2.0.4.
+        def nodoc_comment?(node, require_all: false)
+          return false unless node&.children&.first
+
+          nodoc = nodoc(node)
+
+          return true if same_line?(nodoc, node) && nodoc?(nodoc, require_all: require_all)
+
+          nodoc_comment?(node.parent, require_all: true)
+        end
+
+        def nodoc?(comment, require_all: false)
+          /^#\s*:nodoc:#{"\s+all\s*$" if require_all}/.match?(comment.text)
+        end
+
+        def nodoc(node)
+          processed_source.ast_with_comments[node.children.first].first
+        end
+
+        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)]
+          identifier = nodes.reverse_each.flat_map { |n| qualify_const(n.identifier) }.join('::')
+
+          identifier.sub('::::', '::')
+        end
+
+        def qualify_const(node)
+          return if node.nil?
+
+          if node.type?(:cbase, :self, :call) || node.variable?
+            node.source
+          else
+            [qualify_const(node.namespace), node.short_name].compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Style
+      # Checks for missing documentation comment for public methods.
+      # It can optionally be configured to also require documentation for
+      # non-public methods.
+      #
+      # NOTE: This cop allows `initialize` method because `initialize` is
+      # a special method called from `new`. In some programming languages
+      # they are called constructor to distinguish it from method.
+      #
+      # @example
+      #
+      #   # bad
+      #
+      #   class Foo
+      #     def bar
+      #       puts baz
+      #     end
+      #   end
+      #
+      #   module Foo
+      #     def bar
+      #       puts baz
+      #     end
+      #   end
+      #
+      #   def foo.bar
+      #     puts baz
+      #   end
+      #
+      #   # good
+      #
+      #   class Foo
+      #     # Documentation
+      #     def bar
+      #       puts baz
+      #     end
+      #   end
+      #
+      #   module Foo
+      #     # Documentation
+      #     def bar
+      #       puts baz
+      #     end
+      #   end
+      #
+      #   # Documentation
+      #   def foo.bar
+      #     puts baz
+      #   end
+      #
+      # @example RequireForNonPublicMethods: false (default)
+      #   # good
+      #   class Foo
+      #     protected
+      #     def do_something
+      #     end
+      #   end
+      #
+      #   class Foo
+      #     private
+      #     def do_something
+      #     end
+      #   end
+      #
+      # @example RequireForNonPublicMethods: true
+      #   # bad
+      #   class Foo
+      #     protected
+      #     def do_something
+      #     end
+      #   end
+      #
+      #   class Foo
+      #     private
+      #     def do_something
+      #     end
+      #   end
+      #
+      #   # good
+      #   class Foo
+      #     protected
+      #     # Documentation
+      #     def do_something
+      #     end
+      #   end
+      #
+      #   class Foo
+      #     private
+      #     # Documentation
+      #     def do_something
+      #     end
+      #   end
+      #
+      # @example AllowedMethods: ['method_missing', 'respond_to_missing?']
+      #
+      #    # good
+      #    class Foo
+      #      def method_missing(name, *args)
+      #      end
+      #
+      #      def respond_to_missing?(symbol, include_private)
+      #      end
+      #    end
+      #
+      class DocumentationMethod < Base
+        include DocumentationComment
+        include DefNode
+
+        MSG = 'Missing method documentation comment.'
+
+        # @!method modifier_node?(node)
+        def_node_matcher :modifier_node?, <<~PATTERN
+          (send nil? {:module_function :ruby2_keywords} ...)
+        PATTERN
+
+        def on_def(node)
+          return if node.method?(:initialize)
+
+          parent = node.parent
+          modifier_node?(parent) ? check(parent) : check(node)
+        end
+        alias on_defs on_def
+
+        private
+
+        def check(node)
+          return if non_public?(node) && !require_for_non_public_methods?
+          return if documentation_comment?(node)
+          return if method_allowed?(node)
+
+          add_offense(node)
+        end
+
+        def require_for_non_public_methods?
+          cop_config['RequireForNonPublicMethods']
+        end
+
+        def method_allowed?(node)
+          allowed_methods.include?(node.method_name)
+        end
+
+        def allowed_methods
+          @allowed_methods ||= cop_config.fetch('AllowedMethods', []).map(&:to_sym)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# rubocop:disable Lint/RedundantCopDisableDirective
+# rubocop:disable Style/DoubleCopDisableDirective
+
+module RuboCop
+  module Cop
+    module Style
+      # Detects double disable comments on one line. This is mostly to catch
+      # automatically generated comments that need to be regenerated.
+      #
+      # @example
+      #   # bad
+      #   def f # rubocop:disable Style/For # rubocop:disable Metrics/AbcSize
+      #   end
+      #
+      #   # good
+      #   # rubocop:disable Metrics/AbcSize
+      #   def f # rubocop:disable Style/For
+      #   end
+      #   # rubocop:enable Metrics/AbcSize
+      #
+      #   # if both fit on one line
+      #   def f # rubocop:disable Style/For, Metrics/AbcSize
+      #   end
+      #
+      class DoubleCopDisableDirective < Base
+        extend AutoCorrector
+
+        # rubocop:enable Style/For, Style/DoubleCopDisableDirective
+        # rubocop:enable Lint/RedundantCopDisableDirective, Metrics/AbcSize
+        MSG = 'More than one disable comment on one line.'
+
+        def on_new_investigation
+          processed_source.comments.each do |comment|
+            next unless comment.text.scan(/# rubocop:(?:disable|todo)/).size > 1
+
+            add_offense(comment) do |corrector|
+              corrector.replace(comment, comment.text.gsub(%r{ # rubocop:(disable|todo)}, ','))
+            end
+          end
+        end
+      end
+    end
+  end
+end