npm package: @rmnddesign/eslint-baseline
Description: Adopt strict ESLint rules without fixing everything at once. Baseline current errors, only fail on new ones.
Author: rmnddesign
Latest version: 1.0.0

# @rmnddesign/eslint-baseline

Adopt strict ESLint rules without fixing everything at once.

## The Problem

You want to enable stricter ESLint rules, but your codebase has 500+ existing errors. You have two bad options:

1. **Fix everything first** - Takes weeks, blocks other work
2. **Don't enable the rules** - Tech debt keeps growing

## The Solution

Baseline the existing errors. New code must follow the rules, old code gets a pass (for now).

```bash
# Snapshot current errors
npx @rmnddesign/eslint-baseline init

# In CI - fail only on NEW errors
npx @rmnddesign/eslint-baseline check

# After fixing some errors, update the baseline
npx @rmnddesign/eslint-baseline update
```

## Installation

```bash
npm install -D @rmnddesign/eslint-baseline
```

## How It Works

1. **`init`** - Runs ESLint, saves all current errors to `.eslint-baseline.json`
2. **`check`** - Runs ESLint, compares against baseline, fails only if there are NEW errors
3. **`update`** - Updates the baseline with current errors (after you've fixed some)

The baseline file should be committed to git so your whole team shares it.

## Commands

### `eslint-baseline init`

Generate a baseline from your current ESLint errors.

```bash
npx eslint-baseline init
```

Output:
```
Running ESLint...
Baseline created: .eslint-baseline.json
Baselined 127 errors across 45 unique issues

Add this file to git so your team shares the same baseline.
```

### `eslint-baseline check`

Check for new errors. Exits with code 1 if new errors are found.

```bash
npx eslint-baseline check
```

If no new errors:
```
✓ No new ESLint errors!
  12 baselined error(s) have been fixed.
  Run 'eslint-baseline update' to update the baseline.
```

If new errors found:
```
✗ Found 2 new ESLint error(s):

src/utils.ts
  no-unused-vars: 'helper' is defined but never used
  no-console: Unexpected console statement

Fix these errors or run 'eslint-baseline update' to baseline them.
```

### `eslint-baseline update`

Update the baseline with current errors. Use this after fixing errors, or to baseline new errors.

```bash
npx eslint-baseline update
```

Output:
```
Running ESLint...
Baseline updated: 12 error(s) removed!
Total baselined errors: 115
```

### `eslint-baseline stats`

Show statistics about your baseline.

```bash
npx eslint-baseline stats
```

Output:
```
Baseline Statistics
───────────────────
Generated: 3/13/2026, 2:30:00 PM
Total errors: 127
Unique issues: 45

Errors by rule:
    42  @typescript-eslint/no-explicit-any
    28  no-console
    15  @typescript-eslint/no-unused-vars
    12  prefer-const
     8  no-empty
  ... and 5 more rules
```

## CI Integration

### GitHub Actions

```yaml
name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx eslint-baseline check
```

### Pre-commit Hook

```json
// package.json
{
  "scripts": {
    "lint": "eslint-baseline check"
  }
}
```

## Workflow

### Initial Setup

```bash
# 1. Enable the strict rules you want in your ESLint config

# 2. Generate baseline (this "grandfathers" existing errors)
npx eslint-baseline init

# 3. Commit the baseline
git add .eslint-baseline.json
git commit -m "Add ESLint baseline"
```

### Daily Development

```bash
# CI runs this - fails if you introduce NEW errors
npx eslint-baseline check
```

### Fixing Errors Over Time

```bash
# Fix some errors in your code...

# Update baseline to reflect the fixes
npx eslint-baseline update

# Commit the updated baseline
git commit -am "Fix 12 ESLint errors"
```

### Baseline Format

The `.eslint-baseline.json` file looks like this:

```json
{
  "version": 1,
  "generated": "2026-03-13T14:30:00.000Z",
  "totalErrors": 127,
  "errors": [
    {
      "file": "src/utils.ts",
      "rule": "no-console",
      "message": "Unexpected console statement",
      "count": 5
    }
  ]
}
```

Errors are identified by file + rule + message. Line numbers are ignored since they shift as code changes.

## FAQ

### Does this work with any ESLint config?

Yes. We just run `eslint . --format json` and parse the output. Your rules, plugins, and config are all respected.

### What if I want to baseline only specific rules?

Currently we baseline all errors. You could manually edit `.eslint-baseline.json` to remove entries for rules you want enforced immediately.

### Can I use this with TypeScript ESLint?

Yes. Any ESLint plugin works - we just read the JSON output.

### What about warnings?

Currently we only track errors (severity 2), not warnings. Warnings don't fail CI anyway.

## License

MIT