# 機能設計書 72-LSPプロトコル型定義 (serve-d:protocol)

## 概要

本ドキュメントは、serve-dのサブパッケージ `serve-d:protocol` の設計を記述する。LSP (Language Server Protocol) v3.16仕様に基づくプロトコル型定義、JSON操作、URI処理を提供する基盤サブパッケージである。

### 本機能の処理概要

**業務上の目的・背景**：LSPサーバーとクライアント間の通信に使用される全てのデータ型を一元的に定義し、型安全なプロトコル通信を実現する。LSP v3.16仕様に準拠した型定義により、初期化パラメータ、補完、ホバー、定義ジャンプ等のあらゆるLSP機能のリクエスト・レスポンス型が提供される。

**機能の利用シーン**：serve-dの全モジュールがLSPプロトコルのデータ構造を使用する際に、このサブパッケージの型定義をインポートして利用する。JSON（de）シリアライゼーション、URI変換、型バリアント処理等の基盤機能もここに含まれる。

**主要な処理内容**：
1. LSP v3.16プロトコル型の定義（InitializeParams、CompletionItem、TextDocumentIdentifier等の数百の型）
2. JSON操作ユーティリティ（mir.serdeベースのシリアライズ/デシリアライズ、RootJsonToken）
3. URI処理ユーティリティ（ファイルパスとfile:// URI間の相互変換、URIの正規化）
4. StructVariant型による柔軟な型バリアント処理（複数の許容型を持つフィールドの自動デシリアライゼーション）

**関連システム・外部連携**：LSPクライアント（VSCode等のエディタ）との通信データ構造として使用される。mir.serdeライブラリによるJSON操作を内部で利用する。

**権限による制御**：なし（型定義のみを提供する基盤モジュール）

## 関連画面

本サブパッケージは直接的に画面と関連しない。全てのLSP機能が間接的にこの型定義を使用する。

## 機能種別

基盤ライブラリ / 型定義

## 入力仕様

### 入力パラメータ

型定義サブパッケージのため、パラメータ入力は各ユーティリティ関数に依存する。

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| file (uriFromFile) | string | Yes | ファイルシステムの絶対パス | 絶対パスであること |
| uri (uriToFile) | DocumentUri | Yes | file:// スキームのURI | file://で始まること |
| value (serializeJson) | T | Yes | シリアライズ対象の値 | mir.serdeでシリアライズ可能な型 |
| text (deserializeJson) | string | Yes | デシリアライズ対象のJSON文字列 | 有効なJSON文字列 |

### 入力データソース

- LSPクライアントからのJSONメッセージ（デシリアライゼーション対象）
- ローカルファイルシステムパス（URI変換対象）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DocumentUri | string | file://スキームのURI文字列 |
| JsonValue | mir.algebraic_alias.json.JsonAlgebraic | JSON値のバリアント型 |
| RootJsonToken | struct | JSONをパススルーするためのラッパー型 |
| 各LSP型 | struct | LSP v3.16仕様に準拠した各種データ型 |

### 出力先

serve-dの各モジュールへの型提供（コンパイル時のインポート）

## 処理フロー

### 処理シーケンス

```
1. JSON受信
   └─ LSPクライアントからJSON-RPCメッセージを受信
2. デシリアライズ
   └─ deserializeJson関数でJSON文字列をD言語の型に変換
3. ビジネスロジック処理
   └─ 各LSP機能で型を使用して処理を実行
4. シリアライズ
   └─ serializeJson関数でD言語の型をJSON文字列に変換
5. JSON送信
   └─ JSON-RPCメッセージとしてクライアントに返信
```

### フローチャート

```mermaid
flowchart TD
    A[JSON文字列受信] --> B[deserializeJson]
    B --> C[LSPプロトコル型のインスタンス]
    C --> D[ビジネスロジック処理]
    D --> E[結果型のインスタンス]
    E --> F[serializeJson]
    F --> G[JSON文字列送信]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-72-01 | URI変換規則 | ファイルパスは絶対パスのみ受け付け、相対パスはExceptionを発生させる | uriFromFile呼び出し時 |
| BR-72-02 | Windowsパス対応 | Windowsドライブレターの`:`は`%3A`にエンコード、UNCパスは`file://share/path`形式 | URI変換時 |
| BR-72-03 | StructVariant自動解決 | JSON構造体の必須キーの有無に基づいて、複数の許容型から適切な型を自動判定してデシリアライズ | JSONデシリアライゼーション時 |
| BR-72-04 | RootJsonToken パススルー | RootJsonTokenはJSONをそのまま保持し、(デ)シリアライゼーションを回避する | JSON操作時 |

### 計算ロジック

特になし。

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

