JA Getting Started Architecture Overview - hiraishikentaro/rails-factorybot-jump GitHub Wiki

はじめに: アーキテクチャ概要

高レベルシステム設計

Rails FactoryBot Jump は VSCode 拡張のエコシステムに典型的なプロバイダーベースアーキテクチャパターンに従い、ファクトリー検出とナビゲーション用の特殊なコンポーネントを備えています。

graph TB
    A[VSCode Ruby ファイル] --> B[拡張機能アクティベーション]
    B --> C[FactoryLinkProvider 登録]
    C --> D[ファイルシステムウォッチャー]
    C --> E[ファクトリーキャッシュ初期化]

    F[ユーザーがファクトリー呼び出しにホバー] --> G[ドキュメントリンクプロバイダー]
    G --> H[ファクトリー検出 Regex]
    H --> I[キャッシュ検索]
    I --> J[クリック可能リンク生成]

    K[ファクトリーファイル変更] --> D
    D --> L[キャッシュ更新]
    L --> E

    M[ユーザーがリンクをクリック] --> N[VSCode コマンド]
    N --> O[定義にジャンプ]

コアコンポーネント

1. 拡張機能エントリーポイント

ファイル: src/extension.ts

メイン拡張機能がシステム全体を統制します：

アクティベーション: Ruby 言語ファイルでトリガー
プロバイダー登録: Ruby ファイル用のドキュメントリンクプロバイダーを登録
コマンド登録: goto-line コマンドをセットアップ
ファイル監視: キャッシュ更新のためファクトリーファイル変更を監視
ライフサイクル管理: アクティベーションと非アクティベーションを処理

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

2. ファクトリーリンクプロバイダー

ファイル: src/providers/factoryLinkProvider.ts

拡張機能のコアインテリジェンス：

ファクトリー検出: 正規表現パターンを使用してテストファイル内のファクトリー呼び出しを識別
キャッシュ管理: ファクトリーとトレイト用のインメモリキャッシュを維持
リンク生成: クリック可能な VSCode ドキュメントリンクを作成
設定処理: ユーザー設定の変更を読み取りそれに応答

データフローアーキテクチャ

1. 初期化フロー

sequenceDiagram
    participant VSCode
    participant Extension
    participant Provider
    participant FileSystem

    VSCode->>Extension: Ruby ファイルでアクティベート
    Extension->>Provider: FactoryLinkProvider を作成
    Extension->>VSCode: ドキュメントリンクプロバイダーを登録
    Provider->>FileSystem: ファクトリーパス設定を読み取り
    Provider->>FileSystem: ファクトリーファイルをスキャン
    Provider->>Provider: ファクトリーとトレイトキャッシュを構築

2. リンク検出フロー

sequenceDiagram
    participant User
    participant VSCode
    participant Provider
    participant Cache

    User->>VSCode: ファクトリー呼び出しにホバー
    VSCode->>Provider: ドキュメントリンクを要求
    Provider->>Provider: 正規表現検出を実行
    Provider->>Cache: ファクトリー/トレイトを検索
    Cache->>Provider: ファイル URI と行を返す
    Provider->>VSCode: ドキュメントリンクを生成
    VSCode->>User: クリック可能リンクを表示

3. ナビゲーションフロー

sequenceDiagram
    participant User
    participant VSCode
    participant Extension
    participant FileSystem

    User->>VSCode: ファクトリーリンクをクリック
    VSCode->>Extension: gotoLine コマンドを実行
    Extension->>FileSystem: ターゲットファイルを開く
    Extension->>VSCode: 特定の行にナビゲート
    VSCode->>User: ファクトリー定義を表示

キャッシング戦略

ファクトリーキャッシュ構造

// 簡略化されたキャッシュ構造
factoryCache: Map<string, { uri: vscode.Uri; lineNumber: number }>;
traitCache: Map<
  string,
  { uri: vscode.Uri; lineNumber: number; factory: string }
>;

キャッシュ操作

構築: すべてのファクトリーファイルをスキャンして定義を抽出
検索: ファクトリー/トレイト名による高速 O(1) 取得
更新: ファイルシステム変更によってトリガー
優先度: 最初に見つかった定義が優先

ソース: src/providers/factoryLinkProvider.ts

パターン認識

ファクトリー検出正規表現

拡張機能は様々な FactoryBot 呼び出し形式を検出するため、洗練された正規表現パターンを使用します：

(?:create|create_list|build|build_list|build_stubbed|build_stubbed_list)\s*(?:\(\s*)?((:[a-zA-Z0-9_]+)(?:\s*,\s*(:[a-zA-Z0-9_]+))*)\s*(?:,\s*[^)]*)?(?:\)|\n|$)

サポート内容:

複数のファクトリーメソッド（create、build、create_list など）
括弧ありと括弧なし構文
ファクトリー名とトレイト
複雑なパラメーター処理

ファクトリー定義検出

factory\s+:([a-zA-Z0-9_]+)\b
trait\s+:([a-zA-Z0-9_]+)\s+do

抽出内容:

factory :name 定義からのファクトリー名
trait :name do ブロックからのトレイト名
ナビゲーション用の正確な行番号

設定アーキテクチャ

設定スキーマ

{
  "rails-factorybot-jump.factoryPaths": {
    "type": "array",
    "default": ["spec/factories/**/*.rb"],
    "description": "ファクトリーファイルを検索するパス"
  }
}

設定フロー

読み込み: VSCode ワークスペース設定から読み取り
検証: パスが有効な glob パターンであることを確認
適用: ファイル監視とキャッシュ構築を更新
更新: 設定変更時にキャッシュを再構築

ソース: package.json#L52-L66

パフォーマンス考慮事項

最適化戦略

遅延読み込み: ファクトリーファイルは必要時にのみスキャン
効率的なキャッシング: O(1) 検索のためのインメモリマップ
増分更新: ファイルウォッチャーが対象を絞ったキャッシュ更新をトリガー
正規表現最適化: 高速テキスト処理のためのコンパイル済みパターン

メモリ管理

キャッシュサイズ: プロジェクトサイズによって制限（通常 < 1MB）
クリーンアップ: 拡張機能非アクティベーション時の自動クリーンアップ
更新: 完全再構築ではなく増分

エラーハンドリング

グレースフル劣化

ファイル不足: ファクトリーファイルが存在しない場合のサイレントフォールバック
無効なパターン: 不正なファクトリー定義をスキップ
権限問題: 利用可能なファイルで操作を継続
正規表現失敗: 拡張機能をクラッシュさせずにエラーをログ

統合ポイント

VSCode API

ドキュメントリンクプロバイダー: コアナビゲーションインターフェース
ファイルシステムウォッチャー: リアルタイムファイル変更検出
コマンド: カスタムナビゲーションコマンド
設定: 設定統合
ワークスペース: マルチフォルダワークスペースサポート

外部依存関係

Node.js: ランタイム環境
TypeScript: 開発言語
VSCode Extension API: プラットフォーム統合
ファイルシステム: ファクトリーファイル検出と読み取り

次のステップ

コア概念 - 重要な概念の理解
技術スタック - 詳細な技術概要
システム設計 - 詳細なシステムアーキテクチャ