repo-pulse
A tiny CLI that summarizes repository health at a glance.
A command-line tool that scans a local code repository and prints a health report covering documentation, scripts, dependencies, git setup, and leftover TODO markers, useful before publishing or handing off a project.
repo-pulse is a small command-line tool that scans a local code repository and prints a summary of its health. It is designed for quick triage before you publish a project, send it to a reviewer, or hand it off to someone else.
Running it in a project folder produces a compact report covering several categories. It detects what package manager and package metadata the project uses, lists the available scripts (like build, lint, and test), and counts how many dependencies are declared. It checks whether common documentation files are present: a README, a license file, a changelog, and a contributing guide. It checks for GitHub Actions configuration and whether the folder is a git repository. It also scans source files to count TODO, FIXME, HACK, and XXX markers, which are notes that developers leave in code to flag unfinished work.
The output can be formatted as readable Markdown or as JSON for automated use. When Markdown output detects something worth flagging, it shows short action items, like a reminder to add a LICENSE file before inviting contributors or to review any leftover TODO markers before releasing.
All scanning happens locally. The tool makes no network requests, sends no telemetry, and does not upload or modify any files.
Installation requires Node.js. You clone the repository, install dependencies, build the TypeScript source, and link the command globally. The README's roadmap mentions planned additions: git dirty-state summaries, severity scoring for missing project basics, a flag for failing CI checks, and terminal color output.
Where it fits
- Run a pre-publish health check on your project to catch missing docs, stale TODO comments, or absent GitHub Actions config before sharing.
- Output a JSON health report in CI to automatically fail the pipeline if required documentation files like README or LICENSE are missing.
- Scan a project you inherited to quickly understand its structure, available scripts, and how many unfinished TODO markers are left in the code.