# 画面設計書 5-DUB依存関係ダウンロード確認ダイアログ

## 概要

本ドキュメントは、serve-d LSPサーバーにおけるDUB依存関係ダウンロード確認ダイアログの画面設計書である。DUBパッケージがローカルに見つからない場合に、Upgrade/Always/Neverの選択肢をエディタに表示する。

### 本画面の処理概要

**業務上の目的・背景**：DUBはD言語のパッケージマネージャであり、プロジェクトの依存パッケージがローカルにインストールされていない場合、コード補完や静的解析が正しく動作しない。本ダイアログはユーザーに依存関係の自動ダウンロードを許可するかを確認し、`dub upgrade --missing-only` による依存関係解決を行うかどうかを判断する。ユーザーは一度だけ実行するか、常に自動実行するか、または永続的に無効化するかを選択できる。

**画面へのアクセス方法**：No.3 ワークスペーススタートアップの `delayedProjectActivation` 関数内で、DUBコンポーネントのアタッチ後に `dub.missingDependencies` が存在し、かつ `config.d.forceDownloadDependencies` が `DubUpgradeAction.ask` の場合に自動表示される。

**主要な操作・処理内容**：
1. DUBプロジェクトの不足依存関係をリスト化する
2. "Upgrade" / "Always" / "Never" の3つの選択肢を含む情報ダイアログを表示する
3. "Always" または "Never" 選択時は設定を永続化する（`coded/updateSetting` 通知）
4. "Upgrade" または "Always" 選択時は `dub.selectAndDownloadMissing()` を実行する

**画面遷移**：
- 遷移元：No.3 ワークスペーススタートアップ（delayedProjectActivation内）
- 遷移先：No.15 設定更新通知（Always/Never選択時）、インポートパス更新

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 54 | インポート更新 (served/updateImports) | 遷移先機能 | 依存関係ダウンロード後にインポートパスの更新が必要になる |
| 81 | 翻訳・多言語対応 | 補助機能 | ダイアログメッセージ（Upgrade/Always/Never）の翻訳にtranslate機能を使用する |

## 画面種別

LSPダイアログ（`window/showMessageRequest` による情報メッセージ + アクションボタン）

## URL/ルーティング

LSPメソッド名: `window/showMessageRequest`（サーバーからクライアントへの要求）

## 入出力項目

### 入力（内部パラメータ）

| 項目名 | 型 | 必須 | 説明 |
|--------|------|------|------|
| missingDeps | string[] | はい | 不足している依存パッケージ名の配列 |
| config.d.forceDownloadDependencies | DubUpgradeAction | はい | 現在のダウンロードポリシー設定（ask/always/never） |

### 出力（ユーザー選択結果）

| 項目名 | 型 | 説明 |
|--------|------|------|
| res | string | ユーザーが選択したアクション文字列 |

## 表示項目

### ダイアログ内容

| 項目 | 内容 | 説明 |
|------|------|------|
| メッセージ種別 | MessageType.info | 情報レベルのメッセージ |
| メッセージ本文 | "Some DUB packages could not be found locally, should they be downloaded through `dub upgrade --missing-only`?\n\n({不足パッケージリスト})" | 不足依存関係をリスト表示 |
| ボタン1 | "Upgrade" | 今回だけダウンロード実行 |
| ボタン2 | "Always" | 常にダウンロードを自動実行（設定を永続化） |
| ボタン3 | "Never" | ダウンロードしない（設定を永続化） |

## イベント仕様

### 1-ダイアログ表示

1. `delayedProjectActivation` 内で `dub.missingDependencies` が存在
2. `config.d.forceDownloadDependencies` が `DubUpgradeAction.ask`（デフォルト）の場合
3. 不足パッケージリストを作成（40文字超の場合は省略表示）
4. `rpc.window.requestMessage(MessageType.info, msg, [upgrade, always, never])` でダイアログ表示

### 2-Upgrade選択

1. `dub.selectAndDownloadMissing()` を実行
2. `dub.validateConfiguration()` で設定を再検証
3. 設定の永続化は行わない

### 3-Always選択

1. `coded/updateSetting` 通知で `forceDownloadDependencies` を "always" に永続化
2. `dub.selectAndDownloadMissing()` を実行
3. `dub.validateConfiguration()` で設定を再検証
4. 進捗通知 `ProgressType.importUpgrades` を送信

### 4-Never選択

1. `coded/updateSetting` 通知で `forceDownloadDependencies` を "never" に永続化
2. ダウンロードは実行しない

### 5-キャンセル

1. ダイアログを閉じた場合、ダウンロードは実行しない

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

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

