Complexity analyzer reference¶

The complexity analyzer measures three dimensions of code complexity from source code: cyclomatic complexity, cognitive complexity, and nesting depth, plus the lines of code of every function. It operates on the UAST representation of your source files and reads the file source alongside it (operators, identifiers and line counts are recovered from the source where a language mapping does not carry them).

For the conceptual model — what each metric means, the exact counting rules, and how the rules are validated — see Understanding complexity metrics. To run it, see the Quick start.

Configuration options¶

The complexity analyzer uses the UAST directly and has no analyzer-specific configuration options. Language support is determined by the UAST parser.

Run-level flags that affect it: --languages, --include-vendored, --include-generated (which files are walked) and --per-file (JSON only, see below).

Output formats¶

Functions are ordered the same way everywhere: cyclomatic descending, then cognitive descending, then nesting descending, then name, file and start line ascending. Ties are therefore deterministic across runs and formats.

Example output¶

The examples below are the real output for a Go file with ten functions (crates/cf-complexity/tests/fixtures/cc.go, the file the test suite measures).

{
  "overall_score_label": "6/10",
  "sections": [
    {
      "title": "COMPLEXITY",
      "score_label": "6/10",
      "status": "Fair complexity - some functions could be simplified",
      "metrics": [
        { "label": "Total Functions", "value": "10" },
        { "label": "Avg Complexity", "value": "3.6" },
        { "label": "Max Complexity", "value": "8" },
        { "label": "Total Complexity", "value": "36" },
        { "label": "Cognitive Total", "value": "29" },
        { "label": "Max Nesting", "value": "3" },
        { "label": "Decision Points", "value": "26" }
      ],
      "distribution": [
        { "label": "Simple (1-5)", "percent": 0.9, "count": 9 },
        { "label": "Moderate (6-10)", "percent": 0.1, "count": 1 },
        { "label": "Complex (11-20)", "percent": 0, "count": 0 },
        { "label": "Very Complex (>20)", "percent": 0, "count": 0 }
      ],
      "issues": [
        {
          "name": "decisions",
          "location": "cc.go",
          "value": "CC=8 | Cog=7 | Nest=1",
          "severity": "fair"
        },
        {
          "name": "manyCases",
          "location": "cc.go",
          "value": "CC=5 | Cog=1 | Nest=1",
          "severity": "good"
        }
      ],
      "score": 0.6
    }
  ],
  "overall_score": 0.6
}

function_complexity:
    - name: decisions
      source_file: cc.go
      language: go
      directory: .
      cyclomatic_complexity: 8
      cognitive_complexity: 7
      nesting_depth: 1
      lines_of_code: 22
      complexity_density: 0.36363636363636365
      risk_level: MEDIUM
    - name: manyCases
      source_file: cc.go
      language: go
      directory: .
      cyclomatic_complexity: 5
      cognitive_complexity: 1
      nesting_depth: 1
      lines_of_code: 14
      complexity_density: 0.35714285714285715
      risk_level: MEDIUM
distribution:
    moderate: 1
    simple: 9
high_risk_functions: []
aggregate:
    total_functions: 10
    average_complexity: 3.6
    max_complexity: 8
    total_complexity: 36
    cognitive_complexity: 29
    nesting_depth: 3
    decision_points: 26
    health_score: 75.5
    message: Fair complexity - some functions could be simplified

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ COMPLEXITY                                                       Score: 6/10 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

  Summary: Fair complexity - some functions could be simplified

  Key Metrics
  ────────────────────────────────────────────────────────────────────────────
  Total Functions     10          Avg Complexity      3.6
  Max Complexity      8           Total Complexity    36
  Cognitive Total     29          Max Nesting         3
  Decision Points     26

  Distribution
  ────────────────────────────────────────────────────────────────────────────
  Simple (1-5)       ████████████████████████████████████░░░░  90%  (9)
  Moderate (6-10)    ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  10%  (1)
  Complex (11-20)    ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   0%  (0)
  Very Complex (>20) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   0%  (0)

  Top Issues
  ────────────────────────────────────────────────────────────────────────────
  decisions                 cc.go                               CC=8 | Cog=7 | Nest=1
  manyCases                 cc.go                               CC=5 | Cog=1 | Nest=1
  nested                    cc.go                               CC=4 | Cog=6 | Nest=3
  loopCond                  cc.go                               CC=4 | Cog=3 | Nest=1
  boolSeq                   cc.go                               CC=4 | Cog=2 | Nest=0

Field reference¶

Per function (function_complexity, issues, report.json: functions)¶

Aggregate (aggregate, the JSON metrics)¶

distribution (yaml/bin) counts functions per cyclomatic bucket and omits empty buckets; high_risk_functions lists every function crossing at least one high threshold, ordered by risk level then the function order, with its issues (High cyclomatic complexity, High cognitive complexity, Deep nesting).

Thresholds¶

Every threshold is defined once (cf_complexity::thresholds) and used by every format.

Risk level (risk_level): each dimension scores 2 at or above its high threshold, 1 at or above its moderate threshold, else 0; the sum maps to a level.

Worked examples: cyclomatic 8, cognitive 12, nesting 3 scores 1 + 1 + 1 = 3 → HIGH; cyclomatic 15, cognitive 22, nesting 5 scores 2 + 2 + 2 = 6 → CRITICAL. The high thresholds are also what high_risk_functions reports as issues.

Cyclomatic buckets: yaml/bin distribution uses simple (≤ 5), moderate (6–10), complex (> 10); the terminal/JSON distribution uses Simple (1-5), Moderate (6-10), Complex (11-20), Very Complex (>20). Issue severity is good (≤ 5), fair (6–10), poor (≥ 11).

Per-function assessments (raw report): cyclomatic ≤ 1 🟢 Simple, ≤ 5 🟡 Moderate, else 🔴 Complex; cognitive ≤ 5 🟢 Low, ≤ 10 🟡 Medium, else 🔴 High; nesting ≤ 3 🟢 Shallow, ≤ 5 🟡 Moderate, else 🔴 Deep.

Average complexity bands (message, section score, health score):

Terminal output (readable risk triage)¶

Top issue rows include all core complexity dimensions in one compact value:

• CC=<cyclomatic> | Cog=<cognitive> | Nest=<nesting>

Example:

decisions                 cc.go                               CC=8 | Cog=7 | Nest=1
nested                    cc.go                               CC=4 | Cog=6 | Nest=3

Issues are sorted by cyclomatic complexity (then cognitive, then nesting, then name and file) so the highest-risk functions consistently appear first. text prints the top five; --verbose prints every function.

Plot output (fast visual scanning)¶

The plot output emphasizes fast interpretation for code-review and planning:

• Scatter view includes explicit cyclomatic/cognitive warning guide lines.
• Bubble size maps to nesting depth to preserve one-glance hotspot detection.
• Bar and pie views keep the same threshold semantics as terminal output.

Troubleshooting¶

• A function is missing: declarations without a body (C prototypes, Go interface methods and function types, Rust trait signatures, Java abstract/interface methods) are never reported. Anonymous function literals outside any function (Go var f = func() {}) are not reported either; inside a function they count toward that function.
• Two functions with the same name: the rows are distinct by source_file (and start line in the ordering); nothing is merged.
• Deeply nested sources: every format handles tens of thousands of nesting levels (the walk grows its stack on demand).
• --per-file with yaml/bin: the flag only enriches the json sections report; the other formats are unchanged.

See also¶

• Understanding complexity metrics — the mental model, the counting rules, and how they are validated.
• Quick start — run static analysis.