@su-record/vibe 0.4.6 → 0.4.7

package/.vibe/rules/languages/typescript-react.md

@@ -0,0 +1,525 @@
+# ⚛️ TypeScript + React 품질 규칙
+
+## 핵심 원칙 (core에서 상속)
+
+```markdown
+✅ 단일 책임 (SRP)
+✅ 중복 제거 (DRY)
+✅ 재사용성
+✅ 낮은 복잡도
+✅ 함수 ≤ 30줄, JSX ≤ 50줄
+✅ 중첩 ≤ 3단계
+✅ Cyclomatic complexity ≤ 10
+```
+
+## TypeScript/React 특화 규칙
+
+### 1. 타입 안전성 100%
+
+```typescript
+// ❌ any 사용
+function processData(data: any) {
+  return data.value;
+}
+
+// ✅ 명확한 타입 정의
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  age: number;
+}
+
+function processUser(user: User): string {
+  return user.name;
+}
+
+// ✅ Generic 활용
+interface ApiResponse<T> {
+  success: boolean;
+  data: T;
+  error?: string;
+}
+
+type UserResponse = ApiResponse<User>;
+type ProductResponse = ApiResponse<Product>;
+```
+
+### 2. 함수형 컴포넌트 + Hooks
+
+```typescript
+// ✅ 함수형 컴포넌트 (권장)
+interface UserCardProps {
+  user: User;
+  onEdit?: (user: User) => void;
+}
+
+export function UserCard({ user, onEdit }: UserCardProps) {
+  const [isEditing, setIsEditing] = useState(false);
+
+  const handleEdit = useCallback(() => {
+    if (onEdit) {
+      onEdit(user);
+    }
+  }, [user, onEdit]);
+
+  return (
+    <div>
+      <h2>{user.name}</h2>
+      <button onClick={handleEdit}>Edit</button>
+    </div>
+  );
+}
+
+// ❌ 클래스 컴포넌트 (레거시)
+class UserCard extends React.Component<UserCardProps> {
+  // 복잡하고 장황함
+}
+```
+
+### 3. Custom Hook으로 로직 분리
+
+```typescript
+// ✅ Custom Hook (재사용 가능한 로직)
+interface UseUserOptions {
+  userId: string;
+}
+
+interface UseUserReturn {
+  user: User | null;
+  isLoading: boolean;
+  error: string | null;
+  refetch: () => Promise<void>;
+}
+
+function useUser({ userId }: UseUserOptions): UseUserReturn {
+  const [user, setUser] = useState<User | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchUser = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const response = await fetch(`/api/users/${userId}`);
+      const data = await response.json();
+      setUser(data);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    } finally {
+      setIsLoading(false);
+    }
+  }, [userId]);
+
+  useEffect(() => {
+    fetchUser();
+  }, [fetchUser]);
+
+  return { user, isLoading, error, refetch: fetchUser };
+}
+
+// 사용
+function UserProfile({ userId }: { userId: string }) {
+  const { user, isLoading, error } = useUser({ userId });
+
+  if (isLoading) return <Spinner />;
+  if (error) return <Error message={error} />;
+  if (!user) return <NotFound />;
+
+  return <UserCard user={user} />;
+}
+```
+
+### 4. Props 타입 정의
+
+```typescript
+// ✅ Props 타입 명확히
+interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  loading?: boolean;
+  onClick?: () => void;
+  children: React.ReactNode;
+}
+
+export function Button({
+  variant = 'primary',
+  size = 'md',
+  disabled = false,
+  loading = false,
+  onClick,
+  children,
+}: ButtonProps) {
+  return (
+    <button
+      className={`btn btn-${variant} btn-${size}`}
+      disabled={disabled || loading}
+      onClick={onClick}
+    >
+      {loading ? <Spinner /> : children}
+    </button>
+  );
+}
+
+// ✅ PropsWithChildren 활용
+import { PropsWithChildren } from 'react';
+
+interface CardProps {
+  title: string;
+  subtitle?: string;
+}
+
+export function Card({
+  title,
+  subtitle,
+  children,
+}: PropsWithChildren<CardProps>) {
+  return (
+    <div>
+      <h2>{title}</h2>
+      {subtitle && <p>{subtitle}</p>}
+      {children}
+    </div>
+  );
+}
+```
+
+### 5. React Query (서버 상태 관리)
+
+```typescript
+// ✅ React Query로 서버 상태 관리
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+function useUser(userId: string) {
+  return useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetchUser(userId),
+    staleTime: 5 * 60 * 1000, // 5분
+  });
+}
+
+function useUpdateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: UpdateUserData) => updateUser(data),
+    onSuccess: (updatedUser) => {
+      // 캐시 업데이트
+      queryClient.setQueryData(['user', updatedUser.id], updatedUser);
+    },
+  });
+}
+
+// 사용
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, isLoading, error } = useUser(userId);
+  const updateMutation = useUpdateUser();
+
+  if (isLoading) return <Spinner />;
+  if (error) return <Error />;
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <button
+        onClick={() => updateMutation.mutate({ id: userId, name: 'New Name' })}
+        disabled={updateMutation.isPending}
+      >
+        Update
+      </button>
+    </div>
+  );
+}
+```
+
+### 6. Zod로 Contract 정의
+
+```typescript
+// ✅ Zod 스키마 (런타임 + 타입 검증)
+import { z } from 'zod';
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  username: z.string().min(3).max(50),
+  password: z.string().min(8),
+  age: z.number().min(0).max(150),
+});
+
+type CreateUserRequest = z.infer<typeof createUserSchema>;
+
+// 사용 (React Hook Form)
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+function SignUpForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<CreateUserRequest>({
+    resolver: zodResolver(createUserSchema),
+  });
+
+  const onSubmit = async (data: CreateUserRequest) => {
+    await registerUser(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <input {...register('username')} />
+      {errors.username && <span>{errors.username.message}</span>}
+
+      <input type="password" {...register('password')} />
+      {errors.password && <span>{errors.password.message}</span>}
+
+      <input type="number" {...register('age', { valueAsNumber: true })} />
+      {errors.age && <span>{errors.age.message}</span>}
+
+      <button type="submit" disabled={isSubmitting}>
+        Sign Up
+      </button>
+    </form>
+  );
+}
+```
+
+### 7. 컴포넌트 분리 (Extract Component)
+
+```typescript
+// ❌ 긴 JSX (80줄)
+function UserDashboard() {
+  return (
+    <div>
+      <header>
+        <h1>Dashboard</h1>
+        {/* 20줄 */}
+      </header>
+      <main>
+        {/* 40줄 */}
+      </main>
+      <footer>
+        {/* 20줄 */}
+      </footer>
+    </div>
+  );
+}
+
+// ✅ 서브 컴포넌트 분리
+function UserDashboard() {
+  return (
+    <div>
+      <DashboardHeader />
+      <DashboardMain />
+      <DashboardFooter />
+    </div>
+  );
+}
+
+function DashboardHeader() {
+  return <header>{/* ... */}</header>;
+}
+
+function DashboardMain() {
+  return <main>{/* ... */}</main>;
+}
+
+function DashboardFooter() {
+  return <footer>{/* ... */}</footer>;
+}
+```
+
+### 8. useCallback + useMemo 최적화
+
+```typescript
+// ✅ useCallback (함수 메모이제이션)
+function Parent() {
+  const [count, setCount] = useState(0);
+
+  // 매번 새 함수 생성 방지
+  const handleClick = useCallback(() => {
+    setCount(prev => prev + 1);
+  }, []);
+
+  return <Child onClick={handleClick} />;
+}
+
+const Child = React.memo<{ onClick: () => void }>(({ onClick }) => {
+  return <button onClick={onClick}>Click</button>;
+});
+
+// ✅ useMemo (값 메모이제이션)
+function ExpensiveComponent({ data }: { data: number[] }) {
+  const processedData = useMemo(() => {
+    return data
+      .map(expensiveCalculation)
+      .filter(x => x > 0)
+      .reduce((a, b) => a + b, 0);
+  }, [data]);
+
+  return <div>{processedData}</div>;
+}
+```
+
+### 9. Error Boundary
+
+```typescript
+// ✅ Error Boundary (클래스 컴포넌트 필수)
+interface ErrorBoundaryProps {
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error?: Error;
+}
+
+class ErrorBoundary extends React.Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+    console.error('Error caught by boundary:', error, errorInfo);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback || <ErrorFallback error={this.state.error} />;
+    }
+
+    return this.props.children;
+  }
+}
+
+// 사용
+function App() {
+  return (
+    <ErrorBoundary fallback={<ErrorPage />}>
+      <UserDashboard />
+    </ErrorBoundary>
+  );
+}
+```
+
+### 10. 타입 가드 활용
+
+```typescript
+// ✅ 타입 가드
+interface Dog {
+  type: 'dog';
+  bark: () => void;
+}
+
+interface Cat {
+  type: 'cat';
+  meow: () => void;
+}
+
+type Animal = Dog | Cat;
+
+function isDog(animal: Animal): animal is Dog {
+  return animal.type === 'dog';
+}
+
+function makeSound(animal: Animal) {
+  if (isDog(animal)) {
+    animal.bark();  // 타입 안전
+  } else {
+    animal.meow();  // 타입 안전
+  }
+}
+
+// ✅ Discriminated Union
+function AnimalCard({ animal }: { animal: Animal }) {
+  switch (animal.type) {
+    case 'dog':
+      return <DogCard dog={animal} />;
+    case 'cat':
+      return <CatCard cat={animal} />;
+  }
+}
+```
+
+## 안티패턴
+
+```typescript
+// ❌ Props drilling (3단계 이상)
+<GrandParent user={user}>
+  <Parent user={user}>
+    <Child user={user} />
+  </Parent>
+</GrandParent>
+
+// ✅ Context 사용
+const UserContext = createContext<User | undefined>(undefined);
+
+<UserContext.Provider value={user}>
+  <GrandParent />
+</UserContext.Provider>
+
+// ❌ useEffect 의존성 누락
+useEffect(() => {
+  fetchUser(userId);
+}, []); // userId 의존성 누락!
+
+// ✅ 모든 의존성 명시
+useEffect(() => {
+  fetchUser(userId);
+}, [userId]);
+
+// ❌ 인라인 객체/함수 (리렌더 유발)
+<Child config={{ theme: 'dark' }} onClick={() => {}} />
+
+// ✅ useMemo/useCallback
+const config = useMemo(() => ({ theme: 'dark' }), []);
+const handleClick = useCallback(() => {}, []);
+<Child config={config} onClick={handleClick} />
+```
+
+## 코드 품질 도구
+
+```bash
+# TypeScript 컴파일
+tsc --noEmit
+
+# ESLint
+eslint src/ --ext .ts,.tsx
+
+# Prettier
+prettier --write src/
+
+# 테스트
+vitest
+# or
+jest
+```
+
+## 체크리스트
+
+TypeScript/React 코드 작성 시:
+
+- [ ] 타입 안전성 100% (no any)
+- [ ] 함수형 컴포넌트 + Hooks
+- [ ] Custom Hook으로 로직 분리
+- [ ] Props 타입 명확히 정의
+- [ ] React Query로 서버 상태 관리
+- [ ] Zod로 Contract 정의
+- [ ] JSX ≤ 50줄 (컴포넌트 분리)
+- [ ] useCallback/useMemo 최적화
+- [ ] Error Boundary 사용
+- [ ] 타입 가드 활용
+- [ ] 복잡도 ≤ 10