feat: add react-x/no-misused-capture-owner-stack rule, closes #1049 (#1047)

Rel1cx · web-flow · commit 68b38a537c59 · 2025-04-11T12:16:51.000+08:00
diff --git a/apps/website/content/docs/rules/meta.json b/apps/website/content/docs/rules/meta.json
@@ -32,6 +32,7 @@
     "no-missing-component-display-name",
     "no-missing-context-display-name",
     "no-missing-key",
+    "no-misused-capture-owner-stack",
     "no-nested-component-definitions",
     "no-prop-types",
     "no-redundant-should-component-update",
diff --git a/apps/website/content/docs/rules/overview.mdx b/apps/website/content/docs/rules/overview.mdx
@@ -55,6 +55,7 @@ Linter rules can have false positives, false negatives, and some rules are depen
 | [`no-missing-component-display-name`](./no-missing-component-display-name)           | 0️⃣  |          | Enforces that all components have a `displayName` which can be used in devtools                      |           |
 | [`no-missing-context-display-name`](./no-missing-context-display-name)               | 0️⃣  |          | Enforces that all contexts have a `displayName` which can be used in devtools                        |           |
 | [`no-missing-key`](./no-missing-key)                                                 | 2️⃣  |          | Disallow missing `key` on items in list rendering                                                    |           |
+| [`no-misused-capture-owner-stack`](./no-misused-capture-owner-stack)                 | 2️⃣  |          | Prevents incorrect usage of `captureOwnerStack`                                                      |           |
 | [`no-nested-component-definitions`](./no-nested-component-definitions)               | 2️⃣  |          | Disallow nesting component definitions inside other components                                       |           |
 | [`no-prop-types`](./no-prop-types)                                                   | 2️⃣  |          | Disallow `propTypes` in favor of TypeScript or another type-checking solution                        |           |
 | [`no-redundant-should-component-update`](./no-redundant-should-component-update)     | 2️⃣  |          | Disallow `shouldComponentUpdate` when extending `React.PureComponent`                                |           |
diff --git a/apps/website/source.config.ts b/apps/website/source.config.ts
@@ -26,9 +26,9 @@ export default defineConfig({
       ],
     },
     remarkPlugins: [
-      remarkMermaid,
-      remarkInstall,
       [remarkDocGen, { generators: [] }],
+      remarkInstall,
+      remarkMermaid,
     ],
   },
 });
diff --git a/packages/core/docs/README.md b/packages/core/docs/README.md
@@ -37,6 +37,8 @@
 - [ComponentFlag](variables/ComponentFlag.md)
 - [ComponentPhaseRelevance](variables/ComponentPhaseRelevance.md)
 - [DEFAULT\_COMPONENT\_DETECTION\_HINT](variables/DEFAULT_COMPONENT_DETECTION_HINT.md)
+- [isCaptureOwnerStack](variables/isCaptureOwnerStack.md)
+- [isCaptureOwnerStackCall](variables/isCaptureOwnerStackCall.md)
 - [isChildrenCount](variables/isChildrenCount.md)
 - [isChildrenCountCall](variables/isChildrenCountCall.md)
 - [isChildrenForEach](variables/isChildrenForEach.md)
diff --git a/packages/core/docs/variables/isCaptureOwnerStack.md b/packages/core/docs/variables/isCaptureOwnerStack.md
@@ -0,0 +1,9 @@
+[**@eslint-react/core**](../README.md)
+
+***
+
+[@eslint-react/core](../README.md) / isCaptureOwnerStack
+
+# Variable: isCaptureOwnerStack
+
+> `const` **isCaptureOwnerStack**: `ReturnType`
diff --git a/packages/core/docs/variables/isCaptureOwnerStackCall.md b/packages/core/docs/variables/isCaptureOwnerStackCall.md
@@ -0,0 +1,9 @@
+[**@eslint-react/core**](../README.md)
+
+***
+
+[@eslint-react/core](../README.md) / isCaptureOwnerStackCall
+
+# Variable: isCaptureOwnerStackCall
+
+> `const` **isCaptureOwnerStackCall**: `ReturnType`
diff --git a/packages/core/src/utils/is-react-api.ts b/packages/core/src/utils/is-react-api.ts
@@ -20,6 +20,7 @@ export function isReactAPICall(arg0: string, arg1?: string) {
     : isCallFromReactObject(arg0, arg1);
 }
 
