rubocop 1.90.0 → 1.92.0

data/lib/rubocop/directive_comment.rb

@@ -26,7 +26,8 @@ module RuboCop
     # @api private
     PUSH_POP_ARGS_PATTERN = "([+\\-]#{COP_NAME_PATTERN_NC}(?:\\s+[+\\-]#{COP_NAME_PATTERN_NC})*)"
     # @api private
-    AVAILABLE_MODES = %w[disable enable todo push pop disable-next todo-next].freeze
+    AVAILABLE_MODES = %w[disable enable todo push pop disable-next todo-next enable-next
+                         next].freeze
     # @api private
     # Longest first, so a `-next` mode is not matched as its prefix
     # (`-` is a word boundary).
@@ -43,6 +44,8 @@ module RuboCop
         .gsub(' ', '\s*')
     )
     # @api private
+    SIGNED_OPERATIONS = %w[+ -].freeze
+    # @api private
     TRAILING_COMMENT_MARKER = '--'
     # @api private
     MALFORMED_DIRECTIVE_WITHOUT_COP_NAME_REGEXP = Regexp.new(
@@ -71,7 +74,7 @@ module RuboCop
     # Checks if the comment is malformed as a `# rubocop:` directive
     def malformed?
       return true if !start_with_marker? || @match_data.nil?
-      return true if missing_cop_name?
+      return true if missing_cop_name? || invalid_signed_args?
 
       tail = @match_data.post_match.lstrip
       !(tail.empty? || tail.start_with?(TRAILING_COMMENT_MARKER))
@@ -84,6 +87,16 @@ module RuboCop
       MALFORMED_DIRECTIVE_WITHOUT_COP_NAME_REGEXP.match?(comment.text)
     end
 
+    # `push` and `next` arguments must be `+`/`-` prefixed cop names, and
+    # `pop` takes no arguments at all.
+    def invalid_signed_args?
+      return cops ? !cops.empty? : false if pop?
+      return false unless push? || next?
+      return false unless cops
+
+      cops.split.any? { |cop_spec| !cop_spec.start_with?('+', '-') }
+    end
+
     # The text of the directive's optional `--` trailing comment, or `nil`
     # when there is none.
     def reason
@@ -150,7 +163,12 @@ module RuboCop
 
     # Checks if this directive enables cops
     def enabled?
-      mode == 'enable'
+      mode == 'enable' || enable_next?
+    end
+
+    # Checks if this directive enables cops for the next statement only
+    def enable_next?
+      mode == 'enable-next'
     end
 
     # Checks if this directive is a push
@@ -163,10 +181,17 @@ module RuboCop
       mode == 'pop'
     end
 
-    # Returns the push arguments as a hash of cop names with their operations
-    def push_args
-      @push_args ||= parse_push_args
+    # Checks if this directive toggles cops for the next statement only
+    def next?
+      mode == 'next'
+    end
+
+    # Returns the `+`/`-` arguments of a `push` or `next` directive as a hash
+    # of operations to cop names
+    def signed_args
+      @signed_args ||= parse_signed_args
     end
+    alias push_args signed_args
 
     # Checks if this directive enables all cops
     def enabled_all?
@@ -210,6 +235,8 @@ module RuboCop
     end
 
     def directive_count
+      return signed_args.values.sum(&:count) if push? || next?
+
       raw_cop_names.count
     end
 
@@ -244,13 +271,15 @@ module RuboCop
       cops - [LINT_REDUNDANT_DIRECTIVE_COP, LINT_SYNTAX_COP]
     end
 
-    def parse_push_args
-      return {} unless push? && cops
+    def parse_signed_args
+      return {} unless (push? || next?) && cops
 
       args = {}
       cops.split.each do |cop_spec|
         op = cop_spec[0]
         cop_name = cop_spec[1..]
+        next unless SIGNED_OPERATIONS.include?(op)
+
         args[op] ||= []
         args[op] << cop_name
       end

data/lib/rubocop/formatter/base_formatter.rb

@@ -35,6 +35,7 @@ module RuboCop
     # * `#file_started`
     # * `#file_finished`
     # * `#file_started`
+    # * `#file_problems` (only when a cop crashed or warned on the file)
     # * `#file_finished`
     # * `#finished`
     #
@@ -88,6 +89,27 @@ module RuboCop
       # @return [void]
       def file_started(file, options); end
 
+      # @api public
+      #
+      # Invoked before `#file_finished` for a file that a cop crashed on or
+      # raised a warning for, or whose corrections went into an infinite loop.
+      # Optional: a formatter implementing the API by duck typing is skipped
+      # when it doesn't define it.
+      #
+      # @param file [String]
+      #   the file path
+      #
+      # @param errors [Array(String)]
+      #   the error messages as they're printed, without colors. A cop that
+      #   crashes on every node of a kind has a message for each, naming the
+      #   line and column.
+      #
+      # @param warnings [Array(String)]
+      #   the warning messages, in the same form
+      #
+      # @return [void]
+      def file_problems(file, errors, warnings); end
+
       # @api public
       #
       # Invoked at the end of inspecting each files.

data/lib/rubocop/formatter/disabled_config_formatter.rb

@@ -23,6 +23,7 @@ module RuboCop
         Enabled
         Exclude
         Include
+        Preview
         Reference
         References
         Safe
@@ -93,6 +94,7 @@ module RuboCop
         command += ' --auto-gen-only-exclude' if @options[:auto_gen_only_exclude]
         command += ' --disable-pending-cops' if @options[:disable_pending_cops]
         command += ' --enable-pending-cops' if @options[:enable_pending_cops]
+        command += preview_option
         command += exclude_limit_option
         command += ' --no-offense-counts' unless show_offense_counts?
 
@@ -103,6 +105,14 @@ module RuboCop
         command
       end
 
+      def preview_option
+        case @options[:preview]
+        when true then ' --preview'
+        when false then ' --no-preview'
+        else ''
+        end
+      end
+
       def exclude_limit_option
         if no_exclude_limit?
           ' --no-exclude-limit'
@@ -259,7 +269,7 @@ module RuboCop
         config = ConfigStore.new.for(parent)
         cfg = config[cop_name] || {}
 
-        if merge_mode_for_exclude?(config) || merge_mode_for_exclude?(cfg)
+        if exclude_merges?(config, cfg)
           offending_files
         else
           cop_exclude = cfg['Exclude']
@@ -272,6 +282,14 @@ module RuboCop
         end
       end
 
+      # `Preview` merges `Exclude` with the default configuration, so the excludes
+      # already in the configuration do not have to be copied into the todo file.
+      def exclude_merges?(config, cop_config)
+        merge_mode_for_exclude?(config) ||
+          merge_mode_for_exclude?(cop_config) ||
+          config.preview?(@options)
+      end
+
       def merge_mode_for_exclude?(cfg)
         Array(cfg.to_h.dig('inherit_mode', 'merge')).include?('Exclude')
       end

data/lib/rubocop/formatter/formatter_set.rb

@@ -23,6 +23,7 @@ module RuboCop
         '[pa]cman'      => 'PacmanFormatter',
         '[p]rogress'    => 'ProgressFormatter',
         '[q]uiet'       => 'QuietFormatter',
+        '[sa]rif'       => 'SARIFFormatter',
         '[s]imple'      => 'SimpleTextFormatter',
         '[t]ap'         => 'TapFormatter',
         '[w]orst'       => 'WorstOffendersFormatter'
@@ -48,6 +49,10 @@ module RuboCop
         each { |f| f.file_started(file, options) }
       end
 
+      def file_problems(file, errors, warnings)
+        each { |f| f.file_problems(file, errors, warnings) if f.respond_to?(:file_problems) }
+      end
+
       def file_finished(file, offenses)
         each { |f| f.file_finished(file, offenses) }
         offenses
@@ -57,7 +62,7 @@ module RuboCop
         if output_path
           dir_path = File.dirname(output_path)
           FileUtils.mkdir_p(dir_path)
-          output = File.open(output_path, 'w') # rubocop:disable Style/FileOpen
+          output = File.open(output_path, 'w') # rubocop:disable Style/FileOpen -- the file is closed by `close_output_files`, not by a block
         else
           output = $stdout
         end

data/lib/rubocop/formatter/github_actions_formatter.rb

@@ -15,6 +15,10 @@ module RuboCop
         @offenses_for_files[file] = offenses unless offenses.empty?
       end
 
+      def file_started(_file, options)
+        @config_store = options[:config_store]
+      end
+
       def finished(_inspected_files)
         @offenses_for_files.each do |file, offenses|
           offenses.each do |offense|
@@ -31,11 +35,8 @@ module RuboCop
       end
 
       def minimum_severity_to_fail
-        @minimum_severity_to_fail ||= begin
-          # Unless given explicitly as `fail_level`, `:info` severity offenses do not fail
-          name = options.fetch(:fail_level, :refactor)
-          RuboCop::Cop::Severity.new(name)
-        end
+        @minimum_severity_to_fail ||=
+          RuboCop::Cop::Severity.minimum_to_fail(options, @config_store&.for_pwd)
       end
 
       def github_severity(offense)

data/lib/rubocop/formatter/html_formatter.rb

@@ -74,7 +74,7 @@ module RuboCop
         end
 
         # Make Kernel#binding public.
-        # rubocop:disable-next Lint/UselessMethodDefinition
+        # rubocop:disable-next Lint/UselessMethodDefinition -- redefined only to make `Kernel#binding` public
         def binding
           super
         end
@@ -143,7 +143,7 @@ module RuboCop
         }.freeze
 
         # Make Kernel#binding public.
