# 機能設計書 16-透過コンパイラ

## 概要

本ドキュメントは、F#コンパイラサービスの透過コンパイラ（TransparentCompiler）の機能設計を記述する。TransparentCompilerは、BackgroundCompilerの代替実装として、より細粒度なキャッシュとインクリメンタル処理を提供する。

### 本機能の処理概要

TransparentCompilerは、プロジェクトスナップショットベースのキャッシュ機構を採用し、ファイル単位での依存関係グラフに基づく効率的な型チェックを実現する。

**業務上の目的・背景**：大規模プロジェクトでのIDE体験を向上させるため、より細かい粒度でのキャッシュと並列処理を実現する。BackgroundCompilerの制限を克服し、メモリ効率とパフォーマンスを改善する。

**機能の利用シーン**：
- 大規模F#プロジェクトの編集
- 高頻度なコード変更に対する高速応答
- メモリ効率が重要な環境

**主要な処理内容**：
1. プロジェクトスナップショットの管理
2. 依存関係グラフに基づく型チェック順序決定
3. ファイル単位のキャッシュ管理（AsyncMemoize）
4. ブートストラップ情報の生成
5. スクリプトクロージャの計算

**関連システム・外部連携**：
- FSharpChecker（API層）
- BackgroundCompiler（レガシー処理のフォールバック）
- GraphChecking（依存関係グラフ）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | テキストエディタ | 主機能 | インクリメンタル型チェック |
| 4 | エラー一覧 | 出力先 | 診断情報の表示 |

## 機能種別

透過コンパイル / 依存関係グラフ / 細粒度キャッシュ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| projectSnapshot | FSharpProjectSnapshot | Yes | プロジェクトスナップショット | - |
| fileName | string | Yes | ソースファイル名 | - |
| sourceText | ISourceTextNew | Yes | ソースコード | - |

### 入力データソース

- プロジェクトスナップショット
- ファイルスナップショット

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FSharpParseFileResults | FSharpParseFileResults | パース結果 |
| FSharpCheckFileResults | FSharpCheckFileResults | 型チェック結果 |
| TcInfo | TcInfo | 型チェック情報 |
| BootstrapInfo | BootstrapInfo | ブートストラップ情報 |

### 出力先

- CompilerCaches（各種キャッシュ）

## 処理フロー

### 処理シーケンス

```
1. スナップショット受信
   └─ FSharpProjectSnapshotからファイル情報を取得
2. ブートストラップ情報生成
   └─ TcConfig, TcImports, TcGlobalsの初期化
3. 依存関係グラフ構築
   └─ ファイル間の依存関係を解析
4. 型チェック順序決定
   └─ グラフに基づく処理順序を決定
5. ファイル単位の型チェック
   └─ 各ファイルを依存順に型チェック
6. 結果のキャッシュ
   └─ AsyncMemoizeで結果を保存
```

### フローチャート

