# What Is Knowledge Gap Analysis and How Does It Identify Structural Weaknesses?

> Understand knowledge gap analysis, a graph traversal technique that identifies structural weaknesses in codebases by finding missing metadata, untested functions, and unresolved dependencies.

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

---

**Knowledge gap analysis is a graph‑traversal technique that walks a codebase’s knowledge graph to find missing metadata—particularly untested functions and unresolved dependencies—revealing structural weaknesses that could lead to regressions or maintenance nightmares.**

In the `code-review-graph` open‑source repository, knowledge gap analysis serves as the intelligence layer that transforms raw source code into actionable review context. By representing files, classes, and functions as nodes and their relationships (imports, calls, inheritance, and test coverage) as edges, the tool can programmatically spot exactly where the code structure is fragile or incomplete.

## How Knowledge Gap Analysis Works in code-review-graph

The analysis operates on a persistent, incrementally‑updated knowledge graph stored in an SQLite database (`.code-review-graph/graph.db`). Each node represents a language‑level entity—files, classes, functions, or tests—while edges capture structural relationships such as `CALLS`, `IMPORTS`, `INHERITS_FROM`, and critically, `TESTED_BY`.

### Building the Knowledge Graph Foundation

The process begins with `code-review-graph build`, which parses every tracked file using Tree‑sitter to extract qualified names and their relationships. This data is persisted in [`docs/architecture.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/architecture.md) describes the schema and storage layer that enables efficient querying of millions of edges without reloading the entire codebase into memory.

### Detecting Changes and Impact Radius

When analyzing a pull request or working directory, the `detect_changes_tool` (exposed via CLI as `detect-changes`) first identifies modified files using `get_changed_files()`. It then invokes `get_impact_radius()` to perform a bidirectional breadth‑first search (BFS) expanding forward and reverse edges up to a configurable `max_depth` (default **2 hops**). This blast‑radius captures downstream consumers and upstream dependencies that might be affected by the change, ensuring the gap analysis focuses on relevant code paths rather than the entire repository.

### Identifying Structural Weaknesses

For every node within the impact radius, the engine checks for the presence of required edges. The most critical check looks for `TESTED_BY` edges; nodes lacking this link are flagged as **test gaps**. Additional validations scan for unresolved import edges, orphaned nodes with no callers (dead code), and inheritance relationships that fail to resolve to qualified names.

## Types of Structural Weaknesses Detected

Knowledge gap analysis in `code-review-graph` categorizes structural weaknesses into four specific gap types:

- **Untested functions and methods**: Nodes without a `TESTED_BY` edge detected by `detect_changes_tool` and `get_knowledge_gaps_tool`. These represent uncovered code paths that may introduce regressions.

- **Missing callers or callees**: Nodes that lack inbound or outbound call edges within the 2‑hop blast radius. This indicates dead code or isolated modules that are difficult to reason about and refactor safely.

- **Unresolved imports and inheritance**: Edges that cannot be resolved to qualified names after parsing, often signaling broken builds, missing dependencies, or hidden runtime failures.

- **Community cohesion problems**: Clusters identified by `list_communities_tool` that exhibit low internal cohesion or excessive coupling. These structural weaknesses highlight subsystems that are either too fragmented or dangerously intertwined.

## Practical Implementation and Code Examples

The following examples demonstrate how to invoke knowledge gap analysis via CLI and programmatic interfaces.

### CLI Detection of Test Gaps

Run a read‑only analysis on the current working tree to surface untested functions within the impact radius:

```bash
code-review-graph detect-changes --brief

```

Typical output highlights structural weaknesses immediately:

```

⚠️  Test gaps
  - src/auth.py::verify_token  (no test)
  - src/auth.py::logout        (no test)

🧭  Impact radius: 2 hops, 12 affected nodes

```

The `--brief` flag skips source extraction for speed while still performing the full BFS gap analysis described in [`docs/COMMANDS.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/COMMANDS.md).

### Programmatic Gap Retrieval via MCP Tools

Integrate gap detection into custom workflows using the Model Context Protocol (MCP) tools:

```python
from crg.mcp import query_graph_tool, get_knowledge_gaps_tool

# Retrieve all knowledge gaps in the repository

gaps = get_knowledge_gaps_tool(repo_root=".")
print([g["qualified_name"] for g in gaps["test_gaps"]])

```

This returns a list of qualified names (e.g., `['src/auth.py::verify_token', 'src/auth.py::logout']`) that lack test coverage, enabling automated enforcement of testing policies.

### Visualizing Structural Weaknesses

Launch the interactive D3.js visualization to explore gaps graphically:

```bash
code-review-graph visualize --serve

```

Navigate to `http://localhost:8765` and apply the "untested" filter to highlight nodes with missing `TESTED_BY` edges. The visualization logic in [`code_review_graph/visualization.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/visualization.py) applies special CSS classes to these nodes, making structural weaknesses visually obvious during architectural reviews.

## Core Implementation Files

Understanding the following source files provides complete insight into how knowledge gap analysis identifies structural weaknesses:

| File | Role |
|------|------|
| [`docs/architecture.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/architecture.md) | Documents the graph schema, BFS impact‑radius algorithm, and gap detection logic |
| [`docs/COMMANDS.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/COMMANDS.md) | Defines CLI commands (`detect-changes`, `visualize`) and MCP tools (`get_knowledge_gaps_tool`, `detect_changes_tool`) |
| [`code_review_graph/visualization.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/visualization.py) | Renders the interactive force‑directed graph with gap highlighting capabilities |
| [`code_review_graph/tsconfig_resolver.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tsconfig_resolver.py) | Resolves TypeScript path aliases to ensure accurate import edges for JavaScript/TypeScript projects |
| [`scripts/render_pr_comment.py`](https://github.com/tirth8205/code-review-graph/blob/main/scripts/render_pr_comment.py) | Formats risk‑scored gap reports for GitHub Action PR comments |
| [`tests/test_changes.py`](https://github.com/tirth8205/code-review-graph/blob/main/tests/test_changes.py) | Unit tests asserting correct detection of test gaps and impact radius calculations |

## Summary

- **Knowledge gap analysis** traverses a persisted knowledge graph to locate missing `TESTED_BY` edges, unresolved imports, and orphaned code.
- The **2‑hop BFS impact radius** ensures analysis remains focused on code affected by current changes, avoiding noise from unrelated subsystems.
- **Structural weaknesses** manifest as untested functions, dead code, broken inheritance chains, and low‑cohesion communities.
- Results are consumable via **CLI**, **Python MCP tools**, and **interactive visualizations**, with risk scoring based on blast radius depth and community criticality.

## Frequently Asked Questions

### What is the difference between knowledge gap analysis and traditional code coverage?

Traditional coverage tools measure line execution during test runs, while knowledge gap analysis operates statically on the graph structure. It can identify untested functions before tests even run and detect structural weaknesses like missing callers or unresolved imports that coverage tools cannot see, as implemented in `code-review-graph`'s static analysis pipeline.

### How does the blast radius calculation work in knowledge gap analysis?

The blast radius uses a bidirectional BFS starting from changed files, expanding through `CALLS` and `IMPORTS` edges up to `max_depth` (default 2). This captures both upstream dependencies and downstream effects, ensuring the `get_knowledge_gaps_tool` only reports gaps within the meaningful impact zone of a change, as documented in [`docs/architecture.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/architecture.md).

### Can knowledge gap analysis detect architectural decay in legacy codebases?

Yes. By analyzing community cohesion via `list_communities_tool`, the system identifies clusters with low internal connectivity or excessive external coupling. These metrics reveal structural weaknesses like tightly‑coupled monoliths or fragmented microservices that traditional linting cannot detect, making it ideal for legacy refactoring projects.

### What output formats does code-review-graph support for gap reports?

The tool emits gap reports through multiple channels: human‑readable CLI tables (`detect-changes --brief`), JSON via MCP tools (`get_knowledge_gaps_tool`), and formatted Markdown for GitHub PR comments generated by [`scripts/render_pr_comment.py`](https://github.com/tirth8205/code-review-graph/blob/main/scripts/render_pr_comment.py). Each format includes risk scores, qualified names, and blast radius metadata for prioritization.