+export const isCaptureOwnerStack = isReactAPI("captureOwnerStack");
 export const isChildrenCount = isReactAPI("Children", "count");
 export const isChildrenForEach = isReactAPI("Children", "forEach");
 export const isChildrenMap = isReactAPI("Children", "map");
@@ -32,6 +33,7 @@ export const isCreateRef = isReactAPI("createRef");
 export const isForwardRef = isReactAPI("forwardRef");
 export const isMemo = isReactAPI("memo");
 
+export const isCaptureOwnerStackCall = isReactAPICall("captureOwnerStack");
 export const isChildrenCountCall = isReactAPICall("Children", "count");
 export const isChildrenForEachCall = isReactAPICall("Children", "forEach");
 export const isChildrenMapCall = isReactAPICall("Children", "map");
diff --git a/packages/plugins/eslint-plugin-react-x/src/configs/recommended.ts b/packages/plugins/eslint-plugin-react-x/src/configs/recommended.ts
@@ -27,6 +27,7 @@ export const rules = {
   "react-x/no-forward-ref": "warn",
   "react-x/no-implicit-key": "warn",
   "react-x/no-missing-key": "error",
+  "react-x/no-misused-capture-owner-stack": "error",
   "react-x/no-nested-component-definitions": "error",
   "react-x/no-prop-types": "error",
   "react-x/no-redundant-should-component-update": "error",
diff --git a/packages/plugins/eslint-plugin-react-x/src/plugin.ts b/packages/plugins/eslint-plugin-react-x/src/plugin.ts
@@ -31,6 +31,7 @@ import noLeakedConditionalRendering from "./rules/no-leaked-conditional-renderin
 import noMissingComponentDisplayName from "./rules/no-missing-component-display-name";
 import noMissingContextDisplayName from "./rules/no-missing-context-display-name";
 import noMissingKey from "./rules/no-missing-key";
+import noMisusedCaptureOwnerStack from "./rules/no-misused-capture-owner-stack";
 import noNestedComponentDefinitions from "./rules/no-nested-component-definitions";
 import noPropTypes from "./rules/no-prop-types";
 import noRedundantShouldComponentUpdate from "./rules/no-redundant-should-component-update";
@@ -88,6 +89,7 @@ export const plugin = {
     "no-missing-component-display-name": noMissingComponentDisplayName,
     "no-missing-context-display-name": noMissingContextDisplayName,
     "no-missing-key": noMissingKey,
+    "no-misused-capture-owner-stack": noMisusedCaptureOwnerStack,
     "no-nested-component-definitions": noNestedComponentDefinitions,
     "no-prop-types": noPropTypes,
     "no-redundant-should-component-update": noRedundantShouldComponentUpdate,
diff --git a/packages/plugins/eslint-plugin-react-x/src/rules/no-misused-capture-owner-stack.md b/packages/plugins/eslint-plugin-react-x/src/rules/no-misused-capture-owner-stack.md
@@ -0,0 +1,74 @@
+---
+title: no-misused-capture-owner-stack
+---
+
+**Full Name in `eslint-plugin-react-x@beta`**
+
+```plain copy
+react-x/no-misused-capture-owner-stack
+```
+
+**Full Name in `@eslint-react/eslint-plugin@beta`**
+
+```plain copy
+@eslint-react/no-misused-capture-owner-stack
+```
+
+## Description
+
+Prevents incorrect usage of `captureOwnerStack`.
+
+The `captureOwnerStack` is only available in development builds of React and must be:
+
+1. Imported via namespace to avoid direct named imports.
+2. Conditionally accessed within an `if (process.env.NODE_ENV !== 'production') {...}` block to prevent execution in production environments.
+3. The call of `captureOwnerStack` happened inside of a React controlled function (**not implemented yet**).
+
+## Examples
+
+### Failing
+
+```tsx
+// Failing: Using named import directly
+import { captureOwnerStack } from "react";
+//       ^^^^^^^^^^^^^^^^^
+//       - Don't use named imports of `captureOwnerStack` in files that are bundled for development and production. Use a namespace import instead.
+
+if (process.env.NODE_ENV !== "production") {
+  const ownerStack = React.captureOwnerStack();
+  console.log("Owner Stack", ownerStack);
+}
+```
+
+```tsx
+// Failing: Missing environment check
+import * as React from "react";
+
+const ownerStack = React.captureOwnerStack();
+//                 ^^^^^^^^^^^^^^^^^^^^^^^^^
+//                 - `captureOwnerStack` should only be used in development builds. Use an environment check to ensure it is not executed in production.
+console.log(ownerStack);
+```
+
+### Passing
+
+```tsx
+// Passing: Correct namespace import with environment check
+import * as React from "react";
+
+if (process.env.NODE_ENV !== "production") {
+  const ownerStack = React.captureOwnerStack();
+  console.log("Owner Stack", ownerStack);
+}
+```
+
+## Implementation
+
+- [Rule source](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x/src/rules/no-misused-capture-owner-stack.ts)
+- [Test source](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x/src/rules/no-misused-capture-owner-stack.spec.ts)
+
+## Further Reading
+
+- [React: APIs `captureOwnerStack`](https://react.dev/reference/react/captureOwnerStack)
+  - [The Owner Stack is `null`](https://react.dev/reference/react/captureOwnerStack#the-owner-stack-is-null)
+  - [`captureOwnerStack` is not available](https://react.dev/reference/react/captureOwnerStack#captureownerstack-is-not-available)
diff --git a/packages/plugins/eslint-plugin-react-x/src/rules/no-misused-capture-owner-stack.spec.ts b/packages/plugins/eslint-plugin-react-x/src/rules/no-misused-capture-owner-stack.spec.ts
@@ -0,0 +1,120 @@
+import { AST_NODE_TYPES as T } from "@typescript-eslint/types";
+import tsx from "dedent";
+
+import { ruleTester } from "../../../../../test";
+import rule, { RULE_NAME } from "./no-misused-capture-owner-stack";
+
+ruleTester.run(RULE_NAME, rule, {
+  invalid: [
+    {
+      code: `import { captureOwnerStack } from 'react';`,
+      errors: [
+        {
+          type: T.ImportSpecifier,
+          messageId: "useNamespaceImport",
+        },
+      ],
+    },
+    {
+      code: `import { captureOwnerStack } from "react";`,
+      errors: [
+        {
+          type: T.ImportSpecifier,
+          messageId: "useNamespaceImport",
+        },
+      ],
+    },
+    {
+      code: tsx`
+        // Failing: Using named import directly
+        import { captureOwnerStack } from "react";
+
+        if (process.env.NODE_ENV !== "production") {
+          const ownerStack = React.captureOwnerStack();
+          console.log("Owner Stack", ownerStack);
+        }
+      `,
+      errors: [
+        {
+          type: T.ImportSpecifier,
+          messageId: "useNamespaceImport",
+        },
+      ],
+    },
+    {
+      code: tsx`
+        // Failing: Missing environment check
+        import * as React from "react";
+
+        const ownerStack = React.captureOwnerStack();
+
+        console.log("Owner Stack", ownerStack);
+      `,
+      errors: [
+        {
+          type: T.CallExpression,
+          messageId: "missingDevelopmentOnlyCheck",
+        },
+      ],
+    },
+    {
+      code: tsx`
+        // Failing: Using named import directly without environment check
+        import { captureOwnerStack } from "react";
+
+        const ownerStack = React.captureOwnerStack();
+
+        console.log("Owner Stack", ownerStack);
+      `,
+      errors: [
+        {
+          type: T.ImportSpecifier,
+          messageId: "useNamespaceImport",
+        },
+        {
+          type: T.CallExpression,
+          messageId: "missingDevelopmentOnlyCheck",
+        },
+      ],
+    },
+  ],
+  valid: [
+    {
+      code: `import * as React from 'react';`,
+    },
+    {
+      code: `import {useState} from 'react';`,
+    },
+    {
+      code: `import {} from 'react';`,
+    },
+    {
+      code: `import * as React from "react";`,
+    },
+    {
+      code: `import {useState} from "react";`,
+    },
+    {
+      code: `import {} from "react";`,
+    },
+    {
+      code: tsx`
+        // Passing: Correct namespace import with environment check
+        import * as React from "react";
+
+        if (process.env.NODE_ENV !== "production") {
+          const ownerStack = React.captureOwnerStack();
+          console.log("Owner Stack", ownerStack);
+        }
+      `,
+    },
+    {
+      code: `import * as React from "@pika/react";`,
+      settings: {
+        "react-x": {
+          importSource: "@pika/react",
+        },
+      },
+    },
+  ],
+});
diff --git a/packages/plugins/eslint-plugin-react-x/src/rules/no-misused-capture-owner-stack.ts b/packages/plugins/eslint-plugin-react-x/src/rules/no-misused-capture-owner-stack.ts
@@ -0,0 +1,77 @@
+import type { RuleListener } from "@typescript-eslint/utils/ts-eslint";
+import * as AST from "@eslint-react/ast";
+import * as ER from "@eslint-react/core";
+import { type RuleContext, type RuleFeature } from "@eslint-react/kit";
+import { getSettingsFromContext } from "@eslint-react/shared";
+import { AST_NODE_TYPES as T, type TSESTree } from "@typescript-eslint/types";
+
+import { createRule } from "../utils";
+
+export const RULE_NAME = "no-misused-capture-owner-stack";
+
+export const RULE_FEATURES = [] as const satisfies RuleFeature[];
+
+export type MessageID =
+  | "useNamespaceImport"
+  | "missingDevelopmentOnlyCheck";
+
+export default createRule<[], MessageID>({
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Prevents incorrect usage of `captureOwnerStack`.",
+      [Symbol.for("rule_features")]: RULE_FEATURES,
+    },
+    fixable: "code",
+    messages: {
+      useNamespaceImport:
+        "Don't use named imports of 'captureOwnerStack' in files that are bundled for development and production. Use a namespace import instead.",
+      // eslint-disable-next-line perfectionist/sort-objects
+      missingDevelopmentOnlyCheck:
+        `Don't call 'captureOwnerStack' directly. Use 'if (process.env.NODE_ENV !== "production") {...}' to conditionally access it.`,
+    },
+    schema: [],
+  },
+  name: RULE_NAME,
+  create,
+  defaultOptions: [],
+});
+
+export function create(context: RuleContext<MessageID, []>): RuleListener {
+  if (!context.sourceCode.text.includes("captureOwnerStack")) return {};
+  const { importSource } = getSettingsFromContext(context);
+
+  return {
+    CallExpression(node) {
+      if (!ER.isCaptureOwnerStackCall(context, node)) return;
+      if (AST.findParentNode(node, isDevelopmentOnlyCheck) == null) {
+        context.report({
+          messageId: "missingDevelopmentOnlyCheck",
+          node,
+        });
+      }
+    },
+    ImportDeclaration(node) {
+      if (node.source.value !== importSource) return;
+      for (const specifier of node.specifiers) {
+        if (specifier.type !== T.ImportSpecifier) continue;
+        if (specifier.imported.type !== T.Identifier) continue;
+        if (specifier.imported.name === "captureOwnerStack") {
+          context.report({
+            messageId: "useNamespaceImport",
+            node: specifier,
+          });
+        }
+      }
+    },
+  };
+}
+
+function isDevelopmentOnlyCheck(node: TSESTree.Node) {
+  if (node.type !== T.IfStatement) return false;
+  if (AST.isProcessEnvNodeEnvCompare(node.test, "!==", "production")) return true;
+  // if (AST.isProcessEnvNodeEnvCompare(node.test, "===", "development")) return true;
+  // if (AST.isProcessEnvNodeEnvCompare(node.test, "!=", "production")) return true;
+  // if (AST.isProcessEnvNodeEnvCompare(node.test, "==", "development")) return true;
+  return false;
+}
diff --git a/packages/plugins/eslint-plugin/src/configs/x.ts b/packages/plugins/eslint-plugin/src/configs/x.ts
@@ -28,6 +28,7 @@ export const rules = {
   "@eslint-react/no-forward-ref": "warn",
   "@eslint-react/no-implicit-key": "warn",
   "@eslint-react/no-missing-key": "error",
+  "@eslint-react/no-misused-capture-owner-stack": "error",
   "@eslint-react/no-nested-component-definitions": "error",
   "@eslint-react/no-prop-types": "error",
   "@eslint-react/no-redundant-should-component-update": "error",
diff --git a/packages/utilities/ast/src/index.ts b/packages/utilities/ast/src/index.ts
@@ -18,6 +18,8 @@ export * from "./is-line-break";
 export * from "./is-literal";
 export * from "./is-multi-line";
 export * from "./is-node-equal";
+export * from "./is-process-env-node-env";
+export * from "./is-process-env-node-env-compare";
 export * from "./is-this-expression";
 export * from "./to-readable-node-name";
 export * from "./to-readable-node-type";
diff --git a/packages/utilities/ast/src/is-process-env-node-env-compare.ts b/packages/utilities/ast/src/is-process-env-node-env-compare.ts
diff --git a/packages/utilities/ast/src/is-process-env-node-env.ts b/packages/utilities/ast/src/is-process-env-node-env.ts
