# バッチ設計書 68-Build-SupportedSequenceIndex.ps1

## 概要

本ドキュメントは、ソースコードをスキャンしてサポートされるVTシーケンスの一覧を生成するPowerShellスクリプト `Build-SupportedSequenceIndex.ps1` のバッチ設計書である。ITermDispatchインターフェース、ConsoleHostアダプタ、Terminalアダプタの各ソースファイルを解析し、VTシーケンスのサポート状況をMarkdown形式のドキュメントとして出力する。

### 本バッチの処理概要

本スクリプトは、Windows Terminal/ConsoleHostのソースコードを解析し、VT100互換のターミナルシーケンス（エスケープシーケンス）のサポート状況をマスターリストとコードの実装状況を照合してMarkdownドキュメントを自動生成する。

**業務上の目的・背景**：Windows Terminal/ConsoleHostプロジェクトは多数のVTシーケンスをサポートしており、どのシーケンスが実装済みかを把握することはドキュメント維持の観点で重要である。手動でサポート一覧を管理するのは非現実的であるため、本スクリプトはソースコードを正規表現でスキャンし、ITermDispatchベースインターフェースのメソッド定義、ConsoleHostアダプタとTerminalアダプタのoverride実装を自動検出する。これにより、常にコードと同期したVTシーケンスサポート一覧を生成できる。

**バッチの実行タイミング**：ドキュメント更新時に開発者が手動で実行する。リリース前のドキュメント生成にも使用される。

**主要な処理内容**：
1. master-sequence-list.csvからVTシーケンスのマスターリストを読み込む
2. ITermDispatch.hppからベースインターフェースのメソッドを正規表現で抽出し、コメントに記載されたシーケンス名とマッピングする
3. adaptDispatch.hppからConsoleHostアダプタのoverride実装を正規表現で検出する
4. terminalDispatch.hppからTerminalアダプタのoverride実装を正規表現で検出する
5. マスターリストの各シーケンスに対して、ConsoleHost/Terminalそれぞれの実装状況（行番号リンク付き）を付与する
6. Markdown形式のVT Function Supportドキュメントを生成する
7. サマリー情報（既知シーケンス数、実装数等）を表示する

**前後の処理との関連**：doc/reference/配下のmaster-sequence-list.csvとwindows-terminal-logo.ansを参照する。生成されたMarkdownはドキュメントサイトやリポジトリのdoc/referenceに配置される。

**影響範囲**：標準出力またはファイル出力としてMarkdownドキュメントを生成する。ソースコードの変更は行わない。

## バッチ種別

ドキュメント生成 / コード解析

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（ドキュメント更新時） |
| 実行時刻 | 手動実行 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 開発者による手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| PowerShell 6.1以上 | `#requires -version 6.1` による要件 |
| master-sequence-list.csv | カレントディレクトリにVTシーケンスのマスターリストが存在すること |
| ソースファイル | ITermDispatch.hpp, adaptDispatch.hpp, terminalDispatch.hppが参照可能であること |

### 実行可否判定

master-sequence-list.csvと各ソースファイルが指定パスに存在すること。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| OutFile | string | No（fileセット時は必須） | なし | 出力ファイルパス |
| Force | switch | No | $false | 既存ファイルを上書きするか |
| NoLogo | switch | No | $false | サマリーにロゴを表示しない |
| SummaryOnly | switch | No | $false | Markdown生成をスキップしサマリーのみ表示 |
| Quiet | switch | No | $false | サマリーもロゴも表示しない |
| SolutionRoot | string | No | "..\.." | ソリューションルートパス |
| InterfacePath | string | No | {SolutionRoot}\src\terminal\adapter\ITermDispatch.hpp | ベースインターフェースファイルパス |
| ConsoleAdapterPath | string | No | {SolutionRoot}\src\terminal\adapter\adaptDispatch.hpp | ConsoleHostアダプタファイルパス |
| TerminalAdapterPath | string | No | {SolutionRoot}\src\cascadia\terminalcore\terminalDispatch.hpp | Terminalアダプタファイルパス |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| master-sequence-list.csv | CSV | VTシーケンスのマスターリスト（Sequence, Parent, Description, Origin, Heading, Subheading, ImplementedBy, ConsoleHost, Terminal） |
| ITermDispatch.hpp | C++ヘッダー | ターミナルディスパッチのベースインターフェース |
| adaptDispatch.hpp | C++ヘッダー | ConsoleHostアダプタの実装宣言 |
| terminalDispatch.hpp | C++ヘッダー | Terminalアダプタの実装宣言 |
| windows-terminal-logo.ans | ANSIアート | サマリー表示用ロゴ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力またはファイル | Markdown | VT Function Supportドキュメント |
| 標準出力 | テキスト | サマリー情報（シーケンス数、実装数） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | OutFileパラメータで指定（stdoutの場合はなし） |
| 出力先 | OutFileパラメータで指定 |
| 文字コード | UTF-8（BOMなし: utf8NoBOM） |
| 区切り文字 | Markdown形式 |

