# How to Perform Custom Graph Traversals with traverse_graph_tool

> Learn custom graph traversals with traverse_graph_tool CLI. Specify start nodes, depth limits, and JavaScript filters for powerful BFS control in your code reviews.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-08-13

---

**You can execute custom graph traversals using the `traversegraphtool` CLI by specifying start nodes, depth limits, and JavaScript filter expressions that control the breadth-first search algorithm.**

The `tirth8205/code-review-graph` repository provides a command-line interface for exploring code relationships through graph traversal. The `traverse_graph_tool` functionality allows developers to programmatically navigate the codebase graph, which maps files, symbols, imports, and test dependencies. This article explains how to leverage the traversal engine, customize exploration paths, and extract specific data from the graph database.

## Understanding the Graph Architecture

### The Core Graph Model

The traversal system relies on the `Graph` class implemented in [`src/webview/graph.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/webview/graph.ts). This class stores **nodes** representing files, functions, classes, and test suites, along with **edges** describing relationships such as imports, function calls, and test coverage. The graph structure enables efficient querying of dependency chains and call hierarchies across the entire codebase.

### Data Persistence Layer

Graph data persists in a local SQLite database managed by [`src/backend/sqlite.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/backend/sqlite.ts). Before running any traversal, the [`src/backend/watcher.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/backend/watcher.ts) module ensures the database reflects the current filesystem state by incrementally updating nodes and edges as files change. This synchronization guarantees that traversals operate on the most recent code analysis results.

## How traverse_graph_tool Works

### CLI Entry Point in src/backend/cli.ts

The `traversegraphtool` command is implemented in [`src/backend/cli.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/backend/cli.ts). This module parses command-line arguments, initializes the `Graph` object from the SQLite cache, and configures the traversal parameters. The CLI translates flags like `--start` and `--max-depth` into configuration objects passed to the underlying traversal engine.

### Breadth-First Search Implementation

The traversal engine executes a **breadth-first search (BFS)** beginning from the specified start node. The algorithm explores connected components layer by layer, respecting the `max-depth` constraint to prevent infinite recursion in cyclic dependency graphs. Each visited node is evaluated against user-defined predicates before being included in the output stream.

### Custom Filters and Callbacks

The tool supports three customization mechanisms defined in the CLI layer:

- **`--edge-filter`**: A JavaScript expression string evaluated against edge properties to determine which relationship types to follow (e.g., only `import` edges)
- **`--node-predicate`**: A condition tested against each visited node to filter results by properties like `kind` or `path`
- **`--on-node`**: A custom callback snippet executed for every visited node, enabling side effects such as counting nodes or extracting specific metadata

## Practical Code Examples

### Basic File-to-File Traversal

Start exploration from a specific TypeScript file and capture all reachable nodes within two hops:

```bash
traversegraphtool \
  --start "/src/app/controllers/userController.ts" \
  --max-depth 2 \
  --output visited.json

```

The command outputs a JSON array of node objects to [`visited.json`](https://github.com/tirth8205/code-review-graph/blob/main/visited.json), containing metadata for each discovered file, function, or symbol.

### Relationship-Based Filtering

Follow only import relationships until reaching function definitions:

```bash
traversegraphtool \
  --start "/src/lib/auth.ts" \
  --edge-filter "edge.type === 'import'" \
  --node-predicate "node.kind === 'function'" \
  --max-depth 5

```

This traversal ignores call edges and stops exploring branches once it encounters non-function nodes, optimizing the search for dependency analysis.

### Extracting Test Dependencies

Collect all test files that transitively depend on a specific service module using a custom callback:

```bash
traversegraphtool \
  --start "/src/services/paymentService.ts" \
  --on-node "if (node.kind === 'test') results.push(node.path)" \
  --output payment-tests.json

```

The `--on-node` script executes in the context of the traversal, appending paths to a results array that gets serialized to the output file.

## Summary

- **`traverse_graph_tool`** (exposed as the `traversegraphtool` CLI) performs breadth-first searches over the code analysis graph
- The graph model in [`src/webview/graph.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/webview/graph.ts) represents code entities as nodes and relationships as edges
- **Edge filters** and **node predicates** provide declarative control over traversal paths without modifying source code
- **Custom callbacks** enable arbitrary computation during graph walks for complex data extraction tasks
- The system uses SQLite for persistence via [`src/backend/sqlite.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/backend/sqlite.ts) and stays synchronized through [`src/backend/watcher.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/backend/watcher.ts)

## Frequently Asked Questions

### What output format does traverse_graph_tool generate?

The tool emits a **JSON stream** of visited node objects. By default, output goes to stdout, but you can redirect to a file using the `--output` flag. Each node object includes properties such as `id`, `path`, `kind`, and `metadata` describing the code entity.

### How do I limit the traversal to specific relationship types?

Use the `--edge-filter` option with a JavaScript boolean expression referencing the `edge` object. For example, `--edge-filter "edge.type === 'import'"` restricts the BFS to follow only import statements, ignoring function calls and inheritance relationships defined in [`src/webview/graph.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/webview/graph.ts).

### Can I traverse the graph from multiple starting points simultaneously?

While the CLI accepts a single `--start` argument, you can script multiple traversals or use the underlying API directly. Import the `Graph` class from [`src/webview/graph.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/webview/graph.ts) and the `traverse()` function from [`src/backend/cli.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/backend/cli.ts) in your Node.js script to execute batch traversals with multiple origins.

### How does the tool handle circular dependencies in the codebase?

The BFS implementation tracks visited nodes using a `Set` data structure to prevent infinite loops. When the traversal encounters a node already in the visited set, it skips that branch. The `--max-depth` parameter provides an additional safeguard against deeply cyclic structures.