Plugin de WebStorm para Contratos de UI-kit de React

React Component Contract Guard: Plugin de WebStorm para Evitar Desviaciones en el Kit de UI

En proyectos frontend grandes, el kit de UI comienza a desviarse entre los tipos de TypeScript, el uso real en JSX y las historias de Storybook. Los componentes con docenas de usos acumulan props sin documentar, historias desactualizadas y dependencias ocultas. TypeScript estándar detecta errores de sintaxis, pero pasa por alto las grandes preguntas: ¿El desajuste es aislado o sistémico? ¿Cuántos lugares afectará un cambio en un prop? ¿Refleja Storybook la API actual?

Component Contract Guard aborda esto con un analizador de contratos y un plugin de WebStorm. La herramienta construye un modelo de componente a partir de tres fuentes: contratos de TypeScript, usos en JSX y args de Storybook, resaltando discrepancias directamente en el editor.

Aquí un ejemplo típico de componente:

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

Pero en el proyecto ves:

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

Storybook podría referenciar un mystery: true inexistente.

Arquitectura: Analizador CLI + Plugin de IDE

El proyecto se divide en dos capas para independencia y reutilización:

• Analizador CLI (TypeScript): Carga tsconfig.json, crea un Programa de TypeScript, extrae contratos de props de exportaciones de componentes TSX, recopila usos en JSX, analiza CSF de Storybook.

• Plugin de WebStorm (Kotlin): Ejecuta el CLI, parsea resultados JSON, muestra pistas inline, subrayados, tooltips, resúmenes de archivo e informes de impacto.

Esta separación permite usar el CLI en CI, evita duplicación de lógica y facilita el puerto a otros IDE.

El análisis se ejecuta en tres etapas:

• Recopilación de Contratos: Extrae nombres de props, tipos, estado requerido, valores por defecto, JSDoc. Maneja destructuring con defaults.

• Recopilación de Usos: Posiciones JSX, props pasados, expresiones spread (con advertencias cautelosas).

• Análisis de Storybook: meta.args, argTypes, objetos story.

Señales y Advertencias del Analizador

El plugin genera advertencias precisas:

• Prop desconocido pasado (ej. tone en Button).
• Prop requerido faltante (ej. label).
• Storybook referencia prop desconocido (mystery).
• Prop del contrato no reflejado en Storybook.
• Prop sin usar ni en código ni en historias.

Para cada prop, calcula el impacto:

• Número de usos en código.
• Número de usos en historias.
• Riesgo de cambio (puntuado por frecuencia).

Esto distingue ajustes locales de migraciones de API pública.

Ejemplos de advertencias:

• Prop desconocido "tone" pasado a Button
• Button falta props requeridos: label
• Story BrokenStory referencia prop desconocido "mystery" para Button
• Button.icon no está documentado en args/argTypes de Storybook

Integración con WebStorm: Señales Inline

El plugin se activa al abrir/guardar archivo: escaneo CLI → JSON → elementos UI.

Canales de visualización:

• Insignias inline sobre líneas problemáticas.
• Subrayados ondulados para secciones JSX.
• Tooltips al pasar el mouse con detalles y fixes.
• Resumen a nivel de archivo en la parte superior.
• Ventana de herramientas para visión general del proyecto e impacto de props.

El flujo se integra sin problemas en el editor sin conflictos.

Casos de Uso Principales

La herramienta brilla en:

• Kits de UI y sistemas de diseño.
• Bibliotecas de componentes internas.
• Grandes monorepos con 50+ componentes.
• Proyectos donde Storybook actúa como contrato de documentación.

En proyectos pequeños (3–5 componentes), la revisión manual basta; el desvío surge a escala.

Aspectos Destacados

• Objeto de Control: No AST ni archivos, sino contratos como enlaces entre tipos/usos/docs/impacto.
• API del Compilador de TypeScript: Parsing preciso de props sin atajos.
• Manejo de Spread: Advertencias cautelosas para props dinámicos.
• Puntuación de Impacto: Evaluación cuantitativa de riesgo de migración.
• Integración IDE: Señales inline como nativas del flujo de trabajo, no CLI externo.

Desarrollo Futuro

El MVP se centra en análisis principal. Hoja de ruta:

• Detección de cambios rompientes entre versiones.
• Sugerencias automáticas de migración de props.
• Integración CI/PR.
• Soporte para componentes wrapper.
• Análisis más profundo de Storybook.
• Agrupación de impacto por capas del proyecto.

— Editorial Team