# 機能設計書 41-ALE連携

## 概要

本ドキュメントは、space-vimにおけるALE（Asynchronous Lint Engine）連携機能の設計仕様を定義する。ALEはVim8/NeoVimの非同期機能を活用したリアルタイム構文チェックエンジンであり、コーディング中にエラーや警告を即座にフィードバックする機能を提供する。

### 本機能の処理概要

本機能は、Vim8またはNeoVim環境において、非同期でソースコードの構文チェックを行い、リアルタイムでエラーおよび警告を表示する機能を提供する。

**業務上の目的・背景**：開発者がコードを記述している最中に、構文エラーやコーディング規約違反を即座に検出・表示することで、コードレビューの前段階でのバグ発見、コード品質の向上、開発効率の向上を実現する。従来の同期的なリンターと異なり、非同期処理によりエディタの応答性を損なわずにチェックを実行できる。

**機能の利用シーン**：
- ソースコード編集中のリアルタイム構文チェック
- ファイル保存時の自動コード整形（Fixer機能）
- エラー・警告箇所へのジャンプナビゲーション
- ステータスラインへのエラー・警告数の表示

**主要な処理内容**：
1. Vim8/NeoVim環境の検出とALEプラグインの遅延読み込み
2. リンター設定（エラー・警告の表示形式、検出タイミング）の適用
3. テキスト変更時およびInsertモード離脱時の非同期構文チェック実行
4. エラー・警告間のナビゲーションキーバインドの提供
5. ファイル保存時の自動Fixer実行

**関連システム・外部連携**：
- w0rp/ale プラグイン（コア機能）
- vim-airline/lightline（ステータスライン連携）
- 各言語のリンター（flake8, eslint, pyflakes等）

**権限による制御**：特になし（全ユーザー共通機能）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 10 | ALE/Syntastic（構文エラー表示） | 主画面 | 非同期リンターによるリアルタイム構文チェック結果の表示 |
| 14 | Airline（ステータスライン） | 結果表示画面 | ALEのエラー・警告情報のステータスライン表示 |

## 機能種別

バリデーション / リアルタイムチェック / コード整形

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:ale_set_highlights | Number | No | ハイライト表示の有効/無効 | 0または1 |
| g:ale_fix_on_save | Number | No | 保存時の自動修正 | 0または1 |
| g:ale_echo_msg_format | String | No | エラーメッセージのフォーマット | 文字列 |
| g:ale_statusline_format | List | No | ステータスライン表示フォーマット | 3要素のリスト |
| g:ale_lint_on_text_changed | String | No | テキスト変更時のチェックモード | 'normal'/'insert'/'always'/'never' |
| g:ale_lint_on_insert_leave | Number | No | Insertモード離脱時のチェック | 0または1 |
| g:ale_lint_delay | Number | No | チェック実行までの遅延（ms） | 正の整数 |
| g:ale_completion_delay | Number | No | 補完実行までの遅延（ms） | 正の整数 |
| g:ale_echo_delay | Number | No | エコー表示までの遅延（ms） | 正の整数 |

### 入力データソース

- 編集中のソースコードバッファ
- 言語別リンター設定（b:ale_linters）
- 言語別Fixer設定（b:ale_fixers）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| エラー表示 | Sign | サインカラムへのエラーマーク表示 |
| 警告表示 | Sign | サインカラムへの警告マーク表示 |
| エコーメッセージ | String | カーソル行のエラー・警告メッセージ |
| ステータスライン | String | エラー・警告の総数 |

### 出力先

- Vimのサインカラム（左端）
- コマンドライン（エコーエリア）
- ステータスライン（airline/lightline連携時）

## 処理フロー

### 処理シーケンス

```
1. space-vim起動時
   └─ g:spacevim.vim8 または g:spacevim.nvim の判定

2. ALE有効環境の場合（Vim8/NeoVim）
   └─ timer_start(200, 'spacevim#defer#ale') で遅延読み込みスケジュール

3. 200ms後にspacevim#defer#ale実行
   └─ plug#load('ale') でALEプラグイン読み込み

4. config.vim の設定適用
   └─ g:ale_* 変数群の設定

5. テキスト編集時（Normalモード）
   └─ g:ale_lint_delay(500ms)後に非同期リント実行

6. Insertモード離脱時
   └─ 即座に非同期リント実行

7. ファイル保存時
   └─ g:ale_fix_on_save=1 の場合、Fixer実行
```

### フローチャート

