ts-review-graph: Instructions file for Claude Code

ts-review-graph

Commands

pnpm build          # 全パッケージをビルド (tsc)
pnpm test           # 全パッケージのテストを実行 (vitest)
pnpm lint           # 全パッケージの型チェック (tsc --noEmit)
pnpm sync-version   # cli/package.json の version を全配布物へ同期

# 特定パッケージのみ
cd packages/core && pnpm build
cd packages/mcp-server && pnpm build
cd cli && pnpm build

Architecture

pnpm monorepo。4 パッケージで構成:

Package	Name	Role
packages/core	@elchika-inc/ts-review-graph-core	グラフ構築・クエリエンジン (SQLite + ts-morph)
packages/mcp-server	@elchika-inc/ts-review-graph-mcp-server	MCP サーバー (8 ツール)
packages/plugin	(配布専用)	Claude Code プラグイン (commands/hooks/skills)
cli/	@elchika-inc/ts-review-graph	CLI ツール

依存関係: mcp-server → core、cli → core。plugin は Node package/build を持たず、Markdown・hooks.json・shell hook scripts で構成する。

Key Files

• packages/core/src/db.ts — SQLite スキーマ定義と openDb
• packages/core/src/analyzer.ts — ts-morph による AST 解析
• packages/core/src/blast.ts — BFS ブラスト半径計算 (SQL Recursive CTE)
• packages/core/src/updater.ts — 増分更新ロジック
• packages/mcp-server/src/tools/index.ts — 全 MCP ツール定義と登録
• cli/src/index.ts — CLI エントリポイント (install/build/update/status/uninstall)
• cli/src/codex-config.ts — Codex 用 .codex/config.toml の追記。中止の粒度は2段（判定軸は「ファイルを正しく読めたか」）— 詳細は CodexConfigUpdate の doc コメント

Database Schema

SQLite 4 テーブル: nodes、edges、file_hashes、meta

Edge kinds: IMPORTS_FROM | TYPED_BY | IMPLEMENTS | EXTENDS | HAS_TEST

重要: nodes.file と nodes.id はプロジェクトルート相対の POSIX パスで保存する。 絶対パスで保存すると、リポジトリの移動・worktree・別マシンでのクローンでグラフが 無言で全件ミスする（実障害あり）。DB へ保存するすべてのファイルパスは共通 ユーティリティ toProjectRelative を通す。analyzer.ts ではルート外を除外する toRelativeOrNull を経由する。

重要: edges.target_id に意図的に REFERENCES を付けていない。増分更新でファイルを 削除するとき、source_id が削除ファイルのエッジだけを CASCADE で消し、 逆方向 (B→A) エッジは残す必要があるため。

重要: meta テーブルはグラフの構築条件（schema_version / tsconfigs / built_at / built_root）を記録する。checkGraphHealth() がこれを使って検疫する。 meta 不在の DB は旧形式として fail-closed で拒否される。