TypeScript Repository Indexing for Code Agent Retrieval

논문 요약: 코드 에이전트 검색을 위한 TypeScript 저장소 인덱싱

1. 문제 정의 (Problem)

LLM 기반 코드 에이전트 (Code Agents) 의 성능은 작업 수행에 필요한 관련 코드 조각을 얼마나 정확하게 찾아내고 컨텍스트로 제공하는지 (Context Retrieval) 에 크게 의존합니다. 기존 접근 방식에는 다음과 같은 한계가 있었습니다.

• 명령어 기반 탐색 (Command-line Exploration): grep 등 키워드 검색에 의존하여 문법적 중복이 없는 관련 코드를 놓치거나, 불필요한 노이즈를 포함하는 문제가 있습니다.
• 유사도 기반 검색 (Similarity-based Retrieval): 키워드 매칭이나 벡터 임베딩을 사용하지만, 함수 간 호출 체인 (Call Chains) 이나 타입 의존성 같은 구조적 관계를 파악하는 데는 한계가 있습니다.
• 기존 ABCoder 프레임워크의 병목 현상: 기존 ABCoder 는 Tree-sitter(구문 분석) 와 LSP(언어 서버 프로토콜) 를 결합하여 사용했습니다. Tree-sitter 가 심볼을 찾으면, LSP 를 통해 각 심볼의 정의를 JSON-RPC 로 하나씩 조회해야 했습니다. 대규모 TypeScript 저장소의 경우, 이 심볼당 개별 RPC 호출이 누적되어 인덱싱 속도가 매우 느려지는 심각한 병목 현상이 발생했습니다.

2. 방법론 (Methodology)

저자들은 이러한 병목 현상을 해결하기 위해 **abcoder-ts-parser**라는 새로운 TypeScript 파서를 제안했습니다.

• TypeScript Compiler API 직접 활용:
  • 기존 LSP 기반 방식 (별도 프로세스 간 RPC 통신) 을 버리고, TypeScript 컴파일러 API 를 직접 활용하여 프로젝트 전체를 단일 인메모리 (in-process) 컴파일러 인스턴스에 로드합니다.
  • 이를 통해 AST(추상 구문 트리), 시맨틱 정보, 모듈 해석 결과를 외부 RPC 호출 없이 직접 접근할 수 있습니다.
• UniAST (Universal Abstract Syntax Tree) 인덱스 생성:
  • 파싱된 코드를 언어에 독립적인 UniAST 형식으로 변환합니다.
  • 함수, 타입, 변수 등 코드 엔티티와 그들 간의 의존성 (호출, 참조, 구현, 그룹화) 을 그래프 구조로 매핑합니다.
  • 심볼 해석 최적화: Import 체인, 별칭 (Alias), 재내보내기 (Re-export), 배럴 파일 (Barrel files) 등을 추적하여 최종 정의 (Original Declaration) 로 직접 연결되는 의존성 엣지를 생성합니다.
• 그래프 기반 검색 구조:
  • 생성된 인덱스는 단순한 텍스트 조각이 아닌, 엔티티 간의 관계를 표현하는 그래프입니다. 에이전트는 특정 함수를 기준으로 호출자 (Callers), 피호출자 (Callees), 의존 타입 등을 양방향으로 탐색할 수 있습니다.

3. 주요 기여 (Key Contributions)

1. 고성능 TypeScript 파서 개발: TypeScript Compiler API 를 기반으로 한 abcoder-ts-parser 를 개발하여, 기존 LSP 기반 아키텍처의 RPC 오버헤드를 제거했습니다.
2. 효율적인 인덱싱 아키텍처: 대규모 저장소에서도 단일 프로세스로 전체 분석을 수행하여 인덱싱 시간을 획기적으로 단축했습니다.
3. 정확한 구조적 관계 추출: 단순 키워드 매칭이 아닌, 타입 의존성과 호출 체인을 포함한 정밀한 그래프 인덱스를 제공하여 코드 에이전트의 추론 능력을 향상시킵니다.
4. 오픈 소스 및 검증: GitHub 및 npm 을 통해 오픈 소스로 공개되었으며, 175 개의 테스트 케이스로 정합성을 검증했습니다.

4. 실험 결과 (Results)

저자들은 3 개의 오픈 소스 TypeScript 프로젝트 (Excalidraw, Outline, Sentry) 를 대상으로 성능을 평가했습니다.

• 성능 비교:
  • Sentry (123 만 줄, 8,909 개 파일): 약 12 분 (705.6 초) 만에 인덱싱 완료.
  • Excalidraw (14.7 만 줄, 601 개 파일): 약 35 초 만에 인덱싱 완료.
  • 비교 대상: 기존 ABCoder 의 Python 파서 (Tree-sitter + LSP) 는 16 만 줄의 Django 코드를 파싱하는 데 603 초가 소요되었습니다. 반면, 새로운 파서는 유사한 규모의 TypeScript 코드 (Excalidraw) 를 35 초 만에 처리하여 약 17 배 이상의 속도 향상을 보였습니다.
• 정확도: 10 개의 테스트 스위트, 175 개의 테스트 케이스 중 174 개가 통과했으며, 핵심 모듈의 라인 커버리지는 80% 이상을 기록했습니다.

5. 의의 및 중요성 (Significance)

• 코드 에이전트 성능 향상: 정확한 구조적 컨텍스트 (호출 체인, 타입 의존성) 를 제공함으로써, 에이전트가 버그 수정이나 기능 추가 시 더 정확한 루트 원인을 파악하고 완성도 높은 패치를 제안할 수 있게 됩니다.
• 대규모 프로젝트 실용성: 수백만 줄의 코드를 가진 대규모 TypeScript 프로젝트에서도 실시간에 가깝게 인덱싱이 가능해져, 실제 개발 워크플로우에 통합할 수 있는 실용적인 도구가 되었습니다.
• 지속 가능한 유지보수: 오픈 소스 생태계 (CloudWeGo, ABCoder 커뮤니티) 와의 협력을 통해 지속적으로 발전하고 있으며, 모델 컨텍스트 프로토콜 (MCP) 을 통해 다양한 LLM 에이전트 (예: Claude Code) 와 쉽게 연동됩니다.

이 연구는 코드 에이전트가 "단순한 텍스트 검색"을 넘어 "코드 구조의 이해"를 바탕으로 작동할 수 있는 기반을 마련했다는 점에서 의미가 깊습니다.