# 機能設計書 86-シンタックスハイライト

## 概要

本ドキュメントは、Nushellのシンタックスハイライト機能（NuHighlighter）の設計について記述する。この機能は、ユーザーの入力中にリアルタイムで構文に応じた色付けを行い、コードの可読性を向上させる。

### 本機能の処理概要

NuHighlighterは、reedlineのHighlighterトレイトを実装し、入力行を構文解析してFlatShape（構文要素の種類）を取得し、各要素に対応する色スタイルを適用してStyledTextを生成する。括弧のマッチングハイライト、外部コマンドの存在確認ハイライトなどの高度な機能も提供する。

**業務上の目的・背景**：構文ハイライトはコード入力時の視認性を大幅に向上させる。キーワード、文字列、数値、コマンド名などが色分けされることで、構文エラーの早期発見や入力内容の理解が容易になる。対話型シェルにおいて、入力中のリアルタイムハイライトはユーザー体験の重要な要素である。

**機能の利用シーン**：REPLでのコマンド入力中に常時動作。入力文字が追加/削除されるたびにハイライトが更新される。カーソル位置に応じた括弧のマッチングハイライトも提供される。

**主要な処理内容**：
1. 入力行の構文解析（パース）
2. ブロックのフラット化（FlatShape取得）
3. 各FlatShapeに対応する色スタイルの取得
4. 括弧マッチング位置の計算
5. StyledTextの構築と返却

**関連システム・外部連携**：reedline（ハイライトUI）、nu-color-config（色設定）

**権限による制御**：なし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 補助機能 | コマンド入力中の構文に応じた色付け表示 |

## 機能種別

表示機能 / 入力支援

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| line | &str | Yes | ハイライト対象の入力行 | - |
| cursor | usize | Yes | カーソル位置 | 行長以下 |

### 入力データソース

- 現在の入力行（reedlineから渡される）
- EngineState（設定、色テーマ）
- Stack（環境変数、設定参照）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| styled_text | StyledText | スタイル付きテキスト |

### 出力先

reedlineハイライトシステム

## 処理フロー

### 処理シーケンス

```
1. 入力行のパース
   └─ parse()で構文木を生成
2. フラット化
   └─ flatten_block()でFlatShapeリストを取得
3. 括弧マッチング計算
   └─ カーソル位置の括弧と対応する括弧を検出
4. スタイル適用
   └─ 各FlatShapeに対応する色スタイルを取得
5. StyledText構築
   └─ スタイル付きテキストセグメントを連結
```

### フローチャート

```mermaid
flowchart TD
    A[highlight呼び出し] --> B[入力行パース]
    B --> C[flatten_block]
    C --> D[括弧マッチング計算]
    D --> E[shapesループ開始]
    E --> F{Garbageか?}
    F -->|Yes| G[エラー位置記録]
    F -->|No| H{Externalか?}
    H -->|Yes| I{存在確認設定?}
    I -->|Yes| J[which確認]
    J --> K{存在する?}
    K -->|Yes| L[ExternalResolved色]
    K -->|No| M[External色]
    H -->|No| N{ブロック系か?}
    N -->|Yes| O[括弧ハイライト適用]
    N -->|No| P[通常色適用]
    G --> Q[StyledTextに追加]
    L --> Q
    M --> Q
    O --> Q
    P --> Q
    Q --> R{次の要素あり?}
    R -->|Yes| E
    R -->|No| S[ギャップ処理]
    S --> T[StyledText返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-86-01 | 外部コマンド存在確認 | highlight_resolved_externals設定時にwhichで存在確認 | External FlatShape時 |
| BR-86-02 | 括弧マッチング | {}[]()の対応する括弧をハイライト | カーソルが括弧上にある時 |
| BR-86-03 | ギャップ処理 | shapesの隙間は無スタイルで補完 | shapes間にギャップがある時 |
| BR-86-04 | エラー検出 | Garbage FlatShapeはエラーとして記録 | パースエラー時 |

### 計算ロジック

**色スタイル取得**: `get_shape_color(shape.as_str(), &config)`
**括弧マッチング色**: `get_matching_brackets_style(style, &config)`

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | パース失敗 | Garbageとしてハイライト |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- キー入力ごとに呼び出されるため、高速な処理が必須
- 目標: 10ms以内でハイライト完了

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

特になし

## 備考

- FlatShapeはnu_parserで定義される構文要素の種類
- 色設定はenv.nuやconfig.nuでカスタマイズ可能

---

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

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

### 推奨読解順序

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

ハイライトで使用する主要な構造体を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | syntax_highlight.rs | `crates/nu-cli/src/syntax_highlight.rs` | NuHighlighter構造体、HighlightResult構造体 |

**読解のコツ**:
- **14-17行目**: NuHighlighter構造体（EngineStateとStackへの参照を保持）
- **27-33行目**: HighlightResult構造体（StyledTextとエラースパン）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | syntax_highlight.rs | `crates/nu-cli/src/syntax_highlight.rs` | highlightメソッドとhighlight_syntax関数 |

**主要処理フロー**:
1. **19-24行目**: Highlighterトレイト実装
2. **35-159行目**: highlight_syntax関数の全体
3. **45-46行目**: パースとフラット化
4. **54-60行目**: 括弧マッチング位置の計算
5. **62-151行目**: shapesループでのスタイル適用

#### Step 3: 括弧マッチングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | syntax_highlight.rs | `crates/nu-cli/src/syntax_highlight.rs` | find_matching_brackets関数群 |

**主要処理フロー**:
- **190-241行目**: find_matching_brackets - メイン関数
- **243-289行目**: find_matching_block_end_in_block - ブロック内検索
- **291-516行目**: find_matching_block_end_in_expr - 式内検索

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

```
NuHighlighter::highlight() [reedline Highlighter]
    │
    └─ highlight_syntax()
           │
           ├─ parse() [構文解析]
           │
           ├─ flatten_block() [FlatShapeリスト取得]
           │
           ├─ find_matching_brackets()
           │      │
           │      └─ find_matching_block_end_in_block()
           │             │
           │             └─ find_matching_block_end_in_expr()
           │
           └─ shapes.iter() [ループ]
                  │
                  ├─ get_shape_color() [色取得]
                  │
                  ├─ split_span_by_highlight_positions()
                  │      └─ 括弧ハイライト分割
                  │
                  └─ StyledText::push()
```

### データフロー図

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

入力行 + cursor ───▶ パース ───▶ flatten ───▶ 色適用 ───▶ StyledText
  "ls -la"          Block      [External,   [赤,        [(赤,"ls"),
                               Flag]        青]          (青,"-la")]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| syntax_highlight.rs | `crates/nu-cli/src/syntax_highlight.rs` | ソース | ハイライトメインロジック |
| nu_highlight.rs | `crates/nu-cli/src/nu_highlight.rs` | ソース | nu_highlightコマンド |
| lib.rs | `crates/nu-color-config/src/lib.rs` | ソース | 色設定取得 |
