# 機能設計書 7-@babel/register

## 概要

本ドキュメントは、BabelのNode.js require hookである`@babel/register`パッケージの設計仕様を記述する。このパッケージは、Node.jsのrequire関数をフックして、ファイルが読み込まれる際に自動的にBabelによるトランスパイルを適用する。

### 本機能の処理概要

**業務上の目的・背景**：Node.js環境で最新のJavaScript構文やTypeScriptを使用したモジュールを、事前のビルドプロセスなしに直接require/importできるようにしたい場合がある。@babel/registerは、Node.jsのモジュールローダーにフックを追加し、ファイル読み込み時に透過的なトランスパイルを実現する。

**機能の利用シーン**：開発環境でのテスト実行（Mocha, Jest等）、@babel/nodeの内部実装、スクリプトの直接実行、ワーカースレッドでのコード実行に利用される。

**主要な処理内容**：
1. piratesライブラリを使用したrequire hookの登録
2. ファイル読み込み時の@babel/coreを使用したトランスパイル
3. ソースマップサポート（@cspotcode/source-map-support）
4. ワーカースレッドでの並列トランスパイル
5. フックの登録解除機能

**関連システム・外部連携**：@babel/core（変換処理）、pirates（require hook）、@cspotcode/source-map-support（ソースマップ）と連携する。

**権限による制御**：Node.js実行環境の権限に準ずる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | プログラマティックなAPIとして動作 |

## 機能種別

ランタイムフック

## 入力仕様

### 入力パラメータ（register関数オプション）

| パラメータ名 | 型 | 必須 | 説明 | デフォルト |
|-------------|-----|-----|------|---------|
| extensions | string[] | No | フック対象の拡張子 | DEFAULT_EXTENSIONS |
| ignore | RegExp[] | No | 無視するファイルパターン | [/node_modules/] |
| only | RegExp[] | No | 対象とするファイルパターン | - |
| cache | boolean | No | キャッシュを有効化 | true |
| その他 | InputOptions | No | @babel/coreのオプション | - |

### 入力データソース

- require/import呼び出し
- @babel/nodeからの呼び出し
- テストランナーからの呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| トランスパイル済みコード | string | 変換後のJavaScriptコード |
| ソースマップ | object | デバッグ用のソースマップ |

### 出力先

- Node.jsモジュールシステムへの返却
- ソースマップはメモリ内に保持

## 処理フロー

### 処理シーケンス

```
1. register関数の呼び出し
   └─ オプションの設定
2. WorkerClientの初期化（必要時）
   └─ ワーカースレッドの起動
3. piratesによるrequire hookの登録
   └─ addHook(compile, { exts, ignoreNodeModules: false })
4. ファイルrequire時
   └─ compileコールバックが呼ばれる
   └─ client.transform(inputCode, filename)
5. トランスパイル実行
   └─ ワーカースレッドで@babel/core.transformSync
6. ソースマップの保存
   └─ maps[filename] = map
   └─ installSourceMapSupport()
7. 変換済みコードの返却
```

### フローチャート

