---
title: "Developers"
description: "Build mehen, run the test suite, and contribute changes."
keywords: ["mehen development", "rust", "contributing"]
---

This section documents how to build mehen, run its tests, and contribute changes.

## Prerequisites

- A recent stable Rust toolchain. See [rust-lang.org/tools/install](https://www.rust-lang.org/tools/install).
- For tree-sitter grammar regeneration (Go / C / PowerShell): a Linux or macOS shell, or
  Windows via WSL.
- ANTLR grammar regeneration (Kotlin, Java, C#) needs no separately installed generator:
  xtask links the workspace-pinned `antlr-rust-codegen` crate directly. Keep that exact pin in
  lockstep with `antlr-rust-runtime`; a normal build still uses the checked-in modules.
- For the C# grammar specifically, also [`uv`](https://docs.astral.sh/uv/): the Roslyn grammar is
  transformed by `crates/mehen-csharp-parser/grammar/prepare-grammar.py`, run as a step of
  generation via its PEP 723 inline metadata.

## Clone

```bash
# HTTPS
git clone -j8 https://github.com/ophi-dev/mehen.git

# SSH
git clone -j8 git@github.com:ophi-dev/mehen.git
```

## Build and lint

From the repo root:

```bash
cargo check
cargo build
cargo fmt --all
cargo clippy --all-targets --all-features --locked
```

## Testing

mehen uses `nextest` when available, falling back to `cargo test`:

```bash
if cargo nextest --version >/dev/null 2>&1; then
  cargo nextest run --all-features
else
  cargo test --all-targets --locked
fi
```

## Snapshot tests (`insta`)

Many metric tests use `insta` snapshots. Always pass `--workspace` to avoid false `unreferenced`
failures.

<Tabs>
  <Tab title="CI-style check">
    ```bash
    cargo insta test --workspace --all-features --check --unreferenced reject \
        --test-runner nextest --no-test-runner-fallback --disable-nextest-doctest
    ```
  </Tab>
  <Tab title="Update intentionally">
    ```bash
    cargo insta test --workspace --all-features --review \
        --test-runner nextest --no-test-runner-fallback --disable-nextest-doctest
    ```
  </Tab>
</Tabs>

## Repository layout

| Crate | Purpose |
|---|---|
| `crates/mehen-cli` | CLI binary — entry point, command routing, exit codes. |
| `crates/mehen-engine` | Pipeline orchestration — `run_diff`, `run_top_offenders`, registry. |
| `crates/mehen-core` | Parser-neutral domain types and the `LanguageAnalyzer` trait. |
| `crates/mehen-metrics` | Shared metric formulas, accumulators, finalizers. |
| `crates/mehen-python` | Python analyzer (Ruff). |
| `crates/mehen-typescript` | TypeScript / JavaScript / TSX / JSX analyzer (Oxc). |
| `crates/mehen-php` | PHP analyzer (Mago). |
| `crates/mehen-ruby` | Ruby analyzer (Prism). |
| `crates/mehen-rust` | Rust analyzer (`ra_ap_syntax`). |
| `crates/mehen-kotlin` | Kotlin analyzer (ANTLR — official Kotlin spec grammar). |
| `crates/mehen-java` | Java analyzer (ANTLR — grammars-v4 Java grammar). |
| `crates/mehen-csharp` | C# analyzer (ANTLR — Roslyn's own generated grammar). |
| `crates/mehen-sql` | SQL analyzer (sqruff) — publishes the dedicated `sql.*` metric family. |
| `crates/mehen-go`, `mehen-c`, `mehen-powershell` | Tree-sitter-backed analyzers. |
| `crates/mehen-markdown` | Markdown analyzer (pulldown-cmark) with embedded-code dispatch via `LanguageDispatcher`. |
| `crates/mehen-tree-sitter` | Shared tree-sitter wrapper and CST traversal helpers. |
| `crates/mehen-antlr` | Shared ANTLR-runtime support (span conversion, diagnostics, comment LOC) for ANTLR-backed analyzers. |
| `crates/mehen-git` | Git operations. |
| `crates/mehen-report` | JSON, YAML, TOML, and GitHub-Markdown rendering. |
| `xtask` | Developer-only commands (kind-enum codegen, AST dumps, audits). |

## Coding expectations

- Keep internals internal (`pub(crate)` / private) unless a real external API is needed.
- Prefer explicit imports over wildcard re-exports.
- Avoid dead code — this is a CLI-focused codebase.
- Preserve deterministic metric behavior across platforms.

## Pages

- [How-to: Add a new language](/developers/new-language)
- [How-to: Implement LoC](/developers/loc)
- [How-to: Update grammars](/developers/update-grammars)

## Contributing

Issues and pull requests welcome at [github.com/ophi-dev/mehen](https://github.com/ophi-dev/mehen).
