Preskočiť na obsah

CodeGraph: staticky odvodený graf kódu a schémy Laravel aplikácií ako lokálny MCP server

CodeGraph: staticky odvodený graf kódu a schémy Laravel aplikácií ako lokálny MCP server

V tomto článku opisujem CodeGraph, aplikáciu v paneli ponúk macOS a lokálny server protokolu Model Context Protocol (MCP), ktorý som vyvinul, aby zo zdrojového kódu a databázovej schémy mojich Laravel aplikácií zostavil typovaný graf. Graf odvodzujem výlučne statickou analýzou commitu origin/<vetva>: PHP sa parsuje knižnicou tree-sitter, Blade šablóny mojím vlastným skenerom a databázová schéma sa rekonštruuje prehratím migrácií. Nie je potrebné PHP, Docker ani živá databáza. Výsledok sa ukladá do jedného SQLite súboru na repozitár a AI asistentovi (Claude Desktop alebo Claude Code) je dostupný cez 14 nástrojov.

Každá hrana nesie polohu v zdrojovom kóde (file:line) a jednu z troch úrovní istoty (exact, inferred, candidate), takže príjemca rozlíši syntaktické fakty od heuristík. Na šiestich repozitároch, ktoré som mal nastavené 21. novembra 2026, majú grafy 624 až 25 225 uzlov, zostavia sa za 0,3 až 2,7 sekundy a 78 až 89 % miest volania sa rozlíši na konkrétnu metódu. V mojej každodennej práci nástroj skracuje lokalizáciu chyby zo stack trace alebo z textu zákazníckeho tiketu na malý počet ohraničených volaní nástrojov, ktoré vrátia dotknutú obrazovku, route, handler, validačné pravidlá, modely a tabuľky.

1 Úvod

V Laravel aplikácii vedie cesta od príznaku k príčine cez viacero typov artefaktov, ktoré samotný jazyk neprepája. URL je v súbore rout naviazaná na controller alebo Livewire komponent; komponent vykresľuje Blade view podľa názvu; view sa viaže na metódy komponentu atribútmi wire:; metóda validuje vstup a volá Eloquent modely a modely sa konvenciou mapujú na tabuľky definované postupne v mnohých migráciách. Väčšina týchto väzieb sú reťazce vyhodnocované až za behu, preto celú reťaz nesleduje textové vyhľadávanie ani jazykový server.

Na rovnakú ťažkosť som narazil pri práci s AI asistentom pre programovanie. Bez štruktúrneho indexu musí asistent reťaz objavovať čítaním súborov a textovým vyhľadávaním, čo spotrebúva jeho kontextové okno a nedáva žiadnu informáciu o tom, nakoľko je každá odvodená väzba spoľahlivá.

CodeGraph som vytvoril, aby tieto väzby vypočítal raz, vopred, a uložil ich ako dopytovateľný graf. Môj pôvodný cieľ, zaznamenaný v návrhovej špecifikácii zo 16. októbra 2026, bol úzky: ja alebo kolega z helpdesku vložíme do Clauda stack trace alebo text zákazníckeho tiketu a asistent dohľadá dotknutú obrazovku, route, komponent, validáciu, modely, tabuľky a texty prekladov. Odvtedy som projekt zovšeobecnil z jedného repozitára na ľubovoľný počet Laravel repozitárov, z ktorých každý sa sleduje na vlastnej vetve.

Systém opisujem v stave po 192 commitoch (16. október až 21. november 2026): približne 17 900 riadkov Swiftu v zdrojových súboroch a 13 700 riadkov v testoch. Všetky kvantitatívne tvrdenia pochádzajú z môjho zdrojového kódu, z mojich návrhových dokumentov v docs/superpowers/specs alebo z výstupu nástroja status bežiaceho servera.

2 Architektúra systému

CodeGraph dodávam ako jeden spustiteľný súbor s dvoma režimami. Bez argumentov je to SwiftUI aplikácia v paneli ponúk; s argumentom --mcp je to stdio MCP server, ktorý si Claude spúšťa sám. V režime MCP nesie štandardný výstup iba správy protokolu.

