React UI-kit 契约的 WebStorm 插件

React 组件契约守护：WebStorm 插件防止 UI 套件漂移

在大型前端项目中，UI 套件容易在 TypeScript 类型、实际 JSX 使用和 Storybook 故事之间产生漂移。组件被大量使用后，会积累未文档化的 props、过时的故事和隐藏依赖。标准 TypeScript 能捕获语法错误，但无法回答核心问题：不匹配是孤立的还是系统性的？修改一个 prop 会影响多少地方？Storybook 是否反映当前 API？

组件契约守护 通过契约分析器和 WebStorm 插件解决这些痛点。该工具从三个来源构建组件模型：TypeScript 契约、JSX 使用和 Storybook 参数，直接在编辑器中高亮差异。

典型组件示例：

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

但项目中实际使用：

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

Storybook 可能引用不存在的 mystery: true。

架构：CLI 分析器 + IDE 插件

项目分为两层，确保独立性和可复用性：

• CLI 分析器 (TypeScript)：加载 tsconfig.json，创建 TypeScript Program，从 TSX 组件导出提取 props 契约，收集 JSX 使用，解析 CSF Storybook。

• WebStorm 插件 (Kotlin)：运行 CLI，解析 JSON 结果，在编辑器中显示内联提示、下划线、工具提示、文件摘要和影响报告。

这种分离允许在 CI 中使用 CLI，避免逻辑重复，便于移植到其他 IDE。

分析分为三个阶段：

• 契约收集：提取 props 名称、类型、必填状态、默认值、JSDoc。处理带默认值的解构。

• 使用收集：JSX 位置、传递的 props、展开表达式（谨慎警告）。

• Storybook 解析：meta.args、argTypes、story 对象。

分析器信号和警告

插件生成精确警告：

• 传递未知 prop（如 Button 的 tone）。
• 缺少必填 prop（如 label）。
• Storybook 引用未知 prop（mystery）。
• 契约 prop 未在 Storybook 中体现。
• prop 在代码和故事中均未使用。

针对每个 prop，计算影响：

• 代码使用次数。
• 故事使用次数。
• 修改风险（按频率评分）。

这能区分局部调整和公共 API 迁移。

警告示例：

• 未知 prop "tone" 被传递给 Button
• Button 缺少必填 props: label
• Story BrokenStory 为 Button 引用未知 prop "mystery"
• Button.icon 未在 Storybook args/argTypes 中文档化

WebStorm 集成：内联信号

插件在文件打开/保存时触发：CLI 扫描 → JSON → UI 元素。

显示渠道：

• 问题行上的内联徽章。
• JSX 部分的波浪下划线。
• 悬停工具提示，含详情和修复建议。
• 文件顶部级别摘要。
• 工具窗口，提供项目概览和 prop 影响。

流程无缝融入编辑器，无冲突。

目标用例

工具适用于：

• UI 套件和设计系统。
• 内部组件库。
• 含 50+ 组件的大型代码库。
• 以 Storybook 作为文档契约的项目。

小型项目（3–5 个组件）手动审查足矣；漂移问题在大规模时显现。

核心亮点

• 控制对象：非 AST 或文件，而是类型/使用/文档/影响间的契约链接。
• TypeScript 编译器 API：精确 props 解析，无捷径。
• 展开处理：动态 props 的谨慎警告。
• 影响评分：定量迁移风险评估。
• IDE 集成：内联信号如工作流原生，非外部 CLI。

未来发展

MVP 聚焦核心分析。路线图：

• 跨版本破坏性变更检测。
• 自动迁移 prop 建议。
• CI/PR 集成。
• 包装组件支持。
• 更深 Storybook 分析。
• 按项目层分组影响。

— Editorial Team