fix(complexity): score else-if chains at parent nesting level

Else-if alternates no longer inherit consequent cognitive nesting;
golden pins labyrinth cognitive_complexity at 27 on minimal fixture.

Author: SutuSebastian

docs/architecture.md

@@ -283,7 +283,7 @@ All base tables use `STRICT` mode; **`source_fts`** is an FTS5 virtual table (no
 | parent_name          | TEXT       | Nearest **named** enclosing scope (class, function, method, arrow-assigned-to-const). Walks past anonymous arrows / IIFEs / callbacks (e.g. `forEach(() => …)` inside `foo` → `parent_name='foo'`). NULL when no named owner exists — true module-scope OR inside a top-level anonymous IIFE. **For a strict "module-scope only" filter use `scope_local_id = 0`** (the canonical answer), not `parent_name IS NULL` |
 | visibility           | TEXT       | JSDoc visibility tag derived from `doc_comment` at parse time: `public` / `private` / `internal` / `alpha` / `beta`. NULL when no tag present. Tag must start its own line (after the JSDoc `*` prefix); first match in document order wins. Powers the `visibility-tags` recipe and `WHERE visibility = ?` queries via the partial index `idx_symbols_visibility`                                                   |
 | complexity           | REAL       | Cyclomatic complexity (McCabe; `1 + decision points`) for function-shaped symbols (top-level `function`, named arrow/const, class methods). NULL for non-functions. Decision points: `if`, `while`, `do…while`, `for`, `for…in`, `for…of`, `case X:` arms (not `default:`), short-circuit logical/nullish operators, ternary `?:`, and `catch` clauses. Powers `high-complexity-untested` (cyclomatic gate)          |
-| cognitive_complexity | INTEGER    | SonarSource cognitive complexity for the same function-shaped symbols as `complexity` (NULL otherwise). Penalizes nesting; computed in the same oxc walk as cyclomatic (`src/extractors/complexity.ts`). Powers `high-cognitive-complexity`; also exposed as a column on `high-complexity-untested` rows                                                                                                             |
+| cognitive_complexity | INTEGER    | Sonar-inspired cognitive complexity for the same function-shaped symbols as `complexity` (NULL otherwise). Penalizes nesting over flat else-if chains; same oxc walk as cyclomatic. Powers `high-cognitive-complexity`; also exposed as a column on `high-complexity-untested` rows                                                                                                                                  |
 | name_column_start    | INTEGER    | 0-based column of the symbol-name token on `line_start` (per [R.6])                                                                                                                                                                                                                                                                                                                                                  |
 | name_column_end      | INTEGER    | One-past-last column of the symbol-name token                                                                                                                                                                                                                                                                                                                                                                        |
 | scope_local_id       | INTEGER    | Enclosing scope where the symbol's NAME is declared (joins `scopes.local_id`). Default `0` (module)                                                                                                                                                                                                                                                                                                                  |

docs/glossary.md

@@ -141,7 +141,7 @@ Per-function decision-point count (REAL column on `symbols`). Computed by the pa
 
 ### `symbols.cognitive_complexity` / cognitive complexity
 
-SonarSource cognitive complexity (INTEGER on `symbols`) for the same function-shaped symbols as cyclomatic `complexity`. Penalizes nested control flow; same oxc walk as McCabe (`src/extractors/complexity.ts`). Recipes: `high-cognitive-complexity` (`min_score` default 15); `high-complexity-untested` includes the column while filtering on cyclomatic `complexity`.
+SonarSource-inspired cognitive complexity (INTEGER on `symbols`) for the same function-shaped symbols as cyclomatic `complexity`. Penalizes nested control flow; computed in the same parser walk as McCabe. Recipes: `high-cognitive-complexity` (`min_score` default 15, Sonar rule threshold); `high-complexity-untested` includes the column while filtering on cyclomatic `complexity`.
 
 ### `source_fts` (FTS5 virtual table) / `--with-fts` / opt-in full-text
 

fixtures/golden/minimal/high-cognitive-complexity.json

@@ -5,7 +5,7 @@
     "file_path": "src/lib/complexity-fixture.ts",
     "line_start": 22,
     "line_end": 83,
-    "cognitive_complexity": 40,
+    "cognitive_complexity": 27,
     "complexity": 19,
     "nesting_depth": 5
   }

