> ## Documentation Index
> Fetch the complete documentation index at: https://mehen.ophi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Developers

> Build mehen, run the test suite, and contribute changes.

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.
* For ANTLR grammar regeneration (Kotlin, Java): a Java runtime, an `antlr-4.13.2-complete.jar`, and
  the `antlr4-rust-gen` generator (`cargo install antlr-rust-runtime`). Only needed to *regenerate*
  parsers — a normal build uses the checked-in modules and needs none of these.

## Clone

```bash theme={null}
# 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 theme={null}
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 theme={null}
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 theme={null}
    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 theme={null}
    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-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).