# 機能設計書 87-Find-DbaCommand

## 概要

本ドキュメントは、dbatools PowerShellモジュールのFind-DbaCommand関数の機能設計を定義する。この関数は、dbatoolsコマンドをインラインヘルプテキストから検索する機能を提供する。

### 本機能の処理概要

Find-DbaCommand は、dbatoolsモジュール内のコマンドを、ヘルプテキスト全体を対象に検索するコマンドレットである。Get-Helpが遅いため、統合JSONインデックスを構築してクエリすることで高速な検索を実現している。

**業務上の目的・背景**：dbatoolsには700以上のコマンドがあり、目的のコマンドを見つけることが困難な場合がある。本機能は、キーワード検索、タグフィルター、作者フィルターなどの多様な検索方法を提供し、ユーザーが必要なコマンドを効率的に発見できるようにする。従来のGet-Helpコマンドは全コマンドのスキャンに時間がかかるため、事前構築されたインデックスを使用することで高速な検索を実現している。

**機能の利用シーン**：
- 特定のSQL Server機能に関連するコマンドの検索
- 特定の作者が書いたコマンドの一覧取得
- バックアップ、AG、ジョブなどの機能タグでのフィルタリング
- 新機能や概念の関連コマンド発見
- dbatoolsの学習・探索

**主要な処理内容**：
1. インデックスファイルの存在確認（なければ再構築）
2. JSONインデックスの読み込み
3. 指定されたフィルター条件での検索（Pattern、Tag、Author、Version）
4. 検索結果の出力

**関連システム・外部連携**：
- dbatoolsモジュールのコマンドヘルプシステム
- Get-DbaHelp 関数（インデックス構築時）
- ファイルシステム（インデックスファイル）

**権限による制御**：
- 特別な権限は不要
- インデックス再構築時はインデックスファイルへの書き込み権限が必要

## 関連画面

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

## 機能種別

検索 / ヘルプ機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Pattern | string | No | 検索パターン（ワイルドカード対応） | 末尾の"s"は自動トリム |
| Tag | string[] | No | コマンドタグでフィルター | 配列で指定時はAND条件 |
| Author | string | No | 作者名でフィルター | 部分一致 |
| MinimumVersion | string | No | 最小バージョンでフィルター | バージョン文字列 |
| MaximumVersion | string | No | 最大バージョンでフィルター | バージョン文字列 |
| Rebuild | switch | No | インデックスの強制再構築 | - |
| WhatIf | switch | No | 再構築の確認 | - |
| Confirm | switch | No | 再構築の確認プロンプト | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- インデックスファイル: `{moduleDirectory}/bin/dbatools-index.json`
- 再構築時: dbatoolsモジュールのエクスポートコマンドからヘルプを動的取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CommandName | string | コマンド名（デフォルト表示） |
| Synopsis | string | 概要説明（デフォルト表示） |
| Name | string | フル関数名 |
| Availability | string | プラットフォーム対応状況 |
| Alias | string | コマンドエイリアス |
| Description | string | 詳細説明 |
| Examples | string | 使用例 |
| Links | string | 関連リンク |
| Syntax | string | 構文情報 |
| Tags | string[] | コマンドタグ |
| Author | string | 作者名 |
| MinimumVersion | string | 最小バージョン |
| MaximumVersion | string | 最大バージョン |
| Params | object[] | パラメータ情報 |

### 出力先

- PowerShellパイプライン: PSCustomObjectとして出力
- デフォルト表示: CommandNameとSynopsisのみ

## 処理フロー

### 処理シーケンス

