How to Evaluate an Open-Source Library Before You Depend on It: A Practical Checklist

Adding a dependency is the cheapest decision you will ever make and one of the most expensive ones to reverse. One npm install and the library is in your lockfile, your CI, your production stack traces — and, eighteen months later, in your incident reports when it turns out nobody has maintained it since the month you adopted it.

Most teams evaluate dependencies with two numbers: stars and weekly downloads. Both are popularity signals, both are laggy, and one of them is actively being manufactured at industrial scale. What follows is the checklist we built TrustOSS around — six dimensions you can verify from public data in a few minutes, roughly in order of how often they catch problems.

## 1. Activity: is anyone home?

Start with the simplest question: is the project alive? Three signals answer it.

• -Last push. Not the last commit to a docs branch — the last push to the default branch. Months of silence on a library that sits under active ecosystems (a web framework plugin, a client for a moving API) is a warning; on a small finished utility it may be fine.
• -Commit frequency over the last 90 days. A burst of commits two years ago followed by a flat line tells a different story than a steady trickle, even if both repos have the same total count.
• -Release cadence. Commits without releases mean you are expected to consume from HEAD. Releases without recent commits mean the last release may be the final one.

## 2. Maintenance: what happens when something breaks?

Activity measures whether maintainers write code; maintenance measures whether they respond to your problem. Look at the issue tracker the way you would read reviews of a landlord:

• -Median time to close an issue.Days is excellent, weeks is normal, “never — issues just accumulate” is the signal that you will be on your own.
• -Open-issue pressure. A large open count is not itself bad (popular projects accumulate issues), but a ratio that grows month over month means the team is underwater.
• -Archived status. Obvious, yet routinely missed: plenty of archived repositories still gain stars and downloads every week.

## 3. Community: count contributors, not stargazers

A star is one click by one account that may not even be human. A contributor is someone who understood the codebase well enough to change it. The contributor count — and how concentrated the recent commits are — tells you whether the project survives one person losing interest. That concentration has a name, the bus factor, and it is the most underrated number in dependency risk.

## 4. Documentation and governance: the boring predictors

Documentation quality predicts maintenance quality better than it has any right to. A project with a real README, a license, a contributing guide, and issue templates has a maintainer who thinks about other people using the code. Two hard rules:

• -No license, no adoption. Unlicensed code is not open source; it is publicly visible proprietary code, and legal will eventually agree.
• -A README that documents the API, not the vision. Roadmap-heavy, usage-light READMEs correlate with projects that were launched, promoted, and quietly dropped.

## 5. Security surface: check the record, not the vibes

Query the OSV database for known vulnerabilities in the package and — just as important — check whether past advisories were fixed promptly. A project with two CVEs patched within days has a better security story than one with zero CVEs and zero evidence anyone ever looked. Then glance at the dependency tree: every transitive dependency inherits all of these questions.

## 6. Real adoption: dependents beat downloads

Downloads are inflated by CI runs and mirrors; stars are inflated by bots. The hardest signal to fake is other published packages depending on the library — visible via deps.dev. A thousand dependent packages means a thousand maintainers who will notice, and complain loudly, if the library breaks. That community of stakeholders is your insurance policy.

## Putting it together

No single signal decides. Abandoned-looking projects can be stable and finished; hyperactive projects can be one maintainer away from collapse. The skill is reading the shape of all six dimensions at once.

This checklist is exactly what TrustOSS automates. Paste owner/repo into the analyzer and you get a 0–100 health score across five weighted dimensions (activity, maintenance, community, documentation, maturity), a deep scan for vulnerabilities, bus factor, CI health, and real dependents, and a star audit that checks whether the popularity is even real. Evaluating two candidates? Compare them side by side and let the radar chart argue for you.