eslint-seatbelt

0.1.3 verified Sat Apr 25 auth: no javascript

eslint-seatbelt is an ESLint plugin that enables gradual tightening of lint rules via a ratcheting mechanism. It stores per-file error counts in a TSV file and automatically updates them on each lint run, preventing new violations while allowing existing ones to be fixed over time. Version 0.1.3 is current, with stable APIs for both ESLint 7 (legacy) and 8+ (flat config). Unlike bulk suppression tools that use JSON/YAML (merge conflicts) or require wrappers, eslint-seatbelt uses the ESLint processor API for seamless editor/CI integration. Reimplements an internal Notion tool used for large-scale rule migrations. Ships TypeScript types.

Common errors

error Error: ESLint configuration in eslint.config.mjs is invalid: The value "eslint-seatbelt" for the "processor" setting must be a string. ↓

cause Using processor in flat config incorrectly (processor is a string, not object).

fix

Use seatbelt.configs.enable which sets processor correctly, or manually: processor: seatbelt.processors.seatbelt

error Parsing error: Cannot find module 'eslint-seatbelt' ↓

cause Missing or incorrect npm install command for ESLint 7 (alias required).

fix

Run: npm add eslint-plugin-eslint-seatbelt@npm:eslint-seatbelt --save-dev

error TypeError: seatbelt.configs.enable is not a function ↓

cause Using seatbelt.configs.enable() instead of seatbelt.configs.enable (it's an object, not a factory).

fix

Use [ seatbelt.configs.enable ] or spread: ...seatbelt.configs.enable is incorrect; just object reference.

Warnings

breaking ESLint 7 users must install with npm alias: eslint-plugin-eslint-seatbelt@npm:eslint-seatbelt ↓

fix Use npm add eslint-plugin-eslint-seatbelt@npm:eslint-seatbelt --save-dev when using ESLint <=7. This aliases package to satisfy plugin naming convention.

gotcha Rules configured as 'warning' are ignored by eslint-seatbelt; only 'error' severity is ratcheted. ↓

fix Set all rules you want to enforce via seatbelt to 'error' severity. Warnings are not tracked and will not prevent regressions.

gotcha Seatbelt file (eslint.seatbelt.tsv) must be committed to version control and kept in sync with codebase. ↓

fix Always commit eslint.seatbelt.tsv. In CI, run with SEATBELT_FROZEN=1 or CI=1 to verify file is up-to-date.

gotcha Running multiple ESLint instances in parallel (e.g., lint-staged) may produce inconsistent seatbelt file ↓

fix Avoid parallel linting across files; run a single ESLint pass to ensure atomic updates to the TSV file.

Install

npm install eslint-seatbelt

yarn add eslint-seatbelt

pnpm add eslint-seatbelt

Imports

default
wrong
```
const seatbelt = require('eslint-seatbelt')
```
correct
```
import seatbelt from 'eslint-seatbelt'
```
ESM-only since v0.1.0; CJS require() will fail unless using ESM interop. Default export is the plugin object.
seatbelt.processors.seatbelt
wrong
```
import { processors } from 'eslint-seatbelt'
```
correct
```
import seatbelt from 'eslint-seatbelt'; seatbelt.processors.seatbelt
```
processors is a sub-object of the default export. Named export 'processors' does not exist.
seatbelt.configs.enable
```
import seatbelt from 'eslint-seatbelt'; seatbelt.configs.enable
```
Use in flat config array. Equivalent to manually setting plugin, rule, and processor.
seatbelt.configs.enable-legacy
wrong
```
import { enableLegacy } from 'eslint-seatbelt'
```
correct
```
plugin:eslint-seatbelt/enable-legacy (in eslintrc extend)
```
Legacy configs are only accessible via string extend in eslintrc; no direct JS import.

Quickstart

Sets up eslint-seatbelt with flat config, then runs SEATBELT_INCREASE to ratchet a new rule.

// File: eslint.config.mjs
import seatbelt from 'eslint-seatbelt'
import js from '@eslint/js'

export default [
  js.configs.recommended,
  seatbelt.configs.enable,
  {
    rules: {
      'no-unused-vars': 'error'
    }
  }
]
// Then run: SEATBELT_INCREASE=no-unused-vars npx eslint .
// This creates eslint.seatbelt.tsv with current error counts.
// Subsequent runs will fail if new errors are introduced.