2
realknove
4 min de leitura ·

Pitch: Criei o RepoXray: uma CLI em Go para fazer um “raio-x” de projetos open-source

Nos últimos dias eu comecei um projeto open-source chamado RepoXray.

A ideia nasceu de uma pergunta simples:

Como saber se um repositório open-source está realmente preparado para receber usuários, contribuidores e confiança da comunidade?

Muitos projetos têm código bom, mas falham em coisas básicas:

  • não têm licença clara;
  • não têm CI;
  • não têm CONTRIBUTING.md;
  • não têm SECURITY.md;
  • não têm templates de issue ou pull request;
  • não deixam claro como alguém pode contribuir;
  • não mostram sinais mínimos de maturidade.

E isso importa.

Porque open-source não é só código.
Open-source também é manutenção, confiança, documentação, segurança, onboarding e previsibilidade.

Foi daí que surgiu o RepoXray.

O que é o RepoXray?

O RepoXray é uma CLI escrita em Go que analisa um repositório e gera um relatório de saúde, maturidade e manutenibilidade.

A ideia é funcionar como um “raio-x” do projeto.

Você roda:

repoxray scan .

Ou analisa um repositório remoto:

repoxray scan github.com/owner/repo

E recebe um relatório com:

  • score de maturidade;
  • pontos fortes;
  • warnings;
  • problemas críticos;
  • recomendações práticas;
  • sinais ausentes no projeto.

Exemplo de coisas que ele verifica:

  • README.md;
  • licença;
  • arquivos de pacote como go.mod, package.json, Cargo.toml;
  • testes;
  • Git repository;
  • GitHub Actions;
  • CONTRIBUTING.md;
  • CODE_OF_CONDUCT.md;
  • SECURITY.md;
  • issue templates;
  • pull request template.

Por que isso existe?

Porque muitos projetos open-source são avaliados de forma subjetiva.

Às vezes olhamos estrelas, número de commits ou popularidade. Mas esses sinais nem sempre dizem se o projeto é saudável.

Um projeto pode ter muitas estrelas e ainda assim ser difícil de contribuir.

Um projeto pode ter código excelente e ainda assim não ter licença.

Um projeto pode parecer ativo, mas não ter CI, política de segurança ou documentação para novos contribuidores.

O RepoXray tenta transformar esses sinais em algo visível.

Não é uma ferramenta para “julgar” projetos.

É uma ferramenta para ajudar maintainers e contribuidores a enxergarem o que pode melhorar.

O que ele muda para projetos open-source?

Para maintainers, ele pode servir como checklist inicial de maturidade.

Antes de divulgar um projeto, você pode rodar o RepoXray e perguntar:

Meu projeto está minimamente preparado para receber usuários e contribuidores?

Para contribuidores, ele ajuda a entender se um repositório tem sinais bons de manutenção.

Para empresas ou times, ele pode ser usado como uma primeira leitura da saúde de projetos internos ou dependências open-source.

Para quem está começando no open-source, ele também funciona como ferramenta educativa: mostra quais arquivos e práticas fazem um projeto parecer mais confiável.

O projeto ainda está no começo

O RepoXray está em fase inicial.

A primeira versão ainda é simples e determinística. Ele não usa IA, não envia dados para APIs externas e não tenta fazer uma análise mágica do projeto.

Ele verifica sinais objetivos.

Arquivo existe?
Tem CI?
Tem licença?
Tem política de segurança?
Tem templates?
Tem testes?

A ideia é começar simples e evoluir com o tempo.

Algumas coisas que quero adicionar depois:

  • análise mais profunda de GitHub Actions;
  • suporte melhor para múltiplas licenças;
  • relatórios em JSON e Markdown;
  • comparação entre repositórios;
  • análise de dependências;
  • badge de maturidade;
  • integração com GitHub API;
  • recomendações mais contextuais;
  • scoring por categorias, como documentação, segurança, CI e contributor readiness.

Por que Go?

Escolhi Go porque queria uma ferramenta simples, rápida, fácil de instalar e fácil de distribuir.

RepoXray não precisa ser complexo para ser útil.

A proposta é ser uma CLI direta:

repoxray scan github.com/realknove/repoxray

E pronto: você recebe um diagnóstico prático.

O que eu quero com esse projeto

Meu objetivo é construir uma ferramenta open-source pequena, útil e bem mantida.

