Resolves #1164

Overview

This PR implements the Semantic Code Impact Analysis & Change Propagation Engine. It enables developers to predict the blast radius of modifying a code symbol or file before merging changes, reducing the risk of regressions and speeding up code review.

It leverages the repository knowledge graph to traverse upstream dependencies (like callers, subclasses, decorator modifications, and injected classes), calculates a custom risk score, and displays propagation paths and testing recommendations.

Detailed Changes

1. Backend Engine & Graph Traversal (src/codegraphcontext/)

• Tool Registration (tool_definitions.py): Defined the analyze_impact tool accepting arguments: target (required), target_type, repo_path, and depth.
• API Handler (tools/handlers/analysis_handlers.py & server.py): Connected the tool call through the FastAPI REST server /api/tools/call.
• Cypher Traversal Engine (tools/code_finder.py): Implemented the core logic for the change propagation analyzer:
  • Target Auto-Detection: Dynamically resolves if the input target is a file path or a code symbol (Function, Class, Module, etc.). When a file is specified, it matches all symbols defined inside it.
  • Upstream Change Propagation: Executes a database-agnostic Cypher query traversing CALLS, INHERITS, IMPLEMENTS, INJECTS, DECORATED_BY, and IMPORTS relationships backward up to a configurable depth.
  • Multi-Database Compatibility: Utilizes standard Cypher list comprehensions for path projection (nodes(p) and relationships(p) mapping), making it fully compatible with Neo4j, FalkorDB, and KuzuDB.
  • Git Churn Integration: Spawns a local git process (git rev-list --count) to retrieve file modification counts, integrating historical churn into the risk calculations.
  • Rule-Based Explanation Generator: Automatically builds precise test scoping suggestions based on the dependency types found.

2. Risk Scoring System

Computes a normalized risk score out of 10.0 based on:

1. Depth Score (clamped to 5.0): Distance of the propagation path.
2. Blast Radius File Score (clamped to 5.0): Count of distinct files affected.
3. Criticality Score (clamped to 5.0): In-degree centrality (incoming links to target).
4. Historical Churn Score (clamped to 5.0): How often the target files are modified in git history.

3. Visual Dependency Explorer (website/)

• CodeGraphViewer UI Panel (CodeGraphViewer.tsx):
  • Added a Semantic Impact Explorer button (Zap icon) to the sidebar panel header.
  • Added a hybrid client-side/API resolver: queries the local python API if connected, and falls back to an in-memory BFS search on the client-side if offline or running in a static web build.
  • Rendered a rich dashboard: circular radial gauge color-coded by risk severity level (Green/Teal for Low, Orange for Medium, Red for High), breakdown metric cards, a blast radius list, and explanation cards.
  • Integrated visual force-graph highlighting: dims non-affected nodes/edges and applies color-coding directly to the 2D/3D force graph representations (Red for Target, Orange for Direct Impact, Yellow for Indirect Impact).

Verification & Testing

Automated Tests

Created unit test suite tests/unit/tools/test_impact_analysis.py covering target symbol resolution, file-level containment queries, risk scoring heuristics, empty states, and local Git command fallbacks.
Run commands:

$env:PYTHONPATH="src"; python -m pytest tests/unit/tools/test_impact_analysis.py

Status: All 3 tests passed successfully.

Manual Verification

• Verified backend /tools/call endpoint returns exact propagation paths.
• Verified that selecting a node in the graph explorer successfully highlights dependencies, updates the sidebar dashboard, and dims unrelated nodes in both 2D and 3D visual modes.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added unit tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes