JA Architecture Module Structure - hiraishikentaro/rails-factorybot-jump GitHub Wiki

アーキテクチャ: モジュール構造

コード組織概要

Rails FactoryBot Jump 拡張機能は、明確な責任分離と明確に定義されたモジュール境界を持つモジュラーアーキテクチャに従っています。

src/
├── extension.ts              # 拡張機能エントリポイントとライフサイクル
├── constants/
│   └── defaults.ts          # デフォルト設定値
├── providers/
│   └── factoryLinkProvider.ts # コアビジネスロジック
├── models/                   # データモデル（v1.3.0で追加）
│   ├── factory.ts           # ファクトリー定義モデル
│   ├── location.ts          # ロケーション情報モデル
│   └── trait.ts             # トレイト定義モデル
├── services/                 # ビジネスサービス（v1.3.0で追加）
│   ├── cacheManager.ts      # キャッシュ管理サービス
│   ├── configurationManager.ts # 設定管理サービス
│   ├── errorNotificationService.ts # エラー通知サービス
│   ├── factoryParser.ts     # ファクトリー解析サービス
│   └── fileSearcher.ts      # ファイル検索サービス
├── utils/                    # ユーティリティ関数（v1.3.0で追加）
│   ├── pathUtils.ts         # パス操作ユーティリティ
│   └── regexPatterns.ts     # 正規表現パターン
└── test/
    ├── runTest.ts           # テストランナー設定
    ├── runUnitTests.ts      # ユニットテストランナー（v1.3.0で追加）
    ├── suite/               # 統合テスト
    │   ├── index.ts         # テストスイート設定
    │   └── extension.test.ts # メイン統合テストスイート
    └── unit/                # ユニットテスト（v1.3.0で追加）
        ├── index.ts         # ユニットテスト設定
        ├── models/          # モデルテスト
        │   ├── factory.test.ts
        │   ├── location.test.ts
        │   └── trait.test.ts
        ├── services/        # サービステスト
        │   ├── cacheManager.test.ts
        │   └── factoryParser.test.ts
        ├── utils/           # ユーティリティテスト
        │   └── regexPatterns.test.ts
        └── unitTestsRunner.ts # ユニットテスト実行ランナー

コアモジュール

1. 拡張機能エントリポイント（extension.ts）

目的: メイン拡張機能ライフサイクル管理と VSCode 統合。

主要責任:

  • 拡張機能のアクティベーションとデアクティベーション
  • プロバイダーとコマンドの登録
  • ファイルシステムウォッチャーの設定
  • リソース管理

パブリックインターフェース:

export function activate(context: vscode.ExtensionContext): void;
export function deactivate(): void;

依存関係:

  • vscode - VSCode 拡張機能 API
  • ./providers/factoryLinkProvider - コアビジネスロジック

内部構造:

function activate(context: vscode.ExtensionContext) {
  // プロバイダー登録
  const provider = new FactoryLinkProvider();
  context.subscriptions.push(
    vscode.languages.registerDocumentLinkProvider(
      { scheme: "file", language: "ruby" },
      provider
    )
  );

  // コマンド登録
  context.subscriptions.push(
    vscode.commands.registerCommand(
      "rails-factorybot-jump.gotoLine",
      gotoLineHandler
    )
  );

  // ファイルシステムウォッチャー
  const watcher = vscode.workspace.createFileSystemWatcher(
    "**/factories/**/*.rb"
  );
  // ... ウォッチャーイベントハンドラー
}

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

2. ファクトリリンクプロバイダー（providers/factoryLinkProvider.ts）

目的: ファクトリ検出とリンク生成のコアビジネスロジック。

主要責任:

  • ファクトリとトレイトの検出
  • キャッシュ管理
  • ドキュメントリンクの生成
  • 設定処理

パブリックインターフェース:

export class FactoryLinkProvider implements vscode.DocumentLinkProvider {
  provideDocumentLinks(document: vscode.TextDocument): vscode.DocumentLink[];
  initializeFactoryFiles(): Promise<void>;
}

内部アーキテクチャ:

