# 画面設計書 17-セマンティックトークン（全体）

## 概要

本ドキュメントは、Lua Language Serverの「セマンティックトークン（全体）（textDocument/semanticTokens/full）」機能の画面設計書である。この機能は、ファイル全体のセマンティックハイライト情報を提供する。

### 本画面の処理概要

この機能では、ドキュメント全体を解析し、各トークン（変数、関数、キーワード等）のセマンティック情報（種類、修飾子）を返却する。エディタはこの情報を使用して、構文ハイライトを超えた意味的なコードハイライトを実現する。

**業務上の目的・背景**：従来の構文ハイライトはテキストパターンに基づいており、コードの意味を考慮しない。セマンティックトークン機能により、変数の種類（ローカル、グローバル、パラメータ等）、関数の呼び出しと定義、クラスとインスタンスなどを視覚的に区別できる。これにより、コードの可読性が大幅に向上し、バグの早期発見にも貢献する。

**画面へのアクセス方法**：ファイルを開くと自動的にセマンティックトークン情報が取得される。設定でLua.semantic.enableがtrueの場合に有効となる。

**主要な操作・処理内容**：
1. ドキュメントのASTを取得する
2. すべてのソース要素を走査し、トークンタイプと修飾子を判定する
3. 重複・複数行トークンを処理する
4. LSP形式のトークンデータ（差分エンコード）を生成する

**画面遷移**：セマンティックトークンは表示のみの機能であり、他の機能への直接的な遷移はない。

**権限による表示制御**：特になし。LSPプロトコルレベルでの認証・権限管理は行わない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 43 | セマンティックトークン (textDocument/semanticTokens) | 主機能 | ファイル全体のセマンティックハイライト情報を提供する主処理 |

## 画面種別

LSP機能（ハイライト情報提供）

## URL/ルーティング

LSPメソッド: `textDocument/semanticTokens/full`

## 入出力項目

### 入力項目（リクエストパラメータ）

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| textDocument | TextDocumentIdentifier | Yes | 対象ドキュメントのURI |

### 出力項目（レスポンス）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| data | number[] | トークンデータ（差分エンコード形式） |

### トークンデータ形式

5つの数値で1トークンを表現（LSP仕様準拠）:
1. deltaLine: 前トークンからの行差分
2. deltaStartChar: 前トークンからの文字位置差分（同一行）/ 行頭からの位置（異なる行）
3. length: トークンの長さ
4. tokenType: トークンタイプ（TokenTypes定義による）
5. tokenModifiers: 修飾子ビットフラグ（TokenModifiers定義による）

## 表示項目

| 表示項目 | 説明 |
|---------|------|
| トークンハイライト | 各トークンの種類に応じた色分け表示 |

### トークンタイプ一覧

| トークンタイプ | 説明 |
|--------------|------|
| function | 関数 |
| variable | 変数 |
| method | メソッド |
| parameter | パラメータ |
| property | プロパティ |
| class | クラス |
| type | 型 |
| keyword | キーワード |
| string | 文字列 |
| number | 数値 |
| comment | コメント |
| operator | 演算子 |
| macro | マクロ（alias/enum） |

### 修飾子一覧

| 修飾子 | 説明 |
|--------|------|
| declaration | 宣言 |
| readonly | 読み取り専用 |
| global | グローバル |
| defaultLibrary | 標準ライブラリ |
| async | 非同期 |
| modification | 変更 |
| documentation | ドキュメント |
| deprecated | 非推奨 |
| static | 静的 |
| abstract | 抽象 |

## イベント仕様

### 1-semanticTokens/fullリクエスト処理

1. クライアントからtextDocument/semanticTokens/fullリクエストを受信
2. Lua.semantic.enable設定を確認
3. ドキュメントのASTを取得
4. guide.eachSourceBetweenで全ソース要素を走査
5. Care関数で各ソースタイプに応じたトークン情報を生成
6. コメントのトークン情報を追加
7. solveMultilineAndOverlappingで重複・複数行を処理
8. buildTokensでLSP形式のデータを生成
9. トークンデータを返却

## データベース更新仕様

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

この機能はデータベース操作を行わない。ソースコードを解析するのみで、変更は行わない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| semanticTokens/fullリクエスト | なし | SELECT（読み取り） | ソースコードの解析のみ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| WINDOW_PROCESSING_SEMANTIC_FULL | 進捗 | 処理中表示 | トークン解析処理中 |
| - | 成功 | （トークンデータ返却） | 正常終了時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ファイルが見つからない | 空配列を返却 |
| ASTの取得に失敗 | 空配列を返却 |
| Lua.semantic.enableがfalse | 空配列を返却 |

## 備考

- トークンデータはLSP仕様に従い、差分エンコード形式で返却される
- 複数行にまたがるトークンは、クライアントがmultilineTokenSupportを持つ場合はそのまま、持たない場合は行ごとに分割される
- 設定項目: Lua.semantic.enable（有効/無効）, Lua.semantic.variable（変数ハイライト）, Lua.semantic.annotation（アノテーションハイライト）, Lua.semantic.keyword（キーワードハイライト）
- LuaDocアノテーション（@class, @param等）もセマンティックトークンとして処理される
- 仮想ソース（source.virtual = true）はスキップされる

