Contents

Woke - Non-intrusive language

Woke

Woke is an text file analyzer for non-inclusive language.

Woke is an text file analyzer for non-inclusive language. That means that it helps you to easily find alternatives to words on your code or documentation that can cause discomfort or even harm to people and cultures.

Basics

Woke is an analysis tool made in golang that will scan your code or document looking for some non-inclusive words to later on suggest you alternatives with same meaning so you can replace it.

As any analysis tool you will have to download a binary and execute it giving it the directory in which it will run an analysis.

Woke comes with a default directory but that directory has just a few basic words and suggestions.

It is the company or the developer rule to create and define it’s own dictionary. The good news is that it is very simple to create and use a custom dictionary and since it is a yaml file it can be kept on the project repository.

If you don’t provide any dictionary woke will run using it’s own default rules/dictionary

Custom dictionary

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
rules:
  - name: allowlist
    terms:
      - whitelist
      - white-list
    alternatives:
      - allowlist
  - name: renegade
    terms:
      - black ship
      - blackship
      - black-ship
    alternatives:
      - renegade
  - name: ostracize
    terms:
      - blackball
    alternatives:
      - ostracize
  - name: extortion
    terms:
      - blackmail
    alternatives:
      - extortion
  - name: spouse
    terms:
      - wife
      - husband
    alternatives:
      - spouse

Configuration files

Woke also offers you a way to ignore files and/or directories you don’t really want to analyze. To do such thing all you have to do is to create a new file by the name of .wokeignore on your project root directory

wokeignore file is a yaml file to configure what should not be scanned by woke when it is looking for non-intrusive language.

1
2
3
4
ignore_files:
  - .git/*
  - node_modules/*
  - bin/*

Installing it locally

To run woke on your repository you will first need to download it from woke project project on github.

Go to the release page and download the last version to the OS you use (linux/windows/darwin).

After downloading you will have to decompress the downloaded file with your favorite decompressing tool and later copy the woke binary to some directory on your machine.

On Linux you can always move the binary to ‘/usr/local/bin’ and just by doing it you will have that binary available to be used because ‘/usr/local/bin’ is usually already part of the PATH environment variable in every Linux distro out there.

On Windows you could create for example, a ‘bin’ folder on your user directory and set the Windows PATH environment variable to contain that directory as well.

On Darwin I have no idea but I believe you can follow the same steps from Linux and copy the woke binary to ‘/usr/local/bin’

To check if everything is ok just move to a different directory and type

1
woke --version

Windows users will probably have to type woke.exe

1
woke.exe --version

If you get command not found it means you don’t have the woke binary directory set on your PATH environment variable so double check it 😄

Running it locally

Now go back to your favorite terminal emulator, go to your project folder and run:

1
2
3
#linux/darwin

woke
1
2
3
# windows

woke.exe

Example

I just run it on a personal project and the results are:

1
2
3
4
5
6
test/java/com/user/birthdaydroid/contact/ContactServiceTest.java:114:83-88: `Dummy` may be insensitive, use `placeholder`, `sample` instead (error)
        final CloseableIterator<AndroidContact> iterator = new TestClosableIteratorDummy<>(Arrays.asList(androidContact1, androidContact2));
                                                                                   ^
test/java/com/user/birthdaydroid/contact/ContactServiceTest.java:144:83-88: `Dummy` may be insensitive, use `placeholder`, `sample` instead (error)
        final CloseableIterator<AndroidContact> iterator = new TestClosableIteratorDummy<>(Arrays.asList(androidContact1, androidContact2));
                                                                                   ^

As you can see woke is telling me I’m using the word “dummy” and it also tells me I should use “sample” instead. Beautiful ❤️

Use of custom directory

To use the custom dictionary all you have to is:

  1. Create the dictionary file
  2. Give it as a parameter to woke binary
1
woke -c your-custom-dictionary.yaml

Extensions

VIM

VSCode

It is possible to have woke integrated to VIM ❤️ or Visual Studio Code but in keep in mind you will still have to download/install/update the woke binary as it was described here before.

Mind that the extention will scan your code only after you have the woke binary path into your the PATH environment.