fixtures/golden/minimal/high-complexity-untested.json

@@ -6,7 +6,7 @@
     "line_start": 22,
     "line_end": 83,
     "complexity": 19,
-    "cognitive_complexity": 40,
+    "cognitive_complexity": 27,
     "coverage_pct": 0
   }
 ]

src/extractors/complexity.test.ts

@@ -23,19 +23,42 @@ describe("cognitive complexity", () => {
     expect(sym?.cognitive_complexity).toBeGreaterThan(sym!.complexity!);
   });
 
-  it("flat if-else-if chain: cognitive ≈ cyclomatic", () => {
-    const src = `export function flat(n: number): number {
+  it("flat if-else-if chain: cognitive ≈ cyclomatic, below nested peer", () => {
+    const flatSrc = `export function flat(n: number): number {
   if (n % 2 === 0) return 1;
   else if (n % 3 === 0) return 2;
   else if (n % 5 === 0) return 3;
   return 0;
 }
 `;
-    const d = extractFileData("/proj/x.ts", src, "x.ts");
-    const sym = d.symbols.find((s) => s.name === "flat");
-    expect(sym?.complexity).toBe(4);
-    expect(sym?.cognitive_complexity).toBeGreaterThanOrEqual(3);
-    expect(sym?.cognitive_complexity).toBeLessThanOrEqual(sym!.complexity! + 2);
+    const nestedSrc = `export function nested(level: number): number {
+  if (level > 0) {
+    if (level > 1) {
+      if (level > 2) {
+        return level;
+      }
+      return 2;
+    }
+    return 1;
+  }
+  return 0;
+}
+`;
+    const flat = extractFileData("/proj/x.ts", flatSrc, "x.ts").symbols.find(
+      (s) => s.name === "flat",
+    );
+    const nested = extractFileData(
+      "/proj/x.ts",
+      nestedSrc,
+      "x.ts",
+    ).symbols.find((s) => s.name === "nested");
+    expect(flat?.complexity).toBe(4);
+    expect(nested?.complexity).toBe(4);
+    expect(flat?.cognitive_complexity).toBe(3);
+    expect(nested?.cognitive_complexity).toBe(6);
+    expect(flat!.cognitive_complexity!).toBeLessThan(
+      nested!.cognitive_complexity!,
+    );
   });
 
   it("class method: both complexity and cognitive_complexity populated", () => {

src/extractors/complexity.ts

@@ -66,10 +66,13 @@ export function createComplexityTracker(
     getArrowSymbol(node) {
       return arrowMap.get(node);
     },
-    cognitiveStructural() {
+    cognitiveStructural(opts?: { elseIf?: boolean }) {
       const top = stack[stack.length - 1];
       if (!top) return;
-      top.cognitive += 1 + top.cognitiveNest;
+      const nestLevel = opts?.elseIf
+        ? Math.max(0, top.cognitiveNest - 1)
+        : top.cognitiveNest;
+      top.cognitive += 1 + nestLevel;
     },
     cognitiveFlat() {
       const top = stack[stack.length - 1];
@@ -91,8 +94,12 @@ export const complexityExtractor: TierExtractor = {
   tierId: "complexity",
   register(visitor, ctx) {
     const { complexity } = ctx;
+    // Else-if chains reuse the parent `if`'s cognitive nesting level (Sonar
+    // spec) — mark alternate `IfStatement` nodes on the parent enter.
+    const elseIfNodes = new WeakSet<object>();
+
     const nest = () => {
-      complexity.cognitiveStructural();
+      complexity.cognitiveStructural({});
       complexity.enterCognitiveNest();
       complexity.enterNest();
       complexity.increment();
@@ -101,6 +108,21 @@ export const complexityExtractor: TierExtractor = {
       complexity.exitCognitiveNest();
       complexity.exitNest();
     };
+    const nestIf = (node: any) => {
+      if (node.alternate?.type === "IfStatement") {
+        elseIfNodes.add(node.alternate);
+      }
+      const isElseIf = elseIfNodes.has(node);
+      complexity.cognitiveStructural({ elseIf: isElseIf });
+      if (!isElseIf) complexity.enterCognitiveNest();
+      complexity.enterNest();
+      complexity.increment();
+    };
+    const unnestIf = (node: any) => {
+      if (!elseIfNodes.has(node)) complexity.exitCognitiveNest();
+      elseIfNodes.delete(node);
+      complexity.exitNest();
+    };
 
     Object.assign(visitor, {
       // `symbolsExtractor`'s VariableDeclaration populates the arrow
@@ -122,8 +144,8 @@ export const complexityExtractor: TierExtractor = {
       // forms (if/for/while/try/ternary) ALSO increment nesting_depth
       // on enter and decrement on exit. Cognitive uses Sonar structural
       // increments (+1 + nesting) on the same shapes.
-      IfStatement: nest,
-      "IfStatement:exit": unnest,
+      IfStatement: nestIf,
+      "IfStatement:exit": unnestIf,
       WhileStatement: nest,
       "WhileStatement:exit": unnest,
       DoWhileStatement: nest,

src/extractors/types.ts

@@ -71,7 +71,7 @@ export interface ComplexityTracker {
   markArrowSymbol(node: object, symbolIndex: number): void;
   getArrowSymbol(node: object): number | undefined;
   /** Sonar structural break (+1 + current cognitive nesting). */
-  cognitiveStructural(): void;
+  cognitiveStructural(opts?: { elseIf?: boolean }): void;
   /** Flat +1 (switch case, boolean operator) — no nesting penalty. */
   cognitiveFlat(): void;
   enterCognitiveNest(): void;

templates/recipes/high-cognitive-complexity.md

@@ -4,7 +4,7 @@ params:
     type: number
     required: false
     default: 15
-    description: Minimum SonarSource cognitive complexity score (default matches Sonar rule threshold)
+    description: Minimum cognitive complexity score (default 15 matches Sonar rule threshold)
 actions:
   - type: review-cognitive-complexity
     auto_fixable: false
@@ -13,7 +13,7 @@ actions:
 
 # high-cognitive-complexity
 
-Functions with **cognitive complexity** ≥ `min_score` (default **15**, Sonar-aligned). Uses the same function-shaped symbol coverage as cyclomatic `symbols.complexity` (top-level functions, named arrow/const, class methods).
+Functions with **cognitive complexity** ≥ `min_score` (default **15**, Sonar rule threshold). Uses the same function-shaped symbol coverage as cyclomatic `symbols.complexity` (top-level functions, named arrow/const, class methods).
 
 Distinct from `high-complexity-untested` (cyclomatic gate + coverage) and `deeply-nested-functions` (`nesting_depth` only).
 

templates/recipes/high-complexity-untested.md

@@ -16,7 +16,7 @@ McCabe formula: `1 + (decision points)`. Branching nodes counted by Codemap's pa
 - `&&` / `||` / `??` short-circuit operators (`?` / `:` ternary too)
 - `catch` clauses
 
-**Computed for function-shaped symbols** — top-level `function` declarations, named arrow/const bindings, and class methods (`MethodDefinition` bodies). Non-function kinds (interfaces, types, enums, plain consts) get `complexity = NULL` and are excluded by `WHERE s.complexity IS NOT NULL`.
+**Computed for function-shaped symbols** — top-level `function` declarations, named arrow/const bindings, and class methods. Non-function kinds (interfaces, types, enums, plain consts) get `complexity = NULL` and are excluded by `WHERE s.complexity IS NOT NULL`.
 
 ## Cognitive complexity column (`symbols.cognitive_complexity`)