shamefile 0.1.7

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

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

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

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:

A failure on any of the three exits non-zero.

# .github/workflows/ci.yml
- name: Check suppressions
  run: shame me . --dry-run

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'

• 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 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.

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.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
• Native exclusion config — first-class exclude: patterns in shamefile.yaml for checked-in vendored or generated code that bypasses the default .gitignore discovery

FAQ

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.