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

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 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:

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.

Programmatic Gap Retrieval via MCP Tools

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

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:

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 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	Documents the graph schema, BFS impact‑radius algorithm, and gap detection logic
docs/COMMANDS.md	Defines CLI commands (detect-changes, visualize) and MCP tools (get_knowledge_gaps_tool, detect_changes_tool)
code_review_graph/visualization.py	Renders the interactive force‑directed graph with gap highlighting capabilities
code_review_graph/tsconfig_resolver.py	Resolves TypeScript path aliases to ensure accurate import edges for JavaScript/TypeScript projects
scripts/render_pr_comment.py	Formats risk‑scored gap reports for GitHub Action PR comments
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.

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. Each format includes risk scores, qualified names, and blast radius metadata for prioritization.

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