## 処理フロー

### 処理シーケンス

```
1. パラメータ解析
   └─ ParameterSetName（stdout/file）に基づき出力先を決定
2. グローバル変数初期化
   └─ バージョン（0.6-beta）、マスターリスト読み込み、ハッシュテーブル初期化
3. Read-SourceFiles実行
   └─ ITermDispatch.hppからベースメソッドとシーケンスのマッピング抽出
   └─ adaptDispatch.hppからoverride実装のメソッド名と行番号抽出
   └─ terminalDispatch.hppからoverride実装のメソッド名と行番号抽出
4. Markdown生成（SummaryOnlyでない場合）
   └─ Get-SequenceIndexMarkdown関数でMarkdown文字列を構築
   └─ 各シーケンスにConsoleHost/Terminalの実装状況をマッピング
   └─ Heading/Subheadingに基づくセクション構造を生成
   └─ vt100.netへのリンクとGitHubソースコードリンクを付与
5. 出力
   └─ fileモード: Out-Fileで書き出し
   └─ stdoutモード: 標準出力に出力
6. サマリー表示（Quietでない場合）
   └─ Show-Summary関数でシーケンス数、実装数を表示
   └─ NoLogoでなければwindows-terminal-logo.ansを表示
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[パラメータ解析]
    B --> C[master-sequence-list.csv読み込み]
    C --> D[Read-SourceFiles: ソースコードスキャン]
    D --> D1[ITermDispatch.hpp: ベースメソッド抽出]
    D --> D2[adaptDispatch.hpp: ConsoleHost実装検出]
    D --> D3[terminalDispatch.hpp: Terminal実装検出]
    D1 --> E{SummaryOnly?}
    D2 --> E
    D3 --> E
    E -->|No| F[Get-SequenceIndexMarkdown: Markdown生成]
    F --> G{出力モード}
    G -->|file| H[Out-Fileで書き出し]
    G -->|stdout| I[標準出力に出力]
    H --> J{Quiet?}
    I --> J
    E -->|Yes| K[Show-Summary]
    J -->|No| K
    J -->|Yes| L[バッチ終了]
    K --> L
```

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

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

データベース操作は行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | - |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル未検出 | master-sequence-list.csvまたはソースファイルが見つからない場合 | SolutionRootパラメータを正しく設定する |
| - | 正規表現不一致 | ソースコードの形式がスキャナーの期待と異なる場合 | スキャナーの正規表現を更新する |
| - | ファイル書き込みエラー | OutFileの書き込みに失敗した場合 | パスと権限を確認する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

ソースファイルのパスを確認し、SolutionRootパラメータが正しいことを検証する。正規表現によるスキャンが失敗する場合、ソースコードのフォーマット変更がないか確認する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | マスターリストのシーケンス数 + 3つのソースファイル解析 |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

排他制御は不要。読み取り専用の操作がメインであり、ファイル出力モード時のみ出力ファイルへの書き込みが発生する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| Verbose | stdout出力モード時 | `Emitting markdown to STDOUT` |
| Host出力 | サマリー表示時 | シーケンス数、ベースメソッド数、ConsoleHost/Terminal実装数 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | - |

## 備考

- スクリプトバージョン: 0.6-beta（semver形式）
- ベースインターフェースの正規表現: `virtual\s\w+\s(?<method>\w+)...` でメソッド名を抽出し、`//`コメントのシーケンス名とマッピング
- override実装の正規表現: `\s+\w+\s(?<method>\w+)...override;` でメソッド名と行番号を抽出
- 生成されるMarkdownにはvt100.netへのリンク（各シーケンスの参照ページ）とGitHubリポジトリへのソースコードリンク（行番号付き）が含まれる
- Table of Contentsは手動で定義されており、自動生成はTODOとして残されている
- 出力Markdownの末尾に生成日時が付与される
- ソースファイル: `doc/reference/Build-SupportedSequenceIndex.ps1`
