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

Author: aqilaziz

.changeset/quiet-headers-scope.md

@@ -0,0 +1,5 @@
+---
+"react-doctor": patch
+---
+
+Avoid reporting response header mutations and request-scoped collections as GET handler side effects.

packages/react-doctor/src/plugin/constants.ts

@@ -362,6 +362,10 @@ export const MUTATION_METHOD_NAMES = new Set([
   "append",
 ]);
 
+export const HEADERS_API_MUTATION_METHOD_NAMES = new Set(["append", "delete", "set"]);
+
+export const REQUEST_SCOPED_MUTATION_CONSTRUCTOR_NAMES = new Set(["Headers", "Map", "Set"]);
+
 // In-place Array.prototype mutators. These are the canonical "mutating"
 // methods used to flag direct mutation of useState values (e.g. an
 // `items` from `useState([])` that gets `.push()`ed). The immutable

packages/react-doctor/src/plugin/helpers.ts

@@ -1,9 +1,11 @@
 import {
   FETCH_CALLEE_NAMES,
   FETCH_MEMBER_OBJECTS,
+  HEADERS_API_MUTATION_METHOD_NAMES,
   LOOP_TYPES,
   MUTATING_HTTP_METHODS,
   MUTATION_METHOD_NAMES,
+  REQUEST_SCOPED_MUTATION_CONSTRUCTOR_NAMES,
   SETTER_PATTERN,
   UPPERCASE_PATTERN,
 } from "./constants.js";
@@ -333,6 +335,61 @@ const isCookiesOrHeadersCall = (node: EsTreeNode, methodName: string): boolean =
   return object.callee.name === methodName;
 };
 
+const isRequestScopedMutationInitializer = (node: EsTreeNode): boolean =>
+  node.type === "NewExpression" &&
+  node.callee?.type === "Identifier" &&
+  REQUEST_SCOPED_MUTATION_CONSTRUCTOR_NAMES.has(node.callee.name);
+
+const collectRequestScopedMutationBindings = (node: EsTreeNode): Set<string> => {
+  const bindings = new Set<string>();
+  walkAst(node, (child: EsTreeNode) => {
+    if (child.type !== "VariableDeclarator") return;
+    if (child.id?.type !== "Identifier") return;
+    if (!child.init || !isRequestScopedMutationInitializer(child.init)) return;
+    bindings.add(child.id.name);
+  });
+  return bindings;
+};
+
+const isRequestScopedMutationCall = (
+  node: EsTreeNode,
+  requestScopedMutationBindings: Set<string>,
+): boolean => {
+  if (node.type !== "CallExpression" || node.callee?.type !== "MemberExpression") return false;
+  const { object, property } = node.callee;
+  if (object?.type !== "Identifier") return false;
+  if (property?.type !== "Identifier") return false;
+  return (
+    requestScopedMutationBindings.has(object.name) && MUTATION_METHOD_NAMES.has(property.name)
+  );
+};
+
+const isHeadersApiMutationCall = (node: EsTreeNode): boolean => {
+  if (node.type !== "CallExpression" || node.callee?.type !== "MemberExpression") return false;
+  const { object, property } = node.callee;
+  if (
+    property?.type !== "Identifier" ||
+    !HEADERS_API_MUTATION_METHOD_NAMES.has(property.name)
+  ) {
+    return false;
+  }
+  if (object?.type !== "MemberExpression") return false;
+  return object.property?.type === "Identifier" && object.property.name === "headers";
+};
+
+const isHeadersFunctionMutationCall = (node: EsTreeNode): boolean => {
+  if (node.type !== "CallExpression" || node.callee?.type !== "MemberExpression") return false;
+  const { object, property } = node.callee;
+  if (
+    property?.type !== "Identifier" ||
+    !HEADERS_API_MUTATION_METHOD_NAMES.has(property.name)
+  ) {
+    return false;
+  }
+  if (object?.type !== "CallExpression" || object.callee?.type !== "Identifier") return false;
+  return object.callee.name === "headers";
+};
+
 const isMutatingDbCall = (node: EsTreeNode): boolean => {
   if (node.type !== "CallExpression" || node.callee?.type !== "MemberExpression") return false;
   const { property } = node.callee;
@@ -363,8 +420,15 @@ const isMutatingFetchCall = (node: EsTreeNode): boolean => {
 
 export const findSideEffect = (node: EsTreeNode): string | null => {
   let sideEffectDescription: string | null = null;
+  const requestScopedMutationBindings = collectRequestScopedMutationBindings(node);
   walkAst(node, (child: EsTreeNode) => {
     if (sideEffectDescription) return;
+    if (isHeadersApiMutationCall(child) || isHeadersFunctionMutationCall(child)) {
+      return;
+    }
+    if (isRequestScopedMutationCall(child, requestScopedMutationBindings)) {
+      return;
+    }
     if (isCookiesOrHeadersCall(child, "cookies")) {
       const methodName = child.callee.property.name;
       sideEffectDescription = `cookies().${methodName}()`;

packages/react-doctor/tests/regressions/nextjs-side-effects.test.ts

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, describe, expect, it } from "vite-plus/test";
+
+import { runOxlint } from "../../src/utils/run-oxlint.js";
+import { setupReactProject } from "./_helpers.js";
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "rd-nextjs-side-effects-"));
+
+afterAll(() => {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+describe("issue #206: nextjs-no-side-effect-in-get-handler avoids request-local mutations", () => {
+  it("does not flag response header shaping in GET route handlers", async () => {
+    const projectDir = setupReactProject(tempRoot, "issue-206-headers", {
+      packageJsonExtras: {
+        dependencies: { next: "^15.0.0", react: "^19.0.0", "react-dom": "^19.0.0" },
+      },
+      files: {
+        "src/app/headers/route.tsx": `import { NextResponse } from "next/server";
+
+export async function GET() {
+  const response = NextResponse.json({ ok: true });
+  response.headers.set("Cache-Control", "no-store");
+  response.headers.append("Vary", "Accept");
+  response.headers.delete("X-Deprecated");
+
+  const headers = new Headers();
+  headers.set("X-Route", "headers");
+
+  const requestScope = new Map<string, string>();
+  requestScope.set("seen", "true");
+
+  return response;
+}
+`,
+      },
+    });
+
+    const diagnostics = await runOxlint({
+      rootDirectory: projectDir,
+      hasTypeScript: true,
+      framework: "nextjs",
+      hasReactCompiler: false,
+      hasTanStackQuery: false,
+    });
+
+    const headerRouteIssues = diagnostics.filter(
+      (diagnostic) =>
+        diagnostic.rule === "nextjs-no-side-effect-in-get-handler" &&
+        diagnostic.filePath.includes("app/headers/route"),
+    );
+    expect(headerRouteIssues).toHaveLength(0);
+  });
+});

packages/react-doctor/tests/run-oxlint.test.ts

@@ -245,6 +245,7 @@ describe("runOxlint", () => {
       );
       expect(wrappedPageIssues).toHaveLength(0);
     });
+
   });
 
   describe("server rule scope", () => {