Skip to content
🤕 An ESLint warning tracker to help introduce rules into a legacy code base
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
__tests__
example
lib
scripts
.eslintrc.js
.gitignore
.prettierignore
.travis.yml
.versionrc.json
CONTRIBUTING.md
LICENSE Add License and Badges Aug 10, 2018
README.md
index.js
jest.config.js
package-lock.json
package.json

README.md

esplint

npm Build Status npm

An ESLint warning tracker to help introduce rules into a legacy code base

About

Linting is a powerful way to catch bad code and enforce best practices. That said, turning a rule on for an existing project can be difficult. It can surface hidden violations that you must fix before you can use the rule at all.

Instead, esplint allows you to turn new rules on as “warnings,” and prevent further violations. esplint tracks the number of eslint “warnings” in each file and prevents the number of “warnings” from increasing. When the number of “warnings” decreases, esplint records the new lower number. This way you can fix existing, legacy violations over time while avoiding further violations.

For more information about the motivation behind esplint, read this post.

Getting Started

Install esplint as a dev dependency of your project.

$ npm install esplint --save-dev

Create .esplintrc.js and add your configurations.

module.exports = {
  surfaceArea: [ ... ],
  rules: [ ...the rules you wish to track... ]
};

Run

$ ./node_modules/.bin/esplint

This will create a .esplint.rec.json record file that stores the number of eslint warnings per file. Add this file to your git repository.

NOTE: This record file will only include files with warnings. If a file is included in the esplint "surfaceArea" but not present in the record file then it has none of the tracked warnings.

Now add this esplint check to your validation on commit hooks (using lint-staged) or CI.

Here's an example using lint-staged:

// package.json

{
  ...
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "*.js": [
      "esplint",
      "git add .esplint.rec.json"
    ]
  },
  ...
}

See a full example here.

Command line

$ ./node_modules/.bin/esplint --help

esplint

Run check and update record
esplint [options] file.js [file.js] [dir]

Commands:
  esplint        Run check and update record                          [default]
  esplint stats  Print stats about eslint violations

Options:
  --version    Show version number                                     [boolean]
  --help       Show help                                               [boolean]
  --overwrite  Ignore existing record file            [boolean] [default: false]
  --no-write   Don't update record file               [boolean] [default: false]

esplint

Run check and update record.

The options are:

  • --overwrite — Ignore existing record file. Useful to bypass the esplint check and force an increase in the number of warnings.
  • --no-write — Only perform warning count check and don't update the record file if the warning count goes down.

esplint stats

Print stats about eslint violations.

Configuration

// .esplintrc.js

module.exports = {
  surfaceArea: [ ... ],
  eslint: { ... },
  rules: [ ... ],
  write: true,
};

The options are:

  • surfaceArea — An array of files and/or directories to track. Use [ "." ] to track all Javascript files in the current directory. These files and directories are used if no files or directories are specified from the CLI
  • eslint — ESLint cli (CLIEngine) options.
  • rules — An array of eslint rule names to track.
  • write — Corresponds to the negation of the --no-write CLI option. See Command line options.

Git Conflicts

Git conflicts can sometimes occur in the record file. If that happens, running esplint should fix most cases.

You can’t perform that action at this time.