GitHub Gem Hunter
Propósito
Encuentra repositorios de GitHub de alto valor y baja visibilidad para un dominio dado, buscando ampliamente en el grafo de temas y profundamente en rangos de estrellas y fechas.
Cuándo usarlo
- El usuario solicita "gemas ocultas", "subestimados", "oportunidades perdidas" o "lo que me estoy perdiendo" en un área tecnológica.
- El usuario quiere descubrimiento, no un solo repositorio conocido.
- El usuario proporciona un tema, lenguaje o enunciado de problema.
Cuándo NO usarlo
- El usuario quiere el repositorio más popular (simplemente busca por estrellas directamente).
- El usuario quiere búsqueda de código (usa búsqueda de código, no de repositorios).
- El usuario no tiene token de GitHub y espera resultados profundos (advierte sobre límites).
Pipeline de ejecución
Fase 0 — Verificación de autenticación
- Preferir CLI
ghsi está autenticado; de lo contrario, requerirGITHUB_TOKEN. - Si no está autenticado, advertir: la búsqueda está limitada a aproximadamente 10 req/min y los resultados serán superficiales.
Fase 1 — Expansión de temas (amplia)
- Consultar
/search/topics?q=<tema-usuario>para encontrar nombres de temas relacionados. - Construir un clúster de 3 a 8 temas relacionados.
- Construir consultas de repositorios con calificadores
topic:para cada tema en el clúster.
Fase 2 — Corte por rango de estrellas (profunda)
Para cada tema en el clúster, ejecutar estos rangos disjuntos:
stars:1..10, stars:11..50, stars:51..200, stars:201..1000, stars:1001..5000.
Paginar dentro de cada rango hasta el límite de 1000 resultados.
Fase 3 — Filtro de actualización reciente
Para rangos que devuelvan >1000 resultados, dividir el rango de fechas pushed: recursivamente hasta que cada ventana esté por debajo del límite.
Fase 4 — Barrido de gemas con pocas estrellas
Ejecutar una consulta dedicada stars:1..20 por tema con pushed:>YYYY-MM-DD (6 meses atrás). Recoger estos por separado.
Fase 5 — Desduplicación y enriquecimiento
- Desduplicar por
full_name. - Obtener metadatos: estrellas, forks, issues abiertos, pushed_at, created_at, temas, licencia, longitud del README (mediante API de contenidos).
- Excluir forks a menos que el usuario los solicite (
fork:true).
Fase 6 — Puntuación y clasificación
Aplicar la puntuación de gema:
- velocidad de estrellas (estrellas / meses desde creación)
- días desde el último push (más bajo es mejor)
- longitud y estructura del README
- densidad de relevancia temática
- capacidad de respuesta a issues (si está disponible)
Agrupar resultados en:
- Gemas activas (commits recientes, velocidad creciente)
- Gemas de pre-traction (pocas estrellas, actividad reciente)
- Rellenos de brecha (repositorios que conectan dos clústeres de temas)
Fase 7 — Salida
Devolver una tabla markdown ordenada con columnas:
repo | estrellas | edad | último push | por qué es una gema
Incluir una nota breve de metodología y una advertencia sobre límites de velocidad de API.
Manejo de errores
- En HTTP 403 (límite secundario de velocidad): esperar y reintentar con backoff exponencial.
- En HTTP 422 (consulta demasiado compleja): simplificar la consulta eliminando el calificador menos importante y reintentar.
- En resultados vacíos para un rango de estrellas: saltar el rango y continuar.
Limitaciones
- GitHub Search limita cada consulta a 1000 resultados; el corte mitiga pero no elimina esto.
- La velocidad de estrellas es ruidosa para repositorios muy nuevos (< 30 días).
- La longitud del README es un proxy, no una garantía de calidad.