# バッチ設計書 2-dev.js

## 概要

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

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

本バッチは、esbuildを使用してVue.jsパッケージの開発用ビルドをウォッチモードで実行するスクリプトである。Rollupによるプロダクションビルドと比較して高速なビルドを提供し、ファイル変更を検知して自動的に再ビルドを行う。

**業務上の目的・背景**：Vue.jsの開発時には、ソースコード変更のたびにプロダクションビルド（Rollup）を実行すると時間がかかりすぎるため、esbuildを使用した高速な開発用ビルド環境が必要である。本バッチはesbuildのウォッチモードを利用し、ファイル変更時に即座にバンドルを再生成することで、開発効率を大幅に向上させる。

**バッチの実行タイミング**：開発者がローカル環境でVue.jsの開発を行う際に手動で実行する。ウォッチモードのため、一度起動すると明示的に停止するまで常駐する。

**主要な処理内容**：
1. コマンドライン引数の解析（出力フォーマット、プロダクションモード、インライン依存オプション）
2. 対象パッケージの決定（位置引数またはデフォルトの'vue'）
3. 出力フォーマット（iife/cjs/esm）の決定
4. 外部依存関係（externals）の解決
5. esbuildコンテキストの作成とウォッチモードの開始
6. ビルド完了時のログ出力プラグインの適用

**前後の処理との関連**：本バッチは `scripts/build.js`（プロダクションビルド）の開発時代替として位置づけられる。`packages-private/` ディレクトリも参照する。compiler-sfcパッケージの場合は `@vue/consolidate` の依存関係も外部化する。

**影響範囲**：対象パッケージの `dist/` ディレクトリ配下に開発用ビルド成果物が生成される。ソースマップも同時に生成される。ウォッチモードのためプロセスが常駐し、ファイル変更を監視し続ける。

## バッチ種別

ビルド処理（開発用・ウォッチモード）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（開発時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 手動実行（開発者による起動） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js実行環境 | Node.jsがインストールされていること |
| pnpm依存関係 | `pnpm install` により依存パッケージ（esbuild等）がインストール済みであること |
| packagesディレクトリ | `packages/` ディレクトリ配下に対象パッケージが存在すること |
| パッケージビルド成果物 | 対象パッケージのエントリポイント（`src/index.ts`）が存在すること |

### 実行可否判定

対象パッケージの `package.json` と `src/index.ts` が存在すれば実行可能。特別な実行可否判定ロジックはない。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| [positionals] | string[] | No | ['vue'] | ビルド対象パッケージ名 |
| --format, -f | string | No | 'global' | 出力フォーマット（global, cjs, esm-bundler, esm-browser, global-runtime等） |
| --prod, -p | boolean | No | false | プロダクションモード（__DEV__をfalseに設定） |
| --inline, -i | boolean | No | false | 全依存関係をインラインでバンドル |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| packages/{target}/src/index.ts | TypeScript | エントリポイントファイル |
| packages/{target}/package.json | JSON | パッケージ設定（version, buildOptions, dependencies等） |
| packages-private/ ディレクトリ | ファイルシステム | プライベートパッケージ一覧 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/{target}/dist/{target}.{postfix}.js | JavaScript | esbuildによるバンドル済みビルド成果物 |
| packages/{target}/dist/{target}.{postfix}.js.map | SourceMap | ソースマップファイル |
| 標準出力 | テキスト | ビルド完了メッセージ（`built: {outfile}`） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | `{target}.{postfix}.js`（例: `vue.global.js`, `vue.esm-bundler.js`） |
| 出力先 | `packages/{target}/dist/` または `packages-private/{target}/dist/` |
| 文字コード | UTF-8 |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ parseArgsにより format, prod, inline オプションを取得
2. 出力フォーマットの決定
   └─ global→iife, cjs→cjs, その他→esm
3. 出力ファイル名のポストフィックス計算
   └─ runtime付きフォーマットの場合は `runtime.{format}` 形式
4. 対象パッケージごとのループ処理
   4.1 パッケージベースディレクトリの決定（packages/ or packages-private/）
   4.2 package.jsonの読み込み
   4.3 出力ファイルパスの決定（vue-compatの場合はvueに変換）
   4.4 外部依存関係の解決
       └─ cjs/esm-bundlerの場合: dependencies + peerDependencies + Node.js組み込みモジュール
       └─ compiler-sfcの場合: @vue/consolidateの依存関係 + 追加の外部モジュール
   4.5 プラグインの設定（log-rebuild, polyfillNode）
   4.6 esbuildコンテキストの作成
       └─ define設定: __COMMIT__, __VERSION__, __DEV__, __TEST__, __BROWSER__等の環境変数
   4.7 ウォッチモードの開始
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[コマンドライン引数解析]
    B --> C[出力フォーマット決定]
    C --> D[対象パッケージループ開始]
    D --> E[パッケージベースディレクトリ決定]
    E --> F[package.json読み込み]
    F --> G[出力ファイルパス決定]
    G --> H{inline指定?}
    H -->|No| I[外部依存関係の解決]
    H -->|Yes| J[全依存をバンドル]
    I --> K[esbuildプラグイン設定]
    J --> K
    K --> L[esbuildコンテキスト作成]
    L --> M[ウォッチモード開始]
    M --> N{次のパッケージあり?}
    N -->|Yes| D
    N -->|No| O[常駐待機]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | esbuildビルドエラー | TypeScriptのコンパイルエラーや構文エラー | エラーメッセージを確認しソースコードを修正（ウォッチモードにより自動再ビルド） |
| - | パッケージ未発見 | 指定パッケージのpackage.jsonまたはsrc/index.tsが存在しない | 正しいパッケージ名を指定して再実行 |
| - | 依存関係解決エラー | @vue/consolidateのpackage.jsonが見つからない（compiler-sfc） | pnpm installを実行して依存関係を再インストール |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | リトライ機構なし（ウォッチモードにより自動再ビルド） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

esbuildのウォッチモードはビルドエラーが発生してもプロセスを終了しない。ソースコードを修正すると自動的に再ビルドが実行される。プロセスの停止はCtrl+Cで行う。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | パッケージ単位 |
| コミットタイミング | esbuildがファイル書き込み完了時 |
| ロールバック条件 | ビルドエラー時は前回の成功ビルド成果物が維持される |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1〜数パッケージ（通常は1パッケージ） |
| 目標処理時間 | esbuildによりミリ秒〜秒単位（Rollupより大幅に高速） |
| メモリ使用量上限 | 明示的な制限なし（Node.jsデフォルト） |

## 排他制御

同一パッケージに対する複数のdev.jsプロセスの同時実行は想定されていない。同一の出力ファイルに対して複数のウォッチモードが同時に書き込むとファイル競合が発生する可能性がある。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ビルド完了ログ | 各ビルド完了時（初回および変更検知時） | `built: {相対ファイルパス}` |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| - | - | 開発用スクリプトのため監視・アラートは設定なし |

## 備考

- 本スクリプトはesbuildを使用しているためRollupよりも大幅に高速だが、tree-shakingの精度やファイルサイズの最適化はRollupに劣る。そのためプロダクションビルドには `build.js`（Rollup）を使用する
- `vue-compat` パッケージの場合、出力ファイル名は `vue.{postfix}.js` に変換される
- `enableNonBrowserBranches` が有効なパッケージでcjs以外のフォーマットの場合、`esbuild-plugin-polyfill-node` プラグインが適用される
- define設定により多数のコンパイル時フラグ（__DEV__, __BROWSER__, __SSR__等）が注入される
- ソースマップは常に生成される（`sourcemap: true`）
