# 帳票設計書 11-DScanner設定レポート

## 概要

本ドキュメントは、serve-dサーバーが提供する「DScanner設定レポート」の帳票設計を定義する。指定URIに対するDScannerの現在の設定（INIセクションとフィーチャー）を一覧として出力し、各チェック項目の有効/無効状態を含む情報を返却する。

### 本帳票の処理概要

本帳票は、D言語の静的解析ツールであるDScannerの設定状態をJSON形式で出力する機能である。LSPプロトコルの `served/getDscannerConfig` リクエストを介して呼び出される。

**業務上の目的・背景**：D言語開発において、DScannerは静的解析による品質チェックを担当するが、プロジェクトごとに異なる設定が適用される。開発者がエディタ上で現在の設定状態を確認し、不要なチェックの無効化や必要なチェックの有効化を判断するために本帳票が必要となる。設定の可視化により、プロジェクト固有の品質基準を管理できる。

**帳票の利用シーン**：開発者がVSCodeなどのエディタでD言語プロジェクトを編集中に、DScannerの現在の設定状態を確認したい場面で利用される。特に、特定のlintチェックが有効か無効かを確認する際や、プロジェクトのdscanner.ini設定ファイルの反映状態を検証する際に使用される。

**主要な出力内容**：
1. DScannerのINIセクション情報（セクション名と説明）
2. 各フィーチャー（チェック項目）の名前、説明、有効/無効状態

**帳票の出力タイミング**：エディタ拡張機能から `served/getDscannerConfig` リクエストが送信された時点で出力される。手動操作またはエディタ拡張機能の設定画面表示時にトリガーされる。

**帳票の利用者**：D言語で開発を行うソフトウェアエンジニア、プロジェクトのコード品質管理を担当する開発リーダー。

## 帳票種別

一覧表（設定情報レポート）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | エディタ（VSCode等）の設定画面 | LSP: `served/getDscannerConfig` | エディタ拡張機能のコマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON（LSPレスポンス） |
| 用紙サイズ | N/A（データ形式出力） |
| 向き | N/A |
| ファイル名 | N/A（LSPレスポンスとして返却） |
| 出力方法 | LSP JSON-RPCレスポンス |
| 文字コード | UTF-8 |

### PDF固有設定

該当なし（JSON形式のLSPレスポンス）

### Excel固有設定

該当なし（JSON形式のLSPレスポンス）

## 帳票レイアウト

### レイアウト概要

LSPレスポンスとして `DScannerIniSection[]` 配列を返却する。各セクションにフィーチャー（チェック項目）の配列を含む階層構造である。

