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"（默认）