名称: ts-morph-analyzer 描述: 在调试TypeScript/JavaScript错误时使用，通过追踪调用链、快速理解陌生代码库、做出架构决策或审查代码质量。无需完整读取文件即可提取函数签名和JSDoc，追踪调用层次结构上下，检测代码异味，并跟随数据流。触发于调试、理解代码库、架构分析、签名提取、调用追踪。

TypeScript 代码库分析器

概述

使用ts-morph进行轻量级代码库分析。提取签名、JSDoc和调用链，而不会因完整文件读取而淹没上下文。

核心原则: 以最少的令牌使用获取最大的架构洞察。

使用时机

情境	使用的脚本
快速理解代码库的公共API	`extract-signatures.ts`
通过函数调用追踪错误	`trace-calls.ts`
映射模块导出的内容	`analyze-exports.ts`
在深入之前检测架构问题	`code-smells.ts`
理解导入/依赖结构	`analyze-exports.ts --deps`

设置

# 在技能目录中
cd ~/.claude/skills/ts-morph-analyzer
npm install

或运行设置脚本：

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

快速参考

提取签名（最常见）

获取函数/方法签名和JSDoc，无需读取完整文件：

# 文件中所有签名
npx ts-node scripts/extract-signatures.ts src/api/users.ts

# 目录中所有签名（递归）
npx ts-node scripts/extract-signatures.ts src/

# 仅过滤导出的
npx ts-node scripts/extract-signatures.ts src/ --exported

# 包括类型和接口
npx ts-node scripts/extract-signatures.ts src/ --types

# 输出为JSON以进行进一步处理
npx ts-node scripts/extract-signatures.ts src/ --json

输出示例:

// src/api/users.ts

/**
 * 从数据库中按ID获取用户
 * @param id - 用户的唯一标识符
 * @returns 用户对象或如果未找到则返回null
 */
export async function getUser(id: string): Promise<User | null>

/**
 * 创建新用户账户
 * @throws ValidationError 如果电子邮件无效
 */
export async function createUser(data: CreateUserInput): Promise<User>

追踪调用层次结构

跟随函数调用向上（谁调用此函数？）或向下（此函数调用什么？）：

# 谁调用此函数？
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --up

# 此函数调用什么？
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --down

# 完整调用链（双向，限制深度）
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --depth 3

# 输出为树形结构
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --tree

输出示例（–up）：

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

分析导出

映射模块的公共API表面：

# 此模块导出什么？
npx ts-node scripts/analyze-exports.ts src/api/

# 包括重新导出
npx ts-node scripts/analyze-exports.ts src/ --follow-reexports

# 显示依赖图
npx ts-node scripts/analyze-exports.ts src/ --deps

检测代码异味

快速架构评估：

# 完整分析
npx ts-node scripts/code-smells.ts src/

# 特定检查
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表面

# 获取大局：导出了什么？
npx ts-node scripts/extract-signatures.ts src/ --exported --json > api-surface.json

寻找：过于复杂的接口、不一致的命名、公共API缺少JSDoc

2. 依赖结构

# 映射导入 - 循环依赖是红旗
npx ts-node scripts/code-smells.ts src/ --check circular-deps

寻找：循环依赖、深层导入链、不清晰的模块边界

3. 函数复杂性

# 找到可能需要重构的复杂函数
npx ts-node scripts/code-smells.ts src/ --check large-functions --check many-params

寻找：函数超过50行、超过5个参数、深层嵌套

4. 文档覆盖

# 公共API应有文档
npx ts-node scripts/code-smells.ts src/ --check missing-jsdoc --exported

跟随数据痕迹

在调试时，无需读取完整文件即可追踪数据流：

模式：“这个值从哪里来？”

# 1. 找到谁使用坏值调用函数
npx ts-node scripts/trace-calls.ts src/service.ts:processData --up --depth 5

# 2. 获取调用者的签名以理解参数流
npx ts-node scripts/extract-signatures.ts src/caller.ts

模式：“这个返回值去哪里？”

# 1. 找到什么使用此函数的返回值
npx ts-node scripts/trace-calls.ts src/api.ts:fetchUser --down

# 2. 检查返回值如何被消费
npx ts-node scripts/trace-calls.ts src/api.ts:fetchUser --down --show-usage

模式：“错误的完整调用链”

# 获取从入口点到问题区域的完整路径
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`	检测架构问题

常见问题

问题	解决方案
“找不到模块 ‘ts-morph’”	在技能目录中运行 `npm install`
在大代码库上慢	添加 `--include "src/*/.ts"` 限制范围
缺少类型信息	确保tsconfig.json在项目根目录
内存问题	使用 `--exclude "node_modules"`（默认）