# How to Configure Custom Language Support in code-review-graph Using languages.toml

> Easily add custom language support to code-review-graph. Learn to configure new languages using languages.toml by specifying grammar paths, file extensions, and aliases.

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

---

**You can extend code-review-graph with new languages by creating a [`.code-review-graph/languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/.code-review-graph/languages.toml) file in your repository root and defining `[languages.<name>]` sections that specify the grammar path, file extensions, and optional aliases.**

The `code-review-graph` engine analyzes repository structure and dependencies across multiple programming languages. When you need to parse languages not included in the default distribution, you can configure custom language support in code-review-graph using languages.toml without modifying the core source code. This declarative approach allows the parser to treat your custom definitions as first-class participants for syntax parsing, symbol resolution, and call-graph building.

## Configuration File Location and Discovery

The loader expects the configuration file at a specific path relative to the repository root. During initialization, the engine searches for [`.code-review-graph/languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/.code-review-graph/languages.toml) and automatically ingests any valid definitions found there.

- The file must reside inside the hidden directory `.code-review-graph/` at the repository root.
- If the file is missing or empty, the analyzer proceeds with only the built-in language set.
- Relative paths declared inside the TOML file are resolved against the repository root.

## The languages.toml Schema

Each language definition lives under a TOML table header formatted as `[languages.<name>]`. The schema requires specific keys to bind file extensions to parsing logic.

**Required fields:**

- **`grammar`** – A string path (relative to repo root) pointing to a compiled Tree-sitter grammar WASM file or a custom parser module capable of parsing the language.
- **`extensions`** – An array of file-extension strings (without the leading dot) that should trigger this parser.

**Optional fields:**

- **`aliases`** – An array of alternative language identifiers that may appear in import statements or shebang lines.
- **`probe_fields`** – An array of attribute names the engine uses when heuristically probing for callees or symbols not explicitly covered by the grammar.

A valid entry for a fictional language looks like this:

```toml
[languages.foolang]
grammar = "grammars/foolang/tree-sitter-foolang.wasm"
extensions = ["foo", "fool"]
aliases = ["fl"]
probe_fields = ["module", "handler"]

```

## Step-by-Step Configuration Examples

### Adding a Custom DSL

Create the configuration directory and file, then define your language:

```bash
mkdir -p .code-review-graph
cat > .code-review-graph/languages.toml <<'EOF'
[languages.mydsl]
grammar = "grammars/mydsl/tree-sitter-mydsl.wasm"
extensions = ["mydsl", "mdl"]
aliases = ["mydsl_lang"]
probe_fields = ["service", "endpoint"]
EOF

```

When analysis runs, any file ending in `.mydsl` or `.mdl` is parsed using the specified WASM grammar, and the engine recognizes `mydsl_lang` as a valid alias in import graphs.

### Running Analysis via CLI

With the TOML file in place, invoke the analyzer from the repository root. The tool automatically detects and loads the custom definitions:

```bash
code-review-graph analyze .

```

The parser pipeline ingests the configuration before scanning source files, ensuring your custom language is included in the final call graph.

### Programmatic Access

You can inspect loaded configurations programmatically using the `load_custom_languages` function from [`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py):

```python
from pathlib import Path
from code_review_graph.custom_languages import load_custom_languages

repo_root = Path(".")
languages = load_custom_languages(repo_root)

for name, config in languages.items():
    print(f"{name}: grammar={config.grammar}, extensions={config.extensions}")

```

This returns a mapping of language names to configuration objects, allowing you to verify that your [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) was parsed correctly before analysis begins.

## Validation and Error Handling

The configuration is strictly validated on load to prevent inconsistent analysis states. 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) performs the following checks:

- **Presence of required keys** – Missing `grammar` or `extensions` fields raise a clear configuration error.
- **Path existence** – The system verifies that the grammar path resolves to an actual file.
- **Duplicate detection** – Duplicate language names within the same file are rejected immediately.
- **Type checking** – Fields like `extensions` must be arrays of strings; malformed types trigger validation failures.

If any check fails, the engine raises an exception before parsing begins, preventing partial or incorrect language registrations from corrupting the analysis results.

## Implementation Details

The core logic resides in [`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py), which implements the `load_custom_languages` function. This module reads the TOML file, validates the schema, and injects the custom definitions into the parser pipeline. The test suite in [`tests/test_custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/tests/test_custom_languages.py) verifies end-to-end handling, including error cases for malformed configurations and successful integration of custom grammars into the symbol resolution engine.

When the analyzer starts, it constructs a merged language registry that combines built-in parsers with user-defined entries from [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml). The `probe_fields` option is particularly useful when the standard Tree-sitter grammar does not explicitly tag certain call patterns, allowing the heuristic resolver to examine specific attribute names for dependency edges.

## Summary

- Place a [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) file inside the `.code-review-graph/` directory at your repository root to define custom languages.
- Each language requires a `[languages.<name>]` table with `grammar` and `extensions` keys; optional `aliases` and `probe_fields` refine parsing behavior.
- The `load_custom_languages` function in [`code_review_graph/custom_languages.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/custom_languages.py) parses and validates the configuration on startup.
- Validation occurs before analysis begins, rejecting missing files, duplicate names, or malformed paths to ensure data integrity.
- Custom languages participate fully in call-graph construction and symbol resolution once configured.

## Frequently Asked Questions

### Where must I place the languages.toml file?

The file must be located at [`.code-review-graph/languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/.code-review-graph/languages.toml) relative to the repository root. The engine specifically searches this hidden directory during initialization; placing the file elsewhere will result in the custom language being ignored.

### What format should the grammar path use?

The `grammar` field should contain a relative path from the repository root to a compiled Tree-sitter WASM grammar or a compatible parser module. For example, `grammars/python/tree-sitter-python.wasm` resolves to `./grammars/python/tree-sitter-python.wasm` inside your repo.

### Can I define multiple custom languages in one file?

Yes. You can declare multiple `[languages.<name>]` tables within a single [`languages.toml`](https://github.com/tirth8205/code-review-graph/blob/main/languages.toml) file. Each table must have a unique name, and the engine loads all valid definitions into the analysis pipeline simultaneously.

### How does the engine validate my configuration?

The `load_custom_languages` function validates the TOML structure immediately upon loading. It checks for required keys, ensures the grammar file exists, prevents duplicate language names, and verifies that `extensions` is an array of strings. Any violation raises a descriptive error before source-code parsing begins.