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

You can extend code-review-graph with new programming languages by placing a languages.toml file inside the .code-review-graph/ directory at your repository root, defining [languages.<name>] tables that map file extensions to custom tree-sitter grammars and optional aliases.

The code-review-graph analyzer supports user-defined language extensions without requiring modifications to the core library. By creating a structured TOML configuration, you instruct the engine to recognize additional file types and parse them using specified grammar definitions. This guide demonstrates the exact schema, file placement, and validation steps based on the implementation in code_review_graph/custom_languages.py and the test suite in tests/test_custom_languages.py.

Configuration File Location

The engine searches for .code-review-graph/languages.toml relative to the repository root. If present, the load_custom_languages() function in code_review_graph/custom_languages.py reads and validates this file during the initialization phase.

mkdir -p .code-review-graph
touch .code-review-graph/languages.toml

The languages.toml Schema

Each custom language is defined under a [languages.<name>] table, where <name> is the unique identifier for the language.

Required Fields

• grammar: A string path (relative to repository root) pointing to the compiled tree-sitter grammar file (Wasm) or parser module.
• extensions: A list of file extension strings without the leading dot (e.g., ["foo", "fool"]).

Optional Fields

• aliases: A list of alternative language names used when resolving import statements or language identifiers.
• probe_fields: A list of attribute names that the engine checks during heuristic symbol detection (e.g., ["service", "endpoint"]).

A complete example registering a fictional FooLang looks like this:

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

Loading Custom Languages Programmatically

While the CLI automatically detects the configuration file when running code-review-graph analyze, you can also load definitions manually using the Python API. The load_custom_languages() function accepts a Path object pointing to the repository root and returns a dictionary mapping language names to configuration objects.

from pathlib import Path
from code_review_graph.custom_languages import load_custom_languages

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

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

Validating Your Configuration

The test suite in tests/test_custom_languages.py demonstrates how the engine validates TOML syntax and required fields. Missing keys or malformed paths raise descriptive errors preventing analysis with an inconsistent setup. You can verify your configuration by running the project's test suite or by invoking the loader directly in a Python shell as shown above.

Summary

• Place languages.toml inside the .code-review-graph/ directory at your repository root.
• Define each language under [languages.<name>] with required grammar and extensions fields.
• Add optional aliases and probe_fields to improve symbol resolution heuristics.
• The load_custom_languages() function in code_review_graph/custom_languages.py handles parsing and validation.
• Reference tests/test_custom_languages.py for examples of valid and invalid configurations.

Frequently Asked Questions

Where exactly should I put the languages.toml file?

Create the file at .code-review-graph/languages.toml relative to your repository root. The load_custom_languages() function specifically looks for this path when initializing the analyzer.

What format should the grammar field use?

The grammar field must contain a relative path string pointing to a compiled tree-sitter grammar (typically a .wasm file) or a custom parser module that the engine can load. Path separators should match your operating system or use forward slashes for cross-platform compatibility.

Can I define multiple custom languages in a single file?

Yes. The TOML format supports multiple [languages.<name>] tables within the same file. Each table defines a distinct language with its own grammar, extensions, and optional aliases.

How does the tool handle configuration errors?

If languages.toml is missing required fields, contains invalid syntax, or references non-existent grammar files, the load_custom_languages() function raises a validation error immediately upon loading. This prevents the analysis pipeline from executing with incomplete language definitions.

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