```mermaid
flowchart TD
    A[require/import呼び出し] --> B{フック対象?}
    B -->|No| C[元のrequire処理]
    B -->|Yes| D[compile関数]
    D --> E[client.transform]
    E --> F{ワーカーモード?}
    F -->|Yes| G[ワーカースレッドで変換]
    F -->|No| H[メインスレッドで変換]
    G --> I{変換結果あり?}
    H --> I
    I -->|No| J[元のコードを返却]
    I -->|Yes| K{ソースマップあり?}
    K -->|Yes| L[maps に保存]
    K -->|No| M[コードを返却]
    L --> N[installSourceMapSupport]
    N --> M
    M --> O[Node.jsに返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ignoreNodeModules | node_modulesはデフォルトで無視しない | ignoreNodeModules: false |
| BR-02 | ソースマップ自動設定 | ソースマップがあれば自動的にサポートをインストール | map存在時 |
| BR-03 | プロセス終了時のクリーンアップ | exit/SIGINT/SIGTERMでワーカーをクローズ | ワーカーモード時 |
| BR-04 | 自動登録 | importするだけで自動的にregisterが呼ばれる | require('@babel/register') |

### 計算ロジック

特になし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 構文エラー | 無効なJavaScript | Babelのエラーメッセージ表示 |
| - | 変換エラー | プラグイン/プリセットの問題 | 設定の確認 |

### リトライ仕様

リトライ機能なし

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

該当なし

## パフォーマンス要件

- ワーカースレッドを使用した並列トランスパイル
- ソースマップはメモリ内にキャッシュ
- 実行時コンパイルのため、起動時間にオーバーヘッドあり

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

- 読み込まれるファイルは自動的にトランスパイルされるため、信頼できるソースのみを対象とすること
- node_modulesは対象外（デフォルトでは無視されない設定だが、通常はBabel設定で除外）

## 備考

- ES Modulesにはesmオプションが必要（experimental）
- キャッシュはデフォルトで有効

---

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

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

### 推奨読解順序

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

まず、インターフェースと型定義を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.cts | `packages/babel-register/src/types.cts` | IClient、Options型 |

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

処理の起点となるファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.cts | `packages/babel-register/src/index.cts` | register関数（7-25行目）、エクスポート（27-31行目） |

**主要処理フロー**:
1. **7行目**: register関数定義
2. **9-22行目**: WorkerClient初期化とプロセスイベントリスナー設定
3. **23行目**: WorkerClientの生成
4. **24行目**: hook.registerの呼び出し
5. **33-35行目**: 自動登録処理

#### Step 3: フック処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | hook.cts | `packages/babel-register/src/hook.cts` | compile関数（27-38行目）、register関数（40-49行目） |

**主要処理フロー**:
- **8-25行目**: installSourceMapSupport - ソースマップサポートのインストール
- **27-38行目**: compile関数 - トランスパイル実行とソースマップ保存
- **40-49行目**: register関数 - piratesでフックを登録
- **51-53行目**: revert関数 - フックの登録解除

#### Step 4: ワーカー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | worker-client.cts | `packages/babel-register/src/worker-client.cts` | WorkerClientクラス |
| 4-2 | worker/transform.mts | `packages/babel-register/src/worker/transform.mts` | トランスパイル実行 |

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

```
require('@babel/register') (index.cts)
    │
    ├─ register()
    │      ├─ new WorkerClient() (worker-client.cts)
    │      │      └─ new Worker() - ワーカースレッド起動
    │      │
    │      └─ hook.register() (hook.cts)
    │             └─ pirates.addHook(compile)
    │
    └─ require('some-module')
           │
           └─ compile() (hook.cts)
                  │
                  ├─ client.transform()
                  │      └─ ワーカースレッド
                  │             └─ @babel/core.transformSync
                  │
                  └─ installSourceMapSupport()
```

### データフロー図

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

require呼び出し ───────▶ pirates hook ───────▶ compile
                                                  │
ソースコード ───────▶ client.transform ───────▶ 変換済みコード
                           │
                    @babel/core
                           │
                      ソースマップ ───────▶ maps[filename]
                                                  │
                                    source-map-support
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.cts | `packages/babel-register/src/index.cts` | ソース | エントリーポイント |
| hook.cts | `packages/babel-register/src/hook.cts` | ソース | require hookの実装 |
| worker-client.cts | `packages/babel-register/src/worker-client.cts` | ソース | ワーカークライアント |
| is-in-register-worker.cts | `packages/babel-register/src/is-in-register-worker.cts` | ソース | ワーカー判定 |
| types.cts | `packages/babel-register/src/types.cts` | ソース | 型定義 |
| worker/index.mts | `packages/babel-register/src/worker/index.mts` | ソース | ワーカーエントリー |
| worker/transform.mts | `packages/babel-register/src/worker/transform.mts` | ソース | トランスパイル処理 |
| worker/cache.mts | `packages/babel-register/src/worker/cache.mts` | ソース | キャッシュ管理 |
| worker/handle-message.mts | `packages/babel-register/src/worker/handle-message.mts` | ソース | メッセージハンドラ |
