@lark-apaas/fullstack-presets 1.1.3-beta.1 → 1.1.3-beta.3

package/README.md

@@ -41,6 +41,16 @@ export default [
 ];
 ```
 
+#### 错误信息
+
+当检测到嵌套的 styled-jsx 标签时，规则会提供详细的错误信息，指出与哪一行的外层 styled-jsx 标签冲突：
+
+```
+17:23  error  Detected nested styled-jsx tag. The outer styled-jsx tag is at line 4. Read more: https://nextjs.org/docs/messages/nested-styled-jsx-tags  @lark-apaas/no-nested-styled-jsx
+```
+
+这样可以快速定位到冲突的外层 styled-jsx 标签，方便修复问题。
+
 #### 自定义错误信息
 
 可通过配置自定义报错信息：
@@ -53,7 +63,101 @@ rules: {
 }
 ```
 
+注意：使用自定义错误信息时，将不会显示外层 styled-jsx 标签的行号信息。
+
 #### 参考资料
 
 - [Next.js 错误说明](https://nextjs.org/docs/messages/nested-styled-jsx-tags)
-- [styled-jsx GitHub Issue #42](https://github.com/vercel/styled-jsx/issues/42)
+- [styled-jsx GitHub Issue #42](https://github.com/vercel/styled-jsx/issues/42)
+
+---
+
+### 路由守卫规则 (RoutesComponent)
+
+保护 `client/src/app.tsx` 中的 RoutesComponent 组件结构，确保路由配置不被意外破坏。
+
+#### 规则目的
+
+该规则强制 `RoutesComponent` 必须直接返回 `<Routes>` 组件，不允许在外层添加任何包装元素（如 `<div>`、`<BrowserRouter>` 等）。这确保了：
+- ✅ 路由结构保持一致和可预测
+- ✅ 防止开发者误修改核心路由架构
+- ✅ 允许在 `<Routes>` 内部自由添加/修改/删除路由配置
+
+#### 生效范围
+
+**仅在 loose 模式下对 `client/src/app.tsx` 文件生效**
+
+该规则通过环境变量 `FORCE_FRAMEWORK_LINT_LOOSE_MODE=true` 启用，并且只检查项目中的 `client/src/app.tsx` 文件。
+
+#### 错误示例
+
+❌ **不允许：添加外层包装元素**
+
+```tsx
+// ❌ 错误：使用 div 包装
+const RoutesComponent = () => (
+  <div>
+    <Routes>
+      <Route path="/" element={<HomePage />} />
+    </Routes>
+  </div>
+);
+
+// ❌ 错误：使用 BrowserRouter 包装
+const RoutesComponent = () => {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+};
+```
+
+#### 正确示例
+
+✅ **允许：直接返回 Routes，在内部修改路由**
+
+```tsx
+// ✅ 正确：直接返回 Routes
+const RoutesComponent = () => (
+  <Routes>
+    <Route path="/" element={<HomePage />} />
+    <Route path="/about" element={<AboutPage />} />
+    <Route path="/users" element={<UsersPage />} />
+    <Route path="*" element={<NotFound />} />
+  </Routes>
+);
+
+// ✅ 正确：使用嵌套路由
+const RoutesComponent = () => (
+  <Routes>
+    <Route element={<Layout />}>
+      <Route index element={<HomePage />} />
+      <Route path="/about" element={<AboutPage />} />
+    </Route>
+    <Route path="*" element={<NotFound />} />
+  </Routes>
+);
+```
+
+#### 错误信息
+
+当违反规则时，会看到以下错误信息：
+
+```
+47:23  error  RoutesComponent must return <Routes> directly without any wrapper. Do not add <div>, <BrowserRouter> or other wrappers. You can only modify routes inside <Routes> (add/edit/remove <Route> elements).  no-restricted-syntax
+```
+
+错误信息包含三个层次的指导：
+1. **明确要求**：必须直接返回 `<Routes>`，不能有包装器
+2. **具体禁止**：不要添加 `<div>`、`<BrowserRouter>` 或其他包装器
+3. **允许操作**：可以在 `<Routes>` 内部添加/编辑/删除 `<Route>` 元素
+
+#### 使用场景
+
+该规则主要用于妙搭等需要保护核心路由结构的场景。在这些场景中：
+- 框架会自动管理路由的外层结构（如 BrowserRouter）
+- 开发者只需关注路由配置本身（路径、组件映射等）
+- 防止开发者误修改导致路由失效

package/lib/custom-eslint-rules/no-nested-styled-jsx.js

@@ -24,6 +24,7 @@ const rule = {
         ],
         messages: {
             nestedStyleJsx: DEFAULT_MESSAGE,
+            nestedStyleJsxWithLocation: 'Detected nested styled-jsx tag. The outer styled-jsx tag is at line {{line}}. Read more: https://nextjs.org/docs/messages/nested-styled-jsx-tags',
         },
     },
     create(context) {
@@ -47,24 +48,67 @@ const rule = {
                 if (!hasJsxAttribute) {
                     return;
                 }
-                // Count JSXElement ancestors
+                // Count JSXElement ancestors and find the outer styled-jsx tag
                 // styled-jsx uses ignoreClosing counter that increments on JSXOpeningElement enter
                 // and checks if ignoreClosing > 1 on style tag exit
                 // @see https://github.com/vercel/styled-jsx/blob/d7a59379134d73afaeb98177387cd62d54d746be/src/babel.js#L222
                 let jsxElementCount = 0;
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                let outerStyledJsxNode = null;
                 let current = node.parent;
                 while (current) {
                     if (current.type === 'JSXElement') {
                         jsxElementCount++;
+                        // Check if any sibling or ancestor siblings contain a styled-jsx tag
+                        if (!outerStyledJsxNode && current.parent) {
+                            const parentNode = current.parent;
+                            // Check if parent has children that we can iterate
+                            const children = parentNode.children || (parentNode.type === 'JSXElement' ? parentNode.children : null);
+                            if (children && Array.isArray(children)) {
+                                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                                for (const child of children) {
+                                    if (child.type === 'JSXElement' && child !== node) {
+                                        const childOpeningElement = child.openingElement;
+                                        if (childOpeningElement) {
+                                            const childElementName = childOpeningElement.name;
+                                            if (childElementName?.type === 'JSXIdentifier' &&
+                                                childElementName?.name === 'style') {
+                                                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                                                const hasChildJsxAttr = childOpeningElement.attributes?.some((attr) => attr.type === 'JSXAttribute' &&
+                                                    attr.name?.type === 'JSXIdentifier' &&
+                                                    attr.name?.name === 'jsx');
+                                                if (hasChildJsxAttr) {
+                                                    outerStyledJsxNode = child;
+                                                    break;
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
                     }
                     current = current.parent;
                 }
                 // If there's more than 1 JSXElement ancestor, the style tag is nested
                 if (jsxElementCount > 1) {
-                    context.report({
-                        node,
-                        ...(customMessage ? { message: customMessage } : { messageId: 'nestedStyleJsx' }),
-                    });
+                    if (outerStyledJsxNode && outerStyledJsxNode.loc) {
+                        // Report with location information about the outer styled-jsx tag
+                        context.report({
+                            node,
+                            messageId: 'nestedStyleJsxWithLocation',
+                            data: {
+                                line: outerStyledJsxNode.loc.start.line,
+                            },
+                        });
+                    }
+                    else {
+                        // Fallback to the original message if we can't find the outer styled-jsx tag
+                        context.report({
+                            node,
+                            ...(customMessage ? { message: customMessage } : { messageId: 'nestedStyleJsx' }),
+                        });
+                    }
                 }
             },
         };

package/lib/simple/recommend/eslint/eslint-client.d.ts

@@ -1,8 +1,8 @@
-export declare const looseSpecificSyntaxRules: {
+export declare const looseRestrictSyntaxRules: {
     selector: string;
     message: string;
 }[];
-declare const _default: {
+declare const _default: ({
     name: string;
     languageOptions: {
         ecmaVersion: number;
@@ -34,5 +34,14 @@ declare const _default: {
         };
     };
     rules: any;
-};
+} | {
+    name: string;
+    files: string[];
+    rules: {
+        'no-restricted-syntax': (string | {
+            message: string;
+            selector: string;
+        })[];
+    };
+} | null)[];
 export default _default;

package/lib/simple/recommend/eslint/eslint-client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.looseSpecificSyntaxRules = void 0;
+exports.looseRestrictSyntaxRules = void 0;
 const globals = require('globals');
 const reactHooks = require('eslint-plugin-react-hooks');
 const tseslint = require('typescript-eslint');
@@ -32,17 +32,17 @@ const baseSyntaxRules = [
     },
 ];
 // loose模式特化的规则
-exports.looseSpecificSyntaxRules = [
+exports.looseRestrictSyntaxRules = [
     // 约束RoutesComponent路由组件 dom规则
     {
         // 箭头函数 block body
         selector: "VariableDeclarator[id.name='RoutesComponent'] > ArrowFunctionExpression > BlockStatement > ReturnStatement[argument.type='JSXElement'][argument.openingElement.name.name!='Routes']",
-        message: 'RoutesComponent must return <Routes> directly without any wrapper',
+        message: 'RoutesComponent must return <Routes> directly without any wrapper. Do not add <div>, <BrowserRouter> or other wrappers. You can only modify routes inside <Routes> (add/edit/remove <Route> elements).',
     },
     {
         // 箭头函数 expression body
         selector: "VariableDeclarator[id.name='RoutesComponent'] > ArrowFunctionExpression > JSXElement:not([openingElement.name.name='Routes'])",
-        message: 'RoutesComponent must return <Routes> directly without any wrapper',
+        message: 'RoutesComponent must return <Routes> directly without any wrapper. Do not add <div>, <BrowserRouter> or other wrappers. You can only modify routes inside <Routes> (add/edit/remove <Route> elements).',
     },
 ];
 // 严格语法规则：仅正常模式启用，loose 模式下不启用
@@ -94,21 +94,23 @@ const strictSyntaxRules = [
         message: 'Classname "text-accent" would cause visibility issues. Consider using proper semantic color tokens from `client/src/tailwind-theme.css`',
     },
 ];
-const looseSpecificRules = {
-    '@lark-apaas/no-nested-styled-jsx': 'error'
-};
 const looseSpecificPlugins = {
     '@lark-apaas': { rules: custom_eslint_rules_1.customRules }
 };
+const looseSpecificRules = {
+    '@lark-apaas/no-nested-styled-jsx': 'error'
+};
 // 宽松模式下覆盖的规则（关闭非关键规则）
 const looseOverrideRules = isLooseMode
     ? {
+        ...looseSpecificRules,
         '@typescript-eslint/no-unsafe-function-type': 'off',
         '@typescript-eslint/no-unused-expressions': 'off',
         'no-useless-escape': 'off', // 允许不必要的转义字符
     }
     : {};
-exports.default = {
+// 基础配置（适用于所有文件）
+const baseConfig = {
     name: 'fullstack-presets/client-recommend',
     languageOptions: {
         ecmaVersion: 2020,
@@ -175,9 +177,23 @@ exports.default = {
         'no-restricted-syntax': [
             'error',
             ...baseSyntaxRules,
-            ...(isLooseMode ? exports.looseSpecificSyntaxRules : strictSyntaxRules),
+            // 注意：严格模式的 strictSyntaxRules 仍然应用于所有文件
+            ...(isLooseMode ? [] : strictSyntaxRules),
         ],
         // 宽松模式下覆盖上述规则
         ...looseOverrideRules,
     },
 };
+// app.tsx 专属配置（仅在 loose 模式下生效）
+const appTsxConfig = isLooseMode
+    ? {
+        // 路由守卫规则
+        name: '@lark-apaas/client-recommend/app-tsx',
+        files: ['client/src/app.tsx'],
+        rules: {
+            'no-restricted-syntax': ['error', ...baseSyntaxRules, ...exports.looseRestrictSyntaxRules],
+        },
+    }
+    : null;
+// 导出配置数组，过滤掉 null
+exports.default = [baseConfig, appTsxConfig].filter(Boolean);

package/lib/simple/recommend/eslint/index.d.ts

@@ -1,7 +1,7 @@
 export declare const eslintPresets: {
     client: ({
         readonly rules: Readonly<import("eslint").Linter.RulesRecord>;
-    } | import("typescript-eslint/dist/compatibility-types").CompatibleConfig | {
+    } | import("typescript-eslint/dist/compatibility-types").CompatibleConfig | ({
         name: string;
         languageOptions: {
             ecmaVersion: number;
@@ -34,6 +34,15 @@ export declare const eslintPresets: {
         };
         rules: any;
     } | {
+        name: string;
+        files: string[];
+        rules: {
+            'no-restricted-syntax': (string | {
+                message: string;
+                selector: string;
+            })[];
+        };
+    } | null)[] | {
         ignores: string[];
     })[];
     server: ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-presets",
-  "version": "1.1.3-beta.1",
+  "version": "1.1.3-beta.3",
   "files": [
     "lib"
   ],