repo-doctor 0.1.1

Turn any repository into an open-source-ready, professional repo in one command.

Repo Doctor scans your Git repository, scores it against 17 open-source best-practice rules, and auto-generates any missing files including README, LICENSE, CI workflow, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY policy, and .gitignore, without ever touching your source code.

Demo

Install

# From PyPI (recommended)
pipx install repo-doctor

# Or with uv
uv tool install repo-doctor

pipx install git+https://github.com/JaaasperLiu/repo-doctor.git
# or
uv tool install git+https://github.com/JaaasperLiu/repo-doctor.git

Quickstart

# Scan a repo and get a health score + report
repo-doctor scan /path/to/repo

# Preview what would be fixed (no files written)
repo-doctor fix --dry-run /path/to/repo

# Fix issues automatically
repo-doctor fix --yes /path/to/repo

# Generate a config file
repo-doctor init

What it checks

17 rules across 6 categories:

Each rule produces a pass/fail, a severity (error/warn/info), and a weight toward the 0-100 score. Grade thresholds: A (90+), B (75+), C (55+), D (<55).

Rule reference

Use --only and --skip with these IDs:

repo-doctor scan --only readme_exists --only license_exists
repo-doctor scan --skip lint_config --skip pinned_deps

How fixes work

Repo Doctor is safe by default:

1. Scans and identifies failing auto-fixable rules
2. Builds a ChangePlan (list of files to create or patch)
3. Shows a rich diff preview of every file
4. Only writes files after you confirm (or use --yes)
5. Re-scans and shows the score improvement

Guarantees:

• Never deletes files
• Never modifies your source code
• Only generates meta-files (README, LICENSE, CI, etc.)
• Templates are stack-aware — a Python repo gets pytest in CI, a Node repo gets npm test

Detected stacks

Repo Doctor auto-detects your project type and tailors templates accordingly:

CLI Reference

repo-doctor scan [PATH]     Scan and produce a health report
repo-doctor fix [PATH]      Auto-generate missing files
repo-doctor init [PATH]     Create a .repo-doctor.yml config

Key flags

Output files

After scanning, Repo Doctor writes:

• repo-doctor.report.md — Human-readable report
• repo-doctor.report.json — Machine-readable report (for CI)
• repo-doctor.changes.md — Summary of applied/planned changes

Use --output-dir to keep your repo clean:

repo-doctor scan --output-dir .repo-doctor

Config

If .repo-doctor.yml exists in your repo root, Repo Doctor loads it automatically. CLI flags override config values.

Create one with repo-doctor init, or write it manually:

project_name: my-project
license: mit
ci: github-actions
readme: standard
output_dir: .repo-doctor
skip:
  - lint_config
  - pinned_deps

Use in CI (GitHub Action)

Add Repo Doctor to your GitHub Actions workflow:

- name: Repo Doctor
  uses: JaaasperLiu/repo-doctor/action@v0
  with:
    strict: true  # fail the build if issues are found

The action posts the full report to the GitHub Actions summary and exports score and grade as outputs:

- name: Repo Doctor
  id: doctor
  uses: JaaasperLiu/repo-doctor/action@v0

- name: Check score
  run: echo "Score is ${{ steps.doctor.outputs.score }}"

Action inputs

Development

git clone https://github.com/JaaasperLiu/repo-doctor.git
cd repo-doctor
uv sync --dev
uv run pytest -x -v        # run tests (79 tests)
uv run ruff check src/     # run linter
uv run repo-doctor scan .  # scan itself (scores 100/100)

Contributing

See CONTRIBUTING.md for guidelines, including how to add new rules.

License

MIT