Indeksowanie bazy kodu

1. Przegląd koncepcji i problem systemowy

Korporacyjne bazy kodu liczą setki tysięcy linii, tysiące plików i głębokie drzewa katalogów. Mimo rozszerzenia okna kontekstowego współczesnych LLM do 1–2 milionów tokenów, próba wczytania całego repozytorium przy każdym zapytaniu jest inżynieryjnie niewykonalna: prowadzi to do gigantycznych opóźnień (Time to First Token rzędu dziesiątek sekund), katastrofalnych kosztów finansowych oraz degradacji uwagi modelu (zjawisko Lost-in-the-Middle).

Z drugiej strony naiwny podział plików na stałe bloki po 500 znaków rozcina ciała funkcji na pół, niszcząc składnię. Codebase Indexing to fundamentalny podsystem Agentic IDE oraz wibecodingu. Przekształca płaski tekst plików w ustrukturyzowaną, wielowymiarową bazę wiedzy: buduje drzewa składniowe (AST), rejestruje graf zależności między modułami oraz tworzy hybrydowy indeks (leksykalny + semantyczny) do natychmiastowego wyodrębniania minimalnie niezbędnego kontekstu.

2. Taksonomia architektoniczna i model mentalny

Współczesny indeks bazy kodu zorganizowany jest w czterech równoległych warstwach:

