Code Quality Scanner: AST-Based Complexity and Upgrade Friction

The Code Quality Scanner performs fast, AST-based quality checks — measuring cyclomatic complexity and identifying upgrade-friction hotspots. It runs as part of a normal scan and contributes to your DriftScore. This article is for developers who want a content-aware view of where complexity will slow an upgrade.

What it detects

• Cyclomatic complexity — a measure of how many independent paths run through your code, computed from the abstract syntax tree (AST).
• Upgrade-friction hotspots — places where complexity, combined with what the code does, predicts a hard time during migrations.

Because it parses the code into an AST, this scanner sees structure that a metadata-only pass cannot, while staying fast enough for routine scans.

Why it matters

High cyclomatic complexity is strongly associated with bugs and with the difficulty of changing code safely. When you upgrade a framework or language version, the most complex functions are where behavior shifts in subtle ways and where tests are hardest to write. A content-aware hotspot is more actionable than a size-based one: it points at the specific functions that will resist change, not just the largest files.

For leaders, complexity is a quantifiable proxy for maintenance cost. For developers, it is a prioritized list of refactor targets that pay off at upgrade time.

How to act

Scan the project:

vg

Review the highest-complexity findings and consider decomposing those functions, adding tests, or simplifying control flow before you take on a major upgrade. Lowering complexity in the riskiest spots reduces the blast radius of future changes.

Capture progress with a baseline so improvements are tracked and regressions gated:

vg baseline

Triage tips

• Refactor the top few complexity hotspots before a major migration, not all at once.
• Add characterization tests to complex functions you cannot simplify yet.
• Combine with File Hotspots for a quick-then-deep prioritization.

Related

This scanner complements the File Hotspots Scanner (metadata-only) and the Breaking Change Exposure Scanner. To see what a complex node calls and what calls it, use Vibgrate Graph via vg show and vg tree.