class FactoryLinkProvider {
  // キャッシュ構造
  private factoryCache: Map<string, { uri: vscode.Uri; lineNumber: number }>;
  private traitCache: Map<
    string,
    { uri: vscode.Uri; lineNumber: number; factory: string }
  >;
  private factoryFiles: vscode.Uri[];

  // コアメソッド
  private async initializeFactoryFiles();
  private async cacheFactoryDefinitions();
  private async cacheTraitDefinitions();
  private createDocumentLink();
}

依存関係:

  • vscode - ファイル操作とリンク生成のための VSCode API
  • path - パス操作ユーティリティ

ソース: src/providers/factoryLinkProvider.ts

モジュール依存関係

依存関係グラフ

graph TD
    A[extension.ts] --> B[providers/factoryLinkProvider.ts]
    A --> C[vscode API]
    B --> C
    B --> D[Node.js path]
    E[test/runTest.ts] --> F[test/suite/extension.test.ts]
    F --> A
    F --> G[vscode/test-electron]
    F --> H[mocha]
    F --> I[sinon]
Loading

外部依存関係

VSCode 拡張機能 API:

  • vscode.languages.registerDocumentLinkProvider
  • vscode.commands.registerCommand
  • vscode.workspace.createFileSystemWatcher
  • vscode.workspace.findFiles
  • vscode.workspace.openTextDocument

Node.js コアモジュール:

  • path - クロスプラットフォームパス操作

開発依存関係:

  • @vscode/test-electron - 拡張機能テストフレームワーク
  • mocha - テストランナー
  • sinon - モックフレームワーク

ソース: package.json#L77-L90

モジュール間データフロー

1. 初期化フロー

sequenceDiagram
    participant Main as extension.ts
    participant Provider as factoryLinkProvider.ts
    participant VSCode as VSCode API
    participant FS as ファイルシステム

    Main->>Provider: new FactoryLinkProvider()
    Main->>VSCode: registerDocumentLinkProvider(provider)
    Main->>VSCode: createFileSystemWatcher()
    Note over Provider: 初回使用時遅延初期化
    VSCode->>Provider: provideDocumentLinks()
    Provider->>VSCode: workspace.findFiles()
    VSCode->>FS: ファクトリファイルを検索
    FS-->>VSCode: ファイルURI
    VSCode-->>Provider: ファクトリファイルリスト
    Provider->>Provider: キャッシュ構築
Loading

2. ランタイムデータフロー

graph LR
    A[ユーザーアクション] --> B[VSCodeコア]
    B --> C[extension.ts]
    C --> D[factoryLinkProvider.ts]
    D --> E[ファクトリキャッシュ]
    D --> F[トレイトキャッシュ]
    E --> G[ドキュメントリンク]
    F --> G
    G --> B
    B --> H[UI表示]
Loading

モジュラーデザインパターン

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

実装:

  • FactoryLinkProviderはvscode.DocumentLinkProviderを実装
  • VSCode 統合とビジネスロジックの明確な分離
  • リンク生成の単一責任

メリット:

  • テスト可能なビジネスロジック
  • VSCode API の抽象化
  • 交換可能な実装

2. ファサードパターン

実装:

  • extension.tsが VSCode API のファサードとして機能
  • 複雑な VSCode サブシステムとの相互作用を簡素化
  • 拡張機能機能の統一インターフェースを提供

メリット:

  • 簡素化されたクライアントインターフェース
  • 集中化された設定
  • テストとモックの容易さ

3. リポジトリパターン（キャッシュレイヤー）

実装:

  • キャッシュマップがファクトリ定義のリポジトリとして機能
  • ビジネスロジックからデータアクセスを抽象化
  • 一貫したデータアクセスインターフェース

メリット:

  • 集中化されたデータ管理
  • パフォーマンス最適化
  • テスト可能なデータレイヤー

モジュール設定

設定フロー

graph TB
    A[VSCode設定] --> B[extension.ts]
    B --> C[設定変更イベント]
    C --> D[factoryLinkProvider.ts]
    D --> E[キャッシュ無効化]
    E --> F[ファクトリファイル再スキャン]
    F --> G[キャッシュ再構築]
Loading

設定スキーマ

拡張機能マニフェスト（package.json）:

