アーキテクチャ: システム設計

全体的なアーキテクチャパターン

Rails FactoryBot Jump は プロバイダーベースアーキテクチャ と イベント駆動更新 および レイヤード関心分離 に従います。設計はパフォーマンス、保守性、VSCode 拡張エコシステムとのシームレスな統合を重視しています。

graph TB
    subgraph "VSCode Extension Host"
        A[拡張機能エントリーポイント] --> B[プロバイダー登録]
        A --> C[コマンド登録]
        A --> D[ファイルシステムウォッチャー]
    end

    subgraph "コアロジックレイヤー（v1.3.0で強化）"
        E[FactoryLinkProvider] --> F[CacheManager]
        E --> G[FactoryParser]
        E --> H[ConfigurationManager]
        E --> I[ErrorNotificationService]
        E --> J[FileSearcher]
    end

    subgraph "データレイヤー"
        K[ファクトリーキャッシュ]
        L[トレイトキャッシュ]
        M[ファイルキャッシュ]
    end

    subgraph "モデルレイヤー（v1.3.0で新規追加）"
        N[Factory]
        O[Location]
        P[Trait]
    end

    subgraph "外部システム"
        L[ファイルシステム]
        M[VSCode API]
        N[Ruby ファクトリーファイル]
    end

    B --> E
    F --> I
    F --> J
    F --> K
    G --> N
    D --> L
    H --> M

設計原則

1. 単一責任原則

各コンポーネントが一つの明確な目的を持っています：

• 拡張機能: ライフサイクルと VSCode 統合
• プロバイダー: ドキュメントリンク生成の統制
• CacheManager: ファクトリー定義の保存と取得の専門管理
• FactoryParser: Ruby ファクトリーファイルの解析
• ConfigurationManager: 拡張機能設定の管理
• ErrorNotificationService: エラーハンドリングとユーザー通知
• FileSearcher: ファクトリーファイルの検索と監視

2. 関心の分離

明確な境界：

• プラットフォーム統合（VSCode API）
• ビジネスロジック（ファクトリー検出とナビゲーション）
• データ管理（キャッシングとファイルシステム）
• データモデル（Factory、Location、Trait）
• サービス層（解析、キャッシュ、設定、エラーハンドリング）
• ユーティリティ層（パス操作、正規表現パターン）

3. イベント駆動アーキテクチャ

以下によるリアクティブ更新：

• ファイルシステムイベント → キャッシュ無効化
• 設定変更 → プロバイダー再設定
• ユーザーインタラクション → ナビゲーションコマンド

ソース: src/extension.ts#L28-L41

レイヤードアーキテクチャ

1. プレゼンテーション層（VSCode 統合）

拡張機能エントリーポイント (src/extension.ts):

• 拡張機能ライフサイクル管理（アクティベーション/非アクティベーション）
• VSCode にプロバイダーとコマンドを登録
• ファイルシステム監視をセットアップ
• 横断的関心事を処理

責任:

• VSCode API 統合
• リソース管理
• イベント調整
• 拡張機能設定

2. ビジネスロジック層（コア機能）

FactoryLinkProvider (src/providers/factoryLinkProvider.ts):

• VSCode DocumentLinkProvider インターフェースを実装
• ファクトリー検出とリンク生成を統制
• 設定変更を管理
• キャッシュ操作を調整

パターン検出エンジン:

• 正規表現ベースのファクトリー呼び出し検出
• マルチフォーマットサポート（括弧あり/なし）
• ファクトリーとトレイト認識
• 行精密マッチング

3. データアクセス層（キャッシングシステム）

キャッシュアーキテクチャ:

// 簡略化されたキャッシュ構造
class CacheSystem {
  factoryCache: Map<string, FactoryDefinition>;
  traitCache: Map<string, TraitDefinition>;
  fileCache: Map<string, vscode.Uri>;
}

キャッシュ操作:

• 読み取り: ファクトリー/トレイト名による O(1) 検索
• 書き込み: ファイル変更時のバッチ更新
• 無効化: 特定のファイル変更での対象無効化
• 更新: 必要時の完全再構築

