# 機能設計書 67-Tree-sitter構文解析

## 概要

本ドキュメントは、Doom EmacsにおけるTree-sitter構文解析モジュールの機能設計を記述する。本モジュールはEmacs 29以降のネイティブtreesit機能を活用し、高速で正確なシンタックスハイライトと構文解析を提供する。

### 本機能の処理概要

Tree-sitter構文解析モジュールは、Tree-sitterライブラリを使用して高速かつ正確な構文解析を行い、シンタックスハイライト、インデント、テキストオブジェクトなどの機能を提供する。従来の正規表現ベースのハイライトと比較して、より正確で高速な処理を実現する。

**業務上の目的・背景**：
従来のEmacsのシンタックスハイライトは正規表現ベースであり、複雑な言語構文では不正確になることがあった。Tree-sitterはインクリメンタルなパーサーであり、編集時の再パースが高速で、文法に忠実なハイライトが可能である。本モジュールにより、開発者はより正確な構文表示を得られ、コードの可読性が向上する。

**機能の利用シーン**：
- 各種プログラミング言語のシンタックスハイライト
- 構文ベースのインデント
- *-ts-modeへの自動リマップ
- グラマーの自動インストール

**主要な処理内容**：
1. treesit-enabled-modesによるts-modeの有効化
2. major-mode-remap-alistによるモード切り替え
3. set-tree-sitter!によるモードリマップ設定
4. グラマーの自動ダウンロード・インストール
5. グラマーソースリストの管理

**関連システム・外部連携**：
- treesit：Emacs組み込みのTree-sitter統合
- 各言語のTree-sitterグラマー（外部リポジトリ）

**権限による制御**：
本機能に権限による制御は存在しない。

## 関連画面

本機能は画面を持たないバックグラウンド機能である。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | シンタックスハイライト、インデント |

## 機能種別

構文解析 / シンタックスハイライト

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| treesit-enabled-modes | list/t | No | 有効化するモードのリスト（デフォルト:t） | シンボルリストまたはt |
| treesit-font-lock-level | integer | No | フォントロックレベル（デフォルト:4） | 1-4 |
| treesit-auto-install-grammar | symbol | No | グラマー自動インストール設定 | 'always, 'ask, nil |

### 入力データソース

- ソースコードバッファ
- treesit-language-source-alist（グラマーソース定義）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| syntax-tree | treesit-parser | パース済み構文木 |
| font-lock-faces | overlay | ハイライト情報 |

### 出力先

- バッファ表示（フォントロック）
- doom-profile-data-dir/tree-sitter/（グラマーライブラリ）

## 処理フロー

### 処理シーケンス

```
1. ファイルオープン
   └─ auto-mode-alist によるモード決定

2. major-mode-remap
   ├─ +tree-sitter--maybe-remap-major-mode-a
   ├─ グラマー存在確認
   └─ ts-mode または fallback-mode 選択

3. ts-mode 有効化
   ├─ treesit-parser 作成
   └─ font-lock 有効化

4. グラマー不足時
   ├─ treesit-auto-install-grammar 確認
   └─ treesit-install-language-grammar 実行
```

### フローチャート

