> ## Content Index
> Fetch the complete content index at: https://stalin-pereira.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Ratchets: Build Limits That Only Tighten
- URL: https://stalin-pereira.com/ratchets-build-limits-that-only-tighten/
- Published: 2026-11-18T08:30:00.000Z
- Updated: 2026-11-18T08:30:00.000Z
- Description: Floors catch a collapse, not a slow slide. Ratchets for bundle size, coverage and docs, the tree-shaking bug one caught, and the escape hatch they need.
- Author: Stalin Pereira
- Tags: Developer Practices

Most quality gates in CI are floors: coverage must be above 80%, the bundle must be under 250 KB. Floors stop a collapse. They do nothing about a slow slide. A package sitting at 94% coverage against a 90% floor can lose four points one commit at a time and never go red, and after a year the floor that was meant to be a minimum has quietly become the target.

The fix I keep coming back to is a **ratchet**: a limit stored next to the code that can move in one direction on its own and needs a human with a written reason to move in the other. I use three of them. Here is how each works, the bug one of them caught, and where they hurt.

## 1\. A bundle budget whose ceilings come down

The setup is a small JSON file with one ceiling per app, in gzipped kilobytes, and a CI step that builds each app, measures the boot chunk, and fails if it is over:

```json
{
  "$comment": "Measured ceilings, not aspirations. Every change below is logged with its reason...",
  "webAppGzipKb": 150,
  "adminAppGzipKb": 300
}
```

Three rules make it a ratchet rather than a number people bump:

- **The tool never raises a ceiling.** It can print the current sizes and it can lower a ceiling, but a raise is a hand edit in a pull request.
- **Every raise comes with a note in `$comment`** saying what it bought and what it cost: "new settings screen, 0.8 KB, no new dependency". That field has turned into a decision log. When someone asks why a budget is where it is, the answer is in the file.
- **Ceilings sit just above the measurement, not far above it.** Slack above a number is how the next raise gets argued for on a bundle that never needed it. When a fix saves bytes, the ceiling comes down to match. The saving is not kept in reserve for later.

155 150 145 time (commits) → KB gz raised by hand reason in the log fix lands → lowered saving not banked 
- ceiling in the JSON file
- measured boot chunk

Illustrative numbers. The one raise is deliberate and written down; every drop follows a real saving, so the ceiling always stays close to what actually ships.

## The bug it caught: a schema package nobody was tree-shaking

Two front-end apps share a contracts package: zod schemas for every request and response in the system. Each app uses a different subset. For a while, every time one app gained a screen, the *other* app's budget went red. That cross-talk was the clue.

Part of it was easy to see. Both apps imported one object that mapped every route to its schemas, so referencing it pulled in all of them. Splitting the runtime part (method and path) away from the schemas fixed that, and both ceilings came down. But the bundles still contained schemas from the other app's screens, which made no sense once nothing referenced them.

The rest was the barrel file. The package's `index.ts` re-exports every schema module, and each app imports *part* of nearly every module. A bundler can drop a module when none of its exports are used, and it can drop an unused export inside a used module, but only if it can prove that export's code has no side effects. In this case it couldn't prove that:

```javascript
export const settingsOutput = z.object({ ... });
```

To Rollup (which Vite uses for production builds) that is a call to a function from another package, and a call is assumed to do something. So every unused schema in every touched module stayed in.

The obvious fix was `"sideEffects": false` in the package's `package.json`. I measured it: **zero bytes saved**. That flag lets a bundler skip whole modules whose exports are unused, and that case already worked. It says nothing about unused exports inside a module you do use. I reverted it rather than keep it as unmeasured insurance, and wrote the zero down in the budget log so nobody spends an afternoon on it again.

What worked was telling Rollup, for that one package only, that its modules have no top-level side effects:

```javascript
// vite.config.ts
build: {
  rollupOptions: {
    treeshake: {
      moduleSideEffects: (id, external) =>
        id.includes("/shared-contracts/src/") ? false : !external,
    },
  },
}
```

The `!external` fallback matters. Returning a bare `true` for everything else would tell Rollup that all of `node_modules` has side effects, and the bundle would *grow*, with no error to tell you why. Both apps lost a couple of kilobytes, and both ceilings came down to match.

That declaration is a promise about code that future contributors won't be thinking about when they edit it. If someone adds a top-level `registry.register(schema)`, Rollup will silently drop it. Both apps will build, every unit test will pass (Vitest doesn't tree-shake), and the call will be missing only in production. So a test keeps the promise true:

```javascript
it("every top-level statement is a declaration", () => {
  for (const file of sourceFiles("shared-contracts/src")) {
    const offenders = topLevelLines(file).filter((l) => !DECLARATION.test(l));
    expect(offenders, file).toEqual([]);
  }
});
```

Without the budget I would never have looked. The schemas were a couple of kilobytes, and no functional test would have noticed them.

## 2\. A coverage ratchet that allows deleting dead code

The second ratchet stores per-package coverage in a committed baseline file. CI fails if any metric drops more than half a point below it. Half a point is above ordinary noise and below a real regression.

The obvious version of this rule is "coverage may only go up", and that version is wrong. Delete a well-covered file that nothing uses any more and the percentage drops without a single test being removed. A ratchet that punishes that teaches people to keep dead code. So the script has an `--update` flag that rewrites the baseline, and the rule is: run it, and say why in the commit. "Deleted the unused export path, coverage 96.1 → 95.4" is a fine reason. "Tests were annoying" is visible in review.

One bug in my own version is worth passing on. The first draft skipped any package with no coverage summary. In CI only one job's packages had summaries, so the gate checked one package out of several and printed "coverage held", while another package slid well below its baseline. A missing measurement now fails the run, and a deliberately partial check has to pass a flag that says so. A gate that skips what it can't see is reporting success for work it never did.

## 3\. Never copy a number from a config file into prose

The third ratchet is a writing rule. The project docs used to say "the web app's ceiling is N KB". That went stale twice. Both times the JSON was edited correctly, and both times the paragraph wasn't. After the first time I added a hedge, "if these disagree, believe the JSON", and it went stale again anyway, because a reader trusts the number in front of them.

Now the docs say what the file is for and where it is, and they name no value: "the ceilings live in the budget file; the size command prints the current numbers." It is less convenient to read, but it can't go stale.

## Trade-offs

- **Ratchets can block an urgent fix.** A production hotfix shouldn't wait on someone shaving 300 bytes. You need an escape hatch, and it has to be cheap: a hand edit or an `--update` flag. The cost is the written reason, not the hassle.
- **Tight ceilings mean frequent small raises.** That is fine as long as each one is a sentence in the log. Raise once per feature, not once per commit, so the number records a decision rather than a slow drift.
- **The log gets long.** Mine is long. I'd still keep it: for any number in the file, it tells you who moved it and why.
- **Noisy metrics make bad ratchets.** Timing measurements on shared CI runners wobble. Use a tolerance, measure on a quiet machine, or don't ratchet them.

## Takeaway

A floor tells you when things got bad. A ratchet tells you when they got worse than last time, and it makes every step backwards a decision someone wrote down. Store the limit next to the code, make the tool unable to loosen it on its own, and keep a reason next to every raise.