Codebase Indexing (Індексація кодової бази)(Індексація кодової бази)

1. Огляд концепції та системна проблема

Корпоративні кодові бази налічують сотні тисяч рядків коду, тисячі файлів і глибокі дерева каталогів. Попри розширення контекстного вікна сучасних LLM до 1–2 мільйонів токенів, спроба завантажувати весь репозиторій у кожний запит є інженерно неможливою: це призводить до гігантських затримок (Time to First Token у десятки секунд), катастрофічних фінансових витрат і деградації уваги моделі (Lost-in-the-Middle).

З іншого боку, наївний поділ файлів на фіксовані блоки по 500 символів розриває тіла функцій навпіл, руйнуючи синтаксис. Codebase Indexing (індексація кодової бази) — це фундаментальна підсистема Agentic IDE та вайбкодингу. Вона перетворює плоский текст файлів на структуровану багатовимірну базу знань: будує синтаксичні дерева (AST), фіксує граф залежностей між модулями та створює гібридний (лексичний + семантичний) індекс для миттєвого вилучення мінімально необхідного контексту.

2. Архітектурна таксономія та ментальна модель

Сучасний індекс кодової бази організований у чотири паралельні шари:

┌─────────────────────────────────────────────────────────────┐
│                 CODEBASE INDEXING ARCHITECTURE              │
├─────────────────────────────────────────────────────────────┤
│ 1. Structural / AST Layer (Tree-sitter, SCIP, LSP Graph)    │
│    Класи, методи, інтерфейси, грати викликів caller/callee  │
├─────────────────────────────────────────────────────────────┤
│ 2. Lexical Inverted Index (BM25, Trigram ripgrep Engine)    │
│    Точний пошук імен змінних, констант, помилок компілятора │
├─────────────────────────────────────────────────────────────┤
│ 3. Semantic Vector Index (Dense Embeddings, HNSW / SQLite)  │
│    Пошук бізнес-логіки за концептуальним змістом наміру     │
├─────────────────────────────────────────────────────────────┤
│ 4. Synchronization Engine (Merkle Trees, Inotify / FSEvents)│
│    Інкрементальне оновлення змінених файлів за мілісекунди  │
└─────────────────────────────────────────────────────────────┘

1. Синтаксичний шар (AST & Symbol Index):
   • Парсить код за допомогою високошвидкісних компіляторів (Tree-sitter) для кожної мови (TypeScript, Rust, Python, Go).
   • Чанки формуються суворо по межах синтаксичних одиниць (окрема функція разом із JSDoc-коментарем або клас із сигнатурою).
2. Лексичний шар (Inverted Index / BM25):
   • Індексує точні ідентифікатори: назви функцій, типи помилок, константи. Гарантує, що запит за точним символом (AuthSessionProvider) знайде потрібний файл, навіть якщо семантична модель вважатиме його менш релевантним.
3. Семантичний векторний шар (Dense Semantic Index):
   • Пропускає кожен синтаксичний чанк через спеціалізовану модель ембеддінгів коду.
   • Зберігає вектори у локальній або хмарній базі даних (SQLite-vec, LanceDB, Qdrant) для пошуку за природною мовою («де генерується PDF інвойс»).
4. Інкрементальний менеджер синхронізації:
   • Будує дерево хешів (Merkle Tree) проекту. При зміні рядка оновлюється лише один чанк, не чіпаючи решту репозиторію.

3. Технічний пайплайн та внутрішня механіка

Життєвий цикл індексації та контекстного пошуку:

1. Фільтрація та виключення (Ingestion Gate): Сканер читає .gitignore, .cursorignore та виключає бінарні файли, lock-файли, скомпільований код (dist, .next) і секрети (.env*).
2. Синтаксичний парсинг (Tree-sitter Parsing): Кожен файл розбирається на вузли AST. Витягуються метадані: ім'я файлу, експортовані символи, список імпортованих бібліотек та вхідні типи.
3. Гібридне збереження:
   • Текстові токени записуються в інвертований індекс BM25.
   • Для кожного блоку генерується вектор фіксованої розмірності і записується у векторний простір HNSW.
4. Обробка користувацького запиту (Hybrid Querying): Коли інженер пише: «Як у нас валідуються платіжні вебхуки?»:
   • Запит розбивається на ключові слова (webhook, payment, validate) для BM25-пошуку.
   • Одночасно генерується ембеддінг запиту для семантичного векторного пошуку.
5. Злиття результатів (RRF & Reranking) та розширення графу: Алгоритм Reciprocal Rank Fusion поєднує два списки. Далі движок індексу дивиться на граф імпортів знайденого файлу і автоматично підтягує інтерфейси типів (Type Definitions), формуючи вичерпний і компактний контекст для промпту.

4. Практичні інженерні сценарії в продакшені

01. Миттєве занурення в незнайомий монорепозиторій на 500k рядків

Новий інженер починає роботу над складним фінтех-сервісом:

• Замість читання застарілої вікі він запитує Agentic IDE: «Який життєвий цикл проходження транзакції від клієнта до шлюзу?».
• Завдяки індексованому графу викликів IDE підтягує ланцюжок: PaymentController ➔ TransactionPipeline ➔ StripeGatewayAdapter, дозволяючи моделі згенерувати точну архітектурну схему.

02. Безпечний масштабний рефакторинг глобального інтерфейсу

Зміна сигнатури ключової функції автентифікації verifySession:

• Завдяки AST-індексу агент знаходить 100% місць виклику цієї функції по всьому репозиторію, включаючи неочевидні виклики у фонових cron-воркерах.
• Формує повний список файлів для оновлення без пропусків.

03. Нульова затримка при перемиканні між Git-гілками

Інженер перемикається з гілки feature-a на hotfix-main:

• Движок індексації перевіряє хеші файлів за деревом Меркла.
• Замість 10-хвилинного повного сканування репозиторію оновлюються лише 8 змінених файлів за 250 мілісекунд, не блокуючи роботу IDE.

5. Підводні камені, типові помилки та безпека

• Витік конфіденційних даних та секретів: Якщо забути додати файли .env, сертифікати SSL або дамп тестової бази до .cursorignore, їх вміст потрапить в ембеддінги і може бути переданий на сервери сторонніх провайдерів.
• Зависання CPU через папки вендорів (Runaway Indexing): Відсутність ігнорування каталогів node_modules, venv, target або build призводить до сканування сотень тисяч чужих бібліотек. Це викликає 100% утилізацію процесора і перегрів машини розробника.
• Розсинхронізація індексу (Stale Index Ghosting): Якщо фоновий демон індексації дає збій, агент починає оперувати застарілим контекстом: намагається імпортувати видалені модулі або звертається до старих сигнатур методів, спричиняючи галюцинації.
• Семантичний шум у схожих функціях: Якщо в репозиторії є десятки схожих утиліт (наприклад, копіпаста в різних мікросервісах), семантичний векторний пошук може повернути неправильну версію функції з іншого сервісу замість локальної.