ソース: src/providers/factoryLinkProvider.ts

コンポーネント相互作用パターン

1. 初期化フロー

sequenceDiagram
    participant VSCode
    participant Extension
    participant Provider
    participant Cache
    participant FileSystem

    VSCode->>Extension: activate(context)
    Extension->>Provider: new FactoryLinkProvider()
    Extension->>VSCode: registerDocumentLinkProvider(provider)
    Extension->>FileSystem: createFileSystemWatcher()
    Note over Provider: 遅延初期化
    VSCode->>Provider: provideDocumentLinks()
    Provider->>Cache: initializeFactoryFiles()
    Cache->>FileSystem: findFiles(factoryPaths)
    FileSystem-->>Cache: ファクトリーファイル URI
    Cache->>Cache: parseFactoryDefinitions()

2. リンク生成フロー

sequenceDiagram
    participant User
    participant VSCode
    participant Provider
    participant Detector
    participant Cache

    User->>VSCode: ファクトリー呼び出しにホバー
    VSCode->>Provider: provideDocumentLinks(document)
    Provider->>Detector: detectFactoryCalls(text)
    Detector-->>Provider: ファクトリー呼び出し範囲
    loop 各ファクトリー呼び出し
        Provider->>Cache: lookup(factoryName)
        Cache-->>Provider: ファクトリー定義
        Provider->>Provider: createDocumentLink()
    end
    Provider-->>VSCode: DocumentLink[]
    VSCode-->>User: クリック可能リンクを表示

3. キャッシュ更新フロー

sequenceDiagram
    participant FileSystem
    participant Watcher
    participant Provider
    participant Cache

    FileSystem->>Watcher: ファイル変更イベント
    Watcher->>Provider: initializeFactoryFiles()
    Provider->>Cache: clearAffectedEntries()
    Provider->>FileSystem: readChangedFiles()
    FileSystem-->>Provider: ファイル内容
    Provider->>Cache: updateDefinitions()
    Cache->>Cache: rebuildIndex()

設計パターン

1. プロバイダーパターン

意図: ドキュメントリンク生成のアルゴリズムをカプセル化。

実装:

class FactoryLinkProvider implements vscode.DocumentLinkProvider {
  provideDocumentLinks(document: vscode.TextDocument): vscode.DocumentLink[];
}

利点:

• VSCode 統合からの明確な分離
• テスト可能なビジネスロジック
• 交換可能な実装

2. オブザーバーパターン

意図: ファクトリーファイル変更時のリアクティブ更新。

実装:

• ファイルシステムウォッチャーがファイル変更を観察
• プロバイダーがキャッシュ更新によって変更に反応
• VSCode が自動的にリンクを更新

利点:

• リアルタイム更新
• コンポーネント間の疎結合
• 効率的なリソース利用

3. Cache-Aside パターン

意図: アプリケーションがデータソースとは別にキャッシュを管理。

実装:

• アプリケーションが最初にキャッシュをチェック
• キャッシュミス時、ファイルシステムから読み込み
• 新しいデータでキャッシュを更新
• ファイル変更時のキャッシュ無効化

利点:

• パフォーマンス最適化
• 明示的なキャッシュ制御
• キャッシング戦略の柔軟性

4. コマンドパターン

意図: ナビゲーション要求をオブジェクトとしてカプセル化。

実装:

vscode.commands.registerCommand(
  "rails-factorybot-jump.gotoLine",
  async (args: { uri: string; lineNumber: number }) => {
    // ナビゲーションロジック
  }
);

利点:

• 統一されたコマンドインターフェース
• パラメーター受け渡し
• VSCode コマンドシステムとの統合

ソース: src/extension.ts#L14-L26

このアーキテクチャは、将来の拡張に向けた柔軟性を維持しながら、最適なパフォーマンスとユーザーエクスペリエンスを確保する拡張機能の堅実な基盤を提供します。