# 帳票設計書 8-ビルドタスク一覧

## 概要

本ドキュメントは、serve-dのビルドタスク一覧機能の設計を記述する。DUBプロジェクトのビルドタスク（Run、Build、Test、Rebuild）を一覧として出力する帳票である。

### 本帳票の処理概要

ビルドタスク一覧は、ワークスペース内の全DUBプロジェクトについて、実行可能なビルドタスク（Run、Build、Test、Rebuild）の一覧を生成し、各タスクの実行コマンドやコンパイラ設定を含む詳細情報を提供する帳票である。

**業務上の目的・背景**：D言語開発者がエディタ内からDUBプロジェクトのビルド・テスト・実行を行えるようにする。エディタのタスク機能と統合することで、コマンドラインに切り替えることなくビルド操作を完了でき、開発ワークフローの効率化を図る。

**帳票の利用シーン**：エディタのタスクリストを開いた際に、各DUBプロジェクトのビルドタスクが一覧表示される。開発者はリストからタスクを選択して実行できる。現在のコンパイラ設定、アーキテクチャ、ビルドタイプが反映されたコマンドが生成される。

**主要な出力内容**：
1. タスク名（"Run {name}", "Build {name}", "Test {name}", "Rebuild {name}"）
2. タスク定義（type, run, test, force, compiler, archType, buildType, configuration, cwd）
3. 実行コマンド配列（dub run/build/test + コンパイラフラグ）
4. タスクグループ（build / test / rebuild）
5. タスクスコープ（ワークスペースフォルダURI）

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

**帳票の利用者**：D言語開発者（エディタのタスク機能を使用する開発者）

## 帳票種別

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

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | タスクリスト | `served/buildTasks` | タスク一覧リクエスト時 |

## 出力形式

### 基本仕様

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

### PDF固有設定

N/A

### Excel固有設定

N/A

## 帳票レイアウト

### レイアウト概要

Task構造体の配列として、DUBプロジェクトごとに4種類のタスクを出力する。

```
┌─────────────────────────────────────────────┐
│  Task[]                                      │
├─────────────────────────────────────────────┤
│  [0] Run {projectName}                       │
│    source: "dub"                             │
│    definition: {type, run:true, ...}         │
│    exec: ["dub", "run", "--compiler=...", ...]│
│    group: build                              │
│  [1] Test {projectName}                      │
│    exec: ["dub", "test", "--compiler=...", ...]│
│    group: test                               │
│  [2] Build {projectName}                     │
│    exec: ["dub", "build", "--compiler=...", ...]│
│    group: build                              │
│  [3] Rebuild {projectName}                   │
│    exec: ["dub", "build", "--force", ...]    │
│    group: rebuild                            │
└─────────────────────────────────────────────┘
```

### ヘッダー部

N/A（リクエストにパラメータなし）

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | name | タスク名 | "Run/Build/Test/Rebuild " + dub.name | 文字列 | - |
| 2 | source | タスクソース | 固定値 "dub" | 文字列 | - |
| 3 | definition | タスク定義JSON | type, run, test, force, compiler, archType, buildType, configuration, cwd | JsonValue | - |
| 4 | exec | 実行コマンド配列 | dubPath + "run"/"build"/"test" + コンパイラフラグ | string[] | - |
| 5 | group | タスクグループ | build / test / rebuild | Task.Group列挙 | - |
| 6 | scope_ | タスクスコープ | workspace.folder.uri | URI文字列 | - |

### フッター部

N/A

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| DUBコンポーネント有効 | instance.has!DubComponentがtrue | Yes |
| 有効なビルド構成 | dub.isValidBuildConfigurationがtrue | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | backendインスタンスの登録順 | 昇順 |
| 2 | タスク種別順（Run, Test, Build, Rebuild） | 固定順 |

### 改ページ条件

N/A

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

### 参照テーブル一覧

本帳票はデータベースを使用しない。

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

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

