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

# Introduction

> mehen is a Rust-powered CLI for heuristic source code metrics — complexity, maintainability, lines of code, documentation health — at scale.

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

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

<Columns cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Install via npm, PyPI, or `cargo binstall` from a single GitHub Release.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Analyze a file, rank a tree, and diff a PR in under a minute.
  </Card>

  <Card title="GitHub Action" icon="github" href="/guides/github-action">
    Drop the action into a workflow to publish per-PR metric trends.
  </Card>

  <Card title="Code metrics" icon="ruler" href="/metrics/code/overview">
    Cyclomatic, cognitive, Halstead, MI, ABC, LOC family, NOM/NPA/NPM/WMC.
  </Card>

  <Card title="Markdown metrics" icon="book-open" href="/metrics/markdown/overview">
    DMI, MRPC, MCC, Halstead-md, link debt, filler/lazy risk, prose layer.
  </Card>

  <Card title="SQL metrics" icon="database" href="/metrics/sql/overview">
    CTE graphs, join/subquery structure, object-touch risk, SQL Halstead, composite scores.
  </Card>
</Columns>

## 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

<Columns cols={2}>
  <Card title="Polyglot by design" icon="layer-group">
    Per-file language detection across eleven source languages plus Markdown and SQL — built for monorepos.
  </Card>

  <Card title="Real parsers, not regex" icon="microchip">
    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.
  </Card>

  <Card title="SQL as a first-class language" icon="database">
    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](/metrics/sql/overview).
  </Card>

  <Card title="Deterministic, no network" icon="lock">
    Pure static analysis. Same input → same output. Safe for air-gapped CI.
  </Card>

  <Card title="Code, SQL, and documentation" icon="files">
    A single tool covers source-code complexity, SQL structure, *and* Markdown documentation health.
  </Card>

  <Card title="Pull-request native" icon="git-pull-request">
    Built-in `mehen diff` plus a sticky comment GitHub Action — no glue code required.
  </Card>

  <Card title="Many output formats" icon="file-export">
    Console, JSON, YAML, TOML, GitHub-flavored Markdown.
  </Card>
</Columns>

## 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](/metrics/sql/overview) (backed by the dialect-aware
[sqruff](https://github.com/quarylabs/sqruff) parser) that measures the complexity mechanism SQL
actually has — **relational and dataflow structure**:

* **[CTE dependency graphs](/metrics/sql/overview)** — depth, fan-out, recursion, and unused CTEs.
* **[Join and subquery structure](/metrics/sql/overview)** — outer/cross/non-equi joins, correlated
  subqueries, missing join conditions.
* **[Object-touch and change risk](/metrics/sql/overview)** — `DROP`, `TRUNCATE`, `UPDATE`/`DELETE`
  without a `WHERE`, and other migration-script hazards.
* **[SQL Halstead](/metrics/sql/overview)** 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](/guides/github-action) surfaces
SQL deltas in the same sticky comment as your source-code metrics.

## What mehen computes

For source code:

* **[Cyclomatic complexity](/metrics/code/cyclomatic)** and **[Cognitive complexity](/metrics/code/cognitive)**
* **[Halstead metrics](/metrics/code/halstead)** (volume, difficulty, effort, estimated bugs)
* **[Maintainability Index](/metrics/code/mi)** (Original, Visual Studio, SEI variants)
* **[ABC](/metrics/code/abc)** (Assignments / Branches / Conditions)
* **[NOM](/metrics/code/nom)**, **[NARGS](/metrics/code/nargs)**, **[NEXITS](/metrics/code/nexits)**, **[NPA](/metrics/code/npa)**, **[NPM](/metrics/code/npm)**, **[WMC](/metrics/code/wmc)**
* **[LOC family](/metrics/code/loc)** — SLOC, PLOC, LLOC, CLOC, blanks

For Markdown documentation:

* **[Documentation Maintainability Index (DMI)](/metrics/markdown/dmi)**
* **[Markdown Reading Path Complexity (MRPC)](/metrics/markdown/mrpc)**
* **[Markdown Cognitive Complexity (MCC)](/metrics/markdown/mcc)**
* **[Markdown Halstead](/metrics/markdown/halstead)**
* **[Link Debt](/metrics/markdown/link-debt)**, **[Table Burden](/metrics/markdown/table-burden)**,
  **[Visual Scaffold](/metrics/markdown/visual-scaffold)**, **[Artifact Debt](/metrics/markdown/artifact-debt)**
* **[Repository Grounding](/metrics/markdown/repository-grounding)**, **[Evidence Coverage](/metrics/markdown/evidence-coverage)**
* **[Filler / Lazy Structure Risk](/metrics/markdown/filler-lazy-risk)**, **[Review Criticality Index](/metrics/markdown/review-criticality-index)**
* An opt-in [English readability ensemble](/metrics/markdown/prose/english-readability) and
  [Japanese script composition](/metrics/markdown/prose/japanese-script-composition) prose layer.

For SQL:

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

## Get started

<Steps>
  <Step title="Install mehen">
    Pick the path that matches your toolchain:

    <Tabs>
      <Tab title="npm">
        ```bash theme={null}
        npm install -g mehen
        ```
      </Tab>

      <Tab title="PyPI">
        ```bash theme={null}
        uv tool install mehen
        # or: pip install mehen
        ```
      </Tab>

      <Tab title="cargo binstall">
        ```bash theme={null}
        cargo binstall --git https://github.com/ophi-dev/mehen mehen
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Analyze a file">
    ```bash theme={null}
    mehen metrics src/main.py --pretty
    ```
  </Step>

  <Step title="Add the GitHub Action">
    Publish per-PR metric trends with a few lines of YAML.
    See the [GitHub Action guide](/guides/github-action).
  </Step>
</Steps>