Hledejte kód v grafu kódu

Tenhle návod ukáže, jak dostat repozitář do grafu kódu a pak jím odpovědět na otázku, kterou před refaktorem opravdu máš: co na tom závisí?

Graf kódu je databáze symbolů a hran. Vzniká parsováním registrovaných checkoutů přes tree-sitter. Nástroje jsou pro agenty: dostaneš se k nim tak, že se agenta zeptáš.

Než začneš

Graf indexuje Dart, JavaScript, TypeScript, TSX, PHP, Python, Rust, Zig, C, C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB a Ada. Soubory v jiném jazyce se neparsují, takže se neobjeví v search_code, code_symbol, code_callers, code_callees ani code_impact.

Co se dostane do indexu, určují ještě dvě věci:

V git work tree se výčet řídí příkazem git ls-files --cached --others --exclude-standard, takže platí každé .gitignore, vnořený ignore soubor, .git/info/exclude i globální soubor vyloučení. Tím se z grafu drží node_modules a výstup sestavení.
Generovaný Dart se zahodí vždy. Generované soubory se obvykle commitnou, takže samotný git by je nevyloučil a při každém codegenu by se v indexu přepisovaly.

Zaindexuj repozitář

Registrace checkoutu vyvolá RepoAdded a ta pro něj automaticky spustí pipeline index_code. Viz Přidejte repozitáře do pracovního prostoru.

Když chceš indexovat znovu ručně:

Otevři Nastavení → Pracovní prostor → Repozitáře.
Na řádku repozitáře klikni na tlačítko Indexovat kód.
Po dobu běhu tlačítko ukazuje hotové soubory z celkového počtu a ovládání zrušení. Po dokončení se z něj stane zaškrtnutí s počtem symbolů.

Graf je rozdělený podle pracovního prostoru, repozitáře a checkoutu: navázaný checkout je jeden oddíl a worktree každého prostoru má vlastní (klíčem je id izolovaného repozitáře).

Dvě omezení stojí za to znát, protože vysvětlí čekání, které vypadá jako zaseknutí:

Sledování souborů pustí na hostiteli najednou jen jeden běh indexace. Druhý checkout čeká. Pipeline index_code má zvlášť strop jeden běh na pracovní prostor, takže dva repozitáře ve stejném pracovním prostoru čekají ve frontě. Různé pracovní prostory můžou indexovat paralelně. Indexer sám serializuje dva běhy téhož checkoutu, aby start pipeline a průchod sledovače souborů nemohly tentýž checkout rozparsovat dvakrát.
Worktree nečinných prostorů (žádná zpráva za poslední týden) se nesledují ani neindexují. Navázané checkouty se sledují dál. Rozhodnutí přeskočit se po pěti minutách znovu ověří, takže prostor, který se zase rozběhne, se do indexace dostane.

Najdi symbol

Požádej agenta, ať hledá. Nástroj je search_code a potřebuje pracovní prostor i repozitář:

search_code(workspace_id: "...", repo_id: "...", query: "authentication middleware")

Id repozitářů bereš z list_repos. Volitelný argument mode je keyword, semantic nebo hybrid a výchozí je hybrid: BM25 nad názvy, signaturami a dokumentačními komentáři, sloučený s vektorovou podobností.

Každý výsledek nese id symbolu, název, kvalifikovaný název, druh, cestu k souboru, počáteční a koncový řádek a signaturu, když ji má. Id předáš každému dalšímu nástroji na téhle stránce.

Když znáš přesný název, vyhledej ho rovnou:

code_symbol(workspace_id: "...", repo_id: "...", name: "MyClass")

Sleduj volání

Oba berou symbol_id z výsledku hledání a volitelný limit (výchozí 50):

code_callers(workspace_id: "...", symbol_id: "...")
code_callees(workspace_id: "...", symbol_id: "...")

code_callers vrátí symboly s příchozí hranou k tomuhle. code_callees vrátí ty, na kterých tenhle závisí.

Zjisti, co by změna rozbila

Na tenhle nástroj celá stránka míří:

code_impact(workspace_id: "...", symbol_id: "...", depth: 3)

Spočítá poloměr zpětných závislostí: všechno, co na symbolu závisí přímo nebo tranzitivně po hranách calls, extends a implements (importy, mixes-in a generické reference v grafu jsou, ale tady se po nich nechodí). depth je nejvyšší počet skoků, od 1 do 6, výchozí 2.

Výsledek má tři pole:

root: symbol, na který ses ptal
impacted: dosažitelná množina včetně kořene v hloubce 0, každý se svým depth od kořene
edgeCount: kolik hran průchod překročil, jako počet, ne jako samotné hrany

Spusť ho, než přejmenuješ symbol nebo změníš signaturu, a agentovi dej seznam zasažených jako rozsah.

Výsledky se ověřují proti vlastní pracovní kopii volajícího

Když volá agent, id prostoru se doplní samo a výsledky se ověří proti pracovní kopii toho prostoru. Symbol, jehož soubor ve stromu volajícího už není, se vynechá. Odpověď nese počet staleOmitted a poznámku, že index je pro ty symboly zastaralý.

Proto se tvoje odpověď a odpověď agenta na stejný dotaz můžou lišit, stejně jako odpovědi agentů ve dvou prostorech. Všechny konverzace v prostoru sdílejí jeden worktree. Při chybě ověření se propouští: zastaralá odpověď je lepší než prázdná.

Až budeš chtět poloměr dopadu změny, požádej agenta, ať spustí code_impact (nebo review_studio.blastRadius). Viz Výpočet kontroly.

Sémantické vyhledávání potřebuje model embeddingů

Symboly a fakta dostanou vektor při zápisu, a jen když je nainstalovaný model embeddingů na zařízení. Do té doby nemá mode: "semantic" ani sémantická polovina hybridu proti čemu porovnávat a hledání je prakticky jen podle klíčových slov.

Model nainstaluj v Nastavení → Server → Diagnostika a soukromí → Sémantické vyhledávání, než začneš indexovat. Symbol dostane vektor, když se jeho soubor načte do indexu.

Každé nové sestavení binárky serveru navíc znovu připraví dyliby gramatik a změní jejich mtime. Tím zneplatní každý checkpoint indexu a při příštím běhu vynutí jeden úplný průchod každého checkoutu. Hashe se spočítají znovu, nezměněné soubory se znovu neextrahují.

Co je v grafu

Druhy symbolů: function, method, class, field, enum, constructor, getter, setter, typedef, extension, mixin, variable.

Druhy hran: calls, imports, extends, implements, mixes in, references.

Kanonické signatury těchhle nástrojů jsou na stránce Nástroje MCP.

Související návody

Související koncepty

Pracovní prostory a izolace