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

> Explore 15 CRG graph query patterns like callers_of, references_to, and tests_for. Analyze code reviews efficiently with built-in relationship queries via the query_graph API.

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

---

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

```python
from code_review_graph.tools.query import query_graph

```

### Example 1: Find Callers of a Function

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

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

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

```

This identifies all files depending on [`shared/constants.py`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/query.py)** — Core implementation housing `_QUERY_PATTERNS` and the `query_graph` entry point.

- **[`code_review_graph/graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/graph.py)** — `GraphStore` class providing low-level graph storage operations and traversal primitives.

- **[`code_review_graph/tools/_common.py`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/query.py) (patterns and API), [`graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/graph.py) (storage), [`_common.py`](https://github.com/tirth8205/code-review-graph/blob/main/_common.py) (utilities), [`semantic_search_nodes.py`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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.