How Knowledge Gap Analysis Detects Untested Hotspots and Isolated Nodes in code-review-graph

The find_knowledge_gaps function in code_review_graph/analysis.py identifies isolated nodes by filtering for non-file nodes with a degree of ≤ 1, and detects untested hotspots by locating nodes with a degree of ≥ 5 that lack TESTED_BY edges and are not test files.

The tirth8205/code-review-graph repository implements this structural analysis to expose architectural weaknesses in codebases represented as graph structures. By walking the entire GraphStore and categorizing nodes based on connectivity and test coverage relationships, the analysis surfaces specific targets for refactoring and quality improvement. These detection mechanisms help engineering teams prioritize review efforts on disconnected components and critical untested hubs.

The Core Algorithm in analysis.py

The knowledge gap analysis centers on the find_knowledge_gaps function, which accepts a GraphStore instance containing the codebase graph. This function orchestrates the detection of structural weaknesses across four categories, with isolated nodes and untested hotspots representing the most critical connectivity and coverage gaps. The algorithm proceeds in distinct phases: first building a connectivity map, then applying specific thresholds to identify problematic nodes.

Step 1: Mapping Node Connectivity and Test Coverage

Before identifying gaps, the algorithm constructs a degree map by iterating over all edges in the graph. This phase counts total connections per node while simultaneously recording which nodes are covered by TESTED_BY relationships.

# Build degree map

degree: dict[str, int] = Counter()
tested_nodes: set[str] = set()
for e in edges:
    degree[e.source_qualified] += 1
    degree[e.target_qualified] += 1
    if e.kind == "TESTED_BY":
        tested_nodes.add(e.source_qualified)

This produces two essential data structures: degree, which tracks the total in-plus-out degree per node, and tested_nodes, which contains the set of nodes having at least one TESTED_BY edge. As implemented in code_review_graph/analysis.py lines 28‑34, this map enables downstream filtering based on connectivity volume and test coverage status.

Detecting Isolated Nodes with Low Connectivity

Isolated nodes represent code elements that are barely integrated into the system architecture. The algorithm defines these as non-file nodes whose degree is ≤ 1, indicating minimal or no connections to other components.

# 1. Isolated nodes (degree <= 1, not File)

isolated = []
for n in nodes:
    d = degree.get(n.qualified_name, 0)
    if d <= 1:
        isolated.append({
            "name": _sanitize_name(n.name),
            "qualified_name": n.qualified_name,
            "kind": n.kind,
            "file": n.file_path,
            "degree": d,
        })

Located in analysis.py lines 37‑48, this scan surfaces likely dead code, utility helpers with minimal reuse, or entry points never wired into the broader system. By highlighting these nodes, reviewers can evaluate whether the code should be removed, better integrated, or documented to address the knowledge gap.

Identifying High-Degree Untested Hotspots

Untested hotspots are architectural "hubs" that interact heavily with other components but lack any test coverage. The detection logic applies three strict criteria: the node must have a high degree (≥ 5 connections), must not appear in the tested_nodes set, and must itself not be a test node.

# 3. Untested hotspots (degree >= 5, no TESTED_BY)

untested_hotspots = []
for n in nodes:
    d = degree.get(n.qualified_name, 0)
    if (d >= 5
            and n.qualified_name not in tested_nodes
            and not n.is_test):
        untested_hotspots.append({
            "name": _sanitize_name(n.name),
            "qualified_name": n.qualified_name,
            "kind": n.kind,
            "file": n.file_path,
            "degree": d,
        })

This logic, found in analysis.py lines 72‑86, identifies the most impactful candidates for test creation. High-degree nodes without TESTED_BY edges represent significant knowledge gaps where defects could cascade through the system undetected.

Return Structure and Integration

After completing both scans, find_knowledge_gaps bundles the results into a structured dictionary for downstream consumption. The function truncates results to focus attention on the most critical items, returning up to 50 isolated nodes and 20 untested hotspots alongside other structural categories.

