Este post também está disponível em inglês: Leia em inglês
No post anterior, compartilhei a ideia e motivação por trás do Project Insight — um projeto open source que estou desenvolvendo com o objetivo de criar um assistente inteligente capaz de entender e documentar código-fonte de forma interativa.
Neste post, vamos fazer uma breve análise na primeira parte técnica do projeto: o crawler.
O que é o crawler e por que ele é importante?
O crawler é o coração da etapa de análise estática do Project Insight. Ele é responsável por:
- Navegar pelos arquivos de um projeto Java.
- Identificar e extrair informações importantes como:
- Nome de classes e métodos.
- Modificadores (
public,private, etc). - Tipo de retorno.
- Linha em que cada item aparece no código.
Esses dados são armazenados em um banco local e futuramente utilizados pela IA para responder perguntas sobre o projeto de forma contextualizada.
Estrutura inicial do projeto
Para manter o projeto bem organizado desde o início, estruturei o crawler em módulos separados, cada um com uma responsabilidade clara:
project-insight-crawler/
├── crawler/
│ ├── database/ # Criação e conexão com o banco (SQLite)
│ ├── logger/ # Logger centralizado para o projeto
│ ├── models/ # Modelos para classes e métodos Java
│ ├── parser/ # Parser que extrai dados dos arquivos .java
│ ├── use_cases/ # Casos de uso como salvar dados no banco
│ └── __init__.py
├── tests/ # Testes unitários para os módulos principais
├── crawler.db # Banco de dados SQLite gerado localmente
├── main.py # Interface CLI do projeto
├── runner.py # Arquivo principal para execução do crawler
├── LICENSE
├── Makefile
├── poetry.lock
├── pyproject.toml
├── README.md
Essa organização permite que cada parte evolua de forma isolada, mantendo o código limpo e testável.
Decisões iniciais de arquitetura
Desde o início, tomei algumas decisões para facilitar o desenvolvimento e garantir qualidade:
- Linguagem: Python, pela familiaridade e agilidade para prototipar.
- Banco de dados: SQLite, por ser leve, simples de configurar e ideal para MVPs.
-
Gerenciador de dependências:
poetry, para facilitar a instalação e empacotamento. -
Qualidade de código: já estão configuradas ferramentas como:
-
ruff(linter e formatter) -
mypy(type checking) - Hooks de pre-commit
-
-
Automação e manutenção:
- GitHub Actions: para rodar testes automaticamente a cada push.
- Dependabot: para manter as dependências sempre atualizadas de forma segura.
Isso tudo ajuda a manter o padrão do código consistente e evita surpresas no futuro.
Próximos passos
No próximo post da série (Parte 2.2), vou mostrar em mais detalhes como funciona o parser que lê os arquivos .java linha por linha, identificando os blocos relevantes do código e extraindo as informações que alimentam o banco de dados.
E aí, o que achou?
Se curtiu o conteúdo até aqui, me segue aqui no Dev.to pra acompanhar os próximos posts sobre o Project Insight. Tô desenvolvendo tudo isso aos poucos e em tempo real, então qualquer sugestão, dúvida ou crítica é super bem-vinda nos comentários!
Link para o repositório: https://github.com/gustavogutkoski/project-insight-crawler
⚙️ Este texto foi escrito com o apoio de uma IA como assistente de escrita e revisão. Todas as ideias, estrutura do projeto e implementações técnicas são de autoria própria.
Top comments (2)
Trabalho em uma empresa hoje em que uma ideia assim iria facilitar muito a vida dos Devs kkk
Uma é possível a implementação do project insight em projetos de outras linguagens? Desde Low-level até high-level?
Em projetos com linguagens legadas como Cobol e Pascal, é possível a implementação?
A ideia é futuramente conseguir modularizar essa parte da linguagem e dai criar módulos separados para cada linguagem, por exemplo, ter a opção de fazer o build da aplicação escolhendo qual linguagem vc deseja mas por enquanto ta focado na linguagem Java pois ja tenho outros projetos pessoais que quero utilizar essa ferramenta quando estiver pronta