React UI-kit 계약을 위한 WebStorm 플러그인

React 컴포넌트 계약 가드: UI 키트 드리프트 방지 WebStorm 플러그인

대규모 프론트엔드 프로젝트에서 UI 키트는 TypeScript 타입, 실제 JSX 사용, Storybook 스토리 간에 서서히 어긋나기 시작합니다. 수십 군데에서 사용되는 컴포넌트들은 문서화되지 않은 props, 오래된 스토리, 숨겨진 의존성을 쌓아갑니다. 일반 TypeScript는 구문 오류만 잡아내고, 핵심 질문에는 답하지 못합니다: 불일치가 개별적인가 시스템적인가? props 변경이 몇 군데에 영향을 미칠까? Storybook이 현재 API를 제대로 반영하고 있는가?

컴포넌트 계약 가드(Component Contract Guard)는 계약 분석기와 WebStorm 플러그인을 통해 이 문제를 해결합니다. 이 도구는 TypeScript 계약, JSX 사용, Storybook args 세 가지 소스에서 컴포넌트 모델을 구축하고, 에디터 내에서 불일치를 즉시 강조 표시합니다.

전형적인 컴포넌트 예시:

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 컴포넌트 export에서 props 계약 추출, JSX 사용 수집, CSF Storybook 파싱.

• WebStorm 플러그인 (Kotlin): CLI 실행, JSON 결과 파싱, 인라인 힌트, 밑줄 표시, 툴팁, 파일 요약, 영향 보고서 표시.

이 분리는 CI에서 CLI 단독 사용, 로직 중복 방지, 다른 IDE 포팅을 용이하게 합니다.

분석은 세 단계로 진행됩니다:

• 계약 수집: props 이름, 타입, 필수 여부, 기본값, JSDoc 추출. 기본값이 있는 구조 분해 처리.

• 사용 수집: JSX 위치, 전달된 props, 스프레드 표현식 (신중한 경고 포함).

• Storybook 파싱: meta.args, argTypes, 스토리 객체.

분석기 신호와 경고

플러그인은 정확한 경고를 생성합니다:

• 알려지지 않은 props 전달 (예: Button의 tone).
• 필수 props 누락 (예: label).
• Storybook이 알려지지 않은 props 참조 (mystery).
• 계약 props가 Storybook에 반영되지 않음.
• 코드나 스토리에서 사용되지 않는 props.

각 props에 대해 영향도를 계산합니다:

• 코드 사용 횟수.
• 스토리 사용 횟수.
• 변경 위험도 (빈도 기반 점수).

이로써 로컬 수정과 공용 API 마이그레이션을 구분합니다.

경고 예시:

• 알려지지 않은 props "tone"이 Button에 전달되었습니다
• Button에 필수 props가 누락되었습니다: label
• Story BrokenStory가 Button의 알려지지 않은 props "mystery"를 참조합니다
• Button.icon이 Storybook args/argTypes에 문서화되지 않았습니다

WebStorm 통합: 인라인 신호

플러그인은 파일 열기/저장 시 트리거: CLI 스캔 → JSON → UI 요소.

표시 채널:

• 문제 라인 위 인라인 배지.
• JSX 섹션에 물결 밑줄.
• 상세 정보와 수정 제안 툴팁.
• 파일 상단 요약.
• 프로젝트 개요와 props 영향도 툴 윈도우.

에디터 워크플로에 자연스럽게 통합됩니다.

주요 사용 사례

이 도구는 다음에서 빛을 발합니다:

• UI 키트와 디자인 시스템.
• 내부 컴포넌트 라이브러리.
• 50+ 컴포넌트 대형 모노레포.
• Storybook이 문서 계약으로 사용되는 프로젝트.

작은 프로젝트(3~5 컴포넌트)에서는 수동 검토로 충분하지만, 규모가 커지면 드리프트가 발생합니다.

주요 특징

• 제어 객체: AST나 파일이 아닌, 타입/사용/문서/영향을 연결하는 계약 중심.
• TypeScript 컴파일러 API: 단축 없이 정확한 props 파싱.
• 스프레드 처리: 동적 props에 신중한 경고.
• 영향도 점수화: 정량적 마이그레이션 위험 평가.
• IDE 통합: 외부 CLI가 아닌 워크플로 네이티브 인라인 신호.

향후 개발

MVP는 핵심 분석에 집중. 로드맵:

• 버전 간 변경 감지.
• 자동 마이그레이션 props 제안.
• CI/PR 통합.
• 래퍼 컴포넌트 지원.
• 심층 Storybook 분석.
• 프로젝트 레이어 별 영향 그룹화.

— Editorial Team