ts-morph-analyzer

TypeScript コードベースアナライザー

概要

ts-morph を使用した軽量なコードベース分析です。ファイル全体を読み込んでコンテキストを圧迫することなく、シグネチャ、JSDoc、呼び出しチェーンを抽出します。

基本原則： トークンの使用量を最小限に抑えながら、アーキテクチャに関する知見を最大限に得ます。

使用する場面

状況	使用するスクリプト
コードベースの公開 API をすばやく把握する	extract-signatures.ts
関数呼び出しをたどってバグを追跡する	trace-calls.ts
モジュールがエクスポートする内容を把握する	analyze-exports.ts
詳細に調べる前にアーキテクチャ上の問題を検出する	code-smells.ts
インポート／依存関係の構造を把握する	analyze-exports.ts --deps

セットアップ

# In the skill directory
cd ~/.claude/skills/ts-morph-analyzer
npm install

または、セットアップスクリプトを実行します：

~/.claude/skills/ts-morph-analyzer/setup.sh

クイックリファレンス

シグネチャを抽出する（最もよく使う機能）

ファイル全体を読まずに、関数／メソッドのシグネチャと JSDoc を取得します：

# All signatures in a file
npx ts-node scripts/extract-signatures.ts src/api/users.ts

# All signatures in a directory (recursive)
npx ts-node scripts/extract-signatures.ts src/

# Filter to exported only
npx ts-node scripts/extract-signatures.ts src/ --exported

# Include types and interfaces
npx ts-node scripts/extract-signatures.ts src/ --types

# Output as JSON for further processing
npx ts-node scripts/extract-signatures.ts src/ --json

出力例：

// src/api/users.ts

/**
 * Fetches user by ID from the database
 * @param id - User's unique identifier
 * @returns User object or null if not found
 */
export async function getUser(id: string): Promise<User | null>

/**
 * Creates a new user account
 * @throws ValidationError if email is invalid
 */
export async function createUser(data: CreateUserInput): Promise<User>

呼び出し階層を追跡する

関数呼び出しを上方向（これを呼び出すのは何か？）または下方向（これは何を呼び出すか？）にたどります：

# Who calls this function?
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --up

# What does this function call?
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --down

# Full call chain (both directions, limited depth)
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --depth 3

# Output as tree
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --tree

出力例（--up）：

getUser (src/api/users.ts:15)
├── called by: handleGetUser (src/routes/users.ts:23)
│   └── called by: router.get('/users/:id') (src/routes/users.ts:8)
├── called by: validateSession (src/middleware/auth.ts:45)
└── called by: getUserProfile (src/services/profile.ts:12)

エクスポートを分析する

モジュールの公開 API の範囲を把握します：

# What does this module export?
npx ts-node scripts/analyze-exports.ts src/api/

# Include re-exports
npx ts-node scripts/analyze-exports.ts src/ --follow-reexports

# Show dependency graph
npx ts-node scripts/analyze-exports.ts src/ --deps

コードスメルを検出する

アーキテクチャをすばやく評価します：

# Full analysis
npx ts-node scripts/code-smells.ts src/

# Specific checks
npx ts-node scripts/code-smells.ts src/ --check circular-deps
npx ts-node scripts/code-smells.ts src/ --check large-functions
npx ts-node scripts/code-smells.ts src/ --check missing-jsdoc
npx ts-node scripts/code-smells.ts src/ --check many-params

アーキテクチャ評価のパターン

新しいコードベースを分析して潜在的な問題を見つける場合：

1. まず公開 API の範囲を確認する

# Get the big picture: what's exported?
npx ts-node scripts/extract-signatures.ts src/ --exported --json > api-surface.json

確認する項目：過度に複雑なインターフェース、一貫性のない命名、公開 API における JSDoc の欠落

2. 依存関係の構造

# Map imports - circular deps are red flags
npx ts-node scripts/code-smells.ts src/ --check circular-deps

確認する項目：循環依存、深いインポートチェーン、不明確なモジュール境界

3. 関数の複雑さ

# Find complex functions that may need refactoring
npx ts-node scripts/code-smells.ts src/ --check large-functions --check many-params

確認する項目：50 行を超える関数、パラメーターが 5 個を超える関数、深いネスト

4. ドキュメントの網羅性

# Public APIs should be documented
npx ts-node scripts/code-smells.ts src/ --check missing-jsdoc --exported

データの流れをたどる

デバッグ時にファイル全体を読まず、データの流れを追跡します：

パターン：「この値はどこから来るのか？」

# 1. Find who calls the function with the bad value
npx ts-node scripts/trace-calls.ts src/service.ts:processData --up --depth 5

# 2. Get signatures of callers to understand parameter flow
npx ts-node scripts/extract-signatures.ts src/caller.ts

パターン：「この戻り値はどこに渡されるのか？」

# 1. Find what uses this function's return
npx ts-node scripts/trace-calls.ts src/api.ts:fetchUser --down

# 2. Check how return values are consumed
npx ts-node scripts/trace-calls.ts src/api.ts:fetchUser --down --show-usage

パターン：「バグの呼び出しチェーン全体」

# Get complete path from entry point to problem area
npx ts-node scripts/trace-calls.ts src/broken.ts:problematicFn --up --tree

スクリプトの場所

すべてのスクリプトの場所：~/.claude/skills/ts-morph-analyzer/scripts/

スクリプト	目的
extract-signatures.ts	JSDoc を含む関数／メソッド／クラスのシグネチャを抽出する
trace-calls.ts	呼び出し階層を上方向／下方向に追跡する
analyze-exports.ts	モジュールのエクスポートと依存関係を把握する
code-smells.ts	アーキテクチャ上の問題を検出する

よくある問題

問題	解決策
"Cannot find module 'ts-morph'"	スキルディレクトリで npm install を実行する
大規模なコードベースで遅い	対象範囲を絞るために --include "src/**/*.ts" を追加する
型情報が不足している	tsconfig.json がプロジェクトルートにあることを確認する
メモリの問題	--exclude "node_modules" を使用する（デフォルト）