@nossbigg/eslint-workflows v0.0.0-rc4

@nossbigg/eslint-workflows

Surgically mute ESLint errors at scale 🤫⚡️

🔪 Silence lint errors selectively at per-file + per-rule basis

💪 Great for monorepos / large teams / noisy rules

Problem / Solution

Problem

1. Introducing a new ESLint rule usually adds a lot of errors/warnings.
2. It's hard to address all these errors in one go.
3. At the same time, you want to apply this new rule to all new code.

In a large monorepo with many developers adding new code all the time, you're essentially fighting a losing battle trying to fix lint errors faster than they come...

If only there was a better way... 🤔

Solution

eslint-workflows allows you to incrementally apply lint rules to your codebase, via the following features:

1. Helps you mute lint errors at per-file + per-rule basis.

2. Tracks all mutes via a human-readable .yml file.

3. Autogenerates .yml changes from eslint output when you need to add new entries.

4. Contains an intuitive CLI interface to let you to safely modify the .yml file.

Basic Usage Guide

1. Adding an entry to yml file

Scenario: You have just added a new eslint rule, but you want to incrementally make changes to adhere to the rule whilst preserving a clean eslint output.

1. Run yarn lint:json to generate a fresh copy of your eslint results
2. Run eslint-workflows entry add to add a new entry to the yml file
3. Select the rule you wish to add
4. Confirm that eslint-workflows had made changes to your yml file
5. Confirm that lint errors related to the rule are no longer emitted by eslint

2. Removing an entry from yml file

Scenario: You have applied changes to adhere to rule, and want eslint to enforce the rule onto a given file.

1. Run eslint-workflows entry remove to remove an entry from yml file
2. Select the granularity (eg. Entry > Team > File)
3. Follow requisite instructions as per selected granlarity
4. Confirm that eslint-workflows had made changes to your yml file
5. Confirm that lint errors related to the rule are now emitted by eslint

3. Viewing yml file contents

Scenario: You want to view the yml file contents in a pretty-printed format.

1. Run eslint-workflows view to view the contents of the yml file in a pretty-printed format.

Setup

Initial setup

1. Install eslint-workflows: yarn add -D @nossbigg/eslint-workflows

2. In project root, run eslint-workflows init

   This step creates the following files:

   • .eslint-workflowsrc.js (config for eslint-workflows)
   • eslint-workflows-entries.yml (tracks mutes)

3. Follow instructions to apply manual changes to your repo

• package.json (Add lint:json task to package.json)
• .gitignore (Add eslint output file to .gitignore)
• .eslintrc.js (Add getWorfklowOverrides() to .eslintrc.js)

Recommended setup

For an ideal developer experience, it is recommended that your ESLint output is empty (ie. 0 errors, 0 warnings), so that developers know whether their changes has introduced any lint errors

You can do this with ESLint by using --max-warnings=0 argument, eg:

eslint --max-warnings=0 .

API: CLI

Top-level Commands

Commands

1. eslint-workflows view

   Print yml file contents, useful for quickly viewing yml file contents.

2. eslint-workflows entry

   Interact with entries.yml file.

   Subcommands:

   • entry add: Add an entry
   • entry remove: Remove an entry or part of an entry
   • entry fmt: Apply formatter to yml file

3. eslint-workflows init

   Set up baseline config for eslint-workflows usage in the current project

API: Node.js

1. getWorkflowOverrides()

   Computes overrides from yml file to be applied to ESLint config.

Configuration

.eslint-workflowsrc.js

Config for eslint-workflows.

Schema:

module.exports = {
  eslintOutputPath: "eslint-workflows/eslint-output.json",
  codeownersPath: ".github/CODEOWNERS",
  workflowsEntriesPath: "eslint-workflows/eslint-workflows-entries.yml",
};

Properties:

• eslintOutputPath (required): Path to eslint output json
• codeownersPath (optional): Path to CODEOWNERS
• workflowsEntriesPath (required): Path to yml file

Note:

• For all path-related properties, you may use absolute paths or relative paths (will be resolved against process.cwd())

eslint-workflows-entries.yml

Tracks mutes at the file-level + rule-level.

Example:

entries:
  - ruleId: no-unused-vars
    teams:
      "@team-a":
        files:
          - src/team-a/file-a.js
      "@team-b":
        files:
          - src/team-b/file-b.js
      _NO_OWNER_:
        files:
          - src/no-owner/no-owner.js

Properties:

• entries: Represents an entry in the yml file
• entry: Represents a combination of a rule + teams
• teams: Represents individual team with related files for muting

Developing

Please refer to this README.