codedeep-mcp 0.1.0

package/dist/indexer/complexity.js

@@ -0,0 +1,633 @@
+// Shared C-family boolean-operator reader (TS/JS + Go). One `binary_expression`
+// node covers ALL binary operators, so read the operator TOKEN and count only
+// the short-circuiting logical operators — the C-family boolean trap (`a + b`/
+// `a == b` must NOT increment). VERIFIED against SonarJS source (S1541): its
+// cyclomatic counts `&&`, `||`, AND `??` (all three are one ESTree
+// LogicalExpression with no operator filter); it does NOT count the
+// logical-ASSIGNMENT forms `&&=`/`||=`/`??=` (those are an AssignmentExpression,
+// absent from the cyclomatic switch). tree-sitter groups `??` as a
+// `binary_expression` (op token `??`), so reading the token catches it. Go has
+// no `??` nor logical-assignment, so the `??` entry is simply never hit there
+// (sonar-go counts `&&`/`||` only); Python uses a distinct `boolean_operator`
+// node and does not pass this predicate.
+const C_BOOLEAN_OPS = new Set(['&&', '||', '??']);
+// Returns the short-circuit logical operator KIND (`&&`/`||`/`??`) of a C-family
+// `binary_expression` node, else null. The single source for "read a C-family
+// boolean operator token": the cyclomatic predicate below counts any of the
+// three; per-language cognitive `booleanOperatorKind` readers compare the kind
+// for run-collapse (and filter out `??` where the language lacks it).
+export function cFamilyBooleanOperatorKind(node) {
+    if (node.type !== 'binary_expression')
+        return null;
+    const op = node.childForFieldName('operator')?.type;
+    return op !== undefined && C_BOOLEAN_OPS.has(op) ? op : null;
+}
+export function isCFamilyBooleanOperator(node) {
+    return cFamilyBooleanOperatorKind(node) !== null;
+}
+// Only function/method symbols carry a cyclomatic number. The gate excludes the
+// class-body PendingBody that TS/Python push for call resolution (its symbolId
+// is the CLASS symbol — counting it would fold member control flow into a
+// phantom). Bodiless symbols (interface methods, declarations) never reach here.
+const COMPLEXITY_KINDS = new Set(['function', 'method']);
+// A guard against generated/minified files: a parser table can have cyclomatic
+// in the thousands and would otherwise dominate tool output and the (future)
+// risk ranking on code agents never touch.
+const COMPLEXITY_CAP = 999;
+// The cognitive walk is RECURSIVE (the if/else-if chain, try/catch, and
+// boolean-run flatten are irreducibly recursive — a frame stack would need
+// synthetic marker frames and be more bug-prone). The Phase-2 stack-safety
+// rationale (a generated file can be pathologically deep) is preserved by this
+// explicit depth guard: descent stops past MAX_COGNITIVE_DEPTH. Real source
+// nests orders of magnitude below this.
+const MAX_COGNITIVE_DEPTH = 2000;
+// Walks each function/method PendingBody and writes `symbol.complexity` onto the
+// live Symbol instances (omitting the trivial value 1, the `receiver?`-omit
+// hygiene). Mutates `symbols` in place; returns nothing. MUST run in the
+// live-tree window (before pipeline.ts deletes the tree), at the per-language
+// `resolveCalls` call site.
+export function computeComplexity(bodies, symbols, opts) {
+    const byId = new Map(symbols.map((s) => [s.id, s]));
+    // Decision points accrue per symbolId so multiple bodies sharing an id
+    // accumulate (matters for Kotlin/C# later; a no-op for the MVP three, where
+    // each function/method has exactly one body). complexity = 1 + decisionPoints.
+    const decisionPoints = new Map();
+    // Cognitive points accrue the same way (sum across bodies, omit at 0). Null
+    // until a language opts in via `opts.cognitive`.
+    const cognitivePoints = opts.cognitive ? new Map() : null;
+    // symbolIds that have already taken the direct-recursion +1 (for `recursion.
+    // oncePerSymbol`). Owned here, across ALL of a symbol's bodies — a C# primary
+    // constructor pushes >1 body for one symbolId, so a per-body flag would re-count.
+    const recursedSymbols = new Set();
+    // The cyclomatic DFS may skip a wider set than the cognitive walk (Java
+    // excludes lambdas from cyclomatic but descends them for cognitive).
+    const cycSkip = opts.cyclomaticSkipTypes ?? opts.skipTypes;
+    for (const { symbolId, body } of bodies) {
+        const sym = byId.get(symbolId);
+        if (!sym || !COMPLEXITY_KINDS.has(sym.kind))
+            continue;
+        // If the body node is ITSELF a skip type — a curried/function-returning arrow
+        // whose `body` field is the inner `arrow_function` (`const g = (x) => (y) =>
+        // {…}`) — treat it as a separate scope and don't descend. The child loop
+        // below only skip-tests CHILDREN, so without this guard the root would bypass
+        // the skip check and leak the inner arrow's branches into this symbol.
+        if (opts.skipTypes.has(body.type))
+            continue;
+        let count = decisionPoints.get(symbolId) ?? 0;
+        // Iterative DFS (not recursion): `walkCalls` recurses unbounded, and a
+        // deeply-nested generated file could blow the stack. The skip test applies
+        // to CHILDREN (the root is handled by the guard above), mirroring walkCalls.
+        const stack = [body];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (opts.decisionNodeTypes.has(node.type))
+                count++;
+            else if (opts.extraDecisionPredicate?.(node))
+                count++;
+            if (opts.cyclomaticDecrement?.(node))
+                count--; // SwiftLint fallthrough −1
+            for (const child of node.namedChildren) {
+                if (!cycSkip.has(child.type))
+                    stack.push(child);
+            }
+        }
+        decisionPoints.set(symbolId, count);
+        if (cognitivePoints) {
+            const prev = cognitivePoints.get(symbolId) ?? 0;
+            cognitivePoints.set(symbolId, prev + computeCognitive(body, opts.cognitive, opts.skipTypes, sym, recursedSymbols));
+        }
+    }
+    for (const [id, count] of decisionPoints) {
+        const dp = Math.max(0, count); // floor: a SwiftLint `fallthrough` −1 in a broken
+        if (dp === 0)
+            continue; // parse can't drive complexity below 1; trivial omitted
+        byId.get(id).complexity = Math.min(1 + dp, COMPLEXITY_CAP);
+    }
+    if (cognitivePoints) {
+        for (const [id, points] of cognitivePoints) {
+            if (points === 0)
+                continue; // cognitive 0 → omit (the receiver?-omit hygiene)
+            byId.get(id).cognitiveComplexity = Math.min(points, COMPLEXITY_CAP);
+        }
+    }
+}
+// True when `t` is one of the language's parenthesis-like wrappers. `spec` is a
+// single `parenthesizedType` string for most languages, or a SET (C# — expression
+// AND pattern parens) matched by membership.
+function matchesParen(t, spec) {
+    return typeof spec === 'string' ? t === spec : spec.has(t);
+}
+// Unwraps nested parenthesized expressions to the inner expression (sonar's
+// ExpressionUtils.skipParentheses), used while linearizing a boolean sequence.
+function skipParens(node, parenSpec) {
+    let n = node;
+    while (n && matchesParen(n.type, parenSpec))
+        n = n.namedChild(0);
+    return n;
+}
+// First named child that is not a comment. tree-sitter attaches comments as
+// NAMED children ("extras"), so positional access (namedChild(0)) can land on a
+// comment instead of the real node — e.g. the body of `else /*c*/ {…}`. Every
+// grammar wired so far names this node type `comment`.
+function firstNonComment(node) {
+    let child = node.namedChild(0);
+    while (child && child.type === 'comment')
+        child = child.nextNamedSibling;
+    return child;
+}
+// Computes the cognitive complexity of ONE body subtree (whitepaper §1.2,
+// clean-room verified against sonar-java's CognitiveComplexityVisitor). Returns
+// the increment total (0 when trivial). Reuses the SAME skipTypes boundary as
+// the cyclomatic walk so "this symbol's body" means the same thing for both
+// metrics — methods containing anon/local classes therefore UNDER-COUNT vs
+// sonar-java (which rolls those bodies into the enclosing method); a deliberate
+// per-symbol-model divergence, like the TS/Py arrow-callback gap.
+//
+// Nesting starts at 0; a SURCHARGE node adds `1 + nesting` (the whitepaper
+// "+1 plus one per level of nesting"; sonar-java's base-1 + `+= nesting` is
+// algebraically identical). Booleans, labeled jumps, and `else`/`else if` are
+// FLAT (+1, no surcharge). Lambdas raise nesting but add nothing.
+function computeCognitive(body, cog, skipTypes, sym, 
+// symbolIds that already took the recursion +1 (for `recursion.oncePerSymbol`).
+// Owned by computeComplexity and SHARED across all of a symbol's bodies, so a
+// C# primary constructor (which pushes >1 body for one symbolId) counts recursion
+// ONCE per method, not once per body.
+recursedSymbols) {
+    let total = 0;
+    // Direct recursion (gocognit): +1 per bare self-call, but only for symbol
+    // kinds the language opts in (Go: 'function' — methods self-call via a
+    // selector, never a bare identifier, so they're excluded). Hoisted once; the
+    // `rec` capture lets TS narrow it inside visit() (no non-null assertions).
+    const rec = cog.recursion;
+    const recEligible = rec !== undefined && rec.eligibleKinds.has(sym.kind);
+    // node.id of every logical-operator node already counted as part of a boolean
+    // run, so the DFS doesn't recount them when it later descends the left spine.
+    // Keyed on node.id (stable across web-tree-sitter wrapper objects); MUST be
+    // call-local (per body) — hoisting it would undercount across symbols.
+    const counted = new Set();
+    // Per-language run-start rule; default = +1 at every operator-KIND change
+    // (sonar-java). TS overrides to count only `&&`-run-starts (SonarJS S3776).
+    const runStarts = cog.booleanRunStarts ?? ((kind, prev) => prev === null || prev !== kind);
+    // Logical-operand field names: default left/right; Swift's conjunction/disjunction
+    // nodes use lhs/rhs.
+    const leftField = cog.booleanLeftField ?? 'left';
+    const rightField = cog.booleanRightField ?? 'right';
+    // Parenthesis-like wrapper(s) to treat as transparent — a single type, or C#'s set
+    // of expression+pattern parens. Used by the source-order flatten AND the tree-scoped
+    // ancestor walk (both via `matchesParen`, which handles string or set).
+    const parenSpec = cog.parenthesizedType;
+    // Additional if-like node type(s) (Dart's collection `if_element`; Ruby's
+    // `unless`/`elsif`) are treated as `ifType`. `collectionIfType` is a single type
+    // (Dart) or a set (Ruby) — matched by equality or membership.
+    const isIfLike = (t) => t === cog.ifType ||
+        (cog.collectionIfType !== undefined &&
+            (typeof cog.collectionIfType === 'string'
+                ? t === cog.collectionIfType
+                : cog.collectionIfType.has(t)));
+    const visitField = (node, field, nesting, depth) => {
+        const child = node.childForFieldName(field);
+        if (child)
+            visit(child, nesting, depth + 1);
+    };
+    // Walks an `if`'s condition at base nesting. Field-based by default (`initField`
+    // + `conditionField`); when `conditionFromNamedChildren` is set (Dart's fieldless
+    // condition/pattern/`when`-guard), walks every named child that is NOT the
+    // consequence/alternative field-child (and not a comment) so the condition's
+    // booleans and Dart-3 pattern guards count. Shared by the head-if and the
+    // else-if branch so the two never drift.
+    const visitIfCondition = (ifNode, nesting, depth) => {
+        if (cog.conditionFromNamedChildren) {
+            const cons = ifNode.childForFieldName(cog.consequenceField);
+            const alt = ifNode.childForFieldName(cog.alternativeField);
+            for (const c of ifNode.namedChildren) {
+                if (c.type === 'comment')
+                    continue;
+                if ((cons && c.id === cons.id) || (alt && c.id === alt.id))
+                    continue;
+                visit(c, nesting, depth + 1);
+            }
+            return;
+        }
+        if (cog.initField)
+            visitField(ifNode, cog.initField, nesting, depth);
+        visitField(ifNode, cog.conditionField, nesting, depth);
+    };
+    // Python's `else_clause` (+1 FLAT, body one level deeper). Shared by BOTH the
+    // handleAlternative path (an `if`'s own terminal else, consumed there so it isn't
+    // re-dispatched) and the visit() dispatch (a for/while/try `else` reached via
+    // general descent) — one helper so the two mutually-exclusive paths can't drift.
+    const visitElseClauseBody = (clause, nesting, depth) => {
+        total += 1;
+        for (const child of clause.namedChildren)
+            visit(child, nesting + 1, depth + 1);
+    };
+    // Walks an `if`'s else/else-if chain. The head `if` is handled by the caller
+    // (it surcharges); each link here is +1 FLAT. An `else if` (alternative is
+    // another `if`) keeps the chain's base nesting for its own condition and
+    // surcharge-free body; a plain `else` scans its body one level deeper.
+    const handleAlternative = (ifNode, nesting, depth) => {
+        // Bound the else-if chain recursion by the same depth guard as `visit` — a
+        // pathologically long `if/else if/else if/…` chain would otherwise blow the
+        // native stack despite MAX_COGNITIVE_DEPTH (the chain recurses here, not
+        // through `visit`).
+        if (depth > MAX_COGNITIVE_DEPTH)
+            return;
+        // Python: the `alternative` field is a flat LIST of elif_clause / else_clause
+        // SIBLINGS (not a nested-if chain). Each elif/else is +1 FLAT; the elif
+        // condition stays at base nesting (its booleans are flat anyway), every clause
+        // BODY is one level deeper. No recursion — the clauses are siblings, not nested.
+        if (cog.elifClauseType) {
+            for (const alt of ifNode.childrenForFieldName(cog.alternativeField)) {
+                if (alt.type === cog.elifClauseType) {
+                    total += 1;
+                    visitField(alt, cog.conditionField, nesting, depth);
+                    visitField(alt, cog.consequenceField, nesting + 1, depth);
+                }
+                else if (cog.elseClauseType && alt.type === cog.elseClauseType) {
+                    // PHP two-word `else if`: an `else` clause whose body is itself an `if`.
+                    // SonarPHP gives the inner if +1 FLAT (no `else` +1) but inside the else
+                    // clause's own nesting bump, so its body is one level deeper than a one-word
+                    // elseif (elseChainsIf). Otherwise a plain `else`: +1 flat, body nested.
+                    const innerIf = cog.elseChainsIf ? alt.childForFieldName(cog.consequenceField) : null;
+                    if (innerIf && innerIf.type === cog.ifType) {
+                        const n2 = nesting + 1; // the else clause's nesting bump wraps the inner if
+                        total += 1; // inner if: +1 FLAT (SonarPHP's ifStatementWithoutNesting)
+                        visitIfCondition(innerIf, n2, depth);
+                        visitField(innerIf, cog.consequenceField, n2 + 1, depth);
+                        handleAlternative(innerIf, n2, depth + 1);
+                    }
+                    else {
+                        visitElseClauseBody(alt, nesting, depth);
+                    }
+                }
+            }
+            return;
+        }
+        const rawAlt = ifNode.childForFieldName(cog.alternativeField);
+        if (!rawAlt)
+            return;
+        // Unwrap an else-wrapper node (TS `else_clause`) to the real else-if / else
+        // body; grammars that hold the if/block directly (Java) leave elseClauseType
+        // unset and use rawAlt as-is. SKIP a leading comment: tree-sitter attaches a
+        // comment sitting between `else` and the body as a NAMED child of the wrapper
+        // (`else /*c*/ {…}`), so a bare namedChild(0) would grab the comment and drop
+        // the entire else body's complexity.
+        const alt = cog.elseClauseType && rawAlt.type === cog.elseClauseType
+            ? firstNonComment(rawAlt)
+            : rawAlt;
+        if (!alt)
+            return;
+        if (isIfLike(alt.type)) {
+            total += 1; // the `else if` keyword: +1 flat, no surcharge (elsif chains always count)
+            visitIfCondition(alt, nesting, depth);
+            visitField(alt, cog.consequenceField, nesting + 1, depth);
+            handleAlternative(alt, nesting, depth + 1);
+        }
+        else {
+            // Plain (terminal) else: +1 flat for the `else` keyword — UNLESS the head if is
+            // an EXPRESSION-TERNARY (Ruby: a simple 2-branch if-else used as an expression,
+            // where SLANG's isTernaryOperator suppresses the else). Unset elsewhere → always
+            // +1 (sonar-java/whitepaper). Body at nesting+1 (sonar default) or base nesting
+            // (gocognit, via nestElseBody === false; `=== false` keeps unset = sonar-java).
+            if (!cog.isExpressionTernary || !cog.isExpressionTernary(ifNode))
+                total += 1;
+            visit(alt, cog.nestElseBody === false ? nesting : nesting + 1, depth + 1);
+        }
+    };
+    // Swift's POSITIONAL `if` (cog.ifPositionalBlockType set): no consequence/
+    // alternative field. Conditions are `conditionField` children (possibly several:
+    // `if a, let b = c`); the consequence is the block child BEFORE the `else` keyword;
+    // the else branch (an `ifType` else-if, or a plain-else block AFTER `else`) is split
+    // off at the `else` keyword (elseKeywordType) — NOT inferred from a second block
+    // child, because an empty `{}` body emits NO block node, which would otherwise drop
+    // the `+1 FLAT` for an empty-consequence or empty-else branch. The head if's surcharge
+    // is added by the caller; this walks the conditions (base nesting, booleans flat), the
+    // consequence (nesting+1), and the FLAT else/else-if chain (each +1, no surcharge —
+    // recurses for else-if WITHOUT a head surcharge). Depth-guarded like handleAlternative
+    // (a long else-if chain recurses here, not through `visit`).
+    const visitPositionalIfBody = (ifNode, nesting, depth) => {
+        if (depth > MAX_COGNITIVE_DEPTH)
+            return;
+        // Conditions: base nesting, booleans flat (Swift allows several — `if a, let b = c`).
+        // condIds is built ONLY for the Kotlin path (it excludes the condition field-children —
+        // a field child is also a named child — when locating the consequence/else among
+        // namedChildren); Swift finds the consequence by block type and never reads it, so it
+        // stays null (no allocation on the Swift path).
+        const condIds = cog.ifConsequenceFromNamedChildren ? new Set() : null;
+        for (const cond of ifNode.childrenForFieldName(cog.conditionField)) {
+            condIds?.add(cond.id);
+            visit(cond, nesting, depth + 1);
+        }
+        // Kotlin: the `else` keyword is ANONYMOUS and a branch may be BRACE-LESS, so SPLIT at
+        // the `else` keyword (always emitted for a real else, even when a branch is a `;` empty
+        // statement that emits no named child — the empty-branch lesson). The consequence is the
+        // first named non-condition non-comment child BEFORE `else`; the else body is the first
+        // such child AFTER it (each may be absent for a `;` branch).
+        if (cog.ifConsequenceFromNamedChildren) {
+            const isBody = (c) => c.isNamed && !condIds.has(c.id) && c.type !== 'line_comment' && c.type !== 'block_comment';
+            const kids = ifNode.children;
+            const elseIdx = cog.elseKeywordType ? kids.findIndex((c) => c.type === cog.elseKeywordType) : -1;
+            const consequence = (elseIdx === -1 ? kids : kids.slice(0, elseIdx)).find(isBody);
+            if (consequence)
+                visit(consequence, nesting + 1, depth + 1);
+            if (elseIdx === -1)
+                return; // no else clause
+            const elseBody = kids.slice(elseIdx + 1).find(isBody);
+            // sonar-kotlin charges the else +1 ONLY when the else body is a block (`{}`, the
+            // elseChargeBlockType) or an else-if (`ifType`) — a BRACE-LESS `else expr` is the
+            // ternary form and gets NO +1. The else body still NESTS regardless.
+            const isElseIf = elseBody?.type === cog.ifType;
+            if (isElseIf || elseBody?.type === cog.elseChargeBlockType)
+                total += 1; // +1 FLAT, no surcharge
+            if (isElseIf)
+                visitPositionalIfBody(elseBody, nesting, depth + 1); // else-if chain, no head surcharge
+            else if (elseBody)
+                visit(elseBody, nesting + 1, depth + 1); // plain else body nests
+            return;
+        }
+        const blockType = cog.ifPositionalBlockType;
+        const kids = ifNode.namedChildren;
+        // The `else` keyword (a named token) signals the else clause and splits the body
+        // from it — even when either block is the empty `{}` that emits no block node.
+        const elseIdx = cog.elseKeywordType ? kids.findIndex((c) => c.type === cog.elseKeywordType) : -1;
+        const beforeElse = elseIdx === -1 ? kids : kids.slice(0, elseIdx);
+        const consequence = beforeElse.find((c) => c.type === blockType);
+        if (consequence)
+            visit(consequence, nesting + 1, depth + 1);
+        if (elseIdx === -1)
+            return; // no else clause
+        total += 1; // else / else-if: +1 FLAT, no surcharge
+        const afterElse = kids.slice(elseIdx + 1);
+        const elseIf = afterElse.find((c) => c.type === cog.ifType);
+        if (elseIf) {
+            visitPositionalIfBody(elseIf, nesting, depth + 1); // recurse the chain
+        }
+        else {
+            const elseBody = afterElse.find((c) => c.type === blockType);
+            if (elseBody)
+                visit(elseBody, nesting + 1, depth + 1); // may be absent (empty else)
+        }
+    };
+    function visit(node, nesting, depth) {
+        if (depth > MAX_COGNITIVE_DEPTH)
+            return;
+        const t = node.type;
+        if (skipTypes.has(t))
+            return; // nested classes / methods: own symbols' bodies
+        // --- direct recursion: +1 FLAT per self-call site (no surcharge, no return:
+        // the call's arguments still descend below to catch nested control flow). A
+        // call node is never a boolean (so never in `counted`) and matches no other
+        // dispatch branch, so this can't double-count. The walk descends func_literal
+        // (nestOnly), so a self-call inside a closure counts toward the enclosing
+        // function — matching gocognit, whose FuncDecl-rooted walk doesn't reset the
+        // target across closures. ---
+        if (recEligible && rec && t === rec.callType) {
+            // null/undefined callee never equals the (always-non-empty) symbol name.
+            const isSelf = rec.isSelfCall
+                ? rec.isSelfCall(node, body, sym)
+                : rec.bareCalleeName?.(node) === sym.name;
+            if (isSelf) {
+                // oncePerSymbol (C#): +1 only the FIRST time across the symbol's bodies.
+                // Per-site (Go, oncePerSymbol unset): +1 every time, `recursedSymbols` untouched.
+                if (!rec.oncePerSymbol || !recursedSymbols.has(sym.id))
+                    total += 1;
+                if (rec.oncePerSymbol)
+                    recursedSymbols.add(sym.id);
+            }
+        }
+        // --- if / else-if / else chain (head if surcharges; chain links are flat).
+        // `isIfLike` also matches Dart's collection `if_element` (an if inside a
+        // collection literal — same surcharge/else handling). ---
+        if (isIfLike(t)) {
+            total += 1 + nesting;
+            if (cog.ifPositionalBlockType || cog.ifConsequenceFromNamedChildren) {
+                // Positional consequence/else (no fields): Swift (keyword-split) or Kotlin
+                // (anon `else` + brace-less branches). See visitPositionalIfBody.
+                visitPositionalIfBody(node, nesting, depth);
+            }
+            else {
+                visitIfCondition(node, nesting, depth);
+                visitField(node, cog.consequenceField, nesting + 1, depth);
+                handleAlternative(node, nesting, depth);
+            }
+            return;
+        }
+        // --- for/while/try `else` clause (Python): +1 flat, body one level deeper.
+        // Gated on elifClauseType (Python mode). The `if`'s OWN else is consumed by
+        // handleAlternative (the if-case returns), so this fires only for a loop/try
+        // `else_clause` reached via general descent — matching sonar-python's
+        // `visitElseClause` (+1 flat) with the else body StatementList nesting one level. ---
+        if (cog.elifClauseType && cog.elseClauseType && t === cog.elseClauseType) {
+            visitElseClauseBody(node, nesting, depth);
+            return;
+        }
+        // --- loops: surcharge, then nest the body. With loopBodyField set (Python),
+        // ONLY the body child nests and the iterable/condition/target/`else` stay at the
+        // loop's ambient nesting (sonar-python). Without it, ALL children nest — the
+        // KNOWN DIVERGENCE (Java/TS/Go, accepted): sonar nests ONLY the body, not the
+        // loop header, so a nested STRUCTURAL construct in the header (`for(;cond?a:b;)`)
+        // over-counts; booleans are flat (unaffected) and headers rarely hold control
+        // flow (0 cases in the TS/gson/gocognit oracles). The precise per-construct-body
+        // fix landed for Python (loopBodyField); generalizing it needs re-oracling the
+        // other grammars, deferred. ---
+        if (cog.loopTypes.has(t)) {
+            total += 1 + nesting;
+            const bodyChild = cog.loopBodyField ? node.childForFieldName(cog.loopBodyField) : null;
+            for (const child of node.namedChildren) {
+                const inner = cog.loopBodyField
+                    ? bodyChild && child.id === bodyChild.id
+                        ? nesting + 1
+                        : nesting
+                    : nesting + 1;
+                visit(child, inner, depth + 1);
+            }
+            return;
+        }
+        // --- surcharge-FLAT (C# `goto`/`goto case`): surcharge (+1 + nesting) but
+        // descend children at the SAME nesting — the construct itself is a flow-breaker,
+        // but a structural construct in its operand (`goto case (p ? 1 : 2)`) is NOT
+        // nested by SonarC# (it's counted at the goto's own nesting). Kept separate from
+        // the switch/ternary branch, which DOES nest its children. ---
+        if (cog.surchargeTypes?.has(t)) {
+            total += 1 + nesting;
+            for (const child of node.namedChildren)
+                visit(child, nesting, depth + 1);
+            return;
+        }
+        // --- ternary with BRANCH-ONLY nesting (PHP): surcharge, but nest ONLY the
+        // configured branch fields (true/false); the CONDITION stays at the ternary's
+        // ambient nesting. Resolves the overbump for a chained elvis `a ?: b ?: c`
+        // (`((a ?: b) ?: c)`), whose inner conditionals sit in the CONDITION position —
+        // bump-all would compound the surcharge per link (SonarPHP visits the condition at
+        // ambient). The loopBodyField analog for ternaries; only PHP sets ternaryBranchFields. ---
+        if (t === cog.ternaryType && cog.ternaryBranchFields) {
+            total += 1 + nesting;
+            const branchIds = new Set();
+            for (const f of cog.ternaryBranchFields) {
+                const c = node.childForFieldName(f);
+                if (c)
+                    branchIds.add(c.id);
+            }
+            for (const child of node.namedChildren) {
+                visit(child, branchIds.has(child.id) ? nesting + 1 : nesting, depth + 1);
+            }
+            return;
+        }
+        // --- switch / ternary: surcharge, then ALL children one level deeper. (sonar
+        // nests the WHOLE ternary subtree — incl. its test — so bump-all is correct for
+        // a ternary; the header-overbump caveat above applies to switch discriminants.)
+        // A statement-position ternary (Ruby: parent ∈ ternaryStatementParentTypes) is
+        // an if-else, so it also takes the `else` keyword's +1 FLAT. ---
+        if (cog.switchTypes.has(t) || t === cog.ternaryType) {
+            total += 1 + nesting;
+            // A STATEMENT-position ternary (Ruby) is an if-else → also +1 for the `else`;
+            // an EXPRESSION-position ternary is the surcharge-only form. Unset elsewhere
+            // (other languages' ternaries are always surcharge-only).
+            if (t === cog.ternaryType && cog.isExpressionTernary && !cog.isExpressionTernary(node)) {
+                total += 1;
+            }
+            for (const child of node.namedChildren)
+                visit(child, nesting + 1, depth + 1);
+            return;
+        }
+        // --- catch clause: surcharge at the current (try's) nesting, body one level
+        // deeper. Handled as its own case rather than nested inside a try-node
+        // branch, so it fires for ANY try container — `try_statement` AND
+        // `try_with_resources_statement` — which are themselves plain pass-through
+        // (the try body / resource spec / `finally` add nothing and don't bump). ---
+        if (t === cog.catchType && (!cog.catchPredicate || cog.catchPredicate(node))) {
+            total += 1 + nesting;
+            for (const child of node.namedChildren)
+                visit(child, nesting + 1, depth + 1);
+            return;
+        }
+        // --- try container with FLAT catch bodies (Dart): the try body (`bodyField`
+        // child) and the `on`/type/`catch_clause` headers + `finally` stay at base
+        // nesting; EACH other direct `catchBodyType` child is a catch body that
+        // surcharges (+1 + nesting) and nests at +1. This covers `catch(e){}`,
+        // `on E catch(e){}`, AND a binding-less `on E {}` (a block with no catch_clause),
+        // all of which the SonarQube Dart rule counts as a catch. Other languages leave tryType unset
+        // (their catch clause contains its body — handled by the catchType branch). ---
+        if (cog.tryType && t === cog.tryType.node) {
+            const tryBody = node.childForFieldName(cog.tryType.bodyField);
+            for (const child of node.namedChildren) {
+                // A catch body = a `catchBodyType` child that is NOT the try body. The
+                // `tryBody &&` guard matters on a malformed parse where the `body:` field
+                // didn't bind (tryBody null): without it the try body itself would be
+                // mis-surcharged as a catch (an over-count); instead descend everything at
+                // base nesting (a safe under-count). Valid Dart always binds `body:`.
+                if (tryBody && child.type === cog.tryType.catchBodyType && child.id !== tryBody.id) {
+                    total += 1 + nesting;
+                    visit(child, nesting + 1, depth + 1);
+                }
+                else {
+                    visit(child, nesting, depth + 1);
+                }
+            }
+            return;
+        }
+        // --- nesting-only (lambda): raise nesting, add nothing ---
+        if (cog.nestOnlyTypes.has(t)) {
+            for (const child of node.namedChildren)
+                visit(child, nesting + 1, depth + 1);
+            return;
+        }
+        // --- labeled break/continue: +1 flat if it jumps to a label, then DESCEND. In
+        // Rust `break`/`continue` are EXPRESSIONS that can carry a value (`break a && b`,
+        // `break if c {1} else {2}`) whose control flow counts (flat, no extra bump); the
+        // label is a `label` leaf that matches no branch, so descending it is a no-op.
+        // Go/Java/TS/Python jumps hold only a label/nothing, so the descent is a no-op
+        // there too (verified: the full suite is unchanged). ---
+        if (cog.labeledJumpTypes.has(t)) {
+            if (cog.hasLabel(node))
+                total += 1;
+            for (const child of node.namedChildren)
+                visit(child, nesting, depth + 1);
+            return;
+        }
+        // --- boolean runs (TREE-SCOPED, the SonarQube Dart model): a logical node adds +1 iff its
+        // operator kind differs from its nearest LOGICAL ANCESTOR (skipping parens) —
+        // a top-of-tree logical node or a kind-change starts a run. No flatten: each
+        // logical node is processed once as the DFS reaches it, operands descend below. ---
+        if (cog.booleanByTreeParent) {
+            const kind = cog.booleanOperatorKind(node);
+            if (kind !== null) {
+                let anc = node.parent;
+                while (anc && matchesParen(anc.type, parenSpec))
+                    anc = anc.parent;
+                const ancKind = anc ? cog.booleanOperatorKind(anc) : null;
+                if (ancKind !== kind)
+                    total += 1; // new run (different or no logical parent)
+                for (const child of node.namedChildren)
+                    visit(child, nesting, depth + 1);
+                return;
+            }
+        }
+        // --- boolean runs: +1 per maximal same-kind sequence in SOURCE order ---
+        if (cog.booleanOperatorKind(node) !== null) {
+            if (!counted.has(node.id)) {
+                // Linearize the whole boolean tree IN SOURCE ORDER (sonar's
+                // flattenLogicalExpression): in-order over BOTH operands, unwrapping
+                // parens, so `a && b && (c||d)` → [&&, &&, ||]. A +1 is charged at the
+                // start and at each operator-kind change. (A left-spine-only flatten
+                // would wrongly merge &&s split by a parenthesized || — oracle-caught.)
+                const run = [];
+                // `d` carries the visit depth so a pathologically long boolean spine
+                // (`a && a && … `, tens of thousands of operands in generated code)
+                // can't overflow the native stack — bounded by the same guard as `visit`.
+                const flatten = (n, d) => {
+                    if (d > MAX_COGNITIVE_DEPTH)
+                        return;
+                    const inner = skipParens(n, parenSpec);
+                    if (inner && cog.booleanOperatorKind(inner) !== null) {
+                        counted.add(inner.id);
+                        // Operands via the operand FIELDS (default `left`/`right`, Swift
+                        // `lhs`/`rhs` via booleanLeftField/booleanRightField), not positional
+                        // namedChild(0)/(1): a comment interleaved around the operator
+                        // (`a && /*c*/ b`) is a named child, so positional access would read
+                        // the comment as the right operand and drop a parenthesized sub-run.
+                        // Every logical node so far (Java/TS/Go/Rust `binary_expression`,
+                        // Python `boolean_operator`, Swift `conjunction_expression`/
+                        // `disjunction_expression`) exposes a left/right operand field pair;
+                        flatten(inner.childForFieldName(leftField), d + 1);
+                        run.push(inner);
+                        flatten(inner.childForFieldName(rightField), d + 1);
+                    }
+                };
+                flatten(node, depth); // marks the whole subtree `counted`
+                // A run whose ROOT is excluded (TS JSX short-circuit) contributes 0 —
+                // but the flatten above still ran, so its inner logical nodes won't be
+                // recounted when the DFS descends below.
+                if (!cog.excludeBooleanRun?.(node)) {
+                    let prevKind = null;
+                    for (const n of run) {
+                        const kind = cog.booleanOperatorKind(n); // non-null: it's in `run`
+                        if (runStarts(kind, prevKind))
+                            total += 1;
+                        prevKind = kind;
+                    }
+                }
+            }
+            // Descend operands at the SAME nesting (booleans are flat). The flattened
+            // logical nodes are in `counted` so they skip the run-count but are still
+            // descended (to catch a nested ternary / control structure in an operand).
+            for (const child of node.namedChildren)
+                visit(child, nesting, depth + 1);
+            return;
+        }
+        // --- flat conditional (Rust `let … else`): +1 flat, then descend at the
+        // SAME nesting (no surcharge, no bump — the value expr and the divergent else
+        // block both stay at the binding's level). ---
+        if (cog.flatIncrement?.(node)) {
+            total += 1;
+            for (const child of node.namedChildren)
+                visit(child, nesting, depth + 1);
+            return;
+        }
+        // --- default: pass through, nesting unchanged ---
+        for (const child of node.namedChildren)
+            visit(child, nesting, depth + 1);
+    }
+    visit(body, 0, 0);
+    return total;
+}