TypeScript Codebase Analyzer

TypeScript代码库分析器

Overview

概述

Lightweight codebase analysis using ts-morph. Extract signatures, JSDoc, and call chains without flooding context with full file reads.

Core principle: Get maximum architectural insight with minimum token usage.

使用ts-morph实现轻量级代码库分析。无需读取完整文件即可提取签名、JSDoc和调用链，避免上下文信息过载。

核心原则：用最少的令牌消耗获取最大的架构洞察。

When to Use

适用场景

Situation	Script to Use
Understand a codebase's public API quickly	`extract-signatures.ts`
Trace a bug through function calls	`trace-calls.ts`
Map what a module exports	`analyze-exports.ts`
Detect architectural issues before diving in	`code-smells.ts`
Understand import/dependency structure	`analyze-exports.ts --deps`

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

Setup

安装设置

bash

undefined

bash

undefined

In the skill directory

在技能目录中

cd ~/.claude/skills/ts-morph-analyzer npm install


Or run the setup script:
```bash
~/.claude/skills/ts-morph-analyzer/setup.sh

cd ~/.claude/skills/ts-morph-analyzer npm install


或者运行安装脚本：
```bash
~/.claude/skills/ts-morph-analyzer/setup.sh

Quick Reference

快速参考

Extract Signatures (Most Common)

提取签名（最常用）

Get function/method signatures + JSDoc without reading full files:

bash

undefined

无需读取完整文件即可获取函数/方法签名 + JSDoc：

bash

undefined

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

以JSON格式输出以便后续处理

npx ts-node scripts/extract-signatures.ts src/ --json


**Output example:**

// 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>

undefined

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>

undefined

Trace Call Hierarchy

追踪调用层级

Follow function calls up (who calls this?) or down (what does this call?):

bash

undefined

向上（谁调用了这个函数？）或向下（这个函数调用了什么？）追踪函数调用：

bash

undefined

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


**Output example (--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)

undefined

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)

undefined

Analyze Exports

分析导出内容

Map a module's public API surface:

bash

undefined

映射模块的公开API范围：

bash

undefined

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

undefined

npx ts-node scripts/analyze-exports.ts src/ --deps

undefined

Detect Code Smells

检测代码异味

Quick architectural assessment:

bash

undefined

快速架构评估：

bash

undefined

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

undefined

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

undefined

Architectural Assessment Patterns

架构评估模式

When analyzing a new codebase for potential issues:

在分析新代码库以查找潜在问题时：

1. Public API Surface First

1. 先看公开API范围

bash

undefined

bash

undefined

Get the big picture: what's exported?

获取全局视图：导出了哪些内容？

npx ts-node scripts/extract-signatures.ts src/ --exported --json > api-surface.json

Look for: Overly complex interfaces, inconsistent naming, missing JSDoc on public APIs

npx ts-node scripts/extract-signatures.ts src/ --exported --json > api-surface.json

关注：过于复杂的接口、不一致的命名、公开API缺少JSDoc

2. Dependency Structure

2. 依赖结构

bash

undefined

bash

undefined

Map imports - circular deps are red flags

映射导入 - 循环依赖是危险信号

npx ts-node scripts/code-smells.ts src/ --check circular-deps

Look for: Circular dependencies, deep import chains, unclear module boundaries

npx ts-node scripts/code-smells.ts src/ --check circular-deps

关注：循环依赖、深层导入链、模糊的模块边界

3. Function Complexity

3. 函数复杂度

bash

undefined

bash

undefined

Find complex functions that may need refactoring

查找可能需要重构的复杂函数

npx ts-node scripts/code-smells.ts src/ --check large-functions --check many-params

Look for: Functions >50 lines, >5 parameters, deep nesting

npx ts-node scripts/code-smells.ts src/ --check large-functions --check many-params

关注：超过50行的函数、超过5个参数的函数、深层嵌套

4. Documentation Coverage

4. 文档覆盖率

bash

undefined

bash

undefined

Public APIs should be documented

公开API应该有文档

npx ts-node scripts/code-smells.ts src/ --check missing-jsdoc --exported

undefined

npx ts-node scripts/code-smells.ts src/ --check missing-jsdoc --exported

undefined

Following the Data Trail

跟踪数据流

When debugging, trace data flow without reading full files:

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

Pattern: "Where does this value come from?"

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

bash

undefined

bash

undefined

1. Find who calls the function with the bad value

1. 找到谁用错误的值调用了该函数

npx ts-node scripts/trace-calls.ts src/service.ts:processData --up --depth 5

