fastererer 0.12.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee0a8fc9f430360ccef546a4f391fdb3112801f6fb2c56204900f0dca8214063
-  data.tar.gz: a477c6a7b4b9f19011ea89bee00aa193d562f91981dd38e5136cd88fd7ebca14
+  metadata.gz: ba7c93c8bf5af26d77535e03595b6e56720bd31f865d23714a36e02f27c21a1a
+  data.tar.gz: 6eedb452c7ec6ac71ff7c9b145060cdccf9a5ab7b6837ad2797e02705fc15957
 SHA512:
-  metadata.gz: 4d239a4233228c45cc0c0ea28ef00110a8d2ea6476c258ef8f68d3f5b443a66cc48724f47529bb6eb787857843a3c7a4d84aed4aeda09c3a2266880c65ccb14a
-  data.tar.gz: 6ac88eca14ca854edc0e549b4ddbd6cd9b39796fb9658c10e3c16399b65a7341cea039c0d18fbb9e243406fe8503072ec25ba1a9671dba35d77f0549995bc7ea
+  metadata.gz: 62425177d92da9debe1b47babac4f1a634633a6e67c4665c0ed65093932515a35547e067c9f72a60b9abe674c2af367a23bf86204ff994adb6906762075461bd
+  data.tar.gz: 30a136f9742eefbd5c1499c4dae8c4d92e64541984f7caed36386e2aecda9b0a90ef1acbbd0c9c0fc5c98f9b4bb653cf685e2049ed76850f7b49f25446c7d6c7

data/CHANGELOG.md

