chore(repo): gate cognitive complexity with bulk suppressions by alexcarpenter · Pull Request #9749 · clerk/javascript

alexcarpenter · 2026-09-14T15:55:56Z

Description

Adds sonarjs/cognitive-complexity as an error at 15 so new functions can't land over the limit.

Cognitive over ESLint's complexity: cyclomatic counts every ??, ?., &&, and default param as a branch, so a component merging props from context scores like a 60-line state machine. Cognitive scores a fallback chain as one and penalizes nesting instead, so it flags functions that are genuinely hard to follow rather than ones that are just wide.

Existing violations (92 functions, 15 packages) are grandfathered via ESLint bulk suppressions in each package's eslint-suppressions.json. No inline disables, no refactoring required to land this. Fixing one leaves a stale entry that fails lint until pruned, so the baseline only shrinks.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

changeset-bot · 2026-09-14T15:56:01Z

🦋 Changeset detected

Latest commit: 007419a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-09-14T15:56:03Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 14, 2026 7:15pm UTC
swingset	Ready	Preview	Sep 14, 2026 7:15pm UTC

coderabbitai · 2026-09-14T15:56:06Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Team

Run ID: c5a33403-05e8-41b1-8a77-8806b0957e7a

📥 Commits

Reviewing files that changed from the base of the PR and between 9801ed5 and 007419a.

⛔ Files ignored due to path filters (1)

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (20)

.changeset/complexity-lint-warning.md
.claude/skills/clerk-monorepo/SKILL.md
.prettierignore
eslint.config.mjs
package.json
packages/backend/eslint-suppressions.json
packages/clerk-js/eslint-suppressions.json
packages/electron/eslint-suppressions.json
packages/eslint-plugin/eslint-suppressions.json
packages/expo/eslint-suppressions.json
packages/express/eslint-suppressions.json
packages/fastify/eslint-suppressions.json
packages/headless/eslint-suppressions.json
packages/hono/eslint-suppressions.json
packages/react/eslint-suppressions.json
packages/shared/eslint-suppressions.json
packages/testing/eslint-suppressions.json
packages/ui/eslint-suppressions.json
packages/upgrade/eslint-suppressions.json
packages/vue/eslint-suppressions.json

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)

Included review availability: 3 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

📝 Walkthrough

Walkthrough

The repository now includes eslint-plugin-sonarjs and enables sonarjs/cognitive-complexity as an error above 15. Package-level suppression files record existing findings across multiple packages. Documentation describes suppression maintenance, and Prettier ignores these files. A changeset file containing two horizontal rules was also added.

Area	Change
ESLint	Added and enabled the SonarJS cognitive-complexity rule.
Suppressions	Added package-level suppression configurations.
Tooling	Updated documentation and Prettier exclusions.
Changeset	Added a file with two horizontal rules.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: dstaley

Merge Risk: ⚪ Minimal · up to 00741

The PR enables cognitive-complexity enforcement while preserving existing violations through suppressions, with no identified merge-blocking risk.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: enforcing cognitive complexity with bulk suppressions.
Description check	✅ Passed	The description directly explains the cognitive-complexity rule, threshold, existing suppressions, and maintenance requirements described by the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

Create stacked PR
Commit on current branch

Warning

Linked repositories: Your configuration references 7 linked repositories, but your current plan allows 5. Analyzed clerk/clerk_go, clerk/dashboard, clerk/accounts, clerk/backoffice, clerk/clerk, skipped clerk/clerk-docs, clerk/cloudflare-workers.

_{Comment @coderabbitai help to get the list of available commands.}

pkg-pr-new · 2026-09-14T15:59:03Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9749

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9749

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9749

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9749

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9749

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9749

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9749

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9749

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9749

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9749

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9749

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9749

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9749

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9749

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9749

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9749

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9749

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9749

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9749

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9749

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9749

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9749

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9749

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9749

commit: 007419a

