# 機能設計書 53-ESLint設定

## 概要

本ドキュメントは、Payload CMS用のESLint設定パッケージ（@payloadcms/eslint-config）の機能設計を定義する。このパッケージは、Payloadプロジェクト開発における一貫したコード品質を保証するための共通ESLint設定を提供する。

### 本機能の処理概要

ESLint設定パッケージは、TypeScript、React、アクセシビリティ、およびPayload固有のルールを統合したFlat Config形式のESLint設定を提供する。

**業務上の目的・背景**：大規模なモノレポプロジェクトであるPayload CMSでは、全パッケージで一貫したコーディング規約を適用する必要がある。また、コントリビューターが増加する中で、コードレビューの負担を軽減し、自動的にコード品質を担保する仕組みが必要である。ESLint設定パッケージは、Payloadチームが推奨するベストプラクティスを設定として提供し、開発者体験を向上させる。

**機能の利用シーン**：
- Payloadモノレポ内の全パッケージでのリント実行
- 新しいPayloadプロジェクト作成時の初期設定
- CI/CDパイプラインでのコード品質チェック
- エディタ統合によるリアルタイムフィードバック

**主要な処理内容**：
1. TypeScript型チェック統合ESLint設定（typescript-eslint推奨設定）
2. React/JSXルール設定（@eslint-react、react-hooks）
3. アクセシビリティルール（jsx-a11y）
4. コードスタイル強制（perfectionist、Prettier統合）
5. Payload固有ルール（@payloadcms/eslint-plugin）
6. テストファイル用設定（vitest）
7. React Compiler対応設定

**関連システム・外部連携**：
- ESLint 9.x（Flat Config形式）
- TypeScript 5.7+
- Prettier（競合回避設定）
- VS Code/WebStorm（エディタ統合）

**権限による制御**：開発ツールのため、権限制御は存在しない。

## 関連画面

本機能は開発支援ツールであり、Payload CMSの管理画面とは直接関連しない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 管理画面との直接の関連なし |

## 機能種別

開発支援ツール / コード品質管理 / 静的解析設定

## 入力仕様

### 入力パラメータ

#### eslint.config.mjs での使用

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| rootEslintConfig | Config[] | - | メインのESLint設定配列 | ESLint Flat Config形式 |

### 入力データソース

- ソースコード: .ts、.tsx、.js、.mjs、.cjsファイル
- tsconfig.json: TypeScript型チェック設定
- eslint.config.mjs: プロジェクト固有の設定上書き

## 出力仕様

### 出力データ

#### ESLint診断結果

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ruleId | string | 適用されたルールID |
| severity | number | 重要度（1=warn、2=error） |
| message | string | 診断メッセージ |
| line | number | 問題発生行 |
| column | number | 問題発生列 |

### 出力先

- コンソール: ESLint実行結果
- IDE: エディタ上のリアルタイムフィードバック

## 処理フロー

### 処理シーケンス

```
1. ESLint設定読み込み
   └─ rootEslintConfigのエクスポート
2. 設定のマージ
   └─ deepMergeによる複数設定の統合
3. ファイルタイプ別設定適用
   ├─ *.ts: TypeScript設定
   ├─ *.tsx: TypeScript-React設定
   ├─ *.spec.ts: テスト設定
   └─ *.config.ts: Payload設定ファイル用
4. ルール評価
   └─ 各ファイルに対するルールの適用
```

### フローチャート

