eslint-plugin-react-suspense-check 1.0.0

package/README.ko.md

@@ -0,0 +1,124 @@
+### 🇰🇷 한국어
+
+한국 개발자들을 위한 설명서입니다.
+
+# eslint-plugin-react-suspense-check 🇰🇷
+
+> **React Suspense** 런타임 에러를 네이밍 규칙(Naming Convention)으로 예방하세요.
+
+[🇺🇸 English Docs](./README.md)
+
+## 🧐 왜 필요한가요?
+
+React Suspense는 강력하지만, 데이터 로딩 중인 컴포넌트를 상위 `<Suspense>`로 감싸지 않으면 **앱 전체가 멈추거나 하얀 화면**이 될 수 있습니다.
+
+ESLint는 파일 건너편의 상위 트리에 `<Suspense>`가 있는지 확인할 수 없습니다. 그래서 이 플러그인은 **이름 짓기 규칙**을 강제하여 개발자가 실수를 인지하도록 돕습니다.
+
+1.  **훅(Hook)**: 내부에서 Suspense를 유발(Promise throw)하는 훅은 반드시 **`useSuspense...`** 로 시작해야 합니다.
+2.  **컴포넌트**: 위 훅을 사용하는 컴포넌트는 반드시 **`Suspense...`** 로 시작해야 합니다.
+
+즉, 컴포넌트 이름만 봐도 _"아, 이건 쓸 때 Suspense로 감싸줘야 하는구나!"_ 라고 알 수 있게 만드는 것입니다.
+
+## 📦 설치
+
+```bash
+# npm
+npm install --save-dev eslint-plugin-react-suspense-check
+```
+
+```bash
+# pnpm
+pnpm add -D eslint-plugin-react-suspense-check
+```
+
+```bash
+# yarn
+yarn add -D eslint-plugin-react-suspense-check
+```
+
+### ⚙️ 설정 방법
+
+eslint.config.mjs (또는 .js) 파일에 아래 내용을 추가하세요.
+
+```JavaScript
+
+import suspensePlugin from "eslint-plugin-react-suspense-check";
+
+export default defineConfig([
+  // ... 다른 설정들
+  ...suspensePlugin.configs.recommended,// 추천 설정 적용
+
+ //... 다른 설정들
+]);
+```
+
+or
+
+```JavaScript
+
+import suspensePlugin from "eslint-plugin-react-suspense-check";
+
+export default defineConfig([
+  // ... 다른 설정들
+
+   extends: [
+      suspensePlugin.configs.recommended, // 추천 설정 적용
+   ],
+ //... 다른 설정들
+]);
+```
+
+### 📏 규칙 설명
+
+`Suspense` 를 유발하는 훅과 컴포넌트의 이름을 검사합니다.
+
+❌ 잘못된 예시
+
+```ts
+// 1. 훅 이름 위반
+// Suspense를 유발하는데 일반 훅처럼 이름을 지음
+function useUserData() {
+  throw promise;
+}
+
+// 2. 컴포넌트 이름 위반
+// Suspense 훅을 사용하는데 일반 컴포넌트처럼 이름을 지음
+function UserProfile() {
+  const data = useSuspenseUser(); // <--- ⚠️ 경고: 컴포넌트 이름을 'SuspenseUserProfile'로 변경하세요.
+  return <div>{data.name}</div>;
+}
+```
+
+✅ 올바른 예시
+
+```ts
+// 1. 훅 이름이 'useSuspense'로 시작함
+function useSuspenseUserData() {
+  throw promise;
+}
+
+// 2. 컴포넌트 이름이 'Suspense'로 시작함
+// 호출하는 사람이 <Suspense>가 필요하다는 것을 이름만 보고 알 수 있음.
+function SuspenseUserProfile() {
+  const data = useSuspenseUserData();
+  return <div>{data.name}</div>;
+}
+```
+
+### 🌍 언어 설정 (한글 지원)
+
+에러 메시지를 한국어로 보고 싶다면 옵션을 설정할 수 있습니다. (기본값은 영어)
+
+한국어 설정 예시:
+
+```ts
+// eslint.config.mjs
+export default [
+  {
+    //...
+    rules: {
+      'react-suspense-check/detect-suspense-hook': ['warn', { language: 'kr' }],
+    },
+  },
+];
+```