-        # rubocop:disable-next Lint/UselessMethodDefinition
+        # rubocop:disable-next Lint/UselessMethodDefinition -- redefined only to make `Kernel#binding` public
         def binding
           super
         end

data/lib/rubocop/formatter/json_formatter.rb

@@ -13,19 +13,29 @@ module RuboCop
       def initialize(output, options = {})
         super
         @output_hash = { metadata: metadata_hash, files: [], summary: { offense_count: 0 } }
+        @problems = {}
       end
 
       def started(target_files)
         output_hash[:summary][:target_file_count] = target_files.count
       end
 
+      def file_problems(file, errors, warnings)
+        @problems[file] = hash_for_problems(file, errors, warnings)
+      end
+
       def file_finished(file, offenses)
-        output_hash[:files] << hash_for_file(file, offenses)
+        entry = hash_for_file(file, offenses)
+        problems = @problems.delete(file)
+        entry.merge!(problems) if problems
+
+        output_hash[:files] << entry
         output_hash[:summary][:offense_count] += offenses.count
       end
 
       def finished(inspected_files)
         output_hash[:summary][:inspected_file_count] = inspected_files.count
+        output_hash[:summary].merge!(problem_counts(output_hash[:files]))
         output.write output_hash.to_json
       end
 
@@ -46,6 +56,32 @@ module RuboCop
         }
       end
 
