# 機能設計書 55-依存関係一覧取得

## 概要

本ドキュメントは、serve-dのLSPカスタムリクエスト `served/listDependencies` の機能設計を記述する。指定パッケージの依存関係一覧（バージョン・パス・説明等）を返却する機能である。

### 本機能の処理概要

**業務上の目的・背景**：D言語のDUBプロジェクトには複数の依存パッケージが存在し、エディタのDUB依存関係ツリー表示で依存関係の階層構造を可視化する必要がある。本機能は、ルート依存関係または指定パッケージの子依存関係をメタデータ付きで返却し、クライアント側でのツリー表示を実現する。

**機能の利用シーン**：エディタのサイドバーにDUB依存関係ツリーを表示する際、ルートの依存関係一覧を取得するためにpackageNameを空で呼び出し、展開時に特定パッケージの子依存関係を取得するためにpackageNameを指定して呼び出す。

**主要な処理内容**：
1. クライアントから `served/listDependencies` リクエストを受信する
2. アクティブなDUBインスタンスの存在を確認する
3. packageNameの有無に応じて処理を分岐する
   - 空の場合：ルート依存関係一覧を取得
   - 指定ありの場合：指定パッケージの子依存関係一覧を取得
4. 各依存関係のメタデータ（バージョン、パス、説明、ライセンス等）を収集する
5. DubDependency配列として返却する

**関連システム・外部連携**：workspace-dサブパッケージのDubComponentに処理を委譲する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 55 | 依存関係一覧取得（served/listDependencies） | 主画面 | 指定パッケージの依存関係一覧を返却する |
| 12 | DUBツリー初期化通知 | 呼出元 | coded/initDubTree通知後にクライアントが本機能を呼び出す |
| 13 | DUBツリー更新通知 | 呼出元 | coded/updateDubTree通知後にクライアントが本機能を再呼出しする |

## 機能種別

データ取得処理（DUB依存関係のメタデータ一覧取得）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| packageName | string | No | 子依存関係を取得する対象パッケージ名。空の場合はルート依存関係を返却。ListDependenciesParams構造体またはstring直接指定に対応 | なし |

### 入力データソース

LSPクライアントからのJSON-RPCリクエスト（ListDependenciesParams構造体）。ListDependenciesParamsはSingleValueParams!(string, "packageName") mixinを使用しており、構造体形式とstring直接形式の両方に対応する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 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） |

### 出力先

LSPクライアントへのJSON-RPCレスポンス（DubDependency配列）

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ ListDependenciesParamsとしてデシリアライズ
2. アクティブインスタンス確認
   └─ DubComponentが存在しない場合は空配列を返却
3. 依存関係一覧取得
   ├─ [packageNameが空の場合]
   │   └─ dub.rootDependencies でルート依存関係を取得
   │       └─ 各依存のメタデータを dub.getPackageInfo() で取得
   │       └─ root = true に設定
   └─ [packageNameが指定の場合]
       └─ dub.getPackageInfo(packageName).dependencies で子依存関係を取得
           └─ 各依存のメタデータを dub.getPackageInfo() で取得
4. 結果返却
   └─ DubDependency配列として返却
```

### フローチャート

```mermaid
flowchart TD
    A[served/listDependencies リクエスト受信] --> B{DubComponent あり?}
    B -->|No| C[空配列を返却]
    B -->|Yes| D{packageName が空?}
    D -->|Yes| E[rootDependencies を取得]
    D -->|No| F[getPackageInfo で子依存関係を取得]
    E --> G[各依存のメタデータを収集]
    F --> G
    G --> H[DubDependency 配列を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-55-01 | ルート/子の分岐 | packageNameが空の場合はルート依存関係、指定ありの場合は指定パッケージの子依存関係を返却する | 常時 |
| BR-55-02 | 失敗パッケージの検出 | dub.failedPackagesを参照し、読み込み失敗したパッケージにはfailed=trueを設定する | 常時 |
| BR-55-03 | ルートフラグ | ルート依存関係の場合にのみroot=trueを設定する。子依存関係ではrootは設定されない（デフォルトfalse） | packageNameが空の場合 |
| BR-55-04 | hasDependenciesフラグ | 各パッケージが更に子依存関係を持つかどうかをdependencies.lengthで判定する | 常時 |

### 計算ロジック

特になし。DubComponentからの情報をDubDependency構造体にマッピングして返却する。

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

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

本機能はデータベースを使用しない。DubComponentのインメモリキャッシュから情報を取得する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 暗黙的空配列 | DubComponentが存在しない場合 | 空のDubDependency配列を返却 |

### リトライ仕様

リトライは不要。

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

トランザクション管理は不要。読み取り専用操作。

## パフォーマンス要件

即時応答が期待される。DubComponentからのパッケージ情報取得はインメモリ操作である。

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

返却されるpath情報にはファイルシステムの絶対パスが含まれる。

## 備考

- ListDependenciesParamsはSingleValueParams!(string, "packageName") mixinを使用しており、`"package-name"` のようなstring直接指定と `{"packageName": "package-name"}` のような構造体指定の両方に対応する
- サブパッケージ名は `other.subPackages.map!"a.name".array` で取得される
- 本機能はDUBツリー初期化通知（coded/initDubTree）およびDUBツリー更新通知（coded/updateDubTree）の後にクライアントから呼び出される

---

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

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

### 推奨読解順序

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

DubDependency構造体とListDependenciesParamsの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 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` を避けるため `version_` としている。シリアライズ時はJSONキー `"version"` が使われる。

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

listDependencies関数の全体処理を把握する。

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

**主要処理フロー**:
1. **327行目**: `@protocolMethod("served/listDependencies")` - LSPメソッド登録
2. **328行目**: `DubDependency[] listDependencies(ListDependenciesParams params)` - 配列返却
3. **332-333行目**: DubComponentの存在チェック。なければ空配列返却
4. **336行目**: `dub.failedPackages` - 失敗パッケージ一覧の取得
5. **337-357行目**: packageNameが空の場合の処理。rootDependenciesを取得しroot=trueを設定
6. **359-380行目**: packageNameが指定の場合の処理。getPackageInfoから子依存関係を取得

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

```
listDependencies(ListDependenciesParams) [source/served/commands/dub.d:328]
    |
    +-- activeInstance [source/served/types.d:471]
    |
    +-- DubComponent [workspace-d API]
    |       |
    |       +-- failedPackages [失敗パッケージ一覧]
    |       +-- rootDependencies [ルート依存関係]
    |       +-- getPackageInfo(name) [パッケージメタデータ取得]
    |              +-- ver, path, description, homepage, authors
    |              +-- copyright, license, subPackages, dependencies
    |
    +-- return DubDependency[]
```

### データフロー図

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

ListDependenciesParams       -->  listDependencies()            -->  DubDependency[]
  packageName: string              |                                   (name, version,
  (空=ルート/指定=子)               +-- rootDependencies                 path, description,
                                   |   or getPackageInfo               failed, root, ...)
                                   +-- メタデータ収集
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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プロトコルメソッドのルーティング基盤 |
