typescript-code-review

TypeScript コードレビュースキル

型安全性、ベストプラクティス、パフォーマンス、セキュリティ、保守性に重点を置き、TypeScript コードを徹底的かつ専門的にレビューします。

レビュープロセス

TypeScript コードをレビューするときは、次の構成に沿って進めます。

1. 初期評価

• コードの目的と背景を把握する
• 対象範囲を特定する（単一ファイル、モジュール、機能、またはコードベース全体）
• TypeScript のバージョンと設定を確認する（tsconfig.json を確認）
• 関連するドキュメントやコメントを確認する

2. 主なレビュー項目

型安全性

• Strict モードへの準拠：tsconfig.json で strict: true が設定されていることと、その設定に従っていることを確認する
• 型注釈：適切な型注釈が付いているか確認し、暗黙の any を避ける
• 型の絞り込み：型ガードと型の絞り込みが適切に使われていることを確認する
• ジェネリック型：安全性を損なうことなく柔軟性を実現できているか、ジェネリック型の使い方を確認する
• ユニオン型と交差型：適切に使われ、処理されていることを確認する
• 型アサーション：不要または危険な型アサーション（as キーワードや非 null アサーション演算子）を指摘する
• null／undefined の処理：オプショナルチェーン（?.）と null 合体演算子（??）が適切に使われていることを確認する
• 戻り値の型：すべての関数に明示的な戻り値の型があることを確認する
• 判別可能なユニオン：網羅性チェックが適切に行われていることを確認する

コード品質とベストプラクティス

• 命名規則：明確で説明的な名前が使われていることを確認する（変数／関数には camelCase、型／クラスには PascalCase）
• 関数の長さ：約50行を超える関数や、複雑度の高い関数を指摘する
• 単一責任：関数やクラスが明確な目的を1つだけ持つようにする
• DRY 原則：抽出すべき重複コードを特定する
• マジックナンバー／文字列：定数にすべきハードコード値を指摘する
• エラー処理：try-catch の使い方、エラー型、エラーメッセージを確認する
• Async/await：非同期処理が適切に行われていることを確認し、コールバックとプロミスの混在を避ける
• 不変性：let より const を優先し、配列／オブジェクトの変更を確認する
• Enum とユニオン型：適切な場合は、通常の Enum より const enum またはユニオン型を推奨する

最新の TypeScript 機能

• オプショナルチェーン：ネストされたプロパティへのアクセスには ?. の使用を提案する
• Null 合体演算子：デフォルト値には || より ?? を推奨する
• テンプレートリテラル型：テンプレートリテラルを使用できる箇所がないか確認する
• ユーティリティ型：適切な場合は Partial、Pick、Omit、Record などの使用を提案する
• const アサーション：リテラル型には as const を推奨する
• 型述語：カスタム型ガードに使用する
• satisfies 演算子：型を検証する際は型アサーションの代わりに使用する

パフォーマンス

• 不要な再レンダリング：React／フレームワークでは、メモ化の使用や依存配列を確認する
• 大きなバンドルにつながるインポート：ツリーシェイキングが可能な場合に、ライブラリ全体をインポートしている箇所を指摘する
• 非効率なアルゴリズム：より良い方法がある場合は、O(n²) 以上の計算量を特定する
• メモリーリーク：イベントリスナー、サブスクリプション、タイマーのクリーンアップを確認する
• 遅延読み込み：大きなモジュールには動的インポートを提案する
• 型計算のコスト：コンパイルを遅くする極端に複雑な型計算を指摘する

セキュリティ

• 入力検証：ユーザー入力が検証およびサニタイズされていることを確認する
• XSS の脆弱性：安全でない HTML のレンダリングや eval の使用がないか確認する
• 機密データ：ハードコードされたシークレット、トークン、パスワードを指摘する
• 依存関係の脆弱性：npm audit の実行、または依存関係の確認を推奨する
• セキュリティとしての型安全性：型によってセキュリティ上の問題（タグ付きテンプレートリテラルを介した SQL インジェクションなど）が防止されていることを確認する

テストと保守性

• テストカバレッジ：重要な処理経路にテストが不足していないかを指摘します
• 型のみのインポート：型のみをインポートする場合は import type を使用します
• 循環依存：循環インポートを指摘します
• バレルエクスポート：index ファイルによるパフォーマンス上の問題を確認します
• ドキュメント：公開 API の JSDoc コメントを確認します
• 非推奨の通知：非推奨コードに適切なマークが付いていることを確認します

3. 出力形式

レビューを明確なセクションに分けて整理します。

## Summary
[High-level overview: overall code quality, main concerns, highlights]

## Critical Issues 🔴
[Issues that must be fixed: type errors, security vulnerabilities, breaking bugs]

## Important Improvements 🟡
[Significant issues affecting maintainability, performance, or best practices]

## Suggestions 🔵
[Nice-to-have improvements, style preferences, optimizations]

## Positive Observations ✅
[What the code does well, good patterns to reinforce]

## Detailed Findings

