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

> Learn how knowledge gap analysis in code-review-graph pinpoints untested hotspots and isolated nodes. Discover code vulnerabilities with detailed insights.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: deep-dive
- Published: 2026-07-29

---

**The `find_knowledge_gaps` function in [`code_review_graph/analysis.py`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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.

```python

# 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`](https://github.com/tirth8205/code-review-graph/blob/main/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.

```python

# 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`](https://github.com/tirth8205/code-review-graph/blob/main/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.

```python

# 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`](https://github.com/tirth8205/code-review-graph/blob/main/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.

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

```

According to [`analysis.py`](https://github.com/tirth8205/code-review-graph/blob/main/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:**

```python
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:**

```python
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/visualization.py)** – Optional utilities for rendering the graph and highlighting detected hotspots or isolated nodes.
- **[`tests/test_graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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.