debugging-with-opensrc

OpenSrc を使ったデバッグ

概要

まずソースを読んで、外部ライブラリの動作をデバッグします。

インストールされているバージョンについては、OpenSrc のミラーを信頼できる情報源として扱います。

このスキルを使う場面

• アプリケーションコードがサードパーティライブラリの内部実装に依存する統合の問題を調査するとき。
• ドキュメントと実行時に観測される動作との不一致を解消するとき。
• インストールされている依存関係の関数シグネチャ、デフォルト値、エラー処理、またはエッジケースの処理を確認するとき。

OpenSrc コマンド

# Sync configured repos when the OpenSrc config exists
test ! -f opensrc/sources.json || \
bun run scripts/opensrc-sync.ts

# Fetch a package or GitHub repo
bunx opensrc --modify false <package-or-owner/repo>

利用可能なリポジトリ（opensrc/repos/github.com/）

ライブラリ	パス	確認する項目
Effect	Effect-TS/effect/packages/effect/src/	Schema、Effect.gen、Layer、Context
TanStack Router	TanStack/router/packages/react-router/src/	createFileRoute、loader、useParams
TanStack Query	TanStack/query/packages/react-query/src/	useSuspenseQuery、queryOptions
TanStack Form	TanStack/form/packages/react-form/src/	useForm、バリデーション
TanStack Start	TanStack/router/packages/start/src/	SSR、サーバー関数
TRPC	trpc/trpc/packages/server/src/	プロシージャ、ミドルウェア、ルーター
Drizzle ORM	drizzle-team/drizzle-orm/drizzle-orm/src/	pgTable、リレーション、クエリ
Better Auth	better-auth/better-auth/packages/better-auth/src/	認証設定、プラグイン、セッション
OpenCode	sst/opencode/packages/opencode/src/	スキル、コマンド、プラグイン
Pino	pinojs/pino/lib/	ロガー、トランスポート
Sentry	getsentry/sentry-javascript/packages/	SDK、統合、トレーシング

デバッグのワークフロー

1. 不具合のある動作を、入力、観測された出力、期待される出力を含む1文で定義します。
2. 該当する依存関係とパッケージ領域を特定します。
3. 利用可能なプロジェクト検索ツールを使って、opensrc/repos/github.com/ 内の関連するソースファイルを探します。
4. アプリケーションコードを変更する前に、実装と関連する型を読みます。
5. 公開 API から内部ヘルパーまでの呼び出しフローを追跡します。
6. 具体的な期待事項を抽出します。
   • 関数シグネチャと戻り値の型
   • 必要なラッパー／ビルダー／オプション
   • デフォルト値と省略可能なパラメーターの動作
   • エラー処理とエッジケース
7. 確認済みの動作に基づいて、アプリケーションコードに修正を適用します。
8. 対象を絞ったテストまたは再現手順で検証します。

よくあるデバッグのシナリオ

シナリオ：TanStack Form のバリデーションが動作しない

1. opensrc/repos/github.com/TanStack/form/packages/react-form/src/useForm.ts を読みます。
2. バリデーターのインターフェースと期待される戻り値の型を確認します。
3. インストールされているバージョンで Standard Schema との統合がどのように組み込まれているかを確認します。
4. 確認済みの動作に基づいて、アプリケーションコードを修正します。

シナリオ：TRPC プロシージャがコンテキストを受け取らない

1. opensrc/repos/github.com/trpc/trpc/packages/server/src/core/middleware.ts を読みます。
2. ミドルウェアチェーンを通じてコンテキストがどのように渡されるかを追跡します。
3. 現在のバージョンにおけるミドルウェアの戻り値と opts.next() の動作を確認します。

シナリオ：Effect Layer がサービスを提供しない

1. opensrc/repos/github.com/Effect-TS/effect/packages/effect/src/Layer.ts を読みます。
2. Layer.effect と Layer.succeed の動作を比較します。
3. ライブラリのパターンに照らして Context.Tag の使い方を確認します。

シナリオ：Better Auth のセッションが永続化されない

1. opensrc/repos/github.com/better-auth/better-auth/packages/better-auth/src/ を読みます。
2. セッションの処理と永続化のフローを追跡します。
3. インストールされているコードで、Cookie とストレージに関する要件を確認します。

重要な原則

ソースコードが真実です。

• ドキュメントは古くなっている場合があります
• Stack Overflow の回答が、お使いのバージョンに当てはまるとは限りません
• ブログ記事では、異なる設定が使われている場合があります
• 実際の動作を正確に示すのは、ソースコードだけです

例：デバッグセッションの全体像

問題：キャッシュされたデータがあるにもかかわらず、useSuspenseQuery が undefined を返します。

1. opensrc/repos/github.com/TanStack/query/packages/react-query/src/useSuspenseQuery.ts と周辺の型定義を読みます。
2. インストールされているバージョンで、どのような入力形式が想定されているか確認します。
3. プロジェクトコードで、正常に動作する使用パターンを確認します。
4. 確認した想定に合った修正を適用します。

注：以前、あるバージョンでの調査では、入力を queryOptions() でラップすると問題が解決しました。これは調査で得られた一例として扱い、普遍的なルールとは見なさないでください。

OpenCode 固有の内部情報

OpenCode のスキルの読み込みや、自動読み込みテストの内部実装をデバッグする際は、references/opencode-skill-testing.md を使用してください。

忘れないでください

1. まずソースを読む — 質問する前、ウェブ検索する前に
2. 正確なバージョンが重要です — opensrc には、お使いのバージョンが含まれています
3. コードの流れを追う — エントリーポイントから実装までたどります
4. 型を確認する — TypeScript の型から、想定される使い方がわかることがよくあります
5. テストを見る — ライブラリのテストには、正しい使用パターンが示されています