Skip to content

chore: trim keywords from 37 to 10, reversing the expansion - #22

Merged
lintdeveloper merged 1 commit into
mainfrom
chore/trim-keywords
Aug 4, 2026
Merged

chore: trim keywords from 37 to 10, reversing the expansion#22
lintdeveloper merged 1 commit into
mainfrom
chore/trim-keywords

Conversation

@lintdeveloper

Copy link
Copy Markdown
Owner

This reverses most of what I did in 0.5.2. The measurement says I pushed the wrong way.

The evidence

For the "nuban" result set — 14 packages that all carry the term in their description, so name-matching is held roughly constant — search score correlates negatively with every field-size metric:

corr(score, keywordCount)  = -0.241
corr(score, descLength)    = -0.297
corr(score, termPosition)  = -0.285

And we were the outlier on all three:

                 keywords   descLen   "nuban" position
naija-id             37       186          133
others (median)       7        78           53
#1 nuban              2        47           33

That is the signature of TF-IDF field-length normalisation — a standard search behaviour. Every extra keyword dilutes the weight of the ones you care about. Adding 15 keywords to improve discoverability was exactly backwards.

No harm was actually done: nuban ranked #8 before the expansion and #8 after. So this is a course correction, not a bug fix.

What's kept — the ten that earn their place

Tested each keyword directly against the search API:

keyword rank keyword rank
vnin #1 nuban #8
rsa-pin #2 nin #10
bvn #3 cac #20
naija #5 tin #29

Plus tax-id (the current NRS identifier — high intent, no ranking data yet) and nigeria (country term, appears in the multi-word queries).

What's dropped — 27 that returned nothing

kyc  pii  redaction  identity  e164  msisdn  phone  plate  passport
validation  validator  rc-number  bank-code  + the 15 spelled-out variants from 0.5.2

Every one of those returned no ranking at all when queried directly. They sit in crowded generic fields where npm's name-token matching decides the outcome — so they contributed dilution and nothing else.

Description deliberately unchanged

Front-loading the identifier names would improve term position (nuban currently sits at character 133 of 186). I'm not doing it: the description is the human-facing line on the npm page and in GitHub search results, and trading readability for a couple of positions on a query where the exact-name package outscores us 13× (1059 vs 82) is a bad deal.

Two honest caveats

lint ✓   333 tests ✓   publint + attw ✓   package.json biome-clean ✓

On releasing

Changeset is patch. I'd suggest merging this but letting the Version Packages PR sit until there's something else worth shipping — this would be the third patch release today for metadata alone, and the ranking gain doesn't justify burning another version on its own.

The expansion two releases ago pushed the wrong way. Measuring the 'nuban'
result set (n=14 packages all carrying the term in their description),
search score correlates NEGATIVELY with keyword count (-0.24), description
length (-0.30) and how late the term appears in the description (-0.29) —
the signature of TF-IDF field-length normalisation. Every extra keyword
dilutes the ones that matter. For scale, #1 'nuban' carries 2 keywords and
a 47-char description; we carried 37 and 186.

No measured harm was done (nuban was #8 before the expansion and #8 after),
so this is a course correction, not a bug fix.

Kept the ten terms that measurably rank or are high-intent: vnin (#1),
rsa-pin (#2), bvn (#3), naija (#5), nuban (#8), nin (#10), cac (#20),
tin (#29), plus tax-id and nigeria.

Dropped 27 that returned NO ranking when tested directly — kyc, pii,
redaction, identity, e164, msisdn, phone, plate, passport, validation,
validator and the spelled-out variants. They sit in crowded generic fields
where name-token matching decides the outcome, so they contributed
dilution and nothing else.

Description deliberately unchanged: front-loading identifier names would
improve term position, but it is the human-facing line on the npm page, and
trading readability for a couple of positions on a query where the
exact-name package outscores us 13x is a bad deal.
@lintdeveloper
lintdeveloper merged commit d7f1b1d into main Aug 4, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant