Cyclomatic complexity of functions in Rust and Python source code, as a command-line linter.
cyclo parses source with tree-sitter,
finds every function-like definition, and reports how many linearly
independent paths run through it: 1 + number of decision points. It reads
files, directory trees, or text piped on stdin. Because tree-sitter
recovers from syntax errors, a fragment pasted from the middle of a file
still produces scores for the definitions in it.
cargo install --path crates/cliOr build in place and use target/release/cyclo:
cargo build --releasecyclo src/ # walk a tree, honoring .gitignore
cyclo lib.rs app.py # specific files
cyclo --glob 'src/**/*.rs' . # restrict the walk
cyclo --exclude 'tests/**' . # or trim it
pbpaste | cyclo --lang python # stdin needs --lang
cyclo --explain src/parser.rs # show every counted decision point
cyclo --fail 10 src/ # exit 1 if anything scores above 10
cyclo --changed-since HEAD # only definitions touched by uncommitted changes
cyclo --format json src/ # machine-readable outputText output is one line per definition:
src/parser.rs:42: Parser::parse_expr cc=7 !
The ! marks scores above --warn (default 5). With --explain, each
decision point follows on its own line:
src/parser.rs:42: Parser::parse_expr cc=7 !
src/parser.rs:44: +1 if_expression
src/parser.rs:47: +1 match_arm
src/parser.rs:51: +1 &&
...
A definition whose text contains a syntax error is marked
(parse errors: lower bound): the decisions that did parse are counted,
anything inside the broken region is not.
With --changed-since, the diff only chooses which files and lines
matter. Each touched file is analyzed in full, so scores are exact, and a
definition is listed when its line range overlaps a changed range. This
is the mode for checking a patch without being told about complexity that
was already there:
cyclo --changed-since HEAD --only-above 7 # uncommitted work
cyclo --changed-since origin/main --fail 10 src/ # a branch, in CI| flag | meaning |
|---|---|
--lang rust|python |
language of the input; required for stdin, overrides extension detection for files |
--glob G, --exclude G |
include or exclude paths matching a glob, repeatable |
--changed-since REV |
report only definitions whose lines differ from git revision REV in the working tree, plus every definition in untracked files; paths become git pathspecs, none means the working directory |
--only-above N |
list only definitions scoring above N |
--warn N |
mark definitions above N in text output (default 5) |
--fail N |
exit with status 1 if any definition scores above N (off by default) |
--explain |
list every counted decision point under each definition |
--format text|json |
output format |
Exit status is 0 on success, 1 when --fail is set and exceeded, and 2 on
an error such as an unreadable file or an unknown language.
{
"schema_version": 1,
"files": [
{
"path": "src/parser.rs",
"language": "rust",
"items": [
{
"kind": "method",
"name": "Parser::parse_expr",
"line": 42,
"end_line": 80,
"complexity": 7,
"has_parse_errors": false,
"decisions": [{ "line": 44, "construct": "if_expression" }]
}
]
}
]
}path is null for stdin.
Every function-like definition starts at 1. Each of the following adds one:
- Rust:
if,else if,if let,let ... else,while,while let,for, eachmatcharm after the first, a match guard,&&,||, and?. A bareloopand a plainelseadd nothing. - Python:
if,elif,for,while, eachexcept,a if c else b, eachforandifin a comprehension, eachcaseafter the first, a case guard,and,or, andassert.else,finally, andwithadd nothing.
Decisions inside closures, lambdas, and inner functions count toward the
enclosing function as well. An inner named function is also reported on
its own, under a qualified name such as outer::inner. Methods are
reported as Type::method in Rust and Class::method in Python.
The full tables, worked examples, and the reasoning behind each choice
are in .spec/design/counting-rules.md.
Common thresholds: 10 is the widely used upper limit; under 5 indicates cohesive, well-factored code.
crates/coreis thecyclo-corelibrary: parsing, counting, and the report model. The rules for each language are tree-sitter query files undercrates/core/queries/.crates/cliis thecyclobinary.tests/fixtures/<language>/holds sample sources in which every definition is annotated with its expected score; the test incrates/core/tests/fixtures.rschecks them all..spec/design/holds the design documents.
See .spec/design/architecture.md for how
the pieces fit together and how to add a language.
cargo test # runs the fixture harness
cargo clippy --all-targets
cargo run -- --explain tests/fixtures/rust/basics.rsTo add or change a rule, edit the language's query file and add a function
to the matching fixture with a cc: N annotation on its closing line
(Rust) or on the line after its body (Python).
MIT