```mermaid
flowchart TD
    A[ESLint実行] --> B[Flat Config読み込み]
    B --> C[deepMergeで設定統合]
    C --> D{ファイル拡張子}
    D -->|.ts| E[TypeScript設定適用]
    D -->|.tsx| F[TypeScript-React設定適用]
    D -->|.spec.ts| G[テスト設定追加適用]
    D -->|*.config.ts| H[Payload設定ファイル用適用]
    E --> I[ルール評価実行]
    F --> I
    G --> I
    H --> I
    I --> J[診断結果出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-53-01 | TypeScript型チェック | typescript-eslint recommendedTypeChecked設定を使用 | .ts/.tsxファイル |
| BR-53-02 | React Hooks検証 | react-hooks/rules-of-hooksをerrorに設定 | .tsxファイル |
| BR-53-03 | オブジェクトソート | perfectionistによるオブジェクトプロパティのソート強制 | 全ファイル |
| BR-53-04 | Prettier競合回避 | eslint-config-prettierでフォーマットルールを無効化 | 全ファイル |
| BR-53-05 | 未使用変数警告 | _プレフィックスで始まる変数は除外 | 全TypeScriptファイル |
| BR-53-06 | JSXインポート禁止 | payload/no-jsx-import-statementsルール | 全ファイル |
| BR-53-07 | デフォルトエクスポート制限 | no-restricted-exportsでデフォルトエクスポートを警告 | *.config.ts以外 |

### 計算ロジック

**deepMergeロジック**:
```javascript
// obj2がobj1より優先
// 配列は要素ごとにマージ
// nullまたはundefinedはマージしない（元の値を保持）
function deepMerge(...objs) {
  return objs.reduce((acc, obj) => _deepMerge(acc, obj), {})
}
```

## データベース操作仕様

ESLint設定はデータベースを操作しない。

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 設定読み込みエラー | 依存パッケージ未インストール | npm install実行 |
| - | パーサーエラー | TypeScript設定不備 | tsconfig.json確認 |

### リトライ仕様

リトライは行わない。設定エラーは即座にESLint実行失敗として報告される。

## トランザクション仕様

トランザクション管理は不要。

## パフォーマンス要件

- projectServiceによるTypeScript型情報の効率的な取得
- allowDefaultProjectで特定ファイルを追加対象に指定

## セキュリティ考慮事項

- 開発ツールのため、本番環境では使用されない
- 外部ネットワークへのアクセスは行わない

## 備考

- ESLint 9.x（Flat Config形式）が必要
- Prettierとの併用を推奨（eslint-config-prettierで競合回避済み）
- React Compiler（eslint-plugin-react-compiler）対応

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、ESLint Flat Config形式の設定構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | package.json | `packages/eslint-config/package.json` | 依存関係、使用するプラグイン一覧 |

**読解のコツ**:
- **26-44行目**: dependencies内の各プラグインの役割を把握
- typescript-eslint、@eslint-react、perfectionist、jsx-a11y等

#### Step 2: エントリーポイントを理解する

メインの設定ファイルとエクスポートを把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.mjs | `packages/eslint-config/index.mjs` | メインESLint設定のエクスポート |

**主要処理フロー**:
1. **1-13行目**: プラグインとパーサーのインポート
2. **15-55行目**: baseRulesでベースとなるルールを定義
3. **64-109行目**: typescriptRulesでTypeScript固有ルールを定義
4. **114-118行目**: baseExtendsで基本設定をマージ
5. **121-260行目**: rootEslintConfigで最終的な設定配列を構築

#### Step 3: ファイルタイプ別設定を理解する

各ファイルタイプに適用される設定を把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.mjs | `packages/eslint-config/index.mjs` | ファイルタイプ別設定ブロック |

**主要処理フロー**:
- **122-190行目**: 'Settings'ブロック - 共通設定、パーサー、グローバル変数
- **191-211行目**: 'TypeScript'ブロック - .tsファイル用設定
- **212-233行目**: 'TypeScript-React'ブロック - .tsxファイル用設定
- **234-244行目**: 'Unit and Integration Tests'ブロック - .spec.tsファイル用
- **245-254行目**: 'Payload Config'ブロック - *.config.tsファイル用
- **255-259行目**: 'React Compiler'ブロック - .tsxファイル用

#### Step 4: React設定を理解する

React/JSX関連の設定を把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | configs/react/index.mjs | `packages/eslint-config/configs/react/index.mjs` | React設定の定義 |
| 4-2 | configs/react/rules/react.mjs | `packages/eslint-config/configs/react/rules/react.mjs` | Reactルールカスタマイズ |

**主要処理フロー**:
- **10-50行目（index.mjs）**: deepMergeで複数のReact設定を統合
- **11行目**: @eslint-react推奨型チェック設定を使用
- **14行目**: react-hooks推奨ルールを適用
- **46行目**: react-hooks/rules-of-hooksをerrorに設定

#### Step 5: deepMergeユーティリティを理解する

設定マージの仕組みを把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | deepMerge.js | `packages/eslint-config/deepMerge.js` | 設定マージユーティリティ |

**主要処理フロー**:
- **6-54行目**: `_deepMerge`関数でオブジェクトの深いマージを実行
- **11-18行目**: null/undefinedのマージを防止
- **22-42行目**: 配列の要素ごとのマージ処理
- **56-58行目**: `deepMerge`で複数オブジェクトをreduceでマージ

### プログラム呼び出し階層図

```
rootEslintConfig (index.mjs)
    │
    ├─ deepMerge (deepMerge.js)
    │      └─ _deepMerge（再帰的マージ）
    │
    ├─ baseExtends
    │      ├─ js.configs.recommended
    │      ├─ perfectionist.configs
    │      └─ regexpPluginConfigs
    │
    ├─ TypeScript設定
    │      └─ tseslint.configs.recommendedTypeChecked
    │
    ├─ React設定
    │      └─ reactExtends (configs/react/index.mjs)
    │             ├─ react.configs['recommended-type-checked']
    │             ├─ reactHooks.configs.recommended
    │             └─ reactRules / reactA11yRules
    │
    └─ Prettier競合回避
           └─ eslintConfigPrettier
```

### データフロー図

```
[入力]                    [処理]                         [出力]

依存プラグイン設定 ──┐
                     │
ベースルール ────────┼──▶ deepMerge ──▶ 統合設定
                     │       │
React設定 ──────────┘       │
                            ▼
                    ファイルタイプ別振り分け
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
           .ts設定      .tsx設定      .spec.ts設定
              │             │             │
              └─────────────┼─────────────┘
                            ▼
                    ESLint実行エンジン
                            │
                            ▼
                      診断結果出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.mjs | `packages/eslint-config/index.mjs` | 設定 | メインESLint設定 |
| deepMerge.js | `packages/eslint-config/deepMerge.js` | ユーティリティ | 設定マージ関数 |
| package.json | `packages/eslint-config/package.json` | 設定 | パッケージ定義、依存関係 |
| configs/react/index.mjs | `packages/eslint-config/configs/react/index.mjs` | 設定 | React設定 |
| configs/react/rules/react.mjs | `packages/eslint-config/configs/react/rules/react.mjs` | 設定 | Reactルールカスタマイズ |
| configs/react/rules/react-a11y.mjs | `packages/eslint-config/configs/react/rules/react-a11y.mjs` | 設定 | アクセシビリティルール |
