analyze_complexity

What Complexity Actually Means

Most “complexity” measurements count branches. An if statement adds 1. A switch adds N. This tells you almost nothing about how hard a function is to understand. A function with ten flat if statements is straightforward. A function with three if statements nested four levels deep is a nightmare.

analyze_complexity uses cognitive complexity scoring, which weights nesting depth exponentially. A branch at the top level costs 1. The same branch nested inside a loop inside a conditional costs significantly more. This matches how developers actually experience code difficulty.

The 97% Token Reduction

The native approach to finding complex functions is to grep for control flow keywords (if, for, while, switch, try) across every file, then pipe through wc -l or awk to count occurrences, then manually sort. This produces thousands of lines of raw match output — every control flow keyword in every file, with no ranking, no scoring, and no distinction between flat branches and deeply nested ones.

That raw output consumes approximately 25,100 tokens. analyze_complexity returns a clean ranked list of the top N functions with their scores, file locations, and line numbers in about 660 tokens. The 97% reduction is not compression of the same information. It is the elimination of information that was never useful in the first place.

What the Output Contains

Each entry in the ranked list includes:

• Function name and location — file path and line number
• Cognitive complexity score — the weighted nesting score
• Function length — lines of code
• Nesting depth — maximum nesting level reached

The list is sorted by complexity score descending. The top 10 (or whatever top_n you specify) are the functions most likely to contain bugs, resist testing, and slow down new developers.

When to Use It

analyze_complexity is a refactoring prioritization tool. Use it when:

• You are starting a refactoring effort and need to decide what to split first. The highest-scoring functions are the best candidates for extraction.
• You want to establish a complexity budget for a module. Run it periodically and track whether the top scores are going up or down.
• A code review flags a function as “too complex” and you want to quantify the claim.
• You are onboarding to a codebase and want to know which files will require the most effort to understand.

Do not run it routinely on every task. It reads every function in the index, which is unnecessary when you are working on a specific feature. Save it for deliberate quality assessment.

Pairing With Other Analysis Tools

analyze_complexity identifies the most complex functions. analyze_hotspots cross-references complexity with git churn to find functions that are both complex and frequently changed — the highest-risk code. find_dead_code identifies complex functions that are not even used, making them safe deletion candidates rather than refactoring targets.

The three tools together give you a complete picture: what is complex, what is complex and actively changing, and what is complex but dead.