AST로 Outdated 없는 퍼널 문서 만들기

Context

신규 입사자가 39개 페이지 파일을 수동으로 읽으며 퍼널 흐름을 파악하는 데 며칠이 소요됐습니다. 기존 다이어그램 문서는 3개월 전 작성 후 업데이트되지 않아 코드와 불일치했으며, 수동 문서 작성도 3일 후 다른 팀원의 코드 변경으로 즉시 outdated 됐습니다. 조건부 분기(82개의 서로 다른 경로)를 표현하기 어려웠고, 매번 코드 변경 시마다 문서를 수동으로 동기화하는 것이 현실적으로 불가능했습니다.

Technical Solution

• AST 정적 분석 선택: ts-morph 라이브러리로 소스코드를 Abstract Syntax Tree로 파싱해 런타임 없이 모든 경로를 한 번에 추출
• NavigationEdge 데이터 구조 설계: from, to, method(push/replace), condition, queryParams, lineNumber, sourceType, hookName 필드로 네비게이션의 맥락 정보 저장
• 페이지 파일 추출: src/pages/funnel/ 디렉토리에서 components/, hooks/, _*.tsx 파일을 제외하고 index.tsx, universal.tsx 진입점만 필터링
• 호출식 추출: getDescendantsOfKind(SyntaxKind.CallExpression)로 전체 함수 호출을 찾은 후 router.push(), router.replace() 패턴 확인
• 조건문 추출: 네비게이션 노드에서 AST 부모 방향으로 거슬러 올라가며 가장 가까운 if문이나 삼항 연산자 검색
• 커스텀 훅 역추적: 페이지가 import하는 훅의 파일을 재귀적으로 분석해 로직 분리된 네비게이션도 포착
• Mermaid 플로우차트 생성: push는 단일 화살표(-->), replace는 이중 화살표(==>)로 구분해 브라우저 히스토리 차이 시각화

Impact

신규 입사자 온보딩 시간 단축: 39개 파일을 하나씩 읽을 필요 없이 다이어그램 하나로 전체 흐름을 제시 가능했습니다. 코드 변경 시 자동 문서 동기화로 outdated 문서 문제 해결했습니다. 데드엔드 페이지(네비게이션이 없는 페이지) 자동 탐지로 개발 중 실수로 빠진 네비게이션을 발견했습니다.

Key Takeaway

AST 정적 분석을 활용하면 코드가 변경될 때마다 자동으로 동기화되는 절대 outdated 되지 않는 문서를 생성할 수 있습니다. 라우팅 구조, 컴포넌트 의존성, API 호출 패턴 등 코드에 명시된 정보를 자동 추출해 문서화하는 방식으로 수동 문서 작성의 부담을 없앨 수 있습니다.