Wtyczka WebStorm do kontraktów React UI-kit

Monitorowanie zgodności kontraktów komponentów React: wtyczka WebStorm w walce z dryfem UI-kit

W dużych projektach frontendowych UI-kit zaczyna się rozbiegać między typami TypeScript, rzeczywistym użyciem JSX a Storybook. Komponenty z dziesiątkami zastosowań gromadzą niezadokumentowane właściwości, przestarzałe historie i ukryte zależności. Zwykły TypeScript wychwytuje błędy syntaktyczne, ale nie odpowiada na kluczowe pytania: czy rozbieżność ma charakter jednostkowy czy systemowy, ile miejsc dotknie zmiana właściwości, czy Storybook odpowiada aktualnemu API.

Component Contract Guard rozwiązuje to zadanie poprzez analizator kontraktów i wtyczkę do WebStorm. Narzędzie buduje model komponentu z trzech źródeł: kontraktu TypeScript, zastosowań JSX i argumentów Storybook, podświetlając rozbieżności bezpośrednio w edytorze.

Przykład typowego komponentu:

type ButtonProps = {
  label: string;
  variant?: "primary" | "secondary";
  icon?: React.ReactNode;
};

export function Button({ label, variant = "primary", icon }: ButtonProps) {
  return (
    <button data-variant={variant}>
      {icon}
      {label}
    </button>
  );
}

A w projekcie spotykane są:

<Button variant="primary" tone="loud" />
<Card title="Health" variant="ghost" />

Storybook może odnosić się do nieistniejących mystery: true.

Architektura: analizator CLI + wtyczka IDE

Projekt podzielony jest na dwie warstwy dla niezależności i ponownego wykorzystania:

• Analizator CLI (TypeScript): ładuje tsconfig.json, uruchamia TypeScript Program, wyodrębnia kontrakty właściwości z eksportów komponentów TSX, zbiera zastosowania z JSX, parsuje CSF-Storybook.

• Wtyczka WebStorm (Kotlin): uruchamia CLI, parsuje wyniki JSON, wyświetla podpowiedzi inline, podkreślenia, tooltipy, podsumowania plików i raporty wpływu.

Podział pozwala na użycie CLI w CI, unikanie duplikacji logiki i ułatwia portowanie na inne IDE.

Analiza przebiega w trzech etapach:

• Zbieranie kontraktów: wyodrębnianie nazwy właściwości, typu, obowiązkowości, wartości domyślnych, JSDoc. Uwzględnianie destrukturyzacji z wartościami domyślnymi.
• Zbieranie zastosowań: pozycje w JSX, przekazane właściwości, wyrażenia spread (z ostrożnymi ostrzeżeniami).
• Analiza Storybook: meta.args, argTypes, obiekty historii.

Sygnały i ostrzeżenia od analizatora

Wtyczka generuje precyzyjne ostrzeżenia:

• Przekazano nieznaną właściwość (np. tone w Button).
• Brak obowiązkowej właściwości (np. label).
• Storybook odnosi się do nieznanej właściwości (mystery).
• Właściwość z kontraktu nie jest odzwierciedlona w Storybook.
• Nieużywana właściwość ani w kodzie, ani w historiach.

Dla każdej właściwości obliczany jest wpływ:

• Liczba zastosowań w kodzie.
• Liczba zastosowań w historiach.
• Ryzyko zmian (ocena na podstawie częstotliwości).

To odróżnia lokalne poprawki od migracji publicznego API.

Przykłady ostrzeżeń:

• Unknown prop "tone" is passed to Button
• Button is missing required props: label
• Story BrokenStory references unknown prop "mystery" for Button
• Button.icon is not documented in Storybook args/argTypes

Integracja w WebStorm: sygnały inline

Wtyczka uruchamiana jest przy otwieraniu/zapisywaniu pliku: skan CLI → JSON → elementy UI.

Kanały wyświetlania:

• Plakietki inline nad liniami z problemami.
• Faliste podkreślenia dla obszarów JSX.
• Tooltip z szczegółami i poprawkami przy najechaniu.
• Podsumowanie na poziomie pliku u góry.
• Okno narzędziowe dla przeglądu projektu i wpływu właściwości.

Płynnie integruje się z edytorem bez konfliktów.

Obszar zastosowania

Narzędzie jest istotne dla:

• UI-kit i systemów designu.
• Wewnętrzne biblioteki komponentów.
• Duże monorepozytoria z 50+ komponentami.
• Projekty, gdzie Storybook jest kontraktem dokumentacji.

W małych projektach (3–5 komponentów) ręczny przegląd wystarczy; dryf pojawia się przy skali.

Co jest ważne

• Obiekt kontroli: nie AST czy plik, ale kontrakt jako połączenie typów/zastosowań/dokumentacji/wpływu.
• TypeScript Compiler API: precyzyjne parsowanie właściwości bez uproszczeń.
• Obsługa spread: ostrożne ostrzeżenia dla dynamicznych właściwości.
• Ocena wpływu: ilościowa ocena ryzyk migracji.
• Integracja IDE: sygnały inline jako część workflow, nie zewnętrzny CLI.

Dalszy rozwój

MVP skupia się na podstawowej analizie. Plany:

• Detekcja breaking changes między wersjami.
• Automatyczne podpowiedzi migracji właściwości.
• Integracja CI/PR.
• Uwzględnianie wrapper-ów komponentów.
• Pogłębiona analiza Storybook.
• Wpływ z grupowaniem według warstw projektu.

— Editorial Team