inclusive-code 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0e9a66b10fa6c3d82c8faa54ddacb5953682d660b3751567aec4af6e6a1d945
-  data.tar.gz: cdb7d1ec5ceaa41f4fa134c449a463251c59560a2d4ae6e8fe87d4e46b7acc6d
+  metadata.gz: 7fc5f8f716dd932818068d5b282bc52d1f7e93ad38eec1f16e100076347c42f8
+  data.tar.gz: 372a8b68115654589caf6ec9a6c03e94c96d5f2cced613065c15b0454214076a
 SHA512:
-  metadata.gz: 87f0191b289b92d8b3241b05295d12b661fda42aa671519471b2bb494ed6ca3853d8b4a3aee662c8ba6828693fc50f4a219d60b8d6552069585571dacd99fd5d
-  data.tar.gz: 1782766b518b793d0e702a2977c499f672a4ea1bbfc5009f1efbb628e3458ac536469265b95e9b705cdf6fdf64ddccab27319ee2ce07572ebb98f8517254778a
+  metadata.gz: 6781133cb6fad6ef8bb373de9d7359a0d121901f58863adcf5f0498c0550059af3b3b6787cab808ca104392ef790e22e6fe4529805362c5c0c3c5332269004d5
+  data.tar.gz: aa2a97adf00529dbdf3fb6f525aaaa994e7988fe0242d47aeb934cd063fc448e0c8723ee22f91da792727c914b68b6fbbea78142fe271641e3242818450d64da

data/README.md

@@ -19,7 +19,7 @@ Configure your own set of flagged terms following the structure of the `inclusiv
 
 Put this into your .rubocop.yml:
 
-```
+```yaml
 require:
   - inclusive-code
 
@@ -29,8 +29,92 @@ Flexport/InclusiveCode:
   DisableAutoCorrect: false
 ```
 
-You can run the cop on your entire codebase with `rubocop --only Flexport/InclusiveCode`. 
+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/lib/rubocop/cop/inclusive_code.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/core_ext/string'
 
 module RuboCop
@@ -23,46 +25,56 @@ module RuboCop
       class InclusiveCode < Cop
         include RangeHelp
 
-        SEVERITY = 'warning'.freeze
+        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`."
 
-        MSG = '🚫 Use of non_inclusive word: `%<non_inclusive_word>s`. Consider using these suggested alternatives: `%<suggestions>s`.'.freeze
+        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 = Regexp.new(
-            @all_non_inclusive_words.join('|'),
-            Regexp::IGNORECASE
-          )
-          @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)
+          @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)
 
-            @all_non_inclusive_words.each do |non_inclusive_word|
-              allowed = @allowed[non_inclusive_word]
-              scan_regex = if allowed.blank?
-                             /(?=#{non_inclusive_word})/i
-                           else
-                             /(?=#{non_inclusive_word})(?!(#{@allowed[non_inclusive_word]}))/i
-                           end
+            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
+              non_inclusive_words = line.scan(/#{non_inclusive_word}/i)
 
               locations = locations.zip(non_inclusive_words).to_h
               next if locations.blank?
@@ -87,7 +99,7 @@ module RuboCop
           path = processed_source.path
           return if path.nil?
 
-          non_inclusive_words_match = path.match(@non_inclusive_words_regex)
+          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)
@@ -124,26 +136,36 @@ module RuboCop
 
         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]['allowed']
+          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 {|correction_key, _| Regexp.new(correction_key, Regexp::IGNORECASE).match? word_to_correct.downcase }
+          _, 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(
-            MSG,
+            suggestions.present? ? FULL_FLAG_MSG : FLAG_ONLY_MSG,
             non_inclusive_word: non_inclusive_word,
-            suggestions: correction.fetch('suggestions') {[]}.join(', ')
+            suggestions: suggestions
           )
         end
       end

data/lib/rubocop/inclusive_code/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module InclusiveCode
-    VERSION = '0.1.4'
+    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.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Flexport Engineering
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-22 00:00:00.000000000 Z
+date: 2021-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -55,7 +55,8 @@ files:
 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.