# 帳票設計書 9-DUB依存関係一覧

## 概要

本ドキュメントは、serve-dのDUB依存関係一覧機能の設計を記述する。DUBプロジェクトの依存パッケージ一覧を出力し、パッケージの詳細情報を提供する帳票である。

### 本帳票の処理概要

DUB依存関係一覧は、DUBプロジェクトの依存パッケージをツリー構造で提供する帳票である。ルートレベルの依存と、特定パッケージの子依存の両方を取得できる。

**業務上の目的・背景**：D言語プロジェクトの依存関係を可視化し、開発者がプロジェクトの依存ツリーを把握できるようにする。パッケージのバージョン、パス、説明、ライセンス情報などの詳細を提供することで、依存関係の管理と監査を支援する。失敗した依存の特定も可能。

**帳票の利用シーン**：エディタの依存関係ツリービュー（coded/updateDubTree）やコマンドパレットから依存パッケージ情報を参照する際に使用される。packageNameパラメータの有無で、ルート依存の一覧またはサブ依存の一覧を返す。

**主要な出力内容**：
1. パッケージ名（name）
2. バージョン（version_）
3. パッケージパス（path）
4. 説明（description）
5. ホームページ（homepage）
6. 著者（authors）
7. 著作権（copyright）
8. ライセンス（license）
9. サブパッケージ名一覧（subPackages）
10. 子依存有無（hasDependencies）
11. 読み込み失敗フラグ（failed）
12. ルート依存フラグ（root）

**帳票の出力タイミング**：served/listDependenciesリクエストを受信した際にレスポンスとして返却される。

**帳票の利用者**：D言語開発者（依存関係の管理・確認を行う開発者）

## 帳票種別

ビルド情報レポート（LSPレスポンス）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | 依存関係ツリービュー | `served/listDependencies` | 依存ツリー表示時にリクエスト |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON-RPC（LSPプロトコル） |
| 用紙サイズ | N/A（デジタル出力） |
| 向き | N/A |
| ファイル名 | N/A（ストリーム出力） |
| 出力方法 | served/listDependenciesレスポンス |
| 文字コード | UTF-8 |

### PDF固有設定

N/A

### Excel固有設定

N/A

## 帳票レイアウト

### レイアウト概要

DubDependency構造体の配列として依存パッケージ一覧を出力する。

```
┌─────────────────────────────────────────┐
│  DubDependency[]                         │
├─────────────────────────────────────────┤
│  [0] name: string                        │
│      failed: bool                        │
│      root: bool                          │
│      version_: string                    │
│      path: string                        │
│      description: string                 │
│      homepage: string                    │
│      authors: string[]                   │
│      copyright: string                   │
│      license: string                     │
│      subPackages: string[]               │
│      hasDependencies: bool               │
│  [1] ...                                 │
└─────────────────────────────────────────┘
```

### ヘッダー部

N/A（リクエストパラメータのpackageNameで取得対象を指定）

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | name | パッケージ名 | DubComponent.rootDependencies / getPackageInfo | 文字列 | - |
| 2 | failed | 読み込み失敗フラグ | DubComponent.failedPackages.canFind(dep) | ブール値 | - |
| 3 | root | ルート依存フラグ | packageName未指定時にtrue | ブール値 | - |
| 4 | version_ | インストール済みバージョン | DubComponent.getPackageInfo(dep).ver | 文字列 | - |
| 5 | path | パッケージディレクトリパス | DubComponent.getPackageInfo(dep).path | 文字列 | - |
| 6 | description | パッケージ説明 | DubComponent.getPackageInfo(dep).description | 文字列 | - |
| 7 | homepage | ホームページURL | DubComponent.getPackageInfo(dep).homepage | URL文字列 | - |
| 8 | authors | 著者一覧 | DubComponent.getPackageInfo(dep).authors | 文字列配列 | - |
| 9 | copyright | 著作権情報 | DubComponent.getPackageInfo(dep).copyright | 文字列 | - |
| 10 | license | ライセンス | DubComponent.getPackageInfo(dep).license | 文字列 | - |
| 11 | subPackages | サブパッケージ名一覧 | other.subPackages.map!"a.name".array | 文字列配列 | - |
| 12 | hasDependencies | 子依存の有無 | other.dependencies.length > 0 | ブール値 | - |

### フッター部

N/A

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| DUBコンポーネント有効 | activeInstance.has!DubComponentがtrue | Yes |
| packageName指定 | 空: ルート依存一覧、指定: 該当パッケージの子依存一覧 | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | DubComponent.rootDependencies / dependencies の返却順 | - |

### 改ページ条件

N/A

## データベース参照仕様

