inclusive-code 0.1.0 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 495cf47e5d18f5dad603026d5314bdfeeaeae01a045884444e2eb6316fc1ae68
-  data.tar.gz: 774b4de9e09abae3ec9c80373a9a6d3af1f63593df0ddd18a4922ad2deb92c46
+  metadata.gz: 7fc5f8f716dd932818068d5b282bc52d1f7e93ad38eec1f16e100076347c42f8
+  data.tar.gz: 372a8b68115654589caf6ec9a6c03e94c96d5f2cced613065c15b0454214076a
 SHA512:
-  metadata.gz: c6cf747c66926af9c1bc9d6c7fcdc0cf52ee3ee9b3c20c17238989a5a2983c569bea8929dfcade6cf5f60333fb604a5a6ff961e8abc7d9b842c0692e4d07e281
-  data.tar.gz: e850f2f2cfae0a2ece5efd6368c8d8e45a3f31544aff933b4fccd802bcbb4bce420854472dc83c609c01aeaa6b1c8fc0a43060ebb52fa9a1af34897fc40aec88
+  metadata.gz: 6781133cb6fad6ef8bb373de9d7359a0d121901f58863adcf5f0498c0550059af3b3b6787cab808ca104392ef790e22e6fe4529805362c5c0c3c5332269004d5
+  data.tar.gz: aa2a97adf00529dbdf3fb6f525aaaa994e7988fe0242d47aeb934cd063fc448e0c8723ee22f91da792727c914b68b6fbbea78142fe271641e3242818450d64da

data/README.md