Architektúra CodeGraph: git klon a vendor cache vstupujú do indexera, ktorý zapisuje graph.sqlite čítaný MCP serverom

Súbor grafu je jediné rozhranie medzi stranou buildu a stranou dopytov; neotvára sa žiadny sieťový port.

Swift balík som rozdelil na tri targety:

Target

Zodpovednosť

Externé závislosti

CodeGraphCore

prístup ku gitu, analýza PHP a Blade, prehratie migrácií, úložisko grafu, dopyty, sťahovanie vendor balíkov, koordinácia buildu

swift-tree-sitter 0.25.0, tree-sitter-php 0.25.1, systémový SQLite

CodeGraphMCP

továreň servera, definície nástrojov, spúšťač nástrojov s poistkou veľkosti odpovede

MCP Swift SDK 0.12.1

CodeGraph

spustiteľný súbor: menu, okno nastavení, hárky pre prihlasovacie údaje a balíky

AppKit, SwiftUI

2.1 Zdroj pravdy

Graf staviám z refs/remotes/origin/<vetva>, nikdy nie z pracovného adresára ani z lokálnej vetvy. Súbory sa čítajú ako git bloby, takže checkout inej vetvy graf nemení a indexer do checkoutu nikdy nezasahuje. Jediným zápisom do repozitára je git fetch --no-tags --quiet origin <vetva>, ktorý sa vykoná najviac raz za päť minút s GIT_TERMINAL_PROMPT=0 a SSH BatchMode=yes. Watcher na vzdialenom refe a na packed-refs (FSEvents, oneskorenie 2 s) zachytí aj ručný fetch.

2.2 Build a konzistencia

Rebuild sa spustí, keď sa SHA sledovanej vetvy líši od SHA zaznamenaného v grafe alebo keď sa zmení odtlačok vendor cache. Každý build zapisujem do dočasného súboru a atomickým premenovaním ho presúvam na graph.sqlite, takže zlyhaný build ponechá predchádzajúci graf platný. Čítanie, ktoré sa stretne s premenovaním, sa raz zopakuje na novom spojení. Buildy a fetche sú medzi procesmi serializované pomocou flock na samostatných zámkových súboroch, vďaka čomu MCP proces udržiava graf aktuálny aj vtedy, keď aplikácia v paneli ponúk nebeží.

2.3 Vendor deklarácie

Laravel repozitár neobsahuje vendor/, no väčšina volaní v aplikačnom kóde smeruje do frameworku. Preto každý produkčný balík z composer.lock sťahujem ako zip distribúciu, extrahujem z neho iba deklarácie (triedy, dedenie, signatúry metód, návratové typy a docblock značky @mixin, @method, @property, @return) a výsledok ukladám do cache pod kľúčom name@reference. Telá vendor metód sa neindexujú. Prihlasovacie údaje sa čítajú z ~/.composer/auth.json alebo z macOS Keychain a nikdy sa neobjavia v logoch, stavových súboroch ani v odpovediach nástrojov. Neúspešné stiahnutie build nezhodí; graf sa postaví s tým, čo je v cache, a prebuduje sa, keď pribudnú ďalšie balíky.

3 Model grafu a extrakcia

Graf je orientovaný typovaný multigraf. Uzol má kľúč, druh, názov, voliteľný súbor s rozsahom riadkov a reťazcové atribúty. Hrana má zdroj, cieľ, druh, istotu a voliteľné file:line. Oboje ukladám do dvoch SQLite tabuliek indexovaných podľa (src, kind) a (dst, kind), s FTS5 tabuľkou (tokenizer unicode61, bez diakritiky) pre fulltextové vyhľadávanie.

3.1 Indexované zdroje

