fork-meter

A command-line tool that measures cyclomatic complexity by counting decision points and branching paths in source code.

Requirements

• Python >=3.14

Installation

pip install fork-meter

Supported Languages

Language	Grammar
Python	tree-sitter-python
JavaScript	tree-sitter-javascript
TypeScript	tree-sitter-typescript
Java	tree-sitter-java
Go	tree-sitter-go
Gosu	tree-sitter-gosu
C	tree-sitter-c
C++	tree-sitter-cpp
C#	tree-sitter-c-sharp
Rust	tree-sitter-rust
Kotlin	tree-sitter-kotlin
Scala	tree-sitter-scala

Usage

fork-meter [OPTIONS] PATHS...

PATHS may be files or directories; directories are scanned recursively.

Options

Option	Default	Description
--max INT	10	Report functions with complexity strictly above this value
--output NAME	fork-meter-output	Base name for output files (no extension)
--output-dir DIR	<cwd>/reports	Directory for output files
--format [json|html|both]	both	Output format
--exclude PATTERN	—	Glob pattern to exclude from scanning (repeatable)
--target-list	false	Treat PATHS as a single existing file listing target paths (files and/or directories), one per line, instead of separate arguments
-V, --version		Show version and exit
-h, --help		Show help and exit

Example

# Scan a project, flag anything above complexity 5, write HTML only
fork-meter src/ --max 5 --format html --exclude "**/*_test.py"

Target List

Use --target-list to scan targets listed in a file instead of passing them as separate arguments. PATHS must then be a single existing file, one target per line; blank lines and lines starting with # are skipped.

# targets.txt:
#   src/
#   lib/utils.py
fork-meter targets.txt --target-list

While scanning, a live progress indicator shows how many files have been checked:

fork-meter checking files ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 42/120 0:00:03

Once done, it is replaced by the final summary:

fork-meter done in 0.08s
  ✓ reports/fork-meter-output.html

fork-meter exits with status code 1 if any function exceeds --max complexity, and 0 otherwise.

Complexity Scale

Range	Colour	Risk
1 – 5	🟢 Green	Low
6 – 10	🟡 Yellow	Moderate
11 – 15	🟠 Orange	High
16 +	🔴 Red	Critical

Output Formats

• HTML — self-contained interactive report with a sortable complexity table.
• JSON — machine-readable report suitable for CI integration.

Configuration

fork-meter bootstraps its log/config directory automatically, including a default fm_ignore file (gitignore-style patterns) used to skip matching files during a scan. Override the location with:

export FORK_METER_CONFIG_DIR=/path/to/dir

A config.ini file is also bootstrapped into that directory. Its [override] section lets you rename the ignore file fork-meter reads, in case you want to reuse an existing gitignore-style file under a different name:

[override]
ignore-file = fm_ignore

If the configured file is missing, fork-meter logs a warning and falls back to the bundled fm_ignore file.

Development

Setup

poetry install

Format and Lint

poetry run black fork_meter; poetry run pylint fork_meter

Run Tests with Coverage

poetry run pytest --cov=fork_meter tests --cov-report html

Changelog

License

This project is licensed under the MIT License — see the LICENSE file for details.