# バッチ設計書 1-build.js

## 概要

本ドキュメントは、Vue.jsプロジェクトのプロダクションビルドスクリプト `scripts/build.js` の設計仕様を定義するバッチ設計書である。

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

本バッチは、Vue.jsモノレポ内の全パッケージまたは指定パッケージに対して、Rollupによるプロダクションビルドを並列実行し、バンドルファイルおよびTypeScript型定義ファイル（.d.ts）の生成を行うスクリプトである。

**業務上の目的・背景**：Vue.jsフレームワークは複数のパッケージ（vue, compiler-core, runtime-core等）で構成されるモノレポ構造を採用しており、各パッケージのプロダクションビルド成果物（ESM, CJS, IIFE形式）を効率的に生成する必要がある。本バッチは、Rollupを使用してコードのバンドル・最適化を行い、リリース可能な成果物を生成する。また、ビルド前にTypeScript enumのインライン変換キャッシュを生成し、バンドルサイズの最適化も実現する。

**バッチの実行タイミング**：リリース前のビルド工程、CI/CDパイプライン内、または開発者が手動でプロダクションビルドを実行する際に随時実行される。

**主要な処理内容**：
1. コマンドライン引数の解析（対象パッケージ、出力フォーマット、オプションの取得）
2. TypeScript enumのスキャンとインライン変換用キャッシュの生成（`scanEnums()`の呼び出し）
3. 対象パッケージのファジーマッチによる解決
4. CPUコア数に基づく並列ビルドの実行（Rollupによるバンドル）
5. ビルド成果物のgzip/brotli圧縮サイズの計測と表示
6. オプション指定時の型定義ファイル（.d.ts）生成
7. enumキャッシュファイルのクリーンアップ

**前後の処理との関連**：本バッチは `scripts/inline-enums.js` の `scanEnums()` 関数を呼び出してenum変換キャッシュを事前生成する。また、`scripts/utils.js` の `targets`, `exec`, `fuzzyMatchTarget` を使用する。リリースフロー（`scripts/release.js`）からは `pnpm run build --withTypes` として間接的に呼び出される。ビルド結果はサイズ計測バッチ（`scripts/size-report.js`, `scripts/usage-size.js`）の入力データとなる。

**影響範囲**：各パッケージの `dist/` ディレクトリ配下にビルド成果物が生成される。`--size` オプション指定時は `temp/size/` ディレクトリにサイズデータJSONが出力される。ビルド前に既存の `dist/` ディレクトリが削除される（特定フォーマット指定時を除く）。

## バッチ種別

ビルド処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 手動実行 / CI/CDパイプライン / リリーススクリプトからの呼び出し |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js実行環境 | Node.jsがインストールされていること |
| pnpm依存関係 | `pnpm install` により依存パッケージがインストール済みであること |
| packagesディレクトリ | `packages/` ディレクトリ配下にビルド対象パッケージが存在すること |
| Gitリポジトリ | `git rev-parse --short=7 HEAD` でコミットハッシュが取得可能であること |
| Rollup設定 | プロジェクトルートに `rollup.config.js` が存在すること |

### 実行可否判定

