Grafos TP1 - Análise de Grafos com Dados do GitHub

Este projeto extrai e processa eventos, comentários e reviews do repositório GitHub LadybirdBrowser para análise de teoria dos grafos (trabalho prático TP1). Utiliza Python para extração de dados via API do GitHub e Java (Maven) para processamento e análise dos grafos.

Pré-requisitos

• Java 21 (para compilação Maven)
• Python 3.x com bibliotecas requests e python-dotenv
• Token do GitHub válido (armazenado em arquivo .env)
• Maven instalado para componentes Java

Instalação

1. Clone o repositório:

   git clone <url-do-repositorio>
   cd grafos-tp1

2. Instale as dependências Python:

   pip install requests python-dotenv

3. Configure o token do GitHub:

   • Crie um arquivo .env na raiz do projeto
   • Adicione: GITHUB_TOKEN=seu_token_aqui

4. Compile o projeto Java:

   mvn clean compile -f app/api/pom.xml

Estrutura do Projeto

grafos-tp1/
├── app/
│   ├── data/                          # Dados CSV extraídos
│   │   ├── issue_authors.csv          # Autores das issues
│   │   ├── closed_issues.csv          # Issues fechadas
│   │   ├── issue_comments.csv         # Comentários em issues
│   │   ├── pr_events.csv              # Eventos de pull requests
│   │   ├── pr_reviews.csv             # Reviews de pull requests
│   │   └── pr_comments.csv            # Comentários em PRs
│   │
│   ├── extraction/                    # Scripts Python para extração
│   │   ├── core/                      # Módulos principais
│   │   │   ├── api.py                 # Cliente da API GitHub
│   │   │   └── io.py                  # Operações de I/O
│   │   ├── comments.py                # Extração de comentários
│   │   ├── issues.py                  # Extração de issues
│   │   ├── prs.py                     # Extração de pull requests
│   │   └── main.py                    # Script principal de extração
│   │
│   ├── exports/                       # Arquivos GEXF exportados
│   │   ├── grafo_comentarios.gexf     # Grafo de comentários
│   │   ├── grafo_fechamentoissues.gexf # Grafo de fechamento
│   │   ├── grafo_pullrequests.gexf    # Grafo de pull requests
│   │   └── grafo_grafointegrado.gexf  # Grafo integrado
│   │
│   └── api/                           # Aplicação Java
│       └── src/main/java/com/grafos/puc/
│           ├── Main.java              # Classe principal
│           ├── model/                 # Modelos de grafo
│           │   ├── AbstractGraph.java
│           │   ├── AdjacencyListGraph.java
│           │   └── AdjacencyMatrixGraph.java
│           ├── loader/                # Carregadores de dados
│           │   ├── GerenciadorUnificado.java
│           │   ├── issues/            # Processamento de issues
│           │   ├── comentarios/       # Processamento de comentários
│           │   └── pullRequest/       # Processamento de PRs
│           ├── builder/               # Construtores de grafos
│           │   ├── GerenciadorGrafos.java
│           │   ├── ConstrutorGrafoComentarios.java
│           │   ├── ConstrutorGrafoFechamentoIssues.java
│           │   ├── ConstrutorGrafoReviewPullRequests.java
│           │   └── ConstrutorGrafoIntegrado.java
│           ├── service/               # Serviços de análise
│           │   ├── GraphMetricsService.java
│           │   └── metrics/           # Métricas específicas
│           └── ui/                    # Interface do usuário
│               ├── GerenciadorMenu.java
│               └── AnaliseGrafo.java
├── docs/                              # Documentação do projeto
│   ├── enunciado-tp1.pdf              # Enunciado do trabalho prático
│   ├── apresentacao.pdf               # Apresentação usada no vídeo
│   ├── relatorio-tp1.pdf              # Relatório final do TP1
│   └── LadybirdBrowser.md             # Sobre o repositório analisado
└── README.md                          # Este arquivo

Documentação

Na pasta docs/ você encontrará:

• LadybirdBrowser.md: Documentação detalhada sobre o repositório GitHub LadybirdBrowser que foi analisado, incluindo características do projeto, estatísticas de contribuição e padrões de desenvolvimento
• enunciado-tp1.pdf: Enunciado completo do trabalho prático, com especificações dos requisitos, objetivos e critérios de avaliação
• apresentacao.pdf: Slides da apresentação utilizada no vídeo de divulgação, contendo resumo visual dos resultados e metodologia
• relatorio-tp1.pdf: Relatório final detalhado com análise dos resultados, discussão das métricas obtidas e conclusões

Como Usar

1. Extração de Dados

Execute o script Python para buscar dados do GitHub:

python app/extraction/main.py

Dados extraídos:

• issue_comments.csv: Comentários em issues
• pr_comments.csv: Comentários em pull requests
• closed_issues.csv: Issues fechadas
• pr_events.csv: Eventos de PRs (abertura, fechamento, merge)
• pr_reviews.csv: Reviews de pull requests
• issue_authors.csv: Autores das issues

2. Análise com Java

Execute a aplicação Java para análise dos grafos:

mvn exec:java -Dexec.mainClass="com.grafos.puc.Main" -f app/api/pom.xml

Funcionalidades disponíveis:

• Escolha entre Lista de Adjacência ou Matriz de Adjacência
• Construção de 4 tipos de grafos diferentes
• Análise de métricas (centralidade, comunidades, estrutura)
• Exportação para formato GEXF

Tipos de Grafos Gerados

A aplicação Java constrói 4 tipos de grafos na seguinte ordem:

1. Grafo de Comentários Unificado

   • Representa interações através de comentários em issues e PRs
   • Arestas: usuário que comenta → autor do item

2. Grafo de Fechamento de Issues

   • Representa colaboração no fechamento de issues
   • Arestas: quem fecha → quem criou a issue

3. Grafo de Pull Requests (Reviews)

   • Representa interações através de reviews
   • Arestas: reviewer → autor do PR

4. Grafo Integrado Ponderado

   • Arestas ponderadas pela frequência de interação

Funcionalidades da Aplicação Java

Interface Interativa

• Menu principal com navegação intuitiva
• Análise individual de cada grafo
• Comparação entre grafos

Métricas Disponíveis

• Centralidade: Grau, Betweenness, Closeness
• Estrutura: Densidade, componentes conectados, diâmetro
• Comunidades: Detecção e análise de comunidades

Exportação

• Arquivos GEXF para visualização em ferramentas como Gephi
• Relatórios detalhados das métricas

Comandos Úteis

Verificar limite da API:

python app/extraction/check_rate_limit.py

Compilar apenas:

mvn clean compile -f app/api/pom.xml

Executar testes:

mvn test -f app/api/pom.xml

Estrutura dos Dados

Os dados extraídos representam interações no repositório, adequados para modelagem de grafos de colaboração entre usuários, incluindo:

• Redes de comentários e discussões
• Fluxos de trabalho de desenvolvimento
• Padrões de colaboração e review
• Hierarquias de contribuição

Contribuição

1. Faça um fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

Observações Importantes

• Todos os comandos devem ser executados a partir do diretório raiz devido aos contextos das pastas
• O token do GitHub é obrigatório para extração de dados
• Os arquivos CSV devem estar em app/data/ para a aplicação Java funcionar
• A aplicação suporta tanto grafos esparsos (lista) quanto densos (matriz)

Suporte

Para dúvidas ou problemas:

1. Verifique se todos os arquivos CSV estão presentes em app/data/
2. Confirme se o token do GitHub está configurado corretamente
3. Verifique se o Java 21 e Maven estão instalados
4. Execute os comandos a partir do diretório raiz do projeto