# 機能設計書 52-アクティブDUB設定取得

## 概要

本ドキュメントは、serve-dのLSPカスタムリクエスト `served/getActiveDubConfig` の機能設計を記述する。アクティブプロジェクトのDUBビルド設定詳細（パス・フラグ・依存関係等）を返却する機能である。

### 本機能の処理概要

**業務上の目的・背景**：D言語のDUBプロジェクトには、パッケージパス、ターゲットパス、コンパイラフラグ、リンカフラグ、インポートパスなど多数のビルド設定が存在する。本機能は、クライアントやツール連携がこれらの詳細なビルド設定情報をプログラム的に取得できるようにするために提供される。デバッガ設定の自動構成やビルドスクリプトの生成、他ツールとの連携時に必要となる。

**機能の利用シーン**：エディタ拡張がデバッグ構成を自動生成する場合や、外部ツールがDUBプロジェクトのインポートパスやソースファイル一覧を必要とする場合に使用される。

**主要な処理内容**：
1. クライアントから `served/getActiveDubConfig` リクエストを受信する
2. アクティブなDUBインスタンスの存在を確認する
3. DubComponentの `rootPackageBuildSettings()` メソッドでビルド設定を取得する
4. コンパイル時static assertによりAPIの型保証を検証する
5. 取得した設定をJsonValue形式に変換して返却する

**関連システム・外部連携**：workspace-dサブパッケージのDubComponentに処理を委譲する。返却されるデータにはDUBのビルドシステムが管理する広範な情報が含まれる。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 64 | アクティブDUB設定取得（served/getActiveDubConfig） | 主画面 | アクティブプロジェクトのDUBビルド設定詳細を返却する |

## 機能種別

データ取得処理（DUBビルド設定の詳細情報取得）

## 入力仕様

### 入力パラメータ

本リクエストにパラメータはない。

### 入力データソース

LSPクライアントからのJSON-RPCリクエスト（パラメータなし）。アクティブなワークスペースインスタンスのDubComponentから情報を取得する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| packagePath | string | パッケージのディレクトリパス |
| packageName | string | パッケージ名 |
| recipePath | string | DUBレシピファイル（dub.json/dub.sdl）のパス |
| targetPath | string | ビルドターゲットの出力ディレクトリパス |
| targetName | string | ビルドターゲット名 |
| targetType | string | ターゲットタイプ（executable, library等） |
| workingDirectory | string | 作業ディレクトリ |
| mainSourceFile | string | メインソースファイル |
| dflags | string[] | Dコンパイラフラグ |
| lflags | string[] | リンカフラグ |
| libs | string[] | リンクするライブラリ |
| linkerFiles | string[] | リンカに渡すファイル |
| sourceFiles | string[] | ソースファイル一覧 |
| copyFiles | string[] | コピー対象ファイル |
| versions | string[] | バージョン識別子 |
| debugVersions | string[] | デバッグバージョン識別子 |
| importPaths | string[] | インポートパス |
| stringImportPaths | string[] | 文字列インポートパス |
| importFiles | string[] | インポートファイル |
| stringImportFiles | string[] | 文字列インポートファイル |
| preGenerateCommands | string[] | 生成前コマンド |
| postGenerateCommands | string[] | 生成後コマンド |
| preBuildCommands | string[] | ビルド前コマンド |
| postBuildCommands | string[] | ビルド後コマンド |
| preRunCommands | string[] | 実行前コマンド |
| postRunCommands | string[] | 実行後コマンド |
| buildOptions | string[] | ビルドオプション |
| buildRequirements | string[] | ビルド要件 |

### 出力先

LSPクライアントへのJSON-RPCレスポンス（StringMap!JsonValue形式）

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ served/getActiveDubConfig（パラメータなし）
2. アクティブインスタンス確認
   └─ activeInstanceがnullまたはDubComponentを持たない場合は空のStringMap!JsonValueを返却
3. ビルド設定取得
   └─ DubComponent.rootPackageBuildSettings() を呼び出し
4. コンパイル時型保証チェック
   └─ static assertにより返却される型のフィールドが期待通りであることを検証
5. JSON変換・返却
   └─ ret.toJsonValue.get!(StringMap!JsonValue) でJSON形式に変換して返却
