CRG Graph Query Patterns: 15 Built-In Relationship Queries for Code Review Analysis

CRG graph query patterns include 15 built-in relationship types—such as callers_of, references_to, tests_for, inheritors_of, and publishers_of—defined in the _QUERY_PATTERNS constant and exposed through the query_graph API.

The Code‑Review‑Graph (CRG) from tirth8205/code-review-graph provides a structured graph query system for exploring code relationships programmatically. Developers use these patterns to answer questions about function calls, test coverage, inheritance hierarchies, and event-driven architectures—enabling automated code reviews and refactoring assistance.

---

Where Query Patterns Are Defined

All supported patterns are declared in code_review_graph/tools/query.py within the _QUERY_PATTERNS constant (lines 26‑44). This constant serves as the single source of truth for valid query types. The public query_graph function validates incoming requests against this list at lines 57‑64, rejecting unsupported patterns with an error message listing the allowed options.

---

Complete List of CRG Graph Query Patterns

The CRG supports these 15 relationship query patterns, organized by category:

Call and Reference Relationships

• callers_of — Find every function or method that calls a specified target. Use this to identify dependencies on a critical function before refactoring.

• callees_of — Find every function or method that the target calls. This reveals the implementation details and external dependencies of a function.

• references_to — Locate every node that references a symbol (variable, class, constant). This catches usages beyond direct function calls.

Import and Module Relationships

• imports_of — List all imports from the target file or module. Shows what a file depends on.

• importers_of — List all files that import the target file or module. Reveals the blast radius of changing a shared module.

Containment and Structure

• children_of — Return all contained nodes (classes, functions, nested definitions) inside a file or class. Useful for understanding file organization.

• file_summary — Produce a summary of all nodes defined in a given file, providing a complete inventory of symbols.

Test Coverage

• tests_for — Retrieve the unit tests for a given function or class, including indirect test coverage. Critical for pre-commit validation workflows.

Object-Oriented Relationships

• inheritors_of — Find all classes that inherit from a given base class. Essential when modifying base class behavior.

Event-Driven and Messaging Patterns

• publishers_of — Find methods that publish a specific event or message type.

• listeners_of — Find methods that handle (listen to) a specific event or message type.

• handlers_of — Find methods that handle a particular endpoint (HTTP route or similar entry point).

• endpoints_for — Find endpoints that are handled by a given method (inverse of handlers_of).

Scheduled and Triggered Execution

• triggers_of — Show methods invoked by a scheduler, cron job, or trigger mechanism.

• triggered_by — Show schedulers or triggers that invoke a given method.

Configuration and Dependency Injection

• consumers_of — Locate code that consumes a Spring-style configuration property or similar configuration value.

---

Using the query_graph API

Invoke any pattern through the query_graph function with a consistent interface. All examples below assume:

from code_review_graph.tools.query import query_graph

Example 1: Find Callers of a Function

result = query_graph(
    pattern="callers_of",
    target="utils.validate",
    detail_level="minimal",
)
print(result["summary"])

This returns all functions calling utils.validate, with minimal detail for quick scanning.

Example 2: Retrieve Test Coverage

result = query_graph(
    pattern="tests_for",
    target="UserService",
    max_results=20,
)
for test in result["results"]:
    print(f"Test: {test['qualified_name']} (indirect={test['indirect']})")

The indirect flag indicates tests that cover the target through intermediate calls rather than direct invocation.

Example 3: Map Module Dependencies

result = query_graph(
    pattern="importers_of",
    target="shared/constants.py",
)
print(result["summary"])

This identifies all files depending on shared/constants.py, helping assess change impact.

Common Parameters

Parameter	Purpose
pattern	One of the 15 supported strings from _QUERY_PATTERNS
target	Function name, qualified name, or file path to query against
detail_level	"minimal", "standard", or "full"—controls result verbosity
max_results	Integer limit for result set size
repo_root	Optional override for repository root path

---

Implementation Architecture

The query system relies on several interconnected components:

• code_review_graph/tools/query.py — Core implementation housing _QUERY_PATTERNS and the query_graph entry point.

• code_review_graph/graph.py — GraphStore class providing low-level graph storage operations and traversal primitives.

• code_review_graph/tools/_common.py — Shared utilities including built-in call filters reused across query implementations.

• code_review_graph/tools/semantic_search_nodes.py — Complementary semantic search tool often combined with graph queries for hybrid exploration.

This architecture separates pattern definitions from storage mechanics, allowing new relationship types to be added by extending _QUERY_PATTERNS and implementing corresponding traversal logic.

---

Summary

• 15 query patterns are defined in code_review_graph/tools/query.py lines 26‑44 as the _QUERY_PATTERNS constant.

• Pattern validation occurs at lines 57‑64, ensuring only supported queries execute.

• Core patterns cover: call relationships (callers_of, callees_of), references, imports, containment, tests, inheritance, events (publishers_of, listeners_of), endpoints, scheduled triggers, and configuration consumers.

• Consistent API: All patterns use query_graph(pattern=..., target=...) with optional detail_level, max_results, and repo_root parameters.

• Key files: query.py (patterns and API), graph.py (storage), _common.py (utilities), semantic_search_nodes.py (semantic search companion).

---

Frequently Asked Questions

What happens if I use an unsupported query pattern?

The query_graph function validates the pattern parameter against _QUERY_PATTERNS at lines 57‑64. If you supply an unsupported string, it returns an error message listing all 15 allowed patterns. This prevents silent failures and makes debugging straightforward.

Can I combine multiple query patterns in a single call?

No—query_graph processes one pattern per invocation. For complex analysis, chain multiple calls or use the underlying GraphStore directly from code_review_graph/graph.py. The modular design encourages composing simple queries rather than attempting multi-pattern expressions.

How does tests_for identify indirect test coverage?

The pattern traverses call graphs from test entry points, marking a test as indirect: true when it reaches the target through intermediate functions rather than direct invocation. This captures integration-level coverage without requiring explicit test-to-target annotations in source code.

Are these patterns language-specific or framework-specific?

Several patterns target specific paradigms: consumers_of assumes Spring-style configuration properties, while publishers_of/listeners_of fit event-driven architectures. However, core patterns like callers_of, references_to, and imports_of work across languages. The CRG implementation in tirth8205/code-review-graph currently focuses on Python and Java—the pattern applicability depends on the language parser used during graph construction.

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