get_cross_file_dependencies¶

Analyze all dependencies a function or class needs from other files, recursively resolving imports and extracting the complete dependency chain.

Quick Reference¶

get_cross_file_dependencies(
    target_file: str,                    # File containing symbol
    target_symbol: str,                  # Symbol to analyze
    project_root: str = None,            # Project directory
    max_depth: int = 3,                  # Resolution depth
    include_code: bool = True,           # Include source code
    include_diagram: bool = True,        # Include Mermaid diagram
    confidence_decay_factor: float = 0.9 # Confidence decay per level
) -> CrossFileDependencies

User Stories¶

Persona	Story	Tool Value
👥 David (Team Lead)	"Understand dependencies before approving changes"	Better code reviews
🔧 Chris (OSS Contributor)	"Understand module relationships with confidence scoring"	Dependency analysis
🏢 Jennifer (Enterprise Architect)	"Trace dependencies across enterprise-scale systems"	Comprehensive analysis

→ See all user stories

Parameters¶

Parameter	Type	Required	Default	Description
`target_file`	string	Yes	-	Path to file (relative to project root)
`target_symbol`	string	Yes	-	Function or class name
`project_root`	string	No	cwd	Project root directory
`max_depth`	int	No	3	Maximum dependency depth
`include_code`	bool	No	true	Include source code
`include_diagram`	bool	No	true	Include Mermaid diagram
`confidence_decay_factor`	float	No	0.9	Confidence decay per level

Response Schema¶

{
  "data": {
    "target_file": "string",
    "target_symbol": "string",
    "dependencies": [
      {
        "symbol": "string",
        "file": "string",
        "type": "string",
        "depth": "integer",
        "confidence": "float",
        "code": "string | null",
        "line_start": "integer",
        "line_end": "integer"
      }
    ],
    "dependency_graph": {
      "nodes": ["string"],
      "edges": [{"from": "string", "to": "string"}]
    },
    "combined_code": "string",
    "circular_dependencies": ["string"],
    "low_confidence_count": "integer",
    "low_confidence_warning": "string | null",
    "mermaid_diagram": "string"
  },
  "tier_applied": "string",
  "duration_ms": "integer"
}

Examples¶

Analyze Function Dependencies¶

AI PromptMCP Tool CallCLI CommandResponse

What dependencies does process_order need from other files?

{
  "target_file": "services/order_service.py",
  "target_symbol": "process_order"
}

codescalpel get-cross-file-dependencies services/order_service.py --symbol process_order

{
  "data": {
    "target_file": "services/order_service.py",
    "target_symbol": "process_order",
    "dependencies": [
      {
        "symbol": "Order",
        "file": "models/order.py",
        "type": "class",
        "depth": 1,
        "confidence": 0.9,
        "code": "class Order:\n    def __init__(self, items, customer_id):\n        ...",
        "line_start": 10,
        "line_end": 45
      },
      {
        "symbol": "validate_order",
        "file": "validators/order_validator.py",
        "type": "function",
        "depth": 1,
        "confidence": 0.9,
        "code": "def validate_order(data: dict) -> bool:\n    ...",
        "line_start": 15,
        "line_end": 35
      },
      {
        "symbol": "calculate_total",
        "file": "utils/pricing.py",
        "type": "function",
        "depth": 1,
        "confidence": 0.9,
        "code": "def calculate_total(items: list) -> float:\n    ..."
      },
      {
        "symbol": "PricingRule",
        "file": "models/pricing.py",
        "type": "class",
        "depth": 2,
        "confidence": 0.81,
        "code": "class PricingRule:\n    ..."
      }
    ],
    "dependency_graph": {
      "nodes": ["process_order", "Order", "validate_order", "calculate_total", "PricingRule"],
      "edges": [
        {"from": "process_order", "to": "Order"},
        {"from": "process_order", "to": "validate_order"},
        {"from": "process_order", "to": "calculate_total"},
        {"from": "calculate_total", "to": "PricingRule"}
      ]
    },
    "combined_code": "# From models/order.py\nclass Order:\n    ...\n\n# From validators/order_validator.py\ndef validate_order(data: dict) -> bool:\n    ...\n\n# From utils/pricing.py\ndef calculate_total(items: list) -> float:\n    ...\n\n# From models/pricing.py\nclass PricingRule:\n    ...\n\n# From services/order_service.py\ndef process_order(data: dict) -> Order:\n    ...",
    "circular_dependencies": [],
    "low_confidence_count": 0,
    "mermaid_diagram": "graph TD\n    process_order --> Order\n    process_order --> validate_order\n    process_order --> calculate_total\n    calculate_total --> PricingRule"
  },
  "tier_applied": "pro",
  "duration_ms": 245
}

Deep Dependency Analysis¶

AI PromptMCP Tool CallCLI CommandResponse

Get all dependencies of UserService up to 5 levels deep

{
  "target_file": "services/user_service.py",
  "target_symbol": "UserService",
  "max_depth": 5
}

codescalpel get-cross-file-dependencies services/user_service.py \
  --symbol UserService \
  --max-depth 5

{
  "data": {
    "target_symbol": "UserService",
    "dependencies": [
      {"symbol": "User", "file": "models/user.py", "depth": 1, "confidence": 0.9},
      {"symbol": "Database", "file": "db/database.py", "depth": 1, "confidence": 0.9},
      {"symbol": "validate_email", "file": "validators.py", "depth": 1, "confidence": 0.9},
      {"symbol": "BaseModel", "file": "models/base.py", "depth": 2, "confidence": 0.81},
      {"symbol": "Connection", "file": "db/connection.py", "depth": 2, "confidence": 0.81},
      {"symbol": "EmailValidator", "file": "validators/email.py", "depth": 2, "confidence": 0.81},
      {"symbol": "Config", "file": "config.py", "depth": 3, "confidence": 0.729},
      {"symbol": "Pool", "file": "db/pool.py", "depth": 3, "confidence": 0.729}
    ],
    "low_confidence_count": 2,
    "low_confidence_warning": "2 symbols at depth 3+ have confidence < 0.75. Results may be less reliable."
  }
}

