# 機能設計書 2-@babel/parser

## 概要

本ドキュメントは、BabelのJavaScriptパーサーである`@babel/parser`パッケージの設計仕様を記述する。このパッケージは、ソースコードを抽象構文木（AST）に変換する機能を提供し、TC39提案やTypeScript、Flow、JSXの構文をサポートする。

### 本機能の処理概要

**業務上の目的・背景**：JavaScriptコードを変換・解析するためには、まずソースコードを機械的に処理可能な形式（AST）に変換する必要がある。@babel/parserは、ECMAScript標準に準拠した高精度なパース機能を提供し、最新の言語仕様やステージ段階の提案構文もサポートする。これにより、Babelエコシステム全体のコード変換基盤を支える。

**機能の利用シーン**：@babel/coreから内部的に呼び出される場合、ESLint（@babel/eslint-parser）でコード解析を行う場合、コード解析ツールやエディタ拡張でAST操作を行う場合、またはプログラマティックにコード構造を解析する場合に利用される。

**主要な処理内容**：
1. 入力ソースコードの字句解析（トークン化）
2. トークン列の構文解析（パース）
3. AST（抽象構文木）の構築
4. コメントのAST関連付け
5. 構文エラーの検出と報告（エラーリカバリモードあり）
6. TypeScript、Flow、JSX等の拡張構文サポート

**関連システム・外部連携**：@babel/core（変換パイプライン）、@babel/traverse（AST走査）、@babel/eslint-parser（ESLint統合）、各種IDE・エディタ拡張と連携する。

**権限による制御**：特になし。純粋な文字列処理のため、ファイルシステムへのアクセスは不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本パッケージは画面との直接連携なし（@babel/core経由で間接利用） |

## 機能種別

構文解析処理（パーサー）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| input | string | Yes | パース対象のJavaScriptソースコード | 空文字列も許容 |
| options | ParserOptions | No | パースオプション | オブジェクト形式 |
| options.sourceType | "script" \| "module" \| "commonjs" \| "unambiguous" | No | ソースコードの種別（デフォルト: "script"） | 指定値のみ |
| options.sourceFilename | string | No | ソースファイル名（AST出力用） | - |
| options.startIndex | number | No | 開始インデックス（デフォルト: 0） | 0以上の整数 |
| options.startLine | number | No | 開始行番号（デフォルト: 1） | 1以上の整数 |
| options.startColumn | number | No | 開始列番号（デフォルト: 0） | 0以上の整数 |
| options.plugins | Plugin[] | No | 有効化するプラグインの配列 | 有効なプラグイン名 |
| options.strictMode | boolean | No | strictモードの有無 | boolean |
| options.ranges | boolean | No | rangeプロパティの追加（デフォルト: false） | boolean |
| options.tokens | boolean | No | トークン情報の追加（デフォルト: false） | boolean |
| options.allowAwaitOutsideFunction | boolean | No | async関数外でのawait許可（デフォルト: false） | boolean |
| options.allowReturnOutsideFunction | boolean | No | 関数外でのreturn許可（デフォルト: false） | boolean |
| options.allowImportExportEverywhere | boolean | No | import/exportの位置制限解除（デフォルト: false） | boolean |
| options.allowSuperOutsideMethod | boolean | No | メソッド外でのsuper許可（デフォルト: false） | boolean |
| options.allowUndeclaredExports | boolean | No | 未宣言exportの許可（デフォルト: false） | boolean |
| options.errorRecovery | boolean | No | エラーリカバリモード（デフォルト: false） | boolean |
| options.attachComment | boolean | No | コメントのAST関連付け（デフォルト: true） | boolean |
| options.createParenthesizedExpressions | boolean | No | 括弧式ノードの生成（デフォルト: false） | boolean |
| options.createImportExpressions | boolean | No | ImportExpressionノードの生成（デフォルト: true） | boolean |
| options.annexB | boolean | No | Annex B構文サポート（デフォルト: true、falseのみ指定可） | false |

### 入力データソース

