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

## 概要

本ドキュメントは、Babelプラグイン `@babel/plugin-transform-unicode-property-regex` の機能設計を記載したものである。本プラグインは、Unicode Property Escape（`\p{...}` 構文）を使用した正規表現をES5互換の正規表現に変換する。

### 本機能の処理概要

**業務上の目的・背景**：ES2018で導入されたUnicode Property Escape（`\p{Script=Greek}` や `\p{Letter}` など）は、文字のUnicodeプロパティに基づいてマッチングを行う強力な機能である。しかし、古いJavaScript実行環境ではこの構文がサポートされていないため、トランスパイルが必要となる。本プラグインは、Unicode Property Escapeを含む正規表現を、同等の機能を持つES5互換の正規表現パターンに変換することで、レガシー環境でも最新の正規表現機能を利用可能にする。

**機能の利用シーン**：
- 国際化対応のアプリケーションで、特定のスクリプト（ギリシャ文字、漢字など）を検出する場合
- フォームバリデーションで、Unicode文字カテゴリ（文字、数字、記号など）に基づく入力検証を行う場合
- テキスト処理で、絵文字や特定のUnicodeプロパティを持つ文字をマッチングする場合

**主要な処理内容**：
1. AST内のRegExpLiteralノードを検出
2. `u`（unicode）フラグを持つ正規表現で、`\p{...}` または `\P{...}` パターンが含まれるかを判定
3. 該当する場合、`regexpu-core` ライブラリを使用してパターンを変換
4. 変換後のパターンで元の正規表現リテラルを置換

**関連システム・外部連携**：`@babel/helper-create-regexp-features-plugin` を使用して正規表現機能変換の共通処理を実行。内部的に `regexpu-core` ライブラリを利用してパターン変換を行う。

**権限による制御**：本プラグインに権限制御の概念は存在しない。

## 関連画面

該当なし（CLIツール/ビルドツールとして動作）

## 機能種別

データ変換処理（ASTトランスフォーム）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| useUnicodeFlag | boolean | No | 変換後の正規表現にuフラグを維持するかどうか（デフォルト: true） | boolean型でなければエラー |

### 入力データソース

- Babelコアから渡されるAST（抽象構文木）
- `RegExpLiteral` ノードが処理対象

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 変換後AST | AST Node | Unicode Property Escapeが展開された正規表現リテラル |

### 出力先

変換されたASTはBabelコアに返され、最終的にJavaScriptコードとして出力される

## 処理フロー

### 処理シーケンス

```
1. プラグイン初期化
   └─ Babelバージョン検証（^7.0.0-0 || ^8.0.0）
   └─ useUnicodeFlag オプションの検証と取得

2. createRegExpFeaturePlugin 呼び出し
   └─ プラグイン名: "transform-unicode-property-regex"
   └─ 機能フラグ: "unicodePropertyEscape"

3. pre フック実行（ファイル処理開始時）
   └─ featuresKey に機能フラグを設定
   └─ useUnicodeFlag=false の場合、unicodeFlag機能も有効化

4. RegExpLiteral ノード訪問
   └─ 正規表現の特徴を分析
   └─ 変換が必要か判定（canSkipRegexpu）
   └─ regexpu-core でパターン変換
   └─ フラグ変換（transformFlags）
```

### フローチャート

