codemap_traverse

Traverse the dependency graph from a starting file.

graphtraversedependencies

Parameters

Name	Type	Required	Description
`relativePath`	`string`	✅ Required	File path (relative or absolute)
`direction`	`string`imports \| importers	✅ Required	Traversal direction: 'imports' (what this file imports) or 'importers' (what imports this file)
`maxDepth`	`number`	❌ Optional	Maximum depth for traversal (default: 3)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_traverse",
  "arguments": {
    "relativePath": "src/types/user.ts",
    "direction": "importers",
    "maxDepth": 2
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "start": "src/types/user.ts",
  "direction": "importers",
  "maxDepth": 2,
  "files": [
    "src/api/users.ts",
    "src/features/auth.ts",
    "src/components/UserCard.vue",
    "src/pages/Profile.vue",
    "src/pages/Users.vue"
  ],
  "count": 5
}

ℹ️When to Use This Tool

codemap_traverse

Understand dependency depth - See how deep dependency chains go
Find transitive dependencies - Discover indirect dependencies through the chain
Map blast radius - Traverse importers to see who depends on a file
Build dependency graphs - Collect all relationships for visualization
Detect circular dependencies - Check if a file appears in its own dependency chain
Audit dependency counts - Compare imports vs importers at different depths
Migration planning - Find all files that need updating when changing a dependency

💡Common Patterns

Bidirectional Analysis

// Understand both upstream and downstream
const imports = await codemap.graph.traverse({
  relativePath: file,
  direction: 'imports',
  maxDepth: 3
});

const importers = await codemap.graph.traverse({
  relativePath: file,
  direction: 'importers',
  maxDepth: 3
});

console.log(Dependencies: ${imports.count});
console.log(Dependents: ${importers.count});

Circular Dependency Check

// Check if a file depends on itself transitively
const deps = await codemap.graph.traverse({
  relativePath: file,
  direction: 'imports',
  maxDepth: 3
});

if (deps.files.includes(file)) {
  console.warn('⚠️  Circular dependency detected!');
}

Progressive Depth Discovery

// See how dependency count grows with depth
for (let depth = 1; depth <= 3; depth++) {
  const result = await codemap.graph.traverse({
    relativePath: file,
    direction: 'imports',
    maxDepth: depth
  });
  
  console.log(Depth ${depth}: ${result.count} dependencies);
}

Full Dependency Network

// Build complete network map
const network = new Set();

const imports = await codemap.graph.traverse({
  relativePath: file,
  direction: 'imports',
  maxDepth: 3
});

const importers = await codemap.graph.traverse({
  relativePath: file,
  direction: 'importers',
  maxDepth: 3
});

[...imports.files, ...importers.files].forEach(f => network.add(f));
console.log(Network size: ${network.size} files);

💡Pro Tips

Use direction strategically - 'imports' finds what a file needs (downstream), 'importers' finds who needs it (upstream).

Start with depth=1, expand as needed - Shallow traversals are faster. Only go deeper if you need transitive relationships.

Max depth is capped at 3 - Deep traversals can be expensive. If you need more, consider multiple calls or using specialized tools.

Combine both directions - For complete context, traverse both imports and importers to understand a file's full network.

Watch for exponential growth - If depth=1 shows 5 files but depth=2 shows 50, you have high coupling.

Use for refactoring scope - Before moving a file, traverse importers to see what breaks.

✅Best Practices

Always compare depths - Run depth 1, 2, and 3 to understand how transitive dependencies grow.

Cache traversal results - If building graphs, cache results to avoid redundant traversals of the same files.

Use for documentation - Traverse results make excellent dependency diagrams in docs.

Track growth over time - Monitor if files' transitive dependency counts increase (signals coupling growth).

Validate circular dependencies - Regularly traverse to ensure no circular dependency chains form.

Set depth based on file type - Core types/APIs need depth=3, leaf components might only need depth=1.

⚠️Common Mistakes

❌ Mistake: Confusing direction semantics

// This gets who file depends ON (what it imports)
const result = await codemap.graph.traverse({
  relativePath: 'src/api/client.ts',
  direction: 'imports' // What client.ts imports
});

// Developer expects: files that use client.ts
// Actually gets: files that client.ts imports

✅ Instead: Use correct direction

// To find who uses client.ts:
const users = await codemap.graph.traverse({
  relativePath: 'src/api/client.ts',
  direction: 'importers' // Files that import client.ts
});

---

❌ Mistake: Not checking for exponential growth

const result = await codemap.graph.traverse({
  relativePath: file,
  direction: 'imports',
  maxDepth: 3
});

console.log(Total dependencies: ${result.count});
// Doesn't notice depth=1 had 5, depth=2 had 50, depth=3 has 500

✅ Instead: Check growth per depth

for (let depth = 1; depth <= 3; depth++) {
  const result = await codemap.graph.traverse({
    relativePath: file,
    direction: 'imports',
    maxDepth: depth
  });
  
  console.log(Depth ${depth}: ${result.count});
  
  if (depth > 1) {
    const prev = previousCount;
    const growth = result.count / prev;
    if (growth > 5) {
      console.warn(⚠️  Exponential growth at depth ${depth});
    }
  }
  previousCount = result.count;
}

---

❌ Mistake: Ignoring circular dependencies

const imports = await codemap.graph.traverse({
  relativePath: file,
  direction: 'imports',
  maxDepth: 3
});

// Doesn't check if file appears in its own dependencies

✅ Instead: Always check for cycles

const imports = await codemap.graph.traverse({
  relativePath: file,
  direction: 'imports',
  maxDepth: 3
});

if (imports.files.includes(file)) {
  console.error('⚠️  CIRCULAR DEPENDENCY DETECTED');
  console.log('This file depends on itself through the chain');
}

---

❌ Mistake: Using traverse for single-hop checks

// Overkill - traverse is for multi-hop analysis
const result = await codemap.graph.traverse({
  relativePath: file,
  direction: 'imports',
  maxDepth: 1
});

console.log('Direct imports:', result.files);

✅ Instead: Use get_dependencies for direct relationships

// More efficient for single-hop
const deps = await codemap.graph.getDependencies(file);
console.log('Direct imports:', deps.imports);

---

❌ Mistake: Not deduplicating when building graphs

const graph = { nodes: [], edges: [] };

const imports = await codemap.graph.traverse({
  relativePath: file,
  direction: 'imports',
  maxDepth: 2
});

imports.files.forEach(f => {
  graph.nodes.push(f); // Duplicates!
  graph.edges.push({ from: file, to: f });
});

✅ Instead: Use Set for deduplication

const graph = { nodes: new Set(), edges: [] };

const imports = await codemap.graph.traverse({
  relativePath: file,
  direction: 'imports',
  maxDepth: 2
});

graph.nodes.add(file);
imports.files.forEach(f => {
  graph.nodes.add(f); // No duplicates
  graph.edges.push({ from: file, to: f });
});

graph.nodes = Array.from(graph.nodes);