- @babel/coreからのパイプライン呼び出し
- ESLint/Prettierなどのツールからの直接呼び出し
- コード解析ツールからのプログラマティック利用

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (返却値) | ParseResult<File> | パース結果のASTオブジェクト |
| program | Program | プログラム全体のASTノード |
| comments | Comment[] | パース中に検出されたコメントの配列 |
| errors | ParseError[] | エラーリカバリモード時のエラー配列 |
| tokens | Token[] | トークン配列（options.tokens=trueの場合） |

### 出力先

- @babel/coreへの返却
- 呼び出し元への直接返却

## 処理フロー

### 処理シーケンス

```
1. parse関数の呼び出し
   └─ 入力コードとオプションを受け取る
2. オプションの正規化 (getOptions)
   └─ デフォルト値の適用とバリデーション
3. Parserインスタンスの生成
   └─ プラグインの適用とオプションフラグの設定
4. スコープの初期化
   └─ enterInitialScopes
5. 最初のトークンの取得
   └─ nextToken
6. トップレベル解析
   └─ parseTopLevel
   └─ 各種文・式の再帰的パース
7. 結果の構築
   └─ エラー、コメントの収集
   └─ ParseResult<File>の返却
```

### フローチャート

```mermaid
flowchart TD
    A[parse呼び出し] --> B[getOptions: オプション正規化]
    B --> C{sourceType == unambiguous?}
    C -->|Yes| D[moduleとしてパース試行]
    D --> E{ESM構文あり?}
    E -->|Yes| F[moduleとして返却]
    E -->|No| G{異なるAST生成?}
    G -->|Yes| H[scriptとして再パース]
    G -->|No| I[sourceType=scriptに変更]
    C -->|No| J[指定されたsourceTypeでパース]
    H --> K[結果を返却]
    I --> K
    F --> K
    J --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | sourceType判定 | unambiguous指定時、import/export文の有無でmodule/scriptを自動判定 | sourceType: "unambiguous" |
| BR-02 | strictMode自動設定 | sourceType: "module"の場合、strictModeがtrueとなる | sourceType: "module" |
| BR-03 | commonjs暗黙設定 | sourceType: "commonjs"はallowReturnOutsideFunction等を暗黙的にtrueに | sourceType: "commonjs" |
| BR-04 | プラグインマージ | 同名プラグインは最初の設定が優先される | 複数回のプラグイン指定 |
| BR-05 | エラーリカバリ | errorRecovery: true時、一部エラーはerrors配列に格納して続行 | errorRecovery: true |
| BR-06 | コメント付与 | attachComment: true時、コメントはleading/trailing/innerCommentsとして関連付け | attachComment: true |

### 計算ロジック

特になし

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

該当なし（メモリ内処理のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| SyntaxError | 構文エラー | 無効なJavaScript構文 | 行番号・列番号付きエラーメッセージ |
| UnexpectedToken | トークンエラー | 予期しないトークン | 期待されるトークンを示唆 |
| InvalidOption | オプションエラー | 無効なオプション組み合わせ | エラーメッセージで修正方法を提示 |

### リトライ仕様

- errorRecovery: true時、パース可能な範囲で処理を継続
- エラーはresult.errors配列に蓄積される

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

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

## パフォーマンス要件

- attachComment: falseでコメント処理を無効化すると最大30%の性能向上
- プラグインの組み合わせはキャッシュされ、同一設定での再パースは高速化
- 大規模ファイルでもストリーミングではなく一括処理

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

- 入力コードはそのままパースされ、実行されることはない
- 悪意のあるコードをパースしても、ASTが生成されるのみでコード実行は発生しない

## 備考

- tokTypes定数として各トークンタイプが公開され、外部ツールで利用可能
- Babel 7との互換性のため、一部オプションは非推奨ながらサポート継続

---

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

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

### 推奨読解順序

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

まず、入出力のデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | options.ts | `packages/babel-parser/src/options.ts` | Options型定義（8-148行目）とOptionFlagsの定義（150-165行目） |
| 1-2 | index.ts | `packages/babel-parser/src/index.ts` | ParseResult型（32-36行目）とParserOptions型（30行目） |

**読解のコツ**: OptionFlagsはビットフラグとして実装されており、複数オプションを効率的に管理している。

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

処理の起点となるファイル・関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-parser/src/index.ts` | parse関数（41-86行目）とparseExpression関数（88-97行目） |

