# バッチ設計書 11-lint_special

## 概要

本ドキュメントは、webpackプロジェクトにおけるnpm script `lint:special` の処理内容、実行条件、入出力仕様、エラー処理等を定義するバッチ設計書である。

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

`lint:special` は、ESLintやTypeScript型チェックでは検出できない、webpackプロジェクト固有の特殊リント処理を一括実行するバッチである。lockfileの整合性検証、JSONスキーマの妥当性検証、型継承の正当性チェック、スキーマフォーマットの検証、ランタイムコード生成の最新性確認、WASMコード生成の最新性確認、型定義コンパイルの最新性確認、スキーマプリコンパイルの最新性確認、型生成の最新性確認を順次実行する。

**業務上の目的・背景**：webpackプロジェクトでは、通常のESLintやTypeScript型チェックではカバーできない、プロジェクト固有の整合性チェックが多数存在する。lockfileの依存関係整合性、JSONスキーマとコードの一致性、自動生成コードの最新性など、手動での確認が困難な項目を自動化し、コード品質を担保する。CIパイプラインにおいて `lint` スクリプトの一部として実行されることで、PRマージ前にこれらの整合性を検証する。

**バッチの実行タイミング**：`yarn lint` の一部として実行される（`yarn lint` は `prelint` で `yarn setup` を実行後、`lint:code`、`lint:special`、`lint:types` 等を順次実行する）。CI/CDパイプラインでのPRチェック時、および開発者によるローカルでの手動実行時に使用される。

**主要な処理内容**：
1. `node node_modules/tooling/lockfile-lint` - lockfileの整合性検証
2. `node node_modules/tooling/schemas-lint` - JSONスキーマの妥当性検証
3. `node node_modules/tooling/inherit-types` - 型継承チェック（読み取り専用モード）
4. `node node_modules/tooling/format-schemas` - スキーマフォーマット検証（読み取り専用モード）
5. `node tooling/generate-runtime-code.js` - ランタイムコード生成の最新性確認（`--write`なしで差分検出のみ）
6. `node tooling/generate-wasm-code.js` - WASMコード生成の最新性確認（`--write`なしで差分検出のみ）
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` - 型生成の最新性確認（テンプレートリテラル無効）

**前後の処理との関連**：`yarn lint` の一部として `lint:code`（ESLint）の後に実行される。`fix:special` が本バッチの自動修正版であり、`--write` オプション付きで同様の処理を実行する。`prelint` で `yarn setup` が事前に実行され、node_modules内のシンボリックリンクが作成されている必要がある。

**影響範囲**：本バッチはリードオンリーのチェック処理であり、ファイルの変更は行わない。差分が検出された場合はプロセス終了コードを1に設定し、CIで失敗として扱われる。対象ファイルは `lib/util/semver.js`（ランタイムコード）、`lib/util/hash/xxhash64.js` および `lib/util/hash/md4.js`（WASMコード）、`schemas/` 配下のJSONスキーマ、`types.d.ts` 等の型定義ファイルである。

## バッチ種別

コード品質チェック / 整合性検証

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | CI/CDパイプライン（PR作成・更新時）、手動実行（`yarn lint` または `yarn lint:special`） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js 16以上 | generate-runtime-code.js および generate-wasm-code.js が Node.js 16以上を要求 |
| npm依存関係インストール済み | `node_modules` 配下にtoolingパッケージ等が必要 |
| yarn setup 実行済み | `prelint` により自動実行。node_modules/webpack へのシンボリックリンクが作成されている必要がある |
| terser インストール済み | generate-runtime-code.js が terser を利用 |
| assemblyscript インストール済み | generate-wasm-code.js が assemblyscript を利用 |
| prettier インストール済み | generate-runtime-code.js が prettier を利用 |

### 実行可否判定

全ての前提条件が満たされていれば実行可能。`&&` 演算子によりコマンドが連結されているため、いずれかのコマンドが失敗（終了コード != 0）した時点で後続のコマンドは実行されない。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本バッチはパラメータを受け取らない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| yarn.lock | lockfile | lockfileの整合性検証対象 |
| schemas/*.json | JSON | JSONスキーマファイル群 |
| lib/util/semver.js | JavaScript | ランタイムコード生成の検証対象 |
| lib/util/hash/xxhash64.js | JavaScript | WASMコード生成の検証対象（xxhash64） |
| lib/util/hash/md4.js | JavaScript | WASMコード生成の検証対象（md4） |
| types.d.ts | TypeScript定義 | 型定義ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力/標準エラー | テキスト | 各チェック処理の結果メッセージ |
| プロセス終了コード | 数値 | 0: 全チェック正常、1: いずれかのチェックで差分検出 |

### 出力ファイル仕様

本バッチ（lint:special）はリードオンリーであり、ファイル出力は行わない。差分が検出された場合は `process.exitCode = 1` が設定され、標準エラーに対象ファイル名が出力される。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし（ファイル出力なし） |
| 出力先 | 標準出力 / 標準エラー |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. lockfile-lint 実行
   └─ yarn.lock の整合性を検証
2. schemas-lint 実行
   └─ schemas/ 配下のJSONスキーマの妥当性を検証
3. inherit-types 実行
   └─ 型継承の正当性をチェック（読み取り専用）
4. format-schemas 実行
   └─ スキーマのフォーマットが正しいか検証（読み取り専用）
5. generate-runtime-code.js 実行
   └─ lib/util/semver.js 内のランタイムコード領域を terser で圧縮し、現在のファイル内容と比較。差分があれば exitCode=1
6. generate-wasm-code.js 実行
   └─ lib/util/hash/xxhash64.js, md4.js 内のWASMコード領域を AssemblyScript でコンパイルし、現在の内容と比較。差分があれば exitCode=1
7. compile-to-definitions 実行
   └─ 型定義のコンパイル結果が最新であるか検証
8. precompile-schemas 実行
   └─ プリコンパイル済みスキーマが最新であるか検証
9. generate-types 実行
   └─ --no-template-literals オプション付きで型生成結果が最新であるか検証
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[lockfile-lint]
    B -->|成功| C[schemas-lint]
    B -->|失敗| Z[バッチ異常終了]
    C -->|成功| D[inherit-types]
    C -->|失敗| Z
    D -->|成功| E[format-schemas]
    D -->|失敗| Z
    E -->|成功| F[generate-runtime-code.js]
    E -->|失敗| Z
    F -->|成功| G[generate-wasm-code.js]
    F -->|失敗| Z
    G -->|成功| H[compile-to-definitions]
    G -->|失敗| Z
    H -->|成功| I[precompile-schemas]
    H -->|失敗| Z
    I -->|成功| J[generate-types --no-template-literals]
    I -->|失敗| Z
    J -->|成功| K[バッチ正常終了]
    J -->|失敗| Z
```

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

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| exit 1 | lockfile不整合 | yarn.lockの内容がpackage.jsonと不一致 | `yarn install` を再実行 |
| exit 1 | スキーマ不正 | JSONスキーマのバリデーションエラー | スキーマファイルを修正 |
| exit 1 | 型継承不正 | 型継承の定義が不正 | `yarn fix:special` で自動修正 |
| exit 1 | スキーマフォーマット不正 | スキーマのフォーマットが規定と異なる | `yarn fix:special` で自動修正 |
| exit 1 | ランタイムコード未更新 | lib/util/semver.js の生成コードが古い | `node tooling/generate-runtime-code.js --write` で再生成 |
| exit 1 | WASMコード未更新 | WASMバイナリの生成コードが古い | `node tooling/generate-wasm-code.js --write` で再生成 |
| exit 1 | 型定義未更新 | コンパイル済み型定義が古い | `yarn fix:special` で自動修正 |
| exit 1 | スキーマプリコンパイル未更新 | プリコンパイル結果が古い | `yarn fix:special` で自動修正 |
| exit 1 | 型生成未更新 | 生成済み型が古い | `yarn fix:special` で自動修正 |
| Error | Node.jsバージョン不足 | Node.js 16未満で実行 | Node.js 16以上にアップグレード |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