{
  "contributes": {
    "configuration": {
      "properties": {
        "rails-factorybot-jump.factoryPaths": {
          "type": "array",
          "default": ["spec/factories/**/*.rb"]
        }
      }
    }
  }
}

ランタイムアクセス:

const config = vscode.workspace.getConfiguration("rails-factorybot-jump");
const factoryPaths = config.get<string[]>("factoryPaths", [
  "spec/factories/**/*.rb",
]);

ソース: package.json#L52-L66

テストモジュール構造

テスト組織

test/
├── runTest.ts           # テストランナーエントリポイント
└── suite/
    ├── index.ts         # Mocha設定
    └── extension.test.ts # テストケース

テストモジュール依存関係

テストランナー（runTest.ts）:

  • VSCode テスト環境を設定
  • 拡張機能開発ホストを設定
  • テスト実行ライフサイクルを管理

テストスイート（extension.test.ts）:

  • コア機能のユニットテスト
  • VSCode API との統合テスト
  • モックファクトリファイルと設定

テストインフラストラクチャ:

// テストモジュールインポート
import * as vscode from "vscode";
import * as assert from "assert";
import * as sinon from "sinon";
import { FactoryLinkProvider } from "../../providers/factoryLinkProvider";

ソース: src/test/suite/extension.test.ts

モジュールインターフェース

パブリック API

拡張機能インターフェース:

// メイン拡張機能エクスポート
export function activate(context: vscode.ExtensionContext): void;
export function deactivate(): void;

プロバイダーインターフェース:

// VSCode DocumentLinkProvider契約
interface DocumentLinkProvider {
  provideDocumentLinks(document: TextDocument): DocumentLink[];
}

内部インターフェース

キャッシュインターフェース:

interface FactoryDefinition {
  uri: vscode.Uri;
  lineNumber: number;
}

interface TraitDefinition extends FactoryDefinition {
  factory: string;
}

設定インターフェース:

interface ExtensionConfig {
  factoryPaths: string[];
}

モジュール間エラーハンドリング

エラー伝播戦略

graph TB
    A[ファイルシステムエラー] --> B[factoryLinkProvider.ts]
    B --> C[エラーログ]
    B --> D[優雅な機能低下]
    D --> E[部分的機能]

    F[VSCode APIエラー] --> G[extension.ts]
    G --> H[エラーログ]
    G --> I[リソースクリーンアップ]
Loading

エラー境界

モジュールレベルエラーハンドリング:

  • 各モジュールが独自のエラーを処理
  • エラーが他のモジュールを破壊するために伝播しない
  • 優雅な機能低下戦略

モジュール間エラー通信:

  • デバッグ用ログ
  • ユーザーフィードバック用ステータスインジケーター
  • フォールバック動作

モジュール拡張ポイント

将来のモジュール追加

追加予定のモジュール構造:

src/
├── parsers/          # 高度なRuby解析ユーティリティ（将来計画）
└── language-support/ # 多言語サポートモジュール（将来計画）

v1.3.0で実装されたモジュール:

  • models/ - ファクトリー、ロケーション、トレイトのデータモデル
  • services/ - 各種ビジネスロジックサービス
  • utils/ - 共有ユーティリティ関数

拡張戦略

プラグインアーキテクチャ:

  • 異なる言語サポートのプロバイダーインターフェース
  • 設定可能な解析戦略
  • プラガブルキャッシュ実装

設定拡張:

  • モジュール固有の設定セクション
  • 動的モジュール読み込み
  • 実験的モジュール用機能フラグ

パフォーマンス考慮事項

モジュール読み込み

遅延読み込み戦略:

  • アクティベーション時にコアモジュールを読み込み
  • 初回使用時に機能モジュールを読み込み
  • テスト環境でのみテストモジュール

メモリ管理:

  • モジュール固有のリソースクリーンアップ
  • 共有リソースプーリング
  • キャッシュサイズ制限

モジュール間通信

効率的なデータ渡し:

  • モジュール間での最小限のデータコピー
  • 適切な場合の共有データ構造
  • ポーリングを最小限に抑えるイベント駆動更新

このモジュラー構造は、コードベースを整理し理解しやすく保ちながら、保守性、テスト可能性、将来の拡張性の堅固な基盤を提供します。

⚠️ **GitHub.com Fallback** ⚠️