Maintainer Radar

Maintainer Radar is a zero-dependency CLI that audits the maintenance health of an open-source repository. It checks whether a project has the practical basics that contributors and downstream users need: documentation, license, contribution path, security policy, tests, CI, recent git activity, and release tags.

The goal is to help maintainers turn vague repository cleanup work into a concrete, repeatable checklist. A project can run the scanner locally, in CI, or during release preparation and get a score plus specific next actions.

Why This Exists

Open-source maintainers often carry work that is invisible until something breaks: reviewing pull requests, triaging issues, keeping release process clear, documenting how to contribute, and making security reporting safe. Maintainer Radar makes that operational work visible by producing a small report that maintainers can share with contributors or use as a release gate.

Features

• Scans local repositories without any API token or network access.
• Detects README, license, contributing guide, security policy, code of conduct, tests, CI workflows, package manifests, git activity, contributors, and release tags.
• Produces table, JSON, or Markdown reports.
• Returns a non-zero exit code only when critical basics are missing, which makes it practical for CI.
• Uses only the Python standard library.

Install

python -m pip install git+https://github.com/roodoss/maintainer-radar.git

For local development:

git clone https://github.com/roodoss/maintainer-radar.git
cd maintainer-radar
python -m pip install -e .

Usage

Scan the current repository:

maintainer-radar scan

Write a Markdown report:

maintainer-radar scan . --format markdown --output maintainer-radar-report.md

Generate JSON for automation:

maintainer-radar scan /path/to/repo --format json

Example Output

Maintainer Radar report for /workspace/project
Score: 83/100
Summary: Healthy project baseline with 1 warning(s) to address.

Findings:
  [WARNING] security: Missing security.
    -> Add SECURITY.md with a private vulnerability reporting path.

Roadmap

• Optional GitHub API integration for issue and pull request maintenance signals.
• Release-readiness profile for projects preparing a new version.
• Dependency ecosystem profiles for Python, JavaScript, Go, Rust, and PHP projects.
• SARIF output for repository governance dashboards.
• A reusable GitHub Action that comments a concise report on pull requests.

Contributing

Contributions are welcome. Please run tests before opening a pull request:

python -m unittest discover -s tests

See CONTRIBUTING.md for development expectations.

License

MIT