JA Development Guides Local Development - hiraishikentaro/rails-factorybot-jump GitHub Wiki

開発ガイド: ローカル開発

ローカル開発セットアップ

前提条件の確認

ローカル開発を始める前に、環境が要件を満たしていることを確認してください：

# Node.js バージョンをチェック（18.x 必須）
node --version

# npm バージョンをチェック
npm --version

# VSCode バージョンをチェック（1.85.0+ 必須）
code --version

# TypeScript インストールをチェック
npx tsc --version

プロジェクトセットアップ

1. クローンとインストール:

git clone https://github.com/hiraishikentaro/rails-factorybot-jump.git
cd rails-factorybot-jump
npm install

2. インストール確認:

# TypeScript をコンパイル
npm run compile

# リンティングを実行
npm run lint

# テストを実行
npm test

ソース: package.json#L68-L76

開発ワークフロー

1. 開発環境

VSCode 開発セットアップ:

# プロジェクトを VSCode で開く
code .

# 推奨拡張機能をインストール
# - TypeScript and JavaScript Language Features（組み込み）
# - ESLint
# - Mocha Test Explorer

開発モード:

# 自動コンパイル用のウォッチモード
npm run watch

# これにより:
# - TypeScript ファイルの変更を監視
# - out/ ディレクトリに自動再コンパイル
# - デバッグ用のソースマップを保持

2. Extension Development Host

開発環境の起動:

プロジェクトを VSCode で開く
F5 を押すか、実行 → デバッグの開始に移動
これにより新しい "Extension Development Host" ウィンドウが起動
拡張機能がこのウィンドウに自動的にロード
開発ホストで変更をテスト

開発ホストの機能:

拡張機能がロードされた完全な VSCode 環境
再コンパイル時のリアルタイム更新
デバッグ用の Developer Tools アクセス
メイン VSCode インストールから分離

3. ホットリロード開発

自動再コンパイル:

# ターミナル 1: TypeScript コンパイル用ウォッチモード
npm run watch

# ターミナル 2: 必要に応じてテストのウォッチモード
npm run test:watch

拡張機能のリロード:

Extension Development Host で、Ctrl+R（Windows/Linux）または Cmd+R（Mac）を押す
これにより最新の変更で拡張機能がリロード
開発ホスト全体を再起動する必要はない

ファイル構造と開発

ソースコード構成

src/
├── extension.ts              # メインエントリーポイント - ここから開始
├── providers/
│   └── factoryLinkProvider.ts # コアビジネスロジック
├── test/
│   ├── runTest.ts           # テスト設定
│   └── suite/
│       └── extension.test.ts # テストケース
└── utils/                   # 将来のユーティリティモジュール

主要な開発ファイル

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

拡張機能のアクティベーションと非アクティベーション
VSCode へのプロバイダー登録
コマンド登録
ファイルシステムウォッチャーセットアップ

コアプロバイダー (src/providers/factoryLinkProvider.ts):

ファクトリー検出ロジック
キャッシュ管理
ドキュメントリンク生成
設定処理

ソース: src/extension.ts, src/providers/factoryLinkProvider.ts

開発中のテスト

1. ユニットテスト開発

テストの実行:

# すべてのテストを実行
npm test

# 特定のテストスイートを実行
npm test -- --grep "ファクトリー検出"

# 詳細な出力でテストを実行
npm test -- --reporter spec

新しいテストの記述:

// src/test/suite/extension.test.ts にテストを追加
suite("新機能", () => {
  test("新しい機能を処理すべき", () => {
    // テスト実装
    assert.strictEqual(actual, expected);
  });
});

2. 手動テスト

ファクトリー検出のテスト:

テスト Ruby ファイルを作成:

# test.rb
RSpec.describe User do
  it "creates user" do
    user = create(:user, :admin)
    expect(user).to be_valid
  end
end

テストファクトリーファイルを作成:

# spec/factories/users.rb
FactoryBot.define do
  factory :user do
    name { "Test User" }

    trait :admin do
      admin { true }
    end
  end
end

Extension Development Host で test.rb を開く
:user と :admin にホバーしてリンクが表示されることを確認
リンクをクリックしてナビゲーションが動作することを確認

3. インテグレーションテスト

設定変更のテスト:

Extension Development Host で設定を開く
rails-factorybot-jump.factoryPaths を変更
拡張機能がファクトリー検索パスを更新することを確認
カスタムファクトリーディレクトリ構造でテスト

ファイル監視のテスト:

Extension Development Host が開いている間にファクトリーファイルを変更
キャッシュが自動的に更新されることを確認
テストファイルでリンクが更新されることを確認

デバッグ技術

1. VSCode デバッグ

デバッガーセットアップ:

// .vscode/launch.json（すでに設定済み）
{
  "type": "extensionHost",
  "request": "launch",
  "name": "Extension",
  "runtimeExecutable": "${execPath}",
  "args": ["--extensionDevelopmentPath=${workspaceRoot}"]
}

デバッグワークフロー:

TypeScript ソースファイルにブレークポイントを設定
F5 を押してデバッグを開始
Extension Development Host を使用してブレークポイントをトリガー
変数、コールスタック、実行フローを検査

2. コンソールログ

戦略的ログ:

// ファクトリー検出をデバッグ
console.log("ファクトリー検出正規表現結果:", matches);

// キャッシュ操作をデバッグ
console.log("ファクトリーキャッシュサイズ:", factoryCache.size);
console.log("ファクトリーキャッシュ内容:", Array.from(factoryCache.entries()));

// ファイル操作をデバッグ
console.log(
  "見つかったファクトリーファイル:",
  factoryFiles.map((f) => f.path)
);

VSCode Developer Tools:

Extension Development Host で: Help → Toggle Developer Tools
Console タブでデバッグ出力を確認
Network タブでファイル操作を監視
Sources タブでソースマップを使用したデバッグ

開発のベストプラクティス

1. コード構成

単一責任:

// 良い例: 各メソッドが一つの明確な目的を持つ
class FactoryLinkProvider {
  private async initializeFactoryFiles() {
    /* ... */
  }
  private async cacheFactoryDefinitions() {
    /* ... */
  }
  private createDocumentLink() {
    /* ... */
  }
}

明確なインターフェース:

// 良い例: 明確なデータ構造
interface FactoryDefinition {
  uri: vscode.Uri;
  lineNumber: number;
}

interface TraitDefinition extends FactoryDefinition {
  factory: string;
}

2. エラーハンドリング

グレースフル劣化:

// 良い例: 部分的な機能で継続
try {
  const factoryFiles = await vscode.workspace.findFiles(pattern);
  await this.processFactoryFiles(factoryFiles);
} catch (error) {
  console.warn("一部のファクトリーファイルの読み込みに失敗、継続:", error);
  // 利用可能なファイルで継続
}

この包括的なローカル開発ガイドは、Rails FactoryBot Jump 拡張機能に効果的に貢献するために必要なすべてを提供します。