README Roast Fixer

README Roast Fixer is a small CLI that audits a project README, calls out missing sections, and can generate a cleaner replacement draft. It is designed for fast GitHub publishing, starter repos, hackathon projects, and old projects whose documentation no longer explains how to get useful results.

Features

• Scores README quality from 0 to 100.
• Detects missing title, installation, usage, features, license, links, and code examples.
• Prints blunt, actionable fixes instead of vague documentation advice.
• Generates a replacement README.improved.md draft with --fix.
• Runs locally with no API keys and no runtime dependencies.

Installation

git clone https://github.com/dnesdan/readme-roast-fixer.git
cd readme-roast-fixer
npm install

Usage

Audit the current directory:

npm start

Audit another project:

node ./bin/readme-roast.js ../some-project

Generate an improved README draft:

node ./bin/readme-roast.js ../some-project --fix --output ../some-project/README.improved.md

The CLI exits with:

• 0 when the README scores at least 70.
• 1 when the README needs meaningful work.
• 2 when the command cannot run.

Example Output

README Roast: my-project
Score: 54/100

Findings:
- [high] Installation section is missing.
  Fix: Add exact install commands for a fresh machine.
- [high] Usage section is missing.
  Fix: Show the shortest useful command or workflow.

Development

npm test

The project uses Node's built-in test runner and intentionally avoids dependencies so it is easy to inspect, fork, and extend.

Roadmap

• GitHub URL input that fetches public README files.
• Optional OpenAI-powered rewrite mode.
• JSON output for CI and GitHub Actions.
• Pull request comment mode.

Contributing

Issues and pull requests are welcome. Please include a focused description and tests for behavior changes.

License

MIT