Analyze code complexity metrics (cyclomatic, cognitive, function length, coupling). Use when identifying refactoring targets, tracking codebase health, or reviewing large changes.
Instrucciones de origen · Vista previa de solo lectura
name
code-complexity
description
Analyze code complexity metrics (cyclomatic, cognitive, function length, coupling). Use when identifying refactoring targets, tracking codebase health, or reviewing large changes.
$1: Path to analyze (defaults to current directory)
--threshold: Complexity threshold for flagging (default: 10)
--format: Output format — summary (default), detailed, json
Metric Computation: Offload, Never Count By Hand
Complexity metrics (cyclomatic complexity, NLOC, parameter count, function
length, nesting depth) are computed by a tool, never by eyeballing function
boundaries or counting branches by hand. Hand-counting is token-hungry,
irreproducible run-to-run, and exactly the mechanical work that belongs in a
deterministic substrate.
Language-native fast paths (use when the project already has them
configured): radon for Python, cargo clippy for Rust, the ESLint
complexity rule for JS/TS when an ESLint config exists.
lizard — the uniform fallback for every language. One tool computes
cyclomatic complexity (CCN), NLOC, parameter count (PARAM), function length,
and nesting depth (ND) across JS/TS/Go/Python/Rust/C/C++/Java with
machine-readable output. It is the deterministic answer wherever a
language-native tool is absent — always the JS/TS and Go path when ESLint
complexity isn't configured.
Install lizard (tool-installation priority)
uv tool install lizard
Alternative: mise use -g pipx:lizard (mise pipx: backend, runs via uvx).
Execution
Execute this complexity analysis:
Step 1: Detect project language and available tools
Check for language-specific complexity tools, falling back to lizard:
JavaScript/TypeScript: use the ESLint complexity rule when an ESLint
config is present; otherwise use lizard.
Python: use radon (cyclomatic + maintainability index); lizard is a
fallback if radon is unavailable.
Rust: use cargo clippy cognitive-complexity warnings; lizard is a
fallback.
Go: use lizard.
Any other language / no native tool: use lizard.
Confirm lizard is installed (uv tool install lizard) before using the
fallback path.
Step 2: Measure function-level complexity
JavaScript/TypeScript (ESLint complexity rule, when configured):
JavaScript/TypeScript, Go, or any language without a native tool (lizard):
# Warnings only — one line per function exceeding the CCN threshold
lizard -C 10 --warnings_only .
# Full machine-readable metrics for every function (CSV)
lizard --csv .
lizard emits, per function: NLOC, CCN (cyclomatic complexity), token count,
PARAM (parameter count), length, and ND (nesting depth) — the complete metric
set, so no branch counting or line counting is done by hand. Restrict to a
language when needed with -l js, -l typescript, -l go, etc. The
--warnings_only run exits non-zero when any function exceeds the threshold.
radon cc ${1:-.} -s -a --min B
radon mi ${1:-.} -s
Rust:
cargo clippy -- -W clippy::cognitive_complexity
Step 3: Identify hotspots
Rank files and functions by complexity. Flag items exceeding the threshold:
Metric
Green
Yellow
Red
Cyclomatic complexity
1-5
6-10
11+
Cognitive complexity
1-8
9-15
16+
Function length (lines)
1-25
26-50
51+
Nesting depth
1-3
4
5+
Parameters per function
1-3
4-5
6+
Step 4: Calculate file-level metrics
For each source file:
Total functions/methods
Average complexity per function
Maximum complexity function
Lines of code vs lines of logic
Import/dependency count (coupling indicator)
The lizard default (non-CSV) run already prints per-file NLOC, average NLOC,
average CCN, average token count, and function count — use it for the file-level
roll-up.
Step 5: Report results
Complexity Report
=================
Files analyzed: N
Functions analyzed: N
Average complexity: X.X
Hotspots (complexity > threshold):
File | Function | CC | Lines | Depth
src/auth/handler.ts | validateToken | 15 | 82 | 6
src/api/router.ts | handleRequest | 12 | 64 | 5
Distribution:
Low (1-5): NN% of functions
Medium (6-10): NN% of functions
High (11+): NN% of functions
Recommendations:
1. [file:function] Extract nested conditions into helper functions
2. [file:function] Split into smaller focused functions
3. [file:function] Replace switch with strategy pattern
Post-Actions
If many high-complexity functions → suggest /code:refactor for the worst offenders
If complexity tools not installed → suggest uv tool install lizard (uniform, all languages) or pip install radon (Python)
If setting up complexity budgets → suggest adding ESLint complexity rule via /configure:linting
