@h0tp/shucky 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.7
+
+- **Smarter `find` ranking.** Results are now **relevance-first** — shucky preserves the order each
+  registry returned (skills.sh fuzzy, GitHub search) instead of overriding it with raw popularity, so
+  a precise niche match no longer loses to a popular loose one. **Trusted sources get a bounded boost**,
+  and **popularity is normalised per-source** (log scale) so GitHub star counts can't dominate skills.sh
+  install counts. New pure, unit-tested `rankResults()` (5 checks → 189 total).
+
 ## 0.4.6
 
 - **Docs — README rebalanced installer-first:** leads with the *one command · any source · into

package/lib/find.js

@@ -83,17 +83,48 @@ async function searchGitHub(query, opts) {
   } catch (e) { return { error: 'github: ' + e.message }; }
 }
 
+// How shucky merges + ranks results across sources:
+//  • relevance first — preserve the order each registry returned (skills.sh fuzzy, GitHub search),
+//    so a perfect niche match isn't buried under a popular loose one;
+//  • trusted sources get a bounded boost (~TRUST_BOOST positions), never overriding relevance;
+//  • popularity (installs / GitHub stars) is normalised PER SOURCE on a log scale — so a 200k-star
+//    repo can't dominate a 5k-install skill; it's a tiebreak, not the primary signal.
+const TRUST_BOOST = 1.5;
+
+function rankResults(groups, trusted) {
+  const out = [];
+  for (const group of groups) {
+    let maxPop = 0;
+    for (const r of group) maxPop = Math.max(maxPop, r.installs || 0);
+    const logMax = Math.log10(maxPop + 1) || 1;
+    group.forEach(function (r, idx) {
+      if (!r.trust) {
+        const owner = r.source ? String(r.source).toLowerCase().split('/')[0] : '';
+        if (owner && (trusted.has(owner) || trusted.has(String(r.source).toLowerCase()))) r.trust = 'trusted';
+      }
+      const isTrusted = r.trust === 'trusted' ? 1 : 0;
+      r._rank = idx - (isTrusted ? TRUST_BOOST : 0);                        // relevance position, trust-boosted
+      r._pop = maxPop > 0 ? Math.log10((r.installs || 0) + 1) / logMax : 0; // 0..1 within this source only
+      r._trust = isTrusted;
+      out.push(r);
+    });
+  }
+  out.sort(function (a, b) { return a._rank - b._rank || b._trust - a._trust || b._pop - a._pop || String(a.name).localeCompare(String(b.name)); });
+  out.forEach(function (r) { delete r._rank; delete r._pop; delete r._trust; });
+  return out;
+}
+
 async function findSkills(query, opts) {
   opts = opts || {};
   const cwd = opts.cwd;
-  const results = [];
+  const groups = [];   // one results array per source, kept IN that source's relevance order
   const searched = [];
   const errors = [];
 
   if (!opts.localOnly) {
     searched.push('skills.sh');
     const r = await searchSkillsSh(query, opts);
-    if (Array.isArray(r)) results.push.apply(results, r);
+    if (Array.isArray(r)) groups.push(r);
     else if (r && r.error) errors.push(r.error);
   }
 
@@ -102,7 +133,7 @@ async function findSkills(query, opts) {
     searched.push('github');
     const r = await searchGitHub(query, opts);
     if (Array.isArray(r)) {
-      results.push.apply(results, r);
+      groups.push(r);
       if (!ghToken) errors.push('github: showing repo matches — set GITHUB_TOKEN for precise SKILL.md code search');
     } else if (r && r.error) errors.push(r.error);
   }
@@ -111,25 +142,18 @@ async function findSkills(query, opts) {
     if (src.type === 'list') {
       searched.push(src.name);
       const r = await searchListSource(src, query, opts);
-      if (Array.isArray(r)) results.push.apply(results, r); else if (r && r.error) errors.push(r.error);
+      if (Array.isArray(r)) groups.push(r); else if (r && r.error) errors.push(r.error);
     } else if (src.type === 'registry') {
       searched.push(src.name);
       const r = await searchWellKnown(src, query, opts);
-      if (Array.isArray(r)) results.push.apply(results, r); else if (r && r.error) errors.push(r.error);
+      if (Array.isArray(r)) groups.push(r); else if (r && r.error) errors.push(r.error);
     }
   }
 
-  // Annotate trust from the built-in trustedSources + any registered `trusted` owners.
   const trusted = new Set();
   (loadConfig(null, {}).trustedSources || []).concat(registry.trustedOwners(cwd)).forEach(function (t) { trusted.add(String(t).toLowerCase()); });
-  for (const r of results) {
-    if (r.trust) continue;
-    const owner = r.source ? String(r.source).toLowerCase().split('/')[0] : '';
-    if (owner && (trusted.has(owner) || trusted.has(String(r.source).toLowerCase()))) r.trust = 'trusted';
-  }
 
-  results.sort(function (a, b) { return (b.installs || 0) - (a.installs || 0) || String(a.name).localeCompare(String(b.name)); });
-  return { results: results, searched: searched, errors: errors };
+  return { results: rankResults(groups, trusted), searched: searched, errors: errors };
 }
 
 async function cmdFind(args) {
@@ -159,4 +183,4 @@ async function cmdFind(args) {
   return 0;
 }
 
-module.exports = { findSkills, cmdFind, searchSkillsSh };
+module.exports = { findSkills, cmdFind, searchSkillsSh, rankResults };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h0tp/shucky",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "publishConfig": {
     "access": "public"
   },