```mermaid
flowchart TD
    A[プロジェクトスナップショット] --> B[ブートストラップ情報生成]
    B --> C[依存関係グラフ構築]
    C --> D[型チェック順序決定]
    D --> E{並列処理可能?}
    E -->|Yes| F[並列型チェック]
    E -->|No| G[順次型チェック]
    F --> H[結果キャッシュ]
    G --> H
    H --> I[TcInfo/PartialResult]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | スナップショットベース | プロジェクト状態をスナップショットとして管理 | 常時 |
| BR-02 | MD5ハッシュ | ファイルバージョンはMD5ハッシュで管理 | キャッシュキー生成時 |
| BR-03 | 依存結合 | 依存ファイルの結果を結合して入力状態を生成 | combineResults |
| BR-04 | 最大依存選択 | 最大の推移依存を持つノードから状態を再利用 | 型チェック時 |

### 計算ロジック

依存関係結合アルゴリズム（combineResults）:
1. 最大推移依存を持つノードを選択
2. 未包含の依存結果をフォールド
3. 依存順序を保持してマージ

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ブートストラップ失敗 | 参照解決エラー | エラー診断を返却 |
| - | 依存解決失敗 | 循環依存等 | エラーを報告してフォールバック |

### リトライ仕様

キャッシュ無効化時は自動再計算。

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

該当なし

## パフォーマンス要件

- キャッシュサイズは設定可能（CacheSizes）
- 強参照/弱参照の比率を調整可能
- 並列型チェックをサポート

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

特になし

## 備考

- useChangeNotificationsオプションで変更通知を使用
- backgroundCompilerへのフォールバック機能あり

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TransparentCompiler.fs | `src/Compiler/Service/TransparentCompiler.fs` | TcInfo型（50-74行目） |
| 1-2 | TransparentCompiler.fs | `src/Compiler/Service/TransparentCompiler.fs` | BootstrapInfo型（96-118行目） |
| 1-3 | TransparentCompiler.fs | `src/Compiler/Service/TransparentCompiler.fs` | CacheSizes型（260-337行目） |
| 1-4 | TransparentCompiler.fs | `src/Compiler/Service/TransparentCompiler.fs` | CompilerCaches型（339-408行目） |

**主要フィールド**:
- **TcInfo**: tcState, tcEnvAtEndOfFile, moduleNamesDict, topAttribs等
- **BootstrapInfo**: TcConfig, TcImports, TcGlobals, InitialTcInfo等
- **CompilerCaches**: 各種AsyncMemoizeキャッシュ

#### Step 2: 依存関係グラフ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TransparentCompiler.fs | `src/Compiler/Service/TransparentCompiler.fs` | combineResults（169-210行目） |
| 2-2 | TransparentCompiler.fs | `src/Compiler/Service/TransparentCompiler.fs` | processTypeCheckingGraph（216-258行目） |

**主要処理フロー**:
- **169-210行目**: 依存結果の結合、最大依存ノードからの状態再利用
- **216-258行目**: グラフに基づく型チェック処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TransparentCompiler.fs | `src/Compiler/Service/TransparentCompiler.fs` | TransparentCompiler型（410行目以降） |
| 3-2 | TransparentCompiler.fs | `src/Compiler/Service/TransparentCompiler.fs` | ComputeScriptClosure（554-598行目） |

**主要処理フロー**:
- **410-476行目**: コンストラクタ、キャッシュ/イベント初期化
- **478-520行目**: ComputeScriptClosureInner
- **554-598行目**: ComputeScriptClosure（キャッシュ付き）

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

```
TransparentCompiler
    │
    ├─ CompilerCaches (キャッシュ管理)
    │      ├─ ParseFile
    │      ├─ ParseAndCheckFileInProject
    │      ├─ BootstrapInfo
    │      ├─ TcIntermediate
    │      └─ SemanticClassification
    │
    ├─ ComputeScriptClosure
    │      └─ LoadClosure.ComputeClosureOfScriptText
    │
    ├─ 依存関係グラフ処理
    │      ├─ combineResults (依存結合)
    │      └─ processTypeCheckingGraph
    │
    └─ backgroundCompiler (フォールバック)
           └─ IBackgroundCompiler実装
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TransparentCompiler.fs | `src/Compiler/Service/TransparentCompiler.fs` | ソース | 透過コンパイラのコア実装 |
| BackgroundCompiler.fs | `src/Compiler/Service/BackgroundCompiler.fs` | ソース | フォールバック実装 |
| GraphChecking.fs | `src/Compiler/Service/GraphChecking.fs` | ソース | 依存関係グラフ |
| ProjectSnapshot.fs | `src/Compiler/Service/ProjectSnapshot.fs` | ソース | スナップショット型 |
| AsyncMemoize.fs | `src/Compiler/Utilities/AsyncMemoize.fs` | ソース | 非同期メモ化 |
