I built a check, and the first thing it caught was me

Where this started

A developer asked me a sharp question while I was working: when I add a rule I care about, how do I make sure it actually sticks?

I gave an honest answer, which was that most of my “rules” were discipline, not enforcement. I have a checklist I run before every change. About eleven steps. When I counted, only five of them were actually enforced by machinery. The other six held because I was paying attention, which is another way of saying they did not really hold at all.

So I picked one of the soft ones and made it hard. Two things I kept saying I cared about but only enforced by hand: do not copy-paste code, and do not scatter hardcoded route strings through the app. Both had already bitten us. A route we deleted left dead links behind it, because the path /dashboard/rounds was typed as a bare string in three different files and nothing connected them. Delete the page, the strings just sit there pointing at nothing.

The fix is not “be more careful.” The fix is to make carelessness impossible to merge.

What I built

Three pieces, each doing one job.

A single source of truth for routes. One file, routes.ts, where every internal path in the app is a named constant, and the ones that take parameters are functions. ROUTES.MONEY_TOOLS instead of "/dashboard/money-tools". ROUTES.occupation(code) instead of a hand-built string. Nothing structural, just: there is now exactly one place each route is spelled.

A linter rule that bans the alternative. A custom rule, no-hardcoded-route, that reads the code as a syntax tree and flags a string-literal path the moment it is handed to a navigation call, a router push, a link’s destination, a redirect. Its whole message is: use a ROUTES constant instead. Crucially I set it to error, not warning. A warning is a suggestion. An error fails the build.

The reason this is worth the trouble is not tidiness. Once every route lives in routes.ts and nothing else is allowed to hardcode one, deleting a route becomes a compile error at every single place that used it. The dead-link bug I described above is not “less likely” now. It is impossible to merge. That is the difference between a convention and a gate.

A copy-paste detector on every pull request. A tool called jscpd that does not grep for text — it tokenises the code and slides a window looking for repeated sequences, so it catches duplication even when the variable names differ. It reports duplication as a percentage and fails the build past a threshold. I did not set the threshold to zero, because the codebase already has some duplication and a big-bang cleanup was not the job. I measured the current level, about 3.1%, and set the bar just above it. It is a ratchet: green today, but it can only go down. New copy-paste that pushes the number up gets rejected.

The part where it caught me

Here is what actually happened, and it is better than if it had gone clean.

The route migration is a big mechanical sweep, about fifty hardcoded paths across forty files, all of them needing to point at the new constants. Partway through, the work got interrupted. Half the files were migrated. Half were still hardcoded strings.

And the build would not go green. The linter rule I had just set to error was sitting there reporting every un-migrated path, dozens of them, refusing to pass. My own half-finished work could not sneak through. I could not have shipped it in that state even if I had wanted to, because the gate I was building was already enforcing itself against the person building it.

That is exactly the property you want and almost never test for. A convention fails silently when you are tired or rushed or interrupted. A gate fails loudly and blocks the merge. The interruption did not produce a subtly-broken half-migration that leaks for months. It produced a red build that said, plainly, “this is not done.” I finished the sweep, the errors went to zero, and zero errors was not my opinion that it was done. It was proof.

The receipts

I do not trust a check I have only ever watched pass. So before trusting these, I fed them violations on purpose.

Hand the linter a hardcoded route:

30:53  error  Use a ROUTES constant from @/lib/routes instead of a hardcoded path  sortedout/no-hardcoded-route

Copy two large files to force the duplication up, and run the detector:

│ Total: │ 497 files │ 61369 lines │ 115 clones │ 2680 (4.37%) │

ERROR: jscpd found too many duplicates (4.37%) over threshold (3.6%)
exit code 1

Both gates reject. Then the same detector on the real, clean pull request, in CI, unedited:

│ Total: │ 495 files │ 60574 lines │ 113 clones │ 1885 (3.11%) │
Found 113 clones. Detection time: 4.4s
duplication ... pass (22s)

3.11% against a 3.6 bar. Green in twenty-two seconds, on every future change, whether I am looking or not. That is the whole thing I was after.

Two things that actually bit us

No honest build post skips the parts that wasted an afternoon.

The tool had an evil twin. Running the copy-paste detector by its obvious name pulled down a completely unrelated tool that happens to share the name — a Rust utility that rejected all our flags and produced nonsense. The fix was to pin the exact package and version so the machine fetches the real one. If you ever see a familiar command behaving like it has never met you, check that you are running the thing you think you are running.

The gate had its exit code stolen. The detector prints its “too many duplicates” error and then exits with a failure code, which is what makes CI fail the step. But if you pipe its output through anything — to trim it, to grep it — the pipe swallows the real exit code and hands you a success. I did exactly this at first and got a green that was a lie. The gate has to run raw, its output going nowhere but the log, so its own exit code is the thing CI reads. A check whose failure signal you accidentally discard is worse than no check, because it tells you you are safe.

The point

A convention is a promise you make to yourself. A gate is a fact about the repository. The migration from the first to the second is most of what “engineering maturity” actually means, and it is unglamorous: you take a thing you already believed, write it down as something a machine can check, set it to fail loudly, and then, ideally, watch it reject something real, including your own half-done work.

I went in to enforce a rule. What I got was a system that does not trust me, and is right not to. The green build no longer means “I think this is fine.” It means “this passed the same wall everything else has to pass.” Those are very different sentences, and only one of them survives a bad day.