# バッチ設計書 8-verifyPnP.mjs

## 概要

本ドキュメントは、Jestモノレポにおける Yarn PnP（Plug'n'Play）互換性検証バッチ `verifyPnP.mjs` の設計仕様を記載したものです。このバッチは一時ディレクトリで jest と jest-environment-jsdom をリンクし、PnP 環境でテストが正常に実行できるかを検証します。

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

**業務上の目的・背景**：Yarn Berry（v2以降）では PnP（Plug'n'Play）モードがデフォルトとなり、node_modules ディレクトリを使用しない依存関係解決方式が採用されています。Jest は多くのプロジェクトで使用されるため、PnP 環境での互換性を保証することは重要です。本バッチは、実際に PnP 環境を構築してテストを実行することで、Jest が PnP リンカーで正常に動作することを検証します。

**バッチの実行タイミング**：開発者が `yarn verify-pnp` コマンドを実行した際に随時実行されます。CI/CD パイプラインでは、リリース前の検証として実行されます。PnP 関連の変更を行った場合に必ず実行すべきです。

**主要な処理内容**：
1. 一時ディレクトリを作成
2. `.yarnrc.yml` を設定（enableGlobalCache, yarnPath）
3. `package.json` を作成（jest, jest-environment-jsdom を依存として定義）
4. jsdom 環境用テストファイル（`jsdom.test.js`）を作成
5. node 環境用テストファイル（`node.test.js`）を作成
6. `yarn link --private --all` でローカルパッケージをリンク
7. `yarn jest` でテストを実行
8. 一時ディレクトリをクリーンアップ

**前後の処理との関連**：`yarn build` による全パッケージのビルドが完了していることが前提です。パッケージのリンク処理を行うため、ビルド成果物が必要です。

**影響範囲**：Jest 本体および jest-environment-jsdom の PnP 互換性を検証します。テスト自体は一時ディレクトリで実行されるため、リポジトリには影響しません。

## バッチ種別

検証処理 / 互換性テスト / 統合テスト

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（開発者操作時）/ CI/CD |
| 実行時刻 | 任意 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | `yarn verify-pnp` コマンド実行 / CI/CDパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | ^18.14.0 \|\| ^20.0.0 \|\| ^22.0.0 \|\| >=24.0.0 |
| 依存関係インストール済み | `yarn install` が完了していること |
| ビルド完了 | `yarn build` が完了していること |
| 一時ディレクトリ作成可能 | tempy によるディレクトリ作成が可能であること |

### 実行可否判定

- `.yarnrc.yml` が存在し、読み取り可能であること
- Yarn Berry が使用可能であること

## 入力仕様

### 入力パラメータ

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

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| .yarnrc.yml | YAML | Yarn 設定（yarnPath の取得） |
| packages/* | - | ビルド済みパッケージ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | テスト実行結果 |
| 一時ディレクトリ | 各種 | テスト環境（実行後削除） |

### 出力ファイル仕様

一時ディレクトリ内に以下のファイルを生成（終了時に削除）：

| ファイル名 | 内容 |
|-----------|------|
| .yarnrc.yml | Yarn PnP 設定 |
| package.json | テストプロジェクト定義 |
| jsdom.test.js | JSDOM 環境テスト |
| node.test.js | Node 環境テスト |

## 処理フロー

### 処理シーケンス

```
1. Yarn 設定読み込み
   └─ .yarnrc.yml から yarnPath を取得
2. 一時ディレクトリ作成
   └─ tempy.directory() で一時ディレクトリを生成
3. 設定ファイル生成
   ├─ .yarnrc.yml（enableGlobalCache, yarnPath）
   ├─ package.json（jest, jest-environment-jsdom）
   ├─ jsdom.test.js（window の存在確認）
   └─ node.test.js（window が undefined 確認）
4. パッケージリンク
   └─ yarn link --private --all でローカルパッケージをリンク
5. テスト実行
   └─ yarn jest でテストを実行
6. クリーンアップ
   └─ fs.rmSync で一時ディレクトリを削除
7. 結果出力
   └─ 成功メッセージを出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[.yarnrc.yml 読み込み]
    B --> C[一時ディレクトリ作成]
    C --> D[.yarnrc.yml 生成]
    D --> E[package.json 生成]
    E --> F[jsdom.test.js 生成]
    F --> G[node.test.js 生成]
    G --> H[yarn link --private --all 実行]
    H --> I[yarn jest 実行]
    I --> J{テスト成功?}
    J -->|はい| K[成功メッセージ出力]
    J -->|いいえ| L[エラー発生]
    K --> M[一時ディレクトリ削除]
    L --> M
    M --> N[バッチ終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | - | - | データベースへのアクセスなし |

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

データベース操作は発生しません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| execa Error | yarn link 失敗 | パッケージリンクに失敗 | ビルド完了を確認 |
| execa Error | yarn jest 失敗 | テスト実行に失敗 | PnP 互換性の問題を調査 |
| YAML Error | 設定読み込み失敗 | .yarnrc.yml の形式エラー | Yarn 設定を確認 |

### リトライ仕様

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

### 障害時対応

1. エラーメッセージを確認し、失敗箇所を特定
2. `yarn build` が正常に完了しているか確認
3. PnP 関連のコード変更を確認
4. 一時ディレクトリが残っている場合は手動で削除

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回（2つのテストファイル） |
| 目標処理時間 | 数十秒 |
| メモリ使用量上限 | Jest テスト実行に依存 |

## 排他制御

- 同時実行可能（一時ディレクトリは独立）
- グローバルキャッシュを使用するため、キャッシュ競合の可能性あり

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 成功ログ | 正常終了時 | `Successfully ran Jest with PnP linker` |
| 処理ログ | yarn コマンド実行時 | yarn の標準出力（stdio: 'inherit'） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 非0 | CI/CDパイプライン |

## 備考

### 一時ディレクトリ内のテスト内容

**jsdom.test.js**:
```javascript
/*
 * @jest-environment jsdom
 */
test('dummy', () => {
  expect(window).toBeDefined();
});
```

**node.test.js**:
```javascript
test('dummy', () => {
  expect(typeof window).toBe('undefined');
});
```

### 注意事項

- `enableGlobalCache: true` を設定して Yarn のグローバルキャッシュを使用
- `yarn link --private --all` でルートディレクトリの全パッケージをリンク
- finally ブロックで一時ディレクトリを確実に削除
- テスト失敗時も一時ディレクトリは削除される
