Lab
RatchetStrap
Shared lint policies, with a baseline that only shrinks.

By Nathaniel Arfin · Published
What it is
RatchetStrap centralises lint policy for CHS repositories and tracks the debt each one already carries. ESLint detects violations; RatchetStrap compares them with a checked-in baseline and fails a build when a violation appears that the baseline does not already allow. Repairing debt lets the baseline shrink, and tighten records that the debt is gone.
There is no separate rule language. A ratcheted rule is three things: an ESLint detector, its configuration, and a local allowance for the violations that already exist.
Why a ratchet
Enabling a rule late is the familiar problem: a strict detector fires on thousands of existing lines, so the rule gets demoted to a warning nobody reads, or switched off. A ratchet makes the existing count explicit once, then holds it. New code has to comply; old code can be repaired deliberately.
The baseline is a reviewed record of known violations, not a suppression list: check never writes, and tighten and add preview their proposal before --write saves it.
Using it
bun add --dev @chester-hill-solutions/ratchet-strap
ratchet-strap rules
ratchet-strap profiles
ratchet-strap init --rules no-console,complexity --exec-eslint
ratchet-strap check --exec-eslint
ratchet-strap tighten --exec-eslint --writeCommands return JSON. Exit codes are 0 for success, 1 for violations, and 2 for invalid input or tool failure. A repository that already produces lint reports can reuse one instead of re-running ESLint: ratchet-strap check --report eslint-report.json.
Where it runs
Two kinds of profile: a generic set for new projects, and compatibility profiles that preserve the existing lint contracts of Callcaster, Quick Canvass, Sparkfunds on Helcim and Stow's TypeScript. The consumer supplies its own ESLint installation; the CLI never downloads or pins one on its behalf.
What it will not claim
It cannot prove that an externally supplied report covers the whole repository, or that every tracked rule was actually enabled. CI has to produce a fresh report with the intended configuration and scope. Empty reports, duplicate file results, malformed messages and inconsistent totals fail closed rather than passing quietly.
Explore
- Source and package documentation
- Install from GitHub Packages as
@chester-hill-solutions/ratchet-strap(MIT) - Runs under Node 20.11 or newer, with the consuming repository's ESLint
Frequently asked questions
What problem does RatchetStrap solve?
Adding a lint rule to a mature codebase usually fails on violations that already exist, so the rule gets turned off. RatchetStrap records those existing violations once and fails only on new ones.
Does it replace ESLint?
No. ESLint does the detection. RatchetStrap compares the results with a checked-in baseline, decides pass or fail, and records reviewed improvements.
What happens when someone fixes a violation?
tighten removes the repaired entries from the baseline. It previews the change by default and only saves with --write.
Can it adopt an existing ratchet?
Yes. A migration path imports the ratchets of recognised projects after verification, and automatic consumer script changes require a verified migrate --apply rather than a silent rewrite.