@lark-apaas/fullstack-presets 1.1.5-beta.24 → 1.1.5-beta.25

package/lib/custom-eslint-rules/index.d.ts

@@ -3,4 +3,7 @@ export declare const customRules: {
     'require-app-container': import("eslint").Rule.RuleModule;
     'no-direct-capability-api': import("eslint").Rule.RuleModule;
     'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
+    'no-welcome-index-route': import("eslint").Rule.RuleModule;
+    'require-index-route': import("eslint").Rule.RuleModule;
+    'no-duplicate-route-component': import("eslint").Rule.RuleModule;
 };

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

@@ -8,9 +8,15 @@ const no_nested_styled_jsx_1 = __importDefault(require("./no-nested-styled-jsx")
 const require_app_container_1 = __importDefault(require("./require-app-container"));
 const no_direct_capability_api_1 = __importDefault(require("./no-direct-capability-api"));
 const require_scroll_reveal_hook_1 = __importDefault(require("./require-scroll-reveal-hook"));
+const no_welcome_index_route_1 = __importDefault(require("./no-welcome-index-route"));
+const require_index_route_1 = __importDefault(require("./require-index-route"));
+const no_duplicate_route_component_1 = __importDefault(require("./no-duplicate-route-component"));
 exports.customRules = {
     'no-nested-styled-jsx': no_nested_styled_jsx_1.default,
     'require-app-container': require_app_container_1.default,
     'no-direct-capability-api': no_direct_capability_api_1.default,
     'require-scroll-reveal-hook': require_scroll_reveal_hook_1.default,
+    'no-welcome-index-route': no_welcome_index_route_1.default,
+    'require-index-route': require_index_route_1.default,
+    'no-duplicate-route-component': no_duplicate_route_component_1.default,
 };

package/lib/custom-eslint-rules/no-duplicate-route-component.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ESLint rule to disallow duplicate component usage across Route elements within a <Routes>.
+ *
+ * This rule enforces that within any <Routes> element, each JSX component used as the
+ * `element` prop of a <Route> must be unique. Reusing the same component across
+ * multiple routes leads to confusing routing logic.
+ *
+ * Skips:
+ * - Routes without an `element` attribute
+ * - element values that are not JSX elements (e.g., variables, null, false)
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/custom-eslint-rules/no-duplicate-route-component.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Serialize a JSXIdentifier or JSXMemberExpression to a stable string key.
+// e.g. JSXIdentifier "Home" → "Home"
+//      JSXMemberExpression "Pages.Home" → "Pages.Home"
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getJSXName(node) {
+    if (!node)
+        return null;
+    if (node.type === 'JSXIdentifier')
+        return node.name;
+    if (node.type === 'JSXMemberExpression') {
+        const obj = getJSXName(node.object);
+        const prop = node.property?.name;
+        if (obj && prop)
+            return `${obj}.${prop}`;
+    }
+    return null;
+}
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow the same component being used as the element of multiple Routes within a <Routes>',
+            category: 'Best Practices',
+            recommended: true,
+        },
+        messages: {
+            duplicateRouteComponent: "Component <{{componentName}} /> is already used in another Route's element. Remove the duplicate—keep the index Route if present.",
+        },
+        schema: [],
+    },
+    create(context) {
+        // Stack of seen-component maps, one entry per nested <Routes>
+        const routesStack = [];
+        return {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            JSXElement(node) {
+                const tagName = node.openingElement?.name?.name;
+                if (tagName === 'Routes') {
+                    routesStack.push(new Map());
+                    return;
+                }
+                if (tagName !== 'Route')
+                    return;
+                if (routesStack.length === 0)
+                    return;
+                const seenComponents = routesStack[routesStack.length - 1];
+                const attributes = node.openingElement?.attributes || [];
+                // Find the `element` attribute
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const elementAttr = attributes.find(
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                (attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'element');
+                if (!elementAttr)
+                    return;
+                // element value must be a JSXExpressionContainer containing a JSXElement
+                const attrValue = elementAttr.value;
+                if (attrValue?.type !== 'JSXExpressionContainer')
+                    return;
+                const expression = attrValue.expression;
+                if (!expression || expression.type !== 'JSXElement')
+                    return;
+                const componentName = getJSXName(expression.openingElement?.name);
+                if (!componentName)
+                    return;
+                if (seenComponents.has(componentName)) {
+                    context.report({
+                        node: elementAttr,
+                        messageId: 'duplicateRouteComponent',
+                        data: { componentName },
+                    });
+                }
+                else {
+                    seenComponents.set(componentName, elementAttr);
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            'JSXElement:exit'(node) {
+                if (node.openingElement?.name?.name === 'Routes') {
+                    routesStack.pop();
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

package/lib/custom-eslint-rules/no-welcome-index-route.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ESLint rule to disallow Welcome or PagePlaceholder components as the default home page route.
+ *
+ * This rule enforces that the first-level index route (the actual home page at "/")
+ * should use an actual page component rather than placeholder components from the framework.
+ *
+ * Only checks the first-level index route nested directly under a parent Route (typically Layout).
+ * Only flags Welcome/PagePlaceholder if they are imported from @lark-apaas/client-toolkit.
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/custom-eslint-rules/no-welcome-index-route.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow Welcome or PagePlaceholder from @lark-apaas/client-toolkit as the default home page route element',
+            category: 'Best Practices',
+            recommended: true,
+        },
+        messages: {
+            noWelcomeIndex: 'Index route should not use {{componentName}} from @lark-apaas/client-toolkit as the element. Please create and use your own home page component (e.g., HomePage, Dashboard).',
+        },
+        schema: [],
+    },
+    create(context) {
+        // Track imports from @lark-apaas/client-toolkit
+        const toolkitImports = new Set();
+        return {
+            ImportDeclaration(node) {
+                const importNode = node;
+                const source = importNode.source?.value;
+                // Check if importing from @lark-apaas/client-toolkit (any subpath)
+                if (typeof source === 'string' &&
+                    source.startsWith('@lark-apaas/client-toolkit')) {
+                    // Collect all imported names
+                    importNode.specifiers?.forEach(specifier => {
+                        if (specifier.type === 'ImportSpecifier' &&
+                            specifier.imported?.name) {
+                            toolkitImports.add(specifier.imported.name);
+                        }
+                    });
+                }
+            },
+            JSXElement(node) {
+                const element = node;
+                const openingElement = element.openingElement;
+                if (!openingElement)
+                    return;
+                const elementName = openingElement.name;
+                // Check if this is a <Route> element
+                if (elementName.type !== 'JSXIdentifier' ||
+                    elementName.name !== 'Route') {
+                    return;
+                }
+                // Check if it has an index prop that is truthy
+                const indexAttr = openingElement.attributes.find(attr => attr.type === 'JSXAttribute' &&
+                    attr.name?.type === 'JSXIdentifier' &&
+                    attr.name?.name === 'index');
+                // If no index attribute, skip this route
+                if (!indexAttr) {
+                    return;
+                }
+                // Check if index={false} explicitly
+                const indexValue = indexAttr.value;
+                if (indexValue?.type === 'JSXExpressionContainer' &&
+                    indexValue.expression?.type === 'Literal' &&
+                    indexValue.expression.value === false) {
+                    return;
+                }
+                // Check if this is a first-level index route (nested under exactly one parent Route)
+                // The structure should be: <Routes> -> <Route element={<Layout />}> -> <Route index>
+                let routeParentCount = 0;
+                let current = element.parent;
+                while (current) {
+                    if (current.type === 'JSXElement') {
+                        const currentElement = current;
+                        const currentOpeningElement = currentElement.openingElement;
+                        const currentElementName = currentOpeningElement?.name;
+                        if (currentElementName?.type === 'JSXIdentifier' &&
+                            currentElementName.name === 'Route') {
+                            routeParentCount++;
+                        }
+                        else if (currentElementName?.type === 'JSXIdentifier' &&
+                            currentElementName.name === 'Routes') {
+                            // Stop when we reach Routes
+                            break;
+                        }
+                    }
+                    current = current.parent;
+                }
+                // Only check if this is a first-level route (exactly 1 parent Route)
+                // This corresponds to the default home page pattern:
+                // <Routes><Route element={<Layout />}><Route index /></Route></Routes>
+                if (routeParentCount !== 1) {
+                    return;
+                }
+                // Find the element prop
+                const elementProp = openingElement.attributes.find(attr => attr.type === 'JSXAttribute' &&
+                    attr.name?.type === 'JSXIdentifier' &&
+                    attr.name?.name === 'element');
+                if (!elementProp) {
+                    return;
+                }
+                // Check if the element prop value is a JSXExpressionContainer with a JSXElement
+                const propValue = elementProp.value;
+                if (propValue?.type === 'JSXExpressionContainer' &&
+                    propValue.expression?.type === 'JSXElement') {
+                    const jsxElement = propValue.expression;
+                    const jsxOpeningElement = jsxElement.openingElement;
+                    const jsxElementName = jsxOpeningElement?.name;
+                    // Check if the component name is Welcome or PagePlaceholder
+                    if (jsxElementName?.type === 'JSXIdentifier' &&
+                        (jsxElementName.name === 'Welcome' ||
+                            jsxElementName.name === 'PagePlaceholder')) {
+                        const componentName = jsxElementName.name;
+                        // Only report if this component was imported from @lark-apaas/client-toolkit
+                        if (toolkitImports.has(componentName)) {
+                            context.report({
+                                node: elementProp,
+                                messageId: 'noWelcomeIndex',
+                                data: {
+                                    componentName,
+                                },
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

package/lib/custom-eslint-rules/require-index-route.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ESLint rule to require a default index route in RoutesComponent.
+ *
+ * This rule enforces that the RoutesComponent must have a first-level index route
+ * to handle the default "/" path. This ensures users don't see a 404 when visiting
+ * the application root.
+ *
+ * Valid configurations:
+ * 1. <Route index element={...} /> (first-level, nested under one parent Route)
+ * 2. <Route path="/" element={...} /> (first-level or top-level)
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

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

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require a default index route in RoutesComponent to handle the root path',
+            category: 'Best Practices',
+            recommended: true,
+        },
+        messages: {
+            missingIndexRoute: 'RoutesComponent is missing a default home page route. Add either:\n  - <Route index element={<HomePage />} /> (nested under Layout)\n  - <Route path="/" element={<HomePage />} /> (at any level)',
+        },
+        schema: [],
+    },
+    create(context) {
+        let inRoutesComponent = false;
+        let hasDefaultRoute = false;
+        let routeDepth = 0;
+        return {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            VariableDeclarator(node) {
+                // Check if this is RoutesComponent
+                if (node.id?.name === 'RoutesComponent') {
+                    inRoutesComponent = true;
+                    hasDefaultRoute = false;
+                    routeDepth = 0;
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            'VariableDeclarator:exit'(node) {
+                if (node.id?.name === 'RoutesComponent') {
+                    if (!hasDefaultRoute) {
+                        context.report({
+                            node,
+                            messageId: 'missingIndexRoute',
+                        });
+                    }
+                    inRoutesComponent = false;
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            JSXElement(node) {
+                if (!inRoutesComponent)
+                    return;
+                const elementName = node.openingElement?.name?.name;
+                // Track Route depth
+                if (elementName === 'Route') {
+                    routeDepth++;
+                    // Only check first-level routes (depth 1 or 2)
+                    // depth 1: <Routes><Route index /></Routes>
+                    // depth 2: <Routes><Route><Route index /></Route></Routes>
+                    if (routeDepth <= 2) {
+                        const attributes = node.openingElement?.attributes || [];
+                        // Check for index attribute
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const indexAttr = attributes.find((attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'index');
+                        if (indexAttr) {
+                            // Make sure it's not index={false}
+                            const isIndexFalse = indexAttr.value?.type === 'JSXExpressionContainer' &&
+                                indexAttr.value.expression?.type === 'Literal' &&
+                                indexAttr.value.expression.value === false;
+                            if (!isIndexFalse) {
+                                hasDefaultRoute = true;
+                            }
+                        }
+                        // Check for path="/"
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const pathAttr = attributes.find((attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'path');
+                        if (pathAttr) {
+                            const value = pathAttr.value;
+                            // Handle path="/"
+                            if (value?.type === 'Literal' && value.value === '/') {
+                                hasDefaultRoute = true;
+                            }
+                            // Handle path={"/"}
+                            if (value?.type === 'JSXExpressionContainer' &&
+                                value.expression?.type === 'Literal' &&
+                                value.expression.value === '/') {
+                                hasDefaultRoute = true;
+                            }
+                        }
+                    }
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            'JSXElement:exit'(node) {
+                if (!inRoutesComponent)
+                    return;
+                const elementName = node.openingElement?.name?.name;
+                if (elementName === 'Route') {
+                    routeDepth--;
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

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

@@ -19,6 +19,9 @@ declare const _default: {
                 'require-app-container': import("eslint").Rule.RuleModule;
                 'no-direct-capability-api': import("eslint").Rule.RuleModule;
                 'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
+                'no-welcome-index-route': import("eslint").Rule.RuleModule;
+                'require-index-route': import("eslint").Rule.RuleModule;
+                'no-duplicate-route-component': import("eslint").Rule.RuleModule;
             };
         };
     };

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

@@ -22,6 +22,9 @@ export declare const eslintPresets: {
                     'require-app-container': import("eslint").Rule.RuleModule;
                     'no-direct-capability-api': import("eslint").Rule.RuleModule;
                     'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
+                    'no-welcome-index-route': import("eslint").Rule.RuleModule;
+                    'require-index-route': import("eslint").Rule.RuleModule;
+                    'no-duplicate-route-component': import("eslint").Rule.RuleModule;
                 };
             };
         };

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

@@ -15,16 +15,19 @@ declare const _default: ({
         globals: any;
     };
     plugins: {
+        'react-hooks': any;
+        import: any;
         '@lark-apaas': {
             rules: {
                 'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
                 'require-app-container': import("eslint").Rule.RuleModule;
                 'no-direct-capability-api': import("eslint").Rule.RuleModule;
                 'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
+                'no-welcome-index-route': import("eslint").Rule.RuleModule;
+                'require-index-route': import("eslint").Rule.RuleModule;
+                'no-duplicate-route-component': import("eslint").Rule.RuleModule;
             };
         };
-        'react-hooks': any;
-        import: any;
     };
     settings: {
         'import/resolver': {
@@ -45,6 +48,9 @@ declare const _default: ({
             selector: string;
             message: string;
         })[];
+        '@lark-apaas/no-welcome-index-route': string;
+        '@lark-apaas/require-index-route': string;
+        '@lark-apaas/no-duplicate-route-component': string;
     };
 } | null)[];
 export default _default;

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

@@ -114,10 +114,11 @@ const strictSyntaxRules = [
         selector: "CallExpression[callee.name='confirm']",
     },
 ];
-const looseSpecificPlugins = {
-    '@lark-apaas': { rules: custom_eslint_rules_1.customRules },
-};
-// 宽松模式下覆盖的规则
+// 宽松模式专用，请勿删除
+const looseSpecificPlugins = {};
+// 宽松模式专用，请勿删除
+const looseSpecificRules = {};
+// 宽松模式下覆盖的规则（关闭非关键规则）
 const looseOverrideRules = isLooseMode
     ? {
         '@typescript-eslint/no-unsafe-function-type': 'off',
@@ -148,6 +149,7 @@ const baseConfig = {
     plugins: {
         'react-hooks': reactHooks,
         import: importPlugin,
+        '@lark-apaas': { rules: custom_eslint_rules_1.customRules },
         ...looseSpecificPlugins,
     },
     settings: {
@@ -209,6 +211,8 @@ const baseConfig = {
             // 注意：严格模式的 strictSyntaxRules 仍然应用于所有文件
             ...(isLooseMode ? [] : strictSyntaxRules),
         ],
+        // 宽松模式专用规则
+        ...looseSpecificRules,
         // 宽松模式下覆盖上述规则
         ...looseOverrideRules,
     },
@@ -225,6 +229,9 @@ const appTsxConfig = isLooseMode
                 ...baseSyntaxRules,
                 ...exports.looseRestrictSyntaxRules,
             ],
+            '@lark-apaas/no-welcome-index-route': 'error',
+            '@lark-apaas/require-index-route': 'error',
+            '@lark-apaas/no-duplicate-route-component': 'error',
         },
     }
     : null;

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

@@ -14,16 +14,19 @@ export declare const eslintPresets: {
             globals: any;
         };
         plugins: {
+            'react-hooks': any;
+            import: any;
             '@lark-apaas': {
                 rules: {
                     'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
                     'require-app-container': import("eslint").Rule.RuleModule;
                     'no-direct-capability-api': import("eslint").Rule.RuleModule;
                     'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
+                    'no-welcome-index-route': import("eslint").Rule.RuleModule;
+                    'require-index-route': import("eslint").Rule.RuleModule;
+                    'no-duplicate-route-component': import("eslint").Rule.RuleModule;
                 };
             };
-            'react-hooks': any;
-            import: any;
         };
         settings: {
             'import/resolver': {
@@ -44,6 +47,9 @@ export declare const eslintPresets: {
                 selector: string;
                 message: string;
             })[];
+            '@lark-apaas/no-welcome-index-route': string;
+            '@lark-apaas/require-index-route': string;
+            '@lark-apaas/no-duplicate-route-component': string;
         };
     } | null)[] | {
         ignores: string[];

package/package.json

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