# 帳票設計書 1-doc.json

## 概要

本ドキュメントは、Lua Language ServerのAPIドキュメント生成機能によって出力される`doc.json`ファイルの帳票設計を定義する。この帳票は、Luaソースコードから抽出されたグローバル変数、型定義、クラス、関数などのAPIドキュメント情報をJSON形式で構造化して出力する。

### 本帳票の処理概要

本帳票は、Lua Language ServerのCLIコマンドによって生成されるAPIドキュメントであり、Luaコードベースの構造情報を機械可読な形式で出力する。

**業務上の目的・背景**：Luaプロジェクトにおいて、コードベースのAPIドキュメントを自動生成し、外部ツールとの連携やドキュメントサイト生成の基盤データとして活用するために必要である。手動でのドキュメント作成を省力化し、コードと同期したドキュメント維持を可能にする。

**帳票の利用シーン**：ライブラリ開発者がAPIリファレンスを公開する際、CIパイプラインでドキュメントを自動生成する際、また外部ツール（ドキュメント生成ツール、IDE連携ツール等）がプログラム的にAPI情報を参照する際に利用される。

**主要な出力内容**：
1. グローバル変数の定義情報（名前、型、説明、定義位置）
2. 型エイリアス・クラス定義（フィールド、継承関係、可視性）
3. 関数定義（引数、戻り値、非同期フラグ、非推奨フラグ）
4. LuaLSの設定情報（DOCパス、フィールド、defines）

**帳票の出力タイミング**：CLIから`--DOC`オプションを指定して実行した際、またはLSP経由でドキュメント生成リクエストを受信した際に出力される。

**帳票の利用者**：ライブラリ開発者、技術ドキュメント担当者、CIシステム、外部ドキュメント生成ツール

## 帳票種別

データエクスポート（API定義データ）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| CLI | コマンドラインインターフェース | `lua-language-server --DOC=<path>` | --DOCオプション指定 |
| CLI | コマンドラインインターフェース | `lua-language-server --DOC_UPDATE=<path>` | --DOC_UPDATEオプション指定 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON |
| 用紙サイズ | N/A（データファイル） |
| 向き | N/A |
| ファイル名 | `doc.json` |
| 出力方法 | ファイル出力 |
| 文字コード | UTF-8 |

### JSON固有設定

| 項目 | 内容 |
|-----|------|
| インデント | スペース4文字（beautify適用） |
| 配列のスパース対応 | 有効（supportSparseArray = true） |
| エスケープ | 標準JSONエスケープ |

## 帳票レイアウト

### レイアウト概要

JSONファイルはドキュメントオブジェクトの配列として構成される。各オブジェクトはグローバル変数または型定義を表し、名前順でソートされる。

```
[
  {
    "name": "...",           // グローバル名/型名
    "type": "...",           // オブジェクト種別
    "view": "...",           // 表示用型文字列
    "desc": "...",           // 説明文
    "defines": [...],        // 定義情報配列
    "fields": [...]          // フィールド情報配列（型の場合）
  },
  ...
]
```

### ヘッダー部

JSON配列形式のためヘッダー部は存在しない。

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | name | グローバル名/型名 | vm.global.getCodeName() | 文字列 |
| 2 | type | オブジェクト種別 | source.type/source.cate | 文字列（doctype） |
| 3 | view | 型の表示文字列 | vm.getInfer():view() | 文字列 |
| 4 | desc | 説明文（コメント） | getDesc(source) | 文字列 |
| 5 | rawdesc | 生の説明文 | getDesc(source, true) | 文字列 |
| 6 | start | 開始位置 | guide.rowColOf(source.start) | [行, 列] |
| 7 | finish | 終了位置 | guide.rowColOf(source.finish) | [行, 列] |
| 8 | file | ファイルパス | guide.getUri(source) | 相対パス文字列 |
| 9 | defines | 定義情報配列 | source:getSets() | docUnion[] |
| 10 | fields | フィールド配列 | vm.getClassFields() | docUnion[] |
| 11 | args | 関数引数 | source.args | docUnion[] |
| 12 | returns | 戻り値情報 | vm.getReturnOfFunction() | docUnion[] |
| 13 | async | 非同期フラグ | vm.isAsync() | boolean |
| 14 | deprecated | 非推奨フラグ | vm.getDeprecated() | boolean |
| 15 | visible | 可視性 | vm.getVisibleType() | 文字列 |
| 16 | extends | 継承型/値型 | source.extends/source.value | docUnion/文字列 |