```mermaid
flowchart TD
    A[ファイルオープン] --> B[major-mode-remap]
    B --> C{+tree-sitter prop?}
    C -->|No| Z[通常モード]
    C -->|Yes| D{treesit-available-p?}
    D -->|No| E[fallback-mode]
    D -->|Yes| F{グラマー存在?}
    F -->|Yes| G[ts-mode 有効化]
    F -->|No| H{auto-install設定?}
    H -->|always| I[グラマーインストール]
    H -->|ask| J[ユーザー確認]
    H -->|No| E
    J -->|Yes| I
    J -->|No| E
    I --> G
    G --> K[font-lock有効化]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | フォントロックレベル | デフォルト4（最大）に設定 | treesit-font-lock-level |
| BR-02 | モードリマップ | ts-modeが存在しグラマーがある場合のみリマップ | major-mode-remap 時 |
| BR-03 | グラマー保存先 | doom-profile-data-dir/tree-sitter/ に保存 | グラマーインストール時 |
| BR-04 | auto-mode-alist保護 | ts-modeによる auto-mode-alist 上書きを抑止 | ts-mode 定義時 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | treesit未対応 | Emacsがtreesitなしでビルド | fallback-modeを使用 |
| - | グラマー不在 | 言語グラマーがインストールされていない | 自動インストールまたはfallback |
| - | コンパイル失敗 | グラマーのコンパイルエラー | エラーメッセージ表示 |

### リトライ仕様

特になし。

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

該当なし。

## パフォーマンス要件

- Tree-sitterはインクリメンタルパースにより高速な再パースを実現
- 大規模ファイルでも従来の正規表現ベースより高速

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

- グラマーは外部リポジトリからダウンロードされるため、信頼性を確認
- treesit-language-source-alistで指定されたURLのみ使用

## 備考

- Emacs 29以降で利用可能
- 各言語モジュールでset-tree-sitter!を使用してts-modeを設定

---

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

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

### 推奨読解順序

#### Step 1: 基本設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/tools/tree-sitter/config.el` | treesit use-package設定（6-138行目） |

**読解のコツ**:
- `treesit-enabled-modes = t`: 全モードで有効
- `treesit-font-lock-level = 4`: 最大レベルのハイライト

#### Step 2: モードリマップを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/tools/tree-sitter/config.el` | +tree-sitter--maybe-remap-major-mode-a（45-99行目） |

**主要処理フロー**:
- **46-47行目**: major-mode-remap のaround advice
- **48-49行目**: +tree-sitter プロパティからfallback取得
- **50-55行目**: treesit利用不可時のfallback
- **56-95行目**: グラマー存在確認とインストール

#### Step 3: set-tree-sitter! APIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tree-sitter.el | `modules/tools/tree-sitter/autoload/tree-sitter.el` | set-tree-sitter! マクロ（8-50行目） |

**主要処理フロー**:
- **9-20行目**: ドキュメント（MODES, TS-MODE, RECIPES）
- **24-29行目**: derived-mode-extra-parents設定（親モード登録）
- **30-33行目**: major-mode-remap-defaults設定
- **37-50行目**: treesit-language-source-alist への追加

#### Step 4: グラマーインストールを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/tools/tree-sitter/config.el` | グラマーインストール先設定（104-114行目） |
| 4-2 | config.el | `modules/tools/tree-sitter/config.el` | treesit-language-source-alist追加（117-138行目） |

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

```
ファイルオープン
    │
    └─ major-mode-remap
           │
           └─ +tree-sitter--maybe-remap-major-mode-a (advice)
                  │
                  ├─ [treesit-available-p] チェック
                  │
                  ├─ [fboundp ts-mode] チェック
                  │
                  └─ [treesit-ready-p grammar] チェック
                         │
                         ├─ [存在] ts-mode 返却
                         │
                         └─ [不存在]
                                │
                                ├─ [auto-install] treesit-install-language-grammar
                                │
                                └─ [なし] fallback-mode 返却

set-tree-sitter! (各言語モジュールから)
    │
    ├─ put ts-mode 'derived-mode-extra-parents
    │
    ├─ setf major-mode-remap-defaults
    │
    └─ setf treesit-language-source-alist
```

### データフロー図

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

ソースコード ───▶ treesit-parser ───▶ 構文木
                       │
                       ▼
              font-lock-fontify
                       │
                       ▼
              バッファ表示（ハイライト済み）

グラマーURL ───▶ treesit-install-language-grammar ───▶ .so/.dylib
                                                           │
                                                           ▼
                                              tree-sitter/ ディレクトリ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/tools/tree-sitter/config.el` | ソース | メイン設定、adviceの定義 |
| tree-sitter.el | `modules/tools/tree-sitter/autoload/tree-sitter.el` | ソース | set-tree-sitter!マクロ |
| compat-30.el | `modules/tools/tree-sitter/autoload/compat-30.el` | ソース | Emacs 30互換レイヤー |
| doctor.el | `modules/tools/tree-sitter/doctor.el` | 診断 | treesit診断 |
| packages.el | `modules/tools/tree-sitter/packages.el` | 設定 | パッケージ定義（built-in） |
