# 機能設計書 102-エイリアス

## 概要

本ドキュメントは、Windows Console Host (conhost.exe) におけるコマンドエイリアス管理機能について記述する。Aliasクラスとグローバルエイリアスデータ(g_aliasData)を中心に、エイリアスの登録・取得・削除・展開処理と、Win32 Console API経由での外部公開インターフェースを設計レベルで詳述する。

### 本機能の処理概要

**業務上の目的・背景**：コマンドエイリアスは、頻繁に使用するコマンドに短いショートカット名を付けて、入力効率を向上させる機能である。Windows環境ではdoskeyコマンドでエイリアスを設定でき、cmd.exeなどのCUIアプリケーションで利用される。本機能はそのエイリアスデータの管理と展開処理を担う。

**機能の利用シーン**：ユーザーが`doskey ls=dir`のようにエイリアスを設定し、以降`ls`と入力するだけで`dir`コマンドが実行されるシーンで利用される。エイリアスは$1-$9(引数置換)、$*(全引数置換)、$t(改行)、$l(<)、$g(>)、$b(|)などの特殊変数をサポートする。

**主要な処理内容**：
1. EXE名ごとにエイリアス(source=target)のペアを管理する
2. コマンド入力時にエイリアスの展開処理を行う（s_MatchAndCopyAlias）
3. 特殊変数($1-$9, $*, $t, $l, $g, $b)の展開をサポートする
4. Win32 Console API (AddConsoleAlias, GetConsoleAlias等)経由で外部公開する
5. 大文字小文字を区別しないマッチングを行う

**関連システム・外部連携**：Win32 Console API (kernel32.dll) を通じてクライアントプロセスと連携する。

**権限による制御**：コンソールのロック機構(LockConsole/UnlockConsole)によるスレッドセーフティが確保されている。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コンソールウィンドウ | 主画面 | コマンド入力時のエイリアス展開 |

## 機能種別

データ管理（CRUD操作）/ 文字列処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| source | wstring_view | Yes | エイリアス名（ショートカット） | 空でないこと(E_INVALIDARG) |
| target | wstring_view | Yes | 展開先コマンド文字列 | 空の場合はエイリアス削除 |
| exeName | wstring_view | Yes | 対象EXE名 | - |
| sourceText | wstring_view | Yes | マッチ対象のコマンドライン文字列 | - |

### 入力データソース

- doskeyコマンドまたはWin32 Console APIからの登録
- コマンドライン入力バッファからのマッチング対象テキスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| expandedCommand | wstring | 展開後のコマンド文字列 |
| lineCount | size_t | 展開後の行数($t区切り) |
| aliasBuffer | wchar_t[] | 全エイリアス一覧(source=target形式) |

### 出力先

- コマンドライン入力ストリームへの展開結果の注入
- Win32 Console API経由でのクライアントバッファへの返却

## 処理フロー

### 処理シーケンス

```
1. エイリアス登録 (AddConsoleAlias)
   └─ sourceが空ならE_INVALIDARG
      └─ targetが空ならエイリアス削除
         └─ そうでなければ登録(大文字小文字を正規化)

2. エイリアス展開 (s_MatchAndCopyAlias)
   └─ 入力テキストをスペースで分割(最大10引数)
      └─ 最初の語をエイリアス名として検索
         └─ 見つかれば特殊変数を展開して返却
            └─ $1-$9: 対応する引数に置換
            └─ $*: 全引数に置換
            └─ $t: 改行(\r\n)に置換
            └─ $l/$g/$b: </>/ | に置換
```

### フローチャート

