# 機能設計書 73-@babel/plugin-syntax-decorators

## 概要

本ドキュメントは、@babel/plugin-syntax-decoratorsの機能設計について記載する。このパッケージは、Babelパーサーでデコレータ構文の解析を有効化するための構文プラグインである。

### 本機能の処理概要

**業務上の目的・背景**：デコレータはクラス、メソッド、プロパティなどにメタデータや動作を付加するための宣言的な構文であり、TypeScriptやAngular、NestJSなどのフレームワークで広く使用されている。TC39でStage 3の提案として標準化が進んでいる。本プラグインは、Babelパーサーに対してデコレータ構文（@decorator形式）の解析機能を有効化し、クラスデコレータ、メソッドデコレータ、アクセサデコレータなどの構文を解析可能にする。

**機能の利用シーン**：デコレータを使用したJavaScript/TypeScriptソースコードをBabelで処理する際に使用される。単体では構文の解析のみを行い、デコレータの変換は行わない。変換が必要な場合は、@babel/plugin-proposal-decoratorsと組み合わせて使用する。レガシーデコレータと2023-11仕様の両方をサポートする。

**主要な処理内容**：
1. プラグインオプション（version）の受け取りとバリデーション
2. Babelバージョンの互換性チェック（^7.0.0-0 || ^8.0.0）
3. versionオプションの必須チェックと値検証（"2023-11" | "legacy"）
4. Babel 8での非推奨オプション（legacy、decoratorsBeforeExport）のエラー処理
5. parserOptsへのデコレータプラグイン設定の追加

**関連システム・外部連携**：@babel/parserと連携し、パーサーオプションを操作する。@babel/helper-plugin-utilsのdeclare関数を使用してプラグインを定義する。

**権限による制御**：権限による実行制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI/ビルドツール経由での利用 |

## 機能種別

構文解析設定 / パーサー設定変更

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| version | "legacy" \| "2023-11" | Yes | デコレータのバージョン指定 | "2023-11"または"legacy"のいずれか |

### 入力データソース

Babel設定ファイル（babel.config.js、.babelrcなど）からプラグインオプションとして取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | string | プラグイン名 "syntax-decorators" |
| manipulateOptions | function | パーサーオプションを変更する関数 |

### 出力先

@babel/coreのプラグインシステムに対してPluginObjectを返却

## 処理フロー

### 処理シーケンス

```
1. プラグイン初期化
   └─ declare関数でプラグインファクトリを定義
2. Babelバージョン検証
   └─ api.assertVersionで^7.0.0-0 || ^8.0.0を検証
3. オプション取得とバリデーション
   ├─ versionオプションの必須チェック
   ├─ versionの値検証（"2023-11" | "legacy"）
   ├─ legacyオプションのBabel 8非推奨エラー
   └─ decoratorsBeforeExportオプションのBabel 8非推奨エラー
4. manipulateOptions実行
   ├─ version="legacy"の場合: decorators-legacyを追加
   └─ version="2023-11"の場合: decoratorsとdecoratorAutoAccessorsを追加
```

### フローチャート

