Além de Exportações Ausentes: Construindo um Coletor de Lixo Antecipado

Tentei usar um plugin padrão para corrigir links ausentes na documentação do Webpack. Falhou.

Integrar um plugin em uma base de código grande não é uma tarefa simples. Tornou-se um desafio arquitetural. Tive que gerenciar a manipulação da Árvore de Sintaxe Abstrata (AST), o uso de memória e loops recursivos.

O Problema com Plugins Padrão

Realizei três experimentos para encontrar uma solução.

Experimento 1: O plugin recuperou 135 tipos. No entanto, ele os colocou em um módulo interno. Nossa ferramenta criou uma pasta separada para eles. Tivemos que organizá-los manualmente. A documentação também estava estruturalmente incorreta.

Experimento 2: Ativei uma configuração para ocultar tipos externos. Isso funcionou para algumas coisas. Reduziu o payload para 60 tipos do Webpack. Mas o TypeDoc ignorou dependências aninhadas. Ele deixou muitos tipos ocultos enquanto eles ainda consumiam memória.

Experimento 3: Tentei mapear os tipos de volta para seus módulos originais. Isso causou um loop recursivo. O plugin continuou extraindo interfaces aninhadas até criar 630 tipos. A documentação ficou cheia de ruído. Isso arruinou a experiência do usuário.

A Solução: Coleta de Lixo Antecipada

Eu precisava dos tipos em seus módulos corretos, sem o ruído extra. Parei de tentar corrigir a saída e comecei a corrigir o processo.

Usei um hook chamado EVENT_RESOLVE_END. Isso me permitiu interceptar a AST logo após a resolução. Fiz isso antes que o TypeDoc atribuísse categorias ou consumisse muita memória.

Minha lógica seguiu três etapas:

• Encontrar o módulo interno na AST.
• Verificar cada nó usando uma utilidade personalizada.
• Deletar o ruído. Usei project.removeReflection para deletar 300 nós desnecessários imediatamente. Isso permitiu que o Node.js liberasse a memória.
• Mover os tipos importantes. Mesclei os 300 tipos restantes no escopo raiz.

O resultado: salvei 240 tipos vitais. Eles agora estão visíveis e roteados corretamente. Evitei o ruído recursivo do terceiro experimento.

Lições Aprendidas

• Lide com ASTs precocemente. Remover nós desnecessários evita o desperdício de memória posteriormente. • Use hooks em vez de hacks. Compreender o ciclo de vida do compilador permite um trabalho limpo. • Feedback melhora a arquitetura. Revisões de mantenedores me ajudaram a construir um sistema melhor. • Mais dados não é melhor. Boa engenharia significa encontrar o equilíbrio entre dados e usabilidade.

Além de Exportações Ausentes: Construindo um Coletor de Lixo Antecipado para o AST do TypeDoc do Webpack

Ao construir documentação para projetos TypeScript de grande escala, um dos desafios mais comuns é garantir que a documentação reflita com precisão a API pública. O TypeDoc, o padrão da indústria para gerar documentação a partir de código-fonte TypeScript, faz um excelente trabalho nisso. No entanto, quando combinado com bundlers como o Webpack, as coisas podem ficar complicadas.

O Problema: Exportações Ausentes e ASTs Inchados

O trabalho principal do Webpack é agrupar (bundle) módulos. No processo, ele realiza várias transformações, incluindo o tree-shaking para remover código não utilizado. Embora isso seja benéfico para o bundle final, pode levar a problemas quando o TypeDoc tenta analisar o código.

O TypeDoc funciona analisando o código-fonte TypeScript em uma Árvore de Sintaxe Abstrata (AST - Abstract Syntax Tree). Ele então percorre essa árvore para gerar a documentação. Quando o Webpack está envolvido, o código sendo analisado pode já estar parcialmente transformado, o que pode resultar em:

1. Exportações Ausentes: Algumas exportações podem ser removidas