Cognitive Heatmap

Real-time color overlay showing cognitive complexity per function — like a thermal camera for code quality.

The Problem

You know a file is "too complex" but you can't tell which part to refactor. Complexity metrics live in reports and CI dashboards — far from where you're actually writing code. By the time you see a SonarQube report, you've moved on.

What It Does

Cognitive Heatmap renders a live color overlay directly on your editor showing cognitive complexity per function. Green = simple. Yellow = getting complex. Red = too complex. The overlay updates as you type.

Features

• Live color overlay — real-time background tinting per function block
• Four complexity bands — low (green), medium (yellow), high (red), critical (deep red)
• Status bar — shows the most complex function in the current file
• Complexity report — open a detailed panel listing all functions sorted by score
• Keyboard shortcut — Cmd+Shift+H to toggle the heatmap
• Configurable thresholds — adjust what counts as low/medium/high for your team
• Debounced refresh — re-calculates after you stop typing (configurable ms)

Getting Started

The heatmap activates automatically when you open a TypeScript or JavaScript file. Color overlays appear on functions based on their complexity score.

• Toggle on/off: Press Cmd+Shift+H or run Cognitive Heatmap: Toggle Overlay
• See the report: Run Cognitive Heatmap: Show Complexity Report

Commands

Color Bands

Configuration

Stricter thresholds (for high-quality codebases)

{
  "cognitiveHeatmap.thresholds": {
    "low": 3,
    "medium": 7,
    "high": 15
  }
}

What Contributes to Complexity

The score increments for each:

Example:

// Score: ~1 (just one if)
function isAdult(age: number) {
  if (age >= 18) { return true; }
  return false;
}

// Score: ~8 (nested ifs + loops + logical operators)
function processOrder(order: Order) {
  if (order && order.items) {           // +1 (if) +1 (&&)
    for (const item of order.items) {  // +1 (for) +1 nesting
      if (item.stock > 0) {            // +1 (if) +2 nesting
        if (item.price || item.sale) { // +1 (if) +1 (||) +3 nesting
          // ...
        }
      }
    }
  }
}

Tips

• Functions scoring over 20 should almost always be split into smaller functions
• Use the Complexity Report (sorted descending) to prioritize what to refactor
• Reducing nesting (early returns, guard clauses) is the fastest way to lower scores
• Keep the heatmap visible while refactoring — watch the color change as you simplify