lizard-complexity

lizard-complexity

Lizard analyzes source code per function for NLOC (non-comment LoC), CCN (cyclomatic complexity), token count, and parameter count across 30+ languages including C/C++, Java, Python, JavaScript, Go, Rust, TypeScript, Swift, Kotlin (per the Lizard README). Default CCN warning threshold is 15.

When to use

• Polyglot codebase where per-language linters give inconsistent complexity metrics.
• Adding a CCN ceiling to CI without buying a commercial scanner.
• One-off audit of "where is the most complex code?" before a refactor.

Step 1 - Install

pip install lizard

Or run the standalone script:

python lizard.py path/to/code

Per the Lizard README, no external deps required.

Step 2 - Baseline scan

lizard src/

Default output groups by file with per-function NLOC/CCN/token/param counts. Default warning threshold: CCN ≥ 15.

Step 3 - Set production-only thresholds

lizard src/ \
  -x"./tests/*" \
  -x"./vendor/*" \
  -C 10 \
  -L 100 \
  -a 5

Flag	Meaning
-x PATTERN	Exclude (must include tests/** for production-only scope)
-C N	CCN warning threshold (default 15; tighten to 10 for new codebases)
-L N	Max function NLOC (default 1000; tighten to 80 - 100)
-a N	Max parameter count (5 = "if you need more, pass an object")

Step 4 - CSV/XML for CI

# CSV for grep / jq pipelines
lizard src/ -x"./tests/*" -C 10 --csv > lizard.csv

# XML for CI parsers (cppncss-style)
lizard src/ -x"./tests/*" -C 10 -X > lizard.xml

# HTML for human review
lizard src/ -x"./tests/*" -C 10 -H > lizard.html

Step 5 - Fail CI on warnings

lizard src/ -x"./tests/*" -C 10 -L 100 -a 5 -w
EXIT=$?
if [ "$EXIT" -ne 0 ]; then
  echo "Complexity threshold breached. See report."
  exit 1
fi

-w prints warnings only (clang/gcc style). Lizard exits non-zero when any function exceeds the configured threshold.

Step 6 - Per-language scope

# Only Python
lizard src/ -l python -C 10

# Only TypeScript + JS
lizard src/ -l typescript -l javascript -C 10

Useful when a polyglot repo has language-specific budgets (e.g., Python tolerates higher CCN than C).

Anti-patterns

Anti-pattern	Why it fails	Fix
Run on whole repo including tests	Test setup helpers ("create user with 12 fields") look complex; tests get refactored away from clarity	Always exclude tests/, spec/ (Step 3)
Set CCN threshold to default (15)	Too lax for new code	Start at 10 for new code; track existing code as baseline
Block PRs on absolute count	Legacy code can't add a single line	Diff-only: scan PR-changed functions only with git diff --name-only filter
Refactor for CCN at expense of clarity	Splitting a clear linear function into 4 helpers raises overall complexity	Use CCN as a smell signal, not a hard rule
Skip parameter-count guard	"God functions" with 12 args slip through	-a 5 enforces object-arg style

Limitations

• Lizard's CCN counts decision points (if/else/case/&&/||/?:); doesn't reflect cognitive complexity (nesting depth weight). Use SonarQube / qa-code-quality/sonarqube-quality-perspective for cognitive complexity if needed.
• No per-class metrics for OO code beyond per-method.

References

• Lizard README - CLI reference, language list, threshold flags