# How to Add Custom Language Support via languages.toml in Code-Review-Graph

> Add custom language support to Code-Review-Graph by creating a languages.toml file in your repository root. Easily register new Tree-sitter grammars without core library edits.

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

---

**Place a [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) file in the `.code-review-graph` directory at your repository root to register new Tree-sitter grammars without modifying the core library.**

The code-review-graph parser supports extensible language definitions through a declarative configuration file. By creating a [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) manifest in your project's `.code-review-graph` folder, you can teach the analyzer to recognize additional file extensions and node types using any Tree-sitter grammar. This approach keeps custom definitions project-local and avoids maintaining a fork of the tirth8205/code-review-graph repository.

## Configuration File Location and Discovery

The loader searches for a file named [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) inside a `.code-review-graph` directory at the repository root. As implemented in [[`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py)](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py#L47-L49), the path resolution follows standard project-root detection patterns. Place your configuration at the exact relative path [`.code-review-graph/languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/.code-review-graph/languages.toml) to ensure discovery.

## TOML Schema and Validation Rules

Each custom language definition requires a `[languages.<name>]` table containing specific AST node mappings. According to the validation logic in [[`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py)](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py#L53-L68), the schema requires these fields:

- **extensions**: Array of file extensions (each must match `^\.[a-z0-9_+-]{1,15}$`)
- **grammar**: Name of the Tree-sitter grammar package
- **function_node_types**: Array of AST node types representing function definitions
- **class_node_types**: Array of AST node types representing class definitions
- **import_node_types**: Array of AST node types representing import statements
- **call_node_types**: Array of AST node types representing function calls

The validator enforces strict constraints according to the code-review-graph source code:
- Language names must match `^[a-z][a-z0-9_-]{0,31}$` and be unique across the project
- Maximum of **20** custom languages per configuration file
- No collision with built-in language names or extensions
- Duplicate extensions are ignored (first definition wins)

## Loading and Caching Mechanism

When `CodeParser` initializes, it invokes `load_custom_languages()` to parse and validate the configuration. According to the implementation in [[`code_review_graph/parser.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/parser.py)](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/parser.py#L2101-L2104), the parser merges these definitions during instantiation. This process occurs automatically when you create a new parser instance with your repository root.

The caching layer stores parsed results keyed by file path, modification time, and size. As defined in [[`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py)](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py#L92-L98), this cache prevents redundant disk I/O during batch operations. If the [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) file changes, the cache invalidates automatically on the next parser initialization.

## Runtime Integration

Once loaded, custom languages receive identical treatment to built-in definitions throughout the analysis pipeline. The integration logic in [[`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py)](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py#L13081-L13085) ensures that custom definitions populate the internal language map. This enables standard analyses like function extraction, import detection, and call graph construction using your supplied node types.

## Practical Implementation Examples

Define your custom languages using static TOML syntax. The following examples demonstrate configurations for Erlang and a hypothetical experimental language.

Create a minimal configuration for Erlang support:

```toml

# .code-review-graph/languages.toml

[languages.erlang]
extensions = [".erl", ".hrl"]
grammar = "erlang"
function_node_types = ["function_clause"]
class_node_types = ["record_decl"]
import_node_types = ["import_attribute"]
call_node_types = ["call"]
comment = "Erlang via the bundled tree-sitter-erlang grammar"

```

Define a second custom language following the same pattern:

```toml
[languages.mylang]
extensions = [".myl"]
grammar = "mylang_grammar"
function_node_types = ["fn"]
class_node_types = ["class"]
import_node_types = ["import"]
call_node_types = ["call"]
comment = "My experimental language"

```

Initialize the parser in Python to load these definitions automatically:

```python
from pathlib import Path
from code_review_graph.parser import CodeParser

repo_root = Path.cwd()
parser = CodeParser(repo_root)  # Loads custom languages internally

```

Verify loading by running the CLI with verbose output:

```bash
code-review-graph -v build .

```

Look for diagnostic messages confirming the custom language count and any validation warnings.

## Summary

- Place [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) in `.code-review-graph/` at your repository root to enable discovery
- Define languages using `[languages.<name>]` tables with required AST node mappings for functions, classes, imports, and calls
- Respect validation constraints: lowercase names matching `^[a-z][a-z0-9_-]{0,31}$`, valid extensions, and maximum 20 entries
- The parser caches configurations based on file metadata to optimize performance across multiple runs
- Custom languages integrate seamlessly into the analysis pipeline without modifications to the core library

## Frequently Asked Questions

### What is the maximum number of custom languages I can define?

You can define up to **20** custom languages in a single [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) file. This limit prevents excessive memory usage during parser initialization. If you exceed this limit, the loader ignores additional entries and logs a warning to stderr.

### Can I override built-in language definitions?

No, custom language definitions cannot collide with built-in language names or file extensions. The validator in [[`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py)](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py) explicitly checks against the core language map and rejects any configuration attempting to redefine existing entries.

### How do I debug why my custom language isn't loading?

Run the build command with the verbose flag (`-v`) to see diagnostic messages during parser initialization. The loader outputs the number of custom languages detected and specific validation errors if your TOML violates the schema or naming conventions. Verify that your file resides at exactly [`.code-review-graph/languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/.code-review-graph/languages.toml) relative to the repository root.

### Does the configuration support environment variables or interpolation?

No, the [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) file uses static TOML only and does not support environment variable interpolation. All values must be literal strings and arrays as documented in [[`docs/CUSTOM_LANGUAGES.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/CUSTOM_LANGUAGES.md)](https://github.com/tirth8205/code-review-graph/blob/main/docs/CUSTOM_LANGUAGES.md). Dynamic resolution of grammar paths or environment-specific configuration is not supported by the current loader implementation.