v1.3.0

The analyzer can now calculate Cognitive Complexity for supported C# executable members using a documented, deterministic scoring convention.

Unlike Cyclomatic Complexity, which primarily measures independent execution paths, Cognitive Complexity focuses on the structural burden placed on a developer reading the code.

The metric accounts for control-flow structures and the additional cognitive cost introduced by nesting.

Supported constructs include:

• if, else if, and else;
• for, foreach, while, and do;
• switch statements and switch expressions;
• catch clauses;
• conditional (?:) expressions;
• boolean condition sequences;
• pattern matching and when guards;
• nested control flow;
• direct recursion where it can be resolved safely.

Straight-line code starts with a Cognitive Complexity score of 0, while structural control-flow breaks and nesting progressively increase the score.

Nested executable members such as local functions, lambdas, and anonymous methods are analyzed independently and do not incorrectly inflate the score of their lexical parent.

New diagnostic

This release introduces:

• BIG2007 — Cognitive complexity exceeds configured threshold

The diagnostic remains opt-in and is emitted only when a Cognitive Complexity threshold has explicitly been configured and the calculated value exceeds it.

Example:

complexity_analyzers.maximum_cognitive_complexity = 15

dotnet_diagnostic.BIG2007.severity = warning

Invalid or missing configuration does not cause analysis failures and simply leaves the Cognitive Complexity threshold disabled.

Independent complexity dimensions

Cognitive Complexity is intentionally independent from the existing metrics.

A member may therefore have:

• low Cyclomatic Complexity but high Cognitive Complexity because of deep nesting;
• high Cyclomatic Complexity but comparatively low Cognitive Complexity when branches remain flat;
• high algorithmic complexity while remaining structurally simple to understand;
• low Big-O complexity while still being difficult for humans to reason about.

This distinction allows the analyzer to evaluate different dimensions of complexity without attempting to collapse them into a single maintainability score.

Reuse of the Phase 08 analysis foundation

The implementation reuses the executable-member and control-flow foundations introduced during Phase 08 rather than establishing a parallel analysis pipeline.

This keeps executable-member boundaries consistent across metrics and ensures constructs such as:

• methods;
• constructors;
• accessors;
• operators;
• conversion operators;
• local functions;
• lambdas;
• anonymous methods;
• supported expression-bodied members

continue to follow the same analysis model.

Direct recursion detection also covers supported semantic forms such as operators, conversions, and property or event accessors where Roslyn can reliably resolve the invoked symbol.

Documented scoring convention

The project's Cognitive Complexity convention is now documented in both English and Brazilian Portuguese.

The specification explicitly defines how supported C# constructs contribute to the score, including nesting behavior, boolean conditions, modern switch and pattern constructs, and executable-member isolation.

The implementation intentionally describes itself as the ComplexityAnalysis.Analyzers Cognitive Complexity convention rather than claiming equivalence with another analyzer's proprietary implementation.

This makes the metric reproducible and keeps its behavior under the project's own compatibility contract.

Validation

Phase 09 was validated against the engineering baseline established in previous releases, including:

• dedicated Cognitive Complexity unit and integration tests;
• flat versus deeply nested control-flow scenarios;
• threshold boundary behavior;
• invalid configuration handling;
• modern C# switch and pattern constructs;
• boolean-expression behavior;
• recursion scenarios;
• supported executable-member kinds;
• generated-code exclusion;
• regression coverage for Big-O, Cyclomatic Complexity, nesting depth, method-size metrics, and Parameter Count;
• analyzer performance budgets;
• Roslyn host compatibility;
• NuGet package and consumer contracts.

The SonarQube Cloud Quality Gate for the implementation also passed, including the required coverage, reliability, security, maintainability, duplication, and security-hotspot checks.

Why this release matters

Complexity is not a single-dimensional property.

Cyclomatic Complexity can tell us how many independent paths exist through a member, while Maximum Nesting Depth exposes structural depth and Big-O describes algorithmic growth. None of those metrics alone fully captures how difficult code may be for another developer to mentally follow.

Cognitive Complexity adds that missing perspective.

With Phase 09 complete, ComplexityAnalysis.Analyzers can now distinguish between computational complexity, control-flow complexity, structural depth, source size, API shape, and cognitive burden while keeping each metric independently configurable and explainable.

This continues the project's approach of preferring deterministic, evidence-based diagnostics over composite or speculative maintainability scores.

See the canonical execution roadmap in #36 — Execution order for analyzer hardening and capability expansion.

What's Changed

• feat: add Cognitive Complexity analysis for C# — #58
• closes #14 — [09.1] Add Cognitive Complexity analysis for C#

Full Changelog: v1.2.0...v1.3.0