chore(repo): gate cognitive complexity with bulk suppressions

.changeset/complexity-lint-warning.md

@@ -0,0 +1,2 @@
+---
+---

.claude/skills/clerk-monorepo/SKILL.md

@@ -85,6 +85,10 @@ pnpm --filter @clerk/backend test:node path/to/file.test.ts
 pnpm lint
 pnpm format            # workspace packages plus root files, docs/, integration/, scripts/
 pnpm prettier --write '.claude/**/*.md'   # pnpm format does not cover .claude/; format skill files this way
+# Cognitive complexity (`sonarjs/cognitive-complexity`, max 15) is an error. Existing violations are
+# grandfathered in each package's eslint-suppressions.json. After simplifying one of those functions, drop its
+# stale entry (lint fails until you do) from inside that package:
+pnpm eslint src --prune-suppressions
 
 # Changesets — write the file, don't run the CLI (both scripts are interactive prompts)
 pnpm changeset status --since=origin/main   # what CI checks; run this to verify

.prettierignore

@@ -27,3 +27,5 @@ renovate.json5
 # Frozen snapshots of TypeDoc-generated MDX; must match raw `extract-methods.mjs` output.
 .typedoc/__tests__/__snapshots__/
 CLAUDE.md
+# Written by `eslint --suppress-rule` / `--prune-suppressions`; ESLint owns the formatting.
+/**/eslint-suppressions.json

eslint.config.mjs

@@ -9,6 +9,7 @@ import pluginReact from 'eslint-plugin-react';
 import pluginReactHooks from 'eslint-plugin-react-hooks';
 import pluginStylex from '@stylexjs/eslint-plugin';
 import pluginSimpleImportSort from 'eslint-plugin-simple-import-sort';
+import pluginSonarjs from 'eslint-plugin-sonarjs';
 import pluginTurbo from 'eslint-plugin-turbo';
 import pluginUnusedImports from 'eslint-plugin-unused-imports';
 import pluginYml from 'eslint-plugin-yml';
@@ -330,6 +331,7 @@ export default tseslint.config([
         },
       },
       'simple-import-sort': pluginSimpleImportSort,
+      sonarjs: pluginSonarjs,
       'unused-imports': pluginUnusedImports,
       turbo: pluginTurbo,
     },
@@ -398,6 +400,7 @@ export default tseslint.config([
       'sort-imports': 'off',
       ...pluginTurbo.configs['flat/recommended'].rules,
       'unused-imports/no-unused-imports': 'error',
+      'sonarjs/cognitive-complexity': ['error', 15],
       // TYPESCRIPT RULE DISABLES
       '@typescript-eslint/no-explicit-any': 'off',
       '@typescript-eslint/no-unsafe-argument': 'off',

package.json

@@ -116,6 +116,7 @@
     "eslint-plugin-react": "7.37.5",
     "eslint-plugin-react-hooks": "5.2.0",
     "eslint-plugin-simple-import-sort": "12.1.1",
+    "eslint-plugin-sonarjs": "4.2.0",
     "eslint-plugin-turbo": "2.5.5",
     "eslint-plugin-unused-imports": "4.4.1",
     "eslint-plugin-yml": "1.18.0",

packages/backend/eslint-suppressions.json

@@ -0,0 +1,22 @@
+{
+  "src/api/request.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/proxy.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/tokens/authenticateContext.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/tokens/request.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 2
+    }
+  }
+}

packages/clerk-js/eslint-suppressions.json

@@ -0,0 +1,52 @@
+{
+  "src/core/clerk.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 7
+    }
+  },
+  "src/core/fapiClient.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/core/fraudProtection.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/core/protect.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/core/protectSession.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/core/resources/Base.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/core/tokenCache.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/utils/billing.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/utils/captcha/turnstile.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/utils/mergePatch.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  }
+}

packages/electron/eslint-suppressions.json

@@ -0,0 +1,12 @@
+{
+  "src/main/create-clerk-bridge.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/storage/index.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  }
+}

packages/eslint-plugin/eslint-suppressions.json

@@ -0,0 +1,27 @@
+{
+  "src/next/fix-auth-protection.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/next/lib/exports.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 3
+    }
+  },
+  "src/next/lib/fixers.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/next/lib/match-folders.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/next/lib/protection-checks.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 2
+    }
+  }
+}

packages/expo/eslint-suppressions.json

@@ -0,0 +1,12 @@
+{
+  "src/hooks/useSignInWithApple.ios.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/provider/nativeClientSync.tsx": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  }
+}

packages/express/eslint-suppressions.json

@@ -0,0 +1,7 @@
+{
+  "src/authenticateRequest.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  }
+}

packages/fastify/eslint-suppressions.json

@@ -0,0 +1,7 @@
+{
+  "src/withClerkMiddleware.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  }
+}

packages/headless/eslint-suppressions.json

@@ -0,0 +1,22 @@
+{
+  "src/primitives/drawer/use-drawer-drag.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/primitives/drawer/use-snap-points.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/primitives/otp/otp-input.tsx": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/utils/use-render.tsx": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  }
+}

packages/hono/eslint-suppressions.json

@@ -0,0 +1,7 @@
+{
+  "src/clerkMiddleware.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  }
+}

packages/react/eslint-suppressions.json

@@ -0,0 +1,12 @@
+{
+  "src/isomorphicClerk.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/utils/useCustomMenuItems.tsx": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  }
+}

packages/shared/eslint-suppressions.json

@@ -0,0 +1,32 @@
+{
+  "src/authorization.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 3
+    }
+  },
+  "src/internal/clerk-js/completeSignUpFlow.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/internal/clerk-js/url.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/internal/clerk-js/web3.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/keys.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/loadClerkJsScript.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  }
+}

packages/testing/eslint-suppressions.json

@@ -0,0 +1,12 @@
+{
+  "src/common/helpers-utils.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  },
+  "src/playwright/setupClerkTestingToken.ts": {
+    "sonarjs/cognitive-complexity": {
+      "count": 1
+    }
+  }
+}