**主要処理フロー**:
1. **45-82行目**: sourceType: "unambiguous"の処理分岐
2. **51-56行目**: moduleとしてパースを試行
3. **65-67行目**: scriptとして再パースを試行
4. **84行目**: 通常のパース実行

#### Step 3: Parserクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | parser/index.ts | `packages/babel-parser/src/parser/index.ts` | Parserクラスのコンストラクタ（10-69行目）とparse()メソッド（76-86行目） |

**主要処理フロー**:
- **15行目**: getOptionsでオプション正規化
- **19行目**: initializeScopesでスコープ初期化
- **24-68行目**: オプションフラグのビット設定
- **76-86行目**: parse()メソッドでASTを生成

#### Step 4: オプション処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | options.ts | `packages/babel-parser/src/options.ts` | getOptions関数（240-288行目）とcreateDefaultOptions関数（171-236行目） |

**主要処理フロー**:
- **171-236行目**: デフォルト値の定義
- **249-251行目**: annexBオプションのバリデーション
- **253-255行目**: オプションのマージ
- **269-285行目**: sourceType: "commonjs"の特殊処理

#### Step 5: プラグインシステムを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | plugin-utils.ts | `packages/babel-parser/src/plugin-utils.ts` | プラグインの検証とmixin処理 |
| 5-2 | index.ts | `packages/babel-parser/src/index.ts` | getParserClass関数（141-161行目） |

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

```
parse (index.ts)
    │
    ├─ getParser
    │      ├─ validatePlugins (plugin-utils.ts)
    │      └─ getParserClass
    │             └─ mixinPlugins (TypeScript, Flow, JSX等)
    │
    └─ Parser.parse (parser/index.ts)
           ├─ enterInitialScopes
           ├─ nextToken (tokenizer/index.ts)
           └─ parseTopLevel (parser/statement.ts)
                  ├─ parseStatementContent
                  │      ├─ parseImport
                  │      ├─ parseExport
                  │      ├─ parseFunction
                  │      ├─ parseClass
                  │      └─ ...
                  └─ finishNode
```

### データフロー図

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

ソースコード ───────▶ Tokenizer ───────▶ トークン列
(string)               (nextToken)

     オプション ───────▶ getOptions ───────▶ NormalizedOptions
     (ParserOptions)

          トークン列 ───────▶ Parser ───────▶ ParseResult<File>
                             (parseTopLevel)   (AST + comments + errors)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-parser/src/index.ts` | ソース | 公開APIのエントリーポイント |
| options.ts | `packages/babel-parser/src/options.ts` | ソース | オプション型定義と正規化 |
| parser/index.ts | `packages/babel-parser/src/parser/index.ts` | ソース | Parserクラスの定義 |
| parser/statement.ts | `packages/babel-parser/src/parser/statement.ts` | ソース | 文のパース処理 |
| parser/expression.ts | `packages/babel-parser/src/parser/expression.ts` | ソース | 式のパース処理 |
| parser/lval.ts | `packages/babel-parser/src/parser/lval.ts` | ソース | 左辺値のパース処理 |
| tokenizer/index.ts | `packages/babel-parser/src/tokenizer/index.ts` | ソース | 字句解析処理 |
| tokenizer/types.ts | `packages/babel-parser/src/tokenizer/types.ts` | ソース | トークンタイプ定義 |
| plugin-utils.ts | `packages/babel-parser/src/plugin-utils.ts` | ソース | プラグインユーティリティ |
| parse-error.ts | `packages/babel-parser/src/parse-error.ts` | ソース | エラー処理 |
| util/scope.ts | `packages/babel-parser/src/util/scope.ts` | ソース | スコープ管理 |
