Is the Package What It Presents Itself As?¶
Source: hooks/ways/softwaredev/code/supplychain/maturity/maturity.md
Frontmatter
| Field | Value |
|---|---|
description |
judging whether a candidate package is what it presents itself as — adoption versus presentation, and thin wrappers around a mature library |
vocabulary |
package maturity adoption downloads stars wrapper thin wrapper reimplementation candidate library evaluate choose between alternatives which package should we use first order transitive dependency underneath |
refire |
0.15 |
scope |
agent, subagent |
The other supply-chain tiers ask whether a package is safe. This one asks whether it is what it appears to be — which decides whether you should adopt it at all, before safety is even the question.
Two failure modes, and they usually travel together:
- Presentation outruns adoption. A polished README, a benchmark table, and a confident feature list are cheap to produce now. They no longer signal that anyone depends on this or that it has met real-world inputs.
- The package is a thin wrapper positioned as a first-order tool. The substantive work happens in a dependency. You can usually take that dependency directly, and get far more adoption and a smaller surface for the same capability.
The check¶
Three questions, a minute of work, before adopting anything you found through a search:
| Question | How to check |
|---|---|
| How many people actually use this? | Registry API — total downloads, recent downloads, first-published date. Not stars, which reflect attention rather than reliance. |
| What is underneath it? | Read its manifest. A short dependency list with one substantial entry is the wrapper tell. |
| How does the wrapped thing compare? | Look up adoption for that dependency too, and put the two numbers side by side. |
An order-of-magnitude gap between a package and the thing it depends on is the finding. It does not automatically disqualify the wrapper — convenience layers earn their keep when the ergonomics are the point — but it moves the burden: the wrapper now has to justify itself over the library, rather than being adopted because it surfaced first.
Why this needs saying now¶
Search results increasingly include packages that are competent, well-documented, recently created, and barely used. Coding agents make that combination cheap to produce, so the correlation search rank once carried — polish implies adoption implies maturity — has weakened.
Apply the same skepticism to your own output. A capable library written this afternoon and a capable library with a decade of adversarial inputs behind it read almost identically in a README. They carry different risk.
What the numbers do and don't tell you¶
- Low adoption asks a question. New, narrow, and excellent all look alike from the download count. Look at what is underneath before judging.
- High adoption carries its own risk. Widely used packages are worth more attacker attention. This is an appropriateness check; the other tiers stay necessary.
- Prefer the layer doing the work. When a wrapper and its dependency both solve the problem, the dependency is usually the smaller, better-tested, longer-lived choice.
The same question about building it yourself¶
Hand-rolling is also a supply-chain choice, with the maintenance and the defect surface landing on you. Reach for a maintained library specifically when the problem has a specification — parsing a document format, dates and time zones, character encodings, cryptography, protocol handling. There the defects are not in the logic you wrote but in the parts of the specification you did not know to handle, so they surface one at a time, in review after review, long after the thing looks finished.
See Also¶
- code/supplychain(softwaredev) — the trust tiers this precedes
- code/supplychain/depscan(softwaredev) — known vulnerabilities, once a package is chosen
- environment/deps(softwaredev) — the pre-adoption checklist this extends