コマンドライン引数で指定されたパッケージ名がファジーマッチで解決可能であること。解決できない場合はエラー終了する。フルビルド（パッケージ指定なし）かつリリースモードの場合、`package.json` の `private: true` のパッケージはスキップされる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| [positionals] | string[] | No | 全パッケージ | ビルド対象パッケージ名（ファジーマッチ対応） |
| --formats, -f | string | No | パッケージのbuildOptions.formats | 出力フォーマット（例: "cjs", "esm", "global"） |
| --devOnly, -d | boolean | No | false | 開発用ビルドのみ生成（NODE_ENV=development） |
| --prodOnly, -p | boolean | No | false | プロダクション用ビルドのみ生成 |
| --withTypes, -t | boolean | No | false | TypeScript型定義ファイル（.d.ts）も生成 |
| --sourceMap, -s | boolean | No | false | ソースマップを生成 |
| --release | boolean | No | false | リリースモード（privateパッケージをスキップ） |
| --all, -a | boolean | No | false | ファジーマッチで全一致パッケージをビルド |
| --size | boolean | No | false | ビルドサイズデータをJSONファイルに出力 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| packages/ ディレクトリ | ファイルシステム | ビルド対象パッケージ一覧の走査元 |
| packages-private/ ディレクトリ | ファイルシステム | プライベートパッケージ一覧の走査元 |
| package.json（各パッケージ） | JSON | パッケージ設定（buildOptions, private等）の参照元 |
| Gitコミットハッシュ | Git | ビルド環境変数 `COMMIT` の値として使用 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/{target}/dist/ | JavaScript | Rollupによるバンドル済みビルド成果物 |
| packages/{target}/dist/*.d.ts | TypeScript定義 | --withTypes指定時の型定義ファイル |
| temp/size/{fileName}.json | JSON | --size指定時のビルドサイズデータ |
| 標準出力 | テキスト | ビルドサイズ情報（min/gzip/brotli） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | `{target}.global.prod.js`, `{target}.runtime.global.prod.js` 等（Rollup設定による） |
| 出力先 | `packages/{target}/dist/` |
| 文字コード | UTF-8 |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ parseArgsにより formats, devOnly, prodOnly, withTypes, sourceMap, release, all, size オプションを取得
2. サイズ出力ディレクトリの作成（--size指定時）
   └─ temp/size ディレクトリを再帰的に作成
3. TypeScript enumスキャン
   └─ scanEnums()を呼び出し、enum変換キャッシュ(temp/enum.json)を生成
4. ビルド対象パッケージの解決
   └─ 位置引数があればfuzzyMatchTargetで解決、なければ全パッケージを対象
5. 並列ビルドの実行
   └─ CPUコア数を最大並列数として、各パッケージのRollupビルドを実行
   5.1 パッケージディレクトリの解決（packages/ or packages-private/）
   5.2 package.jsonの読み込みとprivateパッケージのスキップ判定
   5.3 既存distディレクトリの削除（特定フォーマット指定時を除く）
   5.4 Rollupコマンドの実行（環境変数: COMMIT, NODE_ENV, TARGET, FORMATS, PROD_ONLY, SOURCE_MAP）
6. ビルドサイズの計測と表示
   └─ global形式のビルド成果物に対してgzip/brotli圧縮サイズを計測
7. 型定義ファイルの生成（--withTypes指定時）
   └─ pnpm run build-dts を実行
8. enumキャッシュのクリーンアップ
   └─ temp/enum.json を削除（finallyブロックで必ず実行）
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{--size指定?}
    B -->|Yes| C[temp/sizeディレクトリ作成]
    B -->|No| D[enumスキャン実行]
    C --> D
    D --> E{対象パッケージ指定あり?}
    E -->|Yes| F[fuzzyMatchTargetで解決]
    E -->|No| G[全パッケージを対象]
    F --> H[並列ビルド実行]
    G --> H
    H --> I[各パッケージのRollupビルド]
    I --> J[ビルドサイズ計測・表示]
    J --> K{--withTypes指定?}
    K -->|Yes| L[型定義ファイル生成]
    K -->|No| M[enumキャッシュ削除]
    L --> M
    M --> N[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファジーマッチエラー | 指定パッケージ名が既存パッケージに一致しない | 正しいパッケージ名を指定して再実行 |
| - | Rollupビルドエラー | Rollupの設定エラーまたはソースコードのコンパイルエラー | エラーメッセージを確認し、ソースコードまたはRollup設定を修正 |
| - | enumスキャンエラー | enumの宣言マージや名前衝突 | 該当するenum定義を修正 |

### リトライ仕様

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

### 障害時対応

ビルド失敗時はenumキャッシュ（`temp/enum.json`）がfinallyブロックで自動削除される。ビルドエラーの原因を確認し、ソースコードまたは設定を修正後に再実行する。`dist/` ディレクトリは次回ビルド時に自動削除されるため、手動クリーンアップは不要。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | パッケージ単位（各パッケージのビルドは独立） |
| コミットタイミング | 各パッケージのビルド完了時 |
| ロールバック条件 | 個別パッケージのビルド失敗はPromise.allにより全体エラーとして伝搬 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約15〜20パッケージ |
| 目標処理時間 | CPUコア数に依存（並列実行による高速化） |
| メモリ使用量上限 | 明示的な制限なし（Node.jsデフォルト） |

## 排他制御

同一パッケージに対する複数ビルドの同時実行は想定されていない。`runParallel` 関数によりCPUコア数を上限とした並列実行制御が行われるが、異なるパッケージ間の排他制御は不要。`dist/` ディレクトリの削除と再生成はビルド開始時に逐次的に実行される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| サイズログ | 各パッケージのビルド完了後 | ファイル名、minサイズ、gzipサイズ、brotliサイズ |
| 型定義ビルドログ | --withTypes指定時 | pnpm run build-dtsの標準出力 |
| Rollupログ | ビルド中 | Rollupのビルド進捗（stdio: inherit） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド失敗 | 1件以上 | プロセス終了コード（非0）により呼び出し元が検知 |

## 備考

- 本スクリプトはESモジュール（`import`構文）で記述されている
- `packages-private/` ディレクトリ内のパッケージもビルド対象となるが、リリースモードまたはフルビルド時はスキップされる
- サイズ計測は `global` フォーマットを含むビルドでのみ実行される
- 並列実行の最大並列数は `os.cpus().length` で決定される
