# 通知設計書 6-外部ヘルパー出力

## 概要

本ドキュメントは、babel-build-external-helpersコマンドを実行した際に、Babelの外部ヘルパーコードを標準出力に出力する機能について設計内容を記載する。

### 本通知の処理概要

この通知は、`babel-external-helpers` コマンドを実行した際に、Babelのランタイムヘルパー関数群を生成して標準出力に出力する機能である。

**業務上の目的・背景**：Babelがコードを変換する際、多くの場合ヘルパー関数（_classCallCheck、_createClass、_inheritsなど）が必要になる。これらのヘルパー関数は通常、各ファイルにインライン化されるが、これによりバンドルサイズが増加する。`babel-external-helpers`コマンドを使用することで、すべてのヘルパー関数を1つのファイルにまとめて出力し、アプリケーション内で共有することができる。これにより、コードの重複を減らし、バンドルサイズを最適化できる。

**通知の送信タイミング**：コマンド実行時に即座に出力される。

**通知の受信者**：コマンドを実行した開発者（標準出力を監視しているユーザー、またはリダイレクト先のファイル）

**通知内容の概要**：指定されたヘルパー関数のJavaScriptコードが出力される。出力形式はglobal、umd、var、moduleから選択可能。

**期待されるアクション**：開発者は、出力されたコードをファイルにリダイレクトして保存し、アプリケーションのエントリーポイントで読み込むことで、ヘルパー関数をグローバルに利用可能にする。

## 通知種別

コンソール出力（標準出力：stdout）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（console.log） |
| 優先度 | 高（コマンドの主要出力） |
| リトライ | なし |

### 送信先決定ロジック

標準出力（stdout）に固定。通常はファイルにリダイレクトして使用される。

## 通知テンプレート

### コンソール通知の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準出力（stdout） |
| フォーマット | JavaScript コード |

### 本文テンプレート

出力形式により異なる：

**global形式（デフォルト）:**
```javascript
(function (global) {
  // ヘルパー関数の定義
})(typeof global === "undefined" ? self : global);
```

**umd形式:**
```javascript
(function (root, factory) {
  // UMD wrapper
})(this, function () {
  // ヘルパー関数の定義
});
```

**var形式:**
```javascript
var babelHelpers = {};
// ヘルパー関数の定義
```

**module形式:**
```javascript
export function _classCallCheck(instance, Constructor) {
  // ...
}
// 他のヘルパー関数
```

### 添付ファイル

該当なし

## テンプレート変数

該当なし（@babel/coreのbuildExternalHelpers関数により生成される）

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | babel-external-helpersコマンド実行 | なし（常に出力） | コマンド実行時に即座に発火 |

### 送信抑止条件

特になし（コマンドの主目的が出力であるため）

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[babel-external-helpersコマンド実行] --> B[commander.jsでオプション解析]
    B --> C{--allowlistオプション?}
    C -->|あり| D[指定ヘルパーのみ選択]
    C -->|なし| E[全ヘルパー選択]
    D --> F{--output-typeオプション?}
    E --> F
    F -->|指定あり| G[指定形式で生成]
    F -->|指定なし| H[global形式で生成]
    G --> I[@babel/core.buildExternalHelpers呼び出し]
    H --> I
    I --> J[console.log出力]
    J --> K[終了]
```

## データベース参照・更新仕様

該当なし（データベースを使用しない）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| InvalidArgumentError | --whitelistオプション（廃止）を使用した場合 | エラーメッセージを表示して終了 |

### リトライ仕様

リトライなし

## 配信設定

### レート制限

該当なし

### 配信時間帯

制限なし

## セキュリティ考慮事項

特になし。生成されるコードはBabelの標準ヘルパー関数であり、機密情報は含まれない。

## 備考

- --whitelistオプションは廃止され、--allowlistに置き換えられた
- 出力形式は--output-type（または-t）オプションで指定：global（デフォルト）、umd、var、module
- 通常は`babel-external-helpers > helpers.js`のようにファイルにリダイレクトして使用する

---

## コードリーディングガイド

本通知を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

この機能に関わるデータ構造は、commanderのオプション定義である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | babel-build-external-helpers.ts | `packages/babel-build-external-helpers/src/babel-build-external-helpers.ts` | programオプションの定義を確認（15-33行目） |

**読解のコツ**: commander.jsの`program.option()`メソッドでCLIオプションを定義している。

#### Step 2: エントリーポイントを理解する

コマンド実行時の処理フローを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | babel-build-external-helpers.ts | `packages/babel-build-external-helpers/src/babel-build-external-helpers.ts` | ファイル全体（1-39行目） |

**主要処理フロー**:
1. **1-4行目**: commander.jsと@babel/coreのインポート
2. **15-19行目**: --allowlistオプションの定義（ヘルパーのフィルタリング）
3. **20-28行目**: --whitelistオプションの廃止エラー
4. **29-33行目**: --output-typeオプションの定義
5. **35-37行目**: コマンドライン解析とオプション取得
6. **39行目**: buildExternalHelpers呼び出しとconsole.log出力

#### Step 3: buildExternalHelpers関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | @babel/core | （外部パッケージ） | buildExternalHelpers関数のAPI仕様を確認 |

**主要処理フロー**:
- 第1引数：allowlist（出力するヘルパーの配列、undefined時は全ヘルパー）
- 第2引数：outputType（出力形式：global/umd/var/module）
- 戻り値：生成されたJavaScriptコード文字列

### プログラム呼び出し階層図

```
babel-external-helpers コマンド
    │
    └─ babel-build-external-helpers.ts
           │
           ├─ commander.js
           │      ├─ program.option("--allowlist")
           │      ├─ program.option("--whitelist") [廃止]
           │      └─ program.option("--output-type")
           │
           ├─ program.parse(process.argv)
           │
           ├─ program.opts()
           │      ├─ allowlist: string[] | undefined
           │      └─ outputType: string
           │
           └─ console.log(buildExternalHelpers(allowlist, outputType))
                  │
                  └─ @babel/core.buildExternalHelpers()
                         └─ ヘルパーコード生成
```

### データフロー図

```
[入力]                       [処理]                           [出力]

CLIオプション ──────────────▶ commander.js解析
    │                              │
    ├─ --allowlist                 ▼
    └─ --output-type        program.opts()
                                   │
                                   ▼
                           buildExternalHelpers()
                                   │
                                   ▼
                           console.log() ───────▶ stdout: JavaScriptコード
                                                        │
                                                        ▼
                                                  リダイレクト ───▶ helpers.js
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| babel-build-external-helpers.ts | `packages/babel-build-external-helpers/src/babel-build-external-helpers.ts` | ソース | コマンドのエントリーポイントと出力処理 |
| @babel/core | 外部パッケージ | ライブラリ | buildExternalHelpers関数の実装 |
