From f49b87607a1344745b44205e1acbb64de53c1915 Mon Sep 17 00:00:00 2001 From: Musa Musa Date: Tue, 4 Aug 2026 17:34:25 +0100 Subject: [PATCH] chore: trim keywords from 37 to 10, reversing the expansion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .changeset/lucky-terms-trim.md | 28 +++++++++++++++++++++++++++ package.json | 35 ++++------------------------------ 2 files changed, 32 insertions(+), 31 deletions(-) create mode 100644 .changeset/lucky-terms-trim.md diff --git a/.changeset/lucky-terms-trim.md b/.changeset/lucky-terms-trim.md new file mode 100644 index 0000000..8038238 --- /dev/null +++ b/.changeset/lucky-terms-trim.md @@ -0,0 +1,28 @@ +--- +"naija-id": patch +--- + +Trim `keywords` from 37 to 10, reversing the previous expansion. + +The expansion in 0.5.2 pushed in the wrong direction. Measuring the "nuban" result set (n=14 packages that all carry 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-character description; we carried 37 and 186. + +The expansion caused no measured harm (`nuban` was #8 before and #8 after), so this is a course correction rather than a bug fix. + +Kept, because these are the terms that measurably rank: + +| keyword | rank | +| --- | --- | +| `vnin` | #1 | +| `rsa-pin` | #2 (as "rsa pin") | +| `bvn` | #3 | +| `naija` | #5 | +| `nuban` | #8 | +| `nin` | #10 | +| `cac` | #20 | +| `tin` | #29 | + +Plus `tax-id` (the current NRS identifier — high intent, no ranking data yet) and `nigeria` (the country term, and it appears in the multi-word queries). + +Dropped 27, all of which returned **no ranking at all** when tested directly: `kyc`, `pii`, `redaction`, `identity`, `e164`, `msisdn`, `phone`, `plate`, `passport`, `validation`, `validator` and the spelled-out variants added in 0.5.2. These sit in crowded generic fields where npm's name-token matching decides the result, so they contributed dilution and nothing else. + +The **description is deliberately unchanged.** Front-loading identifier names would improve term position, but it is the human-facing line on the npm page and in GitHub search results — trading readability for a couple of positions on a query where the exact-name package outscores us 13× is a bad deal. diff --git a/package.json b/package.json index a124e43..eadef6e 100644 --- a/package.json +++ b/package.json @@ -1,45 +1,18 @@ { "name": "naija-id", "version": "0.5.2", - "description": "Zero-dependency validators, formatters and PII redaction for Nigerian identifiers — phone (E.164), NIN, vNIN, BVN, Tax ID, TIN, CAC, NUBAN, plate, passport, driver's licence and RSA PIN.", + "description": "Zero-dependency validators, formatters and PII redaction for Nigerian identifiers \u2014 phone (E.164), NIN, vNIN, BVN, Tax ID, TIN, CAC, NUBAN, plate, passport, driver's licence and RSA PIN.", "keywords": [ "nigeria", "naija", - "validation", - "phone", - "msisdn", - "e164", "nin", - "vnin", "bvn", + "nuban", + "vnin", "cac", - "rc-number", "tin", "tax-id", - "nuban", - "bank-code", - "plate", - "passport", - "rsa-pin", - "identity", - "kyc", - "pii", - "redaction", - "nigerian", - "validator", - "national-identity-number", - "bank-verification-number", - "virtual-nin", - "account-number", - "bank-account-validation", - "voters-card", - "vin", - "drivers-licence", - "fixed-line", - "landline", - "phone-validation", - "data-masking", - "log-redaction" + "rsa-pin" ], "license": "MIT", "author": "Musa Musa",