Não quero que o RepoXray seja só mais uma CLI esquecida.

Quero que ele vire uma forma simples de responder:

“Esse projeto está pronto para crescer?”

E também:

“O que falta para ele parecer mais confiável para a comunidade?”

Open-source precisa de código bom, mas também precisa de estrutura.

O RepoXray tenta ajudar nessa segunda parte.

Repositório

O projeto está aqui:

https://github.com/realknove/repoxray/

Ainda está no começo, então feedback é muito bem-vindo.

Se você mantém um projeto open-source, rode o RepoXray e veja o que ele aponta.

Se você contribui com open-source, talvez ele ajude a enxergar melhor o que torna um projeto saudável.

E se você quiser contribuir com ideias, checks novos ou melhorias no scoring, vou gostar bastante de receber feedback.

Carregando publicação patrocinada...
1

Interessante, realmente existem vários repos abandonados, ou repos de baixa qualidade e mesmo assim com muitas stars... Por outro lado existem repos como awesome lists q n possuem arquivo de pacote, portanto o score seria depreciado.

Seria legal ter uma espécie de panorama de balanço entre commits, pull requets e outras análises como complexidade do repo: talvez tamanho do código?
Saber se aquele repo tem muitas issues abertas q nunca foram respondidas, prazo medio para uma issue ser respondida ou pr mergeado ou pelo menos respondido, ja q nem todo pr é aceito. Enfim, da pra ter varias métricas.

Tbm acho q o modelo de website seria melhor ux. Mas da mais trabalho para manter, claro. E instalar coisas na maquina q são usadas poucas vezes trás bastante preguiça kkk.

Eu fiz algo similar em outro projeto meu, score de acordo com quantidade de commits e stars, e tempo de inatividade para tentar achar os melhores repos de um nicho (open source games), dai usa log tipo IDF para n ter pesos desproporcionais etc.

Se tiver animado posso contribuir tbm.

Enfim, vlw , vou testar em breve

1

Você tocou em vários pontos que fazem bastante sentido.

Sobre repos como awesome lists, documentação, templates ou projetos que não têm package.json, concordo totalmente: o score não pode simplesmente penalizar esse tipo de repositório como se fosse um app/lib comum. Uma das coisas que quero melhorar é justamente classificar melhor o tipo do repo antes de calcular o diagnóstico. Então um awesome list, por exemplo, deveria ser avaliado por sinais diferentes de um projeto Node/Rust/Go.

A ideia do RepoXray também não é ser só um “score mágico”, mas mais um raio-x com sinais explicáveis: o que está bom, o que está ausente, o que pode indicar abandono, e onde talvez exista risco para quem quer usar ou contribuir. Então métricas como equilíbrio entre commits, PRs, issues abertas, tempo médio de resposta, PRs mergeados/respondidos e atividade recente fazem muito sentido para uma próxima etapa.

Também gostei bastante da ideia de evitar pesos desproporcionais. Algo como normalização por tipo de projeto/nicho pode deixar a análise bem mais justa, em vez de comparar um awesome list com uma lib ativa ou uma aplicação grande.

Sobre website: concordo também. CLI é boa para devs testarem rápido e integrar em workflows, mas uma versão web provavelmente deixaria a experiência bem mais acessível para quem só quer colar uma URL e entender o estado de um projeto sem instalar nada. Talvez o caminho seja manter os dois: core/CLI primeiro, e depois uma interface web usando o mesmo motor de análise.

E sobre contribuir: seria muito bem-vindo! Principalmente porque você já parece ter pensado em problemas parecidos e em métricas de ranking. Ainda estou na fase inicial, então contribuições em ideias de métricas, regras, exemplos de repos problemáticos, UX do relatório ou implementação mesmo seriam bem úteis.

Se quiser, posso abrir algumas issues com labels tipo good first issue, metrics, scoring e ux/report, aí fica mais fácil escolher algo pequeno para começar.

1

Top, da sim, podemos ir discutindo as ideias via issue: como arquitetura, requisitos, etc. Antes de ir para o código.

Sendo bem sincero... vc ja é dev a algum tempo eu acredito, pq q suas contas no tabnews/github são novas?

Infelizmente tem tido muitos fakes, repositórios envenenados etc. Pergunto pq fiquei um pouco apreensivo.

1