# 機能設計書 8-@babel/types

## 概要

本ドキュメントは、BabelのAST型システムである`@babel/types`パッケージの設計仕様を記述する。このパッケージは、ASTノードの型定義、ビルダー関数、バリデーター関数、変換ユーティリティを提供する。プラグイン開発において中核的なツールキットとなる。

### 本機能の処理概要

**業務上の目的・背景**：BabelプラグインやAST操作ツールを開発する際、ASTノードの作成・検証・変換を効率的に行う必要がある。@babel/typesは、全てのECMAScript/JSX/TypeScript/FlowのASTノードタイプに対応したビルダー関数とバリデーターを提供し、型安全なAST操作を実現する。

**機能の利用シーン**：Babelプラグイン開発でASTノードを作成・変更する場合、カスタム解析ツールでノードタイプを判定する場合、コード変換ロジックでノードを複製・修正する場合に利用される。

**主要な処理内容**：
1. ASTノードビルダー関数（identifier, memberExpression等）
2. ASTノードバリデーター関数（isIdentifier, isMemberExpression等）
3. ASTノードアサーション関数（assertIdentifier等）
4. ノードのクローン・修正ユーティリティ
5. コメント操作ユーティリティ
6. ノード走査ユーティリティ

**関連システム・外部連携**：@babel/parser（AST入力）、@babel/traverse（AST走査）、@babel/generator（コード生成）、全てのBabelプラグインと連携する。

**権限による制御**：特になし。純粋なメモリ内AST操作のみ。

## 関連画面

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

## 機能種別

AST操作ライブラリ

## 入力仕様

### 入力パラメータ（ビルダー関数の例）

#### identifier(name)
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| name | string | Yes | 識別子名 |

#### memberExpression(object, property, computed?, optional?)
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| object | Expression | Yes | オブジェクト部分 |
| property | Expression \| Identifier \| PrivateName | Yes | プロパティ部分 |
| computed | boolean | No | 計算プロパティか |
| optional | boolean | No | オプショナルチェーンか |

#### cloneNode(node, deep?, withoutLoc?)
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| node | T | Yes | クローン対象のノード |
| deep | boolean | No | 深いクローンを行うか（デフォルト: true） |
| withoutLoc | boolean | No | 位置情報を除外するか（デフォルト: false） |

### 入力データソース

- プラグインからの直接呼び出し
- @babel/traverseのNodePathからの呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ビルダー関数 | t.Node | 生成されたASTノード |
| バリデーター | boolean | ノードタイプ判定結果 |
| アサーション | void \| Error | 型検証（失敗時はエラー） |
| クローン | t.Node | 複製されたノード |

### 出力先

- 呼び出し元への直接返却

## 処理フロー

### 処理シーケンス

```
1. ビルダー関数の呼び出し
   └─ 引数からノードオブジェクトを構築
   └─ validate関数でフィールドを検証
   └─ ノードを返却
2. バリデーター関数の呼び出し
   └─ node.typeとオプションをチェック
   └─ booleanを返却
3. アサーション関数の呼び出し
   └─ バリデーターがfalseならTypeErrorをthrow
4. クローン関数の呼び出し
   └─ ノードをディープコピー
   └─ extraプロパティを処理
   └─ クローンを返却
```

### フローチャート

```mermaid
flowchart TD
    A[t.identifier呼び出し] --> B[ノードオブジェクト構築]
    B --> C{validate?}
    C -->|Yes| D[フィールド検証]
    C -->|No| E[ノード返却]
    D --> F{検証成功?}
    F -->|Yes| E
    F -->|No| G[エラーthrow]

    H[t.isIdentifier呼び出し] --> I{node.type === "Identifier"?}
    I -->|Yes| J{optsマッチ?}
    I -->|No| K[false返却]
    J -->|Yes| L[true返却]
    J -->|No| K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 型継承 | ノードタイプはベースタイプを継承（例: Identifier extends Expression） | 常時 |
| BR-02 | エイリアス | 複数タイプをまとめたエイリアス（例: Expression, Statement） | 常時 |
| BR-03 | validate | ビルダー関数はフィールドを自動検証 | 常時 |
| BR-04 | shallowEqual | オプション指定時は浅い比較 | バリデーター使用時 |
| BR-05 | deprecationWarning | 非推奨機能の使用警告 | 対象機能使用時 |

### 計算ロジック

特になし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | TypeError | アサーション失敗 | 正しいノードタイプを使用 |
| - | ValidationError | ビルダー引数不正 | 正しい引数を渡す |

### リトライ仕様

リトライ機能なし

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

該当なし

## パフォーマンス要件

- 軽量な関数呼び出しで高速なAST操作
- 生成コードによる最適化されたビルダー/バリデーター

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

- AST操作のみでコード実行は発生しない

## 備考

- VISITOR_KEYS, ALIAS_KEYS, NODE_FIELDS等の定数がエクスポートされる
- React用ヘルパー（react.isReactComponent等）も提供

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-types/src/index.ts` | 公開APIのエクスポート構造（1-107行目） |

