npm install <something> is a contract. You're saying: "for the life of this project, I will maintain a dependency on a codebase I don't control, maintained by people I don't know, at a cadence I haven't measured."
Most of us sign that contract on the strength of a README and a star count. I stopped. Now there's a two-minute ritual before any non-trivial dependency lands in package.json, and it's mostly a git check.
The ritual
git clone --depth 300 <repo-url> /tmp/pulse && cd /tmp/pulse
npx @wuchunjie/gitpulse .
That's it. A shallow clone (fast, small) and one command. gitpulse is a zero-dependency analytics tool — it reads the local .git directory and prints the repo's vitals. Nothing about your project touches the network except the clone of the candidate library.
The four numbers I read
1. Active days in the recent window. The single most important number. A library with 30 active days in the last 90 is being actively maintained. One with 3 is in triage-only mode. One with 0 is a liability wearing a popular face. I have a hard rule: if the active-days number is lower than my team's release cadence, the dependency is a problem I'm hiring myself to solve.
2. Contributor spread. Five contributors with one holding 80% is a bus factor of 1.2, not 5. I look at the top-contributor bar and the tail. A healthy tail (three or more names with real commit counts) means the knowledge is distributed. A one-name tail means the "community" is a person with a hobby.
3. File breakdown. The file type distribution tells me what I'm actually depending on. A "library" that's 50% test files is a good sign (tests are real). One that's 40% generated code or 30% vendored deps is a maintenance burden in disguise — I'm now responsible for understanding code that's a byproduct, not a design.
4. Recent activity shape. Clusters or steady? A library that commits 30 times in one week then nothing for two months is in burst mode — a maintainer pushing a release, or a contributor on vacation. Steady daily or weekly activity is the maintenance pattern I want to depend on.
What the ritual has stopped
Three real cases:
The "abandoned popular" trap. A UI library, 6k stars, great docs. Pulse: 2 active days in 90, one contributor with 92%. We almost built a dashboard on it. The decision became trivial: the star count was a 2022 phenomenon, and depending on it meant absorbing every breaking change ourselves. We chose a 900-star library with 45 active days. Eighteen months later, that choice has paid for itself in every release.
The "vendored dependency" surprise. A "small utility" library turned out to be 35% vendored copies of other libraries' code. The file breakdown made it obvious in ten seconds. The maintenance implications (those vendored copies don't get upstream security fixes) were enough to find an alternative.
The "one-person framework" risk. Not a bad project — a great one — but the pulse showed one name, 100% of commits, and a cadence of "one burst per quarter." For a side project, fine. For the client's production service, we wrapped the integration behind our own interface so the dependency could be swapped without a rewrite. The ritual didn't stop the adoption; it changed how we adopted.
The honest limit
The pulse measures the repo, not the code. A repo can pulse beautifully and contain terrible code, or pulse weakly and be the most important stable dependency you have (some libraries are meant to be quiet — they're done). The two-minute check is a risk screen, not a quality review. It answers "will this dependency outlive my patience?" before you answer "is this dependency good?" in the actual code review.
And it's cheap enough to run on every candidate, which is the point. Two minutes to measure a contract you're about to sign for years is the best ROI in my whole dependency process.
git clone --depth 300 <repo> /tmp/pulse && npx @wuchunjie/gitpulse /tmp/pulse
More Tools
| Tool | What it does | Command |
|---|---|---|
| scaffoldx-cli | Production-ready project templates in seconds | npx scaffoldx-cli |
| dotguard | Scan .env files for exposed secrets | npx @wuchunjie/dotguard |
| gitpulse | Git repo analytics in your terminal | npx @wuchunjie/gitpulse |
| snippetx | Terminal code snippet manager | npx @wuchunjie/snippetx |
If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.
Top comments (0)