Code Graph Query

Overview

A skill that helps Claude Code understand and navigate the dependency graph of your codebase — tracing function call chains, mapping component relationships, identifying impact areas before making changes, and finding unused or circular dependencies. Essential for safe refactoring and understanding complex codebases.

When to Use

• Before refactoring: understand what depends on the code you're changing
• Investigating bugs: trace the call chain from entry point to failure
• Code reviews: assess the blast radius of a change
• Architecture analysis: visualize component relationships
• Dead code detection: find unused functions and modules
• Dependency auditing: identify circular or unnecessary dependencies

Quick Start

Copy
# Find all callers of a function
claude "Who calls the validateUser function?"

# Trace a dependency chain
claude "Show me the full call chain from the /api/orders endpoint to the database"

# Find impact of a change
claude "What would break if I change the User interface?"

# Find unused exports
claude "Find all exported functions that are never imported"

Core Principle

Read code → Query dependency graph → Understand impact → Then modify

Never change a widely-used function without first understanding its callers.

Graph Query Types

1. Callers (Who calls this?)

Find all functions that call a specific function:

Copy
# Direct callers
grep -rn "validateUser(" src/ --include="*.ts"

# Including dynamic calls
grep -rn "validateUser\|validate.*User" src/ --include="*.ts"

Example output:

src/controllers/authController.ts:45:  const valid = await validateUser(input);
src/services/registrationService.ts:23:  await validateUser(userData);
src/middleware/auth.ts:67:  if (!validateUser(token.payload)) return next(err);

→ 3 callers across 3 files. Changing validateUser impacts auth, registration, and middleware.

2. Callees (What does this call?)

Find all functions called by a specific function:

Copy
# Read the function and trace its calls
claude "Read the processOrder function and list every external function it calls"

Example:

processOrder()
├── validateOrder()
├── checkInventory()
├── calculateTotal()
│   ├── applyDiscount()
│   └── calculateTax()
├── chargePayment()
└── sendConfirmationEmail()

→ Changing calculateTax only affects calculateTotal → processOrder.

3. Import Graph

Map module dependencies:

Copy
# Find all imports in a file
grep -n "^import\|^const.*require" src/services/orderService.ts

# Find all importers of a module
grep -rn "from.*orderService\|require.*orderService" src/ --include="*.ts"

# Build full import tree
claude "Map the complete import tree for src/services/orderService.ts"

4. Type Dependencies

Trace interface/type usage:

Copy
# Find all files using a type
grep -rn "User\b" src/ --include="*.ts" | grep -v "node_modules\|\.test\."

# Find type extensions
grep -rn "extends User\|Partial<User>\|Pick<User\|Omit<User" src/

5. Component Relationships

For React/frontend codebases:

Copy
# Find all components that render <UserProfile>
grep -rn "<UserProfile" src/components/ --include="*.tsx"

# Find all components imported by a page
grep -n "^import" src/pages/Dashboard.tsx

# Find props drilling chains
claude "Trace how the 'user' prop flows from App.tsx down to leaf components"

Impact Analysis

Before Changing a Function

1. Find all callers              → grep -rn "functionName(" src/
2. Check test coverage           → grep -rn "functionName" tests/
3. Check if it's in the API      → grep -rn "functionName" src/routes/
4. Check if it's exported        → grep -n "export.*functionName" src/
5. Assess blast radius           → How many files? How critical?

Impact Matrix

Change Type	Risk	Check
Rename function	Medium	All callers must update
Change params	High	All callers must match new signature
Change return type	High	All consumers must handle new type
Delete function	Critical	Must find all usages first
Add optional param	Low	Existing callers unaffected
Internal refactor	Low	If signature unchanged

Circular Dependency Detection

Copy
# Find potential circular imports
claude "Check for circular dependencies in src/services/"

# Common pattern:
# A imports B, B imports A → Circular!
# Fix: Extract shared code to C, both import C

Resolution strategies:

1. Extract shared code to a third module
2. Use dependency injection instead of direct imports
3. Lazy imports for runtime-only dependencies
4. Interface segregation — depend on abstractions

Dead Code Detection

Copy
# Find exported functions never imported elsewhere
claude "Find all exported functions in src/utils/ that are never imported by any other file"

# Find unused components
claude "Find React components in src/components/ that are never rendered by any page or other component"

# Find unused types
claude "Find TypeScript interfaces in src/types/ that are never referenced"

Visualization

Text-Based Dependency Tree

src/pages/OrderPage.tsx
├── src/components/OrderForm.tsx
│   ├── src/components/ProductSelector.tsx
│   ├── src/components/AddressForm.tsx
│   └── src/hooks/useOrderForm.ts
│       └── src/services/orderService.ts
│           ├── src/services/inventoryService.ts
│           └── src/services/paymentService.ts
├── src/components/OrderSummary.tsx
└── src/hooks/useOrder.ts
    └── src/services/orderService.ts (shared)

Mermaid Diagram

Copy
graph TD
    A[OrderPage] --> B[OrderForm]
    A --> C[OrderSummary]
    B --> D[orderService]
    C --> D
    D --> E[inventoryService]
    D --> F[paymentService]

Best Practices

1. Always check callers before changing signatures — The compiler catches types, but not logic
2. Map the full tree for risky changes — One level of callers isn't enough
3. Use tests as documentation — Tests show how functions are actually used
4. Keep dependency graphs shallow — Deep chains are hard to reason about
5. Prefer explicit imports — Avoid barrel files (index.ts) that hide dependencies
6. Run dead code detection regularly — Remove unused code to reduce complexity
7. Watch for circular dependencies — They cause import ordering issues and bundling problems
8. Document architectural boundaries — Which modules should never depend on each other