eslint-seatbelt

library0.1.3jsnpmunverified

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.

testing devops

npm install eslint-seatbelt

github ↗package ↗

INSTALL

IMPORT

SIG · ESLINT-SEATBELT

eslint-seatbelt

testingjavascriptv0.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import seatbelt from 'eslint-seatbelt'

✗ const seatbelt = require('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

✓ import seatbelt from 'eslint-seatbelt'; seatbelt.processors.seatbelt

✗ import { processors } from 'eslint-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

✓ plugin:eslint-seatbelt/enable-legacy (in eslintrc extend)

✗ import { enableLegacy } from 'eslint-seatbelt'

Legacy configs are only accessible via string extend in eslintrc; no direct JS import.

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.

Debug

Known issues

breakingESLint 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.

affects: >=0.1.0

gotchaRules 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.

affects: >=0.1.0

gotchaSeatbelt 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.

affects: >=0.1.0

gotchaRunning 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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

Parsing error: Cannot find module 'eslint-seatbelt'

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

fix

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

TypeError: seatbelt.configs.enable is not a function

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.

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

eslintrequiredpeer dependency: required as plugin host engine

@types/eslintoptionalpeer dependency: TypeScript types for ESLint integration

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/justjake/eslint-seatbelt ↗

packagehttps://www.npmjs.com/package/eslint-seatbelt ↗