What Are Architectural Hotspots Identified by `get_hub_nodes_tool`?

Architectural hotspots are high-degree code entities—functions, classes, and modules with the densest incoming and outgoing dependency connections in the repository graph—identified by the get_hub_nodes_tool through degree-based ranking that explicitly excludes file nodes.

The get_hub_nodes_tool in the tirth8205/code-review-graph repository analyzes the structural dependency graph of a codebase to pinpoint these critical architectural junctions. By mapping CALLS and CALLED_BY relationships, the tool reveals which entities serve as central hubs, helping developers prioritize refactoring efforts and risk mitigation strategies.

How get_hub_nodes_tool Identifies Architectural Hotspots

Degree Calculation and Graph Metrics

The tool calculates the degree of each node as the sum of inbound (CALLED_BY) and outbound (CALLS) edges. In [code_review_graph/main.py at line 811](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py#L811), the implementation ranks nodes by this total connectivity metric. Nodes with the highest degree scores—representing the most interconnected functions, classes, or modules—are designated as architectural hotspots because their modification or failure would have the broadest impact on the system.

Exclusion of File-Level Nodes

Unlike raw dependency scanners that map file-to-file relationships, this tool explicitly filters out File nodes to focus on architectural entities. The logic in [code_review_graph/main.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) restricts hotspot detection to code elements such as functions, classes, and modules. This ensures the results reflect structural complexity and architectural significance rather than simple file system organization.

Untested Hotspots: High Connectivity Without Coverage

A critical subset identified by the tool is untested hotspots—nodes with high architectural degree (typically degree ≥ 5) that lack any TESTED_BY relationships. The detection algorithm in [code_review_graph/analysis.py (lines 172-186)](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/analysis.py#L172) flags these entities as high-risk components that centralize logic but have no automated verification. The final payload returned by the tool, compiled around line 208, includes both standard hotspots and this untested subset, providing a comprehensive risk profile for quality assurance prioritization.

Implementation Details in the Source Code

The hotspot detection pipeline spans three primary files that define, implement, and expose the functionality:

• code_review_graph/main.py: Orchestrates the tool execution and documents the architectural hotspot definition, specifically noting the exclusion of file nodes and the degree-based ranking criteria.
• code_review_graph/analysis.py: Contains the core graph traversal algorithms, including the degree calculation logic and the untested hotspot detection rules (lines 172-186), along with the result aggregation that formats the final hotspot lists.
• code_review_graph/tools/analysis_tools.py: Provides the MCP tool wrapper and CLI integration, registering the function as get_hub_nodes_tool and handling parameter validation for limit controls.

Practical Usage Examples

You can invoke the tool programmatically via Python or through the command-line interface.

# Programmatic usage

from code_review_graph.main import get_hub_nodes_tool

result = get_hub_nodes_tool()

print("Top Architectural Hotspots:")
for node in result["hotspots"]:
    print(f"- {node['name']} (degree: {node['degree']}, callers: {len(node['callers'])})")

print("\nHigh-Risk Untested Hotspots:")
for node in result["untested_hotspots"]:
    print(f"- {node['name']} (degree: {node['degree']}, callees: {len(node['callees'])})")

# CLI usage via the crg command

crg get_hub_nodes_tool --limit 15

Both methods return a structured JSON object containing:

• hotspots: A list of high-degree nodes with metrics including total degree, caller entities, and callee entities.
• untested_hotspots: A filtered subset of high-degree nodes that have no associated test coverage (absence of TESTED_BY edges).

Summary

• Architectural hotspots are defined as code entities with the highest total degree (sum of inbound and outbound edges) in the repository dependency graph.
• The get_hub_nodes_tool specifically excludes file nodes to focus on functional architectural elements like functions, classes, and modules.
• Untested hotspots represent a high-risk category of well-connected nodes lacking test coverage, identified when degree ≥ 5 and no TESTED_BY relationships exist.
• Core implementation resides in [code_review_graph/analysis.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/analysis.py) with orchestration logic in [code_review_graph/main.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py).
• The tool outputs detailed metrics including degree counts, caller lists, and callee lists to guide architectural decisions.

Frequently Asked Questions

What constitutes an architectural hotspot in code-review-graph?

An architectural hotspot is any non-file code entity—such as a function, class, or module—that exhibits a high degree of connectivity within the repository's dependency graph. The get_hub_nodes_tool ranks these entities by the sum of their CALLS and CALLED_BY edges, selecting those with the highest connectivity scores as hotspots due to their central role in the software architecture.

How does get_hub_nodes_tool differ from standard dependency analysis?

Standard dependency analysis typically maps file-level relationships, whereas get_hub_nodes_tool operates at the entity level and applies a degree-based threshold to identify architectural criticality. It further differentiates between general hotspots and untested hotspots by verifying the presence of TESTED_BY relationships, offering a risk assessment that standard graph analysis does not provide.

What is the significance of untested hotspots?

Untested hotspots are high-degree architectural nodes that centralize application logic but lack any automated test coverage. These nodes pose elevated risks because cascading failures originating here propagate throughout the system without automated detection. The tool highlights these in [code_review_graph/analysis.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/analysis.py) to direct testing efforts toward the most structurally critical yet unverified components.

Can the hotspot detection threshold be configured?

The tool supports configuration of the output limit via CLI parameters (e.g., --limit 20), which controls how many top-ranked hotspots are returned. However, the internal degree threshold for identifying untested hotspots (defaulting to 5) and the exclusion criteria for file nodes are defined as constants within the source code, specifically in [code_review_graph/analysis.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/analysis.py), requiring source modification to adjust these architectural risk thresholds.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}