RepoCare is a fast, local-first repository health scanner for open-source maintainers. It turns common maintenance gaps into a transparent 100-point report without uploading source code, requiring an API key, or installing runtime dependencies.

RepoCare 0.2.0
Health score: 86/100 (B)
Checks: 12 passed, 2 warnings, 1 failed

[PASS] Open-source license (10/10) - LICENSE
[WARN] README quality (6/12) - README.md
       Next: Add clearly labeled installation and usage sections.
[FAIL] Security policy (0/8) - Not found
       Next: Add a SECURITY.md with a private vulnerability reporting path.

Why RepoCare

Working code is only part of a healthy open-source project. Contributors also need setup instructions, a security contact, issue templates, tests, CI, and a predictable release path. RepoCare checks those signals in seconds and explains the next useful improvement.

  • Local by default: repository contents never leave the machine.
  • Deterministic: the same files produce the same score; no AI judgment is involved.
  • Actionable: every incomplete check includes concrete remediation.
  • CI friendly: enforce a minimum score with a documented exit code.
  • Portable: run it with npx, install it globally, or use the GitHub Action.

RepoCare is a practical maintenance checklist, not a security audit or quality certification.

Quick start

RepoCare requires Node.js 20 or newer. No installation is required:

npx repocare scan .

Or install it globally:

npm install --global repocare
repocare scan .

Usage

Usage:
  repocare scan [path] [options]
  repocare --help
  repocare --version

Options:
  --format <text|markdown|json|sarif>  Report format (default: text)
  --output <file>                Write the report to a file
  --fail-under <0-100>           Exit with code 2 when the score is lower
  --config <file>                Use a config file (default: <path>/.repocare.json)

Write a Markdown report, creating parent directories when necessary:

repocare scan . --format markdown --output artifacts/repocare-report.md

Produce machine-readable JSON and enforce a minimum score:

repocare scan . --format json --output repocare.json --fail-under 80

Configuration

Add .repocare.json to define a project policy:

{
  "$schema": "https://raw.githubusercontent.com/lstsavr/repocare/main/repocare.schema.json",
  "ignore": ["code_of_conduct"],
  "failUnder": 80
}

RepoCare validates option names and rule IDs so configuration typos fail visibly. CLI --fail-under takes precedence over the configured value. Ignored rules are listed in schema-version-2 reports and the score is normalized over active rules.

SARIF

Generate a SARIF 2.1.0 report for GitHub Code Scanning or another compatible consumer:

repocare scan . --format sarif --output repocare.sarif

See the Code Scanning workflow for a complete integration.

Exit codes are:

Code Meaning
0 Scan completed and the minimum score was met
1 Invalid arguments, path, or runtime error
2 Scan completed but the score was below --fail-under

GitHub Action

Pin the action to a released version:

name: Repository health

on:
  pull_request:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  repocare:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Scan repository health
        id: repocare
        uses: lstsavr/repocare@v0.2.0
        with:
          fail-under: 80
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v6
        with:
          name: repocare-report
          path: ${{ steps.repocare.outputs.report }}

The action writes repocare-report.md, exposes its path as the report output, and adds Markdown reports to the GitHub Actions job summary. See the complete workflow example for a copy-ready version.

Action inputs:

Input Default Description
path . Repository path to scan
output repocare-report.md Generated report path
format markdown text, markdown, json, or sarif
fail-under empty Optional minimum score; overrides the config file
job-summary true Add Markdown output to the Actions job summary
config empty Optional RepoCare config file path

What it checks

RepoCare 0.2 evaluates fifteen signals totaling 100 points:

  • README installation and usage guidance
  • Open-source license
  • Contribution and security documentation
  • Code of conduct and changelog
  • Issue and pull request templates
  • Continuous integration and automated tests
  • Dependency update and release automation
  • .gitignore, .editorconfig, and ecosystem metadata

The complete evidence rules, weights, and configuration behavior are documented in docs/rules.md. Reports use schema version 2 for machine-readable integrations.

Privacy and limitations

The scanner reads files under the selected repository path. It does not call GitHub, contact an AI service, execute project code, or inspect Git history. A high score means conventional maintenance evidence exists; it does not prove that the documentation is accurate, the code is secure, or maintainers are responsive.

Development

git clone https://github.com/lstsavr/repocare.git
cd repocare
npm install
npm test
npm run scan:self

See CONTRIBUTING.md for design principles and contribution guidance, SECURITY.md for private vulnerability reporting, and docs/release-process.md for the release checklist.

Roadmap

  • Monorepo and additional ecosystem awareness
  • GitHub annotations and richer SARIF locations
  • Historical score tracking
  • Optional maintainer automation adapters with explicit data controls

Ideas and focused pull requests are welcome. Please open a feature request before starting a large change.