54 lines
3.4 KiB
Markdown
54 lines
3.4 KiB
Markdown
# 10. Excessive complexity check
|
||
|
||
meta:
|
||
id: pygienium-10
|
||
feature: pygienium
|
||
priority: P2
|
||
depends_on: [pygienium-06]
|
||
tags: [check]
|
||
|
||
objective:
|
||
|
||
- Implement the excessive-complexity check: detect high cyclomatic complexity with concrete thresholds, plus unnecessarily fancy code, non-conventional patterns, and over-abstraction; refactor toward the simplest implementation that meets requirements.
|
||
|
||
deliverables:
|
||
|
||
- `src/checks/complexity.ts`: `CheckDefinition` with scan + fix tasks
|
||
- Cyclomatic complexity thresholds (MUST enforce, not advisory):
|
||
- **50+ → must refactor.** No exceptions. The function is too complex; break it up.
|
||
- **35–49 → heavy skepticism.** Only keep if this is a massively critical point along the main path and the complexity genuinely must be here. Otherwise refactor. The agent must justify, in findings.md, why a 35–49 function is kept (critical path + why it can't be simplified).
|
||
- **<35 → not flagged on cyclomatic grounds** (may still be flagged for other complexity smells like nesting/over-abstraction)
|
||
- Rubric: speculative abstractions, premature config indirection, non-idiomatic patterns, over-engineered generics, unnecessary wrappers; refactor to common conventions and the simplest correct form
|
||
- `/pygienium-complexity` runs E2E
|
||
|
||
steps:
|
||
|
||
- Author `buildScanTask`: agent identifies complexity hotspots:
|
||
1. **Cyclomatic complexity** — compute via a deterministic tool when available (e.g. `lizard`/`radon`/`gocyclo`/language-native), fall back to counting decision points (if/else if/for/while/case/&&/||/catch) per function. Classify each function into the 50+ / 35–49 / below-35 bands above. Write per-function scores to `pygienium/checks/complexity/findings.md` with line refs.
|
||
2. **Structural smells** — deep nesting (>3 levels), needless indirection, speculative abstractions — same findings.md, separate section.
|
||
- findings.md includes a proposed simpler form for every flagged function.
|
||
- Author `buildFixTask`: apply safe refactors (flatten nested conditionals, inline trivial wrappers, remove speculative config, split 50+ functions); for 35–49 functions, keep ONLY if the agent can justify critical-path necessity, else refactor. Flag risky refactors for review.
|
||
- Register the check
|
||
|
||
tests:
|
||
|
||
- Integration: temp file with a 55-decision-point function (must-refactor) + a 40-decision-point function (heavy-skepticism, must justify or refactor); run `--fix`; assert the 50+ is split, the 35–49 is either refactored or has a documented justification in changes.md
|
||
- Integration: temp file with a needlessly abstracted config layer + deep nesting; run `--fix`; assert simplified
|
||
|
||
acceptance_criteria:
|
||
|
||
- findings.md lists cyclomatic complexity scores per function banded as 50+/35-49/below-35
|
||
- Every 50+ function is refactored by `--fix` (no 50+ remains post-fix)
|
||
- Every kept 35–49 function has a documented justification (critical path + why-simpler-isn't-possible) in findings.md; unjustified ones are refactored
|
||
- findings.md lists structural complexity hotspots with proposed simplifications
|
||
- `--fix` applies safe refactors and preserves behavior (agent re-reads after edit)
|
||
|
||
validation:
|
||
|
||
- Inspect `pygienium/checks/complexity/{findings.md,changes.md}`
|
||
|
||
notes:
|
||
|
||
- Encode the engineering rules directly in the rubric: simplest implementation, no speculative abstractions, grow in layers
|
||
- The lens risk-hotspots (fan-in × complexity) and module_report complexity flags are signals to feed the agent
|