# 機能設計書 76-ワークスペース機能 (serve-d:workspace-d)

## 概要

本ドキュメントは、serve-dのサブパッケージ `serve-d:workspace-d` の設計を記述する。D言語のコア機能（libdparse、dfmt、D-Scanner、DCD、DUB統合）を提供し、serve-dのセマンティック解析エンジンとして機能するサブパッケージである。

### 本機能の処理概要

**業務上の目的・背景**：D言語の開発支援に必要なコア機能群を統合的に提供するバックエンドレイヤーである。各種ツール（DCD、D-Scanner、dfmt、DUB等）との連携をコンポーネントベースのアーキテクチャで管理し、プロジェクトインスタンスごとに独立した解析環境を提供する。

**機能の利用シーン**：serve-dの全てのセマンティック解析機能（コード補完、静的解析、フォーマット、DUBビルド管理等）がこのサブパッケージのコンポーネントを通じて実行される。ワークスペースの追加・削除時にインスタンスが作成・破棄される。

**主要な処理内容**：
1. WorkspaceD / Backend：コンポーネントの登録・管理、ワークスペースインスタンスの作成・破棄
2. DCDComponent：DCDサーバーの起動・停止・通信管理
3. DubComponent：DUBプロジェクトの構成管理・ビルド・依存関係解決
4. DscannerComponent：D-Scannerによる静的解析の実行
5. DfmtComponent：dfmtによるコードフォーマット
6. IndexComponent：ソースコードのインデックス管理
7. SnippetsComponent：コードスニペットの管理
8. DCDExtComponent：DCD拡張機能（インターフェース実装、メソッド検索等）
9. その他コンポーネント（FSWorkspace、Importer、Moduleman、References等）

**関連システム・外部連携**：DCD、D-Scanner、dfmt、DUBの各外部ツールとの連携。libdparseによるD言語パース。

**権限による制御**：なし（バックエンドライブラリとして動作）

## 関連画面

本サブパッケージは直接的に画面と関連しない。serve-dの全LSP機能が間接的にコンポーネントを使用する。

## 機能種別

基盤ライブラリ / バックエンドエンジン

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| instance (WorkspaceD.Instance) | object | Yes | ワークスペースインスタンス（プロジェクトディレクトリごと） | 有効なパスであること |
| Configuration | struct | No | コンポーネント設定値の集合 | - |
| ImportPathProvider | delegate | No | インポートパスを返すデリゲート | - |

### 入力データソース

- serve-dの各LSP機能モジュールからの呼び出し
- ファイルシステム（プロジェクトファイル、ソースコード）
- DUBプロジェクト設定（dub.json、dub.sdl）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 各コンポーネントの出力 | 各種 | 補完候補、診断結果、フォーマット結果、シンボル情報等 |
| Future | class | 非同期処理の結果を表すFutureオブジェクト |

### 出力先

serve-dの各LSP機能モジュール

## 処理フロー

### 処理シーケンス

```
1. Backend初期化
   └─ グローバルコンポーネントの登録
2. ワークスペースインスタンス作成
   └─ プロジェクトディレクトリに対してInstanceを作成
3. コンポーネントバインド
   └─ インスタンスに必要なコンポーネント（DCD、DUB等）をバインド
4. 機能呼び出し
   └─ serve-dからコンポーネントのメソッドを呼び出し
5. インスタンス破棄
   └─ ワークスペース削除時にコンポーネントを停止・解放
```

### フローチャート

