# バッチ設計書 10-npm script: lint

## 概要

本ドキュメントは、コード品質チェックの一括実行バッチ `npm script: lint` の設計仕様を定義するものである。ESLint、TypeScript型チェック、スペルチェック、フォーマットチェック、特殊リントを順次実行する。

### 本バッチの処理概要

`npm script: lint` は、webpackプロジェクトのコード品質を包括的にチェックするための一括実行バッチである。複数のリントツールとチェック処理を順次実行し、コードの品質基準への準拠を検証する。`prelint` フックにより事前にセットアップ処理が実行される。

**業務上の目的・背景**：webpackは大規模なオープンソースプロジェクトであり、多数のコントリビューターからの変更を受け入れている。コード品質を一定水準に保つために、ESLintによる静的解析、TypeScriptによる型チェック、cspellによるスペルチェック、prettierによるフォーマットチェック、プロジェクト固有の特殊リント処理を統合した包括的なチェック体制が必要である。このバッチはCI/CDパイプラインでの品質ゲートおよび開発者のローカルチェックとして機能する。

**バッチの実行タイミング**：開発者がローカルでコード変更後にチェックする際、CI/CDパイプラインでのプルリクエスト検証時。`pretest` スクリプトの前処理として `npm test` 実行時にも自動的に実行される。

**主要な処理内容**：
1. `prelint` フックで `yarn setup` を実行（webpackのシンボリックリンクセットアップ）
2. `lint:code` - ESLintによるJavaScript/TypeScriptの静的解析（キャッシュ付き）
3. `lint:special` - 特殊リント処理（lockfileリント、スキーマリント、型継承チェック、コード生成チェック等）
4. `lint:types` - TypeScriptコンパイラによる型チェック（tsc）
5. `lint:types-test` - テスト用TypeScript型チェック
6. `lint:types-benchmark` - ベンチマーク用TypeScript型チェック
7. `lint:types-module-test` - モジュールテスト用TypeScript型チェック
8. `lint:types-hot` - HMR用TypeScript型チェック
9. `fmt:check` - Prettierによるフォーマットチェック（修正なし、差分検出のみ）
10. `lint:spellcheck` - cspellによるスペルチェック

**前後の処理との関連**：`prelint` で `yarn setup`（No.2）が実行される。`lint:special` は内部的に `tooling/generate-runtime-code.js`（No.3）と `tooling/generate-wasm-code.js`（No.4）を含む。`pretest` で呼び出されるため、`npm test`（No.9）の前提処理となる。`fix`コマンド（No.12）は修正版のリント処理である。

**影響範囲**：読み取り専用のチェック処理であり、ソースコードに変更は加えない。ESLintのキャッシュファイルとprettierのキャッシュファイルが更新される。

## バッチ種別

リント / コード品質チェック

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（開発時・CI/CD時） |
| 実行時刻 | 任意 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動（npm run lint / yarn lint）またはCI/CD、pretest経由で自動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.jsランタイム | Node.jsがインストールされていること |
| ESLint | eslintがdevDependencyとしてインストール済みであること |
| TypeScript | typescriptがdevDependencyとしてインストール済みであること |
| Prettier | prettierがdevDependencyとしてインストール済みであること |
| cspell | cspellがdevDependencyとしてインストール済みであること |
| toolingパッケージ | webpack/toolingがdevDependencyとしてインストール済みであること |
| webpackセットアップ | prelintフックによりyarn setupが実行済みであること |

### 実行可否判定

`prelint` フック（yarn setup）が失敗した場合はlint処理全体が中断される。各サブコマンドは `&&` で連結されているため、先行するサブコマンドが失敗した場合は後続のサブコマンドは実行されない。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | コマンドライン引数は使用しない |

### サブコマンド一覧

