# 機能設計書 9-式評価（BasicEvaluatedExpression）

## 概要

本ドキュメントは、コンパイル時に式を評価し、定数畳み込み・条件分岐の静的解析を行うBasicEvaluatedExpression機能の設計を記述する。

### 本機能の処理概要

BasicEvaluatedExpressionは、JavascriptParserの式評価結果を表すクラスである。コンパイル時にソースコード中の式（定数、変数参照、テンプレートリテラル、条件式等）を静的に評価し、その結果を型付きで保持する。DefinePlugin、Tree Shaking、Dead Code Eliminationなどの最適化機能がこの評価結果を利用する。

**業務上の目的・背景**：バンドルサイズの削減やデッドコード除去を実現するためには、コンパイル時に式の値を静的に判定する必要がある。例えば、`process.env.NODE_ENV === 'production'`のような式をコンパイル時に評価し、不要なコードブランチを除去できる。BasicEvaluatedExpressionは、この静的評価の結果を構造化して保持する。

**機能の利用シーン**：JavascriptParserのevaluateフック群（evaluateTypeof、evaluate、evaluateIdentifier等）から返される式評価結果として使用される。DefinePluginによるコンパイル時定数の置換、条件分岐のデッドコード除去などで活用される。

**主要な処理内容**：
1. 14種の式タイプ（Unknown/Undefined/Null/String/Number/Boolean/RegExp/Conditional/Array/ConstArray/Identifier/Wrapped/TemplateString/BigInt）の管理
2. 式のtruthy/falsy/nullish判定
3. sideEffectsフラグによる副作用追跡
4. テンプレートリテラルの静的評価（quasis + parts）
5. 条件式の静的評価（options）
6. Wrapped式の評価（prefix + postfix + innerExpressions）
7. Identifier式の評価（rootInfo + getMembers）

**関連システム・外部連携**：JavascriptParser（式評価の呼び出し元）、DefinePlugin（コンパイル時定数定義）、各種最適化プラグインと連携する。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 式評価は画面に直接関連しない基盤機能 |

## 機能種別

静的解析 / 式評価 / データ構造

## 入力仕様

### 入力パラメータ

BasicEvaluatedExpressionはコンストラクタ引数を取らない。各プロパティはセッターメソッドで設定される。

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | number | Yes | 式タイプ（0-13の内部定数） | 有効なタイプであること |
| range | Range | No | ソースコード内の位置範囲 | - |
| expression | Node | No | 元のASTノード | - |

### 入力データソース

- JavascriptParserのevaluateフックから生成される

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| type | number | 式の評価タイプ |
| string | string \| undefined | 文字列値（TypeString時） |
| number | number \| undefined | 数値（TypeNumber時） |
| bool | boolean \| undefined | 真偽値（TypeBoolean時） |
| bigint | bigint \| undefined | BigInt値（TypeBigInt時） |
| regExp | RegExp \| undefined | 正規表現（TypeRegExp時） |
| options | BasicEvaluatedExpression[] \| undefined | 条件式の選択肢（TypeConditional時） |
| truthy | boolean | 真値と確定しているか |
| falsy | boolean | 偽値と確定しているか |
| nullish | boolean \| undefined | null/undefinedであるか |
| sideEffects | boolean | 副作用を持つか |

### 出力先

- JavascriptParserのevaluateフック呼び出し元に返却される
- 各種最適化プラグインが利用する

## 処理フロー

### 処理シーケンス

```
1. new BasicEvaluatedExpression() でインスタンス生成
   └─ すべてのプロパティがデフォルト値に初期化
2. セッターメソッドで値を設定
   ├─ setString("value") → type = TypeString, string = "value"
   ├─ setNumber(42) → type = TypeNumber, number = 42
   ├─ setBoolean(true) → type = TypeBoolean, bool = true
   └─ setIdentifier("name", rootInfo, ...) → type = TypeIdentifier
3. 判定メソッドで状態を問い合わせ
   ├─ isString() → type === TypeString
   ├─ isTruthy() → truthy === true
   ├─ asBool() → 型に基づく真偽値判定
   └─ isPrimitiveType() → プリミティブ型かオブジェクト型か
4. 必要に応じてrangeとexpressionを設定
   └─ setRange([start, end]).setExpression(node)
```

### フローチャート

