# バッチ設計書 8-examples/build-common.js

## 概要

本ドキュメントは、サンプル共通ビルドスクリプト `examples/build-common.js` の設計仕様を定義するものである。各サンプルのtemplate.mdを読み込み、webpackビルド（production・development・none）を実行してREADME.mdを生成する。

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

`examples/build-common.js` は、webpackのexamplesディレクトリ配下にある各サンプルプロジェクトの共通ビルドロジックを提供するスクリプトである。各サンプルの `build.js` から呼び出され、template.mdテンプレートに基づいてwebpackビルド（最大3モード: production、development、none）を実行し、ビルド結果をテンプレートに埋め込んだREADME.mdを生成する。

**業務上の目的・背景**：webpackの各サンプルプロジェクトはドキュメンテーション兼動作検証として機能する。各サンプルのREADME.mdにはwebpackのビルド出力（バンドルサイズ、チャンク情報、最適化結果等）が含まれており、このスクリプトがその生成を自動化する。production/development/noneの3つのビルドモードで実行することで、各モードの動作の違いを比較できるドキュメントを生成する。

**バッチの実行タイミング**：各サンプルの `build.js` から直接呼び出される。`buildAll.js`（No.7）経由で一括実行されるか、個別のサンプルディレクトリで `node build.js` を実行する際に使用される。

**主要な処理内容**：
1. カレントディレクトリの `template.md` を読み込む
2. production、development、noneの3つのモードでwebpackビルドを順次実行する
3. 各モードのビルド出力からタイムスタンプやバージョン番号をプレースホルダに置換する
4. テンプレート内の対応するセクションにビルド結果を埋め込む
5. テンプレートの基本情報を置換する
6. 最終結果をREADME.mdとして書き出す

**前後の処理との関連**：各サンプルの `build.js` から呼び出される共通処理。`buildAll.js`（No.7）が全サンプルを一括実行する際の個別処理エンジンとして機能する。`template-common.js` モジュールの `needResults`、`replaceResults`、`replaceBase` 関数を使用する。

**影響範囲**：各サンプルディレクトリの `dist/` ディレクトリ（ビルド成果物）および `README.md` ファイル。

## バッチ種別

ビルド / ドキュメント生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（各サンプルのbuild.js経由で実行） |
| 実行時刻 | 任意 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動（各サンプルのbuild.jsから呼び出し） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.jsランタイム | Node.jsがインストールされていること |
| webpack-cli | webpack-cliがインストールされていること（require.resolveで確認） |
| neo-asyncパッケージ | 非同期直列処理に使用 |
| template.md | カレントディレクトリにtemplate.mdが存在すること |
| template-common.js | テンプレート処理ユーティリティモジュール |

### 実行可否判定

webpack-cliが解決できない場合はエラーをスローして処理を中断する（"Please install webpack-cli at root."）。template.mdが存在しない場合はfs.readFileSyncでエラーが発生する。

## 入力仕様

### 入力パラメータ

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

### グローバルフラグ

| フラグ名 | 型 | デフォルト | 説明 |
|---------|-----|----------|------|
| global.NO_TARGET_ARGS | boolean | undefined | ターゲット引数を無効化 |
| global.NO_REASONS | boolean | undefined | stats reasons表示を無効化 |
| global.NO_STATS_OPTIONS | boolean | undefined | statsオプションを無効化 |
| global.NO_PUBLIC_PATH | boolean | undefined | public path設定を無効化 |
| global.STATS_COLORS | boolean | undefined | stats出力のカラー表示を有効化 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| template.md | Markdownファイル | README.md生成用テンプレート |
| template-common.js | JavaScriptモジュール | テンプレート処理ユーティリティ |
| bin/webpack.js | JavaScriptファイル | webpackのCLIエントリポイント（child_process経由で実行） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| dist/ | ビルド成果物 | webpackビルドの出力ファイル |
| README.md | Markdownファイル | ビルド結果を埋め込んだREADMEファイル |
| 標準出力（stdout） | テキスト | webpackビルドの出力 |
| 標準エラー出力（stderr） | テキスト | エラーメッセージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | README.md |
| 出力先 | カレントディレクトリ（各サンプルのディレクトリ） |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. template.md読み込み
   └─ カレントディレクトリのtemplate.mdをUTF-8で読み込み
