# 機能設計書 61-EditorConfig統合

## 概要

本ドキュメントは、Doom EmacsにおけるEditorConfig統合モジュールの機能設計を記述する。EditorConfigはプロジェクト固有のコーディングスタイル設定を定義するための標準規格であり、本モジュールはその設定をEmacsに適用する機能を提供する。

### 本機能の処理概要

EditorConfig統合モジュールは、プロジェクトディレクトリに配置された`.editorconfig`ファイルを読み込み、その設定に基づいてEmacsのインデント、文字コード、改行コードなどのエディタ設定を自動的に適用する機能を提供する。

**業務上の目的・背景**：
ソフトウェア開発において、チーム間でコーディングスタイルを統一することは重要である。異なるエディタを使用する開発者が混在するプロジェクトでも、EditorConfigを使用することで一貫したコードスタイルを維持できる。本モジュールにより、Doom Emacsユーザーは他のエディタユーザーと同様にEditorConfig設定を自動的に適用でき、コードレビュー時のスタイル差異による混乱を防止できる。

**機能の利用シーン**：
- 新規プロジェクトへの参加時、プロジェクト固有のインデント設定が自動適用される
- 複数プロジェクトを並行して開発する際、バッファ切り替え時に各プロジェクトの設定が自動反映される
- Python（インデント4スペース）とJavaScript（インデント2スペース）のような異なるスタイルのプロジェクトを同時に作業する場合

**主要な処理内容**：
1. バッファオープン時に`.editorconfig`ファイルを検索・パース
2. indent_style（タブ/スペース）、indent_size（インデント幅）の適用
3. end_of_line（改行コード）、charset（文字コード）の適用
4. trim_trailing_whitespace（末尾空白削除）の設定
5. insert_final_newline（最終行改行）の設定
6. 特定ファイル形式（ZIP、Office形式）の除外処理

**関連システム・外部連携**：
- editorconfig-emacs：EditorConfigのEmacs実装パッケージ
- ws-butler-mode：空白トリミング機能との連携（:editor whitespace +trim）
- dtrt-indent：インデント自動検出との連携（:editor whitespace +guess）

**権限による制御**：
本機能に権限による制御は存在しない。全てのユーザーがEditorConfig設定を利用可能。

## 関連画面

本機能は画面を持たないバックグラウンド機能である。設定はファイル編集時に自動的に適用される。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | ファイル編集時に自動適用 |

## 機能種別

設定適用処理 / フック連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| props | hash-table | Yes | EditorConfigから取得したプロパティ群 | キーはシンボル、値は文字列 |
| indent_style | string | No | "tab" または "space" | 有効値のみ受け入れ |
| indent_size | string | No | 数値文字列（例："2", "4"） | 正の整数 |
| tab_width | string | No | タブ幅の数値文字列 | 正の整数 |
| end_of_line | string | No | "lf", "cr", "crlf" | 有効値のみ |
| charset | string | No | "utf-8", "latin1", etc. | 有効なエンコーディング |

### 入力データソース

- `.editorconfig`ファイル（プロジェクトルートまたは親ディレクトリ）
- `editorconfig-get-properties`関数によるプロパティ取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| tab-width | integer | バッファローカルのタブ幅 |
| indent-tabs-mode | boolean | タブ/スペースの選択 |
| buffer-file-coding-system | symbol | ファイルの文字コード |

### 出力先

- バッファローカル変数への設定適用
- モードラインへの反映（間接的）

## 処理フロー

### 処理シーケンス

```
1. doom-first-buffer フック発火
   └─ editorconfig-mode の有効化

2. ファイルオープン時
   └─ editorconfig-after-apply-functions フック発火

3. EditorConfig プロパティ適用
   ├─ +editorconfig-disable-indent-detection-h
   │   └─ dtrt-indent の抑制判定
   └─ +editorconfig-unset-tab-width-in-org-mode-h
       └─ org-mode での tab-width 保護

4. 除外パターンチェック
   └─ ZIP/Office ファイルの除外
```

### フローチャート

