# 機能設計書 63-コードフォーマット

## 概要

本ドキュメントは、space-vimにおけるコードフォーマット機能の設計について記載する。vim-autoformatプラグインによるソースコードの自動整形機能を提供する。

### 本機能の処理概要

コードフォーマット機能は、ソースコードを言語ごとの標準的なコーディングスタイルに自動整形する機能を提供する。インデント、空白、改行などを統一されたルールに従って自動的に修正する。

**業務上の目的・背景**：チーム開発において、コードスタイルの統一は可読性向上とコードレビュー効率化に不可欠である。手動でフォーマットを調整することは時間がかかり、ヒューマンエラーも発生しやすい。自動フォーマット機能により、一貫したコードスタイルを効率的に維持でき、開発者はロジックに集中できる。

**機能の利用シーン**：
- ファイル保存前にコード全体を整形する場合
- 外部から取得したコードを自社のスタイルに統一する場合
- コードレビュー前にフォーマットを確認・修正する場合
- 手動編集後のインデント崩れを修正する場合

**主要な処理内容**：
1. `:Autoformat` コマンドでバッファ全体をフォーマット
2. `<LocalLeader>=` キーマッピングでフォーマット実行
3. 言語ごとに適切なフォーマッターを自動選択
4. 外部フォーマッターツールとの連携

**関連システム・外部連携**：
- Chiel92/vim-autoformatプラグインにより機能が提供される
- 言語ごとの外部フォーマッター（clang-format, prettier, black, gofmt等）と連携
- space-vimの+programming/formattingレイヤーの一部として提供

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | テキストエディタ全般 | 主画面 | 編集中のソースコードに対してフォーマットを実行 |

## 機能種別

コード変換処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| filetype | String | Yes（自動） | 現在のバッファのファイルタイプ | サポートされるファイルタイプであること |

### 入力データソース

編集中のバッファ（ソースコード）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| フォーマット済みコード | String | 整形されたソースコード |

### 出力先

編集中のバッファ（上書き）

## 処理フロー

### 処理シーケンス

```
1. Autoformatコマンド実行
   └─ :Autoformat または <LocalLeader>=

2. ファイルタイプの検出
   └─ &filetypeから現在の言語を取得

3. フォーマッターの選択
   └─ 言語に対応したフォーマッターを検索
   └─ インストール済みのフォーマッターを優先

4. バッファ内容を外部フォーマッターに渡す
   └─ 標準入力経由でコードを送信

5. フォーマット結果をバッファに反映
   └─ バッファ全体を置換

6. カーソル位置の復元
   └─ 可能な限り元の位置に復元
```

### フローチャート

```mermaid
flowchart TD
    A[Autoformatコマンド実行] --> B[ファイルタイプ検出]
    B --> C{対応フォーマッターあり?}
    C -->|Yes| D[フォーマッター選択]
    C -->|No| E[エラーメッセージ表示]
    D --> F{外部ツール利用可能?}
    F -->|Yes| G[外部フォーマッター実行]
    F -->|No| H[Vim内蔵フォーマット]
    G --> I[結果をバッファに反映]
    H --> I
    I --> J[カーソル位置復元]
    J --> K[完了]
    E --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 言語別フォーマッター | 各言語に適したフォーマッターを使用（C++: clang-format, Python: black等） | 対応する言語のファイル編集時 |
| BR-02 | フォールバック | 外部フォーマッターがない場合はVim内蔵の整形を使用 | 外部ツール未インストール時 |
| BR-03 | 設定ファイル考慮 | プロジェクトルートの設定ファイル（.clang-format等）を参照 | 設定ファイルが存在する場合 |

### 計算ロジック

特になし（外部フォーマッターに処理を委譲）

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

該当なし（ファイルバッファ操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | フォーマッター未対応 | 現在のファイルタイプに対応するフォーマッターがない | 警告メッセージを表示 |
| - | 外部ツール未インストール | 指定されたフォーマッターがシステムにない | 代替フォーマッターを使用またはエラー表示 |
| - | 構文エラー | ソースコードに構文エラーがある | フォーマットを中止し、エラー位置を表示 |

### リトライ仕様

特になし（undo/redoで操作の取り消し・再実行が可能）

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

Vimのundo履歴に1操作として記録される。`u`コマンドで元に戻すことが可能。

## パフォーマンス要件

- 通常のソースファイル（数千行程度）では1秒以内に完了
- 大規模ファイルでは外部フォーマッターの性能に依存

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

外部フォーマッターは信頼できるソースからインストールすること

## 備考

- vim-autoformatは遅延ロードで設定されている（`{ 'on': 'Autoformat' }`）
- 言語固有のフォーマッターは別途インストールが必要
- EditorConfigとの連携も可能

---

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

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

### 推奨読解順序

#### Step 1: プラグイン登録を理解する

vim-autoformatプラグインがどのように登録されているかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+programming/formatting/packages.vim` | vim-autoformatの登録と遅延ロード設定を確認 |

**読解のコツ**: `{ 'on': 'Autoformat' }`オプションにより、`:Autoformat`コマンド実行時に初めてプラグインがロードされる（遅延ロード）。

**主要処理フロー**:
1. **1行目**: `MP 'Chiel92/vim-autoformat', { 'on': 'Autoformat' }` で遅延ロード登録

#### Step 2: キーバインディング設定を理解する

フォーマット実行のキーマッピングを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.vim | `layers/+programming/formatting/config.vim` | キーマッピングの設定を確認 |

**主要処理フロー**:
- **1行目**: `nnoremap <LocalLeader>= :Autoformat<CR>` - LocalLeader（デフォルトはカンマ）と=でフォーマット実行

#### Step 3: レイヤーマニフェストを確認する

レイヤー全体の構成を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | LAYERS.md | `layers/LAYERS.md` | formattingレイヤーに含まれるプラグイン一覧を確認 |

**主要処理フロー**:
- **45行目**: formattingレイヤーにvim-autoformatが含まれることを確認

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

```
space-vim起動
    │
    └─ spacevim#bootstrap()
           │
           └─ +programming/formatting レイヤー読み込み
                  │
                  ├─ packages.vim
                  │      └─ MP 'Chiel92/vim-autoformat' (遅延ロード)
                  │
                  └─ config.vim
                         └─ <LocalLeader>= キーマッピング

:Autoformat 実行時
    │
    └─ vim-plug による遅延ロード
           │
           └─ vim-autoformat 初期化
                  │
                  └─ Autoformat コマンド実行
                         │
                         ├─ ファイルタイプ検出
                         │
                         ├─ フォーマッター選択
                         │
                         └─ 外部ツール実行
                                │
                                └─ バッファ更新
```

### データフロー図

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

現在のバッファ           vim-autoformat                 フォーマット済み
（ソースコード）   ───▶  プラグイン処理    ───▶         ソースコード
    +
ファイルタイプ                   │
                                 ▼
                         外部フォーマッター
                         (clang-format,
                          prettier, black等)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+programming/formatting/packages.vim` | 設定 | プラグイン登録 |
| config.vim | `layers/+programming/formatting/config.vim` | 設定 | キーマッピング設定 |
| LAYERS.md | `layers/LAYERS.md` | ドキュメント | レイヤー一覧 |
| vim-autoformat | 外部プラグイン（Chiel92/vim-autoformat） | プラグイン | 機能本体 |
