# 画面設計書 55-依存関係一覧取得（served/listDependencies）

## 概要

本ドキュメントは、serve-d LSPサーバーが提供するカスタムリクエスト `served/listDependencies` の設計を記述する。このリクエストは、DUBパッケージの依存関係一覧（バージョン・パス・説明・ライセンス等の詳細情報を含む）を返却する。

### 本画面の処理概要

このカスタムリクエストは、エディタ（LSPクライアント）からの要求に応じて、DUBプロジェクトの依存関係ツリーの情報を階層的に提供する処理である。

**業務上の目的・背景**：D言語の開発でDUBパッケージマネージャを使用する際、プロジェクトが依存しているパッケージの一覧を確認する必要がある。エディタのサイドバーに依存関係ツリーを表示し、各パッケージのバージョン、パス、ホームページ、ライセンス等の詳細情報を開発者に提供することで、依存関係の管理を効率化する。

**画面へのアクセス方法**：LSPクライアントが `served/listDependencies` メソッドをJSON-RPCリクエストとして送信する。エディタのDUBツリービュー（coded/initDubTree、coded/updateDubTree通知を契機に初期化・更新される）から呼び出される。

**主要な操作・処理内容**：
1. クライアントからJSON-RPCリクエスト `served/listDependencies` を受信する
2. パッケージ名パラメータが空の場合はルート依存関係一覧を返却する
3. パッケージ名パラメータが指定されている場合はそのパッケージの子依存関係一覧を返却する
4. 各依存関係について、バージョン、パス、説明、ホームページ、著者、著作権、ライセンス、サブパッケージ、子依存関係の有無を含む詳細情報を返却する

**画面遷移**：DUB依存関係管理フローにおいて、ツリー表示の基礎データを提供する。DUBツリー初期化通知（No.12）やDUBツリー更新通知（No.13）の後にクライアントから呼び出される。依存関係インストール（No.58）、更新（No.59）、削除（No.60）の操作対象選択にも使用される。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 55 | 依存関係一覧取得 (served/listDependencies) | 主機能 | 指定パッケージの依存関係一覧（バージョン・パス・説明等）を返却する |

## 画面種別

カスタムLSPリクエスト（データ取得・一覧）

## URL/ルーティング

LSPカスタムメソッド: `served/listDependencies`

## 入出力項目

### 入力（リクエスト）

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| packageName | string | いいえ | 子依存関係を取得する対象パッケージ名。空の場合はルート依存関係を返却。ListDependenciesParams構造体またはstring直接指定 |

### 出力（レスポンス）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | DubDependency[] | 依存関係情報の配列 |

### DubDependency構造体

| フィールド | 型 | 説明 |
|-----------|-----|------|
| name | string | パッケージ名 |
| failed | bool | 読み込み失敗フラグ |
| version | string | インストール済みバージョン（未インストール時null） |
| path | string | パッケージのローカルパス（ローカルに存在しない場合null） |
| description | string | パッケージの説明 |
| homepage | string | ホームページURL |
| authors | string[] | 著者一覧 |
| copyright | string | 著作権情報 |
| license | string | ライセンス情報 |
| subPackages | string[] | サブパッケージ名一覧 |
| hasDependencies | bool | 子依存関係が存在するかどうか |
| root | bool | ルート依存関係かどうか（packageNameが空の場合のみtrue） |

## 表示項目

エディタのDUBツリービューに表示される情報：

| 項目 | 表示形式 | 説明 |
|------|----------|------|
| パッケージ名 | 文字列 | 依存パッケージの名前 |
| バージョン | 文字列 | インストール済みバージョン番号 |
| 説明 | 文字列 | パッケージの概要説明 |
| パス | 文字列 | ローカルファイルシステム上のパス |
| 失敗フラグ | アイコン等 | 読み込みに失敗したパッケージの視覚的表示 |

## イベント仕様

### 1-ルート依存関係取得（packageName が空）

1. `activeInstance` からDubComponentを取得する
2. `dub.rootDependencies` でルート依存関係名の配列を取得する
3. `dub.failedPackages` で読み込み失敗パッケージの一覧を取得する
4. 各ルート依存関係について：
   - `r.root = true` を設定する
   - `dub.getPackageInfo(dep)` でパッケージ詳細情報を取得する
   - バージョン、パス、説明、ホームページ、著者、著作権、ライセンスを設定する
   - サブパッケージ名一覧を `map!"a.name"` で抽出する
   - 子依存関係の有無を `dependencies.length > 0` で判定する
5. DubDependency配列を返却する

### 2-子依存関係取得（packageName が指定されている場合）

