MaarkssDN/Birthub-360 / .agents/skills/lizard-complexity
lizard-complexity
VerifiedUse when a multi-language codebase needs one complexity gate, or a function has grown unreviewable and CI needs a number. Runs Lizard (30+ languages) on production code to enforce per-function cyclomatic complexity, length and parameter-count thresholds, excluding tests.
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 /
sonarqube-maintainability-gatefor cognitive complexity if needed. - No per-class metrics for OO code beyond per-method.
References
- Lizard README - CLI reference, language list, threshold flags
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |