Plugin WebStorm pro kontrakty React UI-kit

Kontrola kontraktů React komponent: plugin pro WebStorm proti odchylkám v UI-kitu

Ve velkých frontendových projektech se UI-kit začíná rozcházet mezi TypeScript typy, skutečným použitím v JSX a Storybookem. Komponenty s desítkami použití hromadí nedokumentované props, zastaralé stories a skryté závislosti. Běžný TypeScript zachytává syntaktické chyby, ale neodpovídá na klíčové otázky: je odchylka jednotlivá nebo systémová, kolik míst ovlivní změna prop, odpovídá Storybook aktuálnímu API.

Component Contract Guard řeší tento problém prostřednictvím analyzátoru kontraktů a pluginu pro WebStorm. Nástroj vytváří model komponenty ze tří zdrojů: TypeScript kontraktu, JSX použití a Storybook args, zvýrazňující odchylky přímo v editoru.

Příklad typické komponenty:

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>
  );
}

V projektu se mohou vyskytovat:

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

Storybook může odkazovat na neexistující mystery: true.

Architektura: CLI analyzátor + IDE plugin

Projekt je rozdělen do dvou vrstev pro nezávislost a opětovné použití:

• CLI analyzátor (TypeScript): načte tsconfig.json, spustí TypeScript Program, extrahuje props kontrakty z exportů TSX komponent, sbírá použití z JSX, parsuje CSF-Storybook.

• WebStorm plugin (Kotlin): spustí CLI, parsuje JSON výsledky, zobrazuje inline nápovědy, podtržení, tooltips, souhrny souborů a impact reporty.

Rozdělení umožňuje použití CLI v CI, vyhýbání se duplikaci logiky a zjednodušuje portování na další IDE.

Analýza probíhá ve třech krocích:

• Sběr kontraktů: extrakce názvu prop, typu, povinnosti, výchozích hodnot, JSDoc. Zohlednění destrukturalizace s výchozími hodnotami.

• Sběr použití: pozice v JSX, předané props, spread výrazy (s opatrnými varováními).

• Analýza Storybook: meta.args, argTypes, story objekty.

Signály a varování od analyzátoru

Plugin generuje přesná varování:

• Předán neznámý prop (např. tone v Button).
• Chybí povinný prop (např. label).
• Storybook odkazuje na neznámý prop (mystery).
• Prop z kontraktu není reflektován v Storybook.
• Nepoužívaný prop ani v kódu, ani v stories.

Pro každý prop se vypočítá impact:

• Počet použití v kódu.
• Počet použití v stories.
• Riziko změn (skórování podle frekvence).

To odlišuje lokální úpravy od migrací veřejného API.

Příklady varování:

• 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

Integrace v WebStorm: inline signály

Plugin se spouští při otevření/uložení souboru: CLI sken → JSON → UI elementy.

Kanály zobrazení:

• Inline značky nad řádky s problémy.
• Vlnité podtržení pro JSX části.
• Tooltip s detaily a opravami při najetí.
• Souhrn na úrovni souboru nahoře.
• Tool window pro přehled projektu a prop impact.

Plynule integrováno do editoru bez konfliktů.

Cílová oblast použití

Nástroj je relevantní pro:

• UI-kit a design systems.
• Vnitřní komponentové knihovny.
• Velké monorepo s 50+ komponentami.
• Projekty, kde Storybook slouží jako kontrakt dokumentace.

V malých projektech (3–5 komponent) je manuální kontrola dostačující; odchylky se projevují při škálování.

Co je důležité

• Objekt kontroly: ne AST nebo soubor, ale kontrakt jako spojení typů/použití/dokumentace/impact.
• TypeScript Compiler API: přesné parsování props bez zjednodušení.
• Spread-handling: opatrná varování pro dynamické props.
• Impact-scoring: kvantitativní hodnocení rizik migrací.
• IDE integrace: inline signály jako součást workflow, ne externí CLI.

Další vývoj

MVP se zaměřuje na základní analýzu. Plány:

• Detekce breaking changes mezi verzemi.
• Auto-návrhy migrací props.
• Integrace CI/PR.
• Účet wrapper komponent.
• Hlubší analýza Storybook.
• Impact se skupinováním podle projektových vrstev.

— Editorial Team