```mermaid
flowchart TD
    A[Backend初期化] --> B[グローバルコンポーネント登録]
    B --> C[ワークスペースフォルダ追加]
    C --> D[Instance作成]
    D --> E[コンポーネントバインド]
    E --> F{DUBプロジェクト?}
    F -->|Yes| G[DubComponent初期化]
    F -->|No| H[FSWorkspaceComponent初期化]
    G --> I[DCDComponent初期化]
    H --> I
    I --> J[サービス提供開始]
    J --> K{ワークスペース削除?}
    K -->|Yes| L[コンポーネント停止・Instance破棄]
    K -->|No| J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-76-01 | コンポーネントベース設計 | 各機能はComponentとして登録され、Instanceにバインドして使用する | 常時 |
| BR-76-02 | グローバル/インスタンス区別 | @globalOnlyコンポーネントはインスタンス非依存、@instancedOnlyはインスタンス必須 | コンポーネント登録時 |
| BR-76-03 | バインド失敗コールバック | コンポーネントのバインド失敗時にComponentBindFailCallbackが呼ばれる | コンポーネントバインド失敗時 |
| BR-76-04 | Future非同期処理 | 時間のかかる処理はFutureオブジェクトで非同期に実行 | 重い処理 |

### 計算ロジック

特になし。

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

本機能ではデータベース操作は行わない。プロジェクト設定やインデックスはインメモリで管理される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Exception | コンポーネントのバインドが失敗した場合 | ComponentBindFailCallbackを呼び出し、エラーをログ出力 |
| - | IMessageHandler.error | コンポーネント内でエラーが発生した場合 | IMessageHandlerを通じてエラーメッセージを通知 |
| - | handleCrash | コンポーネントがクラッシュした場合 | IMessageHandler.handleCrashを通じてクラッシュ情報を収集 |

### リトライ仕様

コンポーネントのバインド失敗時はリトライしない。ユーザーに通知して手動再試行を促す。

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

不要。

## パフォーマンス要件

- タスクプールベースの並列処理（std.parallelism.TaskPool使用）
- libdparseのStringCacheによるメモリ効率の最適化

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

外部ツール（DCD、D-Scanner、dfmt、DUB）の実行はローカルプロセスとして行われ、ネットワーク通信は伴わない。

## 備考

- workspace-dは元々serve-dとは独立した汎用D言語ワークスペースライブラリとして設計された
- コンポーネント一覧：DCD、DCDExt、DUB、DScanner、Dfmt、FSWorkspace、Importer、Index、Moduleman、References、Snippets、DMD、DlangUI、ClangCompilationDatabase
- coms.dモジュールが全コンポーネントのpublic importを提供

---

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

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

### 推奨読解順序

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

コンポーネントシステムの基本型を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | api.d | `workspace-d/source/workspaced/api.d` | ImportPathProvider、ComponentBindFailCallback、IMessageHandler等の基本型定義（32-48行目） |
| 1-2 | api.d | `workspace-d/source/workspaced/api.d` | ComponentInfoParams、ComponentInfo構造体（64-81行目） |
| 1-3 | backend.d | `workspace-d/source/workspaced/backend.d` | Configuration構造体（17-100行目）: コンポーネント設定値の管理 |

**読解のコツ**: D言語のUDA（`@globalOnly`、`@instancedOnly`等）がコンポーネントの性質を示す。`DefaultGlobalComponentWrapper`と`DefaultInstanceComponentWrapper`のmixin templateがコンポーネントの共通機能（WorkspaceDへのアクセス等）を提供する。

#### Step 2: バックエンド管理を理解する

WorkspaceD/Backendのインスタンス管理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | backend.d | `workspace-d/source/workspaced/backend.d` | WorkspaceDクラスの構造とインスタンス管理 |

#### Step 3: コンポーネント一覧を理解する

利用可能な全コンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | coms.d | `workspace-d/source/workspaced/coms.d` | 全コンポーネントのpublic import一覧（1-16行目） |

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

```
serve-d (extension.d)
    │
    └─ workspace-d (backend/api)
           │
           ├─ DCDComponent (com/dcd.d)
           │      └─ DCDクライアント通信
           │
           ├─ DubComponent (com/dub.d)
           │      └─ DUBプロジェクト管理
           │
           ├─ DscannerComponent (com/dscanner.d)
           │      └─ D-Scanner静的解析
           │
           ├─ DfmtComponent (com/dfmt.d)
           │      └─ dfmtフォーマット
           │
           ├─ DCDExtComponent (com/dcdext.d)
           │      └─ DCD拡張（インターフェース実装等）
           │
           ├─ IndexComponent (com/index.d)
           │      └─ ソースインデックス管理
           │
           ├─ SnippetsComponent (com/snippets/)
           │      └─ スニペット管理
           │
           ├─ FSWorkspaceComponent (com/fsworkspace.d)
           │      └─ ファイルシステムワークスペース
           │
           ├─ ImporterComponent (com/importer.d)
           │      └─ インポート管理
           │
           ├─ ModulemanComponent (com/moduleman.d)
           │      └─ モジュール管理
           │
           └─ ReferencesComponent (com/references.d)
                  └─ 参照検索
```

### データフロー図

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

ソースコード ────────────▶ DCDComponent ──────────▶ 補完候補・シンボル情報
DUBプロジェクト設定 ─────▶ DubComponent ──────────▶ ビルド設定・依存関係
ソースコード ────────────▶ DscannerComponent ────▶ 静的解析診断
ソースコード ────────────▶ DfmtComponent ─────────▶ フォーマット結果
ソースコード ────────────▶ IndexComponent ────────▶ シンボルインデックス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| api.d | `workspace-d/source/workspaced/api.d` | ソース | 基本型定義、コンポーネントAPI |
| backend.d | `workspace-d/source/workspaced/backend.d` | ソース | WorkspaceD/Backend、Configuration |
| coms.d | `workspace-d/source/workspaced/coms.d` | ソース | 全コンポーネントのpublic import |
| future.d | `workspace-d/source/workspaced/future.d` | ソース | Futureクラス（非同期処理） |
| helpers.d | `workspace-d/source/workspaced/helpers.d` | ソース | ヘルパーユーティリティ |
| dparseext.d | `workspace-d/source/workspaced/dparseext.d` | ソース | libdparse拡張 |
| index_format.d | `workspace-d/source/workspaced/index_format.d` | ソース | インデックスファイルフォーマット |
| com/dcd.d | `workspace-d/source/workspaced/com/dcd.d` | ソース | DCDコンポーネント |
| com/dub.d | `workspace-d/source/workspaced/com/dub.d` | ソース | DUBコンポーネント |
| com/dscanner.d | `workspace-d/source/workspaced/com/dscanner.d` | ソース | D-Scannerコンポーネント |
| com/dfmt.d | `workspace-d/source/workspaced/com/dfmt.d` | ソース | dfmtコンポーネント |
| com/dcdext.d | `workspace-d/source/workspaced/com/dcdext.d` | ソース | DCD拡張コンポーネント |
| com/index.d | `workspace-d/source/workspaced/com/index.d` | ソース | インデックスコンポーネント |
| com/snippets/ | `workspace-d/source/workspaced/com/snippets/` | ソース | スニペットコンポーネント |
