Custom cop for detecting abbreviations in variables/class names/etc

abbreviation cop README.md

This is a custom Rubocop cop to detect abbreviations in the names of classes, methods, variables, and constants. It does this by taking each definition, splitting it up into individual words, and running it through a spellchecker. The english spellchecker is from ffi-aspell and the ruby and html dictionaries are from spellr. As a nice side-effect, this helps us to avoid misspellings in our names.

Note that spellr and ffi-aspell are required for this, but could be swapped out or removed if desired. Small editing will be needed to remove them from abbreviations.rb.

Note that this doesn't care about using the abbreviations, only defining them. So for example, these will receive a warning:

• abc_thing = ...
• class AbcThing
• ABC_CONST = ...
• def abc_code

but these will not:

• abc_thing(code: abc)
• AbcCode.call
• list.include?(ABC_CONST)

Most repos use a bunch of words that are not in any dictionary but are nonetheless valid. These words can be added in the configuration for the cop which looks like:

require:
  - ./path/to/abbreviations.rb

CustomCops/Abbreviations:
  AllowedWords:
    - cancellable
  QuestionableWords:
    - aad
  AllowedFileWords:
    - path: Gemfile
      words:
        - repo

AllowedWords

These words are we expect to not be in the dictionary but are valid words. Example: arel, stubber, dnd

QuestionableWords

These are words that should likely be removed, fixed, or that are actually valid but you might not know. The goal would be to remove this section entirely over time. It's here now because it allows for increment fixes. Examples: foo, pll, authoized (misspelling of authorized),

AllowedFileWords

In some cases, we want to only allow the word in a single file because they are required by some external API or for whatever reason they're okay in one place but not another. Examples: config in this custom cop because cop_config is a RuboCop value, repo in the Gemfile.

How to try this out

You can run this cop on the whole codebase or a single file:

bin/rubocop --only CustomCops/Abbreviations path/to/abbreviations.rb

References used:

• https://thoughtbot.com/blog/rubocop-custom-cops-for-custom-needs
• https://docs.rubocop.org/rubocop/development.html
• https://github.com/rubocop/rubocop-rails
• https://whitequark.github.io/ast/
• https://www.rubydoc.info/gems/rubocop/
• https://www.rubydoc.info/gems/rubocop-ast/

abbreviations.rb

require "active_support"
require_relative "../../config/initializers/inflections"
require "ffi/aspell"
require "spellr"

module CustomCops
  class Abbreviations < RuboCop::Cop::Base
    NON_LETTERS = /[^a-z]+/
    ABLE_SUFFIX = /able$/

    def check_token(token, node)
      offenses = collect_offenses(token.to_s)
      if offenses.any?
        message = "Please avoid the abbreviation(s): #{offenses.join(", ")}"
        add_offense(node.loc.name, message: message)
      end
    end

    def on_def(node)
      check_token(node.method_name, node)
    end

    def on_class(node)
      check_token(node.children.first.const_name, node)
    end

    def on_casgn(node)
      check_token(node.name, node)
    end

    def on_lvasgn(node)
      check_token(node.name, node)
    end

    def on_investigation_end
      speller.close
    end

    private

    def collect_offenses(token)
      words_from_token(token).select do |word|
        !defined_word?(word) && !allowed?(word, processed_source.file_path)
      end
    end

    def words_from_token(token)
      token.titleize.downcase.split(NON_LETTERS)
    end

    def defined_word?(word)
      speller.correct?(word) ||
        speller.correct?(word.sub(ABLE_SUFFIX, "")) ||
        ruby_words.include?(word).present? ||
        html_words.include?(word).present?
    end

    def allowed?(word, path)
      allowed_word?(word) ||
        questionable_word?(word) ||
        allowed_file_word?(word, path) ||
        active_support_abbreviation?(word)
    end

    def allowed_word?(word)
      case_insensitive_include?(cop_config["AllowedWords"], word)
    end

    def questionable_word?(word)
      case_insensitive_include?(cop_config["QuestionableWords"], word)
    end

    def allowed_file_word?(word, path)
      relative_path = Pathname.new(path).relative_path_from(Dir.pwd).to_s
      file_config = cop_config["AllowedFileWords"]
        .find { |allow| allow["path"] == relative_path }

      file_config.present? &&
        case_insensitive_include?(file_config["words"], word)
    end

    def active_support_abbreviation?(word)
      @acronyms ||= ActiveSupport::Inflector.inflections.acronyms.keys
      case_insensitive_include?(@acronyms, word)
    end

    def speller
      @speller ||= FFI::Aspell::Speller.new("en_US")
    end

    def ruby_words
      @ruby_words ||= begin
        ruby_list = get_spellr_wordlist("ruby")
        Spellr::Wordlist.new(ruby_list)
      end
    end

    def html_words
      @html_words ||= begin
        html_list = get_spellr_wordlist("html")
        Spellr::Wordlist.new(html_list)
      end
    end

    def get_spellr_wordlist(list_name)
      spellr_path = Gem::Specification.find_by_name("spellr").full_gem_path
      Pathname.new(spellr_path).join("wordlists", "#{list_name}.txt")
    end

    def case_insensitive_include?(array, string)
      array.any? { |s| s.casecmp(string).zero? }
    end
  end
end