```mermaid
flowchart TD
    A[プラグイン読み込み] --> B[declare関数実行]
    B --> C{Babelバージョン検証}
    C -->|失敗| D[バージョンエラー]
    C -->|成功| E{versionオプション検証}
    E -->|未定義| F[必須エラーをスロー]
    E -->|定義あり| G{version値検証}
    G -->|不正な値| H[値エラーをスロー]
    G -->|正常| I{legacyオプション検証}
    I -->|設定あり| J[非推奨エラーをスロー]
    I -->|設定なし| K{decoratorsBeforeExport検証}
    K -->|設定あり| L[非推奨エラーをスロー]
    K -->|設定なし| M[PluginObject返却]
    M --> N[manipulateOptions呼び出し]
    N --> O{version判定}
    O -->|legacy| P[decorators-legacyを追加]
    O -->|2023-11| Q[decorators, decoratorAutoAccessorsを追加]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-73-01 | バージョン互換性 | Babel 7.0.0-beta以降またはBabel 8系が必要 | 常時 |
| BR-73-02 | version必須 | versionオプションは必須パラメータ | 常時 |
| BR-73-03 | version値制約 | versionは"2023-11"または"legacy"のみ | 常時 |
| BR-73-04 | legacy非推奨 | legacyオプションはBabel 8で削除、version: "legacy"を使用 | legacyオプション指定時 |
| BR-73-05 | decoratorsBeforeExport非推奨 | Babel 8で削除、デコレータはexport前後どちらも可 | decoratorsBeforeExport指定時 |

### 計算ロジック

特になし

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

### 操作別データベース影響一覧

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| BABEL_VERSION_UNSUPPORTED | バージョンエラー | サポートされないBabelバージョン | @babel/coreを更新する |
| - | 必須エラー | versionオプションが未定義 | versionオプションを追加 |
| - | 値エラー | versionが不正な値 | "2023-11"または"legacy"を指定 |
| - | 非推奨エラー | legacyオプションが指定された | version: "legacy"に変更 |
| - | 非推奨エラー | decoratorsBeforeExportが指定された | オプションを削除 |

### リトライ仕様

リトライ対象外（設定エラーのため）

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

トランザクション処理なし

## パフォーマンス要件

パーサーオプションの設定のみのため、オーバーヘッドは極めて小さい

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

特になし（ソースコード解析のみ）

## 備考

- @babel/plugin-proposal-decoratorsを使用する場合、このプラグインは自動的に含まれる
- 2023-11バージョンは最新のTC39 Stage 3仕様に準拠
- legacyバージョンはTypeScript/Babelの旧デコレータ仕様

---

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

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

### 推奨読解順序

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

まず、プラグインで使用されるオプションの型定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-syntax-decorators/src/index.ts` | Optionsインターフェースの定義（3-5行目） |

**読解のコツ**: TypeScriptのユニオン型により、versionオプションが"legacy"または"2023-11"のいずれかであることが型レベルで保証されている。

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

プラグインのエントリーポイントとバリデーションロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-syntax-decorators/src/index.ts` | declare関数によるプラグイン定義（7-45行目） |

**主要処理フロー**:
1. **7行目**: declare関数でプラグインファクトリを定義開始
2. **8行目**: api.assertVersionでBabelバージョンの互換性チェック
3. **10行目**: optionsからversionを取得
4. **12-17行目**: versionが未定義の場合のエラー処理
5. **18-22行目**: versionが不正な値の場合のエラー処理
6. **23-27行目**: legacyオプションがあればBabel 8非推奨エラー
7. **28-32行目**: decoratorsBeforeExportがあればBabel 8非推奨エラー
8. **34-44行目**: manipulateOptionsでversion別にプラグインを追加

#### Step 3: manipulateOptionsの分岐を理解する

バージョンによるパーサープラグインの違いを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-plugin-syntax-decorators/src/index.ts` | manipulateOptions内の分岐（37-43行目） |

**主要処理フロー**:
- **38-39行目**: version="legacy"の場合、decorators-legacyプラグインを追加
- **40-42行目**: version="2023-11"の場合、decoratorsとdecoratorAutoAccessorsの2つを追加

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

```
@babel/plugin-syntax-decorators/src/index.ts
    │
    ├─ @babel/helper-plugin-utils
    │      └─ declare() - プラグイン定義ラッパー
    │
    └─ @babel/core (実行時)
           ├─ api.assertVersion() - バージョン検証
           └─ manipulateOptions() - パーサー設定変更
                  └─ parserOpts.plugins.push()
                         ├─ "decorators-legacy" (legacy)
                         └─ "decorators", "decoratorAutoAccessors" (2023-11)
```

### データフロー図

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

プラグインオプション ───▶ declare()ラッパー ───▶ PluginObject
  - version: "legacy"        │
    または "2023-11"          │
                              ▼
                      バリデーション
                        │
                        ├──version="legacy"──▶ ["decorators-legacy"]
                        │
                        └──version="2023-11"─▶ ["decorators", "decoratorAutoAccessors"]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-syntax-decorators/src/index.ts` | ソース | プラグインのメイン実装 |
| index.ts | `packages/babel-helper-plugin-utils/src/index.ts` | ソース | declare関数の提供 |
| package.json | `packages/babel-plugin-syntax-decorators/package.json` | 設定 | パッケージメタデータと依存関係 |
