An extensible CLI for measuring code complexity and detecting repeated code fragments.
Designed to be language-agnostic with low overhead.
This document outlines:
- Goals and metrics
- Algorithms used
- Outputs
- Philosophy
- Provide actionable complexity and duplication insights without heavy parsing.
- Support any programming language.
- Keep runtime fast: linear or near-linear where possible.
- Keep architecture modular so deeper analysis can be plugged in later.
- Produce both human-readable and machine-readable reports.
The MVP focuses on high-signal, low-complexity algorithms that require only tokenization—not full AST parsing. This keeps the implementation small and performance excellent.
Measures independent control-flow paths in a function.
Works by building a simple CFG (control-flow graph) from tokens or indentation.
Formula:
CC = E - N + 2P
Where:
E= number of edgesN= number of nodesP= number of connected components, usually1
Purpose:
- Flags overly complex functions.
- Well understood by developers.
Detects repeated token sequences across files.
- Uses a rolling hash window, for example 20–50 tokens.
- Language-agnostic and extremely fast.
Purpose:
- Quickly identifies copy/paste blocks and boilerplate.
Counts physical, logical, comment, and blank lines.
- Token-based classification for accuracy.
- Supports ranking by any metric: logical, physical, comments, or blank.
- Can aggregate and rank by directory.
- Required for future Maintainability Index calculations.
Purpose:
- Provides a baseline size metric.
- Identifies largest files and directories.
- Tracks codebase growth and comment density.
Reads LCOV files and reports line coverage.
- Terminal summaries with uncovered line ranges.
- Detailed file and directory views.
- Optional JSONL and static HTML output.
Purpose:
- Surfaces untested lines in CI output.
- Produces shareable coverage artifacts.
See todo.md.
See DEVELOPMENT.md for workspace structure, common commands, and coverage setup with cargo-llvm-cov.
analyze: Full analysis: complexity, clones, and LOCclones: Detect code clones onlycomplexity: Analyze cyclomatic complexity and LOCloc: Focused LOC analysis with ranking by file or directorydump-config: Display or save current configurationcoverage report: Summarize LCOV coverage datacoverage show: Show detailed file or directory coverage
Common flags:
--json--threshold--min-tokens--rank-by--rank-dirs--config--no-gitignore
FILE: src/server/routes.rs
Cyclomatic Complexity: 14
Physical LOC: 128
Logical LOC: 96
FILE: src/server/auth.rs
Cyclomatic Complexity: 5
Physical LOC: 41
Logical LOC: 30
CLONES:
- HashMatch #7
- src/server/routes.rs:41-78
- src/server/router.rs:12-49
Length: 32 tokens
{
"files": [
{
"path": "src/server/routes.rs",
"loc": {
"physical": 128,
"logical": 96,
"comments": 12,
"blank": 20
},
"cyclomatic": {
"file_complexity": 14,
"functions": []
}
}
],
"clones": [
{
"id": 7,
"length": 32,
"locations": [
{ "file": "src/server/routes.rs", "start": 41, "end": 78 },
{ "file": "src/server/router.rs", "start": 12, "end": 49 }
]
}
]
}- Zero language assumptions in the MVP.
- Pluggable architecture: token → AST → CFG → semantic.
- High performance by default.
- No global state; everything streamed and incremental.
- Developer-friendly reporting and clear severity levels.
- Configurable thresholds.
- https://www.literateprogramming.com/mccabe.pdf
- https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication500-235.pdf