Shamefile – Enforce docs for linter bypasses

Recently, the creators of the Witcher games admitted that they regret not taking documentation seriously enough. As they work on the Witcher 1 remake, they are sometimes forced to reapproach old problems because the original reasoning was never properly recorded. A few veterans still remember the context, but some key decisions were made by people who left the studio years ago.

We all know the pain of undocumented decisions, so I built a meta-linter for linting other linters' warnings to fight my colleagues' laziness and my own (mostly). Maybe you just caught a lag from the number of lint words, but the idea is simple. Imagine a yaml file. Now add an entry to it:

- location: ./the-file.rs:93 n\ token: '// NOLINT' n\ why: 'the reason' n\

Do you know what this NOLINT is? You don't? It's a suppression that you added 2 years ago. You don't remember? That's why you need shamefile. :)

Whoever's fault it is. Yours or the linter's. It doesn't matter. Document it, make sure you understand the code, get a review of your new entry in shamefile.yaml and let CI verify it. With shamefile, your CI won't let any undocumented linter warning pass anymore. Instead of educating the business on why docs are important, you'll say: "quality tools won't let my code pass".

I've observed a noticeable difference in AI agents' behaviour. During the pre-commit phase, reasoning models can "rethink" adding a new shame entry and actually fix the code. Not so easy now Claude, huh?

This is an early-stage tool. We've been using it in prod for a month now with my team and I'm using it in all my 3 OSS projects. Looking for feedback and contributors (adding new languages = good first issue ;))

Repo: https://github.com/BKDDFS/shamefile