| 操作（イベント） | 対象データ | 操作種別 | 概要 |
|----------------|-----------|---------|------|
| Always/Never選択 | クライアント設定 | 更新 | coded/updateSetting通知で設定を永続化 |
| Upgrade/Always選択 | DUBパッケージキャッシュ | ダウンロード | dub upgrade --missing-onlyの実行 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|------------|------|--------------|----------|
| d.dub.downloadMissingMsg | info | "Some DUB packages could not be found locally, should they be downloaded through `dub upgrade --missing-only`?\n\n({0})" | 常に表示 |
| d.dub.downloadMissingUpgrade | アクションボタン | "Upgrade" | 常に表示 |
| d.dub.downloadMissingAlways | アクションボタン | "Always" | 常に表示 |
| d.dub.downloadMissingNever | アクションボタン | "Never" | 常に表示 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ダウンロード失敗 | 不足依存関係のログ出力、補完が一部利用不可となる |
| 不足パッケージリストが長い | 40文字以降の最初のカンマで切り捨て、"..." を付加 |

## 備考

- `forceDownloadDependencies` の設定値は `ask`（デフォルト）、`always`、`never` の3種類
- "Always" 選択後は以降のワークスペースで自動的にダウンロードが実行される
- 不足パッケージリストは `missingDeps.join(", ")` で構築され、40文字超の場合は省略される
- `selectAndDownloadMissing()` はDUBの `upgrade --missing-only` コマンドに相当する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.d | `source/served/types.d` | `DubUpgradeAction` 列挙型（64-69行目）: ask, always, never |
| 1-2 | types.d | `source/served/types.d` | `Configuration.D.forceDownloadDependencies`（108行目）: デフォルトはDubUpgradeAction.ask |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | extension.d | `source/served/extension.d` | `delayedProjectActivation` 関数内の依存関係チェックブロック（806行目〜856行目） |

**主要処理フロー**:
1. **804行目**: `dub.missingDependencies` で不足依存関係を取得
2. **808行目**: `config.d.forceDownloadDependencies` の値でswitch分岐
3. **812-845行目**: `DubUpgradeAction.ask` の場合 - ダイアログ表示
4. **814-816行目**: 翻訳メッセージ取得（upgrade, always, never）
5. **817-822行目**: 不足パッケージリスト構築（40文字制限）
6. **824-828行目**: `rpc.window.requestMessage` でダイアログ表示
7. **830-834行目**: "Always" 選択時の `coded/updateSetting` 通知と処理
8. **836-840行目**: "Never" 選択時の `coded/updateSetting` 通知
9. **846-852行目**: `DubUpgradeAction.always` の場合 - 自動ダウンロード

#### Step 3: 翻訳メッセージを確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | en.txt | `views/en.txt` | 165行目: d.dub.downloadMissingMsg, 166行目: d.dub.downloadMissingUpgrade, 167行目: d.dub.downloadMissingAlways, 168行目: d.dub.downloadMissingNever |

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

```
delayedProjectActivation(...)  [727行目]
    │
    ├─ backend.attachEager(instance, "dub")  [796行目]
    │
    ├─ dub.validateConfiguration()  [803行目]
    │
    └─ dub.missingDependencies チェック  [804行目]
           │
           └─ switch(forceDownloadDependencies)
                  │
                  ├─ ask（デフォルト）
                  │      ├─ translate!("d.dub.downloadMissing*")
                  │      ├─ missingList構築（40文字制限）
                  │      └─ rpc.window.requestMessage(info, msg, [upgrade, always, never])
                  │             ├─ [Always] → coded/updateSetting + selectAndDownloadMissing()
                  │             ├─ [Never] → coded/updateSetting
                  │             └─ [Upgrade] → selectAndDownloadMissing()
                  │
                  ├─ always → selectAndDownloadMissing() + validateConfiguration()
                  │
                  └─ never → 何もしない
```

### データフロー図

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

dub.missingDependencies ──▶ delayedProjectActivation()     ダイアログ表示
config.d.forceDownload         │                            （window/showMessageRequest）
Dependencies                   ├─ メッセージ生成                    │
                               └─ ボタン構築               ユーザー選択
                                                                  │
                                                            ├─ dub upgrade実行
                                                            ├─ coded/updateSetting通知
                                                            └─ 何もしない
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| extension.d | `source/served/extension.d` | ソース | delayedProjectActivation関数内の依存関係ダウンロードダイアログ実装 |
| types.d | `source/served/types.d` | ソース | DubUpgradeAction列挙型、Configuration.D.forceDownloadDependencies |
| translate.d | `source/served/utils/translate.d` | ソース | 翻訳機能 |
| en.txt | `views/en.txt` | リソース | ダイアログメッセージ翻訳 |
