TypeScript Type Checker Skill

專門處理 TypeScript 類型檢查和類型錯誤修復。

🎯 執行時機

• 用戶提到「類型錯誤」、「type error」
• 執行 npm run typecheck 發現錯誤
• 需要定義或修復 TypeScript 類型
• 代碼中出現 any 需要替換為具體類型

📋 執行流程

1. 執行類型檢查

npm run typecheck

2. 分析錯誤輸出

TypeScript 錯誤格式：

src/components/Login.tsx:42:15 - error TS7006: Parameter 'user' implicitly has an 'any' type.

需要提取：

• 檔案路徑: src/components/Login.tsx
• 行號: 42
• 錯誤碼: TS7006
• 錯誤訊息: Parameter 'user' implicitly has an 'any' type

3. 閱讀相關檔案

必須閱讀的檔案（按順序）：

1. 錯誤所在檔案 – 理解上下文
2. 相關類型定義檔案 – 檢查是否已有類型定義

   # 搜尋類型定義檔案
   Glob: pattern="**/types/**/*.ts"
   Glob: pattern="**/*.d.ts"
   

3. 相關的 interface/type – 尋找可重用的類型

   # 在檔案中搜尋 interface 定義
   Grep: pattern="^(export\\s+)?(interface|type)\\s+" output_mode="content"
   

4. 修復策略

策略 A: 使用現有類型

// ❌ 錯誤
function handleUser(user: any) {}

// ✅ 使用專案中已定義的類型
import { User } from '@/types/user';
function handleUser(user: User) {}

策略 B: 定義新類型

如果專案中沒有合適的類型，在適當位置定義：

// 在 src/types/[domain].ts 中定義
export interface UserProfile {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user' | 'guest';
}

策略 C: 使用泛型

// ❌ 錯誤
function fetchData(url: string): Promise<any> {}

// ✅ 使用泛型
function fetchData<T>(url: string): Promise<T> {}

5. 常見類型錯誤修復

TS7006: 隱式 any 參數

// ❌ 錯誤
const handleClick = (e) => {};

// ✅ 修復
const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {};

TS2339: 屬性不存在

// ❌ 錯誤
interface User {
  name: string;
}
user.email; // Property 'email' does not exist

// ✅ 修復：擴展 interface
interface User {
  name: string;
  email: string;
}

TS2345: 參數類型不匹配

// ❌ 錯誤
function greet(name: string) {}
greet(123);

// ✅ 修復：確保參數類型正確
greet(String(123));
// 或
greet(userId.toString());

TS18046: 可能為 undefined

// ❌ 錯誤
const user = users.find((u) => u.id === id);
console.log(user.name); // 'user' is possibly 'undefined'

// ✅ 修復：加入 null check
const user = users.find((u) => u.id === id);
if (user) {
  console.log(user.name);
}
// 或使用可選鏈
console.log(user?.name);

6. React 特定類型

// Props 類型
interface ButtonProps {
  label: string;
  onClick: () => void;
  disabled?: boolean;
}

// Event handlers
const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {};
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {};
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {};

// State 類型
const [user, setUser] = useState<User | null>(null);
const [items, setItems] = useState<Item[]>([]);

// Ref 類型
const inputRef = useRef<HTMLInputElement>(null);

📋 修復流程

1. Read 錯誤檔案
2. Grep 搜尋相關類型定義
3. 決定修復策略（使用現有/定義新/使用泛型）
4. Edit 修復類型錯誤
5. Bash 執行 npm run typecheck 驗證
6. 重複直到所有錯誤修復

🚨 絕對禁止

// ❌ 永遠不要這樣做
const data: any = fetchData();
function process(input: any): any {}
// @ts-ignore
const result = riskyOperation();

✅ 最佳實踐

1. 優先使用現有類型 – 檢查 src/types/ 目錄
2. 類型定義集中管理 – 放在 src/types/[domain].ts
3. 使用嚴格模式 – 確保 tsconfig.json 開啟 strict
4. Export 可重用類型 – 方便其他檔案使用
5. 使用 Type Guards – 提供 runtime 類型安全

📝 回報格式

## TypeScript 類型修復報告

### 修復的錯誤

1. **src/components/Login.tsx:42**
   - 錯誤: TS7006 - Parameter 'user' implicitly has an 'any' type
   - 修復: 使用 `User` interface from `@/types/user`
   - 狀態: ✅ 已修復

2. **src/api/auth.ts:15**
   - 錯誤: TS2345 - Argument type mismatch
   - 修復: 調整參數類型為 `LoginCredentials`
   - 狀態: ✅ 已修復

### 驗證結果

```bash
npm run typecheck
```

✅ 無類型錯誤

新增的類型定義

• src/types/auth.ts – LoginCredentials, AuthResponse

## 🔗 參考資源

- TypeScript 官方文檔: https://www.typescriptlang.org/docs/
- React TypeScript Cheatsheet: https://react-typescript-cheatsheet.netlify.app/
- 專案規範: `/home/user/maihouses/CLAUDE.md`