```mermaid
flowchart TD
    A[evaluateフック発火] --> B[BasicEvaluatedExpression生成]
    B --> C{式のタイプ判定}
    C -->|リテラル| D[setString/setNumber/setBoolean]
    C -->|変数参照| E[setIdentifier]
    C -->|テンプレート| F[setTemplateString]
    C -->|条件式| G[setOptions]
    C -->|不明| H[TypeUnknown維持]
    D --> I[range/expression設定]
    E --> I
    F --> I
    G --> I
    H --> I
    I --> J[呼び出し元に返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | TypeUnknownデフォルト | 生成時のデフォルトタイプはTypeUnknown（0） | コンストラクタ時 |
| BR-02 | sideEffectsデフォルト | sideEffectsのデフォルト値はtrue（副作用あり） | コンストラクタ時 |
| BR-03 | isPrimitiveType判定 | Undefined/Null/String/Number/Boolean/BigIntはプリミティブ、RegExp/Array/ConstArrayはオブジェクト、その他はundefined（不明） | isPrimitiveType()呼び出し時 |
| BR-04 | asBool判定 | 各タイプに応じた真偽値変換ルール（空文字列→false、0→false、null→false等） | asBool()呼び出し時 |

### 計算ロジック

asBool()の計算ロジック:
- TypeBoolean: boolプロパティの値
- TypeNull/TypeUndefined: false
- TypeString: string.length > 0
- TypeNumber: number !== 0
- TypeBigInt: bigint !== 0n
- TypeRegExp: true
- TypeArray/TypeConstArray: true
- TypeWrapped/TypeTemplateString: prefix/postfix/quasisに基づく判定

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

該当なし。

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

該当なし。

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

特にエラーは発生しない。型の不整合はTypeUnknownとして扱われる。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

- BasicEvaluatedExpressionは軽量なデータオブジェクトとして設計されている
- 型判定はnumber比較で高速

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

特になし。

## 備考

- 14種のタイプ定数（TypeUnknown=0〜TypeBigInt=13）は内部定数として定義
- メソッドチェーンをサポート（各セッターがthisを返す）

---

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

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

### 推奨読解順序

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

BasicEvaluatedExpressionのプロパティとタイプ定数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | BasicEvaluatedExpression.js | `lib/javascript/BasicEvaluatedExpression.js` | タイプ定数定義（15-28行目）で14種のタイプを把握する |
| 1-2 | BasicEvaluatedExpression.js | `lib/javascript/BasicEvaluatedExpression.js` | コンストラクタ（34-85行目）で全プロパティのデフォルト値を理解する |

**読解のコツ**: タイプ定数はクラス外部のモジュールレベル変数として定義されている（エクスポートされていない）。各タイプに対応するis*()メソッドとset*()メソッドが対になっている。

#### Step 2: 判定メソッドを理解する

is*()メソッドとisPrimitiveType()の動作を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | BasicEvaluatedExpression.js | `lib/javascript/BasicEvaluatedExpression.js` | is*()メソッド群（87-141行目）で各タイプ判定を理解する |
| 2-2 | BasicEvaluatedExpression.js | `lib/javascript/BasicEvaluatedExpression.js` | isPrimitiveType()メソッド（147行目以降）でプリミティブ/オブジェクト判定を理解する |

**主要処理フロー**:
- **87-89行目**: isUnknown() → type === TypeUnknown (0)
- **91-93行目**: isNull() → type === TypeNull (2)
- **99-101行目**: isString() → type === TypeString (3)
- **103-105行目**: isNumber() → type === TypeNumber (4)

#### Step 3: セッターメソッドを理解する

set*()メソッドの動作を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BasicEvaluatedExpression.js | `lib/javascript/BasicEvaluatedExpression.js` | set*()メソッド群でタイプ設定と値設定の連動を理解する |

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

```
JavascriptParser.evaluateExpression(expression)
    │
    ├─ hooks.evaluate.for(expression.type).call(expression)
    │      └─ 各ParserPlugin / ConstPlugin
    │             └─ new BasicEvaluatedExpression()
    │                    ├─ .setString("value")
    │                    ├─ .setNumber(42)
    │                    ├─ .setBoolean(true)
    │                    ├─ .setIdentifier(name, rootInfo, getMembers, ...)
    │                    ├─ .setRange([start, end])
    │                    └─ .setExpression(node)
    │
    ├─ hooks.evaluateTypeof.for(name).call(expression)
    │      └─ new BasicEvaluatedExpression().setString("string")
    │
    └─ hooks.evaluateIdentifier.for(name).call(expression)
           └─ new BasicEvaluatedExpression().setIdentifier(...)
```

### データフロー図

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

ASTノード ──────────▶ evaluateフック発火
                            │
                     ParserPlugin
                     ├─ リテラル判定 ────────▶ setString/Number/Boolean
                     ├─ 変数参照判定 ────────▶ setIdentifier
                     ├─ テンプレート判定 ────▶ setTemplateString
                     └─ 条件式判定 ──────────▶ setOptions

                     BasicEvaluatedExpression ──▶ 最適化プラグイン
                                                    ├─ DefinePlugin
                                                    ├─ Tree Shaking
                                                    └─ Dead Code Elimination
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| BasicEvaluatedExpression.js | `lib/javascript/BasicEvaluatedExpression.js` | ソース | 式評価結果クラス本体 |
| JavascriptParser.js | `lib/javascript/JavascriptParser.js` | ソース | 式評価の呼び出し元パーサー |
| DefinePlugin.js | `lib/DefinePlugin.js` | ソース | コンパイル時定数定義（evaluateフック利用） |
| ConstPlugin.js | `lib/ConstPlugin.js` | ソース | 定数式の評価 |