Detect Circular Dependencies¶

AI PromptMCP Tool CallCLI CommandResponse

Check if AuthService has any circular dependencies

{
  "target_file": "services/auth_service.py",
  "target_symbol": "AuthService",
  "max_depth": 4
}

codescalpel get-cross-file-dependencies services/auth_service.py \
  --symbol AuthService \
  --max-depth 4

{
  "data": {
    "target_symbol": "AuthService",
    "dependencies": [...],
    "circular_dependencies": [
      "AuthService -> UserService -> AuthService"
    ],
    "warning": "Circular dependency detected. This may cause import errors."
  }
}

Confidence Decay¶

Confidence decreases with depth:

Depth	Confidence (factor=0.9)
0	1.000 (target symbol)
1	0.900
2	0.810
3	0.729
4	0.656
5	0.590

Symbols with confidence < 0.5 are flagged as "low confidence".

Mermaid Diagram¶

The tool generates dependency visualizations:

graph TD
    subgraph "services/order_service.py"
        process_order
    end

    subgraph "models/order.py"
        Order
    end

    subgraph "validators/order_validator.py"
        validate_order
    end

    subgraph "utils/pricing.py"
        calculate_total
    end

    process_order --> Order
    process_order --> validate_order
    process_order --> calculate_total

Tier Differences¶

This tool is available at all tiers. What differs are the limits and capabilities:

Feature	Community	Pro	Enterprise
Availability	✅ Available	✅ Available	✅ Available
Basic dependency analysis	✅	✅ Advanced	✅ Advanced
Max depth	2	5	Unlimited
Include code	✅	✅	✅
Confidence decay factor	0.9	0.9	0.9 (configurable)
Combined code output	Not available	✅	✅
Mermaid diagrams	Not available	✅	✅
Circular detection	Not available	✅	✅
Confidence scoring	Not available	✅	✅
Custom resolution	Not available	Not available	✅

Community Tier

Cross-file dependency analysis is available in Community tier with basic analysis (2 depth max, code extraction). For deeper analysis, diagrams, and circular dependency detection, consider upgrading to Pro or Enterprise.

Use Cases¶

1. Extract with Full Context¶

# Get all code needed to understand a function
result = get_cross_file_dependencies(
    target_file="services/order_service.py",
    target_symbol="process_order",
    include_code=True
)

# combined_code contains everything needed
print(result.combined_code)

2. Refactoring Impact¶

# Before refactoring, understand dependencies
result = get_cross_file_dependencies(
    target_file="models/user.py",
    target_symbol="User",
    max_depth=5
)

# Check what depends on User
print(f"User is used by {len(result.dependencies)} symbols")

3. Module Extraction¶

# Find what's needed to extract a module
result = get_cross_file_dependencies(
    target_file="services/payment_service.py",
    target_symbol="PaymentService",
    max_depth=3
)

# combined_code shows what to include in extracted module

Tier Limits¶

get_cross_file_dependencies capabilities vary by tier:

Feature	Community	Pro	Enterprise
Max depth	1	5	Unlimited
Max files analyzed	50	500	Unlimited
Dependency resolution	Basic	✅ Advanced	✅ Full
Circular import detection	✅	✅	✅
Confidence scoring	✅	✅	✅ Enhanced
Code extraction	✅	✅	✅
Mermaid diagrams	✅	✅	✅ Advanced

Community Tier¶

✅ Analyze cross-file dependencies
✅ Detect circular imports
✅ Basic confidence scoring
✅ Extract dependency code
⚠️ Max depth of 1 - Direct dependencies only
⚠️ Limited to 50 files - May miss transitive dependencies
❌ No deep dependency chain analysis

Pro Tier¶

✅ All Community features
✅ Max depth of 5 - Trace deeper dependency chains
✅ 500 files analyzed - Handle larger projects
✅ Advanced resolution - Better import path detection
✅ Enhanced confidence scoring - More accurate reliability estimates
✅ Timeout protection - Handles large codebases gracefully

Enterprise Tier¶

✅ All Pro features
✅ Unlimited depth - Complete dependency chain
✅ Unlimited files - No project size restrictions
✅ Full semantic analysis - Understand dependency relationships
✅ Low confidence warnings - Flag unreliable deep dependencies
✅ Graph query language - Custom dependency queries

Key Difference: Depth and Scale - Community: Depth 1, 50 files - Immediate dependencies only - Pro: Depth 5, 500 files - Multi-level dependency tracking - Enterprise: Unlimited - Complete dependency graph

→ See tier comparison

Best Practices¶

Start shallow - Use max_depth=2 first, increase if needed
Check confidence - Low confidence = verify manually
Watch for circular deps - Fix before they cause issues
Use combined_code - For AI context, include all deps
Review diagrams - Visualize before refactoring

get_call_graph - Function call relationships
get_project_map - Project structure overview
extract_code - Extract with context

get_cross_file_dependencies¶

Quick Reference¶

User Stories¶

Parameters¶

Response Schema¶

Examples¶

Analyze Function Dependencies¶

Deep Dependency Analysis¶

Detect Circular Dependencies¶

Confidence Decay¶

Mermaid Diagram¶

Tier Differences¶

Use Cases¶

1. Extract with Full Context¶

2. Refactoring Impact¶

3. Module Extraction¶

Tier Limits¶

Community Tier¶

Pro Tier¶

Enterprise Tier¶

Best Practices¶

Related Tools¶