### フッター部

最後の要素として`type: 'luals.config'`のオブジェクトが追加される。

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | name | 固定値"LuaLS" | 定数 | 文字列 |
| 2 | type | 固定値"luals.config" | 定数 | 文字列 |
| 3 | DOC | ドキュメント対象パス | fs.canonical(DOC) | 絶対パス文字列 |
| 4 | defines | 空配列 | 定数 | [] |
| 5 | fields | 空配列 | 定数 | [] |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| DOCパス | ドキュメント対象ディレクトリ | Yes |
| エクスポート可能グローバル | vm.getExportableGlobals()が返すグローバル | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | name | 昇順 |
| 2 | file | 昇順 |
| 3 | start位置 | 昇順 |

### 改ページ条件

N/A（データファイルのため改ページなし）

## データベース参照仕様

### 参照テーブル一覧

本帳票はデータベースを使用せず、ソースコードの解析結果を直接参照する。

| データソース | 用途 | 取得方法 |
|-------------|------|---------|
| vm.global | グローバル変数定義 | vm.getExportableGlobals() |
| parser.object | AST解析結果 | files.getState(uri) |
| workspace | ワークスペース情報 | ws.rootUri |

### テーブル別参照項目詳細

#### vm.global

| 参照項目 | 帳票項目との対応 | 取得条件 | 備考 |
|---------|----------------|---------|------|
| getCodeName() | name | なし | グローバル名取得 |
| getSets() | defines | rootUri | 定義位置一覧 |
| type/cate | type | なし | オブジェクト種別 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 相対パス | fs.relative(file_path, DOC) | N/A | DOCディレクトリからの相対パス |
| 位置情報 | guide.rowColOf(position) | N/A | 0-indexed [行, 列] |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[CLI実行 --DOC=path] --> B[lclient初期化]
    B --> C[workspace準備待機]
    C --> D[Lua.hover.expandAlias=false設定]
    D --> E[buildScript注入]
    E --> F[gatherGlobals実行]
    F --> G[makeDocs実行]
    G --> H[各グローバルをdocumentObject変換]
    H --> I[getLualsConfig追加]
    I --> J[名前順ソート]
    J --> K[JSON beautify]
    K --> L[ファイル書き込み]
    L --> M[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| パス不正 | DOCが文字列でない | CLI_CHECK_ERROR_TYPE | 正しいパスを指定 |
| URI変換失敗 | furi.encodeが失敗 | CLI_CHECK_ERROR_URI | 有効なパスを指定 |
| ファイル書き込み失敗 | util.saveFile失敗 | エラーメッセージ配列で返却 | ディスク容量・権限確認 |
| buildScript読み込み失敗 | docScriptPathが不正 | could not open config file | パス設定確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | プロジェクト規模依存（数十〜数千グローバル） |
| 目標出力時間 | プログレスバー表示あり、大規模プロジェクトで数分以内 |
| 同時出力数上限 | 1（CLI実行単位） |

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

- 出力ファイルにはソースコード内のコメント情報が含まれるため、機密情報がコメントに記載されていないことを確認する
- buildScriptは任意のLuaコードを実行できるため、信頼できるスクリプトのみを使用する
- 出力パスの検証により、意図しないディレクトリへの書き込みを防止

## 備考

- `--DOC_UPDATE`オプションを使用すると、既存のdoc.jsonから設定を読み取って更新可能
- `Lua.docScriptPath`設定でカスタムビルドスクリプトを指定可能
- doc.jsonと同時にdoc.mdも生成される

---

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

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

### 推奨読解順序

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

まず、出力されるJSONのデータ構造（docUnion型）を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | export.lua | `script/cli/doc/export.lua` | docUnion型定義（37-56行目）で出力JSONの構造を理解 |

**読解のコツ**: `---@class docUnion`のLuaDoc注釈でフィールド定義を確認。各フィールドの説明がコメントで記載されている。

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

処理の起点となるCLI処理を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | init.lua | `script/cli/init.lua` | DOCグローバル変数の分岐（26-29行目） |
| 2-2 | init.lua | `script/cli/doc/init.lua` | runCLI関数（176-256行目）がCLIエントリーポイント |

**主要処理フロー**:
1. **176行目**: runCLI関数開始
2. **188行目**: rootUri生成（furi.encode）
3. **210行目**: lclient起動
4. **227行目**: injectBuildScript呼び出し
5. **229行目**: gatherGlobals呼び出し
6. **231行目**: makeDocs呼び出し
7. **249行目**: serializeAndExport呼び出し

#### Step 3: グローバル収集処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | export.lua | `script/cli/doc/export.lua` | gatherGlobals関数（276-278行目） |

**主要処理フロー**:
- **277行目**: vm.getExportableGlobals()でエクスポート可能グローバル取得

#### Step 4: ドキュメント生成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | export.lua | `script/cli/doc/export.lua` | makeDocs関数（284-293行目） |
| 4-2 | export.lua | `script/cli/doc/export.lua` | documentObject関数（92-123行目）が各オブジェクトをJSON用構造に変換 |
| 4-3 | export.lua | `script/cli/doc/export.lua` | makeDocObject（127-271行目）が型別の変換処理を定義 |

**主要処理フロー**:
- **286-289行目**: 各グローバルに対してdocumentObject呼び出し
- **290行目**: getLualsConfig追加
- **291行目**: ソート処理

#### Step 5: シリアライズ・出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | export.lua | `script/cli/doc/export.lua` | serializeAndExport関数（310-360行目） |

**主要処理フロー**:
- **311-312行目**: 出力パス生成
- **315-318行目**: jsonb.beautifyでJSON整形
- **317行目**: util.saveFileで書き込み

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

```
script/cli/init.lua
    │
    └─ require 'cli.doc'.runCLI()
           │
           ├─ script/cli/doc/init.lua:runCLI()
           │      │
           │      ├─ lclient():start()
           │      │      └─ workspace.awaitReady()
           │      │
           │      ├─ injectBuildScript()
           │      │      └─ require 'cli.doc.export'
           │      │
           │      ├─ dirty_export.gatherGlobals()
           │      │      └─ vm.getExportableGlobals()
           │      │
           │      ├─ dirty_export.makeDocs()
           │      │      ├─ export.documentObject()
           │      │      │      └─ makeDocObject[type]()
           │      │      └─ export.getLualsConfig()
           │      │
           │      └─ dirty_export.serializeAndExport()
           │             ├─ jsonb.beautify()
           │             └─ util.saveFile()
           │
           └─ script/cli/doc/export.lua
```

### データフロー図

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

Luaソースファイル群 ──▶ parser解析 ──▶ AST生成
                              │
                              ▼
                        vm.global生成
                              │
                              ▼
                    vm.getExportableGlobals()
                              │
                              ▼
                      documentObject()変換
                              │
                              ▼
                        名前順ソート
                              │
                              ▼
                      jsonb.beautify()
                              │
                              ▼
                    ────────────────────▶ doc.json
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| init.lua | `script/cli/doc/init.lua` | ソース | CLIエントリーポイント、ドキュメント生成の制御 |
| export.lua | `script/cli/doc/export.lua` | ソース | ドキュメントオブジェクト生成、JSON出力 |
| init.lua | `script/cli/init.lua` | ソース | CLIオプション分岐 |
| json-beautify.lua | `script/json-beautify.lua` | ソース | JSON整形出力 |
| utility.lua | `script/utility.lua` | ソース | ファイル保存（saveFile） |
| vm.lua | `script/vm/vm.lua` | ソース | グローバル変数管理 |
| guide.lua | `script/parser/guide.lua` | ソース | AST操作ユーティリティ |
| description.lua | `script/core/hover/description.lua` | ソース | 説明文取得 |
| label.lua | `script/core/hover/label.lua` | ソース | 表示ラベル取得 |
