Code-Review-Graph Knowledge Graph Nodes and Edges: A Complete Schema Guide

The code-review-graph stores program structure in a SQLite-backed knowledge graph where nodes represent concrete code entities (File, Class, Function, Type, Test) and edges capture relationships (CALLS, IMPORTS_FROM, INHERITS, IMPLEMENTS, CONTAINS, TESTED_BY, DEPENDS_ON, REFERENCES) between them.

The tirth8205/code-review-graph project parses source code into a persistent knowledge graph to enable impact analysis and intelligent code review. Understanding the precise schema of code-review-graph knowledge graph nodes and edges is essential for querying the database or extending the parser. The implementation uses SQLite as the backing store, with strict typing enforced through Python dataclasses.

Understanding Node Types in the Code-Review-Graph

Nodes represent concrete code entities extracted during static analysis. According to the source code in code_review_graph/graph.py, the nodes table is defined with a mandatory kind column and metadata fields.

The Node Schema in graph.py

In code_review_graph/graph.py (lines 75-79), the SQLite schema defines nodes with the following columns:

• kind: The entity type (File, Class, Function, Type, or Test)
• name: The short identifier of the entity
• qualified_name: The fully qualified identifier used for cross-references
• file_path: Absolute or relative path to the source file
• line_start and line_end: The span of lines where the entity is defined
• language: Programming language identifier (e.g., "python", "javascript")
• params and return_type: Optional metadata for callable entities

Each node acts as a vertex in the graph, uniquely identified by its qualified name.

The NodeInfo Dataclass

The concrete Python representation lives in code_review_graph/parser.py (lines 66-81). The NodeInfo dataclass mirrors the database schema:

@dataclass
class NodeInfo:
    kind: str  # File, Class, Function, Type, Test

    name: str
    qualified_name: str
    file_path: str
    line_start: int
    line_end: int
    language: str
    is_test: bool
    parent_name: Optional[str] = None
    params: Optional[str] = None
    return_type: Optional[str] = None

Concrete Node Kinds

The five mandatory node kinds cover the primary semantic constructs in modern codebases:

• File: Represents a source code file; acts as the root container for other entities
• Class: Object-oriented class definitions, including nested classes
• Function: Standalone functions and methods, storing parameter signatures and return types
• Type: Type aliases, interfaces, and abstract type definitions
• Test: Specialized nodes marking test functions or test classes (often cross-referenced via TESTED_BY edges)

Understanding Edge Relationships in the Code-Review-Graph

Edges capture directed relationships between nodes, enabling graph traversal for impact analysis.

The Edge Schema in graph.py

In code_review_graph/graph.py (lines 94-100), the edges table schema stores:

• kind: The relationship type (CALLS, IMPORTS_FROM, INHERITS, IMPLEMENTS, CONTAINS, TESTED_BY, DEPENDS_ON, REFERENCES, DEPENDS_ON_CONFIG)
• source: Qualified name of the originating node
• target: Qualified name of the destination node
• file_path: Location where the relationship is declared or inferred
• line: Specific line number where the relationship originates
• confidence: Float score indicating certainty (0.0-1.0)
• extra_data: JSON blob for additional metadata

The EdgeInfo Dataclass

Defined in code_review_graph/parser.py (lines 93-98), the EdgeInfo dataclass provides the Python interface:

@dataclass
class EdgeInfo:
    kind: str
    source: str  # qualified name of source node

    target: str  # qualified name of target node

    file_path: str
    line: int
    confidence: float = 1.0
    extra_data: Optional[Dict[str, Any]] = None

Relationship Types and Semantics

The kind column enumerates nine distinct relationship types:

• CALLS: Function-to-function invocations, including method calls
• IMPORTS_FROM: Module or package import dependencies
• INHERITS: Class inheritance relationships (child to parent)
• IMPLEMENTS: Interface or protocol conformance
• CONTAINS: Parent-child containment (File contains Function, Class contains Method)
• TESTED_BY: Links production code to its corresponding test entities
• DEPENDS_ON: Generic dependency between components
• DEPENDS_ON_CONFIG: Special edge type for configuration-key dependencies (e.g., environment variables)
• REFERENCES: General symbol references not covered by CALLS or IMPORTS_FROM

Working with Nodes and Edges in Python

