Turn silent tech debt into reviewable and documented decisions.
How it works • Why use it • Installation • Supported languages • FAQ • Roadmap • Contributing
shamefile won't let anyone silence a linter warning in your code without writing down why.
People are lazy. Both committer and code reviewer.
- The committer slaps a
// NOLINTcomment when there's no easy fix. They don't justify it — in most languages there's no good place for that. - The code reviewer focuses on more important things: security, bugs, design. There's no dedicated time for checking new suppression arrivals.
Shamefile adds shamefile.yaml for the code reviewer and the shame CLI for the committer to give them tools to react before tech debt gets out of control.
How it works
Five real suppressions across five languages:
Init empty shamefile with shame me .
Fill empty why with shame next
Run again via CI with shame me . --dry-run
Why you should use it
Instantly improves AI agents
Ignoring warnings? Not so easy anymore. Triggers AI reflection — "is this really unfixable?". Observed across Claude, GPT, and Cursor agents. Safer vibe coding by default.
Single source of truth
"Where to document?", "where to look?", "what to do?" — same answer to every question: shamefile.yaml.
Reviewable by design
Make suppression review a ritual, not goodwill.
Shamefile doesn't quit with ex-employees
Knowledge stays in the YAML and you can refactor with confidence.
Installation
| Source | Command |
|---|---|
| npm | npm install -g shamefile |
| PyPI | pip install shamefile |
| crates.io | cargo install shamefile |
| From source | cargo install --git https://github.com/BKDDFS/shamefile |
| Homebrew | coming soon |
All channels install the shame CLI. Run shame --help to verify.
Or as a pre-commit hook:
# .pre-commit-config.yaml - repo: https://github.com/BKDDFS/shamefile rev: main hooks: - id: shamefile
Commands
| Command | What it does |
|---|---|
shame me . |
Scan project, sync shamefile.yaml; fail if any entry lacks why |
shame me . --dry-run |
CI mode — read-only validation, never writes to disk |
shame next |
Show first undocumented entry with the source line highlighted |
shame next "<reason>" |
Document the first undocumented entry inline |
shame fix <location> <token> --why "<reason>" |
Document a specific entry |
shame remove <location> <token> (alias shame rm) |
Delete a stale entry without editing the YAML by hand |
Run shame --help for the full reference.
CI/CD integration
On the CI side, shame me . --dry-run is read-only and deterministic. It validates three contracts:
| Check | Meaning |
|---|---|
| Coverage | Every suppression in code is registered in shamefile.yaml |
| Staleness | Every registered entry still points at a live suppression in code |
| Justification | Every entry has a non-empty why |
A failure on any of the three exits non-zero.
# .github/workflows/ci.yml - name: Check suppressions run: shame me . --dry-run
| Flag | Description |
|---|---|
--dry-run (-n) |
Read-only validation for CI/CD — never writes to disk |
--hidden |
Also scan hidden files and directories (dotfiles) |
Registry format
shamefile.yaml lives at the project root (git root if available, otherwise the working directory). Every entry is human-readable and stable under git diff:
--- config: {} entries: - location: ./src/api.py:42 token: '# type: ignore' content: 'result = parse_legacy_api(raw) # type: ignore' created_at: 2026-04-17 owner: Anna Nowak <anna@example.com> why: 'legacy API returns untyped dict; types module in progress'
locationandtokenform the entry's identity.contentis the verbatim source line — used for reconciliation when code moves.ownerandcreated_atare populated automatically on first run viagit blame.whyis the only field that requires a written justification — from a developer or an AI agent. The PR reviewer decides whether the reason is good enough.
Cascade matching
A registry that breaks every time you refactor is worse than no registry. shamefile reconciles entries against source code in two passes:
- Location match — exact
file:line+ token. - Content match — same source line + token (handles line shifts, with rename detection limited to the most recent commit via
git diff HEAD~1..HEAD -M).
Reformatting a function or inserting imports above a suppression preserves the entry — owner, created_at, and why stay intact. Entries are only removed when the token itself is gone from the code.
Supported languages
shamefile is language-agnostic by design. The list below reflects what has been wired up and tested so far — not a limit on what the engine can do. If your language is missing and there's no open issue for it, please open one so we know there's interest.
| Token | Tool | Language |
|---|---|---|
# noqa |
Flake8 / Ruff | Python |
# pylint: disable |
Pylint | Python |
# type: ignore |
Mypy | Python |
# pyright: ignore |
Pyright | Python |
# pytype: disable |
Pytype | Python |
# pyre-ignore / # pyre-fixme |
Pyre | Python |
nosec |
Bandit | Python |
# pragma: no cover |
Coverage.py | Python |
# fmt: off / # fmt: skip |
Black / Ruff | Python |
# isort: skip |
isort | Python |
# lint-fixme / # lint-ignore |
Fixit | Python |
# autopep8: off |
autopep8 | Python |
// eslint-disable, /* eslint-disable |
ESLint | JS / TS / TSX |
// tslint:disable, /* tslint:disable |
TSLint | TS / TSX |
// @ts-ignore, /* @ts-ignore |
TypeScript | JS / TS / TSX |
// @ts-expect-error, /* @ts-expect-error |
TypeScript | JS / TS / TSX |
Supported file extensions: .py, .js, .jsx, .mjs, .cjs, .ts, .tsx.
Roadmap
- MCP server — native integration for LLM-based PR authors (avoids loading the full registry into agent context)
- Custom git merge driver — auto-resolve
shamefile.yamlconflicts on parallel PRs - Additional language grammars — Rust, Go, Java, Kotlin, C# via tree-sitter
- Custom entry fields — attach
ticket,reviewer, ordeadlinemetadata to suppressions - Native exclusion config — first-class
exclude:patterns inshamefile.yamlfor checked-in vendored or generated code that bypasses the default.gitignorediscovery
FAQ
Why not just write the reason inline, like # noqa: F401 # legacy import?
- Reviewers don't see it. A
# noqaburied in one of seven changed files rarely gets pushback.shamefile.yamlputs every suppression in the PR into one diff — the reviewer sees the full cost as a single list, with author andwhyper entry. - Nothing forces a reason. Linters accept any string after the token, or none.
shame me . --dry-runfails the build until every entry has a non-emptywhy. This matters most for AI coding agents, which lose the suppression's context the moment the session ends — the registry forces them to write the reason to disk while it still exists. - Inline is a bad trade-off. A short reason carries no information; a useful one drowns the line of code it is attached to. The registry keeps source readable and justifications detailed.
What stops developers from writing why: 'TODO' and moving on?
The tool guarantees a string is written; the reviewer judges whether it is a real reason. If why: 'TODO' passes review, that is an organisational gap, not a tool gap — but the registry makes the gap visible: every lazy entry is one grep away, by author and date. Before shamefile, the same shortcut was hidden inside whichever file it lived in.
Won't shamefile.yaml become a merge conflict magnet on parallel PRs?
This is the same trade-off every shared-file tool (lockfiles, changelogs, schema migrations) has accepted in exchange for single-source-of-truth visibility. A custom git merge driver that resolves automatically is on the Roadmap.
The registry is sorted by (location, token), so suppressions added in unrelated parts of the codebase land in different regions of the file — most parallel PRs do not collide. When they do, shame me is idempotent: after a merge, running it on the resolved tree deterministically reconciles entries from source, so git checkout --theirs shamefile.yaml && shame me . is the escape hatch.
What about generated, vendored, or third-party code?
A repo's typical generated/vendored content is excluded for free:
.gitignoreand.ignorefiles are respected (handled by the same engineripgrepuses), sonode_modules/,target/,dist/,__pycache__/etc. are skipped without configuration.- Only
.py / .js / .jsx / .mjs / .cjs / .ts / .tsxare scanned, so vendored content in any other language is silently ignored.
A first-class exclude: config in shamefile.yaml is on the Roadmap.
Contributing
Contributions are welcome. Where you start depends on what you have:
- Found a bug? Open an issue with a minimal repro.
- Idea or design question? Open a Discussion under Ideas so direction can be agreed before any code is written.
- Usage question or trouble setting things up? Ask in Q&A.
- Want to send a PR? Read CONTRIBUTING.md first — dev setup, build/test/lint commands, commit format.
- Security vulnerability? Use the private advisory form — see SECURITY.md. Do not open a public issue.
By participating you agree to the Code of Conduct.
License
shamefile is licensed under the Apache License 2.0. See the LICENSE file for more information.