fastererer 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de024ad42cbd1fb10608607fd4b8f4bbe0c6ff58414f001fea232aee478d2c40
-  data.tar.gz: 2c2722e7fedbe2d4d8542b41db6ad37d61020bea79b5e437305651549cb8c6d5
+  metadata.gz: ba7c93c8bf5af26d77535e03595b6e56720bd31f865d23714a36e02f27c21a1a
+  data.tar.gz: 6eedb452c7ec6ac71ff7c9b145060cdccf9a5ab7b6837ad2797e02705fc15957
 SHA512:
-  metadata.gz: c67fad403a643c864bc7989ca2bb0346802c143baef0bf5bd211a6b6a294abf81dcea1d031a8cf9adca452ee3d83cf58dc75f04297b2ab05fb87c23cfa73cd01
-  data.tar.gz: f034537ef76b425c479ff9dff2304859f869543f7bddad5c2596baa68d4d39525584b65f8c132ca7bc7918049408951c2f02446ae8181929e0c6b4f42695043f
+  metadata.gz: 62425177d92da9debe1b47babac4f1a634633a6e67c4665c0ed65093932515a35547e067c9f72a60b9abe674c2af367a23bf86204ff994adb6906762075461bd
+  data.tar.gz: 30a136f9742eefbd5c1499c4dae8c4d92e64541984f7caed36386e2aecda9b0a90ef1acbbd0c9c0fc5c98f9b4bb653cf685e2049ed76850f7b49f25446c7d6c7

data/CHANGELOG.md

@@ -4,10 +4,45 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog] and this project adheres to [Semantic Versioning].
 
