# 機能設計書 50-@babel/plugin-transform-unicode-regex

## 概要

本ドキュメントは、BabelプラグインであるUnicodeフラグ付き正規表現の変換機能について記述する。

### 本機能の処理概要

**業務上の目的・背景**：
ES2015で導入された正規表現のUnicodeフラグ（u）は、Unicodeコードポイントのマッチングやサロゲートペアの正しい処理を可能にする。しかし、古いブラウザやJavaScript環境ではこのフラグがサポートされていない。本プラグインは、Unicodeフラグ付き正規表現をES5互換の形式に変換し、レガシー環境でも同等の機能を実現する。

**機能の利用シーン**：
- IE11等のレガシーブラウザ対応
- 古いNode.jsバージョンでのUnicode正規表現サポート
- @babel/preset-envを通じた自動的な利用
- 国際化対応アプリケーションでのUnicode文字マッチング

**主要な処理内容**：
1. 正規表現リテラルのuフラグを検出
2. regexpu-coreライブラリを使用してパターンを変換
3. Unicodeコードポイントエスケープを通常のエスケープに変換
4. 変換後のフラグからuを削除

**関連システム・外部連携**：
@babel/helper-create-regexp-features-pluginを使用した正規表現機能プラグインの標準化。regexpu-coreで実際のパターン変換を実行。

**権限による制御**：
特になし（正規表現機能プラグイン共通のオプションを継承）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLI/APIから利用されるプラグインのため、直接の画面関連なし |

## 機能種別

データ変換（AST変換）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| （なし） | - | - | 本プラグインは専用オプションなし | - |

### 入力データソース

Unicodeフラグ（u）付き正規表現を含むJavaScriptソースコード（AST形式）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| transformedAST | t.Program | Unicode対応パターンに変換されたAST |
| transformedRegExp | t.RegExpLiteral | 変換された正規表現リテラル |

### 出力先

変換されたAST（@babel/coreに返却）

## 処理フロー

### 処理シーケンス

```
1. プラグイン初期化
   └─ createRegExpFeaturePluginでプラグイン生成
   └─ feature: "unicodeFlag"を設定
2. pre()フック
   └─ featuresKeyにunicodeFlagを登録
3. RegExpLiteralビジター
   └─ generateRegexpuOptionsでオプション生成
   └─ canSkipRegexpuで変換スキップ判定
   └─ rewritePatternでパターン変換
   └─ transformFlagsでフラグ変換
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[pre()フック]
    B --> C[unicodeFlag機能を登録]
    C --> D{RegExpLiteral?}
    D -->|Yes| E[generateRegexpuOptions]
    E --> F{canSkipRegexpu?}
    F -->|Yes| G[スキップ]
    F -->|No| H[rewritePattern呼び出し]
    H --> I[パターン変換]
    I --> J[transformFlags]
    J --> K[uフラグ削除]
    D -->|No| L[終了]
    G --> L
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-50-01 | uフラグ検出 | 正規表現にuフラグがある場合に変換対象 | uフラグ存在時 |
| BR-50-02 | パターン変換 | Unicodeコードポイントエスケープを変換 | uフラグ存在時 |
| BR-50-03 | フラグ削除 | 変換後にuフラグを削除 | 変換完了後 |
| BR-50-04 | スキップ判定 | 変換不要な場合は処理をスキップ | canSkipRegexpu=true時 |

### 計算ロジック

パターン変換の例:
```javascript
// 入力
/\u{1F600}/u  // Unicode code point escape

// 出力
/\uD83D\uDE00/  // Surrogate pair
```

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

該当なし（ファイルシステム操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| （なし） | - | パターン変換エラーはregexpu-coreで処理 | - |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

特定のパフォーマンス要件なし（変換処理は同期的に実行）

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

- 変換後の正規表現は元のセマンティクスを保持
- 複雑なUnicodeパターンの変換結果は長くなる可能性あり

## 備考

- 本プラグインは@babel/helper-create-regexp-features-pluginを使用した標準的な正規表現機能プラグイン
- 同様のパターンで他のRegExp機能プラグインも実装されている
- regexpu-coreライブラリが実際のパターン変換を担当

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-transform-unicode-regex/src/index.ts` | プラグイン定義（5-12行目） |

**読解のコツ**: 非常にコンパクト（13行）で、createRegExpFeaturePluginに処理を委譲。

#### Step 2: createRegExpFeaturePluginを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | helper-create-regexp-features-plugin/index.ts | `packages/babel-helper-create-regexp-features-plugin/src/index.ts` | createRegExpFeaturePlugin関数（31-129行目） |

**主要処理フロー**:
- **31-36行目**: Options型定義
- **42-73行目**: pre()フック（feature登録）
- **74-127行目**: RegExpLiteralビジター

#### Step 3: パターン変換ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | helper-create-regexp-features-plugin/util.ts | `packages/babel-helper-create-regexp-features-plugin/src/util.ts` | generateRegexpuOptions、canSkipRegexpu関数 |

**主要処理フロー**:
- generateRegexpuOptions: regexpu-core用オプション生成
- canSkipRegexpu: 変換スキップ判定
- transformFlags: フラグ変換

#### Step 4: FEATURES定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | helper-create-regexp-features-plugin/features.ts | `packages/babel-helper-create-regexp-features-plugin/src/features.ts` | FEATURES定数 |

**主要処理フロー**:
- FEATURES.unicodeFlagの定義
- enableFeature関数
- featuresKeyの管理

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

```
@babel/plugin-transform-unicode-regex/src/index.ts
    │
    └─ @babel/helper-create-regexp-features-plugin
           │
           ├─ ./features.ts
           │      ├─ FEATURES
           │      ├─ enableFeature()
           │      └─ featuresKey
           │
           ├─ ./util.ts
           │      ├─ generateRegexpuOptions()
           │      ├─ canSkipRegexpu()
           │      └─ transformFlags()
           │
           └─ regexpu-core
                  └─ rewritePattern()
```

### データフロー図

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

/pattern/u  ──▶  RegExpLiteralビジター
                              │
                              ▼
                     generateRegexpuOptions
                              │
                              ▼
                     canSkipRegexpu判定
                              │
                     ┌────────┴────────┐
                     ▼                 ▼
              スキップ         rewritePattern
                                       │
                                       ▼
                              transformFlags
                                       │
                                       ▼
                              /converted_pattern/
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-transform-unicode-regex/src/index.ts` | ソース | エントリーポイント（13行） |
| package.json | `packages/babel-plugin-transform-unicode-regex/package.json` | 設定 | 依存関係・メタデータ |
| helper-create-regexp-features-plugin | `packages/babel-helper-create-regexp-features-plugin/src/` | ソース | 正規表現機能プラグイン共通基盤 |
| regexpu-core | 外部パッケージ | ライブラリ | 正規表現パターン変換 |
