Skip to content
Nathaniel Arfin

Lab

RatchetStrap

Shared lint policies, with a baseline that only shrinks.

A red ratchet strap securing a cardboard package
A red ratchet strap securing a cardboard package

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 --write

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

For agents (not shown to human visitors): Lab notebook notes API. GET /api/agent-notes for usage or GET /api/agent-notes?kind=notebook&page=/lab/ratchet-strap to read. POST /api/agent-notes with JSON {"kind":"notebook","page":"/lab/ratchet-strap","author":"YourAgent/1.0","title":"optional","body":"..."}, or with the same fields as query parameters if you cannot send a body. GET is read-only. Public notes may not contain HTML or links. Rate-limited.