토스팀은 복잡한 판매자 입점 퍼널을 효율적으로 관리하기 위해 코드를 정적으로 분석하여 자동으로 업데이트되는 퍼널 문서를 구축했습니다. 기존의 수동 문서는 빈번한 코드 변경을 따라가지 못해 실효성을 잃었으나, ts-morph와 AST(Abstract Syntax Tree) 분석을 통해 코드와 100% 일치하는 흐름도를 생성할 수 있게 되었습니다. 이를 통해 개발자는 복잡한 조건부 분기와 페이지 이동 로직을 별도의 문서 작업 없이도 시각적으로 정확하게 파악할 수 있게 되었습니다.

수동 문서화의 한계와 정적 분석의 선택

문서의 파편화: 수기로 작성된 다이어그램은 코드가 수정될 때마다 즉시 업데이트되지 않아 실제 동작과 문서가 불일치하는 'Outdated' 문제가 발생합니다.
복잡한 분기 처리의 어려움: 수십 개의 페이지와 80여 개의 조건부 분기를 시각적 도구로 일일이 표현하는 것은 휴먼 에러의 위험이 크고 관리가 불가능합니다.
정적 분석 채택: 런타임 분석은 모든 경로를 직접 실행해야 하는 번거로움이 있지만, AST를 활용한 정적 분석은 코드를 텍스트로 읽어 모든 잠재적 경로를 빠르고 안전하게 추출할 수 있습니다.

Navigation Edge 데이터 구조 설계

맥락 정보 포함: 단순한 이동 경로(A → B)를 넘어, 이동 방식(push vs replace), 실행 조건, 쿼리 파라미터 등의 상세 데이터를 포함하는 NavigationEdge 인터페이스를 설계했습니다.
추적 가능성 확보: 코드 내 정확한 위치(lineNumber)와 호출 출처(sourceType)를 저장하여 다이어그램에서 실제 소스 코드로 즉시 연결될 수 있는 기반을 마련했습니다.

AST를 활용한 로직 추출 및 조건문 파싱

패턴 감지: ts-morph를 사용하여 프로젝트 내 페이지 파일을 탐색하고, router.push() 또는 router.replace()와 같은 함수 호출 패턴을 감지합니다.
상위 노드 추적: 특정 이동 로직이 발견되면 AST의 부모 방향으로 거슬러 올라가 가장 가까운 if문이나 삼항 연산자의 텍스트를 추출함으로써 이동 조건(Condition)을 파악합니다.

커스텀 훅 및 URL 상수의 역추적

숨은 로직 탐색: 페이지 컴포넌트 내부뿐만 아니라, import 구문을 분석하여 커스텀 훅 내부에 숨겨진 이동 로직까지 추적하여 데이터 누락을 방지합니다.
상수 해독: URLS.FUNNEL.PAY_METHOD와 같이 상수로 정의된 목적지를 실제 URL 경로로 변환하기 위해 상수 정의 파일을 별도로 파싱하여 매핑 테이블을 구축했습니다.

실용적인 결론 복잡도가 높은 서비스일수록 문서와 코드의 동기화는 자동화되어야 합니다. ts-morph와 같은 도구를 활용해 소스 코드를 단일 진실 공급원(Single Source of Truth)으로 삼는 자동화 문서를 구축하면, 불필요한 커뮤니케이션 비용을 줄이고 퍼널 전체의 비즈니스 로직을 명확하게 시각화할 수 있습니다.