N/A

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| cwd | dub.recipePath.dirName.replace(workspaceRoot, "${workspaceFolder}") | - | 行420 |
| exec | dubPath + サブコマンド + "--compiler=" + "-a=" + "-b=" + "-c=" | - | fixEmptyArgsで空引数除去 |
| definition.compiler | useBuildTaskDollarCurrent ? "$current" : dub.compiler | - | 行408-418 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[served/buildTasksリクエスト受信] --> B[全backendインスタンスをループ]
    B --> C{DubComponent有効?}
    C -->|No| B
    C -->|Yes| D{isValidBuildConfiguration?}
    D -->|No| E[スキップ]
    D -->|Yes| F[Runタスク生成]
    F --> G[Testタスク生成]
    G --> H[Buildタスク生成]
    H --> I[Rebuildタスク生成]
    I --> B
    E --> B
    B --> J[Task配列返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| DUB未設定 | DubComponentが利用不可 | なし | 該当インスタンスをスキップ |
| 無効なビルド構成 | isValidBuildConfigurationがfalse | infoログ: "not a buildable project, skipping" | 該当インスタンスをスキップ |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | インスタンス数 x 4タスク |
| 目標出力時間 | DUBコンポーネントのプロパティ参照のみで即時応答 |
| 同時出力数上限 | 制限なし |

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

- 生成されるexecコマンドはDUBツールのパスとビルド設定から構成される
- dubPathはconfig.d.dubPath.userPathから取得され、ユーザー設定に依存する

## 備考

- useBuildTaskDollarCurrentフラグ（行389）がtrueの場合、definition内のcompiler等の値が"$current"に設定される
- fixEmptyArgs関数（行384-387）で末尾が'='の引数（値なしフラグ）を除去
- cwdはrecipePathのディレクトリをワークスペースルートからの相対パスに変換（${workspaceFolder}使用）
- 4種類のタスク: Run（run:true）、Test（test:true）、Build（run:false）、Rebuild（run:false, force:true）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protoext.d | `source/served/lsp/protoext.d` | Task構造体（行125-153）: Group列挙（clean/build/rebuild/test）、definition、exec、name等 |

**読解のコツ**: Task.Group列挙は@serdeEnumProxy!stringで文字列としてシリアライズされる。

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

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

**主要処理フロー**:
1. **行394**: 全backendインスタンスをループ
2. **行396-397**: DubComponent有効性チェック
3. **行402-406**: isValidBuildConfiguration確認
4. **行408-418**: dollarMagicValueとcurrentValueの設定
5. **行420**: cwdの計算（recipePath基準、${workspaceFolder}置換）
6. **行421-441**: Runタスク生成
7. **行442-462**: Testタスク生成
8. **行463-483**: Buildタスク生成
9. **行484-506**: Rebuildタスク生成

#### Step 3: 補助関数を理解する

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

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

```
provideBuildTasks()                               [dub.d:390]
    |
    +-- [foreach instance in backend.instances]
            +-- instance.has!DubComponent           [dub.d:396]
            +-- instance.get!DubComponent           [dub.d:398]
            +-- dub.isValidBuildConfiguration       [dub.d:402]
            +-- dub.recipePath                      [dub.d:400]
            +-- workspace(instance.cwd.uriFromFile) [dub.d:399]
            +-- [Run] Task生成                      [dub.d:421-441]
            |       +-- fixEmptyArgs()              [dub.d:437]
            +-- [Test] Task生成                     [dub.d:442-462]
            |       +-- fixEmptyArgs()
            +-- [Build] Task生成                    [dub.d:463-483]
            |       +-- fixEmptyArgs()
            +-- [Rebuild] Task生成                  [dub.d:484-506]
                    +-- fixEmptyArgs()
```

### データフロー図

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

DUBインスタンス一覧 ────────> provideBuildTasks()        ──> Task[]
(backend.instances)

DubComponent設定 ───────────> compiler/archType/          ──> Task.definition (JSON)
(compiler, archType,          buildType/configuration         Task.exec (string[])
 buildType, configuration)    の取得

workspace.config.d.dubPath ──> exec配列の先頭要素         ──> DUBツールパス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dub.d | `source/served/commands/dub.d` | ソース | ビルドタスク一覧の主処理（provideBuildTasks） |
| protoext.d | `source/served/lsp/protoext.d` | ソース | Task構造体定義 |
| types.d | `source/served/types.d` | ソース | 共通型定義、Configuration構造体 |
| extension.d | `source/served/extension.d` | ソース | LSPサーバー拡張機能 |