本機能ではデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Exception | uriFromFileに相対パスを渡した場合 | 絶対パスに変換してから呼び出す |
| - | IonException | StructVariantのデシリアライゼーションで許容型のいずれにも一致しない場合 | JSON構造を確認し、必須キーが含まれているか確認 |

### リトライ仕様

型変換はステートレスであるため、リトライ不要。

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

不要（ステートレスな型変換のみ）。

## パフォーマンス要件

mir.serdeベースの高速JSON(デ)シリアライゼーションを提供。コンパイル時のメタプログラミングにより、ランタイムオーバーヘッドを最小化する。

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

URIエンコーディング/デコーディングで特殊文字を適切にエスケープ処理する（`encodeComponent`/`decodeComponent`使用）。

## 備考

- LSP v3.16仕様に準拠: https://microsoft.github.io/language-server-protocol/specifications/specification-3-16/
- mir.serdeライブラリ依存（mir.algebraic, mir.deser, mir.ser）
- protocol.dは非常に大きなファイル（数千行）であり、LSPの全型定義を含む

---

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

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

### 推奨読解順序

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

LSPプロトコル型定義の中核を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protocol.d | `protocol/source/served/lsp/protocol.d` | LSP型の定義方法、StructVariantの仕組み（1-250行目） |
| 1-2 | jsonops.d | `protocol/source/served/lsp/jsonops.d` | JsonValue型エイリアス、serializeJson/deserializeJson関数、RootJsonToken型 |

**読解のコツ**: D言語のテンプレートメタプログラミングが多用されている。`@serdeFallbackStruct`や`@serdeProxy`はmir.serdeライブラリのUDAで、JSON(デ)シリアライゼーションの挙動を制御する。`StructVariant`は複数の型候補からJSON構造の必須キーに基づいて自動判定する仕組みである。

#### Step 2: URI処理を理解する

ファイルパスとURIの相互変換を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uri.d | `protocol/source/served/lsp/uri.d` | `uriFromFile`関数（15-29行目）でファイルパスからURIへの変換 |
| 2-2 | uri.d | `protocol/source/served/lsp/uri.d` | `uriToFile`関数（49-64行目）でURIからファイルパスへの変換 |

**主要処理フロー**:
1. **19-21行目**: 相対パスの検出とException発生
2. **22行目**: パスの正規化とバックスラッシュの置換
3. **24-28行目**: Windowsパス・UNCパスの特別処理
4. **28行目**: `encodeComponent`でURLエンコーディング、`%2F`は`/`に戻す

#### Step 3: JSON操作を理解する

JSON(デ)シリアライゼーションの仕組みを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | jsonops.d | `protocol/source/served/lsp/jsonops.d` | `serializeJson`関数（22-30行目）とRootJsonToken特別処理 |
| 3-2 | jsonops.d | `protocol/source/served/lsp/jsonops.d` | `deserializeJson`関数（32-40行目）とRootJsonToken特別処理 |
| 3-3 | jsonops.d | `protocol/source/served/lsp/jsonops.d` | `RootJsonToken`構造体（44-49行目）とパススルー機構 |

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

```
serve-d 全モジュール
    │
    ├─ protocol.d (型定義)
    │      ├─ StructVariant (型バリアント)
    │      ├─ 各LSP型定義 (InitializeParams, CompletionItem等)
    │      └─ public import jsonops.d
    │
    ├─ jsonops.d (JSON操作)
    │      ├─ serializeJson / deserializeJson
    │      ├─ RootJsonToken
    │      └─ JsonValue (mir.algebraic_alias.json)
    │
    └─ uri.d (URI処理)
           ├─ uriFromFile (ファイル→URI)
           ├─ uriToFile (URI→ファイル)
           └─ uriBuildNormalized (相対URI正規化)
```

### データフロー図

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

JSON文字列 ──────────▶ deserializeJson ──────────▶ LSPプロトコル型
                          (mir.deser.json)

LSPプロトコル型 ──────▶ serializeJson ───────────▶ JSON文字列
                          (mir.ser.json)

ファイルパス ──────────▶ uriFromFile ─────────────▶ DocumentUri
DocumentUri ──────────▶ uriToFile ───────────────▶ ファイルパス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| protocol.d | `protocol/source/served/lsp/protocol.d` | ソース | LSP v3.16プロトコル型の全定義 |
| jsonops.d | `protocol/source/served/lsp/jsonops.d` | ソース | JSON操作ユーティリティ（serializeJson, deserializeJson, RootJsonToken） |
| uri.d | `protocol/source/served/lsp/uri.d` | ソース | URI操作ユーティリティ（uriFromFile, uriToFile, uriBuildNormalized） |
