eslint-bankruptcy/README.md

Codemod to eslint-disable all instances of a rule violation in a codebase

# eslint-bankruptcy
> Codemod to eslint-disable all instances of a rule violation in a codebase

## Who Needs This?
Let's say you have an existing codebase, and you'd like to add a new lint rule. When you turn it on, you find that you have many existing violations. Your options are:

1. Go back and fix all existing violations. However, this could be unfeasible, and will delay when you can start getting the protection of the new rule.
1. Turn the rule on as a `warning`. However, this is ineffective because devs ignore warnings.
1. Use a path-specific `.eslintrc` to only enable the rule for greenfield parts of your codebase. However, this is cumbersome, and you won't get protection for newly added code in non-greenfield areas.

None of these options are great. Enter this tool. If you wanted to enable the rule `no-return-assign`, you'd:

1. Add `no-return-assign` as an `error` in your `.eslintrc`. (This tool ignores `warning`s.)
1. Run:
  ```
  $ declare-eslint-bankruptcy src --rule no-return-assign
  ```

The command will add an `eslint-disable-next-line` to every violation of the specified rule(s). It'll change your code from:

```js
function f() {
  let x = 1;
  return x = 2;
}
```

to:

```js
function f() {
  let x = 1;
  // eslint-disable-next-line no-return-assign
  return x = 2;
}
```

Future code, anywhere in your codebase, will have to respect the new rule. Existing code does not need to be further modified.

**Highly recommended:** pass `--explanation` to provide additional context:

```
$ declare-eslint-bankruptcy src --rule no-import-my-legacy-module --explanation "Use MyNewModule instead."
```

```js
// Use MyNewModule instead.
// eslint-disable-next-line no-import-my-legacy-module
import 'my-legacy-module'
```

### Custom ESLint Invocation
By default, this project find the ESLint bin in your project, then invoke a command like:

```
$ eslint path/to/your/files --format json
```

However, some projects have custom ESLint commands (e.g. passing custom args, using a custom ESLint bin wrapper, etc.). In this case, run eslint yourself, have it output JSON, then point this tool to it:

```
$ my-custom-eslint-wrapper files --json-output > eslint-output.json
$ declare-eslint-bankruptcy --eslintOutputFilePath eslint-output.json --rule my-rule --explanation 'My explanation' src
```

### When Not To Use This
* When you want to add a new rule, and there are violations in your existing code, but they can be fixed with a codemod or ESLint's autofixer.

## Installation
```
npm install -g eslint-bankruptcy
```

## Usage
See `declare-eslint-bankruptcy --help`.

Passing the `--explanation` flag will set an explanation along with the `eslint-disable` comments. This is highly recommended, because without context, an `eslint-disable` comment is unclear to future developers. Did the original author intend to disable the rule because it's inapplicable to this current case? Or should the violation be fixed, but disabling the rule was just a cut corner?

```
$ declare-eslint-bankruptcy src --rule no-return-assign --explanation "TODO: Clean this up."
```

```js
function f() {
  let x = 1;
  // TODO: Clean this up.
  // eslint-disable-next-line no-return-assign
  return x = 2;
}
```

### ESLint Instance
When you invoke the command line tool, it runs `require.resolve('eslint')` in your curent working directory and uses it. This means that if you run this tool in your repo, and you have ESLint installed locally (as you should), that's the version that will be used. If you don't have ESLint installed locally, see [Custom ESLint Invocation](#custom-eslint-invocation) above.

If ESLint changes its command line interface, this tool could break.
## Programmatic Usage
`require('eslint-bankruptcy')`. Look at the type definitions in this package's `main` file for usage.

## Whimsy
Depending on your use case, you may find the following aliases useful:

```
alias fuck_it=declare-eslint-bankruptcy
alias oh_god_im_so_sorry=declare-eslint-bankruptcy
alias i_give_up=declare-eslint-bankruptcy
```