Introduction

mehen is a fast, deterministic command-line tool that measures source code, SQL, and Markdown documentation across a repository. It tracks complexity, maintainability, size, and documentation health, and is purpose-built for CI runs, pre-PR hooks, and pull request automation.

mehen metrics src/main.py --pretty
mehen metrics migrations/0007_add_orders.sql --pretty
mehen top-offenders src --metric cognitive
mehen diff --from main --to HEAD --paths src --output-format markdown

Installation

Install via npm, PyPI, or cargo binstall from a single GitHub Release.

Quickstart

Analyze a file, rank a tree, and diff a PR in under a minute.

GitHub Action

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

Code metrics

Cyclomatic, cognitive, Halstead, MI, ABC, LOC family, NOM/NPA/NPM/WMC.

Markdown metrics

DMI, MRPC, MCC, Halstead-md, link debt, filler/lazy risk, prose layer.

SQL metrics

CTE graphs, join/subquery structure, object-touch risk, SQL Halstead, composite scores.

What is Mehen?

Mehen is a mythical ancient Egyptian serpent associated with guarding Ra. In the same spirit, the mehen CLI helps guard your codebase and documentation from collapsing under hidden complexity.

Why teams use mehen

Polyglot by design

Per-file language detection across eleven source languages plus Markdown and SQL — built for monorepos.

Real parsers, not regex

Each language uses the best available parser: Ruff for Python, Oxc for TS/JS/JSX/TSX, Mago for PHP, Prism for Ruby, ra_ap_syntax for Rust, ANTLR for Kotlin and Java, sqruff for SQL, pulldown-cmark for Markdown, tree-sitter for Go, C, PowerShell.

SQL as a first-class language

A dedicated SQL analyzer scores CTE graphs, join structure, object-touch risk, and review burden — dataflow complexity that imperative-only tools cannot see. See SQL metrics.

Deterministic, no network

Pure static analysis. Same input → same output. Safe for air-gapped CI.

Code, SQL, and documentation

A single tool covers source-code complexity, SQL structure, and Markdown documentation health.

Pull-request native

Built-in mehen diff plus a sticky comment GitHub Action — no glue code required.

Many output formats

Console, JSON, YAML, TOML, GitHub-flavored Markdown.

First-class SQL analysis

SQL is where mehen does something most metric tools do not. Commercial code-quality platforms routinely treat .sql files as opaque text — or charge for a SQL add-on that still only counts lines — because their models are built around imperative control flow. A declarative SELECT with ten joins and five CTEs has almost no branches, so a cyclomatic-only tool reports it as “simple” while reviewers know it is anything but. mehen ships a dedicated mehen-sql analyzer (backed by the dialect-aware sqruff parser) that measures the complexity mechanism SQL actually has — relational and dataflow structure:

CTE dependency graphs — depth, fan-out, recursion, and unused CTEs.
Join and subquery structure — outer/cross/non-equi joins, correlated subqueries, missing join conditions.
Object-touch and change risk — DROP, TRUNCATE, UPDATE/DELETE without a WHERE, and other migration-script hazards.
SQL Halstead and six explainable composite scores, including a file-level review-burden index and change-risk score.

Dialect is inferred from syntax with a reported confidence (or pinned with a -- sqlfluff:dialect:… directive) across postgres, T-SQL, snowflake, bigquery, and more. SQL files are picked up automatically — including on pull requests, where the GitHub Action surfaces SQL deltas in the same sticky comment as your source-code metrics.

What mehen computes

For source code:

Cyclomatic complexity and Cognitive complexity
Halstead metrics (volume, difficulty, effort, estimated bugs)
Maintainability Index (Original, Visual Studio, SEI variants)
ABC (Assignments / Branches / Conditions)
NOM, NARGS, NEXITS, NPA, NPM, WMC
LOC family — SLOC, PLOC, LLOC, CLOC, blanks

For Markdown documentation:

Documentation Maintainability Index (DMI)
Markdown Reading Path Complexity (MRPC)
Markdown Cognitive Complexity (MCC)
Markdown Halstead
Link Debt, Table Burden, Visual Scaffold, Artifact Debt
Repository Grounding, Evidence Coverage
Filler / Lazy Structure Risk, Review Criticality Index
An opt-in English readability ensemble and Japanese script composition prose layer.

For SQL:

Structural and cognitive complexity derived from CTE, join, subquery, CASE, and window structure.
Review Burden Index and Change Risk Score — file-level 0–100 ranks for PR effort and migration risk.
SQL Maintainability Index, modularity health, and an SQL Halstead family.

Get started

Install mehen

Pick the path that matches your toolchain:

npm
PyPI
cargo binstall

npm install -g mehen

uv tool install mehen
# or: pip install mehen

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

Analyze a file

mehen metrics src/main.py --pretty

Add the GitHub Action

Publish per-PR metric trends with a few lines of YAML. See the GitHub Action guide.