snqb Uncomplex Analyzer
Detect complexity → understand intent → replace with libraries or simplify.
Quick Run
# Python
radon cc <file_or_dir> -s --min C
# JS/TS
bunx eslint <file_or_dir> --rule 'complexity: [error, 15]' --format json
Workflow
1. Detect (tools do the work)
Cyclomatic complexity:
# Python — install once: pip install radon
radon cc <directory> -s -j --min C | jq '.'
radon hal <file> # Halstead: effort > 500 = hard to read
# JS/TS
bunx eslint <directory> --rule 'complexity: [error, 15]' --format json
Circular dependencies:
# Python — install once: pip install pydeps
pydeps <directory> --no-output --show-cycles
# JS/TS
bunx madge --circular <directory>
Duplication:
bunx jscpd . --threshold 5 --reporters console --ignore "**/*.json,**/*.md,**/*.lock,**/node_modules/**"
Thresholds: CC 15+ = review. CC 20+ = strong replacement candidate. CC 25+ = split or replace.
2. Analyze Intent
For each complex function, answer: what is this trying to accomplish? (not how)
Then check if someone already solved it:
| Code Pattern | Intent | Python | JS/TS |
|---|---|---|---|
| Manual base64 + HMAC | JWT auth | pyjwt |
jose |
| Nested retry loops | Retry with backoff | tenacity |
p-retry |
| Date string parsing | Date manipulation | pendulum |
dayjs |
| Deep object merging | Object utilities | deepmerge |
lodash/merge |
| Manual HTML parsing | Web scraping | beautifulsoup4 |
cheerio |
| Regex-heavy validation | Schema validation | pydantic |
zod |
| Hand-rolled state machine | FSM / workflow | transitions |
xstate |
| Manual CSV/Excel parsing | Tabular data | pandas |
papaparse |
| Custom caching logic | Cache with TTL/LRU | cachetools |
lru-cache |
| Manual rate limiting | Rate limiter | ratelimit |
bottleneck |
| Hand-rolled queue | Task queue | celery, rq |
bull |
| Custom logging format | Structured logging | structlog |
pino |
| Subprocess orchestration | Task runner | invoke |
execa |
If the pattern isn't in this table, search:
~/.pi/agent/skills/github-quality-search/github_search.py \
"<intent keywords>" -l <language> -s 100 -n 3 --json
Quality gates: 100+ stars, MIT/Apache/BSD, commit in last 6 months, has docs.
3. Decide: Replace or Refactor?
Replace when the problem is generic (dates, HTTP, validation, parsing) and a quality library exists.
Refactor when logic is domain-specific or a library would be overkill. Keep it simple:
- God function → split into named helpers
- Nested closures → LibCST codemod to unnest + Rope to move (see python skill, Part 7)
- God module (1000+ lines) → Rope to move top-level symbols to separate modules
- Deep nesting → guard clauses + early returns
- Copy-paste → extract shared function
- 5+ params → config object
Leave alone when:
- Low churn (stable, not causing bugs)
- Domain complexity (the problem IS complex)
- Intentional — comments explain why, perf-critical path, no-dependency policy
4. Report
Create uncomplex-report-YYYYMMDD.md with:
- Summary stats (files scanned, high-complexity count)
- Each finding: location, complexity score, intent, recommendation (library or refactoring)
- Library replacements table (name, stars, license, migration effort)
- Top 3 priorities
Cross-References
- Prioritize targets:
hotspot-detective(high churn + high complexity = act first) - Clean up after:
dead-code-reaper - Library discovery:
github-quality-search
Combo: hotspot-detective → uncomplex-analyzer → dead-code-reaper
Dependencies
pip install radon pydeps # Python
# JS/TS: bunx eslint, bunx jscpd, bunx madge (zero-install)