01Zobacz, jak TypeScript widzi Twój kod
TypeScript AST Viewer pokazuje drzewo składniowe budowane przez compiler API. Wklejasz fragment TypeScriptu, wybierasz preset albo własny kod, a narzędzie pokazuje node kinds, zakresy `pos/end`, diagnostykę składniową i fragmenty źródła dla zaznaczonego węzła. Parser działa w przeglądarce, więc kod użytkownika nie jest wysyłany na backend.
To narzędzie jest przydatne przy pisaniu reguł lintingu, transformacji kodu, generatorów, narzędzi refaktoryzacyjnych i edukacyjnych analiz składni. Zamiast zgadywać, gdzie kończy się deklaracja, typ albo wywołanie funkcji, można kliknąć konkretny node i zobaczyć, jak TypeScript reprezentuje go wewnętrznie.
02Kiedy AST Viewer daje największą wartość
AST jest potrzebne wtedy, gdy proste wyszukiwanie tekstu przestaje wystarczać. Regex może znaleźć słowo `interface`, ale nie rozumie zagnieżdżonych typów, dekoratorów, parametrów generycznych, komentarzy, JSX ani diagnostyki parsera. Compiler API rozbija kod na stabilne węzły, które można przechodzić, filtrować i mapować na dokładne zakresy tekstu.
W MVP najważniejsza jest pętla decyzyjna developera: wkleić kod, zobaczyć drzewo, kliknąć node, przeczytać `SyntaxKind`, sprawdzić range oraz skopiować minimalny snippet compiler API. To zmniejsza koszt wejścia dla osób, które chcą pisać własne reguły, codemody albo narzędzia analityczne bez pełnej konfiguracji projektu.
03Jak czytać wynik
Najpierw patrz na diagnostykę. Jeżeli parser zgłasza błąd składniowy, drzewo nadal może powstać, ale część węzłów będzie wynikiem odzyskiwania po błędzie. Potem przejdź do drzewa AST i wybierz node, który odpowiada problemowi: `FunctionDeclaration`, `InterfaceDeclaration`, `TypeAliasDeclaration`, `CallExpression`, `PropertyAccessExpression` albo `Decorator`. Details panel pokazuje numeric kind, nazwę `SyntaxKind`, zakresy i fragment kodu.
W TypeScript ważne jest rozróżnienie `pos`, `end` i `getStart`. `pos` często obejmuje trivia, czyli spacje i komentarze przed węzłem, a `getStart` wskazuje początek właściwego tokena. To ma znaczenie przy refaktoryzacji i generowaniu fixów, bo zbyt szeroki range może przypadkowo usunąć komentarz albo przecinek. Viewer pokazuje oba zakresy, żeby decyzja była świadoma.
Porównanie z innymi podejściami jest proste: Babel parser jest świetny dla ekosystemu transformacji JS, ale TypeScript compiler API daje natywną semantykę TS i diagnostykę składniową. Regex jest szybki do jednorazowego grep, lecz nie nadaje się do bezpiecznych zmian strukturalnych. Manualna inspekcja jest dobra do nauki, ale nie skaluje się do narzędzi produkcyjnych.
W praktyce warto zaczynać od małych przykładów. Jeżeli chcesz zrozumieć regułę lintingu, wklej minimalny snippet, który powinien zostać wykryty, a potem porównaj go z wariantem poprawnym. Dla `typescript-eslint` szczególnie ważne są miejsca, w których node składniowy różni się od intuicji z edytora: nazwa funkcji może być osobnym `Identifier`, typ zwracany osobnym `TypeNode`, a dekorator albo modifier znajduje się w tablicy powiązanej z deklaracją. Klikanie po drzewie pozwala szybko ustalić, czy reguła powinna reagować na deklarację, wyrażenie, typ, czy dopiero na konkretny token wewnątrz większej struktury.
Przy codemodach najważniejsze jest bezpieczeństwo zakresów. Jeśli planujesz zamienić wywołanie funkcji, dodać argument, przepisać import albo rozwinąć alias typu, nie wystarczy wiedzieć, że node istnieje. Trzeba zobaczyć, jaki fragment tekstu obejmuje, gdzie zaczyna się właściwy token i czy w pobliżu są komentarze, przecinki lub białe znaki. Viewer pomaga odróżnić zmianę strukturalną od prostej podmiany tekstu. To ogranicza ryzyko, że automatyczna refaktoryzacja usunie komentarz dokumentacyjny, popsuje formatowanie albo obejmie zbyt szeroki fragment pliku.
Diagnostyka parsera jest równie ważna jak samo drzewo. TypeScript potrafi odzyskać częściowe AST nawet wtedy, gdy kod ma błąd składniowy. To przydatne w edytorach i narzędziach live, ale może zaskoczyć w testach automatycznych. Jeżeli widzisz w drzewie nietypowy node, najpierw sprawdź listę diagnostyk, pozycję błędu i fragment źródła. Dopiero potem oceniaj, czy problem leży w compiler API, w danych wejściowych, czy w założeniach tworzonego narzędzia.
Narzędzie działa lokalnie w przeglądarce, dlatego dobrze nadaje się do szybkich eksperymentów z prywatnym kodem, fragmentami z dokumentacji albo sztucznymi fixture'ami testowymi. Nie zastępuje pełnej analizy typu z projektem, `tsconfig` i programem TypeScript, ale daje szybki obraz warstwy składniowej. Kiedy potrzebujesz symboli, typów, modułów i resolvingu importów, kolejnym krokiem jest lokalny skrypt oparty o `createProgram`. Gdy wystarcza struktura składniowa, ten viewer skraca drogę od hipotezy do działającego selektora node'ów.
Dobrą praktyką jest też zapisywanie własnych przykładów jako fixture. Ten sam fragment, który oglądasz w viewerze, może później trafić do testu jednostkowego reguły albo codemoda. Dzięki temu decyzja podjęta wizualnie nie ginie po zamknięciu karty przeglądarki. Możesz nazwać oczekiwany node, zanotować jego `SyntaxKind`, sprawdzić najważniejsze zakresy i dopiero wtedy przenieść selektor do kodu narzędzia. Taki proces jest wolniejszy niż zgadywanie po nazwach typów, ale znacznie bezpieczniejszy przy zmianach, które mają później działać na setkach plików w prawdziwym repozytorium. W efekcie viewer staje się nie tylko demo, ale krótką dokumentacją decyzji technicznej przed automatyzacją.