rubocop 1.81.7 → 1.92.1

data/lib/rubocop/magic_comment.rb

@@ -11,6 +11,8 @@ module RuboCop
     KEYWORDS = {
       encoding: '(?:en)?coding',
       frozen_string_literal: 'frozen[_-]string[_-]literal',
+      rbs_inline: 'rbs_inline',
+      warn_indent: 'warn[_-]indent',
       shareable_constant_value: 'shareable[_-]constant[_-]value',
       typed: 'typed'
     }.freeze
@@ -36,6 +38,8 @@ module RuboCop
     def any?
       frozen_string_literal_specified? ||
         encoding_specified? ||
+        rbs_inline_specified? ||
+        warn_indent_specified? ||
         shareable_constant_value_specified? ||
         typed_specified?
     end
@@ -60,6 +64,10 @@ module RuboCop
       [true, false].include?(frozen_string_literal)
     end
 
+    def valid_rbs_inline_value?
+      %w[enabled disabled].include?(extract_rbs_inline_value)
+    end
+
     def valid_shareable_constant_value?
       %w[none literal experimental_everything experimental_copy].include?(shareable_constant_value)
     end
@@ -71,6 +79,13 @@ module RuboCop
       specified?(frozen_string_literal)
     end
 
+    # Was a warn_indent specified?
+    #
+    # @return [Boolean]
+    def warn_indent_specified?
+      specified?(warn_indent)
+    end
+
     # Was a shareable_constant_value specified?
     #
     # @return [Boolean]
@@ -94,6 +109,13 @@ module RuboCop
       end
     end
 
+    # Expose the `warn_indent` value.
+    #
+    # @return [String] for warn_indent config
+    def warn_indent
+      extract_warn_indent
+    end
+
     # Expose the `shareable_constant_value` value coerced to a boolean if possible.
     #
     # @return [String] for shareable_constant_value config
@@ -105,6 +127,10 @@ module RuboCop
       specified?(encoding)
     end
 
+    def rbs_inline_specified?
+      valid_rbs_inline_value?
+    end
+
     # Was the Sorbet `typed` sigil specified?
     #
     # @return [Boolean]
@@ -203,6 +229,13 @@ module RuboCop
         match(KEYWORDS[:frozen_string_literal])
       end
 
+      # Emacs comments cannot specify RBS::inline behavior.
+      def extract_rbs_inline_value; end
+
+      def extract_warn_indent
+        match(KEYWORDS[:warn_indent])
+      end
+
       def extract_shareable_constant_value
         match(KEYWORDS[:shareable_constant_value])
       end
@@ -242,6 +275,12 @@ module RuboCop
       # Vim comments cannot specify frozen string literal behavior.
       def frozen_string_literal; end
 
+      # Vim comments cannot specify RBS::inline behavior.
+      def extract_rbs_inline_value; end
+
+      # Vim comments cannot specify indentation warning behavior.
+      def warn_indent; end
+
       # Vim comments cannot specify shareable constant values behavior.
       def shareable_constant_value; end
 