```mermaid
flowchart TD
    A[RegExpLiteral検出] --> B{uフラグあり?}
    B -->|No| Z[スキップ]
    B -->|Yes| C{\\p\{...}パターンあり?}
    C -->|No| Z
    C -->|Yes| D[regexpu-coreで変換]
    D --> E{useUnicodeFlag=true?}
    E -->|Yes| F[uフラグ維持]
    E -->|No| G[uフラグ除去]
    F --> H[変換完了]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | Unicode Property Escape変換 | `\p{PropertyName}` を同等の文字クラスに展開 | uフラグ付き正規表現 |
| BR-02 | 否定形変換 | `\P{PropertyName}` を否定形の文字クラスに展開 | uフラグ付き正規表現 |
| BR-03 | フラグ維持オプション | useUnicodeFlag=true で変換後もuフラグを維持 | オプション設定時 |

### 計算ロジック

Unicode Property Escapeの展開は `regexpu-core` ライブラリが担当。例えば `\p{ASCII}` は `[\0-\x7F]` に展開される。

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

該当なし（データベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | TypeError | useUnicodeFlag が boolean 以外 | エラーメッセージ表示、処理中断 |
| - | SyntaxError | 不正な正規表現パターン | Babelコアがエラー報告 |

### リトライ仕様

該当なし

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

該当なし（ステートレスな変換処理）

## パフォーマンス要件

- 正規表現パターンの複雑さに応じて処理時間が変動
- `canSkipRegexpu` による早期スキップで不要な変換を回避

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

- ユーザー入力の正規表現パターンを直接処理する場合、ReDoS（正規表現サービス拒否攻撃）のリスクに注意

## 備考

- ES2018以降をネイティブサポートする環境ではこのプラグインは不要
- `@babel/preset-env` 使用時は、ターゲット環境に応じて自動的に適用される

---

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

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

### 推奨読解順序

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

正規表現機能プラグインで使用される機能フラグの定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | features.ts | `packages/babel-helper-create-regexp-features-plugin/src/features.ts` | FEATURESオブジェクトで定義される機能フラグ（unicodePropertyEscape = 1 << 2）を確認 |

**読解のコツ**: ビット演算による機能フラグ管理パターン。各機能は独立したビットで表現され、`|`（OR）で組み合わせる。

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

プラグインの初期化処理とオプション検証を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-transform-unicode-property-regex/src/index.ts` | プラグイン定義とオプション処理 |

**主要処理フロー**:
1. **9-15行目**: オプション `useUnicodeFlag` のデフォルト値設定と検証
2. **17-21行目**: `createRegExpFeaturePlugin` の呼び出し、機能名とフラグの指定

#### Step 3: ヘルパープラグインのコア処理を理解する

正規表現変換の共通ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-helper-create-regexp-features-plugin/src/index.ts` | 共通のプラグイン構造とVisitor実装 |
| 3-2 | util.ts | `packages/babel-helper-create-regexp-features-plugin/src/util.ts` | 変換要否判定とオプション生成 |

**主要処理フロー**:
- **42-73行目（index.ts）**: `pre` フックでファイルごとの機能フラグ設定
- **75-126行目（index.ts）**: `RegExpLiteral` Visitorで実際の変換処理
- **108行目（index.ts）**: `rewritePattern` で `regexpu-core` を使用したパターン変換
- **45-78行目（util.ts）**: `canSkipRegexpu` で変換要否を効率的に判定

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

```
@babel/plugin-transform-unicode-property-regex
    │
    └─ createRegExpFeaturePlugin (helper)
           │
           ├─ pre(): 機能フラグ設定
           │
           └─ visitor.RegExpLiteral()
                  │
                  ├─ generateRegexpuOptions()
                  │      └─ hasFeature(): 機能有効性チェック
                  │
                  ├─ canSkipRegexpu(): 変換スキップ判定
                  │
                  └─ rewritePattern() [regexpu-core]
                         └─ パターン変換実行
```

### データフロー図

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

ソースコード           @babel/parser                     変換後コード
/\p{ASCII}/u    ───▶  RegExpLiteral AST  ───▶  Visitor  ───▶  /[\0-\x7F]/u
                                                  │
                                            regexpu-core
                                         (パターン展開)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-transform-unicode-property-regex/src/index.ts` | ソース | プラグインエントリーポイント |
| package.json | `packages/babel-plugin-transform-unicode-property-regex/package.json` | 設定 | パッケージ定義、依存関係 |
| index.ts | `packages/babel-helper-create-regexp-features-plugin/src/index.ts` | ソース | 正規表現機能プラグイン共通処理 |
| features.ts | `packages/babel-helper-create-regexp-features-plugin/src/features.ts` | ソース | 機能フラグ定義 |
| util.ts | `packages/babel-helper-create-regexp-features-plugin/src/util.ts` | ソース | ユーティリティ関数 |
