# 機能設計書 61-@alias

## 概要

本ドキュメントは、Lua Language Serverにおける`@alias`アノテーション機能の設計を記述する。`@alias`は型エイリアスを定義するためのLuaDocアノテーションであり、複雑な型定義に名前を付けて再利用可能にする機能を提供する。

### 本機能の処理概要

`@alias`アノテーションは、既存の型や複合型に対して新しい名前（エイリアス）を定義する機能である。これにより、長い型定義を簡潔な名前で参照できるようになり、コードの可読性と保守性が向上する。

**業務上の目的・背景**：Lua言語は動的型付け言語であり、静的型検査を行うには型アノテーションが必要となる。複雑な型定義（ユニオン型、テーブル型など）を毎回記述すると冗長になるため、型エイリアスを定義して再利用できる仕組みが必要である。`@alias`はこの課題を解決し、大規模なLuaプロジェクトにおける型安全性と開発効率を両立させる。

**機能の利用シーン**：
- 複数の型をユニオンとして定義し、再利用可能な名前を付ける場合
- コールバック関数の型を定義する場合
- 複雑なテーブル構造に名前を付ける場合
- ジェネリック型エイリアスを定義する場合

**主要な処理内容**：
1. `---@alias`で始まるコメント行を検出
2. エイリアス名を解析し、`doc.alias.name`ノードを生成
3. ジェネリック型パラメータ（`<T, V>`形式）がある場合は解析
4. 拡張型（extends）を解析し、型定義を`doc.type`として構築
5. エイリアス定義をAST（抽象構文木）に追加し、後続処理で型解決に使用

**関連システム・外部連携**：
- パーサー（`script/parser/luadoc.lua`）：アノテーション構文の解析
- 型推論エンジン（`script/vm/infer.lua`）：エイリアス型の解決
- 補完システム（`script/core/completion/`）：エイリアス名の補完候補提供

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はエディタのコメント入力時に動作し、専用の画面は存在しない |

## 機能種別

コード解析 / 型定義

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| コメントテキスト | string | Yes | `---@alias`で始まるコメント行 | `@alias`キーワードの存在確認 |
| エイリアス名 | string | Yes | 定義するエイリアスの名前 | 有効な識別子であること |
| 型定義 | string | Yes | エイリアスに対応する型の定義 | 有効な型構文であること |
| ジェネリックパラメータ | string | No | `<T, V>`形式のジェネリック型パラメータ | 有効な識別子のリストであること |

### 入力データソース

Luaソースファイル内の`---@alias`形式のコメント行

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| doc.alias | table | エイリアス定義のASTノード |
| doc.alias.name | table | エイリアス名を表すノード |
| doc.alias.extends | table | エイリアスが参照する型定義 |
| doc.alias.signs | table | ジェネリック型パラメータのリスト（存在する場合） |
| doc.alias.docAttr | table | ドキュメント属性（存在する場合） |

### 出力先

パーサーの状態オブジェクト（`state.ast.docs`）に追加される

## 処理フロー

### 処理シーケンス

```
1. コメント解析開始
   └─ `---@alias`形式のコメントを検出
2. トークン解析
   └─ コメントテキストをトークンに分割
3. `alias`キーワード認識
   └─ docSwitch関数でaliasケースにディスパッチ
4. ドキュメント属性解析（オプション）
   └─ `(partial)`などの属性があれば解析
5. エイリアス名解析
   └─ `doc.alias.name`ノードを生成
6. ジェネリックパラメータ解析（オプション）
   └─ `<T, V>`形式のパラメータを`signs`として保存
7. 型定義解析
   └─ `parseType`関数で拡張型を解析
8. ASTノード構築
   └─ `doc.alias`ノードを生成し、関連情報を設定
9. ドキュメントリストに追加
   └─ `state.ast.docs`にノードを追加
```

### フローチャート

