Cognitive complexity per function in Gaze + GazeCRAP-CC variant (Group 6)

[jflowers]

Summary

Add cognitive complexity measurement to Gaze by porting the Sonar cognitive complexity algorithm to Go AST analysis, and introduce a GazeCRAP-CC variant that incorporates cognitive complexity.

RFC: https://github.com/orgs/unbound-force/discussions/483 — Group 6
Phase: 3 (Depth)

Context

Cyclomatic complexity (used in CRAP scores) measures the number of linearly independent paths. Cognitive complexity (Sonar's algorithm) measures how hard code is to understand — penalizing nesting, recursion, and breaks in linear flow. Both are valuable; cognitive complexity better captures the human/agent comprehension burden.

Implementation

Cognitive Complexity Algorithm (Sonar Specification)

Port the SonarSource cognitive complexity specification to Go AST:

• Increments: if, else if, else, switch, for, &&, ||, goto, sequences of logical operators, recursion
• Nesting penalty: +1 for each level of nesting on incremented structures
• No increment: case labels, single ternary-like patterns

GazeCRAP-CC Variant

• Combine cognitive complexity with test coverage to produce an alternative CRAP-like score
• Formula: GazeCRAP-CC = CC^2 * (1 - coverage)^3 + CC (mirrors CRAP but uses cognitive complexity)
• Reported alongside existing CRAP score, not replacing it

CI Gate Flag

gaze analyze ./... --max-cognitive-complexity=15

Acceptance Criteria

• Cognitive complexity computed per function via Go AST
• Algorithm matches Sonar specification (nesting penalties, increment rules)
• GazeCRAP-CC variant computed and reported alongside CRAP
• --max-cognitive-complexity=15 CI gate flag
• JSON output includes cognitive_complexity and gaze_crap_cc per function
• Enforces AD-001 from the convention pack
• Tests with functions of known cognitive complexity

Dependencies

• Supports: Agent-design convention pack AD-001 (Group 3)
• Related: CRAP delta reporting (Group 2c)
• Repo: gaze