# 機能設計書 36-@babel/plugin-transform-numeric-separator

## 概要

本ドキュメントは、Babelの変換プラグイン「@babel/plugin-transform-numeric-separator」の機能設計を記述する。本プラグインはES2021の数値セパレータ（`_`）を、古いJavaScript環境でも動作する形式に変換（削除）する。

### 本機能の処理概要

本プラグインは、数値リテラルおよびBigIntリテラル内のアンダースコア（`_`）セパレータを検出し、raw表現から削除する機能を提供する。これにより、ES2021以前の環境でも数値リテラルを正しく解釈できる。

**業務上の目的・背景**：ES2021で導入された数値セパレータは、`1_000_000`のように大きな数値を読みやすく記述できる機能である。これはソースコードの可読性を向上させるための純粋な構文糖衣であり、実行時の値には影響しない。しかし、古いブラウザやNode.jsバージョンではこの構文をサポートしていないため、トランスパイルが必要となる。

**機能の利用シーン**：
- 大きな数値を扱うコードの可読性向上
- 金融計算や科学計算のコード
- `@babel/preset-env`の一部として自動的に適用される場合

**主要な処理内容**：
1. NumericLiteralノードを検出し、extra.rawからアンダースコアを削除
2. BigIntLiteralノードを検出し、extra.rawからアンダースコアを削除
3. 値（value）自体は変更せず、raw表現のみを変更

**関連システム・外部連携**：
- `@babel/helper-plugin-utils`: プラグインユーティリティ
- `@babel/core`: Babelコアとの統合

**権限による制御**：特になし。変換はビルド時に実行される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIまたはビルドツール経由で使用されるため、画面との関連なし |

## 機能種別

コード変換処理 / AST操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | オプションなし | - |

### 入力データソース

- Babelによってパースされたソースコード（AST形式）
- NumericLiteral、BigIntLiteralノードのextra.rawプロパティ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| transformedAST | AST | 変換後のAST（extra.rawからアンダースコア削除済み） |

### 出力先

- 変換されたASTは`@babel/generator`によってJavaScriptコードとして出力

## 処理フロー

### 処理シーケンス

```
1. プラグイン初期化
   └─ remover関数を定義

2. NumericLiteralの処理
   ├─ extra.rawにアンダースコアが含まれるかチェック
   └─ 含まれる場合、replace(/_/g, "")で削除

3. BigIntLiteralの処理
   ├─ extra.rawにアンダースコアが含まれるかチェック
   └─ 含まれる場合、replace(/_/g, "")で削除
```

### フローチャート

```mermaid
flowchart TD
    A[リテラルノードの訪問] --> B{NumericLiteral or BigIntLiteral?}
    B -->|Yes| C{extra.rawに_あり?}
    B -->|No| Z[変換なし]
    C -->|Yes| D[extra.rawから_を削除]
    C -->|No| Z
    D --> E[変換完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-36-01 | raw表現のみ変更 | valueは変更せず、extra.rawのみ変更 | 常時 |
| BR-36-02 | 全セパレータ削除 | 正規表現/_/gで全てのアンダースコアを削除 | アンダースコア存在時 |

### 計算ロジック

- 変換: `1_000_000` → `1000000`（raw表現）
- 変換: `0xFF_FF` → `0xFFFF`（raw表現）
- 変換: `1_000n` → `1000n`（raw表現、BigInt）

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

該当なし（コンパイル時変換のため）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | SyntaxError | 不正な数値セパレータ構文 | パーサーレベルでエラー |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 変換処理は同期的に実行される
- 非常に軽量な処理（正規表現による文字列置換のみ）

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

- 特になし

## 備考

- 本プラグインは`@babel/preset-env`に含まれており、ターゲット環境に応じて自動的に適用される
- 数値の値自体は変更されないため、実行時の動作に影響はない
- Babelのパーサーが数値セパレータを正しく解析することが前提

---

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

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

### 推奨読解順序

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

本プラグインはNumericLiteralとBigIntLiteralのextra.rawプロパティを変換対象とする。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-transform-numeric-separator/src/index.ts` | 非常にシンプルな構造。remover関数のみ |

**読解のコツ**: 本プラグインは最もシンプルなBabelプラグインの一つ。わずか30行程度のコード。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-transform-numeric-separator/src/index.ts` | remover関数とvisitor定義 |

**主要処理フロー**:
1. **1-2行目**: 必要なモジュールのインポート
2. **10-17行目**: remover関数 - extra.rawからアンダースコアを削除
3. **19-20行目**: APIバージョン検証
4. **22-28行目**: プラグイン定義とvisitor設定

#### Step 3: remover関数の詳細

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts (10-17行目) | `packages/babel-plugin-transform-numeric-separator/src/index.ts` | extra.rawの存在チェックとアンダースコア削除 |

**主要処理フロー**:
- **11行目**: nodeからextraを取得
- **13行目**: extra?.raw?.includes("_")でアンダースコア存在チェック
- **15行目**: extra.raw.replace(/_/g, "")で全削除

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

```
@babel/plugin-transform-numeric-separator/src/index.ts
    │
    └─ remover(path)
           │
           ├─ node.extra?.raw?.includes("_")
           │
           └─ extra.raw = extra.raw.replace(/_/g, "")
```

### データフロー図

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

1_000_000          ─▶  NumericLiteral visitor     ─▶  1000000
(extra.raw)              │                              (extra.raw)
                         └─ remover()
                              └─ replace(/_/g, "")

100_000n           ─▶  BigIntLiteral visitor      ─▶  100000n
(extra.raw)              │                              (extra.raw)
                         └─ remover()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-transform-numeric-separator/src/index.ts` | ソース | プラグインエントリーポイント、変換ロジック |
| package.json | `packages/babel-plugin-transform-numeric-separator/package.json` | 設定 | パッケージ依存関係定義 |
| test/index.js | `packages/babel-plugin-transform-numeric-separator/test/index.js` | テスト | テストランナー設定 |
| fixtures/removal/ | `packages/babel-plugin-transform-numeric-separator/test/fixtures/removal/` | テスト | 削除テストケース |
| fixtures/numeric-separator/ | `packages/babel-plugin-transform-numeric-separator/test/fixtures/numeric-separator/` | テスト | 数値セパレータテストケース |
