analyze_file_impact

analyze_file_impact

Analyze the impact (blast radius) of changing one or more files in your codebase. This tool helps you understand how many other modules depend on the files you’re about to modify, either directly or transitively.

Tip

Run this before refactoring core modules to assess risk and plan the scope of your changes.

Parameters

Parameter	Type	Required	Description
project_path	string	Yes	Absolute or relative path to the project root directory
file_paths	array of strings	Yes	List of file paths to analyze (relative to project root)

Response

Returns a JSON summary with metrics computed in the context of the changed files.

Response Schema

{
  "results": [
    {
      "id": "string",
      "values": {
        "key": "value"
      }
    }
  ],
  "violations": [],
  "changed_files_context": ["string"]  // Echo of input file_paths
}

Key Metrics

The tool uses the quick preset internally, which includes:

• SCC (cycles) — If changed files are inside a cycle, the blast radius is amplified
• Centrality — High betweenness centrality means changes will ripple widely
• L1 Overview — Risk categorization of changed files

Note

High centrality.module.betweenness_max (>0.3) indicates the file sits on many dependency paths. Changes to such files affect a large portion of the codebase.

Examples

Single file impact

Request:

{
  "project_path": ".",
  "file_paths": ["src/core/auth.ts"]
}

Response:

{
  "results": [
    {
      "id": "scc",
      "data": [
        { "key": "scc.max_cycle_size", "value": { "kind": "number", "v": 0 } }
      ]
    },
    {
      "id": "centrality",
      "data": [
        { "key": "centrality.module.betweenness_max", "value": { "kind": "number", "v": 0.42 } },
        { "key": "centrality.module.max_fan_in", "value": { "kind": "number", "v": 18 } },
        { "key": "centrality.module.max_fan_out", "value": { "kind": "number", "v": 3 } }
      ]
    }
  ],
  "violations": [],
  "changed_files_context": ["src/core/auth.ts"]
}

Interpretation:

• auth.ts has high betweenness (0.42) — it’s a critical dependency
• 18 modules depend on it (fan-in)
• It depends on only 3 modules (fan-out)
• Not in a cycle (max_cycle_size = 0)
• Risk: High — changes will ripple to 18+ modules

Multiple files impact

Request:

{
  "project_path": "/path/to/project",
  "file_paths": ["src/core/auth.ts", "src/core/session.ts", "src/utils/crypto.ts"]
}

Response:

{
  "results": [
    {
      "id": "scc",
      "data": [
        { "key": "scc.cycle_count", "value": { "kind": "number", "v": 1 } },
        { "key": "scc.max_cycle_size", "value": { "kind": "number", "v": 3 } }
      ]
    },
    {
      "id": "centrality",
      "values": {
        "centrality.module.betweenness_max": 0.58
      }
    }
  ],
  "violations": [],
  "changed_files_context": [
    "src/core/auth.ts",
    "src/core/session.ts",
    "src/utils/crypto.ts"
  ]
}

Interpretation:

• These 3 files form a circular dependency (max_cycle_size = 3)
• Extremely high betweenness (0.58) — critical hub
• Risk: Very high — break the cycle before refactoring

Workflow

Use this tool before making changes to understand impact:

1. analyze_file_impact → assess blast radius
2. If centrality is high:
   a. get_hotspots → find other tightly coupled modules
   b. suggest_refactors → get decoupling recommendations
3. If cycles exist:
   a. Follow cycle-breaking workflow (see check_cycles)

See Workflows: Impact analysis before a refactor for a full example.

Error Cases

Error	Cause	Solution
missing required parameter: file_paths	file_paths not provided	Include file_paths array in request
file_paths must be a non-empty array	Empty array provided	Include at least one file path
No such file or directory	Invalid project or file path	Verify paths exist and are relative to project root

Performance

• Speed: 1-5 seconds (uses quick preset)
• Caching: Does not use cache (always fresh analysis for changed files)
• Scalability: Efficiently handles 10+ files in a single request

Tip

For CI pipelines, combine this with git diff --name-only to automatically analyze all changed files in a PR.

Best Practices

When to use

• Before refactoring core modules
• Before renaming widely-used functions/classes
• In PR checks to assess change risk
• When planning large-scale migrations

Interpreting betweenness centrality

Betweenness	Risk Level	Recommendation
< 0.1	Low	Safe to modify
0.1 - 0.3	Moderate	Review dependents carefully
0.3 - 0.5	High	Consider introducing a facade/adapter
> 0.5	Very high	Break dependencies before refactoring

Interpreting fan-in/fan-out

• High fan-in (>10) — Many modules depend on this file (hub module)
• High fan-out (>10) — This file depends on many modules (potential god class)
• High both — Critical junction point — refactor with extreme caution

Related Tools

• check_cycles — Fast cycle detection
• get_hotspots — Find tightly coupled modules
• suggest_refactors — Get decoupling recommendations
• analyze_architecture — Full analysis with all metrics

Related Guides

• Centrality Metrics — Understanding betweenness, fan-in/out
• Refactoring Patterns — Common refactoring strategies

CLI Equivalent

# Analyze impact using CLI with changed files filter
arxo analyze --preset quick --changed-files src/core/auth.ts,src/core/session.ts