# 機能設計書 23-F# Language Server

## 概要

本ドキュメントは、F# Language Serverの設計を記述する。この機能は、LSP（Language Server Protocol）準拠のF#言語サーバーを提供し、各種エディタ・IDEでF#の開発支援機能を利用可能にする。

### 本機能の処理概要

F# Language Serverは、JSON-RPCベースのLSPを実装し、エディタ（LSPクライアント）からの各種リクエスト（補完、診断、定義ジャンプ等）を処理してF#コンパイラサービスの機能を提供する。

**業務上の目的・背景**：Visual Studio以外のエディタ（VS Code、Neovim、Emacs等）でもF#の高度な開発支援機能を利用可能にする。LSPは言語サーバーの標準プロトコルであり、一度実装すればLSP対応のすべてのエディタで利用できる。これにより、F#開発者のエディタ選択の自由度が向上し、開発体験が統一される。

**機能の利用シーン**：VS Codeでの F# 開発、Neovim/VimでのF#コード編集、その他LSP対応エディタでのF#プロジェクト作業で利用される。

**主要な処理内容**：
1. LSPクライアント（エディタ）からの接続を受け付け、JsonRpcで通信を確立
2. 初期化リクエスト（initialize）を処理し、サーバー機能（capabilities）を返却
3. ドキュメント状態の管理（didOpen、didChange、didClose）
4. 言語機能リクエストの処理（診断、セマンティックトークン等）
5. FSharpWorkspaceを通じてF#コンパイラサービスと連携

**関連システム・外部連携**：FSharpWorkspace経由でFSharpCheckerと連携、LSPクライアント（各種エディタ）とJSON-RPCで通信。

**権限による制御**：特になし。ローカル環境で動作。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | VS Code F#エディタ | 主画面 | LSPリクエストの送信元 |
| - | その他LSP対応エディタ | 主画面 | LSPリクエストの送信元 |

## 機能種別

サーバー / プロトコル処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| jsonRpc | JsonRpc | Yes | JSON-RPC通信ハンドル | null不可 |
| logger | ILspLogger | Yes | ログ出力インターフェース | null不可 |
| initialWorkspace | FSharpWorkspace | No | 初期ワークスペース | デフォルトは新規作成 |
| config | FSharpLanguageServerConfig | No | サーバー設定 | デフォルト設定を使用 |

### 入力データソース

LSPクライアントからのJSON-RPCメッセージ（stdin/stdoutまたはソケット経由）。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| InitializeResult | InitializeResult | サーバー機能（capabilities）情報 |
| 診断結果 | DocumentDiagnosticReport | ドキュメントの診断情報 |
| セマンティックトークン | SemanticTokens | 構文ハイライト用トークン |

### 出力先

LSPクライアント（エディタ）へJSON-RPCレスポンスとして返却。

## 処理フロー

### 処理シーケンス

```
1. FSharpLanguageServer初期化
   └─ JsonRpcハンドルの受け取りとサービス登録
2. ConstructLspServicesでDIコンテナを構築
   └─ 各ハンドラとサービスの登録
3. initialize リクエストの処理
   └─ サーバー機能を返却
4. initialized 通知の処理
   └─ 初期化完了
5. 以降、各種リクエスト/通知を処理
   └─ DocumentStateHandler: ドキュメント状態管理
   └─ LanguageFeaturesHandler: 言語機能提供
```

### フローチャート