### [Category 1: e.g., Type Safety]
**File**: `path/to/file.ts:line_number`
- **Issue**: [Description]
- **Current code**:
  ```typescript
  [code snippet]

• 推奨事項：

  [improved code]
  

• 理由：[これが重要な理由]

[各指摘について繰り返します]

### 4. Code Review Guidelines

**Tone and Style**:
- Be constructive and specific, not vague or critical
- Explain the "why" behind recommendations
- Provide code examples for suggested changes
- Acknowledge good practices when present
- Use severity indicators (🔴 critical, 🟡 important, 🔵 suggestion)

**Prioritization**:
1. Critical: Security issues, type errors, runtime bugs
2. Important: Performance problems, maintainability issues, anti-patterns
3. Suggestions: Style improvements, modern syntax, optimizations

**Context Awareness**:
- Consider the project's maturity (prototype vs production)
- Respect existing patterns if consistent across codebase
- Note tradeoffs (e.g., performance vs readability)
- Reference the project's TypeScript configuration

### 5. Reference Files

For detailed guidance on specific topics, consult the reference files:

- `references/type-safety-checklist.md` - Comprehensive type safety review points
- `references/common-antipatterns.md` - TypeScript anti-patterns to avoid
- `references/security-checklist.md` - Security considerations for TypeScript
- `references/performance-tips.md` - Performance optimization strategies

Search references using Grep when encountering specific issues. For example:
- Type guard issues: grep "type guard" in `references/type-safety-checklist.md`
- Performance concerns: grep "performance" in `references/performance-tips.md`

### 6. TypeScript Configuration Review

When reviewing `tsconfig.json`, check for:

**Recommended strict settings**:
```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitReturns": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

7. フレームワーク固有の考慮事項

React + TypeScript：

• インターフェースを使ったコンポーネントのプロパティ型
• フック（useState、useEffect、useCallback など）の適切な型付け
• イベントハンドラーの型（例：React.MouseEvent<HTMLButtonElement>）
• Ref の型（useRef<HTMLDivElement>(null)）
• 子要素の型付け（React.ReactNode と React.ReactElement の使い分け）

Node.js + TypeScript：

• Express/Fastify のハンドラーの適切な型
• ミドルウェアにおける非同期エラー処理
• 環境変数の型付け
• データベースクエリ結果の型付け

テスト：

• 型安全なモックとスタブ
• テストユーティリティ（Jest、Vitest など）の適切な型付け
• テストでの型アサーション

8. 推奨する自動チェック

まだ導入していない場合は、次のツールの実行を提案します。

• TypeScript コンパイラー：型チェックに tsc --noEmit を使用します
• ESLint：@typescript-eslint/parser と推奨ルールを使用します
• Prettier：一貫したフォーマットに使用します
• ts-prune：未使用のエクスポートを検出します
• depcheck：未使用の依存関係を検出します
• madge：循環依存を検出します

9. レビューワークフロー

1. まず重大な問題を探します：型エラー、セキュリティ上の問題、明らかなバグ
2. アーキテクチャを確認します：ファイル構成、モジュールの境界、関心の分離
3. ロジックを詳しく確認します：アルゴリズムの正しさ、エッジケース、エラー処理
4. 型を徹底的に確認します：正確性、安全性、TypeScript の機能の適切な使用
5. パフォーマンスを確認します：ボトルネック、不要な処理、最適化の機会を特定します
6. スタイルと一貫性を確認します：命名、フォーマット、パターンへの準拠
7. テストとドキュメントを確認します：カバレッジ、明確さ、保守性

10. やり取りの例

ユーザー：「この TypeScript ファイルの問題点をレビューしてください」

応答の流れ：

1. 提供されたファイルを読みます
2. プロジェクト内に tsconfig.json があるか確認します
3. すべてのカテゴリについて体系的にレビューします
4. 重要度別に指摘事項を整理します
5. コード例を交え、具体的で実行可能な推奨事項を示します
6. 優れた実践例を取り上げます
7. 次のステップ（特定のツールの実行、テストの追加、特定箇所のリファクタリング）を提案します

ベストプラクティス

• 徹底しつつ、実用性を重視します：重要な問題に焦点を当てます
• 背景を説明します：問題となる理由と、引き起こされる可能性のある問題を説明します
• 説明するだけでなく、例を示します：推奨事項にはコード例を含めます
• 対象者を考慮します：チームの TypeScript 経験に応じて詳細さを調整します
• 最新の情報を取り入れます：最新の TypeScript の機能（4.9+、5.0+）を参照します
• バランスを保ちます：完璧を求めて良い結果を損なわないようにし、トレードオフも認識します

このスキルを使用する場合

ユーザーが次のことを求めた場合に、このスキルを有効にします。

• TypeScript コードのコードレビューを明示的に依頼する
• TypeScript の実装についてフィードバックを求める
• コードの問題、バグ、改善点の確認を依頼する
• TypeScript のベストプラクティスが守られているか確認したい
• コード品質や型安全性の改善を支援してほしい
• TypeScript コードのセキュリティ監査またはパフォーマンス監査を依頼する