コントリビューションガイドライン

KnowledgePulse へのコントリビューションに興味をお持ちいただきありがとうございます。このドキュメントでは、プロジェクトのコードスタイル、テストの期待事項、プルリクエストプロセスについて説明します。

コードスタイル

• フォーマッターとリンター： Biome がフォーマットとリントの両方を処理します。PR を提出する前に bun run lint を実行してください。
• TypeScript： すべてのパッケージで Strict モードが有効です。外部入力のランタイムバリデーションには Zod v3 を使用してください。
• インポート： 明示的な名前付きインポートを推奨します。ワイルドカード（*）インポートは避けてください。

テスト

• フレームワーク： bun:test（Bun に組み込み）。

• ファイル配置： テストはテスト対象のソースファイルと同じ場所に配置します。テストファイルは *.test.ts サフィックスを使用します。

• スイートの実行：

  bun test --recursive

  現在の完全なスイートは15ファイル、319テストで構成されています。PR がマージされる前にすべてのテストに合格する必要があります。

• スキーマの変更： Zod スキーマまたは KnowledgeUnit 構造への変更には、以下が必要です：

  1. 以前のスキーマバージョンからデータを変換するマイグレーション関数。
  2. データがシリアライズ、マイグレーション、デシリアライズを経てもロスなく保持されることを証明するラウンドトリップテスト。

ビルドに関する注意

SDK は tsup でビルドされ、ESM、CJS、TypeScript 宣言（.d.ts）ファイルを出力します。SDK の tsconfig.json は意図的に "types": [] を設定しています。これは bun-types と tsup の DTS 生成プラグインの競合を回避するためです。この設定を削除しないでください。

プルリクエストプロセス

1. リポジトリをフォークし、main からフィーチャーブランチを作成します。

2. 上記のコードスタイルガイドラインに従って変更を実装します。

3. 変更をカバーするテストを作成または更新します。

4. 完全なテストスイートを実行し、すべてのテストに合格することを確認します：

   bun test --recursive

5. コードをリントします：

   bun run lint

6. 変更内容とその目的を明確に説明したプルリクエストを main に対して提出します。

コミットメッセージ

Conventional Commits スタイルに従ってください：

<type>(<scope>): <short summary>

一般的な type：

Type	使用場面
feat	新しい機能。
fix	バグ修正。
docs	ドキュメントのみの変更。
refactor	動作を変更しないコードの再構成。
test	テストの追加または更新。
chore	ビルド設定、CI、ツーリングの変更。

使用例：

feat(sdk): add vector similarity caching
fix(mcp-server): handle missing API key in proxy mode
test(cli): add integration tests for kp search

ライセンス

すべてのコントリビューションはプロジェクトの他の部分と同様に Apache 2.0 のもとでライセンスされます。