# 機能設計書 16-スニペット登録 (served/addDependencySnippet)

## 概要

本ドキュメントは、serve-d LSPサーバーにおける「スニペット登録」機能の設計を記述する。LSPカスタムメソッド `served/addDependencySnippet` を処理し、依存関係に基づくスニペットをserve-d全体に登録する機能である。

### 本機能の処理概要

外部ツール（主にエディタ拡張機能）から依存パッケージ固有のスニペットを動的に登録するためのAPIを提供する。登録されたスニペットは、指定された依存関係が存在するプロジェクトでのコード補完時にスニペット候補として表示される。

**業務上の目的・背景**：D言語のパッケージエコシステムでは、各ライブラリに固有のコードパターンが存在する。例えば特定のフレームワークの定型的な記述パターンをスニペットとして提供することで、ライブラリ利用時のコーディング効率を向上させる。本機能はエディタ拡張がこうしたスニペットを動的に登録するための拡張ポイントとなる。

**機能の利用シーン**：エディタ拡張機能（VSCode拡張等）がserve-dの起動後に、プロジェクトの依存パッケージに基づいてカスタムスニペットを登録する際に使用される。

**主要な処理内容**：
1. AddDependencySnippetParams からスニペットデータと依存関係情報を抽出
2. SerializablePlainSnippet を PlainSnippet に変換
3. SnippetsComponent.addDependencySnippet で登録

**関連システム・外部連携**：SnippetsComponent（workspace-d）、LSPクライアント（エディタ拡張）

**権限による制御**：`--provide context-snippets` コマンドライン引数によるSnippetsComponentの有効化が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 68 | スニペット登録（served/addDependencySnippet） | 主機能 | 依存関係に基づくスニペットをserve-d全体に登録する |

## 機能種別

データ登録処理 / API

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| params | AddDependencySnippetParams | Yes | スニペット登録パラメータ | - |
| params.requiredDependencies | string[] | Yes | このスニペットが有効になる依存パッケージ名リスト | - |
| params.snippet | SerializablePlainSnippet | Yes | 登録するスニペットデータ | - |

### 入力データソース

LSPクライアントからの `served/addDependencySnippet` リクエスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | bool | 登録成功: true、SnippetsComponent未ロード: false |

### 出力先

LSPクライアントへのレスポンスメッセージ

## 処理フロー

### 処理シーケンス

```
1. SnippetsComponent のロード状態確認
   └─ 未ロードの場合、false を返却
2. SerializablePlainSnippet から PlainSnippet への変換
   └─ tupleof を使用した構造体フィールドの列挙・変換
3. SnippetsComponent.addDependencySnippet で登録
   └─ requiredDependencies と snippet を渡す
4. true を返却
```

### フローチャート

```mermaid
flowchart TD
    A[served/addDependencySnippet 受信] --> B{SnippetsComponent ロード済み?}
    B -->|No| C[false 返却]
    B -->|Yes| D[SerializablePlainSnippet → PlainSnippet 変換]
    D --> E[addDependencySnippet で登録]
    E --> F[true 返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-16-01 | コンポーネント必須 | SnippetsComponentが未ロードの場合はfalseを返却 | 全リクエスト |
| BR-16-02 | 列挙型変換 | SerializablePlainSnippetの列挙型フィールドはcast変換でPlainSnippetに変換 | 変換処理時 |
| BR-16-03 | context-snippets必須 | --provide context-snippetsオプションが必要 | サーバー起動時 |

### 計算ロジック

特になし

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

本機能ではデータベース操作は行わない。SnippetsComponentのインメモリストアに登録。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンポーネント不在 | SnippetsComponent未ロード | false返却 |

### リトライ仕様

リトライなし。

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

トランザクション管理なし。

## パフォーマンス要件

通常は起動時に1回実行されるのみ。特別な性能要件なし。

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

外部からのスニペット登録であるため、スニペット内容の検証は SnippetsComponent 側に委ねる。

## 備考

- `static assert` によりSerializablePlainSnippetとPlainSnippetのフィールド名の同一性が検証される
- `tupleof` を用いた列挙により、構造体フィールドが一対一で対応していることを保証

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | complete.d | `source/served/commands/complete.d` | AddDependencySnippetParams型とSerializablePlainSnippet型の関係を理解する |

**読解のコツ**: D言語の `tupleof` はコンパイル時に構造体の全フィールドをタプルとして取得する機能。`static assert` でフィールド名の同一性をコンパイル時に検証している（1407-1409行目）。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | complete.d | `source/served/commands/complete.d` | `addDependencySnippet` 関数（1399-1415行目）がエントリーポイント |

**主要処理フロー**:
1. **1399行目**: `@protocolMethod("served/addDependencySnippet")` でLSPメソッド登録
2. **1402-1403行目**: SnippetsComponentのロード確認
3. **1404行目**: PlainSnippet構造体の初期化
4. **1405-1411行目**: tupleofによるフィールド列挙とcast変換
5. **1413行目**: `addDependencySnippet` で登録
6. **1414行目**: true返却

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

```
addDependencySnippet (complete.d:1400)
    │
    ├─ backend.has!SnippetsComponent ... ロード確認
    │
    └─ SnippetsComponent.addDependencySnippet
           └─ 依存関係付きスニペット登録
```

### データフロー図

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

AddDependencySnippetParams ──▶ addDependencySnippet ──▶ bool (成功/失敗)
  ├─ requiredDependencies          │
  └─ snippet                       └─ SnippetsComponent
       (Serializable)                   (PlainSnippet変換後登録)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| complete.d | `source/served/commands/complete.d` | ソース | addDependencySnippet関数 |
| extension.d | `source/served/extension.d` | ソース | コマンド登録 |
