https://github.com/yl0711-coder/readme-roast
Roast README drift or report it strictly by checking local links, paths, and project tree examples.
https://github.com/yl0711-coder/readme-roast
cli developer-tooling documentation markdown python readme
Last synced: 14 days ago
JSON representation
Roast README drift or report it strictly by checking local links, paths, and project tree examples.
- Host: GitHub
- URL: https://github.com/yl0711-coder/readme-roast
- Owner: yl0711-coder
- License: mit
- Created: 2026-04-22T11:59:20.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-22T12:06:32.000Z (2 months ago)
- Last Synced: 2026-04-22T14:10:45.892Z (2 months ago)
- Topics: cli, developer-tooling, documentation, markdown, python, readme
- Language: Python
- Size: 10.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# README Roast
[English](README.md) | [简体中文](README.zh-CN.md)
## One-Line Idea
Roast a repository README like a mean reviewer, or switch to strict mode and turn the jokes into actionable checks.
## Why It Exists
Many repositories have README files that sound confident but drift away from reality:
- install steps no longer work
- paths in the docs do not exist
- repository structure examples are outdated
- package metadata and README disagree
This project turns that pain into a fun local tool.
## Core Modes
- `roast`: funny output
- `review`: serious output
- `strict`: CI-friendly failure mode
## MVP
- detect local README links that point to missing files
- detect obvious referenced paths that do not exist
- detect project tree snippets that mention missing directories
- output funny roast lines
- output strict machine-readable findings
## Status
Current version: `v0.1.1`
First version scope:
- local README path truth-checking only
- no network access
- no remote link validation
- no package-manager-specific checks yet
- no automatic fixes
Version `v0.1.1` also understands local links with fragments or query strings, such as `CHANGELOG.md#v011---2026-05-08`, and ignores non-file links such as `mailto:`.
## Good Fit
- Python
- single CLI
- no network
## Non-Goals
- full Markdown parser with every edge case
- remote HTTP link checker
- full package manager validation replacement
## First Demo
Run it against intentionally messy repositories and produce:
- a roast screenshot
- a strict report screenshot
## Usage
```bash
bin/readme-roast
bin/readme-roast --mode review
bin/readme-roast --json
bin/readme-roast --strict
bin/readme-roast --readme README.zh-CN.md --mode review
bin/readme-roast /path/to/repo --mode review --strict
```
Exit codes:
- `0`: command ran successfully
- `1`: findings present in `--strict` mode
- `2`: invalid input such as missing `README.md`
## What It Checks
- local Markdown links such as `[Changelog](CHANGELOG.md)`
- local Markdown links with anchors such as `[Changelog](CHANGELOG.md#v011---2026-05-08)`
- obvious inline path references such as `` `scripts/dev.py` ``
- project tree entries inside README code blocks
## Development
```bash
PYTHONPATH=src python -m unittest discover -s tests
bin/readme-roast --mode review --strict
```