Cloudstack MCP

🚀 差分包

diff パッケージは、予期される値と実際の値の間の差分を生成、比較、および可視化するためのツールを提供します。このパッケージはテストシナリオ向けに設計されていますが、差分の可視化が必要なあらゆるコンテキストで使用することができます。

✨ 主な機能

• go-cmp を使用した汎用型比較
• 文字列の統一差分形式に基づく比較をサポート
• 文字レベルの詳細なテキスト比較機能を提供
• 豊富な色と空白領域の可視化出力をサポート
• 構造体、マップ、基本型を含むさまざまなGo型を処理可能
• 反射を通じた複雑な型の比較

📚 モジュールアーキテクチャ

このパッケージは以下のモジュールによって組織されています：

1. コア差分ロジック（diff.go）：主なインターフェースと特定型の差分生成
2. 統一差分（udiff.go）：統一差分の解析とフォーマットの実装
3. 出力強化（enrich.go）：差分出力の色とフォーマットを向上させるためのもの
4. 型と値のフォーマット（convoluted.go）：Goの型と値のフォーマット比較を担当
5. テストツール（testing.go）：テストシナリオに適した機能の実装

💻 使用例

基本的な比較

package main

import (
    "fmt"
    "github.com/walteh/cloudstack-mcp/pkg/diff"
)

func main() {
    expected := "Hello, World!"
    actual := "Hello, Universe!"

    // 2つの文字列間の差分を生成
    result := diff.TypedDiff(expected, actual)

    // 差分結果を出力
    fmt.Println(result)
}

テストでの使用

package mypackage_test

import (
    "testing"
    "github.com/walteh/cloudstack-mcp/pkg/diff"
)

func TestSomething(t *testing.T) {
    expected := map[string]int{"a": 1, "b": 2}
    actual := map[string]int{"a": 1, "b": 3}

    // 値を比較し、不一致の場合はテストを失敗させる
    diff.RequireEqual(t, expected, actual)
}

複雑な型の比較

package mypackage_test

import (
    "reflect"
    "testing"
    "github.com/walteh/cloudstack-mcp/pkg/diff"
)

type MyStruct struct {
    Name string
    Age  int
    private string
}

func TestStructComparison(t *testing.T) {
    s1 := MyStruct{Name: "Alice", Age: 30, private: "secret"}
    s2 := MyStruct{Name: "Alice", Age: 31, private: "secret"}

    // 非公開フィールドを含む構造体を比較
    diff.RequireEqual(t, s1, s2, diff.WithUnexportedType[MyStruct]())
}

文字レベルの差分比較

package main

import (
    "fmt"
    "github.com/walteh/cloudstack-mcp/pkg/diff"
)

func main() {
    str1 := "Hello"
    str2 := "World"

    // 2つの文字列の文字差分を比較
    diff.Show(str1, str2)
}

🔧 拡張ポイント

このパッケージは、ユーザーが以下のインターフェースを実装するか、オプションを追加することでカスタム動作を可能にするように設計されています。

• diff.Comparator インターフェースを実装してカスタム比較ロジックを作成する。
• diff.WithOptions メソッドを使用して特定の差分生成パラメータを設定する。

💡 ベストプラクティス

1. 適切な比較方法の選択：

   • 単純な値には TypedDiff を使用する。
   • 複雑な構造体には RequireEqual を使用し、オプションを組み合わせて非公開フィールドを処理する。

2. 非公開フィールドを処理する場合：

   // WithUnexportedType オプションを使用して明示的にプライベートフィールドを比較
   diff.RequireEqual(t, a, b, diff.WithUnexportedType[type](...))
   

3. カスタム比較ロジックを使用する場合：

   type MyComparator struct{}
   
   func (MyComparator) Compare(a, b interface{}) string {
       // カスタム比較の実装
   }
   
   // カスタム比較器を登録
   diff.Register(diff.KeyType(reflect.TypeOf(a)), &MyComparator{})
   

🔙 旧バージョンとの互換性

新しいメソッドの使用を推奨しますが、パッケージは下位互換性を確保するために以下の旧関数をサポートしています。

• diff.Show()
• diff.DiffString()

これらの旧関数は徐々に廃止されており、新しいプロジェクトでは最新のインターフェースを優先して使用することをお勧めします。