```mermaid
flowchart TD
    A[ファイルオープン] --> B{EditorConfigモード有効?}
    B -->|No| Z[通常処理]
    B -->|Yes| C{除外パターンに該当?}
    C -->|Yes| Z
    C -->|No| D[.editorconfigを検索]
    D --> E{設定ファイル存在?}
    E -->|No| Z
    E -->|Yes| F[プロパティ読み込み]
    F --> G[インデント設定適用]
    G --> H[文字コード設定適用]
    H --> I[空白処理設定適用]
    I --> J{org-mode?}
    J -->|Yes| K[tab-width=8を強制]
    J -->|No| L[設定完了]
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | インデント検出抑制 | EditorConfigでインデント設定が明示されている場合、dtrt-indentによる自動検出を抑制 | indent_style または indent_size が指定されている場合 |
| BR-02 | org-mode タブ幅固定 | org-modeではtab-widthを8に固定（org-modeの仕様要件） | derived-mode-p が org-mode の場合 |
| BR-03 | アーカイブファイル除外 | ZIP形式およびOffice形式ファイルはEditorConfig適用対象外 | ファイル拡張子が .zip, .docx, .xlsx, .pptx の場合 |

### 計算ロジック

特になし。

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 設定ファイル不在 | .editorconfigが見つからない | デフォルト設定を使用、警告なし |
| - | パース失敗 | 不正な.editorconfigフォーマット | エラーログ出力、デフォルト設定使用 |

### リトライ仕様

リトライは行わない。設定ファイルの読み込みに失敗した場合はデフォルト設定を使用する。

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

該当なし。

## パフォーマンス要件

- ファイルオープン時の処理遅延は100ms以下を目標
- .editorconfigファイルの検索はキャッシュを活用

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

- .editorconfigファイルは信頼できるソースからのみ読み込むこと
- 悪意のある設定による意図しない動作（例：極端なインデント値）への対策はupstreamパッケージに依存

## 備考

- Emacs 30以降では組み込みのeditorconfig機能が提供される予定であり、将来的な移行を検討中（config.el内のTODOコメント参照）

---

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

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

### 推奨読解順序

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

EditorConfigのプロパティはハッシュテーブル形式で管理される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/tools/editorconfig/config.el` | editorconfig-after-apply-functions で渡される props ハッシュテーブルの構造を理解 |

**読解のコツ**: `gethash` 関数でプロパティを取得する Emacs Lisp のパターンを把握すること。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/tools/editorconfig/config.el` | use-package! マクロによる editorconfig パッケージの設定 |

**主要処理フロー**:
1. **6-7行目**: `doom-first-buffer` フックで editorconfig-mode を有効化
2. **14行目**: Elispベースのプロパティ取得関数を設定
3. **16-17行目**: ws-butler-mode との連携設定
4. **22-23行目**: 除外パターン（ZIP/Office形式）の追加
5. **25-45行目**: プロパティ適用後のフック関数定義

#### Step 3: フック関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/tools/editorconfig/config.el` | +editorconfig-disable-indent-detection-h 関数（26-33行目） |
| 3-2 | config.el | `modules/tools/editorconfig/config.el` | +editorconfig-unset-tab-width-in-org-mode-h 関数（38-45行目） |

**主要処理フロー**:
- **29-33行目**: dtrt-indent の抑制条件判定
- **40-45行目**: org-mode での tab-width 強制設定

#### Step 4: 拡張API を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload.el | `modules/tools/editorconfig/autoload.el` | set-editorconfig-indent-var! マクロ |

**主要処理フロー**:
- **4-7行目**: モード固有のインデント変数を editorconfig-indentation-alist に追加

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

```
doom-first-buffer (hook)
    │
    └─ editorconfig-mode
           │
           ├─ editorconfig-get-properties (file)
           │      └─ .editorconfig 検索・パース
           │
           └─ editorconfig-after-apply-functions (hook)
                  │
                  ├─ +editorconfig-disable-indent-detection-h
                  │      └─ setq +whitespace-guess-inhibit
                  │
                  └─ +editorconfig-unset-tab-width-in-org-mode-h
                         └─ setq tab-width
```

### データフロー図

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

.editorconfig ───▶ editorconfig-get-properties ───▶ props (hash-table)
                           │
                           ▼
                   editorconfig-apply
                           │
                   ┌───────┴───────┐
                   ▼               ▼
        インデント設定適用    文字コード設定適用
                   │               │
                   ▼               ▼
        バッファローカル変数   coding-system
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/tools/editorconfig/config.el` | ソース | メイン設定ファイル、フック定義 |
| autoload.el | `modules/tools/editorconfig/autoload.el` | ソース | 自動ロード関数、set-editorconfig-indent-var! |
| packages.el | `modules/tools/editorconfig/packages.el` | 設定 | 依存パッケージ定義（editorconfig） |