各コマンドは `&&` で連結されているため、失敗時は該当コマンドのエラーメッセージを確認し、対応する修正コマンド（`yarn fix:special`）を実行する。全体的に `yarn fix` を実行することで、修正可能な問題は自動修復される。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | プロジェクト内の対象ファイル群（数十〜数百ファイル） |
| 目標処理時間 | 数分以内（AssemblyScriptコンパイル含む） |
| メモリ使用量上限 | デフォルトのNode.jsヒープ上限（約1.5GB） |

## 排他制御

同一プロジェクトディレクトリ内での同時実行は想定していない。CIでは各ジョブが独立した環境で実行されるため、排他制御は不要。ローカル開発では開発者が手動で排他を管理する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 各コマンド実行時 | 各toolingスクリプトの標準出力 |
| エラーログ | 差分検出時 | `{file} need to be updated` 等のメッセージ（標準エラー） |
| エラーログ | 実行失敗時 | 各コマンドのエラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| プロセス終了コード | != 0 | CI/CDパイプライン（GitHub Actions等） |
| 実行時間 | CI設定のタイムアウト値 | CI/CDパイプライン |

## 備考

- `lint:special` はリードオンリーモードで実行される。自動修正を行う場合は `fix:special`（`--write` オプション付き）を使用する。
- `tooling` パッケージは `webpack/tooling#v1.24.6` として devDependencies に定義されており、GitHub上の webpack/tooling リポジトリから取得される。
- `generate-types` に `--no-template-literals` オプションが付与されているのは、互換性維持のためテンプレートリテラル形式の型生成を抑制するためである。