```
1. インデックスファイル確認
   ├─ 存在しない場合: 再構築実行
   └─ Rebuild指定時: 強制再構築

2. インデックス読み込み
   └─ Get-Content -Raw | ConvertFrom-Json

3. フィルター適用
   ├─ Pattern: 全プロパティに対するLike検索
   ├─ Tag: Tags配列にContains検索（複数タグはAND）
   ├─ Author: Author に対するLike検索
   ├─ MinimumVersion: 以上条件
   └─ MaximumVersion: 以下条件

4. 結果出力
   └─ Select-DefaultViewで表示プロパティ設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{インデックス存在?}
    B -->|No| C[Get-DbaIndex実行]
    B -->|Yes| D{Rebuild?}
    D -->|Yes| C
    D -->|No| E[インデックス読み込み]
    C --> E
    E --> F{Patternあり?}
    F -->|Yes| G[Patternフィルター]
    F -->|No| H{Tagあり?}
    G --> H
    H -->|Yes| I[Tagフィルター]
    H -->|No| J{Authorあり?}
    I --> J
    J -->|Yes| K[Authorフィルター]
    J -->|No| L{MinVer?}
    K --> L
    L -->|Yes| M[MinVersionフィルター]
    L -->|No| N{MaxVer?}
    M --> N
    N -->|Yes| O[MaxVersionフィルター]
    N -->|No| P[Select-DefaultView]
    O --> P
    P --> Q[結果出力]
    Q --> R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パターン正規化 | 末尾の"s"を自動トリム | 常時 |
| BR-002 | タグAND条件 | 複数タグ指定時は全タグを含むコマンドのみ | Tag配列指定時 |
| BR-003 | インデックス自動構築 | インデックスファイルが存在しない場合は自動構築 | 常時 |
| BR-004 | デフォルト表示制限 | 表示はCommandNameとSynopsisのみ | Select-DefaultView |

### 計算ロジック

インデックスファイルパス: `{$script:PSModuleRoot}/bin/dbatools-index.json`

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

本機能はデータベース操作を行わない。ファイルシステム上のインデックスファイルのみを使用する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| IndexReadError | 読み込みエラー | インデックスファイルの読み込み失敗 | -Rebuildで再構築 |
| IndexBuildError | 構築エラー | インデックス構築中のエラー | 権限とモジュール状態を確認 |

### リトライ仕様

自動リトライは実装されていない。インデックス構築時の個別コマンドエラーは無視されて続行される。

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

ファイル読み書きのみのため、トランザクション制御は不要。

## パフォーマンス要件

- インデックス読み込み: 数百ミリ秒
- 検索実行: 数十ミリ秒
- インデックス再構築: 数十秒（全コマンドのヘルプ取得のため）

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

- インデックスファイルは公開情報（ヘルプテキスト）のみを含む
- 特別なセキュリティ考慮は不要

## 備考

- インデックスはUnicodeエンコーディングで保存される
- インデックス再構築はShouldProcess対応
- Write-Messageは除外される

---

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

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

### 推奨読解順序

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

出力される検索結果オブジェクトの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaCommand.ps1 | `public/Find-DbaCommand.ps1` | 91-114行目の.OUTPUTS セクションでプロパティ一覧を確認 |

**読解のコツ**: インデックスファイルに保存されるデータ構造は Get-DbaHelp 関数で生成される。

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

パラメータ定義とインデックス管理関数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaCommand.ps1 | `public/Find-DbaCommand.ps1` | 115-124行目のparam()ブロック |
| 2-2 | Find-DbaCommand.ps1 | `public/Find-DbaCommand.ps1` | 125-141行目のbeginブロック |

**主要処理フロー**:
1. **126-141行目**: Get-DbaIndex内部関数の定義
2. **128-129行目**: モジュールのエクスポートコマンド取得
3. **133-136行目**: 各コマンドのヘルプ取得とコレクション追加
4. **138-139行目**: JSONファイルへの書き込み

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

インデックスの確認と再構築トリガーを確認する。

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

**主要処理フロー**:
- **146行目**: パターンの末尾"s"トリム
- **147行目**: インデックスファイルパスの解決
- **148-153行目**: インデックス存在確認と再構築判定

#### Step 4: 検索フィルター処理を理解する

各種フィルター条件の適用ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Find-DbaCommand.ps1 | `public/Find-DbaCommand.ps1` | 154-178行目のフィルター処理 |

**主要処理フロー**:
- **154行目**: JSONインデックスの読み込み
- **155行目**: 結果変数への初期代入
- **156-158行目**: Patternフィルター（全プロパティ対象のLike検索）
- **160-163行目**: Tagフィルター（複数タグはAND条件でループ）
- **166-167行目**: Authorフィルター
- **170-171行目**: MinimumVersionフィルター
- **174-175行目**: MaximumVersionフィルター

#### Step 5: 結果出力を理解する

Select-DefaultViewによる表示制御を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Find-DbaCommand.ps1 | `public/Find-DbaCommand.ps1` | 178行目の結果出力 |

**主要処理フロー**:
- **178行目**: Select-DefaultViewでCommandNameとSynopsisのみをデフォルト表示

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

```
Find-DbaCommand
    │
    ├─ Get-DbaIndex（内部関数、再構築時）
    │      ├─ Get-Module -Name dbatools
    │      │      └─ エクスポートコマンド取得
    │      │
    │      ├─ Get-DbaHelp
    │      │      └─ 各コマンドのヘルプ取得
    │      │
    │      └─ ConvertTo-Json | Out-File
    │             └─ インデックス保存
    │
    ├─ Get-Content -Raw
    │      └─ インデックス読み込み
    │
    ├─ ConvertFrom-Json
    │      └─ JSONパース
    │
    └─ Select-DefaultView
           └─ 表示プロパティ設定
```

### データフロー図

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

Pattern ──────┐
              │
Tag ──────────┼──▶ インデックス読み込み
              │    (dbatools-index.json)
Author ───────┤           │
              │           ▼
MinVersion ───┤    フィルターチェーン
              │    Pattern → Tag → Author
MaxVersion ───┘    → MinVer → MaxVer
                          │
                          ▼
                   Select-DefaultView
                          │
                          ▼
                   PSCustomObject ──────▶ パイプライン出力
                   (CommandName,Synopsis)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaCommand.ps1 | `public/Find-DbaCommand.ps1` | ソース | メイン関数定義 |
| Get-DbaHelp.ps1 | `private/functions/Get-DbaHelp.ps1` | ソース | コマンドヘルプ取得 |
| dbatools-index.json | `bin/dbatools-index.json` | データ | コマンドインデックス |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | 表示プロパティ制御 |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | メッセージ出力関数 |