dstaley · 2026-09-14T18:53:13Z

 - Use `pnpm` only. `npm` and `yarn` are blocked by `preinstall`. Node `>=24.15`, pnpm `>=10.33`.
 - Every PR needs a changeset. `pnpm changeset` for package changes, `pnpm changeset:empty` for tooling/repo-only. Empty changesets are two `---` delimiters with no body. A changeset is a changelog entry for users upgrading the package, not a summary of the work done in the PR. Describe the user-facing change (what changed for someone consuming the library and how it affects them) rather than the implementation details of the diff. If a change has no user-facing impact, use an empty changeset.
 - PR descriptions follow `.github/PULL_REQUEST_TEMPLATE.md` and add no sections of their own. Never add a "Testing" (or "Test plan" / "How to test") section summarizing the tests written or the checks run; the Checklist covers that and reviewers read the diff. Describe the change, not the work done on it.
+- Keep functions under a cognitive complexity of 15 (`sonarjs/cognitive-complexity`, reported as an error). Pre-existing violations are grandfathered in each package's `eslint-suppressions.json`. A change that pushes a function past the limit must split it; do not add new suppressions or `eslint-disable` comments for this rule. When a grandfathered function is simplified, run `pnpm eslint src --prune-suppressions` in that package and commit the result.


lets try without this rule. I think the agent would likely do the right thing.

👍🏼 007419a

github-actions · 2026-09-14T19:17:08Z

API Changes Report

Generated by Break Check on 2026-09-14T19:17:06.080Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

Report generated by Break Check

_{Last ran on 007419a.}

chore(repo): report cyclomatic complexity as an ESLint warning

9a839d3

vercel Bot deployed to Preview – clerk-js-sandbox September 14, 2026 15:56 View deployment

vercel Bot deployed to Preview – swingset September 14, 2026 15:58 View deployment

chore(repo): enforce cyclomatic complexity with bulk suppressions

b06a0cb

alexcarpenter changed the title ~~chore(repo): report cyclomatic complexity as an ESLint warning~~ chore(repo): enforce cyclomatic complexity with bulk suppressions Sep 14, 2026

github-actions Bot added clerk-js nextjs backend expo express testing tanstack react-router ui eslint-plugin labels Sep 14, 2026

vercel Bot deployed to Preview – clerk-js-sandbox September 14, 2026 16:25 View deployment

vercel Bot deployed to Preview – swingset September 14, 2026 16:28 View deployment

alexcarpenter mentioned this pull request Sep 14, 2026

refactor(ui): bring Mosaic Button and Input under the complexity limit #9751

Closed

9 tasks

chore(repo): switch the complexity gate to cognitive complexity

78433f8

alexcarpenter changed the title ~~chore(repo): enforce cyclomatic complexity with bulk suppressions~~ chore(repo): gate cognitive complexity with bulk suppressions Sep 14, 2026

github-actions Bot added react fastify vue labels Sep 14, 2026

vercel Bot deployed to Preview – clerk-js-sandbox September 14, 2026 18:27 View deployment

vercel Bot deployed to Preview – swingset September 14, 2026 18:29 View deployment

dstaley reviewed Sep 14, 2026

View reviewed changes

chore(repo): drop the complexity rule from AGENTS.md

007419a

alexcarpenter marked this pull request as ready for review September 14, 2026 19:12

vercel Bot deployed to Preview – clerk-js-sandbox September 14, 2026 19:12 View deployment

vercel Bot deployed to Preview – swingset September 14, 2026 19:15 View deployment

Navigation Menu

Uh oh!

chore(repo): gate cognitive complexity with bulk suppressions - #9749

chore(repo): gate cognitive complexity with bulk suppressions#9749
alexcarpenter wants to merge 4 commits into
mainfrom
chore/complexity-lint-warning

alexcarpenter commented Sep 14, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Sep 14, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 14, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 14, 2026 •

edited

Loading

Walkthrough

Uh oh!

pkg-pr-new Bot commented Sep 14, 2026 •

edited

Loading

Uh oh!

dstaley Sep 14, 2026

Uh oh!

alexcarpenter Sep 14, 2026

Uh oh!

github-actions Bot commented Sep 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

alexcarpenter commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

changeset-bot Bot commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

pkg-pr-new Bot commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dstaley Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

alexcarpenter Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Sep 14, 2026

API Changes Report

Summary

No API Changes Detected

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alexcarpenter commented Sep 14, 2026 •

edited

Loading

changeset-bot Bot commented Sep 14, 2026 •

edited

Loading

vercel Bot commented Sep 14, 2026 •

edited

Loading

coderabbitai Bot commented Sep 14, 2026 •

edited

Loading

pkg-pr-new Bot commented Sep 14, 2026 •

edited

Loading