ts-morph-analyzer
Use when debugging TypeScript/JavaScript bugs by tracing call chains, understanding unfamiliar codebases quickly, making architectural decisions, or reviewing code quality. Extract function signatures and JSDoc without full file reads, trace call hierarchies up/down, detect code smells, and follow data flow. Triggers on debugging, understanding codebase, architectural analysis, signature extraction, call tracing.
How do I install this agent skill?
npx skills add https://github.com/ratacat/claude-skills --skill ts-morph-analyzerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a suite of static analysis tools for TypeScript and JavaScript codebases. It is designed to extract API signatures, trace call hierarchies, and identify code smells. The skill operates locally using the ts-morph library and does not exhibit any malicious behaviors.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
2/9 files flagged
What does this agent skill do?
TypeScript Codebase Analyzer
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.
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 |
Setup
# In the skill directory
cd ~/.claude/skills/ts-morph-analyzer
npm install
Or run the setup script:
~/.claude/skills/ts-morph-analyzer/setup.sh
Quick Reference
Extract Signatures (Most Common)
Get function/method signatures + JSDoc without reading full files:
# 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
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>
Trace Call Hierarchy
Follow function calls up (who calls this?) or down (what does this call?):
# 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)
Analyze Exports
Map a module's public API surface:
# 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
Detect Code Smells
Quick architectural assessment:
# 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
Architectural Assessment Patterns
When analyzing a new codebase for potential issues:
1. Public API Surface First
# 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
2. Dependency Structure
# 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
3. Function Complexity
# 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
4. Documentation Coverage
# Public APIs should be documented
npx ts-node scripts/code-smells.ts src/ --check missing-jsdoc --exported
Following the Data Trail
When debugging, trace data flow without reading full files:
Pattern: "Where does this value come from?"
# 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
Pattern: "Where does this return value go?"
# 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
Pattern: "Full call chain for a bug"
# Get complete path from entry point to problem area
npx ts-node scripts/trace-calls.ts src/broken.ts:problematicFn --up --tree
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 |
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) |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/ratacat/claude-skills/ts-morph-analyzer">View ts-morph-analyzer on skillZs</a>