| サブコマンド | 実行内容 | 説明 |
|-------------|---------|------|
| lint:code | `node node_modules/eslint/bin/eslint.js --cache .` | ESLintによるコードチェック（キャッシュ有効） |
| lint:special | 複数ツールの順次実行（後述） | 特殊リント処理一括実行 |
| lint:types | `tsc` | TypeScript型チェック |
| lint:types-test | `tsc -p tsconfig.types.test.json` | テスト用型チェック |
| lint:types-benchmark | `tsc -p tsconfig.types.benchmark.json` | ベンチマーク用型チェック |
| lint:types-hot | `tsc -p tsconfig.hot.json` | HMR用型チェック |
| lint:types-module-test | `tsc -p tsconfig.module.test.json` | モジュールテスト用型チェック |
| lint:spellcheck | `cspell --cache --no-must-find-files --quiet "**/*.*"` | スペルチェック |
| fmt:check | `node node_modules/prettier/bin/prettier.cjs --cache --ignore-unknown --check .` | フォーマットチェック |

### lint:special の内部実行順序

| 順序 | コマンド | 説明 |
|------|---------|------|
| 1 | `node node_modules/tooling/lockfile-lint` | lockfileリント |
| 2 | `node node_modules/tooling/schemas-lint` | スキーマリント |
| 3 | `node node_modules/tooling/inherit-types` | 型継承チェック |
| 4 | `node node_modules/tooling/format-schemas` | スキーマフォーマットチェック |
| 5 | `node tooling/generate-runtime-code.js` | ランタイムコード生成チェック（No.3） |
| 6 | `node tooling/generate-wasm-code.js` | WASMコード生成チェック（No.4） |
| 7 | `node node_modules/tooling/compile-to-definitions` | 定義コンパイル |
| 8 | `node node_modules/tooling/precompile-schemas` | スキーマプリコンパイル |
| 9 | `node node_modules/tooling/generate-types --no-template-literals` | 型生成 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| プロジェクト全ファイル | 各種 | ESLint、prettier、cspellの対象 |
| tsconfig.json | JSON | TypeScript型チェック設定 |
| tsconfig.types.test.json | JSON | テスト用TypeScript設定 |
| tsconfig.types.benchmark.json | JSON | ベンチマーク用TypeScript設定 |
| tsconfig.hot.json | JSON | HMR用TypeScript設定 |
| tsconfig.module.test.json | JSON | モジュールテスト用TypeScript設定 |
| .eslintrc / eslint.config.js | 設定ファイル | ESLint設定 |
| .prettierrc / prettier.config.js | 設定ファイル | Prettier設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力（stdout） | テキスト | 各ツールのチェック結果 |
| 標準エラー出力（stderr） | テキスト | エラーメッセージ |
| process.exitCode | 数値 | 0: 全チェック成功、非0: いずれかのチェック失敗 |
| ESLintキャッシュ | ファイル | .eslintcache（キャッシュファイル） |
| prettierキャッシュ | ファイル | prettierのキャッシュファイル |

### 出力ファイル仕様

チェック処理のみでソースコードの変更は行わない。キャッシュファイルのみが更新される。

## 処理フロー

### 処理シーケンス

```
1. prelintフック実行
   └─ yarn setup を実行（webpackシンボリックリンクセットアップ）
2. lint:code（ESLint）
   └─ eslint --cache . でプロジェクト全体をチェック
3. lint:special（特殊リント）
   └─ lockfile-lint → schemas-lint → inherit-types → format-schemas
   └─ generate-runtime-code.js → generate-wasm-code.js
   └─ compile-to-definitions → precompile-schemas → generate-types
4. lint:types（TypeScript型チェック）
   └─ tsc でメインプロジェクトの型チェック
5. lint:types-test
   └─ tsc -p tsconfig.types.test.json
6. lint:types-benchmark
   └─ tsc -p tsconfig.types.benchmark.json
7. lint:types-module-test
   └─ tsc -p tsconfig.module.test.json
8. lint:types-hot
   └─ tsc -p tsconfig.hot.json
9. fmt:check（Prettierフォーマットチェック）
   └─ prettier --check . でフォーマット差分を検出
10. lint:spellcheck（スペルチェック）
    └─ cspell --cache --quiet "**/*.*" でスペルミスを検出
```

