# 機能設計書 20-ドキュメント構造解析

## 概要

本ドキュメントは、F#コンパイラサービスのドキュメント構造解析（Document Structure Analysis）機能の設計を記述する。この機能は、ソースコードの構造的な範囲（アウトライン、折りたたみ領域）を解析し、IDEのコード折りたたみ機能を実現する。

### 本機能の処理概要

ドキュメント構造解析機能は、F#ソースコードのAST（抽象構文木）を走査し、コードの論理的なブロック（モジュール、型、関数、制御構造など）の範囲を特定する。

**業務上の目的・背景**：大規模なソースファイルを効率的にナビゲートするため、コードの論理的なブロックを折りたたんで表示する機能が必要。構造解析により、折りたたみ可能な領域を正確に特定する。

**機能の利用シーン**：
- Visual Studioでのコード折りたたみ
- VS Codeでのアウトライン表示
- エディタでの構造ナビゲーション

**主要な処理内容**：
1. パース結果（AST）の取得
2. AST走査による構造抽出
3. 範囲情報の計算
4. 折りたたみタイプの決定
5. ScopeRange配列の生成

**関連システム・外部連携**：
- FSharpChecker（パース結果の提供）
- Visual Studio Editor API
- Language Server Protocol（LSP）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | テキストエディタ | 主機能 | コード折りたたみ、アウトライン |

## 機能種別

構造解析 / アウトライン / コード折りたたみ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| sourceLines | string[] | Yes | ソースコードの行配列 | - |
| parsedInput | ParsedInput | Yes | パース結果（AST） | - |

### 入力データソース

- パース結果（ParsedInput）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ScopeRange[] | ScopeRange[] | 構造範囲の配列 |
| Scope | Scope | 構造タイプ |
| Collapse | Collapse | 折りたたみタイプ |
| Range | range | 完全な範囲 |
| CollapseRange | range | 折りたたみ範囲 |

### 出力先

- IDE/エディタへの返却

## 処理フロー

### 処理シーケンス

```
1. AST取得
   └─ ParsedInputを受け取る
2. 式の走査
   └─ 再帰的に式を処理
3. 宣言の走査
   └─ モジュール、型、メンバーを処理
4. 範囲計算
   └─ 開始・終了位置を計算
5. ScopeRange生成
   └─ Scope, Collapse, Range, CollapseRangeを設定
```

### フローチャート

