codemap_impact_analysis

Multi-hop blast radius analysis.

graphimpactanalysisblast-radius

Parameters

Name	Type	Required	Description
`target`	`string`	✅ Required	File path or symbol reference
`depth`	`number`	❌ Optional	Maximum depth for traversal (default: 2, max: 3)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_impact_analysis",
  "arguments": {
    "target": "src/utils/helpers.ts"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "file": "src/utils/helpers.ts",
  "depth": 2,
  "affectedFiles": [
    "src/features/dashboard.ts",
    "src/api/routes.ts",
    "src/components/Header.vue",
    "src/pages/Home.vue",
    "src/pages/Dashboard.vue"
  ],
  "affectedCount": 5
}

ℹ️When to Use This Tool

codemap_impact_analysis

Before refactoring - Understand the full scope of files that will be affected
Risk assessment - Evaluate if a change is too risky to make in one PR
Test planning - Identify all files that need testing after a change
Breaking change detection - Find if core type or API changes will cascade
Release planning - Group related changes by their impact overlap
Code review prep - Show reviewers the full blast radius of changes
Migration planning - Understand the scope before migrating shared utilities

💡Common Patterns

Pre-Refactoring Safety Check

async function safeToRefactor(file: string, maxImpact: number = 20): Promise {
  const impact = await codemap.graph.impactAnalysis({ target: file, depth: 3 });
  
  if (impact.affectedCount > maxImpact) {
    console.warn(High risk: ${impact.affectedCount} files affected);
    console.log('Consider breaking into smaller changes');
    return false;
  }
  
  console.log(✓ Safe to refactor (${impact.affectedCount} files affected));
  return true;
}

Progressive Depth Analysis

// Start shallow, go deeper if needed
for (let depth = 1; depth <= 3; depth++) {
  const impact = await codemap.graph.impactAnalysis({ 
    target: 'src/types/api.ts', 
    depth 
  });
  console.log(Depth ${depth}: ${impact.affectedCount} files);
  
  if (impact.affectedCount > 50) {
    console.warn('Stopping - blast radius too large');
    break;
  }
}

Change Grouping by Impact

// Group files by their impact overlap
const changes = ['src/types/user.ts', 'src/types/post.ts'];
const impacts = [];

for (const file of changes) {
  const impact = await codemap.graph.impactAnalysis({ target: file, depth: 2 });
  impacts.push({ file, affected: new Set(impact.affectedFiles) });
}

// Find overlap
const overlap = Array.from(impacts[0].affected).filter(f => 
  impacts[1].affected.has(f)
);

console.log(Overlapping impact: ${overlap.length} files);

Test Coverage Identification

// Find all files that need testing
const impact = await codemap.graph.impactAnalysis({ 
  target: 'src/core/auth.ts', 
  depth: 3 
});

const testFiles = impact.affectedFiles.map(file => 
  file.replace(/\.ts$/, '.spec.ts')
);

console.log('Test files to update:');
testFiles.forEach(f => console.log(  - ${f}));

💡Pro Tips

Always check depth=3 for core files - Core utilities, types, and APIs should be analyzed at maximum depth to understand full impact.

Compare depths incrementally - Run depth 1, 2, and 3 to see how impact grows. Large jumps indicate high coupling.

Set team thresholds - Establish impact limits (e.g., changes affecting >30 files require extra review).

Use for backward compatibility - Before deprecating APIs, run impact analysis to identify all consumers.

Combine with testing - Use affected files list to determine minimum test coverage needed.

Document high-impact files - Files with depth=1 impact >20 should be documented as architectural hubs.

✅Best Practices

Run before every refactor - Make this part of your pre-refactoring checklist.

Check at maximum depth for breaking changes - Type changes, API changes, and utility refactors need depth=3 analysis.

Use impact counts to split PRs - If impact >30 files, consider breaking into smaller changes.

Track impact over time - Monitor if files' blast radii grow (indicates increasing coupling).

Plan testing based on impact - Affected files list directly informs test plan.

Communicate impact in PRs - Include blast radius in PR descriptions for reviewers.

Validate with CI - Consider adding impact analysis checks to CI to flag high-risk changes.

⚠️Common Mistakes

❌ Mistake: Only checking depth=1

// Shallow check misses transitive effects
const impact = await codemap.graph.impactAnalysis({ 
  target: 'src/types/common.ts',
  depth: 1 
});
// Might show 3 files, but depth=3 shows 25!

✅ Instead: Use depth=3 for core files

const impact = await codemap.graph.impactAnalysis({ 
  target: 'src/types/common.ts',
  depth: 3 
});
console.log(Full impact: ${impact.affectedCount} files);

---

❌ Mistake: Ignoring high impact counts

const impact = await codemap.graph.impactAnalysis({ target: file, depth: 3 });
console.log(${impact.affectedCount} files affected);
// Proceeds with refactor anyway even though impact is 87 files

✅ Instead: Set thresholds and act on them

const impact = await codemap.graph.impactAnalysis({ target: file, depth: 3 });

if (impact.affectedCount > 30) {
  console.error('Blast radius too large - split into smaller changes');
  process.exit(1);
}

---

❌ Mistake: Not accounting for affected file content

// All affected files treated equally
const impact = await codemap.graph.impactAnalysis({ target: file, depth: 2 });
console.log(${impact.affectedCount} files need review);

✅ Instead: Prioritize by file type

const impact = await codemap.graph.impactAnalysis({ target: file, depth: 2 });

const critical = impact.affectedFiles.filter(f => 
  f.includes('/api/') || f.includes('/pages/')
);

console.log(${impact.affectedCount} total, ${critical.length} critical);

---

❌ Mistake: Using impact analysis for deletion safety

// Wrong tool - need exact count, not transitive
const impact = await codemap.graph.impactAnalysis({ target: file, depth: 2 });
if (impact.affectedCount === 0) {
  await codemap.delete({ target: file });
}

✅ Instead: Use get_dependencies for deletion

const deps = await codemap.graph.getDependencies(file);
if (deps.importedByCount === 0) {
  await codemap.delete({ target: file });
}

---

❌ Mistake: Not considering both directions

// Only checks who depends on this file (downstream)
const impact = await codemap.graph.impactAnalysis({ target: file, depth: 3 });
// But what if file's dependencies change? (upstream)

✅ Instead: Check dependencies too

const impact = await codemap.graph.impactAnalysis({ target: file, depth: 3 });
const deps = await codemap.graph.getDependencies(file);

console.log('Downstream impact:', impact.affectedCount);
console.log('Upstream dependencies:', deps.importCount);
console.log('Total context:', impact.affectedCount + deps.importCount);