+      # A cop that crashes fails once per node it visits, so messages that
+      # differ only in their line and column are listed once, at the first place
+      # they happened. They name the file the way its entry does. The keys are
+      # absent when there's nothing to report, which keeps them additive for
+      # existing consumers.
+      def hash_for_problems(file, errors, warnings)
+        return {} if errors.empty? && warnings.empty?
+
+        path = smart_path(file)
+        location = /#{Regexp.escape(File.expand_path(file))}((?::\d+)*)/
+
+        { errors: errors, warnings: warnings }.filter_map do |key, messages|
+          next if messages.empty?
+
+          messages = messages.uniq { |message| message.gsub(location, '') }
+          [key, messages.map { |message| message.gsub(location) { path + Regexp.last_match(1) } }]
+        end.to_h
+      end
+
+      def problem_counts(files)
+        {
+          error_count: files.sum { |f| f[:errors]&.size.to_i },
+          warning_count: files.sum { |f| f[:warnings]&.size.to_i }
+        }.reject { |_, count| count.zero? }
+      end
+
       def hash_for_offense(offense)
         hash = {
           severity:    offense.severity.name,
@@ -63,9 +99,43 @@ module RuboCop
           hash[:justification] = offense.justification
         end
 
+        # The edits autocorrection would make, so a consumer can apply or review
+        # them without running autocorrection itself. Additive, and absent when
+        # the offense has no correction.
+        hash[:correction] = correction_for(offense) unless offense.corrections.empty?
+
         hash
       end
 
+      def correction_for(offense)
+        { safe: offense.correction_safe, edits: edits_for(offense) }
+      end
+
+      def edits_for(offense)
+        buffer = offense.location.source_buffer
+
+        offense.corrections.map do |correction|
+          # Built as a range so the columns follow the same 1-based convention
+          # as `hash_for_location`, end-exclusive column included.
+          range = ::Parser::Source::Range.new(buffer, correction.begin_pos, correction.end_pos)
+
+          hash_for_edit_range(range).merge!(
+            begin_pos: correction.begin_pos,
+            end_pos: correction.end_pos,
+            replacement: correction.replacement
+          )
+        end
+      end
+
+      def hash_for_edit_range(range)
+        {
+          start_line: range.line,
+          start_column: range.column + 1,
+          last_line: range.last_line,
+          last_column: range.last_column.zero? ? 1 : range.last_column
+        }
+      end
+
       def hash_for_location(offense)
         {
           start_line:   offense.line,

data/lib/rubocop/formatter/junit_formatter.rb

@@ -47,7 +47,7 @@ module RuboCop
         end
       end
 
-      # rubocop:disable-next Layout/LineLength,Metrics/AbcSize,Metrics/MethodLength
+      # rubocop:disable-next Layout/LineLength,Metrics/AbcSize,Metrics/MethodLength -- the XML is emitted line by line
       def finished(_inspected_files)
         output.puts %(<?xml version='1.0'?>)
         output.puts %(<testsuites>)

data/lib/rubocop/formatter/offense_count_formatter.rb

@@ -14,6 +14,8 @@ module RuboCop
     # --
     # 29  Total in 5 files
     class OffenseCountFormatter < BaseFormatter
+      include TextUtil
+
       attr_reader :offense_counts
 
       def started(target_files)
@@ -64,7 +66,7 @@ module RuboCop
           output.puts "#{count.to_s.ljust(column_width)}#{cop_information(cop_name)}"
         end
         output.puts '--'
-        output.puts "#{total_count}  Total in #{offending_files_count} files"
+        output.puts "#{total_count}  Total in #{pluralize(offending_files_count, 'file')}"
 
         output.puts
       end

data/lib/rubocop/formatter/pacman_formatter.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'io/console'
+
 module RuboCop
   module Formatter
     # This formatter prints a PACDOT per every file to be analyzed.
@@ -50,7 +52,7 @@ module RuboCop
 
       def cols
         @cols ||= begin
-          _height, width = $stdout.winsize
+          _height, width = output.winsize if output.tty?
           width.nil? || width.zero? ? FALLBACK_TERMINAL_WIDTH : width
         end
       end

data/lib/rubocop/formatter/sarif_formatter.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module RuboCop
+  module Formatter
+    # This formatter formats the report data in SARIF 2.1.0, the OASIS standard
+    # for static analysis results. It's understood by GitHub code scanning,
+    # Azure DevOps, and other tools that aggregate analyzer output.
+    #
+    # SARIF only knows three severity levels, so RuboCop's `info`, `refactor`
+    # and `convention` severities are all reported as `note`.
+    class SARIFFormatter < BaseFormatter
+      SCHEMA_URI = 'https://json.schemastore.org/sarif-2.1.0.json'
+      SARIF_VERSION = '2.1.0'
+      INFORMATION_URI = 'https://rubocop.org'
+
+      SEVERITY_LEVELS = {
+        info: 'note',
+        refactor: 'note',
+        convention: 'note',
+        warning: 'warning',
+        error: 'error',
+        fatal: 'error'
+      }.freeze
+
+      def initialize(output, options = {})
+        super
+
+        @rules = []
+        @rule_indexes = {}
+        @results = []
+        @config_store = nil
+      end
+
+      def file_started(_file, options)
+        @config_store = options[:config_store]
+      end
+
+      def file_finished(file, offenses)
+        line_hash_counts = Hash.new(0)
+        offenses.each do |offense|
+          @results << result_for(file, offense, line_hash_counts)
+        end
+      end
+
+      def finished(_inspected_files)
+        output.write(report.to_json)
+      end
+
+      private
+
+      def report
+        {
+          '$schema': SCHEMA_URI,
+          version: SARIF_VERSION,
+          runs: [{ tool: { driver: driver }, results: @results }]
+        }
+      end
+
+      def driver
+        {
+          name: 'RuboCop',
+          version: RuboCop::Version::STRING,
+          semanticVersion: RuboCop::Version::STRING,
+          informationUri: INFORMATION_URI,
+          rules: @rules
+        }
+      end
+
+      def result_for(file, offense, line_hash_counts)
+        result = {
+          ruleId: offense.cop_name,
+          ruleIndex: rule_index_for(file, offense),
+          level: SEVERITY_LEVELS.fetch(offense.severity.name, 'warning'),
+          message: { text: offense.message },
+          locations: [location_for(file, offense)],
+          partialFingerprints: fingerprints_for(offense, line_hash_counts)
+        }
+
+        # Suppressed offenses are only reported under `--display-suppressed`.
+        # SARIF has a first-class representation for them, so consumers can
+        # tell them apart from offenses that were never triggered.
+        result[:suppressions] = [suppression_for(offense)] if offense.disabled?
+        result
+      end
+
+      # The URI is relative to the working directory, which is what consumers
+      # expect to resolve against their own checkout. No `uriBaseId`: it would
+      # have to be declared under `originalUriBaseIds` to mean anything, and
+      # every consumer that matters resolves relative paths without it.
+      def location_for(file, offense)
+        {
+          physicalLocation: {
+            artifactLocation: { uri: uri_for(file) },
+            region: region_for(offense)
+          }
+        }
+      end
+
+      def region_for(offense)
+        # SARIF columns are 1-based and `endColumn` points at the character
+        # *after* the region, while `real_last_column` is the last character.
+        {
+          startLine: offense.first_line,
+          startColumn: offense.real_column,
+          endLine: offense.last_line,
+          endColumn: offense.real_last_column + 1
+        }
+      end
+
+      # GitHub uses these to match an alert across runs. Without them it falls
+      # back to the file path, which makes alerts churn whenever a file moves.
+      # Repeats of the same hash within a file get a `:N` suffix, like GitHub's
+      # own fingerprints, so two offenses on one line don't merge into one alert.
+      # The first occurrence keeps the bare hash to match earlier reports.
+      def fingerprints_for(offense, line_hash_counts)
+        line_hash = Digest::SHA256.hexdigest("#{offense.cop_name}#{offense.location.source_line}")
+        count = line_hash_counts[line_hash] += 1
+        { primaryLocationLineHash: count == 1 ? line_hash : "#{line_hash}:#{count}" }
+      end
+
+      def suppression_for(offense)
+        suppression = { kind: 'inSource' }
+        suppression[:justification] = offense.justification if offense.justification
+        suppression
+      end
+
+      def rule_index_for(file, offense)
+        @rule_indexes[offense.cop_name] ||= begin
+          @rules << rule_for(file, offense)
+          @rules.size - 1
+        end
+      end
+
+      def rule_for(file, offense)
+        cop_class = Cop::Registry.global.find_by_cop_name(offense.cop_name)
+        description = description_for(file, offense)
+        help_uri = cop_class && Cop::Documentation.url_for(cop_class, config_for(file))
+
+        rule = {
+          id: offense.cop_name,
+          name: offense.cop_name,
+          shortDescription: { text: description },
+          fullDescription: { text: description },
+          help: help_for(description, help_uri),
+          defaultConfiguration: { level: default_level_for(file, offense, cop_class) },
+          properties: { tags: [offense.cop_name.split('/').first] }
+        }
+        rule[:helpUri] = help_uri if help_uri
+        rule
+      end
+
+      def help_for(description, help_uri)
+        help = { text: description }
+        help[:markdown] = "#{description}\n\n[Documentation](#{help_uri})" if help_uri
+        help
+      end
+
+      def description_for(file, offense)
+        cop_config(file, offense)['Description'] || offense.cop_name
+      end
+
+      def default_level_for(file, offense, cop_class)
+        severity = cop_config(file, offense)['Severity'] ||
+                   Cop::Base::DEPARTMENT_SEVERITIES.fetch(cop_class&.department, :convention)
+
+        SEVERITY_LEVELS.fetch(severity.to_sym, 'warning')
+      end
+
+      def cop_config(file, offense)
+        config_for(file)&.for_cop(offense.cop_name) || {}
+      end
+
+      # `file_started` is not called when a formatter is used directly through
+      # the API, so there may be no config to consult.
+      def config_for(file)
+        @config_store&.for_file(file)
+      end
+
+      def uri_for(file)
+        PathUtil.smart_path(file).tr('\\', '/')
+      end
+    end
+  end
+end

data/lib/rubocop/formatter/worst_offenders_formatter.rb

@@ -14,6 +14,8 @@ module RuboCop
     # --
     # 29  Total in 2 files
     class WorstOffendersFormatter < BaseFormatter
+      include TextUtil
+
       attr_reader :offense_counts
 
       def started(target_files)
@@ -46,7 +48,7 @@ module RuboCop
         end
 
         output.puts '--'
-        output.puts "#{total_count}  Total in #{file_count} files"
+        output.puts "#{total_count}  Total in #{pluralize(file_count, 'file')}"
 
         output.puts
       end

data/lib/rubocop/formatter.rb

@@ -24,6 +24,7 @@ module RuboCop
     autoload :PacmanFormatter, 'rubocop/formatter/pacman_formatter'
     autoload :ProgressFormatter, 'rubocop/formatter/progress_formatter'
     autoload :QuietFormatter, 'rubocop/formatter/quiet_formatter'
+    autoload :SARIFFormatter, 'rubocop/formatter/sarif_formatter'
     autoload :TapFormatter, 'rubocop/formatter/tap_formatter'
     autoload :WorstOffendersFormatter, 'rubocop/formatter/worst_offenders_formatter'