@@ -4,10 +4,75 @@ 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.
+
+### Changed
+
+- [#9]: Migrate from `ruby_parser` to Ruby's native Prism parser. Prism ships with Ruby itself,
+  so this drops the `ruby_parser`, `sexp_processor`, and `racc` dependencies and keeps the
+  analyzer in step with current and future Ruby syntax, including Ruby 4.0.
+
+### Added
+
+- [#9]: Detect speedups reached through a safe-navigation chain (e.g. `arr&.first`,
+  `arr&.select { … }.first`), which the previous S-expression scanner skipped.
+- [#9]: Detect speedups inside `rescue` bodies — getter-vs-`attr_reader`,
+  setter-vs-`attr_writer`, and proc-call-vs-`yield` offenses are now scanned in rescue clauses.
+- [#15]: Offense output now mirrors RuboCop's format with a `Performance/RuleName` rule name and a
+  [fast-ruby](https://github.com/fastruby/fast-ruby) documentation link, e.g.
+  `path:line: W: Performance/ForLoopVsEach: For loop is slower than using each. (url)`.
+
+### Fixed
+
+- [#9]: Block calls inside a nested scope (a singleton class or a nested method definition) are
+  no longer misattributed to the enclosing method.
+- [#9]: Unparseable source now raises a clear error instead of silently reporting no offenses.
+- [#28]: `hash_merge_bang_vs_hash_brackets` now flags `Hash#update`, an alias of `Hash#merge!`, but
+  only when the receiver is provably a Hash (a `{}` literal, `Hash.new`, or `Hash[...]`). Because
+  `update` is also defined on `ActiveRecord`, `ActionController::Parameters`, and others, a bare
+  `obj.update(k => v)` is left untouched to avoid false positives.
+
 ## [0.12.0] - 2026-05-18
 
 ### Added
@@ -106,8 +171,16 @@ Versions 0.11.0 and earlier were released as [`fasterer`](https://github.com/Dam
 
 [Keep a Changelog]: https://keepachangelog.com
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
-[Unreleased]: https://github.com/ExtractableMedia/fastererer/compare/v0.12.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
 [#2]: https://github.com/ExtractableMedia/fastererer/pull/2
+[#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,22 +49,78 @@ 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
 
+Each offense is reported on a single line, following the same shape as
+RuboCop and its plugins (`path:line: SEVERITY: Department/RuleName: message.
+(url)`), so the rule name and a link to documentation are always visible:
+
 ```text
-app/models/post.rb:57 Array#select.first is slower than Array#detect.
-app/models/post.rb:61 Array#select.first is slower than Array#detect.
+app/models/post.rb:57: W: Performance/SelectFirstVsDetect: Array#select.first is slower than Array#detect. (https://github.com/fastruby/fast-ruby#enumerabledetect-vs-enumerableselectfirst-code)
+app/models/post.rb:61: W: Performance/SelectFirstVsDetect: Array#select.first is slower than Array#detect. (https://github.com/fastruby/fast-ruby#enumerabledetect-vs-enumerableselectfirst-code)
+
+db/seeds/cities.rb:15: W: Performance/KeysEachVsEachKey: Hash#keys.each is slower than Hash#each_key. N.B. Hash#each_key cannot be used if the hash is modified during the each block. (https://github.com/fastruby/fast-ruby#hasheach_key-instead-of-hashkeyseach-code)
+
+test/options_test.rb:84: W: Performance/HashMergeBangVsHashBrackets: Hash#merge! with one argument is slower than Hash#[]. (https://github.com/fastruby/fast-ruby#hashmerge-vs-hash-code)
+
+test/module_test.rb:272: W: Performance/RescueVsRespondTo: Don't rescue NoMethodError, rather check with respond_to?. (https://github.com/fastruby/fast-ruby#beginrescue-vs-respond_to-for-control-flow-code)
+
+spec/cache/mem_cache_store_spec.rb:161: W: Performance/GsubVsTr: Using tr is faster than gsub when replacing a single character in a string with another single character. (https://github.com/fastruby/fast-ruby#stringgsub-vs-stringtr-code)
+```
 
-db/seeds/cities.rb:15 Hash#keys.each is slower than Hash#each_key.
-db/seeds/cities.rb:33 Hash#keys.each is slower than Hash#each_key.
+The rule name (e.g. `Performance/SelectFirstVsDetect`) is derived from the
+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
+```
 
-test/options_test.rb:84 Hash#merge! with one argument is slower than Hash#[].
+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"
+    }
+  ]
+}
+```
 
-test/module_test.rb:272 Don't rescue NoMethodError, rather check with respond_to?.
+`--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`:
 
-spec/cache/mem_cache_store_spec.rb:161 Using tr is faster than gsub when replacing a single character in a string with another single character.
+```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
@@ -114,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.
@@ -165,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/config/locales/en.yml

@@ -0,0 +1,60 @@
+en:
+  fastererer:
+    rules:
+      rescue_vs_respond_to:
+        description: "Don't rescue NoMethodError, rather check with respond_to?"
+        url: "https://github.com/fastruby/fast-ruby#beginrescue-vs-respond_to-for-control-flow-code"
+      module_eval:
+        description: "Using module_eval is slower than define_method"
+        url: "https://github.com/fastruby/fast-ruby#define_method-vs-module_eval-for-defining-methods-code"
+      shuffle_first_vs_sample:
+        description: "Array#shuffle.first is slower than Array#sample"
+        url: "https://github.com/fastruby/fast-ruby#arrayshufflefirst-vs-arraysample-code"
+      for_loop_vs_each:
+        description: "For loop is slower than using each"
+        url: "https://github.com/fastruby/fast-ruby#enumerableeach-vs-for-loop-code"
+      each_with_index_vs_while:
+        description: "Using each_with_index is slower than while loop"
+        url: "https://github.com/fastruby/fast-ruby#enumerableeach_with_index-vs-while-loop-code"
+      map_flatten_vs_flat_map:
+        description: "Array#map.flatten(1) is slower than Array#flat_map"
+        url: "https://github.com/fastruby/fast-ruby#enumerablemaparrayflatten-vs-enumerableflat_map-code"
+      reverse_each_vs_reverse_each:
+        description: "Array#reverse.each is slower than Array#reverse_each"
+        url: "https://github.com/fastruby/fast-ruby#enumerablereverseeach-vs-enumerablereverse_each-code"
+      select_first_vs_detect:
+        description: "Array#select.first is slower than Array#detect"
+        url: "https://github.com/fastruby/fast-ruby#enumerabledetect-vs-enumerableselectfirst-code"
+      sort_vs_sort_by:
+        description: "Enumerable#sort is slower than Enumerable#sort_by"
+        url: "https://github.com/fastruby/fast-ruby#enumerablesort-vs-enumerablesort_by-code"
+      fetch_with_argument_vs_block:
+        description: "Hash#fetch with second argument is slower than Hash#fetch with block"
+        url: "https://github.com/fastruby/fast-ruby#hashfetch-with-argument-vs-hashfetch--block-code"
+      keys_each_vs_each_key:
+        description: "Hash#keys.each is slower than Hash#each_key. N.B. Hash#each_key cannot be used if the hash is modified during the each block"
+        url: "https://github.com/fastruby/fast-ruby#hasheach_key-instead-of-hashkeyseach-code"
+      hash_merge_bang_vs_hash_brackets:
+        description: "Hash#merge!/#update with one argument is slower than Hash#[]"
+        url: "https://github.com/fastruby/fast-ruby#hashmerge-vs-hash-code"
+      block_vs_symbol_to_proc:
+        description: "Calling argumentless methods within blocks is slower than using symbol to proc"
+        url: "https://github.com/fastruby/fast-ruby#block-vs-symbolto_proc-code"
+      proc_call_vs_yield:
+        description: "Calling blocks with call is slower than yielding"
+        url: "https://github.com/fastruby/fast-ruby#proccall-and-block-arguments-vs-yield-code"
+      gsub_vs_tr:
+        description: "Using tr is faster than gsub when replacing a single character in a string with another single character"
+        url: "https://github.com/fastruby/fast-ruby#stringgsub-vs-stringtr-code"
+      select_last_vs_reverse_detect:
+        description: "Array#select.last is slower than Array#reverse.detect"
+        url: "https://github.com/fastruby/fast-ruby#enumerableselectlast-vs-enumerablereversedetect-code"
+      getter_vs_attr_reader:
+        description: "Use attr_reader for reading ivars"
+        url: "https://github.com/fastruby/fast-ruby#attr_accessor-vs-getter-and-setter-code"
+      setter_vs_attr_writer:
+        description: "Use attr_writer for writing to ivars"
+        url: "https://github.com/fastruby/fast-ruby#attr_accessor-vs-getter-and-setter-code"
+      include_vs_cover_on_range:
+        description: "Use #cover? instead of #include? on ranges"
+        url: "https://github.com/fastruby/fast-ruby#cover-vs-include-code"

data/lib/fastererer/analyzer.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
+require 'prism'
 require 'fastererer/method_definition'
 require 'fastererer/method_call'
 require 'fastererer/rescue_call'
+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
@@ -20,75 +23,47 @@ module Fastererer
     end
 
     def scan
-      sexp_tree = Fastererer::Parser.parse(@file_content)
-      traverse_sexp_tree(sexp_tree)
+      root_node = Fastererer::Parser.parse(@file_content)
+      root_node.accept(AnalyzerVisitor.new(errors))
     end
 
     def errors
       @errors ||= Fastererer::OffenseCollector.new
     end
+  end
 
-    private
-
-    def traverse_sexp_tree(sexp_tree)
-      return unless sexp_tree.is_a?(Sexp)
-
-      token = sexp_tree.first
-      scan_by_token(token, sexp_tree)
-
-      if %i[call iter].include?(token)
-        descend_into_call(sexp_tree)
-      else
-        sexp_tree.each { |element| traverse_sexp_tree(element) }
-      end
-    end
-
-    def descend_into_call(sexp_tree)
-      method_call = MethodCall.new(sexp_tree)
-      traverse_sexp_tree(method_call.receiver_element) if method_call.receiver_element
-      traverse_sexp_tree(method_call.arguments_element)
-      traverse_sexp_tree(method_call.block_body) if method_call.block?
+  class AnalyzerVisitor < Prism::Visitor
+    def initialize(offenses)
+      super()
+      @offenses = offenses
     end
 
-    def scan_by_token(token, element)
-      case token
-      when :defn
-        scan_method_definitions(element)
-      when :call, :iter
-        scan_method_calls(element)
-      when :for
-        scan_for_loop(element)
-      when :resbody
-        scan_rescue(element)
-      end
+    def visit_call_node(node)
+      collect(MethodCallScanner.new(node))
+      super
     end
 
-    def scan_method_definitions(element)
-      method_definition_scanner = MethodDefinitionScanner.new(element)
-
-      return unless method_definition_scanner.offense_detected?
-
-      errors.push(method_definition_scanner.offense)
+    def visit_def_node(node)
+      collect(MethodDefinitionScanner.new(node))
+      super
     end
 
-    def scan_method_calls(element)
-      method_call_scanner = MethodCallScanner.new(element)
-
-      return unless method_call_scanner.offense_detected?
-
-      errors.push(method_call_scanner.offense)
+    def visit_for_node(node)
+      collect(ForLoopScanner.new(node))
+      super
     end
 
-    def scan_for_loop(element)
-      errors.push(Fastererer::Offense.new(:for_loop_vs_each, element.line))
+    def visit_rescue_node(node)
+      collect(RescueCallScanner.new(node))
+      super
     end
 
-    def scan_rescue(element)
-      rescue_call_scanner = RescueCallScanner.new(element)
-
-      return unless rescue_call_scanner.offense_detected?
+    private
 
-      errors.push(rescue_call_scanner.offense)
+    def collect(scanner)
+      @offenses.push(scanner.offense) if scanner.offense_detected?
     end
   end
+
+  private_constant :AnalyzerVisitor
 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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'rule_catalog'
+require_relative 'rule_name'
+
+module Fastererer
+  class Explanation
+    def self.for(offense_name)
+      @instances ||= {}
+      @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)
+      @offense_name = offense_name.to_sym
+      @row = RuleCatalog.fetch(@offense_name)
+    end
+
+    def description
+      row.fetch('description')
+    end
+
+    def url
+      row.fetch('url')
+    end
+
+    def rule_name
+      @rule_name ||= RuleName.from(offense_name)
+    end
+
+    def to_s
+      self.class.format_line(self)
+    end
+
+    private
+
+    attr_reader :row
+  end
+end