```mermaid
flowchart TD
    A[コメント検出] --> B{@aliasキーワード?}
    B -->|No| Z[終了]
    B -->|Yes| C[docAttr解析]
    C --> D{エイリアス名あり?}
    D -->|No| E[LUADOC_MISS_ALIAS_NAME警告]
    E --> Z
    D -->|Yes| F[エイリアス名ノード生成]
    F --> G{ジェネリックパラメータ?}
    G -->|Yes| H[signs解析]
    G -->|No| I[型定義解析]
    H --> I
    I --> J{型定義あり?}
    J -->|No| K[LUADOC_MISS_ALIAS_EXTENDS警告]
    K --> Z
    J -->|Yes| L[doc.aliasノード構築]
    L --> M[ASTに追加]
    M --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | エイリアス名必須 | エイリアス定義には必ず名前が必要 | @aliasアノテーション使用時 |
| BR-02 | 型定義必須 | エイリアスには必ず型定義が必要 | @aliasアノテーション使用時 |
| BR-03 | ジェネリック型サポート | `<T>`形式でジェネリック型パラメータを定義可能 | ジェネリックエイリアス定義時 |
| BR-04 | ユニオン型サポート | `type1 | type2`形式でユニオン型を定義可能 | 複合型定義時 |

### 計算ロジック

特になし

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

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

本機能はデータベースを使用しない（メモリ上でAST操作を行う）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| LUADOC_MISS_ALIAS_NAME | Warning | エイリアス名が指定されていない | 正しいエイリアス名を指定する |
| LUADOC_MISS_ALIAS_EXTENDS | Warning | 型定義が指定されていない | 有効な型定義を追加する |
| LUADOC_MISS_SIGN_NAME | Warning | ジェネリックパラメータ名がない | パラメータ名を指定する |

### リトライ仕様

リトライは不要（構文解析時のエラーは即座に報告される）

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

トランザクション管理は不要（メモリ上の解析処理）

## パフォーマンス要件

- 単一のエイリアス解析は1ms以内に完了すること
- 大量のエイリアス定義（1000件以上）があるファイルでも解析時間は100ms以内

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

- 入力文字列の検証（不正な識別子の排除）
- メモリ使用量の制限（極端に長い型定義の制限）

## 備考

- `@alias`は`@type`と組み合わせて使用されることが多い
- VSCodeなどのエディタでは、エイリアス名にホバーすると元の型定義が表示される

---

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

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

### 推奨読解順序

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

まず、`@alias`アノテーションがどのようなASTノードとして表現されるかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | luadoc.lua | `script/parser/luadoc.lua` | `doc.alias`ノードの構造、`doc.alias.name`、`extends`、`signs`フィールドの役割 |

**読解のコツ**: `doc.alias`ノードは以下のフィールドを持つ：
- `type`: `'doc.alias'`
- `alias`: エイリアス名（`doc.alias.name`型）
- `extends`: 型定義（`doc.type`型）
- `signs`: ジェネリックパラメータのリスト（オプション）
- `docAttr`: ドキュメント属性（オプション）

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

`@alias`アノテーションの解析処理の起点を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | luadoc.lua | `script/parser/luadoc.lua` | `docSwitch`の`'alias'`ケース（1112-1140行目） |

**主要処理フロー**:
1. **1114行目**: `doc.alias`テーブルを初期化
2. **1117行目**: `parseDocAttr`でドキュメント属性を解析
3. **1118行目**: `parseName`でエイリアス名を解析
4. **1128行目**: `parseSigns`でジェネリックパラメータを解析
5. **1129行目**: `parseType`で拡張型を解析
6. **1138行目**: 完成したノードを返却

#### Step 3: 補助関数を理解する

エイリアス解析で使用される補助関数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | luadoc.lua | `script/parser/luadoc.lua` | `parseSigns`関数（472-497行目）- ジェネリックパラメータの解析 |
| 3-2 | luadoc.lua | `script/parser/luadoc.lua` | `parseType`関数（944-1037行目）- 型定義の解析 |
| 3-3 | luadoc.lua | `script/parser/luadoc.lua` | `parseDocAttr`関数（258-290行目）- ドキュメント属性の解析 |

**主要処理フロー**:
- **472-497行目**: `parseSigns`は`<`で始まるジェネリックパラメータリストを解析
- **944-1037行目**: `parseType`はユニオン型（`|`区切り）を含む複合型を解析

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

```
luadoc (メイン関数)
    │
    ├─ buildLuaDoc
    │      └─ convertTokens
    │             └─ docSwitch('alias')
    │                    ├─ parseDocAttr
    │                    ├─ parseName
    │                    ├─ parseSigns
    │                    │      └─ parseName (各パラメータ)
    │                    └─ parseType
    │                           └─ parseTypeUnit (再帰)
    │
    └─ bindDocs
           └─ bindGeneric (ジェネリック型のバインド)
```

### データフロー図

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

---@alias MyType int|string
        │
        ▼
  parseTokens         ───▶  トークン配列
        │
        ▼
  docSwitch('alias')  ───▶  aliasケース処理
        │
        ▼
  parseName           ───▶  doc.alias.name = "MyType"
        │
        ▼
  parseType           ───▶  doc.type {types: [int, string]}
        │
        ▼
  doc.aliasノード構築  ───▶  state.ast.docs に追加
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| luadoc.lua | `script/parser/luadoc.lua` | ソース | LuaDocアノテーションの解析メイン処理 |
| compile.lua | `script/parser/compile.lua` | ソース | Luaソースコードのコンパイル（luadocを呼び出す） |
| guide.lua | `script/parser/guide.lua` | ソース | AST操作のユーティリティ関数 |
| infer.lua | `script/vm/infer.lua` | ソース | 型推論エンジン（エイリアス型の解決） |
| definition.lua | `script/core/definition.lua` | ソース | 定義へ移動機能（エイリアス定義へのジャンプ） |
