fix(nextjs): ignore response header mutations in GET handlers

[aqilaziz]

Summary

• ignore outbound response header mutations like response.headers.set() in GET route side-effect detection
• ignore request-scoped Headers/Map mutations created inside the handler
• add regression coverage for issue False positive: nextjs-no-side-effect-in-get-handler flags Response.headers.set() and similar Headers API calls #206 using a temporary Next.js route fixture

Fixes #206.

Testing

• pnpm exec vp test run tests/regressions/nextjs-side-effects.test.ts
• pnpm exec tsc --noEmit from packages/react-doctor
• pnpm exec vp lint
• git diff --check

---

Note

Low Risk
Low risk: changes are limited to lint-side-effect heuristics and test fixtures, primarily reducing false positives without affecting runtime behavior.

Overview
Refines nextjs-no-side-effect-in-get-handler detection by teaching findSideEffect to ignore outbound response header shaping (e.g. response.headers.set/append/delete and headers().* mutations) and ignore mutations on request-scoped collections (new Headers/Map/Set created within the handler).

Adds a Next.js route fixture and a regression test ensuring these patterns no longer produce diagnostics, and includes a patch changeset for react-doctor.

^{Reviewed by Cursor Bugbot for commit bcde713. Bugbot is set up for automated code reviews on this repo. Configure here.}

[reactreview]

Note

No issues found

[vercel]

@aqilaziz is attempting to deploy a commit to the Million Team on Vercel.

A member of the Team first needs to authorize it.

[cursor]

Shared findSideEffect suppresses headers() detection across frameworks

Medium Severity

isHeadersFunctionMutationCall matches headers().set/append/delete(...) and silently suppresses it before the existing isCookiesOrHeadersCall(child, "headers") check can flag it. Since findSideEffect is shared with the TanStack Start rule (tanstack-start.ts line 562), this suppression also applies there — where headers() is not the Next.js read-only accessor and could be a user-defined function returning a mutable object. The headers() branch of isCookiesOrHeadersCall is now effectively dead code for all real Headers API methods. The function also has zero test coverage — the test fixture only exercises isHeadersApiMutationCall and isRequestScopedMutationCall.

Additional Locations (2)

• packages/react-doctor/src/plugin/helpers.ts#L425-L428
• packages/react-doctor/src/plugin/helpers.ts#L434-L437

 

^{Reviewed by Cursor Bugbot for commit 1ed2336. Configure here.}

[aqilaziz]

Rebased/rebuilt this PR onto current main after the monorepo refactor, so GitHub now reports it as mergeable.

What changed in the updated branch:

• moved the fix to the new oxlint-plugin-react-doctor rule utility location
• kept the same behavior: ignore response header shaping (response.headers.set/append/delete) and request-scoped Headers/Map/Set mutations in GET handlers
• added a Next.js fixture route and regression assertion for the headers case

Verification:

• pnpm -C packages/oxlint-plugin-react-doctor typecheck
• built the internal packages on Windows using PowerShell env syntax for NODE_ENV
• direct runOxlint check against the new app/headers/route.tsx fixture returns no nextjs-no-side-effect-in-get-handler diagnostics

Note: pnpm -C packages/react-doctor test -- tests/run-oxlint/nextjs.test.ts currently still has unrelated baseline failures on current main in this checkout, including existing Next.js rule expectations. Vercel is also blocked by team authorization as before.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 3 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bcde713. Configure here.}

[cursor]

isHeadersFunctionMutationCall silently suppresses Next.js headers() side-effect detection

High Severity

isHeadersFunctionMutationCall matches the exact same AST pattern as isCookiesOrHeadersCall(child, "headers") for methods set, append, and delete. Both detect headers().set(...) where headers is a direct function call — which is the Next.js headers() API from next/headers. Because the new skip on line 121 runs before the existing side-effect detection on lines 128–131, calls like headers().set() in GET handlers are now silently ignored instead of being flagged as side effects. The PR intended to suppress only response header mutations (response.headers.set()), not the Next.js request-headers API.

Additional Locations (1)

• packages/oxlint-plugin-react-doctor/src/plugin/utils/find-side-effect.ts#L120-L121

 

^{Reviewed by Cursor Bugbot for commit bcde713. Configure here.}

[cursor]

Scope-blind binding collection causes false suppression across scopes

Low Severity

collectRequestScopedMutationBindings uses walkAst to recurse into the entire handler body — including nested functions and callbacks — collecting binding names into a flat Set without any scope information. If a nested function declares const store = new Map(), the name "store" is added globally. Then isRequestScopedMutationCall will incorrectly suppress an outer-scope store.set(...) where store refers to a completely different binding (e.g., an external KV store), causing a real side effect to go undetected.

Additional Locations (1)

• packages/oxlint-plugin-react-doctor/src/plugin/utils/find-side-effect.ts#L51-L62

 

^{Reviewed by Cursor Bugbot for commit bcde713. Configure here.}