# 画面設計書 270-コマンド検索

## 概要

本ドキュメントは、dbatoolsのコマンド検索機能に関する画面設計書です。dbatoolsコマンドのインラインヘルプテキストを検索し、タグ、作者、バージョン、パターンで絞り込んでコマンドを見つけることができるPowerShellコマンドを定義します。

### 本画面の処理概要

本機能は、dbatoolsコマンドのヘルプテキストを統合したJSONインデックスを構築・クエリすることで、高速なコマンド検索を提供するFind-DbaCommandコマンドを提供します。Get-Helpは処理が遅いため、キャッシュされたインデックスを使用します。

**業務上の目的・背景**：dbatoolsには数百のコマンドがあり、特定の機能や用途に適したコマンドを見つけることが困難です。本機能により、キーワード検索、タグ検索、作者検索など複数の方法でコマンドを効率的に発見できます。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスします。
```powershell
Find-DbaCommand "snapshot"
Find-DbaCommand -Tag Backup
```

**主要な操作・処理内容**：
1. インデックスファイルの存在確認（なければ構築）
2. インデックスファイルの読み込み
3. パターン、タグ、作者、バージョンによるフィルタリング
4. 検索結果の出力

**画面遷移**：
- 単独で使用するコマンド
- 取得結果は他の処理にパイプライン出力可能

**権限による表示制御**：
- 特別な権限は不要
- dbatoolsモジュールがインポートされている必要がある

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 315 | Find-DbaCommand | 主機能 | dbatoolsコマンドの検索 |

## 画面種別

CLI（コマンドラインインターフェース）- PowerShellコマンド

## URL/ルーティング

PowerShellコマンド: `Find-DbaCommand`

## 入出力項目

### パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Pattern | string | No | ヘルプテキスト全体を検索するパターン（位置パラメータ） |
| Tag | string[] | No | フィルタリング用タグ（複数指定時はAND条件） |
| Author | string | No | 作者名によるフィルタリング（ワイルドカード対応） |
| MinimumVersion | string | No | 最小dbatoolsバージョン |
| MaximumVersion | string | No | 最大dbatoolsバージョン |
| Rebuild | switch | No | インデックスを再構築 |
| EnableException | switch | No | 例外を有効化 |
| WhatIf | switch | No | 実行内容の表示 |
| Confirm | switch | No | 確認プロンプト |

## 表示項目

### 出力オブジェクト（PSCustomObject）

デフォルト表示プロパティ:

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CommandName | string | dbatoolsコマンドの名前 |
| Synopsis | string | コマンドの1行説明 |

追加プロパティ（Select-Object * で表示）:

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | コマンド関数の完全名 |
| Availability | string | プラットフォーム可用性（Windows, Linux, macOS等） |
| Alias | string | コマンドのエイリアス（カンマ区切り） |
| Description | string | コマンドの詳細説明 |
| Examples | string | ヘルプテキストの例セクション |
| Links | string | 関連ドキュメントリンク |
| Syntax | string | コマンドの完全構文 |
| Tags | string[] | 機能領域を分類するタグ配列 |
| Author | string | コマンド作者名 |
| MinimumVersion | string | 必要な最小dbatoolsバージョン |
| MaximumVersion | string | サポートする最大dbatoolsバージョン |
| Params | array | パラメータ情報の配列 |

## イベント仕様

### 1-インデックス構築（Get-DbaIndex内部関数）

```powershell
function Get-DbaIndex() {
    $dbamodule = Get-Module -Name dbatools
    $allCommands = $dbamodule.ExportedCommands.Values |
        Where-Object CommandType -In 'Function', 'Cmdlet' |
        Where-Object Name -NotIn 'Write-Message' |
        Sort-Object -Property Name |
        Select-Object -Unique

    $helpcoll = New-Object System.Collections.Generic.List[System.Object]
    foreach ($command in $allCommands) {
        $x = Get-DbaHelp "$command"
        $helpcoll.Add($x)
    }

    $dest = Resolve-Path "$moduleDirectory\bin\dbatools-index.json"
    $helpcoll | ConvertTo-Json -Depth 4 | Out-File $dest -Encoding Unicode
}
```

### 2-検索処理（processブロック）

1. パターンから末尾の's'を削除（単複形の揺れ対応）
2. インデックスファイルの存在確認
3. ファイルがない、または-Rebuild指定時はインデックス再構築
4. JSONファイルを読み込み、フィルタリング:
   - Pattern: 全プロパティ値をワイルドカード検索
   - Tag: 各タグで-Contains条件（AND条件）
   - Author: ワイルドカード検索
   - MinimumVersion: -GE条件
   - MaximumVersion: -LE条件
5. Select-DefaultViewでデフォルト表示プロパティを設定

### 3-フィルタリングロジック

```powershell
# パターン検索
$result = $result | Where-Object { $_.PsObject.Properties.Value -like "*$Pattern*" }

# タグ検索（AND条件）
foreach ($t in $Tag) {
    $result = $result | Where-Object Tags -Contains $t
}

# 作者検索
$result = $result | Where-Object Author -Like "*$Author*"

# バージョン範囲
$result = $result | Where-Object MinimumVersion -GE $MinimumVersion
$result = $result | Where-Object MaximumVersion -LE $MaximumVersion
```

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | N/A | データベースアクセスなし |

