# 機能設計書 18-シンボル解決

## 概要

本ドキュメントは、F#コンパイラサービスのシンボル解決機能の設計を記述する。この機能は、ソースコード内の識別子をF#シンボル（FSharpSymbol）オブジェクトに解決し、シンボルの定義、使用箇所、型情報を提供する。

### 本機能の処理概要

シンボル解決機能は、ソースコード内の識別子（変数、関数、型、メンバーなど）を解析し、それらを統一的なFSharpSymbolオブジェクトとして表現する。

**業務上の目的・背景**：「定義へ移動」「参照の検索」「名前の変更」などのIDE機能を実現するには、ソースコード内の識別子とその定義・使用箇所の関係を正確に把握する必要がある。

**機能の利用シーン**：
- 「定義へ移動」（Go to Definition）
- 「参照の検索」（Find All References）
- 「名前の変更」（Rename）
- シンボル情報の表示（ホバー表示）
- コード解析ツール

**主要な処理内容**：
1. 位置からシンボルの特定
2. シンボルオブジェクトの生成
3. シンボルの使用箇所収集
4. アクセシビリティ判定
5. シンボル情報のフォーマット

**関連システム・外部連携**：
- FSharpChecker（型チェック結果の提供）
- NameResolution（名前解決）
- Visual Studio / VS Code（機能実行）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | テキストエディタ | 主機能 | 定義へ移動、参照検索 |

## 機能種別

シンボル解決 / 名前解決 / コードナビゲーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| checkResults | FSharpCheckFileResults | Yes | 型チェック結果 | - |
| line | int | Yes | 行番号 | 正の整数 |
| column | int | Yes | 列番号 | 正の整数 |
| lineText | string | Yes | 行のテキスト | - |

### 入力データソース

- 型チェック結果
- ソースコードテキスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FSharpSymbol | FSharpSymbol | シンボルオブジェクト |
| FSharpSymbolUse[] | FSharpSymbolUse[] | シンボルの使用箇所 |
| range | range | シンボルの範囲 |

### 出力先

- API呼び出し元への返却

## 処理フロー

### 処理シーケンス

```
1. 位置情報の解析
   └─ 行・列から対象識別子を特定
2. 名前解決
   └─ 識別子をItemに解決
3. シンボル生成
   └─ ItemからFSharpSymbolを生成
4. 使用箇所収集
   └─ プロジェクト内のシンボル使用を検索
5. 結果返却
   └─ FSharpSymbolUseとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[位置情報] --> B[識別子特定]
    B --> C[名前解決]
    C --> D{解決成功?}
    D -->|Yes| E[FSharpSymbol生成]
    D -->|No| F[None返却]
    E --> G[使用箇所収集]
    G --> H[FSharpSymbolUse生成]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | アクセシビリティ確認 | プライベートシンボルへのアクセス権を確認 | シンボル解決時 |
| BR-02 | クロスプロジェクト | 異なるプロジェクト間でもシンボル解決を実行 | 参照検索時 |
| BR-03 | 効果的等価性 | IsEffectivelySameAsで同一シンボルを判定 | 参照検索時 |

### 計算ロジック

シンボル同一性判定（ItemsAreEffectivelyEqual）:
- 型参照が同じ
- 値参照が同じ
- メソッド参照が同じ

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | シンボル未解決 | 不明な識別子 | None返却 |
| - | 未解決アセンブリ | 外部アセンブリが欠落 | エラーメッセージ表示 |

### リトライ仕様

特になし。

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

該当なし

## パフォーマンス要件

- シンボル解決: 数ms
- 全参照検索: プロジェクトサイズに依存

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

特になし

## 備考

- FSharpMemberOrFunctionOrValue等の派生型あり
- シグネチャファイルと実装ファイルの対応をサポート

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Symbols.fs | `src/Compiler/Symbols/Symbols.fs` | FSharpAccessibility型（31-58行目） |
| 1-2 | Symbols.fs | `src/Compiler/Symbols/Symbols.fs` | SymbolEnv型（60-75行目） |
| 1-3 | Symbols.fs | `src/Compiler/Symbols/Symbols.fs` | FSharpSymbol型（223-354行目） |

**主要フィールド/メソッド**:
- **FSharpAccessibility**: IsPublic, IsPrivate, IsInternal, IsProtected
- **SymbolEnv**: g, amap, thisCcu, infoReader
- **FSharpSymbol**: Assembly, FullName, DeclarationLocation, IsAccessible

#### Step 2: シンボル生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Symbols.fs | `src/Compiler/Symbols/Symbols.fs` | FSharpSymbol.Create（268-348行目） |

**主要処理フロー**:
- **274-277行目**: Item.Value -> FSharpMemberOrFunctionOrValue
- **278行目**: Item.UnionCase -> FSharpUnionCase
- **279行目**: Item.ExnCase -> FSharpEntity
- **280-281行目**: Item.RecdField -> FSharpField

#### Step 3: 等価性判定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Symbols.fs | `src/Compiler/Symbols/Symbols.fs` | IsEffectivelySameAs（241-243行目） |
| 3-2 | Symbols.fs | `src/Compiler/Symbols/Symbols.fs` | ItemsAreEffectivelyEqual参照 |

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

```
GetSymbolUseAtLocation (API)
    │
    ├─ 位置からItem取得
    │      └─ TcResolutions.CapturedNameResolutions
    │
    ├─ FSharpSymbol.Create
    │      ├─ Item.Value -> FSharpMemberOrFunctionOrValue
    │      ├─ Item.UnionCase -> FSharpUnionCase
    │      ├─ Item.ExnCase -> FSharpEntity
    │      ├─ Item.RecdField -> FSharpField
    │      ├─ Item.MethodGroup -> FSharpMemberOrFunctionOrValue
    │      └─ 他のItem種別
    │
    └─ FSharpSymbolUse生成
           ├─ Symbol
           ├─ Range
           └─ IsFromDefinition
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Symbols.fs | `src/Compiler/Symbols/Symbols.fs` | ソース | FSharpSymbol階層のコア実装 |
| SymbolHelpers.fs | `src/Compiler/Symbols/SymbolHelpers.fs` | ソース | シンボル操作ヘルパー |
| NameResolution.fs | `src/Compiler/Checking/NameResolution.fs` | ソース | 名前解決 |
| FSharpCheckerResults.fs | `src/Compiler/Service/FSharpCheckerResults.fs` | ソース | シンボル使用の検索 |