```
┌─────────────────────────────────────┐
│  DScannerIniSection[]               │
│  ├─ Section[0]                      │
│  │   ├─ description: string         │
│  │   ├─ name: string                │
│  │   └─ features[]                  │
│  │       ├─ Feature[0]              │
│  │       │   ├─ description          │
│  │       │   ├─ name                 │
│  │       │   └─ enabled              │
│  │       ├─ Feature[1]              │
│  │       │   └─ ...                  │
│  │       └─ Feature[N]              │
│  └─ Section[N] (通常1セクション)      │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | description | INIセクションの説明テキスト | StaticAnalysisConfig構造体の属性 | 文字列 |
| 2 | name | INIセクション名 | StaticAnalysisConfig構造体の属性 | 文字列 |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | description | フィーチャーの説明テキスト | StaticAnalysisConfig各フィールドの属性 | 文字列 | 可変 |
| 2 | name | フィーチャー名（チェック項目識別子） | StaticAnalysisConfig各フィールドの識別子 | 文字列 | 可変 |
| 3 | enabled | 有効/無効状態 | StaticAnalysisConfig各フィールドの値 | "disabled" / "enabled" / "skip-unittest" | 可変 |

### フッター部

該当なし（配列末尾で終了）

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| textDocument.uri | 対象ドキュメントのURI。このURIに基づいてワークスペースインスタンスを特定し、該当するdscanner.iniファイルを決定する | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | フィーチャーのフィールド定義順 | StaticAnalysisConfig構造体のフィールド宣言順（昇順） |

### 改ページ条件

該当なし（JSON配列として一括返却）

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| dscanner.iniファイル | DScanner設定の読み込み | ワークスペースルートディレクトリ配下のdscanner.iniパス |

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

#### dscanner.ini（INI設定ファイル）

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| [analysis.config]セクション | DScannerIniSection.name / description | ワークスペースcwd配下のdscanner.ini | StaticAnalysisConfig構造体の属性アノテーションから取得 |
| 各チェック項目 | DScannerIniFeature.name / enabled | 同上 | string型フィールドのみを対象に列挙 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| INIファイルパス | `buildPath(instance.cwd, "dscanner.ini")` | N/A | ファイルが存在しない場合はデフォルトの"dscanner.ini"を使用 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[served/getDscannerConfigリクエスト受信] --> B[SimpleTextDocumentIdentifierParamsからURI取得]
    B --> C[DscannerComponentの最適インスタンス取得]
    C --> D{インスタンス取得成功?}
    D -->|No| E[null返却]
    D -->|Yes| F[対象URI用のdscanner.iniパス決定]
    F --> G[DscannerComponent.getConfigでINI設定読み込み]
    G --> H[StaticAnalysisConfig構造体の属性からセクション情報抽出]
    H --> I[string型フィールドをループしフィーチャー情報構築]
    I --> J[DScannerIniSection配列として返却]
    J --> K[終了]
    E --> K
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| インスタンスなし | 指定URIに対応するDscannerComponentインスタンスが見つからない | N/A（null返却） | クライアント側で空結果として処理 |
| INIファイル不在 | ワークスペースルートにdscanner.iniが存在しない | N/A（デフォルト設定で動作） | デフォルトの"dscanner.ini"パスにフォールバック |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1セクション、約40-60フィーチャー項目 |
| 目標出力時間 | 100ms以下 |
| 同時出力数上限 | LSPリクエストキューに依存（通常1件） |

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

本帳票はローカルファイルシステム上のINI設定ファイルを読み込むのみであり、個人情報や機密データは含まない。アクセス制御はLSPサーバーのプロセス権限に依存する。

## 備考

- DScannerのStaticAnalysisConfig構造体は多数のチェック項目を持ち、各フィールドがstring型で"enabled"/"disabled"/"skip-unittest"の値を取る
- セクション情報は `__traits(getAttributes, ...)` を使用してコンパイル時にメタデータから取得される
- 本レスポンスは通常1つのセクション（analysis.config相当）のみを含む配列として返却される

---

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

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

### 推奨読解順序

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

まず、レスポンスとして返却されるデータ構造と、DScanner設定の型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protoext.d | `source/served/lsp/protoext.d` | `DScannerIniSection`構造体（258-266行目）と`DScannerIniFeature`構造体（269-277行目）の定義。レスポンスのJSON構造を決定する |
| 1-2 | protoext.d | `source/served/lsp/protoext.d` | `SimpleTextDocumentIdentifierParams`構造体（92-96行目）。リクエストパラメータの定義 |

**読解のコツ**: D言語の `@serdeIgnoreUnexpectedKeys` アノテーションはJSON逆シリアライズ時に未知のキーを無視する指定。mir.serdeライブラリの機能。

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

処理の起点となる関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | extension.d | `source/served/extension.d` | `getDscannerConfig`関数（1189-1224行目）。`@protocolMethod("served/getDscannerConfig")` アノテーションによりLSPリクエストハンドラとして登録される |

**主要処理フロー**:
1. **1189行目**: `@protocolMethod("served/getDscannerConfig")` でLSPメソッドとして登録
2. **1190行目**: `getDscannerConfig(SimpleTextDocumentIdentifierParams params)` 関数シグネチャ。`DScannerIniSection[]`を返却
3. **1194-1195行目**: `backend.getBestInstance!DscannerComponent` でURIに最適なDscannerインスタンスを取得
4. **1197-1198行目**: インスタンスが取得できない場合はnull返却
5. **1200-1202行目**: `getDscannerIniForDocument` でdscanner.iniファイルパスを決定
6. **1204行目**: `instance.get!DscannerComponent.getConfig(ini)` でINI設定を読み込み
7. **1206-1208行目**: `__traits(getAttributes, ...)` でセクションの説明とnameを取得
8. **1211-1221行目**: `config.tupleof` でフィールドをイテレートし、string型のみをフィーチャーとして抽出

#### Step 3: INIファイルパス解決を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | dscanner.d | `source/served/linters/dscanner.d` | `getDscannerIniForDocument`関数（121-133行目）。ドキュメントURIからdscanner.iniのパスを解決するロジック |

**主要処理フロー**:
- **121行目**: 関数定義。引数としてDocumentURIとオプションのインスタンスを受け取る
- **123-124行目**: インスタンスが未指定の場合、`backend.getBestInstance!DscannerComponent`で取得
- **129行目**: `buildPath(instance.cwd, "dscanner.ini")` でワークスペースルート配下のiniパスを構築
- **130-131行目**: ファイルが存在しない場合はデフォルトの `"dscanner.ini"` にフォールバック

#### Step 4: 設定構造体を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | types.d | `source/served/types.d` | `Configuration.DScanner`構造体（138-144行目）。ユーザー設定のDScanner関連部分の定義 |

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

```
served/getDscannerConfig (LSPリクエスト)
    │
    ├─ extension.getDscannerConfig()                    [extension.d:1189-1224]
    │      │
    │      ├─ backend.getBestInstance!DscannerComponent() [WorkspaceDインスタンス取得]
    │      │
    │      ├─ getDscannerIniForDocument()                [dscanner.d:121-133]
    │      │      └─ buildPath(instance.cwd, "dscanner.ini")
    │      │
    │      ├─ instance.get!DscannerComponent.getConfig() [INI設定読み込み]
    │      │
    │      └─ __traits(getAttributes, ...) / tupleof     [メタデータ抽出]
    │             └─ DScannerIniSection[] 構築・返却
    │
    └─ [LSP JSON-RPCレスポンス送信]
```

### データフロー図

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

SimpleTextDocument     ───▶  extension.getDscannerConfig()  ───▶  DScannerIniSection[]
IdentifierParams             │                                    (JSON配列)
  └─ textDocument.uri        ├─ URI → ワークスペース解決
                             ├─ dscanner.ini パス決定
dscanner.ini           ───▶  ├─ INI設定読み込み
(ファイルシステム)             └─ メタデータ抽出 → 構造体構築
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| extension.d | `source/served/extension.d` | ソース | getDscannerConfig関数の定義、LSPリクエストハンドラ |
| protoext.d | `source/served/lsp/protoext.d` | ソース | DScannerIniSection, DScannerIniFeature, SimpleTextDocumentIdentifierParams構造体の定義 |
| dscanner.d | `source/served/linters/dscanner.d` | ソース | getDscannerIniForDocument関数（INIファイルパス解決） |
| types.d | `source/served/types.d` | ソース | Configuration.DScanner構造体（ユーザー設定定義） |
| dscanner.ini | プロジェクトルート | 設定 | DScanner解析設定のINIファイル |
