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

You can extend code-review-graph with new languages by creating a .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 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:

[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:

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:

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:

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 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 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, 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 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. 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 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 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 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 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.

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