Imported from hirohitokato/vscode_dumpcode (
AGENTS.md). Install upstream withnpx skills add hirohitokato/vscode_dumpcode. Copyright stays with the author.
AI Agent Guide: Dump Codes Extension
このガイドは、AI コーディングエージェントが Dump Codes Extension プロジェクトで効率的に作業するための包括的なリファレンスです。
🎯 プロジェクト概要
目的
VS Code 拡張機能として、複数のソースファイルを収集し、単一ファイルまたはクリップボードへエクスポートする機能を提供します。LLM との対話やコードレビューに適したフォーマットで出力します。
主要機能
- エクスプローラーコンテキストメニュー: フォルダ右クリックで即座にダンプ
- ツリービュー: チェックボックスによる細かいファイル選択と管理
- 開いているエディタの選択: 現在作業中のファイルを素早くツリーで選択
- .gitignore 統合: 自動的にバージョン管理外のファイルを除外
- バイナリファイル検出: バイナリファイルを自動除外
- 永続的なチェック状態: ワークスペースごとに選択状態を保存
📁 アーキテクチャ概要
レイヤー構造
┌─────────────────────────────────────────┐
│ UI Layer (Views/Commands) │
│ - extension.ts (エントリーポイント) │
│ - extensionController.ts (コマンド管理) │
│ - fileTree.ts / FileNode.ts (ツリーUI) │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Service Layer │
│ - dumpChildren.ts (ダンプ処理の統合) │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Domain Layer │
│ - fileProcessor.ts (ファイル処理) │
│ - userDefaults.ts (設定管理) │
│ - fsHelper.ts (ファイルシステム抽象化) │
└─────────────────────────────────────────┘
設計原則
- 関心の分離: UI、サービス、ドメインロジックの明確な境界
- 依存性注入: テスト容易性のための柔軟な依存関係管理(
FileProcessor) - 単一責任原則: 各モジュールが単一の明確な責任を持つ
- オープン・クローズド原則:
ignoreFactoryなどの拡張ポイントを提供
🗂️ ファイル構造と責務
コアファイル
src/extension.ts
- 役割: 拡張機能のエントリーポイント
- 責務:
activate(): ツリービュー初期化、コントローラー起動deactivate(): クリーンアップ(現在は空)
- 依存:
FileTreeProvider,initializeTreeAndCommands - 重要:
activationEventsは空 - 手動/F5 起動を前提
src/controllers/extensionController.ts
- 役割: コマンド登録とツリービューの振る舞いを統合
- 責務:
- アクティブエディタのツリー内での reveal
- チェックボックス状態変更の処理
- コマンドハンドラー登録(copy, refresh, clear, dump, selectOpenEditors)
- 設計ポイント: UI ロジックを
extension.tsから分離し、テスト容易性を向上 - 重要な関数:
revealActiveEditorInTree(): エディタとツリーの同期selectOpenEditors(): 開いているタブをツリーで選択
src/views/fileTree.ts
- 役割: ツリービューのデータプロバイダー
- 責務:
- ファイルツリーの構築と表示
.gitignoreとuserIgnorePatternsの統合- チェック状態の永続化(
context.workspaceState) - ノードキャッシュ管理(
nodeCache)
- キーメソッド:
getChildren(): ツリー階層の構築getNodeForPath(): reveal のためのノード取得/生成getParent(): reveal 機能に必須markRecursively()/unmarkRecursively(): ディレクトリ単位の選択
- ignore ロジック:
ignoreライブラリで posix パス形式を使用 - 重要: バイナリ判定は
isbinaryfileを使用、fileProcessor.tsと一貫性を保つこと
src/views/FileNode.ts
- 役割: ツリーアイテムのドメインモデル
- 責務:
TreeItemの生成とチェックボックス状態の同期- ファイル/ディレクトリの識別
- コンテキストメニューの設定
- 設計: UI ロジックとドメインモデルの分離
src/services/dumpChildren.ts
- 役割: ダンプ処理の高レベル統合
- 責務:
- Explorer コンテキストメニューからの呼び出し処理
- Progress UI の表示
- 設定読み込みと
FileProcessorへの委譲
- 関数:
handleDumpFiles(): file/clipboard 出力の分岐copyFilesToClipboard(): クリップボードへの書き込み
src/services/fileProcessor.ts
- 役割: ファイル探索とダンプのコアロジック
- 責務:
- ディレクトリの再帰的走査
.gitignoreルールの階層的な適用- バイナリファイルの除外
- ファイル内容の読み取りとフォーマット
- 設計ハイライト:
FileProcessorクラス: 依存性注入対応(FileOps,isBinary,ignoreFactory)- デフォルトインスタンス提供で既存 API との互換性維持
- 重要メソッド:
getFiles(): 収集対象ファイルのリスト取得dumpFilesContent(): ファイルへの書き込みreadFilesContent(): クリップボード用の文字列生成
src/config/userDefaults.ts
- 役割: 設定値の読み取りラッパー
- 設定項目:
outputFileName: 出力ファイル名userIgnorePatterns: ユーザー定義の除外パターンdefaultDumpTarget: デフォルト出力先(file/clipboard)revealFocus: reveal 時にツリーにフォーカスするかmaxSelectOpenEditors: 選択可能な最大タブ数
src/utils/fsHelper.ts
- 役割: ファイルシステム操作の抽象化
- 目的: テスト容易性と VS Code API の統一的な利用
🧪 テスト戦略
テストファイル
src/test/extension.test.ts: 基本的な拡張機能の起動テストsrc/test/dumpChildren.test.ts: ダンプ処理の統合テストsrc/test/selectOpenEditors.test.ts: 開いているエディタ選択機能のテストsrc/test/fileNode.test.ts: FileNode のユニットテスト(存在予定)
テスト実行環境
- Extension Test Host: VS Code の実環境で実行
- ビルド:
npm run compile-testsでout/にビルド - 実行:
npm testまたはnpm run test:win(Windows の TLS 設定対応版)
テストのベストプラクティス
- 統合テスト:
vscode.workspace.fsなど実 API を使用 - ユニットテスト:
FileProcessorのようにモック可能な設計を活用 - Extension Development Host (F5): 手動での動作確認に活用
🔧 開発ワークフロー
セットアップ
# 依存関係インストール
npm install
# TypeScript コンパイル
npm run compile
# Watch モード(開発時推奨)
npm run watch
ビルドとテスト
# 型チェック
npm run check-types
# リント
npm run lint
# テスト実行前のビルド
npm run compile-tests
# テスト実行
npm test # Linux/Mac
npm run test:win # Windows(TLS 設定対応)
デバッグ
- VS Code でプロジェクトを開く
F5を押して Extension Development Host を起動- 新しいウィンドウで拡張機能をテスト
watchタスクを実行中なら変更が自動反映
パッケージング
npm run package
🎨 コーディング規約
TypeScript スタイル
- 厳格な型付け:
tsconfig.jsonのstrict: true - 明示的な型注釈: 公開 API には必須
- async/await: Promise チェーンよりも優先
- エラーハンドリング: try-catch で適切に処理、ユーザーへの通知は控えめに
命名規則
- ファイル: camelCase (
fileTree.ts,dumpChildren.ts) - クラス: PascalCase (
FileTreeProvider,FileNode) - インターフェース: PascalCase (
FileOps) - 関数/メソッド: camelCase (
getFiles,markRecursively) - 定数: UPPER_SNAKE_CASE(設定キーなど)
コメント
- 日本語 OK: コードコメントは日本語で記述可能
- JSDoc: 公開 API には型と説明を記載
- インラインコメント: 複雑なロジックには必ず説明を追加
⚠️ 重要な注意点と制約
activationEvents が空
- 理由: 現在のテスト/開発は手動起動(F5)を前提
- 影響: 自動起動を期待する機能追加時は要検討
- 対応: 必要に応じて
package.jsonのactivationEventsを設定
ignore ロジックの一貫性
- ツリービュー (
fileTree.ts) と ファイルプロセッサー (fileProcessor.ts) で同じ除外ルールを適用 - 変更時: 両方のファイルを同時に更新すること
- パス形式: posix 形式 (
/区切り) で統一
バイナリファイル判定
- ライブラリ:
isbinaryfileを使用 - 適用場所: ツリービューとファイルプロセッサーの両方
- エラーハンドリング: ファイルアクセスエラーは無視(best-effort)
チェック状態の永続化
- ストレージ:
context.workspaceState - キー:
checkedPaths:<workspace> - タイミング: チェック状態変更時に即座に保存
- 注意: ワークスペースごとに独立
reveal 機能の実装要件
getParent()実装が必須getNodeForPath()でノードを準備dumpSource.revealFocus設定でフォーカス制御- 再試行ロジック: ノードが未キャッシュの場合 refresh → 再試行
🚀 機能追加ガイドライン
新しいコマンドの追加
package.jsonのcontributes.commandsに登録extensionController.tsでハンドラーを実装- 必要に応じて
contributes.menusでメニュー配置 context.subscriptions.push()で Disposable を登録
新しい設定の追加
package.jsonのcontributes.configuration.propertiesに定義userDefaults.tsに getter を追加- 使用箇所で
new UserDefaults()を通じてアクセス
ファイル処理ロジックの変更
FileProcessorクラスを優先的に使用- テスト容易性のため依存性注入を活用
fileTree.tsの ignore ロジックとの一貫性を確認
UI の変更
FileNodeクラスで表示ロジックを変更FileTreeProviderでツリー構造を調整extensionController.tsでイベントハンドリングを追加
🐛 トラブルシューティング
よくある問題
ツリーに表示されないファイルがある
- 原因:
.gitignoreまたはuserIgnorePatternsで除外されている - 確認:
fileTree.tsのloadIgnorePatterns()とgetChildren()のフィルタロジック - デバッグ:
ig.ignores(relPath)の結果をログ出力
チェック状態が保存されない
- 原因:
persist()が呼ばれていない、またはworkspaceStateのキーが不正 - 確認:
markChecked()/unmarkChecked()でpersist()呼び出しを確認 - デバッグ:
context.workspaceState.get(this.stateKey)の値を確認
reveal が動作しない
- 原因:
getParent()未実装、またはノードがキャッシュされていない - 確認:
getNodeForPath()がノードを返すか確認 - デバッグ:
nodeCacheの内容を確認、refresh 後の再試行を実装
テストが失敗する
- Windows の場合:
npm run test:winを使用(TLS 設定) - ビルド忘れ:
npm run compile-testsを実行 - Extension Host: テストは実 VS Code 環境で実行されることを認識
📚 参考リソース
VS Code API
使用ライブラリ
- ignore: .gitignore パターンマッチング
- isbinaryfile: バイナリファイル検出
プロジェクトドキュメント
README.md: ユーザー向け機能説明CHANGELOG.md: バージョン履歴.github/copilot-instructions.md: AI 向けクイックリファレンス
🎯 品質目標
コード品質
- 型安全性: TypeScript の厳格モードで型エラーゼロ
- リント: ESLint ルール違反ゼロ
- テストカバレッジ: 主要ロジック(
fileProcessor.ts)は 80% 以上
パフォーマンス
- 大規模プロジェクト: 10,000 ファイル以上でもスムーズな動作
- UI 応答性: ツリー展開・チェック操作は 100ms 以内
- メモリ効率: ノードキャッシュの適切な管理
ユーザビリティ
- 直感的な UI: エクスプローラーと同じソート順、アイコン使用
- 適切なフィードバック: Progress UI、情報メッセージの適切な使用
- エラーハンドリング: ユーザーに分かりやすいエラーメッセージ
🔄 変更を行う際のチェックリスト
-
コンテキスト把握
- 変更対象のファイルとその責務を理解
- 関連する他のモジュールへの影響を確認
- 既存のテストを確認
-
実装
- 型安全なコードを記述
- エラーハンドリングを適切に実装
- 必要に応じてコメントを追加
-
一貫性の確認
- ignore ロジック:
fileTree.tsとfileProcessor.tsの両方 - バイナリ判定: 同じライブラリ・ロジックを使用
- 設定:
package.jsonとuserDefaults.tsが同期
- ignore ロジック:
-
ビルドとテスト
-
npm run compileでエラーなし -
npm run lintで警告なし -
npm testでテスト通過 - F5 で Extension Development Host で手動テスト
-
-
ドキュメント
- 必要に応じて
README.mdを更新 - 重要な変更は
CHANGELOG.mdに記載 - 新しい設定は
package.jsonで適切に説明
- 必要に応じて
💡 設計パターンと原則
採用している設計パターン
- Provider パターン:
FileTreeProviderで VS Code API とのインターフェース - Strategy パターン:
ignoreFactoryで ignore 生成ロジックの差し替え可能 - Repository パターン:
fsHelper.tsでファイルシステム操作の抽象化 - Facade パターン:
dumpChildren.tsで複雑な処理フローを簡素化
SOLID 原則の適用
- S (Single Responsibility): 各クラス・モジュールが単一の責任
- O (Open/Closed):
FileProcessorは拡張に開き、修正に閉じている - L (Liskov Substitution): インターフェース(
FileOps)を通じた置換可能性 - I (Interface Segregation): 必要最小限のインターフェース定義
- D (Dependency Inversion): 高レベルモジュールが低レベルモジュールに依存しない
📝 最後に
このプロジェクトは、シンプルさと拡張性のバランスを重視しています。新機能追加時は:
- 既存の設計パターンに従う
- テスト容易性を維持する
- ユーザー体験を最優先する
- パフォーマンスに配慮する
不明点があれば、既存のコードパターンを参照し、一貫性のある実装を心がけてください。
Happy Coding! 🚀