@wsxjs/eslint-plugin-wsx 0.0.17 → 0.0.18

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 WSX Framework Contributors
+Copyright (c) 2026 WSXJS Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @wsxjs/eslint-plugin-wsx
 
-ESLint plugin for WSX Framework - enforces best practices and framework-specific rules for Web Components with JSX.
+ESLint plugin for WSXJS - enforces best practices and framework-specific rules for Web Components with JSX.
 
 ## Installation
 

package/dist/index.d.mts

@@ -10,6 +10,7 @@ interface WSXRuleContext extends Rule.RuleContext {
 }
 interface WSXRuleModule extends Rule.RuleModule {
     create: (context: WSXRuleContext) => Rule.RuleListener;
+    defaultOptions?: unknown[];
 }
 interface WSXConfig {
     parser?: string;

package/dist/index.d.ts

@@ -10,6 +10,7 @@ interface WSXRuleContext extends Rule.RuleContext {
 }
 interface WSXRuleModule extends Rule.RuleModule {
     create: (context: WSXRuleContext) => Rule.RuleListener;
+    defaultOptions?: unknown[];
 }
 interface WSXConfig {
     parser?: string;

package/dist/index.js

@@ -260,6 +260,196 @@ var stateRequiresInitialValue = {
   }
 };
 
+// src/rules/require-jsx-import-source.ts
+var JSX_IMPORT_SOURCE_PRAGMA = "/** @jsxImportSource @wsxjs/wsx-core */";
+var requireJsxImportSource = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "require @jsxImportSource pragma in .wsx files",
+      category: "Best Practices",
+      recommended: true
+    },
+    fixable: "code",
+    messages: {
+      missingPragma: "WSX files must include '@jsxImportSource @wsxjs/wsx-core' pragma comment at the top for IDE TypeScript language server support"
+    },
+    schema: []
+    // 无配置选项
+  },
+  defaultOptions: [],
+  // 无默认配置选项
+  create(context) {
+    const filename = context.getFilename();
+    if (!filename.endsWith(".wsx")) {
+      return {};
+    }
+    const sourceCode = context.getSourceCode();
+    const text = sourceCode.getText();
+    const hasPragma = text.includes("@jsxImportSource");
+    if (!hasPragma) {
+      const firstNode = sourceCode.ast.body[0] || sourceCode.ast;
+      context.report({
+        node: firstNode,
+        messageId: "missingPragma",
+        fix(fixer) {
+          return fixer.insertTextBeforeRange([0, 0], `${JSX_IMPORT_SOURCE_PRAGMA}
+`);
+        }
+      });
+    }
+    return {};
+  }
+};
+
+// src/rules/no-null-render.ts
+var noNullRender = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "disallow returning null from render() method",
+      category: "Possible Errors",
+      recommended: true
+    },
+    fixable: "code",
+    messages: {
+      nullReturn: "render() method must not return null. WebComponent and LightComponent require a valid DOM node. Use an empty div as placeholder instead."
+    },
+    schema: []
+    // 无配置选项
+  },
+  defaultOptions: [],
+  create(context) {
+    function checkStatements(statements) {
+      statements.forEach((statement) => {
+        if (statement.type === "ReturnStatement" && statement.argument) {
+          const arg = statement.argument;
+          if (arg.type === "Literal" && (arg.value === null || arg.raw === "null")) {
+            context.report({
+              node: statement,
+              messageId: "nullReturn",
+              fix(fixer) {
+                const sourceCode = context.getSourceCode();
+                const returnToken = sourceCode.getFirstToken(statement);
+                const nullToken = sourceCode.getTokenAfter(returnToken);
+                const semicolonToken = sourceCode.getTokenAfter(nullToken);
+                if (!returnToken || !nullToken) return null;
+                const start = returnToken.range[0];
+                const end = semicolonToken ? semicolonToken.range[1] : nullToken.range[1];
+                return fixer.replaceTextRange([start, end], "return <div></div>;");
+              }
+            });
+          }
+        }
+        if (statement.type === "IfStatement") {
+          if (statement.consequent.type === "BlockStatement") {
+            checkStatements(statement.consequent.body);
+          }
+          if (statement.alternate) {
+            if (statement.alternate.type === "BlockStatement") {
+              checkStatements(statement.alternate.body);
+            } else if (statement.alternate.type === "IfStatement") {
+              checkStatements([statement.alternate]);
+            }
+          }
+        } else if (statement.type === "SwitchStatement") {
+          statement.cases.forEach((caseClause) => {
+            checkStatements(caseClause.consequent);
+          });
+        } else if (statement.type === "ForStatement" || statement.type === "WhileStatement" || statement.type === "DoWhileStatement") {
+          if (statement.body.type === "BlockStatement") {
+            checkStatements(statement.body.body);
+          }
+        } else if (statement.type === "ForInStatement" || statement.type === "ForOfStatement") {
+          if (statement.body.type === "BlockStatement") {
+            checkStatements(statement.body.body);
+          }
+        } else if (statement.type === "TryStatement") {
+          if (statement.block.type === "BlockStatement") {
+            checkStatements(statement.block.body);
+          }
+          if (statement.handler && statement.handler.body.type === "BlockStatement") {
+            checkStatements(statement.handler.body.body);
+          }
+          if (statement.finalizer && statement.finalizer.type === "BlockStatement") {
+            checkStatements(statement.finalizer.body);
+          }
+        }
+      });
+    }
+    function checkReturnNull(node) {
+      const isRenderMethod = node.key.type === "Identifier" && node.key.name === "render" || node.key.type === "Literal" && node.key.value === "render";
+      if (!isRenderMethod) return;
+      const methodValue = node.type === "MethodDefinition" ? node.value : node.value;
+      if (!methodValue || methodValue.type !== "FunctionExpression") return;
+      const body = methodValue.body;
+      if (!body || body.type !== "BlockStatement") return;
+      checkStatements(body.body);
+    }
+    return {
+      // 检查类方法定义
+      MethodDefinition(node) {
+        const ancestors = context.getAncestors();
+        let classDeclaration = null;
+        for (let i = ancestors.length - 1; i >= 0; i--) {
+          const ancestor = ancestors[i];
+          if (ancestor && ancestor.type === "ClassDeclaration") {
+            classDeclaration = ancestor;
+            break;
+          }
+        }
+        if (classDeclaration && classDeclaration.superClass) {
+          const isWSXComponent = classDeclaration.superClass.type === "Identifier" && (classDeclaration.superClass.name === "WebComponent" || classDeclaration.superClass.name === "LightComponent");
+          if (isWSXComponent) {
+            checkReturnNull(node);
+          }
+        }
+      }
+    };
+  }
+};
+
+// src/rules/no-inner-html.ts
+var noInnerHTML = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "disallow use of innerHTML in WSX code",
+      category: "Best Practices",
+      recommended: true
+    },
+    messages: {
+      noInnerHTML: "Do not use innerHTML. Use JSX and WSX's declarative rendering instead. If you need to parse HTML strings, use parseHTMLToNodes() utility function."
+    },
+    schema: []
+    // 无配置选项
+  },
+  create(context) {
+    return {
+      // 检测 innerHTML 赋值：element.innerHTML = "..."
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      AssignmentExpression(node) {
+        if (node.left && node.left.type === "MemberExpression" && node.left.property && node.left.property.type === "Identifier" && node.left.property.name === "innerHTML") {
+          context.report({
+            node,
+            messageId: "noInnerHTML"
+          });
+        }
+      },
+      // 检测 innerHTML 读取：const html = element.innerHTML
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      MemberExpression(node) {
+        if (node.property && node.property.type === "Identifier" && node.property.name === "innerHTML" && node.parent && node.parent.type !== "AssignmentExpression") {
+          context.report({
+            node,
+            messageId: "noInnerHTML"
+          });
+        }
+      }
+    };
+  }
+};
+
 // src/configs/recommended.ts
 var recommendedConfig = {
   parser: "@typescript-eslint/parser",
@@ -281,6 +471,9 @@ var recommendedConfig = {
     "wsx/no-react-imports": "error",
     "wsx/web-component-naming": "warn",
     "wsx/state-requires-initial-value": "error",
+    "wsx/require-jsx-import-source": "error",
+    "wsx/no-null-render": "error",
+    "wsx/no-inner-html": "error",
     // TypeScript 规则（推荐）
     "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
     "@typescript-eslint/no-explicit-any": "warn",
@@ -446,7 +639,10 @@ var plugin = {
     "render-method-required": renderMethodRequired,
     "no-react-imports": noReactImports,
     "web-component-naming": webComponentNaming,
-    "state-requires-initial-value": stateRequiresInitialValue
+    "state-requires-initial-value": stateRequiresInitialValue,
+    "require-jsx-import-source": requireJsxImportSource,
+    "no-null-render": noNullRender,
+    "no-inner-html": noInnerHTML
   },
   // 配置预设
   configs: {

package/dist/index.mjs

@@ -231,6 +231,196 @@ var stateRequiresInitialValue = {
   }
 };
 
+// src/rules/require-jsx-import-source.ts
+var JSX_IMPORT_SOURCE_PRAGMA = "/** @jsxImportSource @wsxjs/wsx-core */";
+var requireJsxImportSource = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "require @jsxImportSource pragma in .wsx files",
+      category: "Best Practices",
+      recommended: true
+    },
+    fixable: "code",
+    messages: {
+      missingPragma: "WSX files must include '@jsxImportSource @wsxjs/wsx-core' pragma comment at the top for IDE TypeScript language server support"
+    },
+    schema: []
+    // 无配置选项
+  },
+  defaultOptions: [],
+  // 无默认配置选项
+  create(context) {
+    const filename = context.getFilename();
+    if (!filename.endsWith(".wsx")) {
+      return {};
+    }
+    const sourceCode = context.getSourceCode();
+    const text = sourceCode.getText();
+    const hasPragma = text.includes("@jsxImportSource");
+    if (!hasPragma) {
+      const firstNode = sourceCode.ast.body[0] || sourceCode.ast;
+      context.report({
+        node: firstNode,
+        messageId: "missingPragma",
+        fix(fixer) {
+          return fixer.insertTextBeforeRange([0, 0], `${JSX_IMPORT_SOURCE_PRAGMA}
+`);
+        }
+      });
+    }
+    return {};
+  }
+};
+
+// src/rules/no-null-render.ts
+var noNullRender = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "disallow returning null from render() method",
+      category: "Possible Errors",
+      recommended: true
+    },
+    fixable: "code",
+    messages: {
+      nullReturn: "render() method must not return null. WebComponent and LightComponent require a valid DOM node. Use an empty div as placeholder instead."
+    },
+    schema: []
+    // 无配置选项
+  },
+  defaultOptions: [],
+  create(context) {
+    function checkStatements(statements) {
+      statements.forEach((statement) => {
+        if (statement.type === "ReturnStatement" && statement.argument) {
+          const arg = statement.argument;
+          if (arg.type === "Literal" && (arg.value === null || arg.raw === "null")) {
+            context.report({
+              node: statement,
+              messageId: "nullReturn",
+              fix(fixer) {
+                const sourceCode = context.getSourceCode();
+                const returnToken = sourceCode.getFirstToken(statement);
+                const nullToken = sourceCode.getTokenAfter(returnToken);
+                const semicolonToken = sourceCode.getTokenAfter(nullToken);
+                if (!returnToken || !nullToken) return null;
+                const start = returnToken.range[0];
+                const end = semicolonToken ? semicolonToken.range[1] : nullToken.range[1];
+                return fixer.replaceTextRange([start, end], "return <div></div>;");
+              }
+            });
+          }
+        }
+        if (statement.type === "IfStatement") {
+          if (statement.consequent.type === "BlockStatement") {
+            checkStatements(statement.consequent.body);
+          }
+          if (statement.alternate) {
+            if (statement.alternate.type === "BlockStatement") {
+              checkStatements(statement.alternate.body);
+            } else if (statement.alternate.type === "IfStatement") {
+              checkStatements([statement.alternate]);
+            }
+          }
+        } else if (statement.type === "SwitchStatement") {
+          statement.cases.forEach((caseClause) => {
+            checkStatements(caseClause.consequent);
+          });
+        } else if (statement.type === "ForStatement" || statement.type === "WhileStatement" || statement.type === "DoWhileStatement") {
+          if (statement.body.type === "BlockStatement") {
+            checkStatements(statement.body.body);
+          }
+        } else if (statement.type === "ForInStatement" || statement.type === "ForOfStatement") {
+          if (statement.body.type === "BlockStatement") {
+            checkStatements(statement.body.body);
+          }
+        } else if (statement.type === "TryStatement") {
+          if (statement.block.type === "BlockStatement") {
+            checkStatements(statement.block.body);
+          }
+          if (statement.handler && statement.handler.body.type === "BlockStatement") {
+            checkStatements(statement.handler.body.body);
+          }
+          if (statement.finalizer && statement.finalizer.type === "BlockStatement") {
+            checkStatements(statement.finalizer.body);
+          }
+        }
+      });
+    }
+    function checkReturnNull(node) {
+      const isRenderMethod = node.key.type === "Identifier" && node.key.name === "render" || node.key.type === "Literal" && node.key.value === "render";
+      if (!isRenderMethod) return;
+      const methodValue = node.type === "MethodDefinition" ? node.value : node.value;
+      if (!methodValue || methodValue.type !== "FunctionExpression") return;
+      const body = methodValue.body;
+      if (!body || body.type !== "BlockStatement") return;
+      checkStatements(body.body);
+    }
+    return {
+      // 检查类方法定义
+      MethodDefinition(node) {
+        const ancestors = context.getAncestors();
+        let classDeclaration = null;
+        for (let i = ancestors.length - 1; i >= 0; i--) {
+          const ancestor = ancestors[i];
+          if (ancestor && ancestor.type === "ClassDeclaration") {
+            classDeclaration = ancestor;
+            break;
+          }
+        }
+        if (classDeclaration && classDeclaration.superClass) {
+          const isWSXComponent = classDeclaration.superClass.type === "Identifier" && (classDeclaration.superClass.name === "WebComponent" || classDeclaration.superClass.name === "LightComponent");
+          if (isWSXComponent) {
+            checkReturnNull(node);
+          }
+        }
+      }
+    };
+  }
+};
+
+// src/rules/no-inner-html.ts
+var noInnerHTML = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "disallow use of innerHTML in WSX code",
+      category: "Best Practices",
+      recommended: true
+    },
+    messages: {
+      noInnerHTML: "Do not use innerHTML. Use JSX and WSX's declarative rendering instead. If you need to parse HTML strings, use parseHTMLToNodes() utility function."
+    },
+    schema: []
+    // 无配置选项
+  },
+  create(context) {
+    return {
+      // 检测 innerHTML 赋值：element.innerHTML = "..."
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      AssignmentExpression(node) {
+        if (node.left && node.left.type === "MemberExpression" && node.left.property && node.left.property.type === "Identifier" && node.left.property.name === "innerHTML") {
+          context.report({
+            node,
+            messageId: "noInnerHTML"
+          });
+        }
+      },
+      // 检测 innerHTML 读取：const html = element.innerHTML
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      MemberExpression(node) {
+        if (node.property && node.property.type === "Identifier" && node.property.name === "innerHTML" && node.parent && node.parent.type !== "AssignmentExpression") {
+          context.report({
+            node,
+            messageId: "noInnerHTML"
+          });
+        }
+      }
+    };
+  }
+};
+
 // src/configs/recommended.ts
 var recommendedConfig = {
   parser: "@typescript-eslint/parser",
@@ -252,6 +442,9 @@ var recommendedConfig = {
     "wsx/no-react-imports": "error",
     "wsx/web-component-naming": "warn",
     "wsx/state-requires-initial-value": "error",
+    "wsx/require-jsx-import-source": "error",
+    "wsx/no-null-render": "error",
+    "wsx/no-inner-html": "error",
     // TypeScript 规则（推荐）
     "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
     "@typescript-eslint/no-explicit-any": "warn",
@@ -417,7 +610,10 @@ var plugin = {
     "render-method-required": renderMethodRequired,
     "no-react-imports": noReactImports,
     "web-component-naming": webComponentNaming,
-    "state-requires-initial-value": stateRequiresInitialValue
+    "state-requires-initial-value": stateRequiresInitialValue,
+    "require-jsx-import-source": requireJsxImportSource,
+    "no-null-render": noNullRender,
+    "no-inner-html": noInnerHTML
   },
   // 配置预设
   configs: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wsxjs/eslint-plugin-wsx",
-  "version": "0.0.17",
-  "description": "ESLint plugin for WSX Framework",
+  "version": "0.0.18",
+  "description": "ESLint plugin for WSXJS",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -25,7 +25,7 @@
     "web-components"
   ],
   "dependencies": {
-    "@wsxjs/wsx-core": "0.0.17"
+    "@wsxjs/wsx-core": "0.0.18"
   },
   "devDependencies": {
     "tsup": "^8.0.0",

package/src/configs/flat.ts

@@ -1,7 +1,7 @@
 /**
  * ESLint Plugin WSX - Flat Config for ESLint 9+
  *
- * Modern flat config format for WSX framework
+ * Modern flat config format for WSXJS
  */
 
 import type { Linter } from "eslint";

package/src/configs/recommended.ts

@@ -25,6 +25,9 @@ export const recommendedConfig: WSXConfig = {
         "wsx/no-react-imports": "error",
         "wsx/web-component-naming": "warn",
         "wsx/state-requires-initial-value": "error",
+        "wsx/require-jsx-import-source": "error",
+        "wsx/no-null-render": "error",
+        "wsx/no-inner-html": "error",
 
         // TypeScript 规则（推荐）
         "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],

package/src/index.ts

@@ -9,6 +9,9 @@ import { renderMethodRequired } from "./rules/render-method-required";
 import { noReactImports } from "./rules/no-react-imports";
 import { webComponentNaming } from "./rules/web-component-naming";
 import { stateRequiresInitialValue } from "./rules/state-requires-initial-value";
+import { requireJsxImportSource } from "./rules/require-jsx-import-source";
+import { noNullRender } from "./rules/no-null-render";
+import { noInnerHTML } from "./rules/no-inner-html";
 import { recommendedConfig } from "./configs/recommended";
 import { createFlatConfig } from "./configs/flat";
 import { WSXPlugin } from "./types";
@@ -26,6 +29,9 @@ const plugin: WSXPlugin = {
         "no-react-imports": noReactImports,
         "web-component-naming": webComponentNaming,
         "state-requires-initial-value": stateRequiresInitialValue,
+        "require-jsx-import-source": requireJsxImportSource,
+        "no-null-render": noNullRender,
+        "no-inner-html": noInnerHTML,
     },
 
     // 配置预设

package/src/rules/no-inner-html.ts

@@ -0,0 +1,64 @@
+/**
+ * ESLint 规则：no-inner-html
+ *
+ * 禁止在 WSX 代码中使用 innerHTML
+ * WSX 框架鼓励使用声明式 JSX 而不是手动 DOM 操作
+ */
+
+import { Rule } from "eslint";
+import { WSXRuleModule } from "../types";
+
+export const noInnerHTML: WSXRuleModule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "disallow use of innerHTML in WSX code",
+            category: "Best Practices",
+            recommended: true,
+        },
+        messages: {
+            noInnerHTML:
+                "Do not use innerHTML. Use JSX and WSX's declarative rendering instead. If you need to parse HTML strings, use parseHTMLToNodes() utility function.",
+        },
+        schema: [], // 无配置选项
+    },
+    create(context: Rule.RuleContext) {
+        return {
+            // 检测 innerHTML 赋值：element.innerHTML = "..."
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            AssignmentExpression(node: any) {
+                if (
+                    node.left &&
+                    node.left.type === "MemberExpression" &&
+                    node.left.property &&
+                    node.left.property.type === "Identifier" &&
+                    node.left.property.name === "innerHTML"
+                ) {
+                    context.report({
+                        node,
+                        messageId: "noInnerHTML",
+                    });
+                }
+            },
+            // 检测 innerHTML 读取：const html = element.innerHTML
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            MemberExpression(node: any) {
+                if (
+                    node.property &&
+                    node.property.type === "Identifier" &&
+                    node.property.name === "innerHTML" &&
+                    node.parent &&
+                    node.parent.type !== "AssignmentExpression"
+                ) {
+                    // 只报告读取操作（赋值已在上面处理）
+                    // 但允许在特定上下文中读取（如调试或工具函数）
+                    // 这里我们仍然报告，但用户可以通过注释禁用
+                    context.report({
+                        node,
+                        messageId: "noInnerHTML",
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/no-null-render.ts

@@ -0,0 +1,171 @@
+/**
+ * ESLint 规则：no-null-render
+ *
+ * 禁止 render() 方法返回 null
+ * WebComponent 和 LightComponent 的 connectedCallback 需要有效的 DOM 节点
+ */
+
+import { Rule } from "eslint";
+import { WSXRuleModule } from "../types";
+
+export const noNullRender: WSXRuleModule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "disallow returning null from render() method",
+            category: "Possible Errors",
+            recommended: true,
+        },
+        fixable: "code",
+        messages: {
+            nullReturn:
+                "render() method must not return null. WebComponent and LightComponent require a valid DOM node. Use an empty div as placeholder instead.",
+        },
+        schema: [], // 无配置选项
+    },
+    defaultOptions: [],
+    create(context: Rule.RuleContext) {
+        /**
+         * 递归检查语句块中的所有 return null
+         */
+        function checkStatements(statements: import("estree").Statement[]) {
+            statements.forEach((statement) => {
+                // 检查 return null
+                if (statement.type === "ReturnStatement" && statement.argument) {
+                    const arg = statement.argument;
+                    // 检查是否为 null 字面量
+                    if (arg.type === "Literal" && (arg.value === null || arg.raw === "null")) {
+                        context.report({
+                            node: statement,
+                            messageId: "nullReturn",
+                            fix(fixer) {
+                                // 将 return null; 替换为 return <div></div>;
+                                const sourceCode = context.getSourceCode();
+                                const returnToken = sourceCode.getFirstToken(statement);
+                                const nullToken = sourceCode.getTokenAfter(returnToken!);
+                                const semicolonToken = sourceCode.getTokenAfter(nullToken!);
+
+                                if (!returnToken || !nullToken) return null;
+
+                                // 计算替换范围：从 return 到 null（或分号）
+                                const start = returnToken.range[0];
+                                const end = semicolonToken
+                                    ? semicolonToken.range[1]
+                                    : nullToken.range[1];
+
+                                // 替换为 return <div></div>;
+                                return fixer.replaceTextRange([start, end], "return <div></div>;");
+                            },
+                        });
+                    }
+                }
+
+                // 递归检查嵌套的语句块
+                if (statement.type === "IfStatement") {
+                    // 检查 then 分支
+                    if (statement.consequent.type === "BlockStatement") {
+                        checkStatements(statement.consequent.body);
+                    }
+                    // 检查 else 分支
+                    if (statement.alternate) {
+                        if (statement.alternate.type === "BlockStatement") {
+                            checkStatements(statement.alternate.body);
+                        } else if (statement.alternate.type === "IfStatement") {
+                            // else if 的情况
+                            checkStatements([statement.alternate]);
+                        }
+                    }
+                } else if (statement.type === "SwitchStatement") {
+                    // 检查 switch 的每个 case
+                    statement.cases.forEach((caseClause) => {
+                        checkStatements(caseClause.consequent);
+                    });
+                } else if (
+                    statement.type === "ForStatement" ||
+                    statement.type === "WhileStatement" ||
+                    statement.type === "DoWhileStatement"
+                ) {
+                    // 检查循环体
+                    if (statement.body.type === "BlockStatement") {
+                        checkStatements(statement.body.body);
+                    }
+                } else if (
+                    statement.type === "ForInStatement" ||
+                    statement.type === "ForOfStatement"
+                ) {
+                    // 检查 for...in 和 for...of 循环体
+                    if (statement.body.type === "BlockStatement") {
+                        checkStatements(statement.body.body);
+                    }
+                } else if (statement.type === "TryStatement") {
+                    // 检查 try 块
+                    if (statement.block.type === "BlockStatement") {
+                        checkStatements(statement.block.body);
+                    }
+                    // 检查 catch 块
+                    if (statement.handler && statement.handler.body.type === "BlockStatement") {
+                        checkStatements(statement.handler.body.body);
+                    }
+                    // 检查 finally 块
+                    if (statement.finalizer && statement.finalizer.type === "BlockStatement") {
+                        checkStatements(statement.finalizer.body);
+                    }
+                }
+            });
+        }
+
+        /**
+         * 检查方法体中是否有 return null
+         */
+        function checkReturnNull(
+            node: import("estree").MethodDefinition | import("estree").Property
+        ) {
+            // 只检查 render 方法
+            const isRenderMethod =
+                (node.key.type === "Identifier" && node.key.name === "render") ||
+                (node.key.type === "Literal" && node.key.value === "render");
+
+            if (!isRenderMethod) return;
+
+            // 获取方法体
+            const methodValue = node.type === "MethodDefinition" ? node.value : node.value;
+            if (!methodValue || methodValue.type !== "FunctionExpression") return;
+
+            const body = methodValue.body;
+            if (!body || body.type !== "BlockStatement") return;
+
+            // 递归检查所有语句（包括嵌套的）
+            checkStatements(body.body);
+        }
+
+        return {
+            // 检查类方法定义
+            MethodDefinition(node: import("estree").MethodDefinition) {
+                // 检查是否继承自 WebComponent 或 LightComponent
+                // 使用 getAncestors 获取父节点链（不包括当前节点）
+                const ancestors = context.getAncestors();
+
+                // 查找最近的 ClassDeclaration 父节点（从后往前）
+                let classDeclaration: import("estree").ClassDeclaration | null = null;
+                for (let i = ancestors.length - 1; i >= 0; i--) {
+                    const ancestor = ancestors[i];
+                    if (ancestor && ancestor.type === "ClassDeclaration") {
+                        classDeclaration = ancestor as import("estree").ClassDeclaration;
+                        break;
+                    }
+                }
+
+                if (classDeclaration && classDeclaration.superClass) {
+                    const isWSXComponent =
+                        classDeclaration.superClass.type === "Identifier" &&
+                        (classDeclaration.superClass.name === "WebComponent" ||
+                            classDeclaration.superClass.name === "LightComponent");
+
+                    if (isWSXComponent) {
+                        checkReturnNull(node);
+                    }
+                }
+            },
+        };
+    },
+};

package/src/rules/require-jsx-import-source.ts

@@ -0,0 +1,64 @@
+/**
+ * ESLint 规则：require-jsx-import-source
+ *
+ * 要求 .wsx 文件包含 @jsxImportSource pragma 注释
+ * 自动修复：如果缺失，自动在文件开头添加
+ *
+ * 为什么需要这个规则：
+ * - IDE 的 TypeScript 语言服务器读取源文件，需要 pragma 来正确进行类型检查
+ * - Vite 插件在构建时注入 pragma 对 IDE 无效（IDE 看不到构建后的代码）
+ * - ESLint 自动修复直接修改源文件，IDE 可以立即看到 pragma
+ * - 这是唯一能让 IDE 和构建工具都正常工作的方案
+ */
+
+import { Rule } from "eslint";
+import { WSXRuleModule } from "../types";
+
+const JSX_IMPORT_SOURCE_PRAGMA = "/** @jsxImportSource @wsxjs/wsx-core */";
+
+export const requireJsxImportSource: WSXRuleModule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "require @jsxImportSource pragma in .wsx files",
+            category: "Best Practices",
+            recommended: true,
+        },
+        fixable: "code",
+        messages: {
+            missingPragma:
+                "WSX files must include '@jsxImportSource @wsxjs/wsx-core' pragma comment at the top for IDE TypeScript language server support",
+        },
+        schema: [], // 无配置选项
+    },
+    defaultOptions: [], // 无默认配置选项
+    create(context: Rule.RuleContext) {
+        const filename = context.getFilename();
+        // 只检查 .wsx 文件
+        if (!filename.endsWith(".wsx")) {
+            return {};
+        }
+
+        const sourceCode = context.getSourceCode();
+        const text = sourceCode.getText();
+
+        // 检查是否已包含 pragma
+        const hasPragma = text.includes("@jsxImportSource");
+
+        if (!hasPragma) {
+            // 获取第一个节点（通常是文件开头的注释或 import）
+            const firstNode = sourceCode.ast.body[0] || sourceCode.ast;
+
+            context.report({
+                node: firstNode,
+                messageId: "missingPragma",
+                fix(fixer) {
+                    // 在文件开头插入 pragma 注释
+                    return fixer.insertTextBeforeRange([0, 0], `${JSX_IMPORT_SOURCE_PRAGMA}\n`);
+                },
+            });
+        }
+
+        return {};
+    },
+};

package/src/types.ts

@@ -12,6 +12,7 @@ export interface WSXRuleContext extends Rule.RuleContext {
 export interface WSXRuleModule extends Rule.RuleModule {
     // WSX 特定的规则模块扩展
     create: (context: WSXRuleContext) => Rule.RuleListener;
+    defaultOptions?: unknown[]; // 默认配置选项（可选）
 }
 
 export interface WSXConfig {