```mermaid
flowchart TD
    A[コマンド入力] --> B{EXEのエイリアスデータ存在?}
    B -->|No| Z[そのまま実行]
    B -->|Yes| C[入力をスペースで分割]
    C --> D{先頭語がエイリアス?}
    D -->|No| Z
    D -->|Yes| E[ターゲット文字列を走査]
    E --> F{特殊変数あり?}
    F -->|$1-$9| G[対応引数で置換]
    F -->|$*| H[全引数で置換]
    F -->|$t| I[改行を挿入]
    F -->|$l,$g,$b| J[特殊文字で置換]
    F -->|なし| K[そのまま出力]
    G --> L[展開結果を返却]
    H --> L
    I --> L
    J --> L
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-102-1 | 大文字小文字無視 | エイリアス名とEXE名の比較は大文字小文字を区別しない | 常時 |
| BR-102-2 | 空ターゲットで削除 | targetが空の場合、該当エイリアスを削除する | AddConsoleAlias時 |
| BR-102-3 | 最大10引数 | エイリアス展開時の引数分割は最大10個まで | s_MatchAndCopyAlias |
| BR-102-4 | 先頭語マッチ | コマンドラインの最初のスペース区切り語のみがエイリアス名としてマッチされる | 展開時 |

### 計算ロジック

特殊変数の展開ルール：$1-$9は対応する引数インデックスの値に、$*はargs[1]からsourceTextの末尾までに置換される。

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

本機能はデータベースを使用しない。グローバル変数g_aliasData（ネストされたunordered_map）でメモリ内管理される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E_INVALIDARG | 引数不正 | source文字列が空 | HRESULTを返却 |
| ERROR_GEN_FAILURE | 汎用失敗 | EXEまたはソースが見つからない | HRESULTを返却 |
| ERROR_INSUFFICIENT_BUFFER | バッファ不足 | 出力バッファが小さすぎる | HRESULTを返却 |

### リトライ仕様

リトライは不要。

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

LockConsole/UnlockConsoleによるスレッド排他制御で一貫性を保証する。

## パフォーマンス要件

- エイリアスの登録・取得はハッシュマップベースでO(1)期待
- エイリアス展開はO(n)（ターゲット文字列の長さに比例）

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

- エイリアスはプロセスセッション内に限定される
- 悪意のあるエイリアスによるコマンドインジェクションのリスクがある（ユーザーの意図的な設定に依存）

## 備考

- g_aliasDataの型は `unordered_map<wstring, unordered_map<wstring, wstring, case_insensitive_hash, case_insensitive_equality>, case_insensitive_hash, case_insensitive_equality>` という3階層のネスト構造
- case_insensitive_hash/case_insensitive_equalityはtransparent comparatorパターンを使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | alias.h | `src/host/alias.h` | Aliasクラスの静的メソッド宣言 |
| 1-2 | alias.cpp | `src/host/alias.cpp` | g_aliasDataの型定義(47-54行目)とcase_insensitiveハッシュ/比較(22-45行目) |

**読解のコツ**: g_aliasDataは2階層のunordered_mapで、外側のキーがEXE名、内側のキーがエイリアス名、値がターゲット文字列。

#### Step 2: エイリアス登録を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | alias.cpp | `src/host/alias.cpp` | AddConsoleAliasWImpl(91-127行目) |

**主要処理フロー**:
1. **98行目**: sourceが空ならE_INVALIDARG
2. **106-107行目**: EXE名とソースを小文字に正規化
3. **109-116行目**: targetが空ならエイリアスを削除
4. **121行目**: 空でなければg_aliasDataに登録

#### Step 3: エイリアス展開を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | alias.cpp | `src/host/alias.cpp` | s_MatchAndCopyAlias(834-965行目) |

**主要処理フロー**:
- **850-880行目**: 入力テキストをスペースで最大10引数に分割
- **889-893行目**: 先頭語でエイリアスを検索
- **904-958行目**: ターゲット文字列を走査し、$エスケープシーケンスを展開

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

```
Alias (静的クラス)
    |
    +-- s_MatchAndCopyAlias(sourceText, exeName) ... コマンド確定時の展開
    |       +-- g_aliasData.find(exeName)        ... EXEデータ検索
    |       +-- exeList.find(args[0])            ... エイリアス名検索
    |       +-- $変数展開ループ                   ... ターゲット文字列の展開
    |
    +-- ApiRoutines::AddConsoleAliasWImpl        ... エイリアス登録/削除
    +-- ApiRoutines::GetConsoleAliasWImpl        ... エイリアス取得
    +-- ApiRoutines::GetConsoleAliasesWImpl      ... 全エイリアス一覧取得
    +-- ApiRoutines::GetConsoleAliasExesWImpl    ... 全EXE名一覧取得
    +-- Alias::s_ClearCmdExeAliases             ... cmd.exeのエイリアスクリア
```

### データフロー図

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

doskey/API登録 -----------> AddConsoleAliasWImpl -----------> g_aliasData
                                                               (メモリ内Map)

コマンドライン入力 -------> s_MatchAndCopyAlias -----------> 展開済みコマンド文字列
                               +-- 引数分割                     (lineCount付き)
                               +-- エイリアス検索
                               +-- $変数展開

API取得リクエスト --------> GetConsoleAliasWImpl -----------> クライアントバッファ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| alias.h | `src/host/alias.h` | ソース(ヘッダ) | Aliasクラスの宣言 |
| alias.cpp | `src/host/alias.cpp` | ソース(実装) | エイリアス管理の実装全体 |
| ApiRoutines.h | `src/host/ApiRoutines.h` | ソース(ヘッダ) | Win32 Console APIルーティンの宣言 |
| convert.hpp | `src/types/inc/convert.hpp` | ソース(ヘッダ) | A/W文字列変換ユーティリティ |
