joblint

Test tech job posts for issues with sexism, culture, expectations, and recruiter fails

Joblint

Test tech job posts for issues with sexism, culture, expectations, and recruiter fails.

Writing a job post? Use Joblint to make your job attractive to a much broader range of candidates and ensure you're not being discriminatory.
Getting swamped in job posts? Use Joblint to filter out the bad ones.

joblint path/to/job-post.txt

Install Joblint globally with npm:

npm install -g joblint

This installs the joblint command-line tool:

  Usage: joblint [options] <path>
 
  Options:
 
    -h, --help                 output usage information
    -V, --version              output the version number
    -r, --reporter <reporter>  the reporter to use: cli (default), json
    -l, --level <level>        the level of message to fail on (exit with code 1): error, warning, notice
    -p, --pretty               output pretty JSON when using the json reporter

Run Joblint against a text file:

joblint path/to/job-post.txt

Run Joblint against a text file and output JSON results to another file:

joblint --reporter json path/to/job-post.txt > report.json

Run Joblint against piped-in input:

echo "This is a job post" | joblint

Run Joblint against the clipboard contents:

# OS X 
pbpaste | joblint
 
# Linux (with xclip installed) 
xclip -o | joblint

The command-line tool uses the following exit codes:

  • 0: joblint ran successfully, and there are no errors
  • 1: there are errors in the job post

By default, only issues with a type of error will exit with a code of 1. This is configurable with the --level flag which can be set to one of the following:

  • error: exit with a code of 1 on errors only, exit with a code of 0 on warnings and notices
  • warning: exit with a code of 1 on errors and warnings, exit with a code of 0 on notices
  • notice: exit with a code of 1 on errors, warnings, and notices
  • none: always exit with a code of 0

The command-line tool can report results in a few different ways using the --reporter flag. The built-in reporters are:

  • cli: output results in a human-readable format
  • json: output results as a JSON object

You can also write and publish your own reporters. Joblint looks for reporters in the core library, your node_modules folder, and the current working directory. The first reporter found will be loaded. So with this command:

joblint --reporter foo path/to/job-post.txt

The following locations will be checked:

<joblint-core>/reporter/foo
<cwd>/node_modules/foo
<cwd>/foo

A joblint reporter should export a single function which accepts two arguments:

  • The test results as an object
  • The Commander program with all its options

Joblint can run in either a web browser or Node.js. The supported versions are:

  • Node.js 0.10, 0.12
  • Android Browser 2.2+
  • Edge 0.11+
  • Firefox 26+
  • Google Chrome 14+
  • Internet Explorer 9+
  • Safari 5+
  • Safari iOS 4+

Install Joblint with npm or add to your package.json:

npm install joblint

Require Joblint:

var joblint = require('joblint');

Include the built version of Joblint in your page (found in built/joblint.js):

<script src="joblint.js"></script>

Install Joblint with Bower or add to your bower.json:

bower install joblint

Run Joblint on a string:

var results = joblint('This is a job post');

The results object that gets returned looks like this:

{
 
    // A count of different issue types 
    counts: {
        foo: Number
    },
 
    // A list of issues with the job post 
    issues: [
        
        {
            name: String, // Short name for the rule that was triggered 
            reason: String, // A longer description of why this rule was triggered 
            solution: String, // A short description of how to solve this issue 
            level: String, // error, warning, or notice 
            increment: {
                foo: Number // The amount that each count has been incremented 
            },
            occurance: String, // The exact occurance of the trigger 
            position: Number, // The position of the trigger in the input text 
            context: String // The text directly around the trigger with the trigger replaced by "{{occurance}}" 
        }
 
    ]
}

You can also configure Joblint on each run. See Configuration for more information:

var results = joblint('This is a job post', {
    // options object 
});

An array of rules which will override the default set. See Writing Rules for more information.

joblint('This is a job post', {
    rules: [
        // ... 
    ]
});

Writing rules (for your own use, or contributing back to the core library) is fairly easy. You just need to write rule objects with all the required properties:

{
    name: String, // Short name for the rule 
    reason: String, // A longer description of why this rule might be triggered 
    solution: String, // A short description of how to solve the issue 
    level: String, // error, warning, or notice 
    increment: {
        foo: Number // Increment a counter by an amount. The default set is: culture, realism, recruiter, sexism, tech 
    },
    triggers: [
        String // An array of trigger words as strings. These words are converted to regular expressions 
    ]
}

Look in lib/rules.js for existing rules.

There are some example job posts that you can test with in the example directory:

joblint example/passing.txt
joblint example/realistic.txt
joblint example/oh-dear.txt

To contribute to Joblint, clone this repo locally and commit your code on a separate branch.

If you're making core library changes please write unit tests for your code, and check that everything works by running the following before opening a pull-request:

make ci

The following excellent people helped massively with defining the original lint rules: Ben Darlow, Perry Harlock, Glynn Phillips, Laura Porter, Jude Robinson, Luke Stavenhagen, Andrew Walker.

Also, there are plenty of great contributors to the library.

Joblint is licensed under the MIT license.
Copyright © 2015, Rowan Manning