shamefile 0.1.2

A cli tool to enforce documentation for code suppressions

 

Turn silent tech debt into reviewable and documented decisions.

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 // NOLINT comment 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.

Why it's important

A mysterious # noqa with no explanation, left by a developer who moved on years ago. Nobody remembers why. Nobody wants to touch it. This is how legacy code accumulates — silently, one linter suppression at a time.

shamefile interrupts that pattern. Every suppression is tracked in a single shamefile.yaml — one file, one purpose. When it changes in a pull request, a reviewer sees the full cost of a shortcut in a single diff. And as AI coding agents become routine PR authors, the registry acts as a consistent gate: whether a suppression was introduced by a human or a model, it ships with a written justification or it doesn't ship at all.

How it works

shamefile exposes two stages, one command each.

Scan — shame me . walks your project, finds every suppression token, and syncs the central shamefile.yaml. New suppressions are registered with auto-filled metadata (owner from git blame, timestamp, source line). Stale entries are removed. The command fails if any entry lacks a why.

Document — shame next shows the first undocumented suppression, with the exact source line highlighted. Provide the reason inline (shame next "<reason>"), or target a specific entry with shame fix <location> <token> --why "<reason>".

The same interface works for a developer opening a PR and for an AI agent iterating through gaps one at a time — without having to read the full registry into context.

Workflow

1. Developer writes code with a suppression:

result = parse_legacy_api(raw)  # type: ignore

2. Pre-commit (or manual) run surfaces the gap:

$ shame me .
Scanning . for suppressions...
Added 1 new entries to /home/user/myproject/shamefile.yaml
1 suppressions need documentation (why).
Run `shame next` to see the first one, or `shame next "<reason>"` to fill its why.

...

3. Developer documents it:

$ shame next
./src/api.py:42
    |
  42| result = parse_legacy_api(raw)  # type: ignore

Fix with:
  shame next "<reason>"
  shame fix "./src/api.py:42" "# type: ignore" --why "<reason>"

$ shame next "legacy API returns untyped dict; types module in progress"
Documented: # type: ignore at ./src/api.py:42
All entries documented. No shame today!

4. Developer commits both api.py and shamefile.yaml. The shortcut and its justification land in the same PR, reviewable in a single diff.

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-17T21:15:05Z
  owner: Anna Nowak <[e-mail]>
  why: 'legacy API returns untyped dict; types module in progress'

• location and token form the entry's identity.
• content is the verbatim source line — used for reconciliation when code moves.
• owner and created_at are populated automatically on first run via git blame.
• why is 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:

1. Location match — exact file:line + token.
2. 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 tokens

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

Experimental tokens

New languages added via the Add a language template land here first. They have passed the existing test suite and a sanity run on a real codebase, but no real-world showcase has been contributed yet. Promotion to Supported tokens happens through the Verify and release a language flow.

Language

Supported file extensions: .py, .js, .jsx, .mjs, .cjs, .ts, .tsx.

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

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.yaml conflicts on parallel PRs
• Additional language grammars — Rust, Go, Java, Kotlin, C# via tree-sitter
• Custom entry fields — attach ticket, reviewer, or deadline metadata to suppressions

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.