Metadata-Version: 2.4
Name: mehen
Version: 0.7.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
License-File: LICENSE
License-File: LICENSE-THIRD-PARTY
Summary: Tool to compute and export code metrics
Keywords: metrics,code-analysis,complexity,cyclomatic,halstead
Author-email: Konstantin Vyatkin <tino@vtkn.io>
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/ophidiarium/mehen#readme
Project-URL: Homepage, https://github.com/ophidiarium/mehen
Project-URL: Issues, https://github.com/ophidiarium/mehen/issues
Project-URL: Repository, https://github.com/ophidiarium/mehen

# mehen

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

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

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

Most common usage patterns we see:

- CI jobs that compute metrics for changed files and publish trend reports
- Pre-PR / pre-CR hooks that provide immediate quality feedback
- Automation workflows that enrich pull request templates with a glance view of metric deltas

## Current Language Support

Today `mehen` supports:

- Python
- TypeScript / JavaScript (`.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`)
- TSX / JSX (`.tsx`, `.jsx`)
- Rust
- Go
- Ruby
- Kotlin
- PowerShell
- C (`.c`, `.h`)
- Markdown (`.md`, `.markdown`, `.mdown`, `.mkd`, `.mkdn`, `.mdx`) — documentation metrics only

Because TypeScript is a superset of JavaScript, `mehen` analyzes `.js`/`.mjs`/`.cjs`
files through the TypeScript grammar and `.jsx` files through the TSX grammar.

Markdown files receive a dedicated documentation metric suite (maintainability,
reading path complexity, link debt, filler/lazy risk, readability) rather than
the code-style metrics — Markdown has no functions, classes, or interfaces to
score. See the [Markdown metric chapter](mehen-book/src/metrics/markdown.md).

We also providing comprehensive support for polyglot monorepos, with per-file language detection and reporting.

## What Mehen Computes

`mehen` provides a broad metric set for source code, including:

- Cyclomatic complexity
- Cognitive complexity
- Maintainability Index
- Halstead metrics
- ABC metrics
- NArgs / NOM / NExit
- LOC family (SLOC, PLOC, LLOC, CLOC, blanks)
- NPA / NPM / WMC

### Markdown documentation metrics

For Markdown (README, ADRs, runbooks, API references, tutorials, generated
docs), `mehen` ships a dedicated metric suite that treats code fences,
diagrams, tables, images, links, math, and repository references as
first-class document constructs instead of stripping them before counting
words. The structural layer covers a Markdown LOC family (prose vs. code
vs. tables vs. math vs. blank lines), Markdown Reading Path Complexity, a
Markdown Cognitive Complexity analogue, Markdown Halstead, a Documentation
Maintainability Index (DMI), link debt, table burden, visual scaffold,
repository grounding, evidence coverage, filler/lazy structure risk, and a
review criticality index. An opt-in language-aware prose layer adds
English readability (Flesch, Flesch-Kincaid, Fog, SMOG, ARI, Coleman-Liau,
Dale-Chall, FORCAST, LIX/RIX), lexical diversity (MATTR, hapax, density),
wording quality (passive, hedges, weasels, wordy, adverbs, nominalizations,
cliches, illusions), inclusive-language flags, Japanese script composition,
the Tateishi simplified readability score, a Jōyō-grade proxy, JTF
rule conformance, and a textlint-ja subset. Full reference in the
[Markdown metric chapter](mehen-book/src/metrics/markdown.md) of the book.

## Distribution

`mehen` ships native binaries through both ecosystems:

- npm (`mehen` + platform packages)
- PyPI (`mehen` via maturin binary packaging)

## Quick Start

### Run without installation

From npm ecosystem:

```bash
bunx mehen --help
```

From Python/uv ecosystem:

```bash
uv tool run mehen --help
# or
uvx mehen --help
```

### Run locally from source

```bash
cargo run -- --help
```

### Typical examples

Analyze metrics for a directory:

```bash
mehen -m -p src
```

Export metrics as JSON/TOML/YAML/CBOR:

```bash
mehen -m -p src -O json -o ./metrics
```

## GitHub Actions

Use the in-repository action to publish changed-file metric trends on pull
requests:

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

steps:
  - uses: actions/checkout@v6
    with:
      fetch-depth: 0

  - uses: ophidiarium/mehen@v0
    with:
      paths: src
```

For polyglot monorepos, pass each root you want tracked. `mehen` will analyze
only supported languages in changed files under those roots:

```yaml
- uses: ophidiarium/mehen@v0
  with:
    paths: |
      crates/api/src
      apps/web/src
      tools
    thresholds: |
      cyclomatic=5
      cognitive=4
      loc.lloc=120
```

Thresholds are optional. When configured, the action fails if an adverse
per-file metric delta exceeds the configured limit.

When enabled and a PR touches one or more Markdown files, `mehen diff`
will also emit a Documentation Metrics section inside the same sticky
comment, anchored by `<!-- mehen-docs -->`. Once fully wired, it will
report DMI, word count, FKGL / Tateishi RS, link debt, and filler risk
per file, plus a template-driven callout list for objective defects
(broken links, new inclusive-language flags, long sentences, heading
skips, unlabelled code fences, etc.). The full specification — anchor
rules, cell format, callout template catalog, planned `--fail-on`
gating — is in
[`commands/pr-comment.md`](mehen-book/src/commands/pr-comment.md). Until
the Markdown renderer emits the anchor and the callout catalog is
wired end-to-end, the GitHub Action only publishes the source-code
metrics section.

## Reporting and Integrations

Current machine-readable outputs:

- JSON
- YAML
- TOML
- CBOR

Roadmap direction:

- Native git integration for changed-file detection
- Rich markdown reports for AI/human review flows
- More polished console reporting for local developer loops

## Implementation Notes

Internally, `mehen` is built on:

- [tree-sitter](https://tree-sitter.github.io/tree-sitter/) for parsing
- The excellent foundational work from Mozilla's [rust-code-analysis](https://github.com/mozilla/rust-code-analysis)

`mehen` continues in its own CLI-focused direction while preserving and evolving that foundation.

## Development

Build and check:

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

Tests:

```bash
cargo test --all-targets --locked
```

Snapshot tests (`insta`):

```bash
cargo insta test --all-features --check --unreferenced reject --test-runner nextest --no-test-runner-fallback --disable-nextest-doctest
```

See `mehen-book/src/developers/` for developer docs, including language and grammar updates.

## Contributing

Contributions are welcome via issues and pull requests:

- https://github.com/ophidiarium/mehen/issues

## License

`mehen` is released under the [Mozilla Public License v2.0](https://www.mozilla.org/MPL/2.0/).