-Versions 0.11.0 and earlier were released as [`fasterer`](https://github.com/DamirSvrtan/fasterer), prior to the fork. From 0.12.0 onward, this is `fastererer`, maintained by ExtractableMedia.
+Versions 0.11.0 and earlier were released as [`fasterer`](https://github.com/DamirSvrtan/fasterer),
+prior to the fork. From 0.12.0 onward, this is `fastererer`, maintained by ExtractableMedia.
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-04
+
+### Added
+
+- [#40]: A `-f`/`--format` flag with machine-readable output formats alongside the default `text`:
+  `json` (one document with a run `summary` and a flat `offenses` array) and `rdjsonl` (the
+  reviewdog Diagnostic Format, one record per offense, ready to pipe into reviewdog for inline PR
+  comments). Machine formats write only their payload to stdout and route diagnostics to stderr.
+
+### Changed
+
+- [#77]: Parse errors and the "No such file or directory" message now go to STDERR instead of
+  STDOUT. STDOUT carries only offense lines and the statistics line, so it can be piped, grepped or
+  redirected on its own.
+- [#84]: A path that does not exist now exits with status `2` instead of `0`. Status `1` still
+  means "offenses were found", so a CI job or wrapper script can tell a mistyped path from a real
+  finding. The exit codes are documented in the README.
+
+### Fixed
+
+- [#77]: The "N offenses detected" statistics line no longer counts offenses suppressed by
+  `speedups: <rule>: false` in `.fastererer.yml`. The total previously included suppressed
+  offenses, so it could exceed the number of offense lines printed; the two now agree.
+- [#84]: An unknown flag now prints its message and exits `2` instead of dumping a Ruby backtrace
+  and exiting `1`. Exiting `1` made a mistyped flag indistinguishable from a real finding.
+- [#84]: A directory whose name contains glob metacharacters (`pkg[1]`, `a{b}`) is now scanned.
+  The name was interpolated into the glob pattern, so such a directory silently reported
+  `0 files inspected` and exited `0`. Passing an absolute directory path no longer raises
+  `ArgumentError` either.
+- [#84]: A missing path no longer reports a clean scan. `fastererer no_such_path` printed
+  `1 file inspected, 0 offenses detected` and exited `0`, so a renamed or mistyped directory in CI
+  stopped linting while the build stayed green. The statistics line now reads
+  `0 files inspected, 0 offenses detected` and the run fails.
+
 ## [1.0.0] - 2026-06-05
 
 First stable release of `fastererer` after the fork.
@@ -136,7 +171,8 @@ First stable release of `fastererer` after the fork.
 
 [Keep a Changelog]: https://keepachangelog.com
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
-[Unreleased]: https://github.com/ExtractableMedia/fastererer/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/ExtractableMedia/fastererer/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/ExtractableMedia/fastererer/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/ExtractableMedia/fastererer/compare/v0.12.0...v1.0.0
 [0.12.0]: https://github.com/ExtractableMedia/fastererer/compare/v0.11.0...v0.12.0
 [#1]: https://github.com/ExtractableMedia/fastererer/pull/1
@@ -144,4 +180,7 @@ First stable release of `fastererer` after the fork.
 [#9]: https://github.com/ExtractableMedia/fastererer/pull/9
 [#15]: https://github.com/ExtractableMedia/fastererer/pull/15
 [#28]: https://github.com/ExtractableMedia/fastererer/issues/28
+[#40]: https://github.com/ExtractableMedia/fastererer/issues/40
 [#42]: https://github.com/ExtractableMedia/fastererer/pull/42
+[#77]: https://github.com/ExtractableMedia/fastererer/issues/77
+[#84]: https://github.com/ExtractableMedia/fastererer/pull/84

data/README.md

@@ -49,7 +49,8 @@ bundle exec fastererer app/models
 bundle exec fastererer app/models/post.rb
 ```
 
-Fastererer exits with status `1` when offenses are found, making it suitable for CI.
+Fastererer exits with status `1` when offenses are found and `2` when the path it was given does not
+exist, making it suitable for CI. See [Exit codes](#exit-codes).
 
 ## Example output
 
@@ -75,6 +76,53 @@ underlying snake_case rule key (e.g. `select_first_vs_detect`), which is what
 you reference in `.fastererer.yml` under `speedups:` to disable a rule.
 Descriptions and documentation URLs live in `config/locales/en.yml`.
 
+## Output formats
+
+By default fastererer prints the human-readable text shown above. Pass `-f`/`--format` to emit
+machine-readable output for editors, log aggregators, or CI reporters instead:
+
+```shell
+fastererer --format=json      # single JSON document, includes a run summary
+fastererer --format=rdjsonl   # reviewdog JSON Lines, one record per offense
+fastererer --format=text      # the default
+```
+
+Machine formats write only their payload to stdout; diagnostics (parse errors, a missing path)
+go to stderr, so `fastererer --format=json > findings.json` captures clean JSON. An unrecognized
+format name is a usage error: the name is reported on stderr and fastererer exits `2` without
+scanning.
+
+`--format=json` produces one document with a `summary` of run counts and a flat `offenses` array
+(each offense carries `path`, `line`, `rule`, `rule_key`, `message`, and `url`). `rule` is the
+display name; `rule_key` is the identifier to write under `speedups:` in `.fastererer.yml`, so a
+consumer can offer to silence a rule without guessing at the name:
+
+```json
+{
+  "metadata": { "fastererer_version": "1.0.0" },
+  "summary": { "offense_count": 1, "inspected_file_count": 12, "unparsable_file_count": 0 },
+  "offenses": [
+    {
+      "path": "app/models/post.rb",
+      "line": 57,
+      "rule": "Performance/SelectFirstVsDetect",
+      "rule_key": "select_first_vs_detect",
+      "message": "Array#select.first is slower than Array#detect",
+      "url": "https://github.com/fastruby/fast-ruby#enumerabledetect-vs-enumerableselectfirst-code"
+    }
+  ]
+}
+```
+
+`--format=rdjsonl` follows the [reviewdog Diagnostic Format][rdf], one JSON object per line, ready
+to pipe straight into reviewdog (see [CI integration](#ci-integration)). `code.value` carries the
+rule key rather than the display name, because reviewdog renders it into the pull request comment
+and the key is the name a reader can act on — the one to add under `speedups:` in `.fastererer.yml`:
+
+```json
+{"message":"Array#select.first is slower than Array#detect","location":{"path":"app/models/post.rb","range":{"start":{"line":57}}},"severity":"WARNING","code":{"value":"select_first_vs_detect","url":"https://github.com/fastruby/fast-ruby#enumerabledetect-vs-enumerableselectfirst-code"}}
+```
+
 ## Configuration
 
 Configuration lives in a `.fastererer.yml` file at the root of your project (or any ancestor
@@ -122,6 +170,38 @@ step:
   run: bundle exec fastererer
 ```
 
+### Exit codes
+
+| Status | Meaning |
+| ------ | ------- |
+| `0` | The scan completed and no offenses were found |
+| `1` | The scan completed and offenses were found |
+| `2` | Usage error — an unknown flag or format, or a path that does not exist, so nothing was scanned |
+
+Status `2` is kept distinct from `1` so a wrapper script can tell "the tool ran and found problems"
+from "you invoked me wrong". A renamed directory, a mistyped flag or an unknown `--format` value
+fails the build instead of reporting a clean scan.
+
+### Inline PR comments with reviewdog
+
+The `rdjsonl` format is consumed natively by [reviewdog](https://github.com/reviewdog/reviewdog),
+which can post findings as inline GitHub PR review comments:
+
+```shell
+bundle exec fastererer --format=rdjsonl \
+  | reviewdog -f=rdjsonl -name=fastererer -filter-mode=nofilter -reporter=github-pr-review
+```
+
+`-filter-mode=nofilter` reports every finding, not only those on lines the pull request touched,
+which is what reviewdog does by default. Findings outside the diff cannot be posted as inline
+review comments — GitHub's review API does not allow it — so reviewdog falls back to check
+annotations for those. `-name=fastererer` attributes the comments, since the rdjsonl record carries
+no tool name of its own. `-reporter=github-pr-review` needs `pull-requests: write`.
+
+Run fastererer from the repository root and let the path default to `.`. reviewdog matches findings
+against the pull request by repository-relative path, so passing an absolute directory emits
+absolute paths that will not match — and puts the runner's directory layout in a public comment.
+
 Color output is auto-disabled when STDOUT isn't a TTY, when `NO_COLOR` is set (see
 [no-color.org](https://no-color.org/)), or when `--no-color` is passed — so CI logs, piped output
 (`fastererer | grep`), and editor integrations get plain text without configuration.
@@ -173,5 +253,6 @@ for the idiom catalog that drives the speed checks.
 [fasterer]: https://github.com/DamirSvrtan/fasterer
 [issues]: https://github.com/ExtractableMedia/fastererer/issues
 [prism]: https://github.com/ruby/prism
+[rdf]: https://github.com/reviewdog/reviewdog/tree/master/proto/rdf
 [roadmap-project]: https://github.com/orgs/ExtractableMedia/projects/1
 [sferik-talk]: https://speakerdeck.com/sferik/writing-fast-ruby

data/lib/fastererer/analyzer.rb

@@ -8,8 +8,9 @@ require 'fastererer/offense'
 require 'fastererer/offense_collector'
 require 'fastererer/parser'
 require 'fastererer/scanners/method_call_scanner'
-require 'fastererer/scanners/rescue_call_scanner'
 require 'fastererer/scanners/method_definition_scanner'
+require 'fastererer/scanners/for_loop_scanner'
+require 'fastererer/scanners/rescue_call_scanner'
 
 module Fastererer
   class Analyzer
@@ -48,7 +49,7 @@ module Fastererer
     end
 
     def visit_for_node(node)
-      @offenses.push(Fastererer::Offense.new(:for_loop_vs_each, node.location.start_line))
+      collect(ForLoopScanner.new(node))
       super
     end
 

data/lib/fastererer/cli.rb

@@ -2,17 +2,31 @@
 
 require 'optparse'
 require_relative 'file_traverser'
+require_relative 'formatters'
 require_relative 'painter'
 require_relative 'version'
 
 module Fastererer
   class CLI
-    def self.execute
+    OFFENSES_FOUND_STATUS = 1
+    USAGE_ERROR_STATUS = 2
+
+    def self.execute(out: $stdout, err: $stderr)
       options = parse_options(ARGV.dup)
+      formatter = Formatters.fetch(options[:format] || 'text').new(out:, err:)
+    rescue UnknownFormatError, OptionParser::ParseError => e
+      err.puts(e.message)
+      exit USAGE_ERROR_STATUS
+    else
       Painter.disable! if options[:no_color]
-      file_traverser = Fastererer::FileTraverser.new(options[:path])
+      file_traverser = FileTraverser.new(options[:path], formatter:)
       file_traverser.traverse
-      abort if file_traverser.offenses_found?
+      exit_with_status_for(file_traverser)
+    end
+
+    def self.exit_with_status_for(file_traverser)
+      exit USAGE_ERROR_STATUS if file_traverser.path_missing?
+      exit OFFENSES_FOUND_STATUS if file_traverser.offenses_found?
     end
 
     def self.parse_options(argv)
@@ -24,6 +38,9 @@ module Fastererer
     def self.build_parser(options)
       OptionParser.new do |opts|
         opts.banner = 'Usage: fastererer [options] [path]'
+        opts.on('-f', '--format FORMAT', 'Output format: text (default), json, rdjsonl') do |format|
+          options[:format] = format
+        end
         opts.on('--no-color', 'Disable ANSI color in output') { options[:no_color] = true }
         opts.on('-h', '--help', 'Show this help') { show_help_and_exit(opts) }
         opts.on('-v', '--version', 'Show version') { show_version_and_exit }
@@ -36,7 +53,7 @@ module Fastererer
     end
 
     def self.show_version_and_exit
-      puts Fastererer::VERSION
+      puts VERSION
       exit
     end
   end

data/lib/fastererer/explanation.rb

@@ -10,6 +10,10 @@ module Fastererer
       @instances[offense_name.to_sym] ||= new(offense_name)
     end
 
+    def self.format_line(source)
+      "#{source.rule_name}: #{source.description.delete_suffix('.')}. (#{source.url})"
+    end
+
     attr_reader :offense_name
 
     def initialize(offense_name)
@@ -30,7 +34,7 @@ module Fastererer
     end
 
     def to_s
-      "#{rule_name}: #{description.delete_suffix('.')}. (#{url})"
+      self.class.format_line(self)
     end
 
     private

data/lib/fastererer/file_traverser.rb

@@ -5,8 +5,9 @@ require 'English'
 
 require_relative 'analyzer'
 require_relative 'config'
-require_relative 'explanation'
-require_relative 'painter'
+require_relative 'finding'
+require_relative 'report'
+require_relative 'formatters/text_formatter'
 
 module Fastererer
   class FileTraverser
@@ -15,19 +16,17 @@ module Fastererer
     EXCLUDE_PATHS_KEY = Config::EXCLUDE_PATHS_KEY
 
     attr_reader :config, :parse_error_paths
-    attr_accessor :offenses_total_count
 
-    def initialize(path)
+    def initialize(path, formatter: Formatters::TextFormatter.new)
       @path = Pathname(path || '.')
       @parse_error_paths = []
       @config = Config.new
-      @offenses_total_count = 0
+      @formatter = formatter
+      @findings = []
     end
 
     def traverse
-      traverse_files
-      output_parse_errors
-      output_statistics
+      @formatter.render(build_report)
     end
 
     def config_file
@@ -35,7 +34,13 @@ module Fastererer
     end
 
     def offenses_found?
-      !!offenses_found
+      findings.any?
+    end
+
+    def path_missing?
+      return @path_missing if defined?(@path_missing)
+
+      @path_missing = !@path.exist?
     end
 
     def scannable_files
@@ -44,83 +49,53 @@ module Fastererer
 
     private
 
-    attr_accessor :offenses_found
+    attr_reader :findings
 
-    def traverse_files
-      if @path.exist?
-        scannable_files.each { |ruby_file| scan_file(ruby_file) }
-      else
-        output_unable_to_find_file(@path)
-      end
+    def build_report
+      scan_files
+
+      Report.new(
+        findings:,
+        files_inspected_count: scannable_files.count,
+        unparsable_files: parse_error_paths,
+        missing_path: (@path.to_s if path_missing?)
+      )
+    end
+
+    def scan_files
+      scannable_files.each { |ruby_file| scan_file(ruby_file) }
     end
 
     def scan_file(path)
       analyzer = Analyzer.new(path)
       analyzer.scan
     rescue Fastererer::ParseError, SystemCallError, SystemStackError, EncodingError => e
-      parse_error_paths.push(ErrorData.new(path, e.class, e.message).to_s)
+      parse_error_paths.push(ErrorData.new(path, e.class, e.message))
     else
-      if offenses_grouped_by_type(analyzer).any?
-        output(analyzer)
-        self.offenses_found = true
-        self.offenses_total_count += analyzer.errors.count
-      end
+      collect_findings(analyzer)
     end
 
-    def all_files
-      if @path.directory?
-        Dir[File.join(@path, '**', '*.rb')].map do |ruby_file_path|
-          Pathname(ruby_file_path).relative_path_from(root_dir).to_s
-        end
-      else
-        [@path.to_s]
+    def collect_findings(analyzer)
+      reported_offenses(analyzer).each do |offense|
+        findings.push(Finding.from(offense, analyzer.file_path))
       end
     end
 
-    def root_dir
-      @root_dir ||= Pathname('.')
-    end
-
-    def output(analyzer)
-      offenses_grouped_by_type(analyzer).each_value do |error_occurrences|
-        explanation = error_occurrences.first.explanation
-
-        error_occurrences.map(&:line_number).each do |line|
-          file_and_line = "#{analyzer.file_path}:#{line}"
-          print "#{Painter.paint(file_and_line, :red)}: #{severity}: #{explanation}\n"
-        end
-      end
-
-      print "\n"
+    def reported_offenses(analyzer)
+      ignored = ignored_speedups
+      analyzer.errors.reject { |offense| ignored.include?(offense.name) }
     end
 
-    def severity
-      @severity ||= Painter.paint('W', :magenta)
-    end
+    def all_files
+      return [] if path_missing?
+      return [@path.to_s] unless @path.directory?
 
-    def offenses_grouped_by_type(analyzer)
-      analyzer.errors.group_by(&:name).delete_if do |offense_name, _|
-        ignored_speedups.include?(offense_name)
+      # base: takes the directory literally; interpolating it would read [ ] { } * ? as pattern
+      Dir.glob('**/*.rb', base: @path.to_s).map do |relative_path|
+        Pathname(File.join(@path, relative_path)).cleanpath.to_s
       end
     end
 
-    def output_parse_errors
-      return if parse_error_paths.none?
-
-      puts 'Fastererer was unable to process some files. Unprocessable files were:'
-      puts '-----------------------------------------------------'
-      puts parse_error_paths
-      puts
-    end
-
-    def output_statistics
-      puts Statistics.new(self)
-    end
-
-    def output_unable_to_find_file(path)
-      puts Painter.paint("No such file or directory - #{path}", :red)
-    end
-
     def ignored_speedups
       config.ignored_speedups
     end
@@ -139,53 +114,4 @@ module Fastererer
       "#{file_path} - #{error_class} - #{error_message}"
     end
   end
-
-  class Statistics
-    def initialize(traverser)
-      @files_inspected_count  = traverser.scannable_files.count
-      @offenses_found_count   = traverser.offenses_total_count
-      @unparsable_files_count = traverser.parse_error_paths.count
-    end
-
-    def to_s
-      [
-        inspected_files_output,
-        offenses_found_output,
-        unparsable_files_output
-      ].compact.join(', ')
-    end
-
-    def inspected_files_output
-      Painter.paint(
-        "#{@files_inspected_count} #{pluralize(@files_inspected_count, 'file')} inspected", :green
-      )
-    end
-
-    def offenses_found_output
-      color = @offenses_found_count.zero? ? :green : :red
-
-      Painter.paint(
-        "#{@offenses_found_count} #{pluralize(@offenses_found_count, 'offense')} detected", color
-      )
-    end
-
-    def unparsable_files_output
-      return if @unparsable_files_count.zero?
-
-      Painter.paint(
-        "#{@unparsable_files_count} unparsable #{pluralize(@unparsable_files_count, 'file')} found",
-        :red
-      )
-    end
-
-    def pluralize(count, singular, plural = nil)
-      if count == 1
-        singular.to_s
-      elsif plural
-        plural.to_s
-      else
-        "#{singular}s"
-      end
-    end
-  end
 end

data/lib/fastererer/finding.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Fastererer
+  Finding = Data.define(:path, :line, :rule_key, :rule_name, :description, :url) do
+    def self.from(offense, path)
+      explanation = offense.explanation
+
+      new(
+        path: path.to_s.scrub,
+        line: offense.line_number,
+        rule_key: offense.name.to_s,
+        rule_name: explanation.rule_name,
+        description: explanation.description,
+        url: explanation.url
+      )
+    end
+  end
+end

data/lib/fastererer/formatters/base.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Fastererer
+  module Formatters
+    class Base
+      # The gap at \x09 keeps tabs, which are printable, out of the escaping
+      UNSAFE_CHARS = /[\x00-\x08\x0A-\x1F\x7F]/
+      private_constant :UNSAFE_CHARS
+
+      def initialize(out: $stdout, err: $stderr)
+        @out = out
+        @err = err
+      end
+
+      private
+
+      attr_reader :out, :err
+
+      # Undecorated on purpose for the machine formats; TextFormatter overrides with color
+      def output_diagnostics(report)
+        missing_path = report.missing_path
+
+        err.puts("No such file or directory - #{sanitize(missing_path)}") if missing_path
+        report.unparsable_files.each { |unparsable_file| err.puts(sanitize(unparsable_file.to_s)) }
+      end
+
+      def sanitize(text)
+        text.to_s.scrub.gsub(UNSAFE_CHARS) { |char| format('\\x%02X', char.ord) }
+      end
+    end
+  end
+end

data/lib/fastererer/formatters/json_formatter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base'
+require_relative '../version'
+
+module Fastererer
+  module Formatters
+    # Diagnostics go to stderr so stdout carries nothing but the JSON document
+    class JsonFormatter < Base
+      def render(report)
+        output_diagnostics(report)
+        out.puts JSON.pretty_generate(document(report))
+      end
+
+      private
+
+      def document(report)
+        {
+          'metadata' => { 'fastererer_version' => Fastererer::VERSION },
+          'summary' => summary(report),
+          'offenses' => offenses(report)
+        }
+      end
+
+      def summary(report)
+        {
+          'offense_count' => report.offenses_detected_count,
+          'inspected_file_count' => report.files_inspected_count,
+          'unparsable_file_count' => report.unparsable_files.count
+        }
+      end
+
+      def offenses(report)
+        report.findings.sort_by { |finding| [finding.path, finding.line] }.map do |finding|
+          {
+            'path' => finding.path,
+            'line' => finding.line,
+            'rule' => finding.rule_name,
+            'rule_key' => finding.rule_key,
+            'message' => finding.description,
+            'url' => finding.url
+          }
+        end
+      end
+    end
+  end
+end

data/lib/fastererer/formatters/rdjsonl_formatter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base'
+
+module Fastererer
+  module Formatters
+    # Shape is pinned to reviewdog's Diagnostic schema: WARNING severity, start-only range
+    # code.value is the rule key, not the display name — the reader pastes it into .fastererer.yml
+    class RdjsonlFormatter < Base
+      SEVERITY = 'WARNING'
+      private_constant :SEVERITY
+
+      def render(report)
+        output_diagnostics(report)
+        report.findings.each { |finding| out.puts JSON.generate(diagnostic(finding)) }
+      end
+
+      private
+
+      def diagnostic(finding)
+        {
+          'message' => finding.description,
+          'location' => {
+            'path' => finding.path,
+            'range' => { 'start' => { 'line' => finding.line } }
+          },
+          'severity' => SEVERITY,
+          'code' => { 'value' => finding.rule_key, 'url' => finding.url }
+        }
+      end
+    end
+  end
+end

data/lib/fastererer/formatters/text_formatter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../painter'
+require_relative 'text_statistics'
+require_relative '../explanation'
+
+module Fastererer
+  module Formatters
+    class TextFormatter < Base
+      def render(report)
+        output_offenses(report)
+        output_diagnostics(report)
+        output_statistics(report)
+      end
+
+      private
+
+      def output_offenses(report)
+        report.findings.group_by(&:path).each_value do |path_findings|
+          path_findings.group_by(&:rule_name).each_value { |group| output_group(group) }
+          out.puts
+        end
+      end
+
+      def output_group(group)
+        group.each do |finding|
+          location = Painter.paint("#{sanitize(finding.path)}:#{finding.line}", :red)
+          out.puts "#{location}: #{severity}: #{Explanation.format_line(finding)}"
+        end
+      end
+
+      def output_diagnostics(report)
+        output_missing_path(report)
+        output_parse_errors(report)
+      end
+
+      def output_missing_path(report)
+        return unless report.missing_path
+
+        message = "No such file or directory - #{sanitize(report.missing_path)}"
+        err.puts Painter.paint(message, :red)
+      end
+
+      def output_parse_errors(report)
+        return if report.unparsable_files.none?
+
+        err.puts 'Fastererer was unable to process some files. Unprocessable files were:'
+        err.puts '-----------------------------------------------------'
+        report.unparsable_files.each { |unparsable_file| err.puts sanitize(unparsable_file.to_s) }
+        err.puts
+      end
+
+      def output_statistics(report)
+        out.puts TextStatistics.new(report)
+      end
+
+      def severity
+        @severity ||= Painter.paint('W', :magenta)
+      end
+    end
+  end
+end

data/lib/fastererer/formatters/text_statistics.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative '../painter'
+
+module Fastererer
+  module Formatters
+    class TextStatistics
+      def initialize(report)
+        @files_inspected_count   = report.files_inspected_count
+        @offenses_detected_count = report.offenses_detected_count
+        @unparsable_files_count  = report.unparsable_files.count
+      end
+
+      def to_s
+        [inspected_files_output, offenses_detected_output, unparsable_files_output]
+          .compact.join(', ')
+      end
+
+      def inspected_files_output
+        count = @files_inspected_count
+
+        Painter.paint("#{count} #{pluralize(count, 'file')} inspected", :green)
+      end
+
+      def offenses_detected_output
+        count = @offenses_detected_count
+        color = count.zero? ? :green : :red
+
+        Painter.paint("#{count} #{pluralize(count, 'offense')} detected", color)
+      end
+
+      def unparsable_files_output
+        return if @unparsable_files_count.zero?
+
+        count = @unparsable_files_count
+
+        Painter.paint("#{count} unparsable #{pluralize(count, 'file')} found", :red)
+      end
+
+      def pluralize(count, singular)
+        count == 1 ? singular : "#{singular}s"
+      end
+    end
+  end
+end

data/lib/fastererer/formatters.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'formatters/text_formatter'
+require_relative 'formatters/json_formatter'
+require_relative 'formatters/rdjsonl_formatter'
+
+module Fastererer
+  class UnknownFormatError < StandardError; end
+
+  module Formatters
+    FORMATS = {
+      'text' => TextFormatter,
+      'json' => JsonFormatter,
+      'rdjsonl' => RdjsonlFormatter
+    }.freeze
+
+    def self.fetch(name)
+      FORMATS.fetch(name) do
+        raise UnknownFormatError,
+              "Unknown format: #{name.inspect}. Valid formats: #{FORMATS.keys.join(', ')}."
+      end
+    end
+  end
+end

data/lib/fastererer/method_call.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require 'prism'
+require 'fastererer/receiver'
 
 module Fastererer
   class MethodCall
+    include Receiver
+
     attr_reader :element
 
     def self.build(node)
@@ -26,6 +29,8 @@ module Fastererer
       method_name
     end
 
+    def call_name = method_name
+
     def arguments
       @arguments ||= argument_nodes.map { |argument| Argument.new(argument) }
     end
@@ -75,7 +80,7 @@ module Fastererer
     end
 
     # Only single positional params convert to &:sym, so a splat or keyword param must not count
-    # toward block_argument_names.one?
+    # toward the single-name check
     def positional_block_parameter_names
       return [] unless block_node.is_a?(Prism::BlockNode)
 
@@ -130,16 +135,13 @@ module Fastererer
   end
 
   class VariableReference
+    include Receiver
+
     attr_reader :name
 
     def initialize(node)
       @name = node.name
     end
-
-    # A bare local/constant reference can't be proven to hold a Hash
-    def hash?
-      false
-    end
   end
 
   class Argument
@@ -180,6 +182,8 @@ module Fastererer
   end
 
   class Primitive
+    include Receiver
+
     attr_reader :element
 
     def initialize(node)

data/lib/fastererer/offense_collector.rb

@@ -14,6 +14,6 @@ module Fastererer
       @offenses.select { |offense| offense.name == offense_name }
     end
 
-    def_delegators :@offenses, :push, :any?, :each, :group_by, :count
+    def_delegators :@offenses, :push, :any?, :each, :group_by, :count, :reject
   end
 end

data/lib/fastererer/receiver.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Fastererer
+  # Query surface every receiver answers; includers override only what is true for their type
+  module Receiver
+    def call_name = nil
+    def name = nil
+    def block? = false
+    def arguments = []
+    def range? = false
+    def array? = false
+    def hash? = false
+  end
+end

data/lib/fastererer/report.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Fastererer
+  # Findings arrive already filtered by ignored speedups; formatters must not filter again
+  Report = Data.define(:findings, :files_inspected_count, :unparsable_files, :missing_path) do
+    def offenses_detected_count
+      findings.count
+    end
+  end
+end

data/lib/fastererer/rule_catalog.rb

@@ -8,6 +8,8 @@ module Fastererer
   # Loads, validates, memoizes and looks up the rule catalog from the i18n locale.
   module RuleCatalog
     LOCALE_PATH = File.expand_path('../../config/locales/en.yml', __dir__)
+    KEY_SHAPE = /\A[a-z0-9_]+\z/
+    private_constant :KEY_SHAPE
 
     class << self
       def all
@@ -48,6 +50,9 @@ module Fastererer
 
       def validate_row!(key, row)
         raise "Fastererer rule #{key} is malformed: #{row.inspect}" unless row.is_a?(Hash)
+        unless key.is_a?(String) && key.match?(KEY_SHAPE)
+          raise "Fastererer rule #{key.inspect} is not a snake_case key"
+        end
 
         validate_url!(key, row['url'])
         validate_description!(key, row['description'])

data/lib/fastererer/scanners/for_loop_scanner.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'fastererer/offense'
+require 'fastererer/scanners/offensive'
+
+module Fastererer
+  class ForLoopScanner
+    include Fastererer::Offensive
+
+    attr_reader :element
+
+    def initialize(element)
+      @element = element
+      check_offense
+    end
+
+    private
+
+    def check_offense
+      add_offense(:for_loop_vs_each) # for is always slower than each, so no guard
+    end
+  end
+end

data/lib/fastererer/scanners/method_call_scanner.rb

@@ -75,9 +75,7 @@ module Fastererer
     end
 
     def check_first_offense
-      return unless method_call.receiver.is_a?(MethodCall)
-
-      case method_call.receiver.name
+      case method_call.receiver&.call_name
       when :shuffle
         add_offense(:shuffle_first_vs_sample)
       when :select
@@ -89,9 +87,7 @@ module Fastererer
     end
 
     def check_each_offense
-      return unless method_call.receiver.is_a?(MethodCall)
-
-      case method_call.receiver.name
+      case method_call.receiver&.call_name
       when :reverse
         add_offense(:reverse_each_vs_reverse_each)
       when :keys
@@ -100,8 +96,7 @@ module Fastererer
     end
 
     def check_flatten_offense
-      return unless method_call.receiver.is_a?(MethodCall)
-      return unless method_call.receiver.name == :map && method_call.arguments.one?
+      return unless method_call.receiver&.call_name == :map && method_call.arguments.one?
 
       add_offense(:map_flatten_vs_flat_map) if method_call.arguments.first.value == 1
     end
@@ -127,17 +122,14 @@ module Fastererer
     end
 
     def check_last_offense
-      return unless method_call.receiver.is_a?(MethodCall)
-      return unless method_call.receiver.name == :select
+      return unless method_call.receiver&.call_name == :select
       return if method_call.arguments.any?
 
       add_offense(:select_last_vs_reverse_detect)
     end
 
     def check_range_include_offense
-      return unless method_call.receiver.is_a?(Primitive) && method_call.receiver.range?
-
-      add_offense(:include_vs_cover_on_range)
+      add_offense(:include_vs_cover_on_range) if method_call.receiver&.range?
     end
   end
 end

data/lib/fastererer/scanners/symbol_to_proc_check.rb

@@ -19,12 +19,18 @@ module Fastererer
     end
 
     def symbol_to_proc_candidate?
-      method_call.block_argument_names.one? &&
+      single_block_argument_name &&
         single_call_body? &&
         method_call.arguments.none? &&
         !method_call.lambda_literal?
     end
 
+    # A destructured param has no name, so |(a, b), c| must not read as a single-name block
+    def single_block_argument_name
+      names = method_call.block_argument_names
+      names.first if names.size == 1
+    end
+
     # A safe-nav body (foo&.bar) is excluded: arr.map(&:bar) raises on a nil element, so the rewrite
     # would not preserve behavior
     def single_call_body?
@@ -32,12 +38,11 @@ module Fastererer
       body&.size == 1 && body.first.is_a?(Prism::CallNode) && !body.first.safe_navigation?
     end
 
+    # A primitive receiver's name is nil, which never matches the named param the gate requires
     def symbol_to_proc_body?(body_call)
       body_call.arguments.none? &&
         !body_call.block? &&
-        !body_call.receiver.nil? &&
-        !body_call.receiver.is_a?(Fastererer::Primitive) &&
-        body_call.receiver.name == method_call.block_argument_names.first
+        body_call.receiver&.name == single_block_argument_name
     end
   end
 end

data/lib/fastererer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fastererer
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fastererer
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Matt Menefee
@@ -46,15 +46,25 @@ files:
 - lib/fastererer/config.rb
 - lib/fastererer/explanation.rb
 - lib/fastererer/file_traverser.rb
+- lib/fastererer/finding.rb
+- lib/fastererer/formatters.rb
+- lib/fastererer/formatters/base.rb
+- lib/fastererer/formatters/json_formatter.rb
+- lib/fastererer/formatters/rdjsonl_formatter.rb
+- lib/fastererer/formatters/text_formatter.rb
+- lib/fastererer/formatters/text_statistics.rb
 - lib/fastererer/method_call.rb
 - lib/fastererer/method_definition.rb
 - lib/fastererer/offense.rb
 - lib/fastererer/offense_collector.rb
 - lib/fastererer/painter.rb
 - lib/fastererer/parser.rb
+- lib/fastererer/receiver.rb
+- lib/fastererer/report.rb
 - lib/fastererer/rescue_call.rb
 - lib/fastererer/rule_catalog.rb
 - lib/fastererer/rule_name.rb
+- lib/fastererer/scanners/for_loop_scanner.rb
 - lib/fastererer/scanners/method_call_scanner.rb
 - lib/fastererer/scanners/method_definition_scanner.rb
 - lib/fastererer/scanners/offensive.rb
@@ -84,7 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Run Ruby more than fast. Fastererer
 test_files: []