┌─────────────────────────────────────────────────────────────┐
│                 ARCHITEKTURA INDEKSOWANIA KODU              │
├─────────────────────────────────────────────────────────────┤
│ 1. Warstwa strukturalna / AST (Tree-sitter, SCIP, graf LSP) │
│    Klasy, metody, interfejsy, graf wywołań caller/callee    │
├─────────────────────────────────────────────────────────────┤
│ 2. Odwrócony indeks leksykalny (BM25, silnik ripgrep Trigram)│
│    Dokładne wyszukiwanie nazw zmiennych, stałych, błędów   │
│    kompilatora                                              │
├─────────────────────────────────────────────────────────────┤
│ 3. Semantyczny indeks wektorowy (Gęste osadzenia, HNSW/SQLite)│
│    Wyszukiwanie logiki biznesowej na podstawie koncepcyjnego│
│    znaczenia intencji                                       │
├─────────────────────────────────────────────────────────────┤
│ 4. Silnik synchronizacji (Drzewa Merkle'a, Inotify/FSEvents)│
│    Inkrementalna aktualizacja zmodyfikowanych plików w       │
│    milisekundach                                            │
└─────────────────────────────────────────────────────────────┘

1. Warstwa składniowa (AST & Symbol Index):
   • Parsuje kod za pomocą wysokowydajnych kompilatorów (Tree-sitter) dla każdego języka (TypeScript, Rust, Python, Go).
   • Chunki są formowane ściśle według granic jednostek składniowych (pojedyncza funkcja wraz z komentarzem JSDoc lub klasa ze sygnaturą).
2. Warstwa leksykalna (Inverted Index / BM25):
   • Indeksuje dokładne identyfikatory: nazwy funkcji, typy błędów, stałe. Gwarantuje, że zapytanie o dokładny symbol (AuthSessionProvider) znajdzie właściwy plik, nawet jeśli model semantyczny uzna go za mniej istotny.
3. Warstwa wektorowa semantyczna (Dense Semantic Index):
   • Przepuszcza każdy chunk składniowy przez wyspecjalizowany model embeddingów kodu.
   • Przechowuje wektory w lokalnej lub chmurowej bazie danych (SQLite-vec, LanceDB, Qdrant) do wyszukiwania w języku naturalnym („gdzie generowany jest PDF faktury”).
4. Menedżer synchronizacji inkrementalnej:
   • Buduje drzewo hashów (Merkle Tree) projektu. Przy zmianie pojedynczej linii aktualizowany jest tylko jeden chunk, bez dotykania reszty repozytorium.

3. Pipeline techniczny i mechanika wewnętrzna

Cykl życia indeksowania i wyszukiwania kontekstowego:

1. Filtracja i wykluczenie (Ingestion Gate): Skaner czyta .gitignore, .cursorignore i pomija pliki binarne, lock-files, skompilowany kod (dist, .next) oraz sekrety (.env*).
2. Parsowanie składniowe (Tree-sitter Parsing): Każdy plik jest dekomponowany na węzły AST. Wyodrębniane są metadane: nazwa pliku, eksportowane symbole, lista importowanych bibliotek oraz typy wejściowe.
3. Hybrydowe przechowywanie:
   • Tokeny tekstowe zapisywane są w odwróconym indeksie BM25.
   • Dla każdego bloku generowany jest wektor o stałej wymiarowości i zapisywany w przestrzeni wektorowej HNSW.
4. Przetwarzanie zapytania użytkownika (Hybrid Querying): Gdy inżynier wpisuje: „Jak walidujemy webhooki płatności?”:
   • Zapytanie jest rozbijane na słowa kluczowe (webhook, payment, validate) do wyszukiwania BM25.
   • Jednocześnie generowany jest embedding zapytania do semantycznego wyszukiwania wektorowego.
5. Łączenie wyników (RRF & Reranking) i rozszerzanie grafu: Algorytm Reciprocal Rank Fusion łączy dwie listy. Następnie silnik indeksu analizuje graf importów znalezionego pliku i automatycznie dołącza definicje typów (Type Definitions), tworząc wyczerpujący, ale zwięzły kontekst dla promptu.

4. Praktyczne scenariusze inżynierskie w produkcji

01. Natychmiastowe zanurzenie się w nieznanym monorepo o rozmiarze 500k linii

Nowy inżynier zaczyna pracę nad złożoną usługą fintechową:

• Zamiast czytania przestarzałej wiki, pyta Agentic IDE: „Jaki jest cykl życia transakcji od klienta do bramki?”.
• Dzięki zaindeksowanemu grafowi wywołań IDE pobiera łańcuch: PaymentController ➔ TransactionPipeline ➔ StripeGatewayAdapter, pozwalając modelowi wygenerować precyzyjny schemat architektury.

02. Bezpieczny, masowy refaktoring globalnego interfejsu

Zmiana sygnatury kluczowej funkcji uwierzytelniającej verifySession:

• Dzięki indeksowi AST agent znajduje 100% miejsc wywołania tej funkcji w całym repozytorium, w tym nieoczywiste wywołania w tle procesów cron-worker.
• Tworzy pełną listę plików do aktualizacji bez pominięć.

03. Zerowe opóźnienie przy przełączaniu między gałęziami Git

Inżynier przełącza się z gałęzi feature-a na hotfix-main:

• Silnik indeksowania sprawdza hashe plików na podstawie drzewa Merkle'a.
• Zamiast 10-minutowego pełnego skanowania repozytorium, aktualizowanych jest tylko 8 zmienionych plików w ciągu 250 milisekund, nie blokując pracy IDE.

5. Pułapki, typowe błędy i bezpieczeństwo

• Wyciek danych poufnych i sekretów: Jeśli zapomnisz dodać pliki .env, certyfikaty SSL lub zrzut testowej bazy danych do .cursorignore, ich zawartość trafi do embeddingów i może zostać przesłana na serwery zewnętrznych dostawców.
• Zawieszenie CPU przez foldery vendorów (Runaway Indexing): Brak ignorowania katalogów node_modules, venv, target lub build prowadzi do skanowania setek tysięcy obcych bibliotek. Powoduje to 100% wykorzystanie procesora i przegrzewanie maszyny deweloperskiej.
• Desynchronizacja indeksu (Stale Index Ghosting): Jeśli demon indeksujący w tle ulegnie awarii, agent zacznie operować na przestarzałym kontekście: będzie próbował importować usunięte moduły lub odwoływać się do starych sygnatur metod, co powoduje halucynacje.
• Szum semantyczny w podobnych funkcjach: Jeśli w repozytorium znajduje się dziesiątki podobnych utility (np. kopiuj-wklej w różnych mikrousługach), semantyczne wyszukiwanie wektorowe może zwrócić niewłaściwą wersję funkcji z innego serwisu zamiast lokalnej.