package/README.md

@@ -0,0 +1,95 @@
+### 🧐 Why is this necessary?
+
+React Suspense is powerful, but failing to wrap a component that is loading data in a parent `<Suspense>` boundary can cause the entire app to freeze or result in a white screen.
+
+ESLint cannot verify if a `<Suspense>` boundary exists in the parent tree across different files. Therefore, this plugin **enforces naming conventions** to help developers recognize potential mistakes.
+
+**Hook**: Hooks that trigger Suspense (throw a Promise) internally must start with useSuspense....
+
+**Component**: Components using the above hooks must start with Suspense....
+
+In short, it ensures that just by looking at the component name, you realize, "Ah, I need to wrap this in Suspense when using it!"
+
+### 📦 Installation
+
+```Bash
+# npm
+npm install --save-dev eslint-plugin-react-suspense-check
+```
+
+```Bash
+# pnpm
+pnpm add -D eslint-plugin-react-suspense-check
+```
+
+```Bash
+# yarn
+yarn add -D eslint-plugin-react-suspense-check
+```
+
+### ⚙️ Configuration
+
+Add the following to your eslint.config.mjs (or .js) file.
+
+```js
+import suspensePlugin from 'eslint-plugin-react-suspense-check';
+
+export default defineConfig([
+  // ... other configs
+  ...suspensePlugin.configs.recommended, // Apply recommended config
+
+  //... other configs
+]);
+```
+
+or
+
+```js
+import suspensePlugin from "eslint-plugin-react-suspense-check";
+
+export default defineConfig([
+  // ... other configs
+
+   extends: [
+      suspensePlugin.configs.recommended, // Apply recommended config
+   ],
+ //... other configs
+]);
+```
+
+### 📏 Rules Description
+
+Checks the names of hooks and components that trigger `Suspense`.
+
+❌ Incorrect Examples
+
+```ts
+// 1. Hook naming violation
+// Triggers Suspense but named like a normal hook
+function useUserData() {
+  throw promise;
+}
+
+// 2. Component naming violation
+// Uses a Suspense hook but named like a normal component
+function UserProfile() {
+  const data = useSuspenseUser(); // <--- ⚠️ Warning: Change component name to 'SuspenseUserProfile'.
+  return <div>{data.name}</div>;
+}
+```
+
+✅ Correct Examples
+
+```ts
+// 1. Hook name starts with 'useSuspense'
+function useSuspenseUserData() {
+  throw promise;
+}
+
+// 2. Component name starts with 'Suspense'
+// The caller can tell just by the name that <Suspense> is required.
+function SuspenseUserProfile() {
+  const data = useSuspenseUserData();
+  return <div>{data.name}</div>;
+}
+```

package/index.js

