Quem mantém um projeto Delphi grande conhece a pergunta: se eu alterar ou remover esta unit, quais partes da aplicação serão afetadas? Encontrar as referências diretas na cláusula uses ajuda, mas nem sempre mostra o caminho completo. Uma unit pode ser usada por outra, que é usada por uma terceira, até chegar ao arquivo principal do projeto.

Foi para tornar essa investigação mais prática que criei o Delphi Unit Backtrace. A primeira versão pública já está disponível no GitHub, com executáveis para Win32 e Win64. A ferramenta recebe um arquivo .dproj e o nome da unit, descobre o fonte correspondente e percorre as dependências no sentido inverso: da unit escolhida até seus consumidores e, quando existe essa ligação, até o DPR.

O problema que a ferramenta resolve

Imagine que uExtrator aparece no uses de uRelatorio. Por sua vez, uRelatorio é usada por uFinanceiro, que participa do projeto principal. Uma busca por uExtrator revela apenas a primeira ligação. Para entender o impacto de uma mudança, você ainda precisa seguir manualmente as referências das outras units.

O Delphi Unit Backtrace transforma essa sequência em um caminho legível:

uExtrator -> uRelatorio -> uFinanceiro -> MeuProjeto [DPR]

Se houver outros caminhos, eles também aparecem. O relatório indica o arquivo, a seção e a linha da declaração uses que sustenta cada ligação. Assim, você consegue sair de uma suspeita genérica — “talvez esta unit seja usada pelo projeto” — para uma relação que pode ser conferida no código.

Do relatório ao grafo navegável

Além do relatório textual, a análise gera um graph.html que pode ser aberto diretamente no navegador. Nele, você pode procurar uma unit, selecionar um arquivo e destacar uma cadeia de dependências até o DPR. Se aquele arquivo não estiver ligado à entrada do projeto, a visualização mostra uma cadeia até um arquivo do próprio projeto, quando disponível.

A execução produz quatro arquivos:

• result.txt: caminhos reversos e evidências das declarações uses;
• graph.html: grafo navegável para explorar os consumidores;
• graph.dot: ligações em formato DOT, útil para outras ferramentas de visualização;
• analysis.log: decisões da análise, avisos e referências que não puderam ser resolvidas.

O programa considera o contexto do .dproj, incluindo caminhos de busca do projeto, e lê declarações uses das seções interface e implementation. Isso importa especialmente em projetos com bibliotecas externas, includes, namespaces e diferentes configurações de compilação.

Como experimentar

Baixe o ZIP da sua plataforma na página da versão mais recente, extraia os arquivos e execute o programa no diretório do projeto:

UnitBacktrace.exe --project "D:\Projetos\MeuERP\MeuERP.dproj" --unit uExtrator

Por padrão, os resultados são gravados na pasta analysis-output do diretório atual. Depois da execução, abra analysis-output\graph.html no navegador. Para escolher outra pasta, acrescente --output "D:\Analise" ao comando.

Se os fontes de uma biblioteca estiverem fora dos caminhos encontrados no projeto ou na instalação do Delphi, você pode acrescentar uma raiz de busca com --source-root DIR. Também é possível selecionar plataforma e configuração com --platform Win32|Win64 e --config Debug|Release.

O que o resultado significa — e o que não significa

O Delphi Unit Backtrace rastreia dependências declaradas em uses. Ele não verifica se algum símbolo da unit é realmente chamado e não modifica os arquivos do projeto. Seu papel é mostrar onde uma dependência foi declarada e por quais rotas ela se propaga.

Uma cadeia destacada no grafo representa uma rota, não a única rota possível. Remover uma declaração uses pode deixar outras ligações intactas. Se a execução terminar com código 3, o resultado foi gerado, mas a análise é parcial: consulte analysis.log antes de tomar decisões, pois pode haver fontes ou referências não resolvidas, ambiguidades ou uso do parser alternativo.

Em projetos com muitos ramos, a lista textual é limitada a 10.000 caminhos para evitar uma explosão de combinações; o grafo conserva as ligações alcançáveis. Esses limites ajudam a usar a ferramenta como apoio à investigação, com a revisão do código e a compilação continuando a fazer parte da decisão.

Projeto aberto para a comunidade Delphi

O código-fonte do Delphi Unit Backtrace está disponível no GitHub sob a licença Apache 2.0. O repositório traz instruções para compilar e testar no Delphi 13, além dos avisos de licença das dependências utilizadas.

Se você mantém um sistema Delphi e precisa entender o alcance de uma unit antes de refatorar, experimente a primeira versão pública. Abra o grafo, confira as linhas apontadas no relatório e veja por onde a dependência chega ao seu projeto. Sugestões, problemas encontrados e contribuições são bem-vindos no repositório.