RatchetStrap

Let the agents code.
And ratchet away the slop.

Make ESLint improve your code. Set your rules, keep the slop out, and tighten up what you have.

One file to keep your code clean, on every pull request.

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.

A kraft parcel cinched with a red ratchet strap

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 props
const [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.

02 · implicit statehouse/explicit-state-machine
before
const [loading, setLoading] = useState(false);
const [error, setError] = useState<Error | null>(null);
const [data, setData] = useState<Data | null>(null);
check
added  house/explicit-state-machine
       src/order.tsx:...#1
exit 1  new debt

loading && error is representable today. The rule is only a warning until the ratchet holds it.

after
type OrderState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "ready"; data: Data }
  | { status: "failed"; error: Error };

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.

zsh — ratchet-strap
$ ratchet-strap init --rules no-console,complexity --exec-eslint
$ ratchet-strap check --exec-eslint
exit 1 — new violation, stale entry
$ ratchet-strap tighten --exec-eslint --write
$ ratchet-strap check --exec-eslint
exit 0 — clean

Output abridged. Every command prints JSON.

How it works

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.

  1. Turn the rules on

    Enable the ESLint rules you want to ratchet in your flat config.

  2. Record what exists

    init writes today's diagnostics to .ratchet-strap.json. Nothing is fixed, nothing is swept.

  3. Check on every run

    check reruns your ESLint scope and never writes. CI runs the same command.

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

setuptwo commands
$ cp -R node_modules/@chester-hill-solutions/ratchet-strap/house-rules ./house-rules
$ ratchet-strap rules --house-rules ./house-rules/index.mjs

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.

ProfileAdapterComparison
eslint@1 defaulteslint-identities@1New and stale identities fail
eslint-counts@1eslint-json@1Per-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.

Exit codes: 0 passed, 1 violations or new debt, 2 invalid input or tool failure.

quickstartbash
$ ratchet-strap rules
$ ratchet-strap init --rules no-console,complexity --exec-eslint
$ ratchet-strap check --exec-eslint

After repairing debt: ratchet-strap tighten --exec-eslint --write. After enabling another rule: add --rules no-alert.