@@ -0,0 +1,33 @@
+const detectSuspenseHook = require('./rules/detect-suspense-hook');
+
+const plugin = {
+  meta: {
+    name: 'eslint-plugin-react-suspense-check',
+    version: '1.0.0',
+  },
+  rules: {
+    'detect-suspense-hook': detectSuspenseHook,
+  },
+  configs: {}, // 아래에서 채움
+};
+
+plugin.configs.recommended = {
+  plugins: {
+    'react-suspense-check': plugin,
+  },
+  rules: {
+    'react-suspense-check/detect-suspense-hook': 'warn',
+  },
+  // ③ (선택사항) 적용할 파일 확장자도 미리 지정해주면 사용자가 편함
+  // 이걸 안 넣으면 모든 파일(.css, .json 등)을 다 찔러봐서 비효율적일 수 있음
+  files: ['**/*.{js,jsx,mjs,cjs,ts,tsx}'],
+  languageOptions: {
+    parserOptions: {
+      ecmaFeatures: {
+        jsx: true,
+      },
+    },
+  },
+};
+
+module.exports = plugin;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "eslint-plugin-react-suspense-check",
+  "version": "1.0.0",
+  "description": "ESLint plugin to enforce naming conventions for React Suspense safety",
+  "main": "index.js",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "react",
+    "suspense",
+    "naming-convention",
+    "hook",
+    "lint",
+    "analysis"
+  ],
+  "author": "Your Name <your.email@example.com> (https://your-website.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rhehfl/eslint-plugin-react-suspense-check.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rhehfl/eslint-plugin-react-suspense-check/issues"
+  },
+  "homepage": "https://github.com/rhehfl/eslint-plugin-react-suspense-check#readme",
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  },
+  "files": [
+    "index.js",
+    "rules",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/rules/detect-suspense-hook.js

@@ -0,0 +1,119 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Enforce naming conventions (Chain of Suspense) for hooks triggering Suspense',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    messages: {
+      // [Case 1] 훅 이름 변경 필요
+      hookRenamingRequired_en:
+        "🛑 This hook triggers Suspense internally. Rename it to start with 'useSuspense' to signal its behavior.\n(Suggested: {{ suggestedName }})",
+      hookRenamingRequired_kr:
+        "🛑 내부에서 Suspense를 유발하는 훅입니다. 이름을 'useSuspense'로 시작하게 변경하여 동작을 명시하세요.\n(추천 이름: {{ suggestedName }})",
+
+      // [Case 2] 컴포넌트 이름 변경 필요
+      componentRenamingRequired_en:
+        "🛑 This component uses a Suspense-triggering hook. Rename it to 'Suspense{{name}}' so callers know to wrap it in a <Suspense> boundary.",
+      componentRenamingRequired_kr:
+        "🛑 내부에서 Suspense 훅을 사용하는 컴포넌트입니다. 상위에서 <Suspense> 처리가 필요함을 알릴 수 있도록 이름을 'Suspense{{name}}' 형식으로 변경하세요.",
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          language: {
+            type: 'string',
+            enum: ['en', 'kr'],
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+
+  create(context) {
+    const configuration = context.options[0] || {};
+    const lang = configuration.language || 'en';
+    return {
+      CallExpression(node) {
+        let hookName = null;
+        if (node.callee.type === 'Identifier') {
+          hookName = node.callee.name;
+        } else if (node.callee.type === 'MemberExpression') {
+          hookName = node.callee.property.name;
+        }
+        const isSuspenseTrigger =
+          hookName === 'use' ||
+          hookName === 'lazy' ||
+          (typeof hookName === 'string' && /^useSuspense/.test(hookName));
+
+        if (!isSuspenseTrigger) return;
+
+        let parent = node.parent;
+        while (parent) {
+          if (
+            parent.type === 'FunctionDeclaration' ||
+            parent.type === 'ArrowFunctionExpression' ||
+            parent.type === 'FunctionExpression'
+          ) {
+            break;
+          }
+          parent = parent.parent;
+        }
+
+        if (!parent) return;
+
+        let parentFunctionName = null;
+        let parentIdNode = null;
+
+        if (parent.type === 'FunctionDeclaration' && parent.id) {
+          parentFunctionName = parent.id.name;
+          parentIdNode = parent.id;
+        } else if (
+          parent.type === 'ArrowFunctionExpression' ||
+          parent.type === 'FunctionExpression'
+        ) {
+          if (parent.parent.type === 'VariableDeclarator' && parent.parent.id) {
+            parentFunctionName = parent.parent.id.name;
+            parentIdNode = parent.parent.id;
+          }
+        }
+
+        if (!parentFunctionName) return;
+
+        const isParentHook = /^use/.test(parentFunctionName);
+
+        if (isParentHook) {
+          if (/^useSuspense/.test(parentFunctionName)) return;
+
+          const suggestedName = parentFunctionName.replace(
+            /^use/,
+            'useSuspense'
+          );
+          context.report({
+            node: parentIdNode,
+            messageId: `hookRenamingRequired_${lang}`,
+            data: {
+              suggestedName: suggestedName,
+            },
+          });
+        } else {
+          const isSuspenseComponent = /^Suspense/.test(parentFunctionName);
+
+          if (!isSuspenseComponent) {
+            context.report({
+              node: parentIdNode,
+              messageId: `componentRenamingRequired_${lang}`,
+              data: {
+                name: parentFunctionName,
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};