# バッチ設計書 2-setup/setup.js

## 概要

本ドキュメントは、webpack開発環境のセットアップスクリプト `setup/setup.js` の設計仕様を定義するものである。node_modules内にwebpack自身へのシンボリックリンクを作成し、自己参照による開発を可能にする。

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

`setup/setup.js` は、webpackプロジェクトの開発環境を構築するためのセットアップスクリプトである。webpackの開発では、webpack自身がwebpackパッケージに依存するケースがあるため、node_modules/webpack にプロジェクトルートへのシンボリックリンクを作成することで、自己参照を実現する。

**業務上の目的・背景**：webpackはモジュールバンドラーとして自身をビルドツールとして使用する自己参照構造を持つ。テストやリント処理において、プロジェクト内のコードが `require("webpack")` でwebpack自身を参照する必要がある。このスクリプトは、yarn linkを使ったシンボリックリンク作成により、この自己参照構造をセットアップする。

**バッチの実行タイミング**：開発環境の初回セットアップ時および `npm run setup` / `yarn setup` コマンド実行時。また、`prelint` スクリプトの前処理として自動実行される。

**主要な処理内容**：
1. node_modules/webpackディレクトリがシンボリックリンクとして存在するか確認する
2. シンボリックリンクが存在しない場合、yarnのインストール状態を確認する
3. yarnが未インストールの場合、npmでグローバルインストールする
4. `yarn install` で依存関係をインストールする
5. `yarn link` でwebpackシンボリックリンクを作成する
6. `yarn link webpack` でプロジェクト内にリンクを適用する
7. シンボリックリンクの作成結果を検証する

**前後の処理との関連**：package.jsonの `prelint` スクリプトで `yarn setup` が実行されるため、lint処理の前提条件として自動実行される。全てのテスト・リント・ビルド処理がwebpackの自己参照を必要とする場合の前処理となる。

**影響範囲**：node_modules/webpackディレクトリ（シンボリックリンク）、yarnのグローバルリンク登録。Windows環境ではシンボリックリンク作成に管理者権限が必要な場合がある。

## バッチ種別

環境セットアップ / 開発支援

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（初回セットアップ時、およびprelintの前処理として自動実行） |
| 実行時刻 | 任意 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動（npm run setup）または自動（prelintフック） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.jsランタイム | Node.jsがインストールされていること |
| npm | npmがインストールされていること（yarnがない場合のインストールに使用） |
| ネットワーク接続 | yarnのインストールおよびyarn installに必要 |

### 実行可否判定

node_modules/webpackがシンボリックリンクとして存在する場合、セットアップ処理をスキップして正常終了する（冪等性あり）。

## 入力仕様

### 入力パラメータ

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

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| node_modules/webpack | ディレクトリ/シンボリックリンク | シンボリックリンク存在確認対象 |
| node_modules | ディレクトリ | 依存パッケージの格納先 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| node_modules/webpack | シンボリックリンク | プロジェクトルートへのシンボリックリンク |
| 標準出力（stdout） | テキスト | 各処理ステップの進捗メッセージ |
| 標準エラー出力（stderr） | テキスト | エラーメッセージ |
| process.exitCode | 数値 | 0: 正常終了、1: エラー終了 |

### 出力ファイル仕様

直接的なファイル出力はないが、yarn install により node_modules ディレクトリが更新される。

## 処理フロー

### 処理シーケンス

```
1. checkSymlinkExistsAsync() でシンボリックリンクの存在を確認
   └─ node_modulesディレクトリの存在確認
   └─ node_modules/webpackディレクトリの存在確認
   └─ node_modules/webpackがシンボリックリンクであるか確認（fs.lstatSync().isSymbolicLink()）
2. シンボリックリンクが存在する場合
   └─ process.exitCode = 0 で正常終了
3. シンボリックリンクが存在しない場合
   └─ ensureYarnInstalledAsync() でyarnの存在確認
      └─ yarn -v でバージョン出力を取得
      └─ semverパターンでバージョン文字列を検証
      └─ yarnが未インストールの場合、npm install -g yarn でグローバルインストール
   └─ runSetupSymlinkAsync() でシンボリックリンクを作成
      └─ yarn install で依存関係インストール
      └─ yarn link でシンボリックリンク登録
      └─ yarn link webpack でリンク適用
4. 作成後にcheckSymlinkExistsAsync()で検証
   └─ 失敗した場合はエラーをスロー
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[シンボリックリンク存在確認]
    B --> C{node_modules/webpack がシンボリックリンク?}
    C -->|Yes| D[スキップ - exitCode=0]
    C -->|No| E[yarnインストール確認]
    E --> F{yarn がインストール済み?}
    F -->|Yes| G[yarn install 実行]
    F -->|No| H[npm install -g yarn]
    H --> G
    G --> I[yarn link 実行]
    I --> J[yarn link webpack 実行]
    J --> K[シンボリックリンク検証]
    K --> L{シンボリックリンク作成成功?}
    L -->|Yes| D
    L -->|No| M[エラー: symlink作成失敗 - exitCode=1]
    D --> N[バッチ終了]
    M --> N
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| exitCode=1 | シンボリックリンク作成失敗 | Windows環境で管理者権限がない場合等 | 管理者権限で再実行、またはシンボリックリンクを手動作成 |
| exitCode=1 | yarnインストール失敗 | npm install -g yarnが失敗した場合 | ネットワーク接続を確認し手動でyarnをインストール |
| exitCode=1 | yarn install失敗 | 依存関係のインストールが失敗した場合 | ネットワーク接続・npm registry設定を確認 |
| exitCode=1 | yarn link失敗 | シンボリックリンク登録処理が失敗した場合 | yarnのキャッシュをクリアして再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A（リトライ機構は未実装） |

### 障害時対応

シンボリックリンクの作成に失敗した場合は、手動で以下のコマンドを実行する：
1. `yarn install`
2. `yarn link`
3. `yarn link webpack`

Windows環境では管理者権限のコマンドプロンプトで実行する必要がある場合がある。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回の実行で1つのシンボリックリンク作成 |
| 目標処理時間 | シンボリックリンク存在時は即座に完了。新規作成時はyarn installの所要時間に依存（数十秒〜数分） |
| メモリ使用量上限 | 特に制限なし（Node.jsデフォルト） |

## 排他制御

排他制御は行わない。同時実行された場合はyarnのロックファイル機構に依存する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 各処理ステップ開始時 | "Setup: {description}" 形式でステップ名を出力 |
| エラーログ | エラー発生時 | エラー詳細メッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| N/A | N/A | N/A（監視設定は未実装） |

## 備考

- npm scriptの `"setup": "node ./setup/setup.js"` として登録されている
- `prelint` スクリプトで `yarn setup` が実行されるため、lint実行時に自動的にセットアップが行われる
- シンボリックリンクが既に存在する場合は処理をスキップする冪等性を持つ
- yarnのバージョン確認にはsemverパターンによる正規表現マッチングを使用している
- child_processのspawnは `shell: true` オプション付きで実行される
- execGetOutput関数はstdoutの内容をBufferとして収集し、utf8文字列として返却する
