mehen

mehen is a Rust-powered CLI for detecting heuristic source code metrics at scale: complexity, maintainability, lines of code, documentation health, and more.

It is designed for fast, deterministic analysis over large codebases, helping both human and AI engineers track how complexity evolves over time.

📚 Documentation: https://mehen.ophi.dev

What is Mehen?

In Ophidiarium projects, names matter. Mehen is a mythical ancient Egyptian serpent associated with guarding Ra. In the same spirit, mehen helps guard your codebase from slowly collapsing under complexity.

Why teams use mehen

• Polyglot by design — per-file language detection across eleven source languages plus Markdown and SQL. Useful for monorepos.
• Real language parsers — Ruff for Python, Oxc for TS/JS/JSX/TSX, Mago for PHP, Prism for Ruby, ra_ap_syntax for Rust, ANTLR (Kotlin spec grammar for Kotlin, grammars-v4 for Java and C#), pulldown-cmark for Markdown, sqruff for SQL, tree-sitter for Go, C, PowerShell.
• Code, documentation, and SQL in one tool — source-code complexity, Markdown documentation health, and a dedicated relational metric family for .sql files.
• Bring-your-own coverage — ingests LCOV, Cobertura, JaCoCo, Clover, Istanbul, and Go coverprofile reports, auto-discovers them in their idiomatic (usually gitignored) locations, and publishes coverage.* as a rankable, gateable metric family down to per-function values.
• Deterministic, no network — pure static analysis. Same input → same output. Safe for air-gapped CI.
• Pull-request native — built-in mehen diff plus a sticky comment GitHub Action.

Install

# npm
npm install -g mehen

# PyPI / uv
uv tool install mehen
# or: pip install mehen

# cargo binstall
cargo binstall --git https://github.com/ophi-dev/mehen mehen

Full installation guide: https://mehen.ophi.dev/installation.

Quick start

# Analyze a single file
mehen metrics src/main.py --pretty

# Rank the worst offenders in a tree
mehen top-offenders src --metric cognitive

# Diff metrics against main
mehen diff --from main --to HEAD --paths src --output-format markdown

Quickstart: https://mehen.ophi.dev/quickstart.

Configuration

Drop a mehen.toml (or .mehen.toml) anywhere between the directory you run mehen from and the git repository root — discovery walks upward and stops at the repository boundary — or pin an explicit file with --config <PATH>:

[thresholds]
cognitive = 15         # higher-is-worse metrics: the limit is a maximum
"loc.lloc" = 500
mi.visual_studio = 40  # higher-is-better metrics (mi.*): the limit is a minimum

[languages.python.thresholds]
cognitive = 10         # overrides the global limit for Python files only

Every command that reports a configured metric enforces it: mehen metrics checks the full metric set of the analyzed file, while mehen diff (head side) and mehen top-offenders check the metrics selected for output — across all analyzed files, not just the displayed rows. Any crossed limit prints a grouped report on stderr and fails the command with exit code 1:

  × 2 metric threshold violations (config: /repo/mehen.toml)
  │
  │ src/app/core.py
  │   cognitive = 23 — exceeds max 10  (set by languages.python.thresholds)
  │   loc.lloc = 640 — exceeds max 500  (set by thresholds)
  help: adjust or remove the limit at the configuration path shown, or bring the file back within it.

Configuration mistakes fail fast with a caret into the TOML source and a suggestion ("unknown metric cognitve … did you mean cognitive?"): every metric name is validated against the keys the analyzers actually publish — including the sql.* and markdown.* namespaces — so a typo can never silently disable a gate. Full reference: https://mehen.ophi.dev/configuration.

GitHub Action

Drop the action into a workflow to publish per-PR metric trends:

permissions:
  contents: read
  pull-requests: write
  issues: write

steps:
  - uses: actions/checkout@v6
    with:
      fetch-depth: 0
  - uses: ophi-dev/mehen@v1
    with:
      paths: src

Full reference: https://mehen.ophi.dev/guides/github-action.

Documentation

Everything else lives in the docs site:

• Code metrics — cyclomatic, cognitive, Halstead, MI, ABC, LOC family, NOM, NPA, NPM, WMC.
• Markdown metrics — DMI, MRPC, MCC, link debt, filler/lazy risk, English/Japanese prose layer.
• SQL metrics — CTE graphs, join/subquery structure, object-touch risk, SQL Halstead, and composite scores via mehen-sql (sqruff-backed).
• Coverage metrics — ingest test-coverage reports (six formats, auto-discovered), gate on line/branch/function coverage, rank the least-tested files.
• Commands — mehen metrics, mehen diff, mehen top-offenders.
• Configuration — mehen.toml thresholds and per-language overrides.
• Developers guide — build, test, contribute, add a language.

Contributing

Issues and pull requests welcome at https://github.com/ophi-dev/mehen/issues.

License

mehen is released under the GNU Affero General Public License v3.0.