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.
mehen top-offenders walks one or more paths, computes head-only metrics, and emits a deterministic
sorted list of the worst-offending files. It is the right tool for repository health dashboards,
prioritization reports, and “where do we spend time?” planning.
mehen top-offenders [OPTIONS] --metric <METRICS> <PATHS>...
| Argument | Description |
|---|
<PATHS>... | One or more files or directories to analyze. |
| Flag | Default | Description |
|---|
-M, --metric <METRICS> | required | Metric to rank by. Repeatable — first is primary key, next breaks ties, etc. Prefix with + for higher-is-better or - for lower-is-better. |
--max-results <N> | 10 | Maximum number of offenders to return. |
-O, --output-format <FMT> | markdown | markdown or json. |
-I, --include <GLOB> | — | Glob to include files. Repeatable. |
-X, --exclude <GLOB> | — | Glob to exclude files. Repeatable. |
-j, --num-jobs <N> | platform default | Number of parser jobs. |
-l, --language-type <LANG> | auto | Language type override (skip auto-detection). |
Known metric names
cyclomatic, cognitive, nom.functions, loc.lloc, mi.original, mi.sei, mi.visual_studio,
halstead.volume, abc, plus the full Markdown family from
Markdown metrics.
Polarity
Each metric has a default direction. mehen knows that higher cognitive complexity is worse, higher
maintainability index is better, etc. Override with the prefix:
--metric +mi.visual_studio — rank highest MI first (best at top).--metric -cognitive — rank highest cognitive first (worst at top).--metric cognitive — same as -cognitive because cognitive’s default polarity is “lower is better”.
Examples
Worst by cognitive
Multi-key sort
Filter to one tree
Markdown docs only
mehen top-offenders src --metric cognitive --max-results 20
mehen top-offenders crates \
--metric cognitive --metric loc.lloc --metric halstead.volume
mehen top-offenders . \
--include 'crates/**' --exclude '**/tests/**' \
--metric cognitive --output-format json
mehen top-offenders docs \
--include '**/*.md' --include '**/*.mdx' \
--metric md.filler_lazy_risk --metric md.dmi
Determinism
The output ordering is fully deterministic: same paths, same metrics, same head ref → byte-identical
report. Tie-breaking falls back to the next --metric, then to the repository-relative path. There is
no sampling and no file-system-order dependence.
Exit codes
| Code | Meaning |
|---|
| 0 | Success. |
| 1 | IO, parser-fatal, or unsupported-language error. |
See also