1. `activeInstance` からDubComponentを取得する
2. `dub.getPackageInfo(params.packageName)` で指定パッケージの情報を取得する
3. `info.dependencies` から依存関係名とバージョンの連想配列を取得する
4. 各子依存関係について：
   - `dub.getPackageInfo(name)` で詳細情報を取得する
   - ルート依存関係と同様のフィールドを設定する（rootフラグはfalse）
5. DubDependency配列を返却する

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 依存関係一覧取得 | (なし) | SELECT相当 | DubComponentのインメモリ状態からの読み取りのみ |

### テーブル別更新項目詳細

データベースへの更新は発生しない。

## メッセージ仕様

| メッセージID | 種別 | 条件 | メッセージ内容 |
|-------------|------|------|---------------|
| (なし) | - | - | 本リクエストではユーザー向けメッセージは発生しない |

## 例外処理

| 条件 | 動作 | 返却値 |
|------|------|--------|
| activeInstanceがnull | 正常返却 | 空配列 |
| DubComponentが存在しない | 正常返却 | 空配列 |

## 備考

- ListDependenciesParamsは `SingleValueParams!(string, "packageName")` を使用しており、string直接指定と構造体指定の両方に対応する
- DUBツリー初期化通知（coded/initDubTree）やDUBツリー更新通知（coded/updateDubTree）をトリガーとしてクライアントから呼び出される
- 階層的なツリー表示のために、まずpackageName空でルート依存関係を取得し、hasDependencies=trueのパッケージを展開する際に再度packageName指定で子依存関係を取得するパターンが一般的

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protoext.d | `source/served/lsp/protoext.d` | DubDependency構造体（53-80行目）の全フィールド定義を確認 |
| 1-2 | protoext.d | `source/served/lsp/protoext.d` | ListDependenciesParams構造体（526-529行目）のSingleValueParams mixinを確認 |

**読解のコツ**: `@serdeKeys("version") string version_` はD言語の予約語回避のためフィールド名が `version_` だが、JSON上は `version` キーとしてシリアライズされる。

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

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

**主要処理フロー**:
1. **327行目**: `@protocolMethod("served/listDependencies")` UDAでLSPメソッドとして登録
2. **328行目**: `DubDependency[] listDependencies(ListDependenciesParams params)` - 配列返却
3. **332-333行目**: DubComponentの存在チェック
4. **336行目**: `dub.failedPackages` - 失敗パッケージ一覧取得
5. **337行目**: `if (!params.packageName.length)` - ルートか子依存関係かの分岐
6. **339行目**: `dub.rootDependencies` - ルート依存関係名一覧取得
7. **346行目**: `dub.getPackageInfo(dep)` - パッケージ詳細情報取得
8. **354行目**: `other.subPackages.map!"a.name".array` - サブパッケージ名抽出
9. **355行目**: `other.dependencies.length > 0` - 子依存関係有無判定
10. **361行目**: 子依存関係取得パス：`dub.getPackageInfo(params.packageName)` から `info.dependencies` を取得

#### Step 3: 呼び出し元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | (クライアント側) | - | coded/initDubTree通知およびcoded/updateDubTree通知を受けてクライアントがlistDependenciesを呼び出す |

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

```
LSPクライアント (エディタ DUBツリービュー)
    |
    |  served/listDependencies (JSON-RPC request)
    v
listDependencies(ListDependenciesParams) [source/served/commands/dub.d:328]
    |
    +-- activeInstance.get!DubComponent
    |
    +-- [packageName が空の場合]
    |       +-- dub.rootDependencies
    |       +-- dub.failedPackages
    |       +-- dub.getPackageInfo(dep) [各ルート依存関係]
    |
    +-- [packageName が指定されている場合]
            +-- dub.getPackageInfo(packageName)
            +-- info.dependencies [連想配列]
            +-- dub.getPackageInfo(name) [各子依存関係]
```

### データフロー図

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

JSON-RPC Request     --->  listDependencies()           --->  DubDependency[]
  packageName: ""             |                                  |
  (or "vibe-d")              +-- [packageName空]                +-- [{name, version, path,
                             |   rootDependencies取得               description, homepage,
                             |   各パッケージ情報取得                  authors, license, ...}]
                             |
                             +-- [packageName指定]
                                 指定パッケージのdependencies取得
                                 各子パッケージ情報取得
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dub.d | `source/served/commands/dub.d` | ソース | listDependencies関数の実装（327-382行目） |
| protoext.d | `source/served/lsp/protoext.d` | ソース | DubDependency構造体（53-80行目）、ListDependenciesParams（526-529行目） |
| types.d | `source/served/types.d` | ソース | activeInstance、backend等のグローバル定義 |
| extension.d | `source/served/extension.d` | ソース | LSPメソッドディスパッチ基盤 |
