# MaguyvaのPowerShell対応: スクリプトとモジュールのコードグラフ

Canonical source: https://maguyva.ai/ja/languages/powershell

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

MaguyvaはAST、シンボル、グラフでPowerShellに対応しています。AIエージェントはスクリプトとモジュール全体で、関数、クラス、コマンドレットの呼び出しをたどれます。

## 対応状況スナップショット

- 対応レベル: AST・シンボル対応
- シェル
- 拡張子: .ps1, .psd1, .psm1
- 構文を考慮した検索と構造コンテキストのための実際のAST解析。
- 名前付きシンボルはセマンティック検索と相互参照に利用されます。関係抽出が有効な場合は、グラフナビゲーションも利用できます。
- この言語は、グラフを考慮した検索にシンボルと関係情報を提供します。対応するエッジの種類は、その言語固有の構文要素によって異なります。
- AST解析とシンボル抽出の両方に対応しています。

## 最適な用途

- スクリプトが互いの関数を呼び合う、大規模な `.ps1` と `.psm1` の資産を持つインフラと運用のチーム。
- 高度な関数、クラス、列挙型で構築されたPowerShellモジュール。
- 変更の前に、どのスクリプトがサービス、ファイル共有、レジストリキーに触れるかをエージェントが確認する必要がある自動化のランブック。

## エージェントワークフロー

- 高度な関数のパラメーターを変更する前に、その呼び出し元をすべて見つける。
- ランブックを変更する前に、`Restart-Service` のようなコマンドレットを呼び出しているスクリプトを一覧にする。
- モジュールをリファクタリングする前に、共有変数に書き込む関数をマッピングする。

## PowerShellが浅いAIツールをつまずかせるところ

あなたの関数と組み込みのコマンドレットは、同じ命名スタイルを共有しています。`Get-Invoice` と `Get-ChildItem` は同じように見えるため、動詞で「組み込み」を除外するツールは、あなた自身の関数まで捨ててしまいます。スクリプトはまた、モジュールレベルのコード、関数、クラス、スクリプトブロックを1つのファイルに混在させるため、ある行がどの関数に属するかを見分けにくくなります。

Maguyvaは両方の種類の呼び出しを保持し、それぞれをそれが置かれた関数に帰属させます。

## MaguyvaがPowerShellで抽出するもの

Maguyvaは `.ps1`、`.psm1`、`.psd1` ファイルに対応しています。関数とクラスメソッドは呼び出し可能なものとして、クラスと列挙型は型として抽出されます。スクリプトとメソッドのパラメーターが追跡され、関数内の読み取りと書き込みはモジュールではなくその関数に帰属されます。

コマンドレットの呼び出しはグラフに残ります。PowerShellには、ほとんどの言語で使われる標準ライブラリのフィルターが適用されないため、`Write-Host`、`Get-ChildItem`、`Restart-Service` は、あなた自身の `Get-*` や `Set-*` の関数と並んで呼び出しのエッジとして表示されます。エージェントは、どのスクリプトがサービスを再起動するか、どの関数がコンソールに書き込むかを尋ねて、構造に基づいた答えを得られます。

PowerShellでは適用対象外とされる関係性の種類がないため、グラフにはクラスの継承とインターフェース実装、インスタンス化、制御フロー、読み取りと書き込みも記録されます。

## エージェントへのプロンプト例

- 「`Invoke-Backup` を呼び出しているのは誰で、どのスケジュール済みスクリプトからか？」（`find_symbol`、次に `dependency_search` の incoming）
- 「`Restart-Service` を呼び出している関数はどれか？」（`dependency_search`）
- 「`Deploy-Site` が最初から最後まで何をするかを追跡して。」（`get_task_context`）

## 既知の制限

- コマンドレットの呼び出しが保持されるため、`Write-Host` や `Select-Object` のような非常に一般的なものは、大量の incoming エッジを持ちます。焦点を絞ったコールグラフが必要なときは、あなた自身の関数から始めてください。
- `Import-Module` とドットソースは通常のコマンドなので、`structural_search` の `imports` プリセットは何も選択しません。それらを一覧にするには `text_pattern_search` を使ってください。

## 次のステップ

[クイックスタート](/ja/docs/quickstart)でリポジトリを接続し、[互換性ページ](/ja/docs/compatibility)で対応マトリクスを確認してください。スクリプトが呼び出す.NETのコードについては、[C#ガイド](/ja/languages/csharp)をご覧ください。

## エンジンの詳細

- PowerShellの対応は `.ps1`、`.psm1`、`.psd1` を含みます。関数とクラスメソッドは呼び出し可能なもので、クラスと列挙型は型です。
- PowerShellでは標準ライブラリのフィルターが無効なため、`Get-ChildItem` のようなコマンドレットの呼び出しは、あなた自身の関数と並んでグラフに残ります。
- 関数内の読み取りと書き込みは、モジュールではなくその関数に帰属されます。

## 役立つMCPエントリーポイント

- `find_symbol`: 定義と呼び出し元が必要なときに、高度な関数やクラスで使ってください。
- `dependency_search`: `Restart-Service` のようなコマンドレットに対してincomingのトラバーサルを使い、それを呼び出しているスクリプトを確認してください。
- `get_task_context`: 「`Deploy-Site` が最初から最後まで何をするかを追跡して」のようなプロンプトに使ってください。