RepoReady

RepoReady is an open-source, browser-only readiness report for public GitHub repositories. It gives maintainers, contributors, recruiters, and users an evidence-based answer to a practical question: is this repository understandable, trustworthy, maintainable, and ready to share publicly?

Live demo · Scoring methodology · Report an issue

Why RepoReady exists

Useful projects are often difficult to evaluate because critical context is scattered or missing: setup instructions, CI, a license, contribution guidance, or a stable release. Repository popularity does not answer whether a new visitor can understand and use the work. RepoReady focuses on the public evidence a maintainer can improve directly.

RepoReady does not assess security, code correctness, developer ability, popularity, or project value.

Features

• Accepts owner/repository, github.com/owner/repository, and complete GitHub URLs.
• Collects public repository metadata with a small set of unauthenticated GitHub REST API requests.
• Applies 24 documented checks across discoverability, documentation, engineering quality, community readiness, and release readiness.
• Separates passed, failed, and unknown evidence; unavailable data never silently becomes a failure.
• Reports both an observable readiness score and scan coverage.
• Explains every check with evidence, direct links, rationale, points, and an actionable recommendation.
• Prioritizes improvements by possible score impact.
• Exports complete Markdown and JSON reports with deterministic filenames.
• Includes a bundled CSV Health fixture that works offline and never calls GitHub.
• Caches completed GitHub reports in sessionStorage for about ten minutes.
• Cancels an older request when a different analysis starts.
• Supports keyboard navigation, reduced motion, visible focus states, and mobile layouts down to 360px.

Quick start

Requirements: Node.js 22.13 or newer and npm.

git clone https://github.com/aminhanifm/RepoReady.git
cd RepoReady
npm install
npm run dev

Open the local address printed by Vite. No environment variables or GitHub credentials are required.

Usage

1. Open the live RepoReady application.
2. Enter a public repository as owner/repository or paste its complete GitHub URL.
3. Select Analyze to collect the repository's public evidence.
4. Review the readiness score, scan coverage, category results, evidence, and recommendations.
5. Export the complete report as Markdown or JSON when you need a stable record.

Architecture

RepoReady is a static React application with a deliberately one-way data flow:

GitHub REST API
  → Zod-validated responses
  → normalized repository facts
  → pure TypeScript scoring engine
  → report model
  → React interface and Markdown/JSON exporters

The API collector, scoring engine, recommendation ordering, report types, and exporters do not import React. That keeps the core reusable for a possible future CLI or GitHub Action.

src/
  api/          input normalization, GitHub client, fact collection, cache
  scoring/      rules, deterministic calculations, recommendations
  components/   accessible report interface
  exporters/    Markdown, JSON, stable downloads
  fixtures/     offline complete and incomplete repository facts
  types/        GitHub fact and public report models
  test/         shared deterministic test setup
e2e/            browser journeys with mocked GitHub responses

Scoring overview

Category	Points
Discoverability	20
Documentation	25
Engineering quality	25
Community readiness	15
Release readiness	15
Total	100

Passed checks earn their full weight. Failed checks earn zero and remain observable. Unknown checks earn no points and are removed from the observable denominator. Scan coverage is the share of the nominal 100 points that could actually be observed. Coverage below 60% produces an Incomplete scan label rather than an overconfident readiness judgment.

Every rule, point value, evidence heuristic, limitation, and formula is specified in SCORING.md. The current ruleset version is 1.0.0.

GitHub API and rate limits

RepoReady uses unauthenticated requests to the public GitHub REST API. A scan makes up to six requests: repository metadata, community profile, README, recursive tree, latest public release, and latest default-branch check runs. These evidence requests are attempted even when GitHub reports a repository size of zero because size alone does not prove that a repository is empty.

The interface displays GitHub's observed request limit, remaining allowance, and reset time. A 404 is reported as “repository not found or not publicly accessible.” Rate limits, malformed responses, network failures, server errors, missing endpoints, and truncated trees are surfaced explicitly. Affected checks remain unknown when the repository itself was successfully identified.

GitHub may enforce stricter or changing public limits. RepoReady intentionally does not accept personal access tokens.

Privacy

RepoReady has no backend, database, authentication, analytics, advertising, trackers, AI service, or cloud storage. GitHub requests are sent directly from the browser for the repository the user enters. Completed reports are stored only in that tab's sessionStorage for roughly ten minutes. The bundled sample needs no network request.

Testing

Automated tests never call the real GitHub API.

npm run format
npm run lint
npm run typecheck
npm test
npm run build
npm run test:e2e

Vitest covers normalization, all 24 rules, weights, calculations, unknown evidence, readiness labels, semantic versions, recommendations, API scenarios, caching behavior, and exports. Integration requests use a deterministic fetch mock. Playwright covers the core journeys in Chromium, including mobile and keyboard use.

Deployment

The build is a static Vite bundle. VITE_BASE_PATH controls asset URLs:

# Root domain
VITE_BASE_PATH=/ npm run build

# Nested portfolio route
VITE_BASE_PATH=/projects/repo-ready/ npm run build

The live application is built into the portfolio Pages artifact at /projects/repo-ready/. The included Pages workflow keeps the legacy /RepoReady/ URL available as a redirect. In both repositories, choose Settings → Pages → Build and deployment → Source: GitHub Actions before the first deployment.

Known limitations

• GitHub's unauthenticated API allowance is shared by IP address and may be exhausted quickly.
• README and release-note checks use documented, conservative text heuristics. They may miss unconventional or non-English structure and cannot verify that instructions work.
• Homepage, evidence, and media links are reported but not fetched or checked for uptime.
• Test files, workflows, and tooling configurations are detected, not executed or judged for quality.
• Very large recursive trees may be truncated by GitHub; affected path checks become unknown.
• GitHub may not expose check runs for every public repository to an unauthenticated browser.
• Tags alone do not count as public GitHub Releases.

Roadmap

• v1.1: explore a reusable CLI using the same scoring engine: npx repo-ready owner/repository.
• Add a GitHub Action adapter without changing the public report model.
• Expand language-aware test, tooling, and lockfile detection with documented fixtures.
• Add opt-in localization for interface copy and README heuristics.

Private repository access, OAuth, token input, vulnerability scanning, AI recommendations, automated repository edits, organization-wide scanning, historical tracking, comparisons, a database, and popularity scoring remain explicit non-goals.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, follow the Code of Conduct, and report security-sensitive findings through SECURITY.md instead of a public issue.

License

MIT © 2026 Amin Hanif