```mermaid
flowchart TD
    A[ParsedInput] --> B{実装ファイル?}
    B -->|Yes| C[ParsedImplFile処理]
    B -->|No| D[ParsedSigFile処理]
    C --> E[モジュール/名前空間処理]
    D --> E
    E --> F[型定義処理]
    F --> G[メンバー処理]
    G --> H[式処理]
    H --> I{さらにネスト?}
    I -->|Yes| H
    I -->|No| J[ScopeRange生成]
    J --> K[結果集約]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 2行以上 | 開始行と終了行が異なる場合のみ折りたたみ対象 | rcheck検証 |
| BR-02 | Below/Same | ブロック内は Same、バインディング後は Below | 折りたたみスタイル |
| BR-03 | コメント | 連続コメントは1つの折りたたみ領域 | コメント処理 |
| BR-04 | XMLDoc | XMLドキュメントコメントは専用スコープ | XmlDocComment |

### 計算ロジック

範囲計算関数:
- endToEnd: r1終了からr2終了まで
- endToStart: r1終了からr2開始まで
- startToEnd: r1開始からr2終了まで
- modStart/modEnd: 列位置を調整

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | AST不完全 | パースエラー | 利用可能な範囲で処理 |

### リトライ仕様

特になし。

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

該当なし

## パフォーマンス要件

- 構造解析: ファイルサイズに比例
- 再帰走査のため深いネストに注意

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

特になし

## 備考

- 24種類のスコープタイプを定義（Scope列挙型）
- コメント行の連結処理を含む

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ServiceStructure.fs | `src/Compiler/Service/ServiceStructure.fs` | Collapse列挙型（72-74行目） |
| 1-2 | ServiceStructure.fs | `src/Compiler/Service/ServiceStructure.fs` | Scope列挙型（78-124行目） |
| 1-3 | ServiceStructure.fs | `src/Compiler/Service/ServiceStructure.fs` | ScopeRange型（177-186行目） |

**主要なスコープタイプ**:
- **Open (79)**: open文
- **Namespace (80)**: 名前空間
- **Module (81)**: モジュール
- **Type (82)**: 型定義
- **Member (83)**: メンバー
- **LetOrUse (84)**: let/use束縛
- **IfThenElse (87)**: if-then-else
- **Match (100)**: match式
- **Comment (123)**: コメント
- **XmlDocComment (124)**: XMLドキュメント

#### Step 2: 範囲計算ユーティリティを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ServiceStructure.fs | `src/Compiler/Service/ServiceStructure.fs` | Range.endToEnd（21-22行目） |
| 2-2 | ServiceStructure.fs | `src/Compiler/Service/ServiceStructure.fs` | Range.modStart/modEnd（37-44行目） |

**主要処理フロー**:
- **21-22行目**: endToEnd - r1終了からr2終了までの範囲
- **25-26行目**: endToStart - r1終了からr2開始までの範囲
- **37-39行目**: modStart - 開始列をオフセット
- **42-44行目**: modEnd - 終了列をオフセット

#### Step 3: 式の走査を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ServiceStructure.fs | `src/Compiler/Service/ServiceStructure.fs` | parseExpr関数（227行目以降） |

**主要処理フロー**:
- **227-237行目**: 単純な式のパターン（Upcast, Downcast等）
- **245-247行目**: New式の処理
- **270-288行目**: Match/MatchBang式の処理
- **290-319行目**: App式（関数適用）の処理

#### Step 4: メイン関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ServiceStructure.fs | `src/Compiler/Service/ServiceStructure.fs` | getOutliningRanges関数（209行目以降） |

**主要処理フロー**:
- **210行目**: 結果を蓄積するResizeArray
- **213-221行目**: rcheck - 2行以上の範囲をチェックして追加
- **227行目以降**: parseExpr - 式の再帰処理

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

```
getOutliningRanges (エントリーポイント)
    │
    ├─ rcheck (検証・追加)
    │      └─ ScopeRange生成
    │
    ├─ parseExpr (式の走査)
    │      ├─ SynExpr.New
    │      ├─ SynExpr.Match / MatchBang
    │      ├─ SynExpr.App
    │      ├─ SynExpr.LetOrUse
    │      ├─ SynExpr.TryWith / TryFinally
    │      ├─ SynExpr.IfThenElse
    │      └─ 他のSynExpr種別
    │
    ├─ parseMatchClause (マッチ節)
    │
    ├─ parseBindings (束縛)
    │
    └─ parseDeclarations (宣言)
           ├─ SynModuleOrNamespace
           ├─ SynTypeDefn
           └─ SynMemberDefn
```

### データフロー図

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

ParsedInput ────────▶ getOutliningRanges
(AST)                        │
                             ▼
                    parseExpr (再帰)
                         │
            ┌────────────┼────────────┐
            ▼            ▼            ▼
         式処理      束縛処理     宣言処理
            │            │            │
            └────────────┼────────────┘
                         ▼
                      rcheck
                         │
                         ▼
ScopeRange[] ◀────── 結果集約
   │
   ├─ Scope (構造タイプ)
   ├─ Collapse (折りたたみタイプ)
   ├─ Range (完全範囲)
   └─ CollapseRange (折りたたみ範囲)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ServiceStructure.fs | `src/Compiler/Service/ServiceStructure.fs` | ソース | ドキュメント構造解析のコア実装 |
| Syntax.fs | `src/Compiler/SyntaxTree/Syntax.fs` | ソース | AST型定義 |
| SyntaxTreeOps.fs | `src/Compiler/SyntaxTree/SyntaxTreeOps.fs` | ソース | AST操作ユーティリティ |
| ParseAndCheckInputs.fs | `src/Compiler/Driver/ParseAndCheckInputs.fs` | ソース | パース処理 |
