Plugin WebStorm pour les Contrats UI-kit React

React Contract Guard : plugin WebStorm contre la dérive des kits UI

Dans les gros projets frontend, le kit UI commence à dériver entre les types TypeScript, l'usage réel en JSX et les stories Storybook. Les composants utilisés des dizaines de fois accumulent des props non documentées, des stories obsolètes et des dépendances cachées. TypeScript standard attrape les erreurs de syntaxe, mais passe à côté des vraies questions : l'écart est-il isolé ou systémique ? Combien d'endroits un changement de prop va-t-il impacter ? Storybook reflète-t-il l'API actuelle ?

React Contract Guard s'attaque à ça avec un analyseur de contrats et un plugin WebStorm. L'outil construit un modèle de composant à partir de trois sources : contrats TypeScript, usages JSX et args Storybook, en mettant en évidence les écarts directement dans l'éditeur.

Voici un exemple typique de composant :

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

Mais dans le projet, on voit :

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

Storybook pourrait référencer un mystery: true inexistant.

Architecture : analyseur CLI + plugin IDE

Le projet se divise en deux couches pour l'indépendance et la réutilisabilité :

• Analyseur CLI (TypeScript) : Charge tsconfig.json, crée un Programme TypeScript, extrait les contrats de props des exports TSX, collecte les usages JSX, parse le CSF Storybook.

• Plugin WebStorm (Kotlin) : Lance le CLI, parse les résultats JSON, affiche des indications inline, soulignements, infobulles, résumés de fichiers et rapports d'impact.

Cette séparation permet d'utiliser le CLI en CI, évite la duplication de logique et facilite le portage vers d'autres IDE.

L'analyse se déroule en trois étapes :

• Collecte des contrats : Extrait noms de props, types, statut obligatoire, valeurs par défaut, JSDoc. Gère le destructuring avec defaults.

• Collecte des usages : Positions JSX, props passées, expressions spread (avec avertissements prudents).

• Parsing Storybook : meta.args, argTypes, objets story.

Signaux et avertissements de l'analyseur

Le plugin génère des avertissements précis :

• Prop inconnue passée (ex. tone sur Button).
• Prop obligatoire manquante (ex. label).
• Storybook référence une prop inconnue (mystery).
• Prop du contrat non reflétée en Storybook.
• Prop inutilisée ni dans le code ni dans les stories.

Pour chaque prop, il calcule l'impact :

• Nombre d'usages dans le code.
• Nombre d'usages dans les stories.
• Risque de changement (noté par fréquence).

Ça distingue les ajustements locaux des migrations d'API publique.

Exemples d'avertissements :

• Prop inconnue "tone" passée à Button
• Button manque des props obligatoires : label
• Story BrokenStory référence prop inconnue "mystery" pour Button
• Button.icon n'est pas documenté dans les args/argTypes Storybook

Intégration WebStorm : signaux inline

Le plugin se déclenche à l'ouverture/enregistrement du fichier : scan CLI → JSON → éléments UI.

Canaux d'affichage :

• Badges inline sur les lignes problématiques.
• Soulignements ondulés pour les sections JSX.
• Infobulles au survol avec détails et correctifs.
• Résumé au niveau fichier en haut.
• Fenêtre outil pour vue d'ensemble projet et impact des props.

Le flux s'intègre parfaitement dans l'éditeur sans conflits.

Cas d'usage cibles

L'outil excelle pour :

• Kits UI et systèmes de design.
• Bibliothèques de composants internes.
• Gros monorepos avec 50+ composants.
• Projets où Storybook fait office de contrat de documentation.

Dans les petits projets (3–5 composants), un review manuel suffit ; la dérive apparaît à l'échelle.

Points forts

• Objet de contrôle : Pas l'AST ou les fichiers, mais les contrats comme liens entre types/usages/docs/impact.
• API du compilateur TypeScript : Parsing précis des props sans raccourcis.
• Gestion des spreads : Avertissements prudents pour props dynamiques.
• Notation d'impact : Évaluation quantitative du risque de migration.
• Intégration IDE : Signaux inline natifs au workflow, pas un CLI externe.

Développement futur

Le MVP se concentre sur l'analyse de base. Feuille de route :

• Détection de changements cassants entre versions.
• Suggestions auto de migration de props.
• Intégration CI/PR.
• Support des composants wrappers.
• Analyse Storybook plus poussée.
• Groupage d'impact par couches projet.

— Editorial Team