Cognitive Complexity

[boyter]

WIP adding cognative complexity... well an approximation of it.

We want to track cognitive complexity nesting. Cognitive complexity
means we assign higher complexity to nested branch conditions, so

if something:
	  if otherthing:

would be assigned a higher complexity than

if something:
if otherthing:

because the nested if requires more mental overhead. To do this we need to track
how nested each condition is when we hit it. We do this by counting the number of
whitespace characters are in front of the condition.
This is an appoximation, true for languages like Python, and probably true for anything
else. However, the benefit of this approach is that it's almost free from a CPU point of view
and the increase in spotting complex code, is genuinely useful.

[boyter]

$ hyperfine 'scc' 'scc --cognitive'
Benchmark 1: scc
  Time (mean ± σ):      4.573 s ±  0.047 s    [User: 11.815 s, System: 6.274 s]
  Range (min … max):    4.520 s …  4.658 s    10 runs

Benchmark 2: scc --cognitive
  Time (mean ± σ):      4.583 s ±  0.086 s    [User: 12.069 s, System: 6.188 s]
  Range (min … max):    4.521 s …  4.816 s    10 runs

Summary
  scc ran
    1.00 ± 0.02 times faster than scc --cognitive

No performance regression from this, and the impact of it is actually almost nothing when turned on. I was expecting 5% overhead, but its closer to benchmark noise.

[Copilot]

Pull request overview

This PR introduces an opt-in “cognitive complexity” metric (nesting-weighted) alongside existing cyclomatic complexity, propagating it through core counting, formatting, history/hotspot analysis, CLI/config flags, and MCP output. The goal is to better surface deeply nested code with minimal additional runtime overhead.

Changes:

• Add --cognitive mode that computes and aggregates nesting-weighted complexity (plus per-line tracking when enabled).
• Update formatters (tabular/CSV/SQL/JSON behavior + sorting) and history hotspots scoring to use cognitive magnitude where appropriate.
• Add focused test coverage for cognitive counting, formatting, history ranking, MCP behavior, and config/flag parsing; update docs and scripts for .sccconfig.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test-all.sh	Updates the project config discovery test to use ./.sccconfig.
SCC-OUTPUT-REPORT.html	Refreshes the checked-in output report to reflect new metrics/files/tests.
README.md	Documents new --cognitive flag and .sccconfig usage/precedence.
processor/workers.go	Implements cognitive nesting tracking and increments cognitive complexity alongside cyclomatic.
processor/workers_cognitive_test.go	Adds unit tests for cognitive counting behavior and per-line invariants.
processor/structs.go	Extends FileJob and LanguageSummary with cognitive fields and per-line storage.
processor/processor.go	Adds the Cognitive global and ensures it implies complexity counting.
processor/history.go	Carries cognitive values through history snapshotting and per-line extraction helpers.
processor/history_hotspots.go	Makes hotspot scoring use cognitive magnitude when enabled.
processor/history_cognitive_test.go	Tests cognitive line-number extraction and hotspot ranking behavior.
processor/formatters.go	Adds active-metric selection for sorting/break rendering in tabular output.
processor/formatters_tabular.go	Adds a wide tabular “Cognitive” column and sums when enabled.
processor/formatters_sql.go	Extends SQL output/schema to include cognitive when enabled.
processor/formatters_csv.go	Extends CSV output and sorting semantics to include/optionally sort by cognitive.
processor/formatters_cognitive_test.go	Adds formatter-level regression tests for cognitive-enabled/disabled parity.
processor/cognitive_nesting_test.go	Adds higher-level tests pinning expected nesting-weight behavior.
mcp.go	Adds MCP cognitive argument and includes cognitive fields in MCP results/totals.
mcp_test.go	Adds MCP tests for cognitive enabled/disabled and per-call state stability.
config.go	Registers the --cognitive CLI/config flag.
config_test.go	Updates exhaustive flag tests and adds cognitive flag/config round-trip tests.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.