Skip to content
WeCodingNowPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

cyclo

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.

Install

cargo install --path crates/cli

Or build in place and use target/release/cyclo:

cargo build --release

Usage

cyclo 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 output

Text 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

Options

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.

JSON

{
  "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.

What counts

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, each match arm after the first, a match guard, &&, ||, and ?. A bare loop and a plain else add nothing.
  • Python: if, elif, for, while, each except, a if c else b, each for and if in a comprehension, each case after the first, a case guard, and, or, and assert. else, finally, and with add 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.

Repository layout

  • crates/core is the cyclo-core library: parsing, counting, and the report model. The rules for each language are tree-sitter query files under crates/core/queries/.
  • crates/cli is the cyclo binary.
  • tests/fixtures/<language>/ holds sample sources in which every definition is annotated with its expected score; the test in crates/core/tests/fixtures.rs checks 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.

Development

cargo test            # runs the fixture harness
cargo clippy --all-targets
cargo run -- --explain tests/fixtures/rust/basics.rs

To 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).

License

MIT

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages