# 機能設計書 56-ビルドタスク提供

## 概要

本ドキュメントは、serve-dのLSPカスタムリクエスト `served/buildTasks` の機能設計を記述する。全DUBインスタンスのビルドタスク（Run・Test・Build・Rebuild）を返却する機能である。

### 本機能の処理概要

**業務上の目的・背景**：D言語の開発ではDUBパッケージマネージャを使用してビルド・テスト・実行を行う。本機能は、エディタのタスクランナー機能と連携して、各DUBプロジェクトに対するRun・Test・Build・Rebuildの4種類のビルドタスクを自動生成する。これにより、開発者はエディタからコマンドラインを直接操作せずにビルド操作を実行できる。

**機能の利用シーン**：エディタのタスク一覧表示時や「タスクの実行」コマンド発行時に呼び出され、利用可能なDUBビルドタスクの一覧を提供する。

**主要な処理内容**：
1. クライアントから `served/buildTasks` リクエストを受信する
2. 全バックエンドインスタンスを走査する
3. 各インスタンスのDubComponentからビルド設定（コンパイラ、アーキテクチャ、ビルドタイプ、設定名）を取得する
4. Run・Test・Build・Rebuildの4種類のタスク定義を生成する
5. Task配列として返却する

**関連システム・外部連携**：workspace-dサブパッケージのDubComponentから各種ビルド設定を取得する。生成されるタスクのexecフィールドにはDUBコマンドラインが設定される。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 56 | ビルドタスク取得（served/buildTasks） | 主画面 | 全DUBインスタンスのビルドタスクを返却する |

## 機能種別

データ生成処理（DUBビルドタスク定義の動的生成）

## 入力仕様

### 入力パラメータ

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

### 入力データソース

LSPクライアントからのJSON-RPCリクエスト（パラメータなし）。全バックエンドインスタンスのDubComponentから情報を取得する。

## 出力仕様

### 出力データ

Task構造体の配列。各タスクは以下のフィールドを持つ。

| 項目名 | 型 | 説明 |
|--------|-----|------|
| source | string | タスクソース（常に"dub"） |
| definition | JsonValue | タスク定義（type, run, test, force, compiler, archType, buildType, configuration, cwd） |
| group | Task.Group | タスクグループ（build / test / rebuild） |
| exec | string[] | 実行コマンド配列（DUBコマンドライン） |
| scope_ | string | ワークスペースフォルダURI |
| name | string | タスク名（"Run {name}", "Test {name}", "Build {name}", "Rebuild {name}"） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ served/buildTasks（パラメータなし）
2. 全インスタンス走査
   └─ backend.instances を foreach で走査
3. 各インスタンスの処理
   ├─ DubComponentの存在確認（なければスキップ）
   ├─ ビルド可能性の確認（isValidBuildConfigurationがfalseならスキップ）
   ├─ 現在のビルド設定（compiler, archType, buildType, configuration）を取得
   └─ 4種類のタスクを生成
       ├─ Run タスク（dub run コマンド、group=build）
       ├─ Test タスク（dub test コマンド、group=test）
       ├─ Build タスク（dub build コマンド、group=build）
       └─ Rebuild タスク（dub build --force コマンド、group=rebuild）
4. 結果返却
   └─ Task配列として返却
