TypeScript Repository Indexing for Code Agent Retrieval

1. Problem Statement

The paper addresses a critical bottleneck in LLM-based code agents (e.g., Claude Code) regarding context retrieval.

• The Challenge: Effective code agents require retrieving not just relevant code snippets, but also their structural relationships (call chains, type dependencies, and dependency graphs).
• Limitations of Existing Methods:
  • Command-line exploration (grep/find): Keyword-driven, misses non-lexical relationships, and generates high noise.
  • Similarity-based retrieval (Vector/Embeddings): Struggles to capture structural logic like call chains or type definitions, especially when lexical overlap is weak.
  • Current Graph-based Indexing (ABCoder): While effective at preserving structure, the existing implementation for TypeScript relies on a hybrid architecture: Tree-sitter (for syntax) + Language Server Protocol (LSP) (for semantics).
• The Specific Bottleneck: The LSP-based approach requires a separate JSON-RPC call for every single symbol lookup (e.g., resolving an import, a method call, or a type reference). In large TypeScript repositories, this results in thousands of sequential network-like calls, making the indexing process prohibitively slow and inefficient.

2. Methodology: abcoder-ts-parser

The authors propose abcoder-ts-parser, a new parser built directly on the TypeScript Compiler API to eliminate the LSP overhead.

• Core Architecture:
  • Instead of using an external language server, the parser loads the entire project into a single in-process compiler instance.
  • It directly accesses the Abstract Syntax Tree (AST), semantic information, and module resolution logic from the compiler's memory.
  • This allows for batch processing of symbol resolution without external RPC calls.
• Parsing Workflow:
  1. Static Analysis: The parser performs a one-pass analysis of the codebase.
  2. Entity Extraction: It identifies functions, types, and variables, recording their signatures, source text, and file locations.
  3. Symbol Resolution: A custom symbol resolver traces references through import chains, aliases, re-exports, and barrel files to find the original declaration, ensuring dependency edges point to actual definitions rather than intermediate exports.
  4. Graph Construction: It constructs a UniAST (Universal Abstract Syntax Tree) index, a language-agnostic, hierarchical JSON format.
• Output Structure (UniAST):
  • Organizes code into Modules, Packages (files), and Entities.
  • Captures four specific relationship types: Dependency (calls/references), Reference (inverse), Implementation (interface to class), and Group (logical units like enums).
  • This structure enables bidirectional graph traversal (e.g., finding all callers and callees of a function).

3. Key Contributions

1. Novel Parser Design: The first TypeScript parser for the ABCoder framework that bypasses the LSP/JSON-RPC bottleneck by utilizing the native TypeScript Compiler API.
2. Efficiency Optimization: By moving from per-symbol RPC calls to in-memory batch resolution, the system drastically reduces indexing time for large codebases.
3. Robust Validation: The parser includes a comprehensive test suite (175 test cases, ~7KLOC of test code) with high coverage (71.75% overall line coverage, >80% for core modules), ensuring accurate entity identification and dependency tracing.
4. Open Source Release: The tool is released as a standalone CLI and npm package, integrated into the ABCoder ecosystem.

4. Results and Evaluation

The authors evaluated the parser on three open-source TypeScript projects ranging from 147K to 1.23M lines of code (Excalidraw, Outline, and Sentry).

• Performance Metrics:
  • Excalidraw (147K LOC): Parsed in 35.2 seconds.
  • Outline (234K LOC): Parsed in 239.9 seconds.
  • Sentry (1.23M LOC): Parsed in 705.6 seconds (~12 minutes).
• Comparison:
  • Compared to ABCoder's existing Python parser (which uses Tree-sitter + LSP) on Django (160K LOC), which took 603 seconds, the new TypeScript parser processed a comparable 147K LOC project in 35 seconds.
  • This represents a ~17x speedup for similar code volumes, demonstrating that avoiding individual symbol-resolution RPC calls yields substantial performance gains.
• Reliability: The parser successfully handles complex TypeScript features like re-exports and barrel files, producing reliable indexes that accurately map dependencies to their true definitions.

5. Significance

• Enabling Large-Scale Code Agents: The significant reduction in indexing time makes graph-based retrieval feasible for massive enterprise repositories, which were previously too slow to index using LSP-based methods.
• Improved Agent Reasoning: By providing agents with a high-quality, function-level graph index, the system allows LLMs to reason about code as a network of connected entities rather than isolated text chunks. This directly improves the agent's ability to fix bugs spanning multiple files or understand complex type dependencies.
• Practical Integration: The tool is designed for real-world workflows, supporting monorepos and offering fast turnaround times suitable for both initial indexing and incremental updates during development.

In conclusion, abcoder-ts-parser solves the scalability issue of TypeScript code indexing for AI agents, bridging the gap between the need for deep semantic understanding and the practical constraints of indexing massive codebases.