本コマンドはローカルファイルシステム上のインデックスファイルのみを操作し、データベースへのアクセスは行いません。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|--------------|---------|
| MSG001 | 情報 | Rebuilding index into $idxFile | インデックス再構築開始 |
| MSG002 | 情報 | Rebuild done in {ms}ms | インデックス再構築完了 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| インデックスファイルなし | 自動的にインデックスを構築 |

## 備考

- インデックスファイルは`$moduleDirectory\bin\dbatools-index.json`に保存
- インデックス構築時はGet-DbaHelp関数を使用して各コマンドのヘルプを取得
- Write-Messageコマンドはインデックスから除外される
- パターン検索はPsObject.Properties.Valueを対象とした広範な検索
- タグ検索は複数指定時にすべてのタグを含むコマンドのみを返す（AND条件）
- -Rebuildで開発者向けにインデックスの強制再構築が可能

---

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

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

### 推奨読解順序

#### Step 1: インデックス構築を理解する

beginブロック内のGet-DbaIndex関数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaCommand.ps1 | `public/Find-DbaCommand.ps1` | 行126-141のGet-DbaIndex関数 |

**読解のコツ**:
- 行128-129: エクスポートされたコマンドの取得とフィルタリング
- 行132-136: Get-DbaHelpでヘルプ情報を収集
- 行138-139: JSONファイルへの書き出し

#### Step 2: 検索処理を理解する

processブロックでの検索処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaCommand.ps1 | `public/Find-DbaCommand.ps1` | 行145-179のprocessブロック |

**主要処理フロー**:
1. **146行**: パターンから末尾の's'を削除
2. **147-153行**: インデックスファイルの確認と再構築
3. **154行**: JSONファイルの読み込み
4. **156-158行**: パターンフィルタリング
5. **160-164行**: タグフィルタリング
6. **166-168行**: 作者フィルタリング
7. **170-176行**: バージョン範囲フィルタリング
8. **178行**: デフォルト表示プロパティの設定

#### Step 3: 出力形式を理解する

インデックスに格納される情報の構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Find-DbaCommand.ps1 | `public/Find-DbaCommand.ps1` | 行90-113のOUTPUTSドキュメント |

**主要プロパティ**:
- デフォルト表示: CommandName, Synopsis
- 詳細: Name, Availability, Alias, Description, Examples, Links, Syntax
- メタデータ: Tags, Author, MinimumVersion, MaximumVersion, Params

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

```
Find-DbaCommand
    |
    +-- begin block
    |       |
    |       +-- Get-DbaIndex (内部関数定義)
    |               |
    |               +-- Get-Module -Name dbatools
    |               |       |
    |               |       +-- ExportedCommands取得
    |               |
    |               +-- foreach ($command in $allCommands)
    |               |       |
    |               |       +-- Get-DbaHelp "$command"
    |               |               |
    |               |               +-- $helpcoll.Add($x)
    |               |
    |               +-- ConvertTo-Json -Depth 4
    |                       |
    |                       +-- Out-File dbatools-index.json
    |
    +-- process block
            |
            +-- $Pattern.TrimEnd("s")
            |
            +-- Test-Path $idxFile
            |       |
            |       +-- false or $Rebuild: Get-DbaIndex呼び出し
            |
            +-- Get-Content -Raw $idxFile | ConvertFrom-Json
            |
            +-- Pattern フィルタ
            |       |
            |       +-- Where-Object { $_.PsObject.Properties.Value -like "*$Pattern*" }
            |
            +-- Tag フィルタ（AND条件）
            |       |
            |       +-- foreach: Where-Object Tags -Contains $t
            |
            +-- Author フィルタ
            |       |
            |       +-- Where-Object Author -Like "*$Author*"
            |
            +-- MinimumVersion フィルタ
            |       |
            |       +-- Where-Object MinimumVersion -GE $MinimumVersion
            |
            +-- MaximumVersion フィルタ
            |       |
            |       +-- Where-Object MaximumVersion -LE $MaximumVersion
            |
            +-- Select-DefaultView -Property CommandName, Synopsis
```

### データフロー図

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

                     +------------------+
                     | begin block      |
                     | Get-DbaIndex定義 |
                     +--------+---------+
                              |
                              v
Rebuild          -->+------------------+
                     | インデックス     |
                     | 存在確認         |
                     +--------+---------+
                              |
                    (なし or Rebuild)
                              |
                              v
                     +------------------+
                     | Get-DbaIndex     |
                     | 実行             |
                     | (Get-DbaHelp)    |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | dbatools-index   |
                     | .json 読み込み   |
                     +--------+---------+
                              |
                              v
Pattern          -->+------------------+
                     | プロパティ値     |
                     | ワイルドカード   |
                     +--------+---------+
                              |
                              v
Tag              -->+------------------+
                     | Tags             |
                     | Contains（AND）  |
                     +--------+---------+
                              |
                              v
Author           -->+------------------+
                     | Author           |
                     | Like             |
                     +--------+---------+
                              |
                              v
MinimumVersion/  -->+------------------+
MaximumVersion       | Version          |
                     | 範囲フィルタ     |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | Select-Default   |---> PSCustomObject[]
                     | View             |     (CommandName, Synopsis)
                     +------------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaCommand.ps1 | `public/Find-DbaCommand.ps1` | ソース | コマンド検索の主要ロジック |
| Get-DbaHelp.ps1 | `public/Get-DbaHelp.ps1` | 依存 | コマンドヘルプ情報の取得 |
| dbatools-index.json | `bin/dbatools-index.json` | データ | コマンドインデックスキャッシュ |