2. Get signatures of callers to understand parameter flow

2. 获取调用者的签名以理解参数流向

npx ts-node scripts/extract-signatures.ts src/caller.ts

undefined

npx ts-node scripts/extract-signatures.ts src/caller.ts

undefined

Pattern: "Where does this return value go?"

模式：“这个返回值去向何方？”

bash

undefined

bash

undefined

1. Find what uses this function's return

1. 找到谁使用了该函数的返回值

npx ts-node scripts/trace-calls.ts src/api.ts:fetchUser --down

2. Check how return values are consumed

2. 检查返回值的使用方式

npx ts-node scripts/trace-calls.ts src/api.ts:fetchUser --down --show-usage

undefined

npx ts-node scripts/trace-calls.ts src/api.ts:fetchUser --down --show-usage

undefined

Pattern: "Full call chain for a bug"

模式：“bug的完整调用链”

bash

undefined

bash

undefined

Get complete path from entry point to problem area

获取从入口点到问题区域的完整路径

npx ts-node scripts/trace-calls.ts src/broken.ts:problematicFn --up --tree

undefined

npx ts-node scripts/trace-calls.ts src/broken.ts:problematicFn --up --tree

undefined

Script Locations

脚本位置

All scripts in:

~/.claude/skills/ts-morph-analyzer/scripts/

Script	Purpose
`extract-signatures.ts`	Extract function/method/class signatures with JSDoc
`trace-calls.ts`	Trace call hierarchies up/down
`analyze-exports.ts`	Map module exports and dependencies
`code-smells.ts`	Detect architectural issues

所有脚本位于：

~/.claude/skills/ts-morph-analyzer/scripts/

脚本	用途
`extract-signatures.ts`	提取带JSDoc的函数/方法/类签名
`trace-calls.ts`	向上/向下追踪调用层级
`analyze-exports.ts`	映射模块导出内容和依赖
`code-smells.ts`	检测架构问题

Common Issues

常见问题

Problem	Solution
"Cannot find module 'ts-morph'"	Run `npm install` in skill directory
Slow on large codebases	Add `--include "src/*/.ts"` to limit scope
Missing type info	Ensure tsconfig.json is in project root
Memory issues	Use `--exclude "node_modules"` (default)

问题	解决方案
"Cannot find module 'ts-morph'"	在技能目录中运行 `npm install`
在大型代码库上运行缓慢	添加 `--include "src/*/.ts"` 以限制范围
缺少类型信息	确保tsconfig.json位于项目根目录
内存问题	使用 `--exclude "node_modules"` （默认已启用）

ts-morph-analyzer

Original

Translation

TypeScript Codebase Analyzer

TypeScript代码库分析器

Overview

概述

When to Use

适用场景

Setup

安装设置

In the skill directory

在技能目录中

Quick Reference

快速参考

Extract Signatures (Most Common)

提取签名（最常用）

All signatures in a file

文件中的所有签名

All signatures in a directory (recursive)

目录中的所有签名（递归）

Filter to exported only

仅过滤导出的内容

Include types and interfaces

包含类型和接口

Output as JSON for further processing

以JSON格式输出以便后续处理

Trace Call Hierarchy

追踪调用层级

Who calls this function?

谁调用了这个函数？

What does this function call?

这个函数调用了什么？

Full call chain (both directions, limited depth)

完整调用链（双向，限制深度）

Output as tree

以树形结构输出

Analyze Exports

分析导出内容

What does this module export?

这个模块导出了什么？

Include re-exports

包含重导出内容

Show dependency graph

显示依赖图

Detect Code Smells

检测代码异味

Full analysis

完整分析

Specific checks

特定检查

Architectural Assessment Patterns

架构评估模式

1. Public API Surface First

1. 先看公开API范围

Get the big picture: what's exported?

获取全局视图：导出了哪些内容？

2. Dependency Structure

2. 依赖结构

Map imports - circular deps are red flags

映射导入 - 循环依赖是危险信号

3. Function Complexity

3. 函数复杂度

Find complex functions that may need refactoring

查找可能需要重构的复杂函数

4. Documentation Coverage

4. 文档覆盖率

Public APIs should be documented

公开API应该有文档

Following the Data Trail

跟踪数据流

Pattern: "Where does this value come from?"

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

1. Find who calls the function with the bad value

1. 找到谁用错误的值调用了该函数

2. Get signatures of callers to understand parameter flow

2. 获取调用者的签名以理解参数流向

Pattern: "Where does this return value go?"

模式：“这个返回值去向何方？”

1. Find what uses this function's return