```

### フローチャート

```mermaid
flowchart TD
    A[served/buildTasks リクエスト受信] --> B[backend.instances を走査]
    B --> C{DubComponent あり?}
    C -->|No| D[次のインスタンスへ]
    C -->|Yes| E{isValidBuildConfiguration?}
    E -->|No| F[スキップ]
    E -->|Yes| G[ビルド設定を取得]
    G --> H[Run タスク生成]
    H --> I[Test タスク生成]
    I --> J[Build タスク生成]
    J --> K[Rebuild タスク生成]
    K --> D
    D --> L{全インスタンス処理済?}
    L -->|No| C
    L -->|Yes| M[Task 配列を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-56-01 | 全インスタンス走査 | 特定のアクティブインスタンスだけでなく、全バックエンドインスタンスを走査する | 常時 |
| BR-56-02 | ビルド可能性チェック | isValidBuildConfigurationがfalseのプロジェクトはスキップする | 常時 |
| BR-56-03 | 空引数除去 | fixEmptyArgsにより末尾が`=`の引数（例: `-a=`）を除去する | コマンドライン生成時 |
| BR-56-04 | $currentマジック値 | useBuildTaskDollarCurrentがtrueの場合、ビルド設定値の代わりに`$current`を使用する | useBuildTaskDollarCurrent設定時 |
| BR-56-05 | cwdのワークスペース相対化 | cwdをrecipePathの親ディレクトリとし、ワークスペースフォルダパスを`${workspaceFolder}`に置換する | 常時 |

### 計算ロジック

特になし。DubComponentからの設定値をタスク定義にマッピングする。

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

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | スキップ | DubComponentが存在しないインスタンス | タスク生成をスキップし次のインスタンスへ |
| - | スキップ | ビルド不可能な設定のプロジェクト | タスク生成をスキップし次のインスタンスへ |

### リトライ仕様

リトライは不要。

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

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

## パフォーマンス要件

即時応答が期待される。全インスタンスの走査はインメモリ操作である。

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

exec配列にDUBコマンドラインが含まれる。クライアント側でこのコマンドを実行する場合のセキュリティはクライアント側の責任となる。

## 備考

- 4種類のタスクはそれぞれ異なるDUBサブコマンドを使用する: run, test, build, build --force
- グローバル変数 `useBuildTaskDollarCurrent` により、タスク定義内のビルド設定値をプレースホルダに置き換えることができる
- fixEmptyArgs関数は、空の設定値（例: アーキテクチャ未指定時の `-a=`）を除去する防御的処理
- recipePath.dirNameでDUBレシピファイルのディレクトリを作業ディレクトリとして使用する

---

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

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

### 推奨読解順序

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

Task構造体の定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protoext.d | `source/served/lsp/protoext.d` | Task構造体（125-153行目）の全フィールド。特にGroup列挙型（build/test/rebuild/clean）の定義 |

**読解のコツ**: `@serdeEnumProxy!string enum Group` はD言語のUDA（User-Defined Attribute）で、シリアライズ時に列挙値をstring型として扱う指定。

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

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

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

**主要処理フロー**:
1. **389行目**: `useBuildTaskDollarCurrent` グローバル変数の定義
2. **390行目**: `@protocolMethod("served/buildTasks")` - LSPメソッド登録
3. **394行目**: `foreach (instance; backend.instances)` - 全インスタンス走査
4. **396-397行目**: DubComponentの存在チェック
5. **402-406行目**: isValidBuildConfigurationチェック
6. **412-418行目**: currentValue テンプレート関数（$current または実際の値を返す）
7. **420行目**: cwdの計算（recipePath.dirNameをワークスペース相対に変換）
8. **421-441行目**: Runタスク生成
9. **442-462行目**: Testタスク生成
10. **463-483行目**: Buildタスク生成
11. **484-506行目**: Rebuildタスク生成

#### Step 3: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | dub.d | `source/served/commands/dub.d` | fixEmptyArgs関数（384-387行目）。末尾が`=`の引数を除去する |

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

```
provideBuildTasks() [source/served/commands/dub.d:391]
    |
    +-- backend.instances [全WorkspaceDインスタンスの走査]
    |       |
    |       +-- instance.has!DubComponent [存在チェック]
    |       +-- instance.get!DubComponent [DUB情報取得]
    |              +-- recipePath [レシピファイルパス]
    |              +-- isValidBuildConfiguration [ビルド可能性]
    |              +-- compiler, archType, buildType, configuration [現在の設定]
    |              +-- name [パッケージ名]
    |
    +-- workspace(...) [ワークスペース情報取得]
    |       +-- config.d.dubPath [DUBコマンドパス]
    |
    +-- fixEmptyArgs(...) [空引数除去]
    |
    +-- return Task[]
```

### データフロー図

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

(パラメータなし) -->  provideBuildTasks()                       -->  Task[]
                       |                                             (4タスク x Nインスタンス)
                       +-- 全インスタンス走査                         Run: dub run ...
                       +-- DubComponentからビルド設定取得              Test: dub test ...
                       +-- 4種タスク生成 (Run/Test/Build/Rebuild)    Build: dub build ...
                       +-- fixEmptyArgs で空引数除去                  Rebuild: dub build --force ...
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dub.d | `source/served/commands/dub.d` | ソース | provideBuildTasks関数（390-509行目）、fixEmptyArgs関数（384-387行目） |
| protoext.d | `source/served/lsp/protoext.d` | ソース | Task構造体定義（125-153行目） |
| types.d | `source/served/types.d` | ソース | backend定義、workspace関数、Configuration.D.dubPath |
| extension.d | `source/served/extension.d` | ソース | LSPプロトコルメソッドのルーティング基盤 |
