GitHub Gem Hunter
Propósito
Descubra repositórios GitHub de alto valor e baixa visibilidade para um domínio específico, pesquisando amplamente no grafo de tópicos e profundamente nas faixas de estrelas e datas.
Quando usar
- O usuário pede por "gemas escondidas", "subestimados", "oportunidades perdidas" ou "o que estou perdendo" em uma área de tecnologia.
- O usuário quer descoberta, não um único repositório mais conhecido.
- O usuário fornece um tópico, linguagem ou declaração de problema.
Quando NÃO usar
- O usuário quer o repositório mais popular (apenas pesquise por estrelas diretamente).
- O usuário quer busca de código (use busca de código, não busca de repositórios).
- O usuário não tem token GitHub e espera resultados profundos (avise sobre limites).
Pipeline de execução
Fase 0 — Verificação de autenticação
- Prefira a CLI
ghse autenticada; caso contrário, exijaGITHUB_TOKEN. - Se não autenticado, avise: a pesquisa é limitada a ~10 req/min e os resultados serão superficiais.
Fase 1 — Expansão de tópicos (ampla)
- Consulte
/search/topics?q=<user-topic>para encontrar nomes de tópicos relacionados. - Construa um cluster de tópicos de 3 a 8 tópicos relacionados.
- Construa consultas de repositórios com qualificadores
topic:para cada tópico no cluster.
Fase 2 — Fatiamento por faixa de estrelas (profundo)
Para cada tópico no cluster, execute estas faixas disjuntas:
stars:1..10, stars:11..50, stars:51..200, stars:201..1000, stars:1001..5000.
Paginação dentro de cada faixa até o limite de 1.000 resultados.
Fase 3 — Filtro de recência
Para faixas que retornam >1.000 resultados, divida o intervalo de data pushed: recursivamente até que cada janela esteja abaixo do limite.
Fase 4 — Varredura de gemas de baixas estrelas
Execute uma consulta dedicada stars:1..20 por tópico com pushed:>YYYY-MM-DD (6 meses atrás). Colete-as separadamente.
Fase 5 — Desduplicação e enriquecimento
- Desduplique por
full_name. - Busque metadados: estrelas, forks, issues abertas, pushed_at, created_at, tópicos, licença, tamanho do README (via API de conteúdo).
- Exclua forks a menos que o usuário os peça (
fork:true).
Fase 6 — Pontuação e classificação
Aplique o gem score:
- velocidade de estrelas (estrelas / meses desde a criação)
- dias desde o último push (menor é melhor)
- tamanho e estrutura do README
- densidade de relevância do tópico
- capacidade de resposta a issues (se disponível)
Agrupe resultados em:
- Gemas ativas (commits recentes, velocidade crescente)
- Gemas pré-tração (baixas estrelas, atividade recente)
- Preenchimentos de lacunas (repositórios que conectam dois clusters de tópicos)
Fase 7 — Saída
Retorne uma tabela markdown ranqueada com colunas:
repositório | estrelas | idade | último push | por que é uma gema
Inclua uma nota metodológica curta e uma ressalva sobre limites de taxa da API.
Tratamento de erros
- Em HTTP 403 (limite de taxa secundário): durma e repita com backoff exponencial.
- Em HTTP 422 (consulta muito complexa): simplifique a consulta removendo o qualificador menos importante e repita.
- Em resultados vazios para uma faixa de estrelas: pule a faixa e continue.
Limitações
- O GitHub Search limita cada consulta a 1.000 resultados; o fatiamento mitiga, mas não elimina isso.
- A velocidade de estrelas é ruidosa para repositórios muito novos (< 30 dias).
- O tamanho do README é um proxy, não uma garantia de qualidade.