```mermaid
flowchart TD
    A[開始: サーバー起動] --> B[FSharpLanguageServer初期化]
    B --> C[ConstructLspServices]
    C --> D[サービス登録完了]
    D --> E{LSPリクエスト待機}
    E -->|initialize| F[InitializeHandler]
    E -->|initialized| G[InitializedHandler]
    E -->|textDocument/didOpen| H[DocumentStateHandler]
    E -->|textDocument/diagnostic| I[LanguageFeaturesHandler]
    E -->|shutdown| J[シャットダウン処理]
    F --> E
    G --> E
    H --> E
    I --> E
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | LSP準拠 | LSP仕様に準拠したリクエスト/レスポンス形式 | 常時 |
| BR-02 | シングルスレッドキュー | リクエストはキューで順序制御される | 常時 |
| BR-03 | ドキュメント状態管理 | 開いているドキュメントの状態を管理 | ドキュメント操作時 |
| BR-04 | キャンセル対応 | 長時間処理はキャンセル可能 | 非同期処理時 |

### 計算ロジック

特になし。プロトコル処理がメイン。

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

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

該当なし。本機能はインメモリでの処理のみを行い、データベース操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| -32700 | ParseError | 不正なJSON | エラーレスポンスを返却 |
| -32600 | InvalidRequest | 不正なリクエスト形式 | エラーレスポンスを返却 |
| -32601 | MethodNotFound | 未対応のメソッド | エラーレスポンスを返却 |
| -32602 | InvalidParams | 不正なパラメータ | エラーレスポンスを返却 |
| -32603 | InternalError | 内部エラー | エラーレスポンスを返却 |

### リトライ仕様

クライアント側でリトライを行う。サーバー側では状態を維持して待機。

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

該当なし。ステートレスなリクエスト/レスポンス処理。

## パフォーマンス要件

- 初期化は数秒以内に完了
- 補完リクエストは100ミリ秒以内に応答
- 診断は数秒以内に結果を返却（ファイルサイズに依存）

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

- ローカル環境での実行を前提
- ファイルシステムアクセスはワークスペース内に限定
- ネットワーク通信はlocalhost（stdio通信が一般的）

## 備考

- Microsoft.CommonLanguageServerProtocol.Frameworkを使用
- Nerdbank.Streamsを使用したストリーム通信
- Newtonsoft.Jsonを使用したシリアライズ（将来的にSystem.Text.Jsonへ移行予定）

---

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

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

### 推奨読解順序

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

まず、Language Serverの構成要素を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | FSharpLanguageServer.fs | `src/FSharp.Compiler.LanguageServer/FSharpLanguageServer.fs` | FSharpLanguageServerクラス（32-77行目）の構造 |
| 1-2 | FSharpLanguageServerConfig.fs | `src/FSharp.Compiler.LanguageServer/FSharpLanguageServerConfig.fs` | サーバー設定の定義 |

**読解のコツ**: NewtonsoftLanguageServerを継承していることに注目。LSPフレームワークの基盤を利用している。

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

サーバーの起動とDI設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | FSharpLanguageServer.fs | `src/FSharp.Compiler.LanguageServer/FSharpLanguageServer.fs` | コンストラクタ（32-49行目）とInitialize呼び出し |
| 2-2 | FSharpLanguageServer.fs | `src/FSharp.Compiler.LanguageServer/FSharpLanguageServer.fs` | ConstructLspServices（53-77行目）でDIコンテナを構築 |

**主要処理フロー**:
1. **44-45行目**: 設定とワークスペースのデフォルト値設定
2. **48-49行目**: base.Initialize()でLSPキューを起動
3. **54-69行目**: ServiceCollectionに各種ハンドラとサービスを登録

#### Step 3: ハンドラの実装を理解する

各LSPリクエストを処理するハンドラを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DocumentStateHandler.fs | `src/FSharp.Compiler.LanguageServer/Handlers/DocumentStateHandler.fs` | ドキュメント状態管理（12-47行目） |
| 3-2 | LanguageFeaturesHandler.fs | `src/FSharp.Compiler.LanguageServer/Handlers/LanguageFeaturesHandler.fs` | 言語機能ハンドラ（15-59行目） |

**主要処理フロー**:
- **DocumentStateHandler 16-25行目**: didOpenの処理
- **DocumentStateHandler 27-36行目**: didChangeの処理
- **DocumentStateHandler 38-47行目**: didCloseの処理
- **LanguageFeaturesHandler 24-50行目**: 診断リクエストの処理
- **LanguageFeaturesHandler 52-59行目**: セマンティックトークンの処理

#### Step 4: 共通コンポーネントを理解する

リクエストコンテキストとケーパビリティ管理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | FSharpRequestContext.fs | `src/FSharp.Compiler.LanguageServer/Common/FSharpRequestContext.fs` | リクエストコンテキストの定義 |
| 4-2 | CapabilitiesManager.fs | `src/FSharp.Compiler.LanguageServer/Common/CapabilitiesManager.fs` | サーバー機能の管理 |

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

```
FSharpLanguageServer
    │
    ├─ ConstructLspServices (DI設定)
    │      ├─ FSharpWorkspace
    │      ├─ ContextHolder
    │      ├─ FSharpLanguageServerConfig
    │      ├─ InitializeHandler
    │      ├─ InitializedHandler
    │      ├─ DocumentStateHandler
    │      ├─ LanguageFeaturesHandler
    │      ├─ ILspLogger
    │      ├─ FShapRequestContextFactory
    │      ├─ CapabilitiesManager
    │      └─ LspServiceLifeCycleManager
    │
    ├─ DocumentStateHandler
    │      ├─ HandleRequestAsync (didOpen)
    │      │      └─ contextHolder.UpdateWorkspace
    │      ├─ HandleRequestAsync (didChange)
    │      │      └─ contextHolder.UpdateWorkspace
    │      └─ HandleNotificationAsync (didClose)
    │             └─ contextHolder.UpdateWorkspace
    │
    └─ LanguageFeaturesHandler
           ├─ HandleRequestAsync (diagnostic)
           │      └─ context.Workspace.Query.GetDiagnosticsForFile
           └─ HandleRequestAsync (semanticTokens)
                  └─ context.GetSemanticTokensForFile
```

### データフロー図

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

LSPクライアント ───▶ JsonRpc ───▶ FSharpLanguageServer ───▶ JsonRpc ───▶ LSPクライアント
                        │                │
                        │                ├─ DocumentStateHandler
                        │                │      └─ FSharpWorkspace更新
                        │                │
                        │                └─ LanguageFeaturesHandler
                        │                       └─ FSharpWorkspace問い合わせ
                        │
                        └─ stdin/stdout または ソケット通信
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| FSharpLanguageServer.fs | `src/FSharp.Compiler.LanguageServer/FSharpLanguageServer.fs` | ソース | メインサーバークラス |
| DocumentStateHandler.fs | `src/FSharp.Compiler.LanguageServer/Handlers/DocumentStateHandler.fs` | ソース | ドキュメント状態管理 |
| LanguageFeaturesHandler.fs | `src/FSharp.Compiler.LanguageServer/Handlers/LanguageFeaturesHandler.fs` | ソース | 言語機能ハンドラ |
| FSharpRequestContext.fs | `src/FSharp.Compiler.LanguageServer/Common/FSharpRequestContext.fs` | ソース | リクエストコンテキスト |
| CapabilitiesManager.fs | `src/FSharp.Compiler.LanguageServer/Common/CapabilitiesManager.fs` | ソース | 機能管理 |
| LifecycleManager.fs | `src/FSharp.Compiler.LanguageServer/Common/LifecycleManager.fs` | ソース | ライフサイクル管理 |
| Executable.fs | `src/FSharp.Compiler.LanguageServer/Executable.fs` | ソース | 実行可能ファイルのエントリーポイント |
| Utils.fs | `src/FSharp.Compiler.LanguageServer/Utils.fs` | ソース | ユーティリティ関数 |
