repograde

Türkçe · English

Grade your repository's first impression — before a recruiter or a contributor does.

Someone lands on your repo for ten seconds. Is there a README? A license? Tests? Or a committed node_modules and a stray .env? repograde checks the things that decide that first impression and gives you a grade and a to-do list.

$ npx repograde

my-project
Grade: C  (65/100)

  [+] README         30/30  README.md, 142 lines
  [+] License        15/15  LICENSE present
  [ ] Tests          0/15   no test files found
  [+] CI             15/15  1 workflow(s)
  [+] .gitignore     10/10  present
  [ ] Description    0/5    no description in the project manifest
  [ ] Contributing   0/5    no CONTRIBUTING guide
  [+] Hygiene        5/5    no committed junk or secrets

To improve:
  - Add tests — even a few signal that the code is trustworthy.
  - Add a one-line description to package.json / pyproject.toml.
  - Add CONTRIBUTING.md so people know how to help.

Run it

No install needed:

npx repograde                 # grade the current directory
npx repograde path/to/repo    # grade another repo

Or install it:

npm install -g repograde
repograde --help

What it grades

Check	Points	What earns them
README	30	Present, with headings, a code example, an install/usage section, and enough detail
License	15	A LICENSE / COPYING file
Tests	15	A test directory or *.test.* / *_test.* files
CI	15	A GitHub Actions workflow (or Travis/CircleCI/Azure)
.gitignore	10	Present
Description	5	A description in package.json or pyproject.toml
Contributing	5	A CONTRIBUTING guide
Hygiene	5	No committed node_modules, .env, keys, or .DS_Store

Grades: A 90+, B 75+, C 60+, D 40+, F below.

The README check is weighted highest on purpose — it's what people actually read. It's scored in tiers, so a one-line README still earns something, and you can see exactly what would raise it.

Use it in CI

--fail-under makes repograde a gate, so a repo can't drop below a bar you set:

- run: npx repograde --fail-under 75

--json gives you the full breakdown for your own tooling:

npx repograde --json | jq '.checks[] | select(.score < .max)'

Hygiene respects .gitignore

A node_modules sitting in your working tree because you ran npm install is not flagged — repograde reads your .gitignore and only counts things that would actually be committed. It flags the real mistakes: a node_modules, .env, or private key that isn't ignored.

Honest by design

repograde grades itself in its own CI. When this project started it scored an F — no README, no license, a committed node_modules. The checks are the same ones it applies to you; there's no special treatment.

Development

npm ci
npm test          # 34 tests (vitest)
npm run typecheck
npm run build

The checks are pure functions over a small RepoFS interface, so they're tested against an in-memory file tree — fast, and no temp directories for the unit tests. The CLI tests use real temp repos end to end.

Contributing

A new check is a function from RepoFS to a Check result, added to the list in src/checks.ts. Keep each check independent and give it clear advice for the points it withholds.

AI-assisted contributions are fine as long as you say so in the pull request and can explain what you're submitting.

License

MIT — see LICENSE.