Skip to main content

​
Overview

The impact tool performs blast radius analysis to show what will be affected if you change a specific symbol. It returns affected symbols grouped by depth (d=1, d=2, d=3), risk assessment, affected execution flows, and impacted functional modules. This is essential before making any non-trivial code changes.
When to use: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.Next step: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.

​
Parameters

​
target
string
required
Name of function, class, method, or file to analyzeExamples:
  • "validateUser"
  • "AuthService"
  • "src/auth/validator.ts"
​
direction
string
required
Analysis direction:
  • "upstream" - What depends on this (most common)
  • "downstream" - What this depends on
​
maxDepth
number
default:3
Maximum relationship depth to traverse
  • d=1: Direct dependencies (WILL BREAK)
  • d=2: Indirect dependencies (LIKELY AFFECTED)
  • d=3: Transitive dependencies (MAY NEED TESTING)
Range: 1-5 recommended
​
relationTypes
array
Filter by relationship types. If omitted, uses usage-based inference.Options:
  • "CALLS" - Function/method calls
  • "IMPORTS" - Import statements
  • "EXTENDS" - Class inheritance
  • "IMPLEMENTS" - Interface implementation
Example: ["CALLS", "IMPORTS"]
​
includeTests
boolean
default:false
Include test files in the analysisSet to true when you need to know which tests will break.
​
minConfidence
number
Minimum confidence threshold (0-1) for relationships
  • 1.0: Certain relationships
  • 0.8-0.99: High confidence
  • 0.7-0.79: Good confidence
  • Below 0.7: Fuzzy matches
Lower this to catch more potential impacts at the cost of false positives.
​
repo
string
Repository name or path. Required when multiple repos are indexed.

​
Response

​
risk
string
required
Overall risk assessment: LOW, MEDIUM, HIGH, or CRITICAL
​
summary
object
required
High-level impact summary
​
byDepth
object
required
Affected symbols grouped by traversal depthEach array contains symbols with:
  • name: Symbol name
  • type: Symbol type
  • filePath: File location
  • line: Line number
  • edgeType: Relationship type (CALLS, IMPORTS, etc.)
  • confidence: Confidence score (0-1)
​
affected_processes
array
Execution flows that will be impacted
​
affected_modules
object
Functional areas impacted, categorized by impact type

​
Example Usage

​
Basic Upstream Impact

impact({
  target: "validateUser",
  direction: "upstream"
})

​
High-Confidence Analysis

impact({
  target: "processPayment",
  direction: "upstream",
  minConfidence: 0.9,
  maxDepth: 2
})

​
Include Test Impact

impact({
  target: "AuthService",
  direction: "upstream",
  includeTests: true
})

​
Filter by Relationship Type

impact({
  target: "validateCard",
  direction: "upstream",
  relationTypes: ["CALLS"]
})

​
Multi-Repo Impact

impact({
  target: "loginHandler",
  direction: "upstream",
  repo: "my-app"
})

​
Example Response

{
  "risk": "MEDIUM",
  "summary": {
    "directCallers": 2,
    "affectedProcesses": 2,
    "affectedModules": 1,
    "totalAffected": 5
  },
  "byDepth": {
    "d1": [
      {
        "name": "loginHandler",
        "type": "Function",
        "filePath": "src/auth/login.ts",
        "line": 42,
        "edgeType": "CALLS",
        "confidence": 1.0
      },
      {
        "name": "apiMiddleware",
        "type": "Function",
        "filePath": "src/api/middleware.ts",
        "line": 15,
        "edgeType": "CALLS",
        "confidence": 1.0
      }
    ],
    "d2": [
      {
        "name": "authRouter",
        "type": "Function",
        "filePath": "src/routes/auth.ts",
        "line": 22,
        "edgeType": "CALLS",
        "confidence": 0.95
      }
    ]
  },
  "affected_processes": [
    {
      "name": "LoginFlow",
      "step": 2,
      "totalSteps": 5
    },
    {
      "name": "TokenRefresh",
      "step": 1,
      "totalSteps": 3
    }
  ],
  "affected_modules": {
    "direct": ["Authentication"],
    "indirect": ["API"]
  }
}

​
Risk Assessment Guide

Criteria:
  • Less than 5 affected symbols
  • Few or no affected processes
  • Single module impact
Action: Proceed with caution, review d=1 items
Criteria:
  • 5-15 affected symbols
  • 2-5 affected processes
  • Multiple modules
Action: Careful review, test affected processes
Criteria:
  • 15 affected symbols
  • Many processes affected
  • Cross-module impact
Action: Comprehensive testing, consider staged rollout
Criteria:
  • Critical path affected (auth, payments, core infrastructure)
  • Widespread impact
Action: Extensive testing, staged deployment, monitoring plan

​
Depth Interpretation

DepthRisk LevelMeaningAction Required
d=1WILL BREAKDirect callers/importersMust update these
d=2LIKELY AFFECTEDIndirect dependenciesReview and likely update
d=3MAY NEED TESTINGTransitive effectsTest thoroughly

​
Real-World Examples

​
Example 1: Safe Change Analysis

// Task: "Is it safe to change validateUser?"
impact({
  target: "validateUser",
  direction: "upstream",
  minConfidence: 0.8
})

// Result:
// - d=1: 2 direct callers (loginHandler, apiMiddleware)
// - d=2: 1 indirect (authRouter)
// - Risk: MEDIUM
// Action: Update loginHandler and apiMiddleware, test LoginFlow

​
Example 2: Critical Infrastructure

// Task: "What breaks if I change the database connection?"
impact({
  target: "connectDB",
  direction: "upstream",
  maxDepth: 2
})

// Result:
// - d=1: 15 direct callers across all modules
// - Risk: CRITICAL
// Action: Don't change signature, consider deprecation path

​
Example 3: Refactoring Prep

// Task: "I want to split this large function"
impact({
  target: "processCheckout",
  direction: "upstream",
  includeTests: true
})

// Result:
// - d=1: 3 callers + 2 test files
// - Affected: CheckoutFlow, RefundFlow
// - Risk: MEDIUM
// Action: Split function, update 3 callers, fix 2 test files

​
Best Practices

Use direction: "upstream" to find what depends on your target. This shows what will break.
These are guaranteed to break. Review and plan updates for every d=1 item before making changes.
Items with confidence below 0.8 may be false positives. Review these manually.
Processes reveal the business impact. Breaking “LoginFlow” is more critical than breaking a utility function.
When refactoring, set includeTests: true to know which tests need updates.
After making changes, run detect_changes() to verify only expected items were affected.

​
Use Cases

  • Pre-change analysis: “Is it safe to modify this?”
  • Refactoring planning: “What do I need to update?”
  • Risk assessment: “How risky is this change?”
  • Breaking change detection: “What’s the blast radius?”
  • Test planning: “What tests will break?”
  • context - Deep dive on specific affected symbols
  • detect_changes - Post-change verification
  • rename - Automated refactoring for renames
  • gitnexus://repo/{name}/processes - Review affected execution flows
  • gitnexus://repo/{name}/clusters - Understand module boundaries

Build docs developers (and LLMs) love

Get started for freeTalk to us