@@ -296,6 +335,14 @@ module RuboCop
         extract(/\A\s*#\s*#{KEYWORDS[:frozen_string_literal]}:\s*#{TOKEN}\s*\z/io)
       end
 
+      def extract_rbs_inline_value
+        extract(/\A\s*#\s*#{KEYWORDS[:rbs_inline]}:\s*#{TOKEN}\s*\z/io)
+      end
+
+      def extract_warn_indent
+        extract(/\A\s*#\s*#{KEYWORDS[:warn_indent]}:\s*#{TOKEN}\s*\z/io)
+      end
+
       def extract_shareable_constant_value
         extract(/\A\s*#\s*#{KEYWORDS[:shareable_constant_value]}:\s*#{TOKEN}\s*\z/io)
       end

data/lib/rubocop/mcp/autocorrection_request.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module MCP
+    # What an autocorrection request asks for, shared by every file it corrects.
+    # The keywords are the tool's arguments, so an unknown one is refused.
+    # @api private
+    class AutocorrectionRequest
+      PROPERTIES = {
+        safety: { type: 'boolean' },
+        contextual: { type: 'boolean' },
+        dry_run: { type: 'boolean' },
+        max_offenses_per_cop: { type: 'integer', minimum: 1 }
+      }.freeze
+
+      # The offenses left over come back after the files are written, so they're
+      # capped unless the agent asks otherwise: a result too big for the client
+      # would hide what was done.
+      DEFAULT_MAX_OFFENSES_PER_COP = 5
+
+      attr_reader :scope, :limit
+
+      def initialize(scope, safety: true, contextual: false, dry_run: false,
+                     max_offenses_per_cop: DEFAULT_MAX_OFFENSES_PER_COP)
+        @scope = scope
+        @safety = safety
+        @contextual = contextual
+        @dry_run = dry_run
+        @limit = OffenseLimit.new(max_offenses_per_cop)
+      end
+
+      def dry_run?
+        @dry_run
+      end
+
+      # The options `LSP::Runtime#format` takes to apply the corrections
+      # `safety` and `contextual` allow, from the cops the scope selects.
+      def format_options
+        command = @safety ? 'rubocop.formatAutocorrects' : 'rubocop.formatAutocorrectsAll'
+        { command: command, options: runtime_options }
+      end
+
+      # The options the LSP runtime takes for each call the request makes.
+      # Cops with `AutoCorrect: contextual` hold back corrections that get in
+      # the way of code still being written, such as removing a variable that
+      # is about to be used, so an agent that is done editing has to ask for them.
+      def runtime_options
+        { **@scope.cop_options, editing: !@contextual }
+      end
+    end
+  end
+end

data/lib/rubocop/mcp/explain_tool.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module MCP
+    # The `rubocop_explain` tool: what cops do, as `--explain` prints it.
+    # @api private
+    class ExplainTool
+      include RuboCop::CLI::Command::CopNames
+
+      DESCRIPTION =
+        'Explain what cops do: the problem each one targets, bad and good examples, ' \
+        'its configuration as this project resolves it, and whether it autocorrects. ' \
+        'Takes cop names as offenses report them, such as `Style/StringLiterals`. ' \
+        'Pass the `path` of a file to see the configuration that applies to it.'
+      INPUT_SCHEMA = {
+        properties: {
+          cop_names: { type: 'array', items: { type: 'string' }, minItems: 1 },
+          path: { type: 'string' }
+        },
+        required: ['cop_names'],
+        additionalProperties: false
+      }.freeze
+      ANNOTATIONS = {
+        title: "RuboCop's cop explanation", destructive_hint: false, idempotent_hint: true,
+        open_world_hint: false, read_only_hint: true
+      }.freeze
+
+      def initialize(config_store)
+        @config_store = config_store
+      end
+
+      # The tool's block does not run in this instance, so it reaches
+      # `explain` through a method object it closes over.
+      def to_tool
+        explain = method(:explain)
+
+        ::MCP::Tool.define(
+          name: 'rubocop_explain',
+          description: DESCRIPTION,
+          input_schema: INPUT_SCHEMA,
+          annotations: ANNOTATIONS
+        ) do |cop_names:, path: nil|
+          ::MCP::Tool::Response.new([{ type: 'text', text: explain.call(cop_names, path) }])
+        rescue RuboCop::Error => e
+          ::MCP::Tool::Response.new([{ type: 'text', text: e.message }], error: true)
+        end
+      end
+
+      private
+
+      # Explains the cops it recognizes and then names the ones it does not, as
+      # `--explain` does, so a typo does not cost the explanations asked for
+      # alongside it. The configuration is loaded first, since that is what
+      # registers the cops of any plugins it names.
+      def explain(cop_names, path)
+        config = path ? @config_store.for_file(path) : @config_store.for_pwd
+        explanations = known_cop_classes(cop_names).map do |cop_class|
+          Cop::CopExplanation.new(cop_class, config).to_s
+        end
+        validate_cop_names!(cop_names)
+
+        explanations.join("\n\n")
+      rescue IncorrectCopNameError => e
+        raise RuboCop::Error, [*explanations, e.message].join("\n\n")
+      end
+    end
+  end
+end

data/lib/rubocop/mcp/scope.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module MCP
+    # What a request asks RuboCop to look at: which cops run, as `--only` and
+    # `--except` choose them, and, when checking files, whether to stick to the
+    # ones git says changed, as `--changed` does.
+    # @api private
+    class Scope
+      PROPERTIES = {
+        only: {
+          type: 'array', items: { type: 'string' },
+          description: 'Run only these cops or departments, ' \
+                       'such as `Style/StringLiterals` or `Lint`.'
+        },
+        except: {
+          type: 'array', items: { type: 'string' },
+          description: 'Run every cop except these cops or departments.'
+        },
+        changed: {
+          type: %w[boolean string],
+          description: 'Check only the files git says changed: `true` for changes since the ' \
+                       'last commit, or a revision to compare against, such as `main`.'
+        }
+      }.freeze
+
+      # An empty list would select no cops at all rather than leave the choice
+      # alone, so it counts as no list.
+      #
+      # @raise [RuboCop::Error] for a scope the command line would refuse
+      def initialize(inline:, only: nil, except: nil, changed: nil)
+        @only = only if only&.any?
+        @except = except if except&.any?
+        @changed = changed == true ? ChangedFiles::DEFAULT_REVISION : changed
+        validate(inline)
+      end
+
+      # @return [Hash] the cop selection, among the options the LSP runtime takes
+      def cop_options
+        { only: @only, except: @except }.compact
+      end
+
+      def select_files(files)
+        @changed ? ChangedFiles.new(@changed).filter(files) : files
+      end
+
+      private
+
+      # Refuses what the command line refuses for the same options. Cop names
+      # are left to the runner, which checks them the way `--only` does: short
+      # names allowed, and only once the configuration naming a plugin's cops
+      # has been loaded.
+      def validate(inline)
+        raise Error, '`changed` only applies when checking files.' if inline && @changed
+        raise Error, '`changed` takes `true` or a git revision.' if @changed == ''
+
+        validator = OptionsValidator.new(cop_options)
+        if validator.only_includes_redundant_disable?
+          raise Error, 'Lint/RedundantCopDisableDirective cannot be used with `only`.'
+        end
+        raise Error, 'Syntax checking cannot be turned off.' if validator.except_syntax?
+      end
+    end
+  end
+end

data/lib/rubocop/mcp/server.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+begin
+  require 'mcp'
+
+  required_mcp_version = '0.6.0'
+
+  if Gem::Version.new(required_mcp_version) > Gem::Version.new(MCP::VERSION)
+    # While `mcp` is not a runtime dependency, users may have an outdated version installed.
+    warn <<~MESSAGE
+      Error: `mcp` gem version #{MCP::VERSION} was loaded, but `rubocop --mcp` requires #{required_mcp_version}.
+      - If you're using Bundler and don't yet have `gem 'mcp'` as a dependency, add it now.
+      - If you're using Bundler and already have `gem 'mcp'` as a dependency, update it to the most recent version.
+      - If you don't use Bundler, run `gem update mcp`.
+    MESSAGE
+    exit!
+  end
+rescue LoadError => e
+  raise unless e.path == 'mcp'
+
+  warn <<~MESSAGE
+    Error: Unable to load `mcp` gem. Add `gem 'mcp'` to your Gemfile, or run `gem install mcp`.
+  MESSAGE
+
+  exit!
+end
+
+require_relative '../lsp'
+require_relative '../lsp/runtime'
+require_relative 'autocorrection_request'
+require_relative 'explain_tool'
+require_relative 'scope'
+require_relative 'source_files'
+
+module RuboCop
+  module MCP
+    # RuboCop MCP Server.
+    # @api private
+    class Server
+      INSPECTION_DESCRIPTION =
+        'Inspect Ruby code for offenses. ' \
+        'Provide `source_code` to check inline code or `path` to check files. ' \
+        'Either way the result lists offenses per file, with a summary, and the ' \
+        'offenses use the `rubocop --format json` format, with 1-based lines. ' \
+        '`correctable` says whether `rubocop_autocorrection` fixes an offense, ' \
+        'and one whose `correction` is not `safe` needs `safety` set to false. ' \
+        'One with a `correction` that is not `correctable` is held back while code is ' \
+        'being written, and only fixed with `contextual` set to true. ' \
+        '`max_offenses_per_cop` caps what each cop reports, and the ' \
+        'summary\'s `unreported_offenses` counts what was left out. ' \
+        'A cop that crashes is listed in its file\'s `errors`; the rest still report.'
+
+      AUTOCORRECTION_DESCRIPTION =
+        'Autocorrect RuboCop offenses in Ruby code. ' \
+        'Provide `source_code` to correct inline code, which comes back corrected as ' \
+        'plain text, or `path` to correct files. ' \
+        'Set `safety` to false to include unsafe corrections, and `contextual` to true ' \
+        'to include the ones held back while code is being written, such as removing ' \
+        'an unused variable. ' \
+        'Set `dry_run` to true to preview: nothing is written, and each corrected file ' \
+        'comes with its `diff`. ' \
+        'For files, the result lists each file that was corrected or still has offenses, ' \
+        'with the offenses left in the `rubocop_inspection` format, located in the ' \
+        'corrected file. One whose `correction` is not `safe` needs `safety` set to false, ' \
+        'and one with a `correction` that is not `correctable` needs `contextual` set to ' \
+        'true. Each cop lists at most `max_offenses_per_cop` of them, 5 unless ' \
+        'set, and the summary\'s `unreported_offenses` counts the rest. ' \
+        'A cop that crashes is listed in its file\'s `errors`, and a file whose ' \
+        'corrections loop is left unchanged.'
+
+      def initialize(config_store)
+        @config_store = config_store
+        # An agent isn't an editor, so offenses are located and worded the way
+        # the command line does it. Only contextual corrections are held back.
+        @runtime = RuboCop::LSP::Runtime.new(@config_store, lsp_mode: false)
+        # One cop crashing on one file should not cost an agent everything else
+        # in the request, so cop errors are collected and reported per file.
+        @runtime.raise_cop_error = false
+        @options = {}
+        # Offenses are reported the way `--format json` reports them, so an agent
+        # sees the same 1-based locations and correction data either way.
+        @json_formatter = RuboCop::Formatter::JSONFormatter.new(nil)
+      end
+
+      def start
+        # No `protocol_version` is specified because draft feature by default can be used.
+        server = ::MCP::Server.new(
+          name: 'rubocop_mcp_server',
+          version: RuboCop::Version::STRING,
+          tools: [inspection_tool, autocorrection_tool, ExplainTool.new(@config_store).to_tool]
+        )
+
+        ::MCP::Server::Transports::StdioTransport.new(server).open
+      end
+
+      private
+
+      def inspection_tool
+        build_tool(
+          name: 'rubocop_inspection',
+          description: INSPECTION_DESCRIPTION,
+          title: "RuboCop's inspection",
+          destructive_hint: false,
+          idempotent_hint: true,
+          read_only_hint: true,
+          properties: { max_offenses_per_cop: { type: 'integer', minimum: 1 } }
+        ) do |scope:, path: nil, source_code: nil, max_offenses_per_cop: nil|
+          run_inspection(path, source_code, max_offenses_per_cop, scope)
+        end
+      end
+
+      def autocorrection_tool
+        build_tool(
+          name: 'rubocop_autocorrection',
+          description: AUTOCORRECTION_DESCRIPTION,
+          title: "RuboCop's autocorrection",
+          destructive_hint: true,
+          idempotent_hint: false,
+          read_only_hint: false,
+          properties: AutocorrectionRequest::PROPERTIES,
+          required: ['safety']
+        ) do |scope:, path: nil, source_code: nil, **arguments|
+          run_autocorrection(path, source_code, AutocorrectionRequest.new(scope, **arguments))
+        end
+      end
+
+      # A limit counts across the files of one request, so every request starts
+      # from zero.
+      def run_inspection(path, source_code, max_offenses_per_cop, scope)
+        limit = OffenseLimit.new(max_offenses_per_cop) if max_offenses_per_cop
+        result =
+          if source_code
+            file = path || 'example.rb'
+            build_result([file], [inspect_source(file, source_code, limit, scope)])
+          else
+            process_files(path, scope) { |file, src| inspect_source(file, src, limit, scope) }
+          end
+        result_json(result, limit)
+      end
+
+      def inspect_source(file, source, limit, scope)
+        options = { **scope.cop_options, editing: true }
+        offenses = @runtime.raw_offenses(file, source, options: options)
+        offense_entry(file, offenses, limit).merge(problems_of_last_run(file))
+      end
+
+      # The offenses of a file the way `--format json` lists them, capped across
+      # the files of a request.
+      def offense_entry(file, offenses, limit)
+        offenses = limit.filter(offenses) if limit
+        @json_formatter.hash_for_file(file, offenses)
+      end
+
+      def run_autocorrection(path, source_code, request)
+        return correct_inline(path, source_code, request) if source_code
+
+        result = process_files(path, request.scope) do |file, source|
+          correct_file(file, source, request)
+        end
+        result[:summary][:corrected_file_count] = result[:files].count { |file| file[:corrected] }
+        result_json(result, request.limit)
+      end
+
+      # The agent never sees stderr, so the summary says what the limit left out.
+      def result_json(result, limit)
+        unreported = limit&.elided_per_cop
+        result[:summary][:unreported_offenses] = unreported if unreported&.any?
+        result.to_json
+      end
+
+      # Cops that keep undoing each other's corrections leave the file half
+      # corrected, so it is left alone and the loop is reported instead. A file
+      # with nothing to correct is left alone too, so its modification time
+      # doesn't tell editors and agents it changed. The offenses left over are
+      # the ones an agent has to fix itself, which saves it inspecting again.
+      def correct_file(file, source, request)
+        corrected = @runtime.format(file, source, **request.format_options)
+        problems = problems_of_last_run(file)
+        looped = @runtime.errors.any?(Runner::InfiniteCorrectionLoop)
+        changed = !looped && source != corrected
+        leftovers = leftover_offenses(file, source, corrected, changed, request)
+        entry = offense_entry(file, leftovers, request.limit)
+        diff = write_or_diff(file, entry[:path], source, corrected, request) if changed
+
+        { path: entry[:path], corrected: changed, diff: diff, **entry, **problems }.compact
+      end
+
+      # A dry run writes nothing and returns the diff a real run would have
+      # applied, line endings included.
+      def write_or_diff(file, path, source, corrected, request)
+        if request.dry_run?
+          UnifiedDiff.new(path, source, Util.emulate_write_read_cycle(corrected)).to_s
+        else
+          SourceFiles.write(file, corrected)
+          nil
+        end
+      end
+
+      # What's left is in the file as written, or as a dry run would have
+      # written it, or as it was when its corrections loop. The runner checks
+      # corrected code with LF line endings, which writing turns into CRLF on
+      # Windows, so there the file is checked again as written.
+      def leftover_offenses(file, source, corrected, changed, request)
+        on_disk = changed ? Util.emulate_write_read_cycle(corrected) : source
+        return @runtime.uncorrected_offenses if on_disk == corrected
+
+        @runtime.raw_offenses(file, on_disk, options: request.runtime_options)
+      end
+
+      # Corrected inline code comes back as plain text with nowhere to mention
+      # a cop that crashed, so a crash fails the call instead of going unseen.
+      def correct_inline(path, source_code, request)
+        file = path || 'example.rb'
+        corrected = @runtime.format(file, source_code, **request.format_options)
+        errors = problems_of_last_run(file)[:errors]
+        raise RuboCop::Error, errors.join("\n") if errors
+
+        SourceFiles.write(path, corrected) if path && !request.dry_run?
+        corrected
+      end
+
+      # Collapsed the way `--format json` collapses them, which also folds the
+      # repeats from each autocorrection pass a crashing cop fails on.
+      def problems_of_last_run(file)
+        errors, warnings = [@runtime.errors, @runtime.warnings].map do |problems|
+          problems.map { |problem| Rainbow::StringUtils.uncolor(problem.to_s) }
+        end
+        @json_formatter.hash_for_problems(file, errors, warnings)
+      end
+
+      def process_files(path, scope)
+        target_finder = RuboCop::TargetFinder.new(@config_store, @options)
+        target_files = scope.select_files(
+          target_finder.find(path ? [path] : [], :only_recognized_file_types)
+        )
+        all_files = target_files.map do |file|
+          yield(file, SourceFiles.read(file, @config_store.for_file(file)))
+        end
+
+        build_result(target_files, all_files)
+      end
+
+      # Inline code is reported as a single file, so an agent reads one shape
+      # whichever way it asked. Files with nothing to report are only counted.
+      def build_result(target_files, all_files)
+        files = all_files.reject { |f| nothing_to_report?(f) }
+
+        { files: files, summary: build_summary(target_files, all_files) }
+      end
+
+      def nothing_to_report?(file)
+        file[:offenses].empty? && !file[:corrected] && !file[:errors] && !file[:warnings]
+      end
+
+      # NOTE: It is useful for RuboCop's result summary to be shown in the LLM's responses
+      # during interactions, so the summary is returned in a form that is easy for the LLM
+      # to reason about. Since LLM execution is non-deterministic, it is also sensible to
+      # compute the summary deterministically at this stage.
+      def build_summary(target_files, files)
+        offense_count = files.sum { |f| f[:offenses].size }
+        { target_file_count: target_files.count, offense_count: offense_count }
+          .merge(@json_formatter.problem_counts(files))
+      end
+
+      # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists
+      def build_tool(
+        name:, description:,
+        title:, destructive_hint:, idempotent_hint:, read_only_hint:, properties:, required: nil
+      )
+        ::MCP::Tool.define(
+          name: name,
+          description: description,
+          input_schema: {
+            properties: {
+              path: { type: 'string' },
+              source_code: { type: 'string' }
+            }.merge(properties, Scope::PROPERTIES),
+            required: required,
+            # The gem checks arguments against the schema, so one the tool
+            # doesn't take is refused by name rather than failing the call.
+            additionalProperties: false
+          }.compact,
+          annotations: {
+            title: title,
+            destructive_hint: destructive_hint,
+            idempotent_hint: idempotent_hint,
+            open_world_hint: false,
+            read_only_hint: read_only_hint
+          }
+        ) do |**arguments|
+          # Taking any keywords makes the gem pass a `server_context` as well.
+          # Each tool's own block names the arguments it accepts.
+          arguments.delete(:server_context)
+          selection = Scope::PROPERTIES.keys.to_h { |key| [key, arguments.delete(key)] }
+          scope = Scope.new(inline: !arguments[:source_code].nil?, **selection)
+          result = yield(**arguments, scope: scope)
+
+          ::MCP::Tool::Response.new([{ type: 'text', text: result }])
+        rescue RuboCop::Error, IncorrectCopNameError => e
+          # The runner raises `IncorrectCopNameError` for a name in `only` or
+          # `except` that it does not know, with suggestions.
+          ::MCP::Tool::Response.new([{ type: 'text', text: e.message }], error: true)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/mcp/source_files.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module MCP
+    # Reads and writes the files the tools work on. A file that can't be read
+    # or written fails the request with an error the agent can act on.
+    # @api private
+    module SourceFiles
+      module_function
+
+      def read(file, config)
+        RuboCop::ProcessedSource.from_file(
+          file, config.target_ruby_version, parser_engine: config.parser_engine
+        ).raw_source
+      rescue Errno::ENOENT
+        raise RuboCop::Error, "No such file or directory: #{file}"
+      end
+
+      # Writing what a file already holds would only bump its modification time.
+      def write(file, content)
+        return if File.file?(file) && File.binread(file) == content.b
+
+        Util.replace_file_contents(file, content)
+      rescue Errno::EACCES
+        raise RuboCop::Error, "Permission denied: #{file}"
+      rescue Errno::EPERM
+        raise RuboCop::Error, "Operation not permitted: #{file}"
+      rescue Errno::ENOSPC
+        raise RuboCop::Error, "No space left on device: #{file}"
+      rescue Errno::EROFS
+        raise RuboCop::Error, "Read-only file system: #{file}"
+      end
+    end
+  end
+end

data/lib/rubocop/offense_limit.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RuboCop
+  # Caps how many offenses each cop gets to report.
+  #
+  # Counted across a whole run rather than per file, since a cop that fires a
+  # handful of times in every file is exactly the one worth capping. Offenses
+  # have to be offered in a stable order (files in the order they are
+  # reported) for the same ones to survive every time.
+  # @api private
+  class OffenseLimit
+    attr_reader :max
+
+    def initialize(max)
+      @max = max
+      @offered = Hash.new(0)
+    end
+
+    # @return [Array<Cop::Offense>] the offenses still within their cop's limit
+    def filter(offenses)
+      offenses.select { |offense| (@offered[offense.cop_name] += 1) <= @max }
+    end
+
+    # @return [Hash{String => Integer}] how many offenses each cop had left out,
+    #   sorted by cop name
+    def elided_per_cop
+      @offered.filter_map { |cop, count| [cop, count - @max] if count > @max }.sort.to_h
+    end
+  end
+end