Import Graph Debugging

Import Graph Debugging

Problem: Empty Import Graph

When explain_file shows no callers or imports, the import graph may not be populated correctly.

---

Diagnostic Tool

Use the built-in diagnostics tool:

# Summary of import graph
node sigmap-diagnostics.js --summary

# Analyze specific file
node sigmap-diagnostics.js --file src/models/account.py

# Search for files matching pattern
node sigmap-diagnostics.js --grep scheduler

# Verbose output
node sigmap-diagnostics.js --file src/models/account.py --verbose

Expected output:

• Shows files that import the target file
• Shows what the file imports
• Summary stats on detected edges

---

Common Causes

1. Python Absolute Imports Not Detected

Symptom: Files with from models.account import Account show no imports

Fix: Ensure v6.10.10+ (latest version with R language support)

npm install -g sigmap@latest

Verify:

sigmap --version
# Should be 6.10.10 or later

2. Missing __init__.py Files

Symptom: Python package structure not recognized

Check:

find src -name "__init__.py" | wc -l

Fix: Add __init__.py to all package directories:

src/models/__init__.py
src/services/__init__.py

3. Relative Import Paths Too Deep

Symptom: from ...utils import helper not resolved

Debug:

sigmap-diagnostics.js --file src/deep/nested/module.py --verbose

Fix: Ensure srcDirs includes the root:

{
  "srcDirs": ["src"]
}

4. External Dependencies Mixed In

Symptom: Import graph includes npm/pip packages

Filter: Check .contextignore excludes node_modules/, site-packages/

---

Testing Import Graph

Test on Simple Project

mkdir test-import
cd test-import
mkdir src/models src/services

cat > src/models/account.py << 'EOF'
class Account:
    def __init__(self, name):
        self.name = name
EOF

cat > src/services/scheduler.py << 'EOF'
from models.account import Account

def process_accounts():
    return Account('test')
EOF

cat > src/models/__init__.py << 'EOF'
EOF

cat > src/services/__init__.py << 'EOF'
EOF

cat > package.json << 'EOF'
{"name": "test"}
EOF

# Generate and test
node gen-context.js
node sigmap-diagnostics.js --file src/models/account.py

# Should show: scheduler.py imports account.py

---

MCP Tools Testing

After diagnostics show imports are detected:

node -e "
const { explainFile } = require('./src/mcp/handlers.js');
const result = explainFile({ path: 'src/models/account.py' }, process.cwd());
console.log(result);
" | grep -A 10 "## Callers"

# Should show files that import account.py

---

Performance Considerations

Large import graphs (5000+ edges) can be slow:

# Benchmark import analysis
time node sigmap-diagnostics.js --summary

If >5 seconds, consider:

• Excluding generated code
• Using per-module strategy
• Limiting srcDirs

---

For v6.10.10+ (Python Imports & Full Language Support)

The following patterns are now detected:

✅ from models.account import Account
✅ from services.scheduler import process_accounts
✅ from services.auth.oauth import get_token
✅ Relative imports: from . import sibling
✅ Relative imports: from .. import parent

❌ Star imports: from models import * (security)
❌ Dynamic imports: __import__('models.account')

---

Still Having Issues?

1. Run full diagnostics:

   sigmap-diagnostics.js --file <problem-file> --verbose

2. Check Testing Guide

3. Open issue with:

   • Output of node sigmap-diagnostics.js --summary
   • File structure (sample tree)
   • Actual imports in files