Zo sledovaného commitu indexujem app/, packages/*/src, routes/, resources/views/, lang/<locale>/*.php, migrácie aplikácie a lokálnych balíkov, service providery, _ide_helper.php, .phpstorm.meta.php a súbory composer.json. Testy a vendor/ sú vynechané.

3.2 Uzly

Skupina

Druhy uzlov

Pôvod

Štruktúra kódu

file, class, trait, interface, enum, method, property

tree-sitter PHP; trieda dostane aj rolu (Model, Controller, Livewire, ...)

Webová vrstva

route, view, kľúč prekladu, validačné pole

súbory rout, Blade šablóny, polia v lang/, rules() a validate()

Databáza

table, column, index, foreign key, migration

prehratie migrácií

Texty za behu

message

doslovný text z throw, abort, Log::*, flash, toast a validačných hlášok; dynamické časti sa nahradia znakom …

Udalosti

event

názvy Livewire eventov, kde sa stretávajú miesta dispatchu a listenery

Závislosti

package

composer.lock

Closures v routach sú reprezentované ako uzly metód (method:{closure}@<súbor>:<riadok>) a ich telá sa analyzujú ako každá iná metóda.

3.3 Hrany

Model definuje 23 druhov hrán:

Skupina

Druhy hrán

Význam

Štruktúra

DEFINES, EXTENDS, IMPLEMENTS, USES_TRAIT

súbor → trieda → člen; dedenie

Cesta požiadavky

ROUTES_TO, RENDERS, INCLUDES, WIRES

route → handler → view → vnorené view; view → metóda alebo property Livewire komponentu

Texty a vstup

USES_TRANSLATION, VALIDATES, EMITS

metóda alebo view → kľúč prekladu; pravidlá → pole; metóda → hláška

Dáta

MODEL_TABLE, RELATION, FK, ALTERS

model → tabuľka; model → model; stĺpec → stĺpec; migrácia → tabuľka

Volania

CALLS, REFERENCES, UNRESOLVED_CALL

metóda → metóda; metóda → trieda; metóda → nerozlíšený názov

Kontajner

BINDS, FACADE_OF

abstrakcia → konkrétna trieda; fasáda → konkrétna trieda

Udalosti

DISPATCHES, LISTENS, OBSERVES

miesto dispatchu → event, job, notifikácia alebo mailable; event → handler; observer → model

3.4 Istota

Nevykonávam úplnú inferenciu typov na spôsob PHPStanu. Namiesto toho každá hrana uvádza, ako vznikla:

Úroveň

Z čoho vznikla

Príklad

exact

zo syntaxe zdrojového kódu

self::m(), $this->m(), X::m(), new X

inferred

z typu: typehinty parametrov a návratových hodnôt, typované properties, docblocky, väzby kontajnera, fasády, Eloquent relácie, dedenie, @mixin a magické presmerovanie

$user->orders()->first()

candidate

iba zo zhody názvu

prijímateľ bez typu, ktorého názov metódy existuje najviac v 3 triedach repozitára

Volanie, ktoré sa nedá priradiť, sa stane hranou UNRESOLVED_CALL, ktorá je vždy candidate. Volanie do vendor kódu nikdy nie je označené ako exact, ak sa k nemu dospelo cez magickú metódu. Vendor triedy slúžia iba na rozlíšenie typov: sú vynechané z fulltextu aj z hľadania kandidátov, takže bežné názvy ako get alebo find nezahlcujú výsledky.

3.5 Fázy buildu

Indexer spracuje jeden commit v 13 usporiadaných fázach:

  1. Výber súborov

  2. Čítanie blobov cez git

  3. Deklarácie (triedy, metódy, properties)

  4. Tabuľka symbolov a mapy kontajnera (väzby, fasády)

  5. Eloquent modely a relácie

  6. Telá metód (volania, referencie, hlášky, dispatche)

  7. Routy vrátane rozvinutia Route::resource a prefixov skupín

  8. Views a Blade (@include, komponenty, väzby wire:)

  9. Listenery, hooky properties a observery

  10. Preklady

  11. Migrácie

  12. Validácie

  13. Composer balíky

Poradie je podstatné: fáza 9 beží po telách a views, aby boli všetky miesta dispatchu známe skôr, než sa pripoja listenery.

3.6 Schéma z migrácií

Databázovú schému odvodzujem prehratím tiel up() všetkých migrácií v poradí názvov súborov: Schema::create, Schema::table, odstránenia a premenovania. Raw SQL prechádza malým DDL parserom. Keď sa podmienka nedá staticky rozhodnúť, prehrajú sa všetky vetvy a dotknuté stĺpce sa označia ako podmienečné. Nerozpoznaný príkaz označí tabuľku ako možno neúplnú, namiesto toho, aby sa ticho ignoroval.

3.7 Varovania ako súčasť výsledku

Každé miesto, kde statická analýza končí, sa zaznamená ako typované varovanie s file:line: nerozlíšený názov view, cieľ wire:, ktorý neexistuje, dynamický názov route, chýbajúci preklad, názov eventu, ktorý nie je literál. Varovania sú uložené v grafe a dá sa na ne dopytovať, takže neúplná oblasť grafu je pre príjemcu viditeľná.

4 Dopytovacie rozhranie

MCP server ponúka 14 nástrojov. Všetky nástroje okrem rebuild iba čítajú a každý nástroj okrem list_repos prijíma názov repozitára, takže dáta rôznych repozitárov sa nikdy nemiešajú.

Nástroj

Vstup

Výsledok

list_repos

žiadny

nastavené repozitáre s vetvou, stavom, SHA vetvy a SHA grafu

status

repo

čas buildu, počty uzlov a hrán, klasifikácia miest volania, stav vendor balíkov, varovania

analyze_stacktrace

vložený trace alebo log

výnimka, správa, SQLSTATE s tabuľkou a stĺpcom, rámce namapované na metódy, views, routy a balíky, zodpovedajúce miesta throw

find_by_text

text videný na obrazovke

fulltextové zhody prevedené na obrazovky: view → komponent alebo controller → route

outline

trieda alebo súbor

dedenie, properties, metódy so signatúrami, routy, views, relácie, počty použití

node

kľúč alebo krátky názov

atribúty a hrany zoskupené podľa druhu

neighbors

kľúč, hĺbka 1–3

okolitý podgraf zoradený podľa hĺbky a istoty

path

dva kľúče

najviac 3 najkratšie cesty, najsilnejšia prvá (obojsmerné BFS, hĺbka ≤ 8)

table

názov tabuľky

stĺpce, typy, indexy, cudzie kľúče, migrácie, modely

route

URI alebo názov

handler, middleware, view, validácia

source

cesta, rozsah riadkov

úryvok súboru zo sledovaného commitu, najviac 300 riadkov

packages

voliteľný filter

Composer balíky so zamknutou verziou a obmedzením

warnings

druh, súbor

miesta, kde je graf neúplný

rebuild

repo

naplánuje fetch a nový build

4.1 Analýza stack trace

analyze_stacktrace prijíma riadok Laravel logu, kópiu z Ignition alebo holé dvojice path:line. Rámce v mojom kóde sa mapujú na uzly metód vrátane closures v routach. Rámec v skompilovanom Blade súbore sa mapuje späť na šablónu; vendor rámec sa mapuje na Composer balík so zamknutou verziou a prvý vendor rámec volaný z môjho kódu je označený ako vstupný. Ak číslo riadku leží mimo rozsahu metódy v sledovanom commite, rámec je označený ako nezhodný, čo znamená, že trace pochádza z inej verzie. Nezávisle od čísel riadkov sa miesta throw hľadajú zhodou statického textu správy výnimky (aspoň 8 znakov).

4.2 Ohraničené odpovede

Každá odpoveď zaberá kontextové okno asistenta. Na repozitári R3 (približne 11 200 uzlov) som nameral, že volanie neighbors v hĺbke 2 vrátilo 149 690 znakov, teda zhruba 37 000 tokenov, z čoho samotné hrany tvorili 91 000 znakov. Preto som zaviedol rozpočet 32 000 znakov pre node a neighbors a pevný strop 64 000 znakov pre každý nástroj.

Hrany sa vracajú v pevnom poradí: najprv podľa hĺbky, potom exact pred inferred pred candidate, potom môj kód pred vendor kódom. Odpoveď teda nikdy nezahodí hranu exact v prospech kandidáta. Čo sa nezmestí, je uvedené v poli omitted s počtami podľa druhu hrany a s offsetom ďalšej strany. Okrem toho sa z kódovania vynecháva predvolená istota (exact) a súbor zhodný so súborom zdrojového uzla.

4.3 Rozlíšenie názvov

Kľúč možno zadať ako krátky názov triedy, Class::method, tabuľku, view, názov route alebo samotný názov metódy. Nejednoznačný názov vráti štruktúrovaný zoznam najviac 10 kandidátov a neznámy názov najviac 5 návrhov z fulltextu. V R3 sa 117 z 826 názvov metód vyskytuje vo viacerých triedach, takže tento prípad je bežný.

5 Ako mi nástroj pomáha ako vývojárovi

5.1 Nameraný stav grafov

CodeGraph používam na šiestich Laravel repozitároch. Ich názvy sú pseudonymizované ako R1 až R6 a zoradené podľa veľkosti grafu. Tabuľka uvádza veľkosť a čas buildu každého grafu tak, ako ich 21. novembra 2026 vrátil nástroj status.

Repozitár

Uzly

Hrany

Čas buildu (s)

Vendor balíky v cache

R1

25 225

78 389

2,66

137

R2

19 739

47 755

2,61

177

R3

11 232

27 079

1,21

145 (+1 lokálny)

R4

8 832

21 006

0,84

104

R5

4 474

9 325

0,61

120

R6

624

474

0,28

97

Čas buildu pokrýva indexovanie jedného commitu s vendor deklaráciami, ktoré už sú v cache. Žiadny repozitár nehlásil chybu parsovania.

Podiel miest volania rozlíšených na konkrétnu metódu v šiestich repozitároch (78 až 89 %)

Jednotkou je miesto volania (jeden výraz volania), zatriedené podľa svojej najlepšej hrany. Skôr, než som pridal vendor deklarácie, nevznikla pre volanie na známom type, ktorého metóda patrila vendor triede, žiadna hrana a reťazec ako User::where()->orderBy()->first() sa po prvom volaní stratil. Tieto volania dnes tvoria podiel frameworku.

5.2 Účinky na moju prácu

  • Lokalizácia chyby zo stack trace. Vložím trace; jedno volanie vráti výnimku, dotknutú tabuľku a stĺpec zo SQLSTATE, metódu každého rámca a obrazovky a routy, ktoré k nej vedú. Súbory už neotváram rámec po rámci.

  • Lokalizácia zo slov zákazníka. Tiket zvyčajne cituje text z obrazovky. Fulltext nad hodnotami prekladov, views, routami, validačnými poľami a doslovnými hláškami, bez ohľadu na diakritiku, prevedie citovaný text na view, jeho komponent alebo controller a route.

  • Analýza dopadu pred zmenou. Vstupné hrany metódy, stĺpca alebo eventu ukážu, čo od nich závisí. Nástroj path odpovie, ako sa route dostane k tabuľke, a uvedie najslabšiu istotu na ceste.

  • Znalosť schémy bez databázy. Nástroj table vráti stĺpce, indexy, cudzie kľúče a migrácie, ktoré ich vytvorili, odvodené z migrácií sledovaného commitu.

  • Žiadne behové prostredie. Analýza nepotrebuje PHP, Docker ani databázu, takže funguje aj kolegovi, ktorý má iba klon. Keďže zdrojom je origin/<vetva>, odpovede opisujú zdieľaný kód, nie môj necommitnutý pracovný adresár.

  • Odstupňovaná dôvera. Hrana exact je syntaktický fakt. Pri hrane candidate server asistentovi ukladá, aby správanie overil nástrojom source. Znižuje sa tým riziko, že mi heuristická väzba bude predložená ako istá.

  • Úsporný kontext. Rozpočet 32 000 znakov a stránkovanie udržia štruktúrnu odpoveď približne na 8 000 tokenoch, kým neohraničená odpoveď dosiahla 37 000.

  • Aktuálnosť bez námahy. Graf sleduje vzdialenú vetvu automaticky a rebuild trvá na mojom najväčšom repozitári menej než tri sekundy.

5.3 Overenie

Systém testujem na troch úrovniach: zhruba 700 jednotkových a integračných testovacích funkcií nad malým fixture repozitárom podobným Laravelu, end-to-end testy, ktoré spúšťajú zostavenú binárku v režime MCP, a golden testy voči R3. Golden testy okrem iného overujú reťaz od route k jej Livewire komponentu, reálny stack trace, slovenský fulltextový dopyt a to, že sa po pridaní vendor deklarácií nestratí žiadna hrana vlastného kódu. Overujú aj to, že úplný build skončí do 30 sekúnd.

6 Obmedzenia a ohrozenia validity

  • Žiadna presná inferencia typov. Nepoužívam PHPStan ani Larastan. Dynamické volania a nejasné typy končia ako hrany candidate alebo UNRESOLVED_CALL; v mojich repozitároch je v týchto dvoch skupinách 11 až 22 % miest volania.

  • Pokrytie miest volania má slepé miesto. Súčet zahŕňa iba miesta volania s aspoň jednou hranou. Volanie na známom, ale neúplne deklarovanom type, ktorému metóda chýba, nedostane žiadnu hranu a nezapočíta sa, takže rozlíšený podiel je horný odhad.

  • Blade sa skenuje, neparsuje. Môj skener nie je HTML gramatika; netradičné konštrukcie mu môžu uniknúť.

  • Schéma je rekonštrukcia. Schéma prehratá z migrácií sa nemusí zhodovať so živou databázou. Raw SQL sa parsuje iba čiastočne; R2 hlási 10 nerozpoznaných príkazov a 75 nerozhodnuteľných podmienok v migráciách.

  • Dynamické názvy sú neviditeľné. Názvy rout, middleware, názvy views a eventov vypočítané až za behu sa hlásia ako varovania a v grafe chýbajú. R2 hlási pre routy 90 takýchto varovaní.

  • Mapy kontajnera závisia od pomocných súborov. Mapy fasád a väzieb sa opierajú o _ide_helper.php a .phpstorm.meta.php; keď sú staršie než composer.lock, stav hlási ide_helper_stale.

  • Rozsah. Nástroj podporuje Laravel aplikácie, remote origin, macOS 14 alebo novší a Apple Silicon. Nemá prepojenie na Sentry ani na živú databázu.

  • Dôkazy. Čísla v tomto článku opisujú šesť repozitárov jedného autora. Nemeral som čas ušetrený na tiket ani som neporovnával presnosť asistenta s grafom a bez neho; prínosy v časti 5.2 vyplývajú z mechanizmu a z môjho vlastného používania, nie z kontrolovaného experimentu.

  • Neoverená podmienka nasadenia. Či fetch na pozadí funguje pri SSH nastavení kolegu, nie je overené; ak nie, graf sa aktualizuje iba po ručnom git fetch.

7 Záver

Ukázal som, že implicitné, reťazcové väzby Laravel aplikácie možno získať staticky, bez spustenia aplikácie, a uložiť ich ako graf, na ktorý sa AI asistent dopytuje malou sadou ohraničených nástrojov. Výsledok nesú tri návrhové rozhodnutia: graf je deterministickou funkciou vzdialeného commitu a zamknutých verzií balíkov; každá hrana uvádza svoju istotu a polohu v zdrojovom kóde; a každé miesto, kde analýza zlyhá, sa zaznamená ako varovanie. S týmito vlastnosťami graf v mojich šiestich repozitároch rozlíši 78 až 89 % miest volania a prebuduje sa za menej než tri sekundy.

Pre moju prácu je praktickým dôsledkom to, že stack trace alebo veta od zákazníka sa niekoľkými volaniami nástrojov preloží na obrazovku, route, handler, modely a tabuľky, s výslovným označením toho, čo je isté a čo treba overiť v zdrojovom kóde. Za nevyhnutný ďalší krok považujem kontrolované meranie tohto účinku na reálnych tiketoch helpdesku.

Google Analytics používam na to, aby som videl, ktoré články ľudia čítajú. Cookies nastaví len vtedy, ak to povolíte. Ochrana súkromia