### フローチャート

```mermaid
flowchart TD
    A[npm run lint] --> B[prelint: yarn setup]
    B --> C{setup成功?}
    C -->|No| D[中断]
    C -->|Yes| E[lint:code - ESLint]
    E --> F{成功?}
    F -->|No| D
    F -->|Yes| G[lint:special - 特殊リント]
    G --> H{成功?}
    H -->|No| D
    H -->|Yes| I[lint:types - TypeScript型チェック]
    I --> J{成功?}
    J -->|No| D
    J -->|Yes| K[lint:types-test]
    K --> L{成功?}
    L -->|No| D
    L -->|Yes| M[lint:types-benchmark]
    M --> N[lint:types-module-test]
    N --> O[lint:types-hot]
    O --> P[fmt:check - Prettier]
    P --> Q{成功?}
    Q -->|No| D
    Q -->|Yes| R[lint:spellcheck - cspell]
    R --> S{成功?}
    S -->|No| D
    S -->|Yes| T[全チェック成功 - exitCode=0]
    D --> U[バッチ終了]
    T --> U
```

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

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

本バッチはデータベースを操作しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| exitCode=非0 | ESLintエラー | コーディング規約違反 | `npm run fix:code` で自動修正または手動修正 |
| exitCode=非0 | TypeScript型エラー | 型不整合 | TypeScriptのエラーメッセージに従って修正 |
| exitCode=非0 | Prettierフォーマットエラー | フォーマット不一致 | `npm run fmt` で自動修正 |
| exitCode=非0 | スペルチェックエラー | スペルミス | スペルを修正、またはcspellの辞書に追加 |
| exitCode=非0 | 特殊リントエラー | コード生成・スキーマ等の不整合 | `npm run fix:special` で自動修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

各サブコマンドのエラーに応じた修正を行う。自動修正可能な項目は `npm run fix` で一括修正できる。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データベース操作なし） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | プロジェクト全ファイル |
| 目標処理時間 | 全サブコマンド合計で数分〜十数分（キャッシュ有効時はより短縮） |
| メモリ使用量上限 | TypeScriptコンパイラの型チェックでメモリを多く使用する可能性あり |

## 排他制御

排他制御は行わない。各サブコマンドは `&&` で順次実行される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ESLint結果 | lint:code完了時 | 検出されたエラー・警告の一覧 |
| TypeScriptエラー | lint:types完了時 | 型エラーの一覧 |
| Prettier結果 | fmt:check完了時 | フォーマット不一致のファイル一覧 |
| cspell結果 | lint:spellcheck完了時 | スペルミスの一覧 |
| 特殊リント結果 | lint:special各ステップ完了時 | 各ツールの検出結果 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| lint実行結果 | 失敗 | CI/CDパイプライン通知 |

## 備考

- `prelint` スクリプトで `yarn setup` が自動実行されるため、lint実行前にwebpackのシンボリックリンクが確保される
- 全サブコマンドは `&&` で連結されているため、先行するサブコマンドが失敗すると後続は実行されない（fail-fast方式）
- ESLintとprettierはキャッシュ機構を使用しており、変更のないファイルのチェックをスキップする
- cspellも `--cache` オプションでキャッシュを使用し、`--no-must-find-files` でファイル未検出時もエラーにしない
- lint:specialでは `--write` オプションなしで実行されるため、差分検出のみでファイル変更は行わない
- 修正を行う場合は `npm run fix` コマンドを使用する（fix:code + fix:special + fmt）
- TypeScript型チェックは複数のtsconfig（メイン、テスト、ベンチマーク、モジュールテスト、HMR）に対して個別に実行される
- lint-stagedの設定により、git commitのpre-commitフックでもESLint、prettier、cspellが実行される
