juanmackie/juanskills

GitHub Gem Hunter

Zweck

Oberflächliche, hochwertige GitHub-Repositories mit geringer Sichtbarkeit für einen bestimmten Bereich identifizieren, indem das Topic-Graph weitgehend und die Star- sowie Datumsbänder tiefgehend durchsucht werden.

Wann verwenden

• Der Nutzer fragt nach „versteckten Schätzen“, „unterbewerteten“ Projekten, „verpassten Chancen“ oder „was mir entgeht“ in einem Technologiebereich.
• Der Nutzer möchte Entdeckungen, nicht das bekannteste einzelne Repository.
• Der Nutzer nennt ein Thema, eine Sprache oder ein Problem.

Wann NICHT verwenden

• Der Nutzer möchte das beliebteste Repository (dann einfach direkt nach Stars sortieren).
• Der Nutzer möchte eine Codesuche (dann Code-Suche verwenden, nicht Repository-Suche).
• Der Nutzer hat kein GitHub-Token und erwartet tiefgehende Ergebnisse (dann auf Limitierungen hinweisen).

Ausführungspipeline

Phase 0 – Authentifizierungsprüfung

• Bevorzuge gh-CLI, falls authentifiziert; andernfalls GITHUB_TOKEN erforderlich.
• Falls nicht authentifiziert, warnen: Die Suche ist auf ~10 Anfragen/Min. begrenzt und die Ergebnisse bleiben oberflächlich.

Phase 1 – Topic-Erweiterung (breit)

1. /search/topics?q=<user-topic> abfragen, um verwandte Topic-Namen zu finden.
2. Ein Topic-Cluster aus 3–8 verwandten Themen aufbauen.
3. Repository-Abfragen mit dem topic:-Qualifier für jedes Topic im Cluster konstruieren.

Phase 2 – Star-Band-Aufschneidung (tief)

Für jedes Topic im Cluster die folgenden disjunkten Bänder durchlaufen: stars:1..10, stars:11..50, stars:51..200, stars:201..1000, stars:1001..5000. Innerhalb jedes Bandes bis zur Obergrenze von 1.000 Ergebnissen paginieren.

Phase 3 – Rezenzfilter

Für Bänder, die mehr als 1.000 Ergebnisse liefern, den pushed:-Datumsbereich rekursiv aufteilen, bis jedes Fenster unter der Grenze liegt.

Phase 4 – Low-Star-Gem-Sweep

Eine dedizierte stars:1..20-Abfrage pro Topic mit pushed:>YYYY-MM-DD (6 Monate zurück) ausführen. Diese Ergebnisse separat sammeln.

Phase 5 – Deduplizieren und Anreichern

• Nach full_name deduplizieren.
• Metadaten abrufen: Stars, Forks, offene Issues, pushed_at, created_at, Topics, Lizenz, README-Länge (über Contents-API).
• Forks ausschließen, es sei denn, der Nutzer fragt explizit danach (fork:true).

Phase 6 – Bewerten und Rangfolge

Den Gem-Score anwenden:

• Sternwachstumsrate (Stars / Monate seit Erstellung)
• Tage seit letztem Push (je niedriger, desto besser)
• README-Länge und -Struktur
• Topic-Relevanzdichte
• Issue-Responsiveness (falls verfügbar)

Ergebnisse gruppieren in:

• Active Gems (aktuelle Commits, steigende Wachstumsrate)
• Pre-traction Gems (niedrige Sterne, aber aktuelle Aktivität)
• Gap Fills (Repos, die zwei Topic-Cluster verbinden)

Phase 7 – Ausgabe

Eine rangierte Markdown-Tabelle mit Spalten ausgeben: repo | stars | age | last push | why it's a gem Einen kurzen Methodik-Hinweis und einen Hinweis zu API-Ratenlimits einfügen.

Fehlerbehandlung

• Bei HTTP 403 (sekundäres Ratenlimit): warten und mit exponentiellem Backoff erneut versuchen.
• Bei HTTP 422 (Abfrage zu komplex): die Abfrage durch Entfernen des unwichtigsten Qualifiers vereinfachen und erneut versuchen.
• Bei leeren Ergebnissen für ein Star-Band: Band überspringen und fortfahren.

Limitierungen

• Die GitHub-Suche begrenzt jede Abfrage auf 1.000 Ergebnisse; das Aufschneiden mildert dies, beseitigt es aber nicht.
• Die Sternwachstumsrate ist bei sehr neuen Repos (< 30 Tage alt) verrauscht.
• Die README-Länge ist ein Indikator, aber keine Garantie für Qualität.