2. webpack-cliの存在確認
   └─ require.resolve("webpack-cli")で確認
   └─ 未インストールの場合はエラースロー
3. productionモードビルド
   └─ tc.needResults()でテンプレートにproductionセクションがあるか確認
   └─ distディレクトリのクリーンアップ
   └─ "node bin/webpack.js --mode production --env production" を実行
   └─ 出力からタイムスタンプ・バージョン番号をプレースホルダに置換
   └─ tc.replaceResults()でテンプレートのproductionセクションを更新
4. developmentモードビルド
   └─ tc.needResults()でテンプレートにdevelopmentセクションがあるか確認
   └─ distディレクトリのクリーンアップ
   └─ "node bin/webpack.js --mode development --env development --devtool none" を実行
   └─ 出力からタイムスタンプ・バージョン番号をプレースホルダに置換
   └─ tc.replaceResults()でテンプレートのdevelopmentセクションを更新
5. noneモードビルド
   └─ tc.needResults()でテンプレートにnoneセクションがあるか確認
   └─ distディレクトリのクリーンアップ
   └─ "node bin/webpack.js --mode none --env none --output-pathinfo verbose" を実行
   └─ 出力からタイムスタンプ・バージョン番号をプレースホルダに置換
   └─ tc.replaceResults()でテンプレートのnoneセクションを更新
6. テンプレート基本情報の置換
   └─ tc.replaceBase()でベース情報を置換
7. README.md書き出し
   └─ fs.writeFileでREADME.mdを出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[template.md読み込み]
    B --> C{webpack-cliインストール済み?}
    C -->|No| D[エラースロー]
    C -->|Yes| E[productionモードビルド]
    E --> F{productionセクションあり?}
    F -->|Yes| G[distクリーンアップ → webpackビルド → 結果埋め込み]
    F -->|No| H[スキップ]
    G --> I[developmentモードビルド]
    H --> I
    I --> J{developmentセクションあり?}
    J -->|Yes| K[distクリーンアップ → webpackビルド → 結果埋め込み]
    J -->|No| L[スキップ]
    K --> M[noneモードビルド]
    L --> M
    M --> N{noneセクションあり?}
    N -->|Yes| O[distクリーンアップ → webpackビルド → 結果埋め込み]
    N -->|No| P[スキップ]
    O --> Q[tc.replaceBase実行]
    P --> Q
    Q --> R[README.md書き出し]
    R --> S[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Error | webpack-cli未インストール | require.resolve("webpack-cli")が失敗 | webpack-cliをインストール |
| Error | webpackビルドエラー | webpack実行時にエラーが発生 | webpackの設定やソースコードを確認 |
| ENOENT | template.md未検出 | カレントディレクトリにtemplate.mdが存在しない | template.mdを作成 |

### リトライ仕様

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

### 障害時対応

ビルドエラーの場合は、webpackの設定（webpack.config.js）やサンプルのソースコードを確認する。webpack-cliが未インストールの場合はプロジェクトルートで `npm install` を実行する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1サンプルにつき最大3回のwebpackビルド（production/development/none） |
| 目標処理時間 | 各ビルドモードで数秒〜十数秒。合計で数十秒程度 |
| メモリ使用量上限 | webpackビルドはchild_processで実行されるため、親プロセスのメモリ使用量は限定的 |

## 排他制御

排他制御は行わない。neo-asyncのseriesにより3つのビルドモードは順次実行される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ビルド出力 | webpackビルド完了時 | webpackのstats出力 |
| エラーログ | ビルドエラー時 | webpackのエラーメッセージ |

## 監視・アラート

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

## 備考

- 各サンプルの `build.js` から呼び出される共通処理であり、単独では実行されない
- neo-asyncのseries関数で3つのビルドモードを順次実行する
- ビルド出力内のタイムスタンプ（日付と時刻）はプレースホルダに置換される（XXXX-XX-XX、XXXX:XX:XX）
- webpackのバージョン番号もプレースホルダに置換される（webpack X.X.X）
- distディレクトリの内容は各ビルド前にクリーンアップされる（再帰的にファイルを削除）
- 子プロセスのstdin/stdout/stderrはpipeで接続される（connectIO/disconnectIO）
- template-common.jsの `needResults` 関数により、テンプレートに対応するセクションがない場合はビルドがスキップされる
- グローバルフラグにより、webpackのCLI引数（ターゲット、stats、public path等）をカスタマイズ可能
