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

## 概要

本ドキュメントは、Prettierパッケージのビルドを実行するスクリプト `scripts/build/build.js` の設計仕様を記載したものです。

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

本バッチは、Prettierプロジェクトの各パッケージをesbuildを使用してバンドル・ビルドし、配布可能な形式のJavaScriptファイルを生成します。

**業務上の目的・背景**：Prettierはソースコードを複数のモジュールに分割して開発されていますが、配布時には単一または少数のバンドルファイルとして提供する必要があります。本バッチは、開発時のソースコードを本番環境向けの最適化されたバンドルに変換し、npmパッケージとして配布可能な状態にするために必要です。

**バッチの実行タイミング**：開発中の手動実行、リリースプロセス時の自動実行、CI/CDパイプラインでのビルド検証時に実行されます。

**主要な処理内容**：
1. CLIオプションの解析（パッケージ指定、クリーンビルド、サイズ比較等）
2. ビルド対象パッケージの特定と設定の読み込み
3. 必要に応じて既存のdistディレクトリをクリーンアップ
4. 各パッケージの各モジュールファイルを順次ビルド
5. ビルド結果（成功/失敗/スキップ）の表示とファイルサイズの出力

**前後の処理との関連**：本バッチは `generate-builtin-plugins.js` で生成されたプラグイン定義を含むソースコードをビルドします。ビルド成果物はリリースプロセス（release.js, run.js）で使用されます。

**影響範囲**：distディレクトリ配下の全ビルド成果物、npmパッケージとして公開される全ファイル。

## バッチ種別

ビルド処理 / バンドル生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（開発時・リリース時） |
| 実行時刻 | 任意 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | 手動 / CI/CD / リリースプロセス |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.jsがインストールされていること |
| 依存パッケージ | yarn installにより依存パッケージがインストール済みであること |
| ソースコード | src/ディレクトリにビルド対象のソースコードが存在すること |

### 実行可否判定

特になし。常に実行可能。ただし、--filesオプション指定時は指定ファイルのみビルド対象となる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --packages | string[] | No | 全パッケージ | ビルド対象のパッケージ名を指定 |
| --files | string[] | No | 全ファイル | ビルド対象のファイルパスを指定 |
| --clean | boolean | No | false | ビルド前にdistディレクトリを削除 |
| --playground | boolean | No | false | playground用ファイルのみビルド |
| --print-size | boolean | No | false | ビルド後のファイルサイズを表示 |
| --compare-size | boolean | No | false | 安定版とのサイズ差分を表示 |
| --save-as | string | No | - | 出力ファイル名を変更 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| scripts/build/packages/index.js | JavaScript | パッケージ設定の定義 |
| src/ | JavaScript | ビルド対象のソースコード |
| node_modules/prettier/ | JavaScript | サイズ比較用の安定版パッケージ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| dist/ | JavaScript | バンドル済みのJavaScriptファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | パッケージ設定に基づく（例: standalone.js, parser-babel.js等） |
| 出力先 | dist/{パッケージ名}/ |
| 文字コード | UTF-8 |
| 区切り文字 | N/A（JavaScriptファイル） |

## 処理フロー

### 処理シーケンス

```
1. CLIオプション解析
   └─ parseArguments()でコマンドライン引数を解析
2. ビルド対象パッケージの特定
   └─ --packagesオプションに基づきパッケージをフィルタリング
3. distディレクトリのクリーンアップ（--clean指定時）
   └─ DIST_DIRを再帰的に削除
4. パッケージごとのビルドループ
   └─ packageConfigsの各パッケージを順次処理
5. モジュールごとのビルド
   └─ 各モジュールの各ファイルをbuildFile()で処理
6. ビルド結果の表示
   └─ DONE/FAIL/SKIPPEDステータスとサイズ情報を出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[CLIオプション解析]
    B --> C{--clean指定?}
    C -->|Yes| D[distディレクトリ削除]
    C -->|No| E[パッケージループ開始]
    D --> E
    E --> F[モジュールループ]
    F --> G{ファイルスキップ条件?}
    G -->|Yes| H[SKIPPED表示]
    G -->|No| I[file.build実行]
    I --> J{ビルド成功?}
    J -->|Yes| K[DONE表示]
    J -->|No| L[FAIL表示・エラー出力]
    H --> M{次ファイルあり?}
    K --> M
    L --> N[エラースロー]
    M -->|Yes| G
    M -->|No| O{次パッケージあり?}
    O -->|Yes| F
    O -->|No| P[バッチ終了]
```

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

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

本バッチはデータベースを使用しません。

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

N/A

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Unknown package | 存在しないパッケージ名を指定 | 正しいパッケージ名を指定 |
| - | Not a directory | DIST_DIRがファイルとして存在 | DIST_DIRを削除して再実行 |
| - | Build error | esbuildでのビルドエラー | ソースコードのエラーを修正 |

### リトライ仕様

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

### 障害時対応

ビルドエラー発生時はエラー内容をコンソールに出力し、例外をスローして処理を中断します。エラー内容に基づきソースコードを修正後、再実行してください。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（ファイルシステム操作のみ） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A（--cleanオプションで手動クリーンアップ可能） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | パッケージ数 x モジュール数 x ファイル数 |
| 目標処理時間 | 数十秒〜数分（パッケージ数による） |
| メモリ使用量上限 | Node.jsデフォルト制限に依存 |

## 排他制御

同時実行は推奨されません。distディレクトリへの書き込みが競合する可能性があります。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | パッケージビルド開始時 | `[n/m] Building package 'パッケージ名'` |
| 進捗ログ | モジュール処理時 | モジュール名（グレー表示） |
| 終了ログ | パッケージビルド完了時 | `Build package 'パッケージ名' success in 時間` |
| エラーログ | エラー発生時 | エラーオブジェクトの内容 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド失敗 | 1件以上 | コンソール出力（FAIL表示） |
| ファイルサイズ増加 | 安定版との比較 | コンソール出力（黄色表示） |

## 備考

- esbuildを使用した高速バンドリングを実現
- pretty-bytesライブラリでファイルサイズを人間が読みやすい形式で表示
- pretty-msライブラリで処理時間を人間が読みやすい形式で表示
- node-style-textライブラリでコンソール出力に色付け
