bun add --dev @chester-hill-solutions/ratchet-strap
Also npm install --save-dev @chester-hill-solutions/ratchet-strap. Prefer the bare name? npm install ratchet-strap@npm:@chester-hill-solutions/ratchet-strap aliases it locally, with no wrapper package. Node 20.11 or later; it uses the ESLint you already have.
Two things that used to slip through.
Your rules, ESLint's detection. A warning-only setup never fixes either finding below, which is what the baseline is for. No ESLint, nothing to ratchet.
01 · derived statehouse/no-derived-effect
before
// effect derives state from propsconst [fullName, setFullName] = useState("");
useEffect(() => {
setFullName(`${first} ${last}`);
}, [first, last]);
check
added house/no-derived-effect
src/profile.tsx:...#1
exit 1 new debt
The rule is on and the baseline has no allowance for this identity, so the gate exits 1. A disable comment moves it to suppressed messages, where it still counts.
after
const fullName = `${first} ${last}`;
One render, no stale frame. If the finding had been baselined, tighten --write would remove the now-stale entry.
Four states instead of eight combinations; impossible states are unrepresentable. Old baseline entries become stale until tightened.
The rule IDs are house-rule names, not detectors bundled here. Any ESLint rule works; RatchetStrap makes the new finding fail, the repair visible, and the suppression count.
A red check is easy to make green.
Agents are good at it: mock the thing under test, retry the flake, raise the timeout, add an eslint-disable. Every one passes CI. RatchetStrap asks for the honest fix instead.
01
Baseline, not sweep
Accept what you already have, once, in a file you commit. Keep the rule on.
02
Only goes down
Fix something and the entry has to go. Leave it stale and the gate stops you.
03
Suppressed still counts
Hide a diagnostic behind a disable comment and it still counts against you.
04
Cannot be raised
Compare against a trusted revision. Debt grows only in a diff someone approved.
A Node script: spawn your ESLint, turn each diagnostic into an identity, set-diff against the committed baseline. No model calls, no network, no parsing your source.
Turn the rules on
Enable the ESLint rules you want to ratchet in your flat config.
Record what exists
init writes today's diagnostics to .ratchet-strap.json. Nothing is fixed, nothing is swept.
Check on every run
check reruns your ESLint scope and never writes. CI runs the same command.
Claim the fixes
tighten --write removes the entries you repaired. Leave one behind and it keeps failing.
Identities, not line numbers
An identity is the file, the rule id, the message and the occurrence number. Move unchanged code around inside a file and the baseline still matches.
Diagnostic, not semantic. Rename a file or change a message and you may need a reviewed migration.
Count profiles are weaker on purpose: one fixed violation can offset a new one of the same rule anywhere in scope.
Suppressed messages join the same numbering, so silencing one does not remove it.
It never downloads ESLint, edits your config or repairs your code.
baseline.ratchet-strap.json
{
"schemaVersion": 2,
"mode": "identities",
"adapter": "eslint-identities@1",
"identities": {
"max-params": [
"app/mail.js:max-params:Function 'sendMessage' has too
many parameters (6). Maximum allowed is 5.#1"
]
}
}
Your thresholds, not ours
Limits, profiles, enabled golden rules and adoption recipes live in a house-rules/ directory you own and review. A package upgrade cannot change them; only an edit you approve can.
Edit quality.mjs and golden.mjs, then keep the directory in version control.
Profiles
Pick a comparison mode and an adapter. New projects start on eslint@1. Already carrying a count budget? Adopt eslint-counts@1 deliberately.
Profile
Adapter
Comparison
eslint@1default
eslint-identities@1
New and stale identities fail
eslint-counts@1
eslint-json@1
Per-rule warning and suppressed counts cannot grow
Baselines pin their adapter, so check and tighten infer the profile. Unknown versions and mixed modes fail. Counts never silently become identities.
The twelve defaults
These hold in any repository, any language, any framework. Golden profiles are opt-in and live in your house rules; the engine ships none.
U1
A change that adds a tracked violation fails the gate.
U2
A baseline may only lose entries. Never raise one to make a change pass.
U3
A suppressed or disabled diagnostic still counts as a violation.
U4
A repaired violation must be removed from the baseline.
U5
Every exemption is scoped to one rule, one location and one written reason.
U6
One local command runs exactly the same checks as CI.
U7
Generated artefacts reproduce with no diff.
U8
Every gate has a fault and a control fixture proving both directions.
U9
No secret value reaches a response, log, span, error or built artefact.
U10
A published change carries a version bump and a changelog line.
U11
A shared module mock keeps the real export surface.
U12
Guarded code cannot opt out of the gate that guards it.
U1–U4 are enforced by this engine. U5 and U12 are review. The rest are consumer gates; the README names the mechanism for each.
Let your agent decide.
Paste this into the agent that already knows your repository. It measures what ESLint reports today, finds the CI job that would run the gate, and tells you whether adopting this is a one-command change or a migration.
It reports and stops. Nothing is installed, no config is edited, no baseline is written.
A verdict: adopt, adopt after one fix, or not a fit.
The count it would baseline on day one, per rule.
The exact CI job and command that would run the gate.
Works in Claude Code, Codex, Cursor, or anything with shell access to your repo.
agent prompt
You are deciding whether the npm package ratchet-strap fits this repository. Report only: do not install anything, edit config, or write a baseline.
What it does: ESLint does the detection. RatchetStrap records the violations that already exist in a committed .ratchet-strap.json, fails the build on any new one, and fails again when a repaired violation is left in the baseline. Commands: ratchet-strap init | check | tighten | add | rules | profiles | migrate. Exit codes 0 pass, 1 violations, 2 bad input.
Inspect this repository and answer:
1. Is ESLint installed, and is there a flat config? What does `eslint . --format json` report today: total violations, errors vs warnings, and the top five rule ids?
2. Is lint run in CI, on which trigger, and with what command? Does an existing ratchet, baseline or max-warnings budget already exist?
3. Who changes lint config: how many contributors, and do coding agents commit here?
4. Which of these rules would need to stay errors rather than baselined warnings?
Then decide, in this shape:
- Verdict: adopt / adopt after one fix / not a fit
- Day-one baseline: the counts you would accept, per rule
- Hook point: the exact CI job and command to replace
- Risks: stale entries, renamed files, count-profile drift, agent gaming
- If not a fit: the smaller alternative, such as fixing the violations or setting --max-warnings
Base every number on output you ran, and quote the command that produced it.
Start with three commands
Leave your ESLint setup alone. Run three commands, commit one file, and every pull request after that is measured.