@@ -1 +1,120 @@
-## TODO: add usage instructions for rubocop gem
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'inclusive-code'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install inclusive-code
+
+## Usage
+Configure your own set of flagged terms following the structure of the `inclusive_code_flagged_terms.yml` file at the top level of this repo. We recommend storing it in `'app/constants/inclusive_code/inclusive_code_flagged_terms.yml'`.
+
+Put this into your .rubocop.yml:
+
+```yaml
+require:
+  - inclusive-code
+
+Flexport/InclusiveCode:
+  Enabled: true
+  GlobalConfigPath: 'app/constants/inclusive_code/inclusive_code_flagged_terms.yml' # or your path
+  DisableAutoCorrect: false
+```
+
+You can run the cop on your entire codebase with `rubocop --only Flexport/InclusiveCode`.
+
+You can run the cop on a specific file with `rubocop --only Flexport/InclusiveCode file_path`.
+
+If you want to add inline `rubocop:disable` or `rubocop:todo` comments on all offenses, set `DisableAutoCorrect: true` in your .rubocop.yml, and run `rubocop --only Flexport/InclusiveCode --auto-correct --disable-uncorrectable`.
+
+## Configuration
+
+The inclusive-code gem includes an initial configuration to get your project started. You can customize this configuration to fit your needs.
+
+### Flagging harmful terms
+
+Rules are added under the key `flagged_term` as follows:
+
+```yaml
+---
+flagged_terms:
+  some_harmful_term: {}
+```
+
+### Specifying harmful terminology
+
+You can specify harmful terminology using basic keys (`another_harmful_term:`), string keys (`" his ":`), or using [regular expressions](https://rubular.com/r/HvcomHUBZ3KFCz) like `"white[-_\\s]*list":`. Please note that when specifying a regular expression, some characters (`\`) may need to be escaped. Examples:
+
+```yaml
+---
+flagged_terms:
+  "white[-_\\s]*list": {}
+  "black[-_\\s]*list": {}
+  " him ": {}
+  master: {}
+```
+
+### Suggestions and Autocorrect
+
+In a document titled [Terminology, Power and Offensive Language](https://tools.ietf.org/id/draft-knodel-terminology-01.html), the Internet Engineering Task Force (IETF) recommends that an editor or reviewer *should* "offer alternatives for offensive terminology as an important act of correcting larger editorial issues and clarifying technical concepts."
+
+As this gem does some of the work of an editor or reviewer, it is appropriate that it should allow for communicating better alternatives when it finds harmful technology.
+
+Here's how you can offer alternative suggestions:
+
+```yaml
+---
+flagged_terms:
+  some_harmful_term:
+    suggestions:
+      - some_thoughtful_alternative
+      - some_other_thoughtful_alternative
+```
+
+When using autocorrect, the first item in the suggestions array will be used as the autocorrect term.
+
+### Allowing exceptions
+
+This gem supports two ways to specify exceptions to your rules: allowing specific terms, allowing specific files.
+
+#### Allowing specific terms
+
+You might want to do this to allow for an [Industry Term Exception](../README.md#industry-term-exemption). Here's how to allow certain terms using the `allowed:` key:
+
+```yaml
+---
+flagged_terms:
+  master:
+    suggestions:
+      - main
+    allowed:
+      - master bill
+      - master air waybill
+      - master consol
+      - master shipment
+```
+
+#### Allowing specific files
+
+You might want to do this when you wish to disallow some term, but you need to allow it in certain files. Perhaps you rely on some library which requires you to configure it using some harmful terminology. Here's how to allow occurrences of a harmful term when they occur within some file using the `allowed_files:` key:
+
+```yaml
+---
+flagged_terms:
+  whitelist:
+    suggestions:
+      - allowlist
+    allowed_files:
+      - config/initializers/some_gem_config.rb
+      - .some_gem/*
+```
+
+This will result in allowing offenses in any files returned by `Dir.glob("{config/initializers/some_gem_config.rb,.some_gem/*}")`

data/config/default.yml

@@ -2,3 +2,5 @@ Flexport/InclusiveCode:
   Description: "Warns on usage of flagged terms, suggests alternatives and allows for exceptions as configured."
   Enabled: true
   VersionAdded: "0.1.0"
+  GlobalConfigPath: ""
+  DisableAutoCorrect: false

data/lib/inclusive-code.rb

@@ -2,10 +2,10 @@
 
 require 'rubocop'
 
-require_relative 'inclusive_code/flexport'
-require_relative 'inclusive_code/flexport/version'
-require_relative 'inclusive_code/flexport/inject'
+require_relative 'rubocop/inclusive_code'
+require_relative 'rubocop/inclusive_code/version'
+require_relative 'rubocop/inclusive_code/inject'
 
-InclusiveCode::Flexport::Inject.defaults!
+RuboCop::InclusiveCode::Inject.defaults!
 
-require_relative 'inclusive_code/cop/inclusive_code'
+require_relative 'rubocop/cop/inclusive_code'

data/lib/rubocop/cop/inclusive_code.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/string'
+
+module RuboCop
+  module Cop
+    module Flexport
+      # This cop encourages use of inclusive language to help programmers avoid
+      # using terminology that is derogatory, hurtful, or perpetuates discrimination,
+      # either directly or indirectly, in their code.
+      #
+      # @example
+      #
+      #   # bad
+      #
+      #   BLACKLIST_COUNTRIES = "blacklist_countries".freeze
+      #
+      # @example
+      #
+      #   # good
+      #
+      #   BLOCKLIST_COUNTRIES = "blocklist_countries".freeze
+      #
+      #
+      class InclusiveCode < Cop
+        include RangeHelp
+
+        SEVERITY = 'warning'
+
+        FLAG_ONLY_MSG = '🚫 Use of non_inclusive word: `%<non_inclusive_word>s`.'
+        FULL_FLAG_MSG = "#{FLAG_ONLY_MSG} Consider using these suggested alternatives: `%<suggestions>s`."
+
+        ALLOWED_TERM_MASK_CHAR = '*'.freeze
+
+        def initialize(config = nil, options = nil, source_file = nil)
+          super(config, options)
+
+          source_file ||= YAML.load_file(cop_config['GlobalConfigPath'])
+          @non_inclusive_words_alternatives_hash = source_file['flagged_terms']
+          @all_non_inclusive_words = @non_inclusive_words_alternatives_hash.keys
+          @non_inclusive_words_regex = concatenated_regex(@all_non_inclusive_words)
+          @allowed_terms = {}
+          @allowed_files = {}
+
+          @all_non_inclusive_words.each do |word|
+            @allowed_terms[word] = get_allowed_string(word)
+            @allowed_files[word] = source_file['flagged_terms'][word]['allowed_files'] || []
+          end
+          @allowed_regex = @allowed_terms.values.reject(&:blank?).join('|')
+
+          @allowed_regex = if @allowed_regex.blank?
+                             Regexp.new(/^$/)
+                           else
+                             Regexp.new(@allowed_regex, Regexp::IGNORECASE)
+                           end
+        end
+
+        def investigate(processed_source)
+          non_inclusive_words_for_current_file = @all_non_inclusive_words.reject do |non_inclusive_word|
+            Dir.glob("{#{@allowed_files[non_inclusive_word].join(',')}}").include?(processed_source.path)
+          end
+
+          processed_source.lines.each_with_index do |line, line_number|
+            next unless line.match(@non_inclusive_words_regex)
+
+            non_inclusive_words_for_current_file.each do |non_inclusive_word|
+              allowed = @allowed_terms[non_inclusive_word]
+              scan_regex = /(?=#{non_inclusive_word})/i
+              if allowed.present?
+                line = line.gsub(/(#{allowed})/i){ |match| ALLOWED_TERM_MASK_CHAR * match.size }
+              end
+              locations = line.enum_for(
+                :scan,
+                scan_regex
+              ).map { Regexp.last_match&.offset(0)&.first }
+
+              non_inclusive_words = line.scan(/#{non_inclusive_word}/i)
+
+              locations = locations.zip(non_inclusive_words).to_h
+              next if locations.blank?
+
+              locations.each do |location, word|
+                range = source_range(
+                  processed_source.buffer,
+                  line_number + 1,
+                  location,
+                  word.length
+                )
+                add_offense(
+                  range,
+                  location: range,
+                  message: create_message(word),
+                  severity: SEVERITY
+                )
+              end
+            end
+          end
+          # Also error for non-inclusive language in file names
+          path = processed_source.path
+          return if path.nil?
+
+          non_inclusive_words_match = path.match(concatenated_regex(non_inclusive_words_for_current_file))
+          return unless non_inclusive_words_match && !path.match(@allowed_regex)
+
+          range = source_range(processed_source.buffer, 1, 0)
+          add_offense(
+            range,
+            location: range,
+            message: create_message(non_inclusive_words_match[0]),
+            severity: SEVERITY
+          )
+        end
+
+        def autocorrect(arg_pair)
+          return if cop_config['DisableAutoCorrect']
+
+          word_to_correct = arg_pair.source
+          correction = correction_for_word(word_to_correct)
+          return if correction['suggestions'].blank?
+
+          corrected = correction['suggestions'][0]
+
+          # Only respects case if it is capitalized or uniform (all upper or all lower)
+          to_upcase = word_to_correct == word_to_correct.upcase
+          if to_upcase
+            corrected = corrected.upcase
+          elsif word_to_correct == word_to_correct.capitalize
+            corrected = corrected.capitalize
+          end
+
+          lambda do |corrector|
+            corrector.insert_before(arg_pair, corrected)
+            corrector.remove(arg_pair)
+          end
+        end
+
+        private
+
+        def concatenated_regex(non_inclusive_words)
+          Regexp.new(
+            non_inclusive_words.join('|'),
+            Regexp::IGNORECASE
+          )
+        end
+
+        def get_allowed_string(non_inclusive_word)
+          allowed = @non_inclusive_words_alternatives_hash[non_inclusive_word].fetch('allowed') { [] }
+          snake_case = allowed.map { |e| e.tr(' ', '_').underscore }
+          pascal_case = snake_case.map(&:camelize)
+          (allowed + snake_case + pascal_case).join('|')
+        end
+
+        def correction_for_word(word_to_correct)
+          _, correction = @non_inclusive_words_alternatives_hash.detect do |correction_key, _|
+            Regexp.new(correction_key, Regexp::IGNORECASE).match?(word_to_correct.downcase)
+          end
+
+          correction || {}
+        end
+
+        def create_message(non_inclusive_word)
+          correction = correction_for_word(non_inclusive_word)
+          suggestions = correction.fetch('suggestions') { [] }.join(', ')
+
+          format(
+            suggestions.present? ? FULL_FLAG_MSG : FLAG_ONLY_MSG,
+            non_inclusive_word: non_inclusive_word,
+            suggestions: suggestions
+          )
+        end
+      end
+    end
+  end
+end

data/lib/{inclusive_code/flexport.rb → rubocop/inclusive_code.rb}

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require 'inclusive_code/flexport/version'
+require 'rubocop/inclusive_code/version'
 
-module InclusiveCode
-  module Flexport
+module RuboCop
+  module InclusiveCode
     class Error < StandardError; end
     PROJECT_ROOT = Pathname.new(__dir__).parent.parent.expand_path.freeze
     CONFIG_DEFAULT = PROJECT_ROOT.join('config', 'default.yml').freeze
@@ -11,4 +11,4 @@ module InclusiveCode
 
     private_constant(:CONFIG_DEFAULT, :PROJECT_ROOT)
   end
-end
+end

data/lib/{inclusive_code/flexport → rubocop/inclusive_code}/inject.rb

@@ -2,8 +2,8 @@
 
 # The original code is from https://github.com/rubocop-hq/rubocop-rspec/blob/master/lib/rubocop/rspec/inject.rb
 # See https://github.com/rubocop-hq/rubocop-rspec/blob/master/MIT-LICENSE.md
-module InclusiveCode
-  module Flexport
+module RuboCop
+  module InclusiveCode
     # Because RuboCop doesn't yet support plugins, we have to monkey patch in a
     # bit of our configuration.
     module Inject
@@ -17,4 +17,4 @@ module InclusiveCode
       end
     end
   end
-end
+end

data/lib/rubocop/inclusive_code/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module InclusiveCode
+    VERSION = '0.1.5'
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: inclusive-code
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.5
 platform: ruby
 authors:
 - Flexport Engineering
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-29 00:00:00.000000000 Z
+date: 2021-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -48,14 +48,15 @@ files:
 - README.md
 - config/default.yml
 - lib/inclusive-code.rb
-- lib/inclusive_code/cop/inclusive_code.rb
-- lib/inclusive_code/flexport.rb
-- lib/inclusive_code/flexport/inject.rb
-- lib/inclusive_code/flexport/version.rb
+- lib/rubocop/cop/inclusive_code.rb
+- lib/rubocop/inclusive_code.rb
+- lib/rubocop/inclusive_code/inject.rb
+- lib/rubocop/inclusive_code/version.rb
 homepage: https://github.com/flexport/rubocop-flexport
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/flexport/inclusive-code
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -71,8 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project:
-rubygems_version: 2.7.7
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: Inclusive Language RuboCop.

data/lib/inclusive_code/cop/inclusive_code.rb

@@ -1,139 +0,0 @@
-module InclusiveCode
-  module Cop
-    module Flexport
-      # This cop encourages use of inclusive language to help programmers avoid
-      # using terminology that is derogatory, hurtful, or perpetuates discrimination,
-      # either directly or indirectly, in their code.
-      #
-      # @example
-      #
-      #   # bad
-      #
-      #   BLACKLIST_COUNTRIES = "blacklist_countries".freeze
-      #
-      # @example
-      #
-      #   # good
-      #
-      #   BLOCKLIST_COUNTRIES = "blocklist_countries".freeze
-      #
-      #
-      class InclusiveCode < Cop
-        include RangeHelp
-
-        SEVERITY = "warning".freeze
-
-        MSG = "🚫 Use of non_inclusive word: `%<non_inclusive_word>s`. Consider using these suggested alternatives: `%<suggestions>s`.".freeze
-
-        NON_INCLUSIVE_WORDS_ALTERNATIVES_HASH = YAML.load_file(global_config_path)["flagged_terms"]
-
-        ALL_NON_INCLUSIVE_WORDS = NON_INCLUSIVE_WORDS_ALTERNATIVES_HASH.keys
-
-        NON_INCLUSIVE_WORDS_REGEX = Regexp.new(
-          ALL_NON_INCLUSIVE_WORDS.join("|"),
-          Regexp::IGNORECASE,
-        )
-
-        def self.get_allowed_string(non_inclusive_word)
-          allowed = NON_INCLUSIVE_WORDS_ALTERNATIVES_HASH[non_inclusive_word]["allowed"]
-          snake_case = allowed.map { |e| e.tr(" ", "_").underscore }
-          pascal_case = snake_case.map(&:camelize)
-          (allowed + snake_case + pascal_case).join("|")
-        end
-
-        ALLOWED = ALL_NON_INCLUSIVE_WORDS.collect do |word|
-          [
-            word,
-            get_allowed_string(word),
-          ]
-        end.to_h
-
-        ALLOWED_REGEX = Regexp.new(ALLOWED.values.reject(&:blank?).join("|"), Regexp::IGNORECASE)
-
-        def investigate(processed_source)
-          processed_source.lines.each_with_index do |line, line_number|
-            if line.match(NON_INCLUSIVE_WORDS_REGEX)
-              ALL_NON_INCLUSIVE_WORDS.each do |non_inclusive_word|
-                allowed = ALLOWED[non_inclusive_word]
-                if allowed.blank?
-                  scan_regex = /(?=#{non_inclusive_word})/i
-                else
-                  scan_regex = /(?=#{non_inclusive_word})(?!(#{ALLOWED[non_inclusive_word]}))/i
-                end
-                locations = line.enum_for(
-                  :scan,
-                  scan_regex,
-                ).map { Regexp.last_match&.offset(0)&.first }
-                next if locations.blank?
-                locations.each do |location|
-                  range = source_range(
-                    processed_source.buffer,
-                    line_number + 1,
-                    location,
-                    non_inclusive_word.length,
-                  )
-                  add_offense(
-                    range,
-                    location: range,
-                    message: create_message(non_inclusive_word),
-                    severity: SEVERITY,
-                  )
-                end
-              end
-            end
-          end
-          # Also error for non-inclusive language in file names
-          path = processed_source.path
-          if path.nil?
-            return
-          end
-          non_inclusive_words_match = path.match(NON_INCLUSIVE_WORDS_REGEX)
-          if non_inclusive_words_match && !path.match(ALLOWED_REGEX)
-            range = source_range(processed_source.buffer, 1, 0)
-            add_offense(
-              range,
-              location: range,
-              message: create_message(non_inclusive_words_match[0]),
-              severity: SEVERITY,
-            )
-          end
-        end
-
-        def autocorrect(arg_pair)
-          word_to_correct = arg_pair.source
-          word_to_correct_downcase = word_to_correct.downcase
-          return if !NON_INCLUSIVE_WORDS_ALTERNATIVES_HASH.key?(word_to_correct_downcase)
-          return if NON_INCLUSIVE_WORDS_ALTERNATIVES_HASH[word_to_correct_downcase]["suggestions"].blank?
-          corrected = NON_INCLUSIVE_WORDS_ALTERNATIVES_HASH[word_to_correct_downcase]["suggestions"][0]
-
-          # Only respects case if it is capitalized or uniform (all upper or all lower)
-          to_upcase = word_to_correct == word_to_correct.upcase
-          if to_upcase
-            corrected = corrected.upcase
-          elsif word_to_correct == word_to_correct.capitalize
-            corrected = corrected.capitalize
-          end
-
-          ->(corrector) do
-            corrector.insert_before(arg_pair, corrected)
-            corrector.remove(arg_pair)
-          end
-        end
-
-        private
-
-        def create_message(non_inclusive_word)
-          format(
-            MSG,
-            non_inclusive_word: non_inclusive_word,
-            suggestions: NON_INCLUSIVE_WORDS_ALTERNATIVES_HASH[non_inclusive_word]["suggestions"].join(", "),
-          )
-        end
-
-        def global_config_path
-          cop_config['GlobalConfigPath']
-        end
-      end
-    end
-  end
-end

data/lib/inclusive_code/flexport/version.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module InclusiveCode
-  module Flexport
-    VERSION = '0.1.0'
-  end
-end