The GraphStore class in code_review_graph/graph.py provides CRUD operations for both entities. Below is a practical example demonstrating node creation, edge insertion, and querying:

from pathlib import Path
from code_review_graph.graph import GraphStore
from code_review_graph.parser import NodeInfo, EdgeInfo

# Open (or create) a graph database

store = GraphStore(Path("/tmp/crg.db"))

# Insert a file node

file_node = NodeInfo(
    kind="File",
    name="src/example.py",
    file_path="src/example.py",
    line_start=0,
    line_end=0,
    language="python",
    is_test=False,
)
store.upsert_node(file_node)

# Insert a function node

func_node = NodeInfo(
    kind="Function",
    name="greet",
    file_path="src/example.py",
    line_start=10,
    line_end=14,
    language="python",
    parent_name=None,
    params="name: str",
    return_type="str",
    is_test=False,
)
store.upsert_node(func_node)

# Record a CALLS edge (greet calls print)

call_edge = EdgeInfo(
    kind="CALLS",
    source="src/example.py::greet",
    target="builtins::print",
    file_path="src/example.py",
    line=12,
)
store.upsert_edge(call_edge)

# Query all function nodes

functions = [n for n in store.get_all_nodes() if n.kind == "Function"]
print(functions)

# Find outgoing CALLS edges from a function

outgoing_calls = store.get_edges_by_source("src/example.py::greet")
print(outgoing_calls)

store.close()

This snippet demonstrates the core workflow: initialize GraphStore, persist NodeInfo objects via upsert_node(), create EdgeInfo relationships via upsert_edge(), and retrieve entities using get_all_nodes() and get_edges_by_source().

Key Source Files and Architecture

Understanding the repository layout helps navigate the implementation of the knowledge graph schema:

• code_review_graph/graph.py: Core SQLite schema definitions, GraphStore class, and CRUD operations for nodes and edges
• code_review_graph/parser.py: NodeInfo and EdgeInfo dataclasses, plus utilities for path normalization and language detection
• code_review_graph/constants.py: Impact-analysis weights and directional defaults for edge kinds (particularly for DEPENDS_ON traversal)
• code_review_graph/visualization.py: Rendering logic that styles different edge kinds with specific colors and dash patterns for graph visualization

Summary

• Nodes represent five concrete code entity types: File, Class, Function, Type, and Test, storing location and metadata in code_review_graph/graph.py
• Edges model nine relationship types (CALLS, IMPORTS_FROM, INHERITS, IMPLEMENTS, CONTAINS, TESTED_BY, DEPENDS_ON, REFERENCES, DEPENDS_ON_CONFIG) with source/target qualified names and confidence scores
• NodeInfo and EdgeInfo dataclasses in code_review_graph/parser.py provide the typed Python interface to the SQLite schema
• GraphStore handles persistence, offering upsert_node(), upsert_edge(), and query methods like get_edges_by_source()

Frequently Asked Questions

What are the valid node kinds in the code-review-graph knowledge graph?

The valid node kinds are File, Class, Function, Type, and Test. These are stored in the mandatory kind column of the nodes table defined in code_review_graph/graph.py (lines 75-79). Each kind corresponds to a specific code construct that the parser extracts during static analysis, with Test nodes specifically identifying test functions and classes for coverage analysis.

How are edges physically stored in the SQLite database?

Edges are stored in a dedicated table with columns for kind, source (qualified name), target (qualified name), file_path, line, confidence, and extra_data. The schema definition resides in code_review_graph/graph.py (lines 94-100). The source and target columns reference the qualified_name field of nodes, creating a foreign-key-like relationship without explicit SQLite foreign key constraints.

What is the difference between CONTAINS and IMPORTS_FROM edges?

CONTAINS edges represent structural containment within the same file or scope, such as a File containing a Function or a Class containing a Method. IMPORTS_FROM edges represent cross-module dependencies where one file imports symbols from another module. While CONTAINS edges are hierarchical and intra-file, IMPORTS_FROM edges are inter-file dependencies that drive the import graph analysis.

How do I query all outgoing edges from a specific function?

Use the GraphStore.get_edges_by_source() method, passing the qualified name of the function as the argument. For example, store.get_edges_by_source("src/example.py::greet") returns a list of EdgeInfo objects representing all relationships (calls, references, etc.) originating from that function. You can filter the results further by checking the kind attribute of each returned EdgeInfo instance.

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