토스코어, AST 기반 정적 분석으로 '절대 Outdated 되지 않는' 판매자 입점 퍼널 문서 생성

기존 퍼널 문서의 한계

• 정보 불일치: 코드 변경 시 문서가 업데이트되지 않아 실제 플로우와 불일치 발생.
• 표현의 어려움: 조건부 분기, 다양한 경로를 다이어그램으로 시각화하기 어려움.
• 수동 업데이트의 비효율성: 코드 변경 시마다 문서를 수동으로 수정하는 것은 현실적으로 불가능.

정적 분석 기반 자동화 선택

• 런타임 분석 vs 정적 분석: 코드 실행 없이 텍스트로 분석하는 정적 분석(AST) 방식 선택.
• AST(Abstract Syntax Tree) 활용: TypeScript 컴파일러와 동일한 방식으로 코드를 트리 구조로 파싱하여 정보 추출.
• ts-morph 라이브러리 사용: 소스코드를 AST로 파싱.

퍼널 흐름 추출 과정

1. 페이지 파일 탐색: src/pages/ 디렉토리에서 페이지 진입점 파일 탐색.
2. Navigation 데이터 구조 설계: 경로(push/replace), 조건(condition), 쿼리 파라미터(queryParams), 코드 라인 번호(lineNumber), 소스 타입(sourceType) 등 맥락 정보 포함.
3. Navigation 패턴 추출: AST 파싱으로 router.push(), router.replace() 호출 탐색. 부모 노드 추적으로 조건문(if, 삼항 연산자)에서 분기 조건 추출.
4. 커스텀 훅 분석: 페이지가 import하는 훅 파일도 AST로 파싱하여 Navigation 호출 추적 및 출처 기록.
5. URL 상수 변환: 상수 형태의 URL을 실제 경로로 매핑하기 위한 상수 파일 파싱.
6. 그래프 구축: 추출된 Navigation edge들을 모아 진입점, 이탈점 포함 그래프 생성.
7. Mermaid 다이어그램 생성: 그래프를 Mermaid 문법의 플로우차트로 변환 (push: -->, replace: ==>).

완성된 다이어그램의 효과

• 신규 입사자 온보딩: 39개 페이지 파일 대신 다이어그램 하나로 퍼널 이해 시간 단축.
• 영향 범위 파악: 코드 수정 시 영향을 받는 페이지 및 경로를 쉽게 식별.
• 데드엔드 발견: Navigation 로직 누락으로 인한 이탈점 없는 페이지 자동 탐지.
• 코드-문서 동기화: 코드 변경 시 스크립트 재실행으로 문서 자동 업데이트.

결론

• AST 기반 정적 분석을 통해 '절대 Outdated 되지 않는' 퍼널 문서 자동 생성 가능.
• 라우팅 구조, 컴포넌트 의존성, API 호출 패턴 등 다양한 정보 추출 및 시각화에 활용 가능.
• '중요하지만 급하지 않은' 문서화 작업을 자동화하여 효율성 증대.