### 参照テーブル一覧

本帳票はデータベースを使用しない。DUBパッケージマネージャの情報を使用する。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| N/A | - | - |

### テーブル別参照項目詳細

N/A

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| failed | failedPackages.canFind(dep) | - | 行344, 367 |
| root | packageName未指定時のみtrue | - | 行345 |
| subPackages | other.subPackages.map!"a.name".array | - | subPackageオブジェクトからname文字列のみ抽出 |
| hasDependencies | other.dependencies.length > 0 | - | 行355, 376 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[served/listDependenciesリクエスト受信] --> B{DubComponent有効?}
    B -->|No| Z[空配列返却]
    B -->|Yes| C{packageName指定あり?}
    C -->|No| D[ルート依存一覧取得]
    D --> E[各依存のgetPackageInfoで詳細取得]
    E --> F[DubDependency配列生成: root=true]
    C -->|Yes| G[指定パッケージのgetPackageInfo]
    G --> H[dependencies連想配列をループ]
    H --> I[各子依存のgetPackageInfoで詳細取得]
    I --> J[DubDependency配列生成: root未設定]
    F --> K[配列返却]
    J --> K
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| DUB未設定 | activeInstanceにDubComponentが存在しない | なし | 空の配列を返却 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | プロジェクトの直接依存数（通常数個〜数十個） |
| 目標出力時間 | DUBコンポーネントのプロパティ参照で即時応答 |
| 同時出力数上限 | 制限なし |

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

- DUBパッケージ情報の参照のみ行い、パッケージの変更は行わない
- ホームページURLなどの外部リンク情報はそのまま返却される

## 備考

- packageNameパラメータが空の場合はルート依存一覧、指定がある場合はそのパッケージの子依存一覧を返す（行337-380）
- failedPackagesでパッケージの読み込み失敗を検出（行336, 344, 367）
- version_フィールドはJSON出力時に@serdeKeys("version")で"version"キーとなる（protoext.d 行60-61）
- ルート依存のみroot=trueフラグが設定される（行345）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protoext.d | `source/served/lsp/protoext.d` | DubDependency構造体（行52-80）: 全12フィールドの定義 |
| 1-2 | protoext.d | `source/served/lsp/protoext.d` | ListDependenciesParams構造体（行526-529）: SingleValueParams!stringミックスインでpackageNameパラメータ |

**読解のコツ**: `@serdeKeys("version")` アノテーションにより、D言語の予約語`version`を避けてversion_フィールドを使用しつつ、JSONシリアライズ時は"version"キーとなる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | dub.d | `source/served/commands/dub.d` | listDependencies関数（行327-382）: served/listDependenciesハンドラ |

**主要処理フロー**:
1. **行330-333**: activeInstanceとDubComponentの有効性チェック
2. **行335-336**: DubComponent取得とfailedPackages取得
3. **行337**: packageName有無で分岐
4. **行339-357**: ルート依存パス: rootDependenciesループ + getPackageInfo
5. **行360-380**: 子依存パス: getPackageInfo(packageName).dependenciesループ

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

```
listDependencies(params)                          [dub.d:327]
    |
    +-- activeInstance.has!DubComponent             [dub.d:332]
    +-- instance.get!DubComponent                   [dub.d:335]
    +-- dub.failedPackages                          [dub.d:336]
    |
    +-- [packageName未指定]
    |       +-- dub.rootDependencies                [dub.d:339]
    |       +-- [foreach dep]
    |               +-- dub.getPackageInfo(dep)     [dub.d:346]
    |               +-- failedPackages.canFind(dep) [dub.d:344]
    |
    +-- [packageName指定]
            +-- dub.getPackageInfo(packageName)     [dub.d:361]
            +-- [foreach name, ver in dependencies]
                    +-- dub.getPackageInfo(name)     [dub.d:369]
                    +-- failedPackages.canFind(name) [dub.d:367]
```

### データフロー図

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

listDependenciesリクエスト ──> listDependencies()       ──> DubDependency[]
(packageName: optional)

DubComponent ───────────────> rootDependencies          ──> 依存パッケージ名一覧
                              getPackageInfo()          ──> パッケージ詳細情報
                              failedPackages            ──> 失敗パッケージ一覧
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dub.d | `source/served/commands/dub.d` | ソース | DUB依存関係一覧の主処理（listDependencies） |
| protoext.d | `source/served/lsp/protoext.d` | ソース | DubDependency構造体、ListDependenciesParams定義 |
| types.d | `source/served/types.d` | ソース | 共通型定義 |
| extension.d | `source/served/extension.d` | ソース | LSPサーバー拡張機能 |
