𝗕𝗲𝘆𝗼𝗻𝗱 𝗠𝗶𝘀𝘀𝗶𝗻𝗴 𝗘𝘅𝗽𝗼𝗿𝘁𝘀: 𝗕𝘂𝗶𝗹𝗱𝗶𝗻𝗴 𝗮𝗻 𝗘𝗮𝗿𝗹𝘆 𝗚𝗮𝗿𝗯𝗮𝗴𝗲 𝗖𝗼𝗹𝗹𝗲𝗰𝘁𝗼𝗿

I tried to use a standard plugin to fix missing links in Webpack documentation. It failed.

Integrating a plugin into a large codebase is not a simple task. It became an architectural challenge. I had to manage Abstract Syntax Tree (AST) manipulation, memory use, and recursive loops.

The Problem with Standard Plugins

I ran three experiments to find a solution.

Experiment 1: The plugin recovered 135 types. However, it put them in an internal module. Our tool created a separate folder for them. We had to sort them manually. The documentation was also structurally wrong.

Experiment 2: I turned on a setting to hide external types. This worked for some things. It reduced the payload to 60 Webpack types. But TypeDoc ignored nested dependencies. It left many types hidden while they still used memory.

Experiment 3: I tried to map types back to their original modules. This caused a recursive loop. The plugin kept extracting nested interfaces until it created 630 types. The documentation was full of noise. It ruined the user experience.

The Solution: Early Garbage Collection

I needed the types in their correct modules without the extra noise. I stopped trying to fix the output and started fixing the process.

I used a hook called EVENT_RESOLVE_END. This let me intercept the AST right after resolution. I did this before TypeDoc assigned categories or used heavy memory.

My logic followed three steps:

The result: I saved 240 vital types. They are now visible and correctly routed. I avoided the recursive noise of the third experiment.

Lessons Learned

• Handle ASTs early. Removing unneeded nodes prevents memory waste later. • Use hooks instead of hacks. Understanding the compiler lifecycle allows for clean work. • Feedback improves architecture. Maintainer reviews helped me build a better system. • More data is not better. Good engineering means finding the balance between data and usability.

Missing Exports 문제를 넘어: Webpack의 TypeDoc AST를 위한 조기 가비지 컬렉터 구축하기

TypeDoc을 사용하여 API 문서를 생성할 때, Webpack과 같은 번들러를 함께 사용하면 종종 "누락된 export(missing exports)" 문제에 직면하게 됩니다. 분명 코드에는 존재하지만, 생성된 문서에는 나타나지 않는 export들이 있는 것이죠.

이 글에서는 이 문제의 근본 원인을 파헤치고, Webpack의 TypeDoc AST(Abstract Syntax Tree)를 위해 불필요한 노드를 조기에 정리하는 '가비지 컬렉터(Garbage Collector)'를 구축하는 방법을 소개합니다.

문제점: 왜 Export가 누락될까요?

Webpack은 모듈을 번들링하고 최적화하는 과정에서 코드를 재구성합니다. 이 과정에서 다음과 같은 일이 발생할 수 있습니다:

  1. 코드 변형: Webpack의 로더나 플러그인이 코드를 변형하여 TypeDoc이 원래의 구조를 파악하기 어렵게 만듭니다.
  2. 트리 쉐이킹(Tree Shaking): 사용되지 않는다고 판단된 코드가 번들 과정에서 제거되면서, TypeDoc이 해당 export를 찾지 못하게 됩니다.
  3. AST 불일치: Webpack이 생성한 AST와 TypeDoc이 기대하는 AST 구조 사이에 차이가 발생합니다.

결과적으로 TypeDoc은 유효한 export를 찾지 못하고, 문서에는 중요한 API 정보가 누락됩니다.

해결책: 조기 가비지 컬렉터 (Early Garbage Collector)

단순히 누락된 export를 수동으로 추가하는 것은 임시방편일 뿐입니다. 근본적인 해결을 위해서는 AST 단계에서부터 불필요하거나 잘못된 노드를 식별하고 제거하는 프로세스가 필요합니다.

제가 제안하는 방식은 TypeDoc이 전체 문서를 생성하기 전, AST를 순회하며 "죽은(dead)" 노드들을 정리하는 조기 가비지 컬렉터를 도입하는 것입니다.

작동 방식

이 가비지 컬렉터는 다음과 같은 세 단계로 작동합니다.

1. AST 탐색 (Traversal)

먼저, Webpack에 의해 생성된 AST를 깊이 우선 탐색(DFS) 방식으로 순회합니다. 모든 노드를 방문하여 각 노드의 타입과 참조 관계를 확인합니다.

2. 참조 분석 (Reference Analysis)

각 노드가 실제로 사용되고 있는지, 혹은 다른 모듈에서 참조되고 있는지를 분석합니다.

3. 가지치기 (Pruning)

참조되지 않거나, Webpack의 변형으로 인해 유효하지 않게 된 노드들을 AST에서 제거합니다. 이를 통해 TypeDoc은 깨끗하고 정확한 AST를 바탕으로 문서를 생성할 수 있게 됩니다.

구현 시 고려사항

이러한 가비지 컬렉터를 구현할 때는 몇 가지 주의사항이 있습니다.

결론

Webpack과 TypeDoc을 함께 사용하는 환경에서 발생하는 export 누락 문제는 단순한 설정 오류가 아닌, AST 구조의 불일치에서 기인하는 경우가 많습니다. 조기 가비지 컬렉터와 같은 접근 방식을 통해 AST를 사전에 정제함으로써, 더욱 신뢰할 수 있는 API 문서를 자동화된 방식으로 생성할 수 있습니다.