---

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

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

### 推奨読解順序

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

まず、トークンタイプと修飾子の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | define.lua | `script/proto/define.lua` | TokenTypes, TokenModifiers定義 |
| 1-2 | semantic-tokens.lua | `script/core/semantic-tokens.lua` (730-764行目) | buildTokens関数 - トークンエンコード |

**読解のコツ**: トークンデータは差分エンコードされるため、前のトークンとの位置差分を計算する必要がある。buildTokens関数がこの変換を行っている。

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

処理の起点となるプロバイダー登録を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | provider.lua | `script/provider/provider.lua` (1079-1109行目) | textDocument/semanticTokens/fullの登録 |

**主要処理フロー**:
1. **1082行目**: `m.register 'textDocument/semanticTokens/full'`でハンドラー登録（client.eventで条件付き）
2. **1096行目**: `core/semantic-tokens`モジュールを呼び出し
3. **1100-1101行目**: 0からmath.hugeの範囲（ファイル全体）で処理

#### Step 3: コア処理を理解する

セマンティックトークン生成のコアロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | semantic-tokens.lua | `script/core/semantic-tokens.lua` | トークン生成の全体構造 |
| 3-2 | semantic-tokens.lua | `script/core/semantic-tokens.lua` (12-54行目) | Care:getglobal/setglobal - グローバル変数処理 |
| 3-3 | semantic-tokens.lua | `script/core/semantic-tokens.lua` (117-255行目) | Care:local/getlocal/setlocal - ローカル変数処理 |
| 3-4 | semantic-tokens.lua | `script/core/semantic-tokens.lua` (421-471行目) | Care:doc.type.name - LuaDoc型名処理 |
| 3-5 | semantic-tokens.lua | `script/core/semantic-tokens.lua` (766-870行目) | solveMultilineAndOverlapping - 重複・複数行処理 |
| 3-6 | semantic-tokens.lua | `script/core/semantic-tokens.lua` (873-951行目) | メイン関数 |

**主要処理フロー**:
- **873-891行目**: 設定確認とオプション構築
- **893-904行目**: guide.eachSourceBetweenで全ソース走査、Care関数で処理
- **906-940行目**: コメントのトークン処理
- **946行目**: solveMultilineAndOverlappingで後処理
- **948行目**: buildTokensでエンコード

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

```
textDocument/semanticTokens/full (provider.lua:1082-1106)
    |
    +-- workspace.awaitReady (ワークスペース準備待機)
    |
    +-- progress.create (進捗表示)
    |
    +-- core/semantic-tokens (semantic-tokens.lua:873-951)
           |
           +-- config.get (設定取得)
           |      +-- Lua.semantic.enable
           |      +-- Lua.semantic.variable
           |      +-- Lua.semantic.annotation
           |      +-- Lua.semantic.keyword
           |
           +-- files.getState (AST取得)
           |
           +-- guide.eachSourceBetween (ソース走査)
           |      |
           |      +-- Care (12-728行目)
           |             +-- getglobal/setglobal処理
           |             +-- local/getlocal/setlocal処理
           |             +-- field処理
           |             +-- キーワード処理
           |             +-- doc.*処理
           |
           +-- コメント処理 (906-940行目)
           |
           +-- solveMultilineAndOverlapping (766-870行目)
           |
           +-- buildTokens (730-764行目)
```

### データフロー図

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

SemanticTokensParams           provider.lua                        SemanticTokens
+------------------+           +------------------+                 +------------------+
| textDocument.uri |  ------>  | config確認        |                 | data: number[]   |
+------------------+           | AST取得          |                 +------------------+
                               +------------------+
                                      |
                                      v
                               semantic-tokens.lua
                               +----------------------+
                               | guide.eachSource     |
                               |   Care関数           |  -------->
                               | コメント処理         |
                               | solveMultiline...   |
                               | buildTokens         |
                               +----------------------+

[トークンデータ形式]
+--------+---------------+--------+-----------+---------------+
| delta  | deltaStart    | length | tokenType | modifiers     |
| Line   | Char          |        |           | (bitflags)    |
+--------+---------------+--------+-----------+---------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPメソッドハンドラー登録 |
| semantic-tokens.lua | `script/core/semantic-tokens.lua` | ソース | セマンティックトークン生成コアロジック |
| define.lua | `script/proto/define.lua` | ソース | TokenTypes, TokenModifiers定義 |
| converter.lua | `script/proto/converter.lua` | ソース | 位置変換処理 |
| linked-table.lua | `script/linked-table.lua` | ソース | 重複処理用リンクテーブル |
| files.lua | `script/files.lua` | ソース | ファイル管理・AST取得 |
| guide.lua | `script/parser/guide.lua` | ソース | AST操作ユーティリティ |
| config.lua | `script/config.lua` | ソース | 設定管理 |
| vm.lua | `script/vm/init.lua` | ソース | 型推論（トークンタイプ判定に使用） |