return {
    "isolated_nodes": isolated[:50],
    "thin_communities": thin,
    "untested_hotspots": untested_hotspots[:20],
    "single_file_communities": single_file,
}

According to analysis.py lines 104‑110, this return format enables direct integration with PR comment generators, dashboards, or automated review pipelines that transform these findings into actionable tasks.

Practical Code Examples

Running the analysis manually:

from code_review_graph.graph import GraphStore
from code_review_graph.analysis import find_knowledge_gaps

# Load a stored graph (e.g., from a previous scan)

store = GraphStore.load("my_project.graphml")

# Get knowledge‑gap report

gaps = find_knowledge_gaps(store)

print("Isolated nodes:")
for node in gaps["isolated_nodes"]:
    print(f"- {node['qualified_name']} (degree {node['degree']})")

print("\nUntested hotspots:")
for hot in gaps["untested_hotspots"]:
    print(f"- {hot['qualified_name']} (degree {hot['degree']})")

Generating review questions from results:

from code_review_graph.analysis import generate_suggested_questions

questions = generate_suggested_questions(store)

for q in questions:
    print(f"[{q['priority']}] {q['category']}: {q['question']}")

These examples demonstrate how the knowledge gap helpers return structured data suitable for automated tooling and manual review workflows.

Key Implementation Files

• code_review_graph/analysis.py – Implements find_knowledge_gaps, find_untested_hotspots, and find_isolated_nodes with the degree-mapping and filtering logic described above.
• code_review_graph/graph.py – Defines GraphStore, the in-memory representation of nodes and edges, providing get_all_edges() and get_all_nodes() for analysis consumption.
• code_review_graph/visualization.py – Optional utilities for rendering the graph and highlighting detected hotspots or isolated nodes.
• tests/test_graph.py – Contains unit tests verifying the correctness of the knowledge gap detection logic against sample graph structures.

Summary

• The knowledge gap analysis operates in code_review_graph/analysis.py via the find_knowledge_gaps function, which scans a GraphStore for structural weaknesses.
• Isolated nodes are detected by filtering for non-file nodes with ≤ 1 connection degree, identifying potentially unused or disconnected code.
• Untested hotspots require ≥ 5 connections, absence from the tested_nodes set (no TESTED_BY edge), and exclusion of test files themselves.
• The algorithm builds a comprehensive degree map first, then applies threshold-based filtering to categorize nodes by connectivity and coverage status.
• Results are returned as structured dictionaries suitable for integration with CI/CD pipelines, PR review tools, and engineering dashboards.

Frequently Asked Questions

How does the knowledge gap analysis define an isolated node?

An isolated node is defined as any node with a degree of one or fewer connections that is not a File type node. The algorithm in analysis.py lines 37‑48 iterates through all non-file nodes after building the degree map, selecting those where d <= 1 to identify potentially dead code or barely-utilized utilities.

What criteria classify a node as an untested hotspot?

A node becomes an untested hotspot when it meets three specific conditions: it has a high degree of five or more connections, its qualified name is absent from the tested_nodes set (meaning no TESTED_BY edge exists), and the node itself is not marked as a test file. As implemented in lines 72‑86 of analysis.py, these criteria ensure the analysis flags only production code that serves as an architectural hub without coverage.

Can the knowledge gap analysis be run outside of automated reviews?

Yes, developers can invoke the find_knowledge_gaps function manually by loading a GraphStore instance and passing it to the analyzer. The function returns a structured dictionary containing isolated nodes, untested hotspots, and other structural categories, which can be rendered in dashboards or used to generate review questions via helper functions like generate_suggested_questions.

What is the significance of the degree thresholds used in the analysis?

The thresholds of ≤ 1 for isolation and ≥ 5 for hotspots represent structural extremes in the dependency graph. Nodes with ≤ 1 connection are barely integrated into the system, while those with ≥ 5 connections act as critical integration points; the lack of tests for these high-degree nodes represents a significant knowledge gap and risk to code maintainability.

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