**読解のコツ**: このファイルは各カテゴリ（asserts, builders, validators等）からre-exportを行っている。カテゴリごとの役割を把握する。

#### Step 2: 定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | definitions/index.ts | `packages/babel-types/src/definitions/index.ts` | ノード定義のエクスポート |
| 2-2 | definitions/core.ts | `packages/babel-types/src/definitions/core.ts` | コアノードタイプの定義 |

#### Step 3: ビルダー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | builders/generated/index.ts | `packages/babel-types/src/builders/generated/index.ts` | 自動生成されたビルダー関数 |
| 3-2 | builders/productions.ts | `packages/babel-types/src/builders/productions.ts` | 手動実装のビルダー関数 |

#### Step 4: バリデーターを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | validators/is.ts | `packages/babel-types/src/validators/is.ts` | is関数の実装 |
| 4-2 | validators/generated/index.ts | `packages/babel-types/src/validators/generated/index.ts` | 自動生成されたバリデーター |

#### Step 5: ユーティリティを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | clone/cloneNode.ts | `packages/babel-types/src/clone/cloneNode.ts` | ノードクローン |
| 5-2 | traverse/traverse.ts | `packages/babel-types/src/traverse/traverse.ts` | 軽量ノード走査 |
| 5-3 | comments/addComment.ts | `packages/babel-types/src/comments/addComment.ts` | コメント追加 |

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

```
@babel/types (index.ts)
    │
    ├─ builders/
    │      ├─ generated/index.ts - 自動生成ビルダー
    │      │      └─ identifier, memberExpression, etc.
    │      ├─ productions.ts - 追加ビルダー
    │      └─ flow/, typescript/, react/
    │
    ├─ validators/
    │      ├─ is.ts - コアis関数
    │      ├─ generated/index.ts - 自動生成バリデーター
    │      │      └─ isIdentifier, isMemberExpression, etc.
    │      └─ その他の検証関数
    │
    ├─ asserts/
    │      └─ generated/index.ts - 自動生成アサーション
    │             └─ assertIdentifier, etc.
    │
    ├─ clone/
    │      └─ cloneNode.ts, clone.ts, cloneDeep.ts
    │
    ├─ comments/
    │      └─ addComment.ts, inheritsComments.ts, etc.
    │
    ├─ converters/
    │      └─ toExpression.ts, toStatement.ts, etc.
    │
    ├─ modifications/
    │      └─ removeProperties.ts, inherits.ts, etc.
    │
    ├─ retrievers/
    │      └─ getBindingIdentifiers.ts, etc.
    │
    ├─ traverse/
    │      └─ traverse.ts, traverseFast.ts
    │
    └─ definitions/
           └─ core.ts, jsx.ts, typescript.ts, flow.ts
```

### データフロー図

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

ノード引数 ───────▶ ビルダー関数 ───────▶ ASTノード
(name, etc)           (identifier)

ASTノード ───────▶ バリデーター ───────▶ boolean
                   (isIdentifier)

ASTノード ───────▶ クローン関数 ───────▶ 複製ノード
                  (cloneNode)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-types/src/index.ts` | ソース | 公開APIのエントリーポイント |
| definitions/index.ts | `packages/babel-types/src/definitions/index.ts` | ソース | ノード定義エクスポート |
| definitions/core.ts | `packages/babel-types/src/definitions/core.ts` | ソース | コアノード定義 |
| definitions/jsx.ts | `packages/babel-types/src/definitions/jsx.ts` | ソース | JSXノード定義 |
| definitions/typescript.ts | `packages/babel-types/src/definitions/typescript.ts` | ソース | TypeScriptノード定義 |
| definitions/flow.ts | `packages/babel-types/src/definitions/flow.ts` | ソース | Flowノード定義 |
| builders/generated/index.ts | `packages/babel-types/src/builders/generated/index.ts` | 生成 | 自動生成ビルダー |
| builders/productions.ts | `packages/babel-types/src/builders/productions.ts` | ソース | 手動ビルダー |
| validators/is.ts | `packages/babel-types/src/validators/is.ts` | ソース | is関数 |
| validators/generated/index.ts | `packages/babel-types/src/validators/generated/index.ts` | 生成 | 自動生成バリデーター |
| validators/validate.ts | `packages/babel-types/src/validators/validate.ts` | ソース | validate関数 |
| asserts/assertNode.ts | `packages/babel-types/src/asserts/assertNode.ts` | ソース | assertNode関数 |
| asserts/generated/index.ts | `packages/babel-types/src/asserts/generated/index.ts` | 生成 | 自動生成アサーション |
| clone/cloneNode.ts | `packages/babel-types/src/clone/cloneNode.ts` | ソース | cloneNode関数 |
| comments/addComment.ts | `packages/babel-types/src/comments/addComment.ts` | ソース | addComment関数 |
| traverse/traverse.ts | `packages/babel-types/src/traverse/traverse.ts` | ソース | traverse関数 |
| traverse/traverseFast.ts | `packages/babel-types/src/traverse/traverseFast.ts` | ソース | traverseFast関数 |
| constants/index.ts | `packages/babel-types/src/constants/index.ts` | ソース | 定数定義 |
