@lark-apaas/fullstack-presets 1.1.2 → 1.1.3-beta.0

package/README.md

@@ -1,2 +1,163 @@
 # 全栈技术栈 Presets
-独立拆分 simple 目录，属于全栈精简版，目前妙搭场景专用。
+独立拆分 simple 目录，属于全栈精简版，目前妙搭场景专用。
+
+## ESLint 自定义规则
+
+### `no-nested-styled-jsx`
+
+检测嵌套的 styled-jsx 标签，防止编译错误。https://nextjs.org/docs/messages/nested-styled-jsx-tags
+
+该规则镜像了 styled-jsx babel 插件中的验证逻辑：
+- [babel.js#L215](https://github.com/vercel/styled-jsx/blob/d7a59379134d73afaeb98177387cd62d54d746be/src/babel.js#L215)
+- [babel.js#L222](https://github.com/vercel/styled-jsx/blob/d7a59379134d73afaeb98177387cd62d54d746be/src/babel.js#L222)
+
+#### 使用方式
+
+该规则已在 `eslint-client.ts` 配置中默认启用，无需额外配置：
+
+```typescript
+import clientConfig from '@lark-apaas/fullstack-presets/recommend/eslint/eslint-client';
+
+export default [
+  clientConfig,
+  // 其他配置...
+];
+```
+
+如需单独使用该规则：
+
+```typescript
+import { customRules } from '@lark-apaas/fullstack-presets/custom-eslint-rules';
+
+export default [
+  {
+    plugins: {
+      '@lark-apaas': { rules: customRules },
+    },
+    rules: {
+      '@lark-apaas/no-nested-styled-jsx': 'error',
+    },
+  },
+];
+```
+
+#### 错误信息
+
+当检测到嵌套的 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 标签，方便修复问题。
+
+#### 自定义错误信息
+
+可通过配置自定义报错信息：
+
+```typescript
+rules: {
+  '@lark-apaas/no-nested-styled-jsx': ['error', {
+    message: '禁止嵌套 styled-jsx 标签，请将 <style jsx> 移到组件根级别'
+  }],
+}
+```
+
+注意：使用自定义错误信息时，将不会显示外层 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)
+
+---
+
+### 路由守卫规则 (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/index.d.ts

@@ -0,0 +1,3 @@
+export declare const customRules: {
+    'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
+};

package/lib/custom-eslint-rules/index.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.customRules = void 0;
+const no_nested_styled_jsx_1 = __importDefault(require("./no-nested-styled-jsx"));
+exports.customRules = {
+    'no-nested-styled-jsx': no_nested_styled_jsx_1.default,
+};

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

@@ -0,0 +1,13 @@
+/**
+ * ESLint rule to detect nested styled-jsx tags.
+ *
+ * This rule mirrors the validation logic in styled-jsx's babel plugin:
+ * @see https://github.com/vercel/styled-jsx/blob/d7a59379134d73afaeb98177387cd62d54d746be/src/babel.js#L215
+ * @see https://github.com/vercel/styled-jsx/blob/d7a59379134d73afaeb98177387cd62d54d746be/src/babel.js#L222
+ *
+ * Test fixture:
+ * @see https://github.com/vercel/styled-jsx/blob/d7a59379134d73afaeb98177387cd62d54d746be/test/fixtures/nested-style-tags.js
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

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

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const DEFAULT_MESSAGE = 'Detected nested styled-jsx tag. Read more: https://nextjs.org/docs/messages/nested-styled-jsx-tags';
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow nested styled-jsx tags',
+            category: 'Possible Errors',
+            recommended: true,
+            url: 'https://nextjs.org/docs/messages/nested-styled-jsx-tags',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    message: {
+                        type: 'string',
+                        description: 'Custom error message',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        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) {
+        const options = context.options[0];
+        const customMessage = options?.message;
+        return {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            JSXElement(node) {
+                const openingElement = node.openingElement;
+                if (!openingElement)
+                    return;
+                const elementName = openingElement.name;
+                // Check if this is a <style> element with jsx attribute
+                if (elementName.type !== 'JSXIdentifier' || elementName.name !== 'style') {
+                    return;
+                }
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const hasJsxAttribute = openingElement.attributes.some((attr) => attr.type === 'JSXAttribute' &&
+                    attr.name?.type === 'JSXIdentifier' &&
+                    attr.name?.name === 'jsx');
+                if (!hasJsxAttribute) {
+                    return;
+                }
+                // Count JSXElement and JSXFragment 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
+                // Note: JSXFragment (<>...</>) should also be counted as a container
+                let jsxElementCount = 0;
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                let outerStyledJsxNode = null;
+                let current = node.parent;
+                while (current) {
+                    // Count both JSXElement and JSXFragment as containers
+                    if (current.type === 'JSXElement' || current.type === 'JSXFragment') {
+                        jsxElementCount++;
+                        // Check if any sibling or ancestor siblings contain a styled-jsx tag
+                        // Always update to find the outermost styled-jsx, not the first encountered
+                        if (current.parent) {
+                            const parentNode = current.parent;
+                            // Check if parent has children that we can iterate
+                            const children = parentNode.children ||
+                                (parentNode.type === 'JSXElement' || parentNode.type === 'JSXFragment' ? 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) {
+                                                    // Always update to find the outermost styled-jsx
+                                                    outerStyledJsxNode = child;
+                                                    break;
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    current = current.parent;
+                }
+                // If there's more than 1 JSXElement ancestor, the style tag is nested
+                if (jsxElementCount > 1) {
+                    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' }),
+                        });
+                    }
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

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

@@ -1,4 +1,8 @@
-declare const _default: {
+export declare const looseRestrictSyntaxRules: {
+    selector: string;
+    message: string;
+}[];
+declare const _default: ({
     name: string;
     languageOptions: {
         ecmaVersion: number;
@@ -11,6 +15,11 @@ declare const _default: {
         globals: any;
     };
     plugins: {
+        '@lark-apaas'?: {
+            rules: {
+                'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
+            };
+        } | undefined;
         'react-hooks': any;
         import: any;
     };
@@ -25,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,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.looseRestrictSyntaxRules = void 0;
 const globals = require('globals');
 const reactHooks = require('eslint-plugin-react-hooks');
 const tseslint = require('typescript-eslint');
 const importPlugin = require('eslint-plugin-import');
+const custom_eslint_rules_1 = require("../../../custom-eslint-rules");
 // 检查是否启用宽松 lint 模式
 const isLooseMode = process.env.FORCE_FRAMEWORK_LINT_LOOSE_MODE === 'true';
 // 基础语法规则：所有模式都启用（包括 loose 模式）
@@ -29,6 +31,20 @@ const baseSyntaxRules = [
         message: "Please don't use relative paths in <a> tags. Use NavLink from 'react-router-dom' instead.",
     },
 ];
+// loose模式特化的规则
+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. 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. Do not add <div>, <BrowserRouter> or other wrappers. You can only modify routes inside <Routes> (add/edit/remove <Route> elements).',
+    },
+];
 // 严格语法规则：仅正常模式启用，loose 模式下不启用
 const strictSyntaxRules = [
     // 限制使用 fetch（推荐使用生成的 API Client）
@@ -78,15 +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 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,
@@ -104,6 +128,7 @@ exports.default = {
     plugins: {
         'react-hooks': reactHooks,
         import: importPlugin,
+        ...(isLooseMode ? looseSpecificPlugins : {}),
     },
     settings: {
         'import/resolver': {
@@ -149,8 +174,26 @@ exports.default = {
                 ],
             },
         ],
-        'no-restricted-syntax': ['error', ...baseSyntaxRules, ...(isLooseMode ? [] : strictSyntaxRules)],
+        'no-restricted-syntax': [
+            'error',
+            ...baseSyntaxRules,
+            // 注意：严格模式的 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;
@@ -14,6 +14,11 @@ export declare const eslintPresets: {
             globals: any;
         };
         plugins: {
+            '@lark-apaas'?: {
+                rules: {
+                    'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
+                };
+            } | undefined;
             'react-hooks': any;
             import: any;
         };
@@ -29,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.2",
+  "version": "1.1.3-beta.0",
   "files": [
     "lib"
   ],
@@ -18,6 +18,7 @@
     "build": "tsc && npm run copy:json",
     "copy:json": "node scripts/copy-json.js",
     "watch": "tsc --watch",
+    "test": "vitest",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
@@ -33,8 +34,11 @@
     "tailwindcss-animate": "^1.0.7"
   },
   "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-react": "^7.24.0",
     "@types/eslint": "^9.6.0",
     "eslint": "^9.35.0",
+    "styled-jsx": "^5.1.6",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.44.0"
   },