# 機能設計書 60-Docker統合

## 概要

本ドキュメントは、Doom Emacsの`tools/docker`モジュールが提供するDocker統合機能の設計仕様を記述する。Dockerfileの編集支援、Dockerコンテナ・イメージの管理インターフェース、LSP対応、Tree-sitter対応などを提供する。

### 本機能の処理概要

**業務上の目的・背景**：コンテナ技術は現代のソフトウェア開発・運用において標準的な技術となっている。Dockerfileの編集、コンテナ・イメージの管理をEmacs内で完結させることで、ターミナルとエディタ間の切り替えを減らし、開発効率を向上させる。

**機能の利用シーン**：
- Dockerfileの作成・編集
- Dockerコンテナの起動・停止・管理
- Dockerイメージの確認・削除
- docker-composeの操作
- TRAMP経由でのコンテナ内ファイル編集

**主要な処理内容**：
1. dockerfile-modeによるDockerfile編集支援
2. dockerfile-ts-mode（Tree-sitter版）による高度な構文解析
3. dockerパッケージによるコンテナ・イメージ管理UI
4. docker-tramp（Emacs 28以前）またはtramp-container（Emacs 29+）によるコンテナアクセス
5. LSP統合によるDockerfile補完・診断
6. dockfmtによるフォーマッタ統合

**関連システム・外部連携**：
- docker（CLIコマンド）
- dockerfile-mode（編集モード）
- dockerfile-ts-mode（Tree-sitter版）
- docker.el（管理UI）
- docker-tramp/tramp-container（TRAMP統合）
- LSP（言語サーバー）
- dockfmt（フォーマッタ）

**権限による制御**：Docker操作にはdockerコマンドの実行権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Dockerfileバッファ | 主画面 | Dockerfile編集、シンタックスハイライト |
| - | *docker-containers* | 補助画面 | コンテナ一覧・管理 |
| - | *docker-images* | 補助画面 | イメージ一覧・管理 |

## 機能種別

外部ツール連携 / 編集支援

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +lsp | flag | No | LSPサポートを有効化 | modulep!でチェック |
| +tree-sitter | flag | No | Tree-sitterサポートを有効化 | modulep!でチェック |

### 入力データソース

- Dockerfileのテキスト
- docker CLIの出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| シンタックスハイライト | face | Dockerfile構文の色分け |
| コンテナ一覧 | table | 実行中/停止中コンテナの一覧 |
| イメージ一覧 | table | ローカルイメージの一覧 |

### 出力先

- Dockerfileバッファ
- docker.elバッファ（コンテナ、イメージ等）

## 処理フロー

### 処理シーケンス

```
1. Dockerfileを開く
   └─ dockerfile-mode（または dockerfile-ts-mode）が有効化
2. 編集操作
   └─ シンタックスハイライト、LSP補完
3. フォーマット実行（オプション）
   └─ dockfmtによるフォーマット
4. docker管理（M-x docker）
   └─ コンテナ/イメージ一覧表示
5. 操作実行
   └─ docker CLIを呼び出し
```

### フローチャート

```mermaid
flowchart TD
    A[Dockerfileを開く] --> B{+tree-sitter?}
    B -->|Yes| C[dockerfile-ts-mode]
    B -->|No| D[dockerfile-mode]
    C --> E{+lsp?}
    D --> E
    E -->|Yes| F[lsp!有効化]
    E -->|No| G[通常編集]
    F --> G
    G --> H[編集操作]
    H --> I{フォーマット?}
    I -->|Yes| J[dockfmt]
    I -->|No| K{docker管理?}
    J --> K
    K -->|Yes| L[M-x docker]
    L --> M[コンテナ/イメージ操作]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-60-01 | DocSetsドキュメント | Dockerドキュメントをset-docsets!で設定 | 常時 |
| BR-60-02 | dockfmtフォーマッタ | dockfmtをset-formatter!で設定 | 常時 |
| BR-60-03 | Tree-sitter有効化 | +tree-sitterフラグでdockerfile-ts-modeを使用 | Emacs 29.1+ |
| BR-60-04 | TRAMP統合 | Emacs 29+ではtramp-container、28以前ではdocker-tramp | バージョンで分岐 |

### 計算ロジック

- Tree-sitter文法: `https://github.com/camdencheek/tree-sitter-dockerfile`

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | docker未インストール | dockerコマンドが見つからない | エラーメッセージ表示 |
| - | dockfmt未インストール | フォーマット時にdockfmtがない | 警告表示（doctor.el） |
| - | Tree-sitter非対応 | Emacs 29未満で+tree-sitter | assert!で警告 |

### リトライ仕様

リトライ処理は不要。

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

トランザクション処理は不要。

## パフォーマンス要件

- Dockerfile編集: 即時応答
- コンテナ/イメージ一覧: docker CLIのレスポンスに依存

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

- docker操作には適切な権限が必要
- TRAMP経由でのコンテナアクセスはセキュリティに注意

## 備考

- Emacs 29以降ではdocker-trampは不要（tramp-containerが組み込み）
- Tree-sitterはEmacs 29.1以上が必要

---

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

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

### 推奨読解順序

#### Step 1: dockerfile-mode設定を理解する

まず、dockerfile-modeの基本設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/tools/docker/config.el` | dockerfile-mode設定（3-8行目） |

**読解のコツ**: `after! dockerfile-mode`で遅延設定。

**主要処理フロー**:
1. **4行目**: `set-docsets!`でDockerドキュメントを設定
2. **5行目**: `set-formatter!`でdockfmtを設定
3. **7-8行目**: +lspフラグでLSPを有効化

#### Step 2: Tree-sitter設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/tools/docker/config.el` | Tree-sitter設定（11-17行目） |

**主要処理フロー**:
- **12行目**: +tree-sitterフラグでの条件分岐
- **15-17行目**: Tree-sitter文法の定義

#### Step 3: パッケージ依存を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | packages.el | `modules/tools/docker/packages.el` | パッケージ定義（1-9行目） |

**主要処理フロー**:
- **4行目**: dockerパッケージ
- **6-7行目**: Emacs 29未満でdocker-trampを使用
- **8行目**: dockerfile-modeパッケージ

#### Step 4: 診断ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | doctor.el | `modules/tools/docker/doctor.el` | 診断チェック（1-13行目） |

**主要処理フロー**:
- **3-5行目**: :tools tree-sitterモジュールの依存チェック
- **7-9行目**: Emacs 29.1+のチェック
- **11-13行目**: dockfmtの存在確認

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

```
Dockerfile開く
    │
    ├─ dockerfile-mode (または dockerfile-ts-mode)
    │      │
    │      ├─ set-docsets! "Docker"
    │      │
    │      ├─ set-formatter! 'dockfmt
    │      │
    │      └─ lsp! (+lspフラグ時)
    │
    └─ set-tree-sitter! (+tree-sitterフラグ時)
           │
           └─ dockerfile-ts-mode

M-x docker
    │
    ├─ docker-containers
    │
    ├─ docker-images
    │
    └─ docker-compose
```

### データフロー図

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

Dockerfile ───▶ dockerfile-mode ───▶ ハイライト表示
                      │
                      ▼
              LSP/Tree-sitter
                      │
                      ▼
              補完/診断

docker CLI ◀───────── docker.el ◀───── ユーザー操作
    │
    ▼
コンテナ/イメージ情報
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/tools/docker/config.el` | ソース | メイン設定 |
| packages.el | `modules/tools/docker/packages.el` | 設定 | 依存パッケージ定義 |
| doctor.el | `modules/tools/docker/doctor.el` | 診断 | 依存関係チェック |