```mermaid
flowchart TD
    A[space-vim起動] --> B{Vim8/NeoVim?}
    B -->|Yes| C[timer_start 200ms]
    B -->|No| D[syntastic読み込み]
    C --> E[spacevim#defer#ale]
    E --> F[plug#load ale]
    F --> G[ALE設定適用]
    G --> H[テキスト編集]
    H --> I{テキスト変更?}
    I -->|Yes| J[500ms遅延]
    J --> K[非同期リント実行]
    K --> L[結果表示]
    I -->|No| M{Insert離脱?}
    M -->|Yes| K
    M -->|No| H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-41-01 | 環境判定ルール | Vim8またはNeoVim環境でのみALEを使用、それ以外はsyntasticを使用 | プラグイン読み込み時 |
| BR-41-02 | 遅延読み込みルール | 起動時間最適化のため200ms後にALEを読み込む | 起動時 |
| BR-41-03 | リント遅延ルール | テキスト変更後500msの遅延を設けてリントを実行 | テキスト変更時 |
| BR-41-04 | 保存時修正ルール | ファイル保存時に自動でFixerを実行する | g:ale_fix_on_save=1 |

### 計算ロジック

ステータスライン表示フォーマット：
- エラーあり: `E・{エラー数}`
- 警告あり: `W・{警告数}`
- 問題なし: `OK`

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | リンター未インストール | 言語別リンターが未インストール | 対応するリンターのインストール案内 |
| - | 設定エラー | 不正な設定値 | デフォルト値へのフォールバック |

### リトライ仕様

リンターエラー時のリトライは行わない（次回のテキスト変更時に再実行）。

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

該当なし（ファイルシステム操作のみ）。

## パフォーマンス要件

- リント実行は非同期で行い、エディタの応答性を維持する
- テキスト変更からリント開始までの遅延: 500ms（設定可能）
- エコーメッセージ表示までの遅延: 20ms

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

- 外部リンターの実行はローカル環境に限定
- リンター出力は信頼できるツールからのみ受け付ける

## 備考

- Vim8未満の環境ではsyntasticがフォールバックとして使用される
- g:spacevim.gui 環境ではエラー・警告文字列のUnicode記号を省略

---

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

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

### 推奨読解順序

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

ALE連携機能で使用される主要な設定変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.vim | `layers/+checkers/syntax-checking/config.vim` | ALE用のグローバル設定変数（g:ale_*）の定義 |

**読解のコツ**: Vimスクリプトのグローバル変数は `g:` プレフィックスで定義される。`let g:ale_xxx = value` の形式で設定が行われる。

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

プラグイン読み込みの起点を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | packages.vim | `layers/+checkers/syntax-checking/packages.vim` | 環境判定とプラグイン登録 |

**主要処理フロー**:
1. **1-2行目**: g:spacevim.vim8 または g:spacevim.nvim の判定
2. **2行目**: MP 'w0rp/ale' でプラグイン登録（遅延読み込み設定）
3. **3行目**: timer_start(200, 'spacevim#defer#ale') で遅延読み込みスケジュール
4. **5行目**: 非Vim8環境ではsyntasticを登録

#### Step 3: 遅延読み込み処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | defer.vim | `core/autoload/spacevim/defer.vim` | 遅延読み込み実装 |

**主要処理フロー**:
- **1-6行目**: s:lod() ヘルパー関数でplug#load()を安全に呼び出し
- **9-11行目**: spacevim#defer#ale() 関数でALEプラグインを読み込み

#### Step 4: ステータスライン連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ale.vim | `core/autoload/spacevim/plug/ale.vim` | ステータスライン用関数 |

**主要処理フロー**:
- **4-14行目**: spacevim#plug#ale#ALEGetError() - エラー数取得
- **16-28行目**: spacevim#plug#ale#ALEGetWarning() - 警告数取得

#### Step 5: 設定適用処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | config.vim | `layers/+checkers/syntax-checking/config.vim` | 詳細設定の適用 |

**主要処理フロー**:
- **5行目**: g:ale_set_highlights = 0 - ハイライト無効化
- **6行目**: g:ale_fix_on_save = 1 - 保存時自動修正有効
- **7行目**: g:ale_echo_msg_format - メッセージフォーマット設定
- **10-13行目**: サイン記号の設定
- **15-19行目**: タイミング関連設定
- **21-23行目**: キーマッピング定義

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

```
space-vim起動
    │
    ├─ layers/+checkers/syntax-checking/packages.vim
    │      ├─ MP 'w0rp/ale' (プラグイン登録)
    │      └─ timer_start(200, 'spacevim#defer#ale')
    │
    ├─ 200ms後
    │      └─ core/autoload/spacevim/defer.vim
    │             └─ spacevim#defer#ale()
    │                    └─ plug#load('ale')
    │
    ├─ layers/+checkers/syntax-checking/config.vim
    │      └─ g:ale_* 設定適用
    │
    └─ core/autoload/spacevim/plug/ale.vim
           ├─ spacevim#plug#ale#ALEGetError()
           └─ spacevim#plug#ale#ALEGetWarning()
```

### データフロー図

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

ソースコード ───────▶ ALEリンター実行 ───────▶ サインカラム表示
                           │
テキスト変更 ───────▶ 非同期チェック ────────▶ エコーメッセージ
                           │
ファイル保存 ───────▶ Fixer実行 ──────────▶ 整形済みコード
                           │
                      ale#statusline#Status()
                           │
                           ▼
                    ステータスライン表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+checkers/syntax-checking/packages.vim` | 設定 | プラグイン登録と環境判定 |
| config.vim | `layers/+checkers/syntax-checking/config.vim` | 設定 | ALE/syntasticの詳細設定 |
| defer.vim | `core/autoload/spacevim/defer.vim` | ソース | 遅延読み込み処理 |
| ale.vim | `core/autoload/spacevim/plug/ale.vim` | ソース | ステータスライン連携関数 |
| python.vim | `core/ftplugin/python.vim` | 設定 | Python用ALE設定 |
| javascript.vim | `core/ftplugin/javascript.vim` | 設定 | JavaScript用ALE設定 |