```

### フローチャート

```mermaid
flowchart TD
    A[served/getActiveDubConfig リクエスト受信] --> B{activeInstance が有効?}
    B -->|No| C[空の StringMap を返却]
    B -->|Yes| D{DubComponent を保持?}
    D -->|No| C
    D -->|Yes| E[rootPackageBuildSettings を呼出]
    E --> F[static assert で型保証検証]
    F --> G[toJsonValue で JSON 変換]
    G --> H[StringMap!JsonValue を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-52-01 | アクティブインスタンス必須 | アクティブなWorkspaceDインスタンスが存在しない場合は空のStringMapを返却する | 常時 |
| BR-52-02 | DubComponent必須 | アクティブインスタンスがDubComponentを保持していない場合は空のStringMapを返却する | 常時 |
| BR-52-03 | API型保証 | 返却されるビルド設定が最低限28個のフィールドを含むことをコンパイル時に保証する | コンパイル時 |

### 計算ロジック

特になし。DubComponentからの取得結果をそのままJSON変換して返却する。

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

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

本機能はデータベースを使用しない。DubComponentのインメモリ状態を参照する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 暗黙的空応答 | activeInstanceがnullの場合 | 空のStringMap!JsonValue.initを返却 |
| - | 暗黙的空応答 | DubComponentが存在しない場合 | 空のStringMap!JsonValue.initを返却 |

### リトライ仕様

リトライは不要。

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

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

## パフォーマンス要件

即時応答が期待される。DubComponentからの設定取得はインメモリ操作であり、大きな遅延は発生しない。

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

返却されるパス情報にはファイルシステムの絶対パスが含まれる。信頼されたクライアント間でのみ通信することが前提となる。

## 備考

- 返却されるフィールドはDDocコメント（132-164行目）に詳細に記載されている
- static assertによりコンパイル時にAPIの後方互換性が保証されている。フィールドの型が変更された場合はコンパイルエラーとなる
- 本機能で取得される情報は、現在の設定（コンパイラ、アーキテクチャ、ビルドタイプ等）に基づくものである

---

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

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

### 推奨読解順序

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

返却されるJSON構造のフィールドを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | dub.d | `source/served/commands/dub.d` | DDocコメント（132-164行目）で返却されるJSONオブジェクトのフィールド一覧を確認 |

**読解のコツ**: D言語の`///`はDDocコメントであり、関数のドキュメントとして使われる。ここでは返却されるJSONオブジェクトの構造が記述されている。

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

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

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

**主要処理フロー**:
1. **166行目**: `@protocolMethod("served/getActiveDubConfig")` - LSPメソッド登録
2. **167行目**: `StringMap!JsonValue getActiveDubConfig()` - パラメータなし、StringMap!JsonValue返却
3. **169-170行目**: activeInstanceとDubComponentの存在チェック。なければ`StringMap!JsonValue.init`返却
4. **171行目**: `activeInstance.get!DubComponent.rootPackageBuildSettings()` - ビルド設定取得
5. **172-199行目**: 28個のstatic assertによるコンパイル時型保証。フィールドの型がstring/string[]であることを検証
6. **201行目**: `ret.toJsonValue.get!(StringMap!JsonValue)` - JSON変換して返却

**読解のコツ**: `static assert(is(typeof(ret.packagePath) : string), ...)` はコンパイル時のみ実行される型チェックであり、ランタイムには影響しない。APIの後方互換性保証のための防御的プログラミング手法。

#### Step 3: 共通基盤を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | types.d | `source/served/types.d` | activeInstanceプロパティ（463-474行目）、backend定義（518行目） |

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

```
getActiveDubConfig() [source/served/commands/dub.d:167]
    |
    +-- activeInstance [source/served/types.d:471]
    |
    +-- activeInstance.has!DubComponent [workspace-d API]
    |
    +-- activeInstance.get!DubComponent [workspace-d API]
    |       |
    |       +-- DubComponent.rootPackageBuildSettings() [workspace-d内部]
    |
    +-- ret.toJsonValue [mir.serde変換]
    |       |
    |       +-- .get!(StringMap!JsonValue) [mir.algebraic]
    |
    +-- return StringMap!JsonValue
```

### データフロー図

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

(パラメータなし)    -->  getActiveDubConfig()                -->  StringMap!JsonValue
                          |                                        (packagePath, dflags,
                          +-- DubComponent                          importPaths 等
                          |     .rootPackageBuildSettings()          28フィールド)
                          +-- toJsonValue変換
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dub.d | `source/served/commands/dub.d` | ソース | getActiveDubConfig関数の実装（132-202行目） |
| types.d | `source/served/types.d` | ソース | activeInstanceプロパティ、backend定義 |
| extension.d | `source/served/extension.d` | ソース | LSPプロトコルメソッドのルーティング基盤 |
