@qlover/create-app 0.10.6 → 0.12.0

package/dist/templates/next-app/eslint.config.mjs

@@ -5,6 +5,7 @@ import importPlugin from 'eslint-plugin-import';
 import prettierPlugin from 'eslint-plugin-prettier';
 import unusedImports from 'eslint-plugin-unused-imports';
 import qloverEslint from '@qlover/eslint-plugin';
+import tseslint from 'typescript-eslint';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -106,7 +107,7 @@ const eslintConfig = [
     rules: {
       '@qlover-eslint/ts-class-method-return': 'error',
       '@qlover-eslint/ts-class-member-accessibility': 'error',
-      '@qlover-eslint/ts-class-override': 'error',
+      '@qlover-eslint/ts-class-override': 'off',
       '@qlover-eslint/require-root-testid': ['error', {
         exclude: ['/Provider$/']
       }],
@@ -188,6 +189,80 @@ const eslintConfig = [
       'import/no-default-export': 'error',
     }
   },
+  // TypeScript files with type checking for ts-class-override rule
+  // The ts-class-override rule requires full type information to accurately detect:
+  // - Methods that override parent class methods (via extends)
+  // - Methods that implement interface methods (via implements)
+  // Without type checking, the rule falls back to AST-based heuristics which are less accurate
+  // This separate config block enables type checking only for TypeScript files to provide
+  // accurate override detection while maintaining good performance
+  ...tseslint.configs.recommendedTypeChecked.map((config) => ({
+    ...config,
+    files: ['src/**/*.{ts,tsx}'],
+    ignores: [
+      '**/dist/**',
+      '**/build/**',
+      '**/ts-build/**',
+      '**/node_modules/**',
+      '**/.nx/**',
+      '**/.cache/**',
+      '**/coverage/**',
+      '**/*.d.ts',
+      '**/*.config.ts',
+      '**/*.test.ts',
+      '**/__mocks__/**',
+      '**/__tests__/**',
+      '**/*.spec.ts',
+      ...(config.ignores || [])
+    ],
+    languageOptions: {
+      ...config.languageOptions,
+      parserOptions: {
+        ...config.languageOptions?.parserOptions,
+        project: './tsconfig.json',
+        tsconfigRootDir: __dirname
+      }
+    },
+    plugins: {
+      ...config.plugins,
+      '@qlover-eslint': qloverEslint
+    },
+    rules: {
+      ...config.rules,
+      // Enable ts-class-override rule with full type information
+      // This rule is disabled in the base config above and only enabled here where
+      // type information is available, ensuring accurate detection of override relationships
+      '@qlover-eslint/ts-class-override': 'error',
+      // Disable other type-checked rules to avoid performance impact
+      // We only need type checking for ts-class-override, so we disable other
+      // type-aware rules that would slow down linting without providing value
+      '@typescript-eslint/ban-ts-comment': 'off',
+      '@typescript-eslint/restrict-template-expressions': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unnecessary-type-assertion': 'off',
+      '@typescript-eslint/no-redundant-type-constituents': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/no-empty-object-type': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/no-unsafe-enum-comparison': 'off',
+      '@typescript-eslint/no-unsafe-literal-comparison': 'off',
+      '@typescript-eslint/no-unsafe-nullish-coalescing': 'off',
+      '@typescript-eslint/no-unsafe-optional-chaining': 'off',
+      '@typescript-eslint/unbound-method': 'off',
+      '@typescript-eslint/await-thenable': 'off',
+      '@typescript-eslint/no-floating-promises': 'off',
+      '@typescript-eslint/no-misused-promises': 'off',
+      '@typescript-eslint/require-await': 'off',
+      '@typescript-eslint/no-base-to-string': 'off',
+      '@typescript-eslint/prefer-promise-reject-errors': 'off',
+      '@typescript-eslint/no-duplicate-type-constituents': 'off',
+      // Disable @typescript-eslint/no-unused-vars as we use unused-imports/no-unused-vars instead
+      '@typescript-eslint/no-unused-vars': 'off',
+      '@typescript-eslint/only-throw-error': 'off'
+    }
+  })),
   // 为特定文件允许 default export
   {
     files: [

package/dist/templates/next-app/package.json

@@ -69,6 +69,7 @@
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-unused-imports": "^4.2.0",
     "prettier": "^3.6.2",
+    "typescript-eslint": "^8.15.0",
     "tailwindcss": "^4",
     "typescript": "^5"
   },

package/dist/templates/react-app/docs/en/test-guide.md

@@ -627,7 +627,20 @@ describe('AsyncService', () => {
 
 ### Type Safety Testing
 
+TypeScript project tests should not only verify runtime behavior but also ensure the correctness of the type system. Vitest provides the `expectTypeOf` utility for compile-time type checking.
+
+#### Why Type Testing?
+
+1. **Type Inference Validation**: Ensure TypeScript correctly infers complex types
+2. **Generic Constraint Checking**: Verify generic parameter constraints
+3. **Type Compatibility**: Ensure type definitions match actual usage
+4. **API Contract Guarantee**: Prevent breaking changes in type definitions
+
+#### Basic Type Testing
+
 ```typescript
+import { describe, it, expectTypeOf } from 'vitest';
+
 describe('TypeSafetyTests', () => {
   it('should maintain type safety', () => {
     const processor = new DataProcessor<User>();
@@ -636,9 +649,190 @@ describe('TypeSafetyTests', () => {
     expectTypeOf(processor.process).parameter(0).toEqualTypeOf<User>();
     expectTypeOf(processor.process).returns.toEqualTypeOf<ProcessedUser>();
   });
+
+  it('should infer correct return types', () => {
+    const result = getData();
+    
+    // Verify return type
+    expectTypeOf(result).toEqualTypeOf<{ id: number; name: string }>();
+    expectTypeOf(result).not.toEqualTypeOf<{ id: string; name: string }>();
+  });
+
+  it('should validate parameter types', () => {
+    function processUser(user: User): void {
+      // implementation
+    }
+
+    // Verify parameter type
+    expectTypeOf(processUser).parameter(0).toMatchTypeOf<{ id: number }>();
+    expectTypeOf(processUser).parameter(0).toHaveProperty('id');
+  });
+});
+```
+
+#### Generic Type Testing
+
+```typescript
+describe('Generic Type Tests', () => {
+  it('should work with generic constraints', () => {
+    class Storage<T extends { id: number }> {
+      store(item: T): T {
+        return item;
+      }
+    }
+
+    const storage = new Storage<User>();
+    
+    // Verify generic type
+    expectTypeOf(storage.store).parameter(0).toMatchTypeOf<User>();
+    expectTypeOf(storage.store).returns.toMatchTypeOf<User>();
+  });
+
+  it('should validate complex generic types', () => {
+    type ApiResponse<T> = {
+      data: T;
+      status: number;
+      message?: string;
+    };
+
+    const response: ApiResponse<User[]> = {
+      data: [],
+      status: 200
+    };
+
+    // Verify nested generic type
+    expectTypeOf(response).toMatchTypeOf<ApiResponse<User[]>>();
+    expectTypeOf(response.data).toEqualTypeOf<User[]>();
+  });
+});
+```
+
+#### Union and Intersection Type Testing
+
+```typescript
+describe('Union and Intersection Types', () => {
+  it('should handle union types correctly', () => {
+    type Result = Success | Error;
+    type Success = { status: 'success'; data: string };
+    type Error = { status: 'error'; message: string };
+
+    function handleResult(result: Result): void {
+      // implementation
+    }
+
+    // Verify union type
+    expectTypeOf(handleResult).parameter(0).toMatchTypeOf<Success>();
+    expectTypeOf(handleResult).parameter(0).toMatchTypeOf<Error>();
+  });
+
+  it('should handle intersection types correctly', () => {
+    type Timestamped = { createdAt: Date; updatedAt: Date };
+    type UserWithTimestamp = User & Timestamped;
+
+    const user: UserWithTimestamp = {
+      id: 1,
+      name: 'John',
+      createdAt: new Date(),
+      updatedAt: new Date()
+    };
+
+    // Verify intersection type contains all properties
+    expectTypeOf(user).toHaveProperty('id');
+    expectTypeOf(user).toHaveProperty('name');
+    expectTypeOf(user).toHaveProperty('createdAt');
+    expectTypeOf(user).toHaveProperty('updatedAt');
+  });
 });
 ```
 
+#### Type Narrowing Testing
+
+```typescript
+describe('Type Narrowing Tests', () => {
+  it('should validate type guards', () => {
+    function isString(value: unknown): value is string {
+      return typeof value === 'string';
+    }
+
+    const value: unknown = 'test';
+    
+    if (isString(value)) {
+      // Within this scope, value should be narrowed to string type
+      expectTypeOf(value).toEqualTypeOf<string>();
+    }
+  });
+
+  it('should validate discriminated unions', () => {
+    type Shape = 
+      | { kind: 'circle'; radius: number }
+      | { kind: 'rectangle'; width: number; height: number };
+
+    function getArea(shape: Shape): number {
+      if (shape.kind === 'circle') {
+        // In this branch, shape should be narrowed to circle type
+        expectTypeOf(shape).toHaveProperty('radius');
+        expectTypeOf(shape).not.toHaveProperty('width');
+        return Math.PI * shape.radius ** 2;
+      } else {
+        // In this branch, shape should be narrowed to rectangle type
+        expectTypeOf(shape).toHaveProperty('width');
+        expectTypeOf(shape).toHaveProperty('height');
+        return shape.width * shape.height;
+      }
+    }
+  });
+});
+```
+
+#### Practical Recommendations
+
+1. **Combine with Runtime Tests**: Type tests should complement runtime tests
+
+```typescript
+describe('Combined Runtime and Type Tests', () => {
+  it('should validate both runtime behavior and types', () => {
+    function add(a: number, b: number): number {
+      return a + b;
+    }
+
+    // Type test
+    expectTypeOf(add).parameter(0).toEqualTypeOf<number>();
+    expectTypeOf(add).returns.toEqualTypeOf<number>();
+
+    // Runtime test
+    expect(add(1, 2)).toBe(3);
+    expect(add(-1, 1)).toBe(0);
+  });
+});
+```
+
+2. **Test Type Inference**: Ensure TypeScript correctly infers types, avoid overusing `any`
+
+```typescript
+describe('Type Inference Tests', () => {
+  it('should infer types correctly', () => {
+    const data = { id: 1, name: 'John' };
+    
+    // Verify inferred type
+    expectTypeOf(data).toEqualTypeOf<{ id: number; name: string }>();
+    expectTypeOf(data.id).toEqualTypeOf<number>();
+    expectTypeOf(data.name).toEqualTypeOf<string>();
+  });
+});
+```
+
+3. **Use TypeScript Compiler Checks**: Run `tsc --noEmit` in CI to ensure no type errors
+
+```bash
+# Add script in package.json
+{
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "pnpm type-check && vitest run"
+  }
+}
+```
+
 ---
 
 ## Performance Testing

package/dist/templates/react-app/docs/zh/test-guide.md

@@ -627,7 +627,20 @@ describe('AsyncService', () => {
 
 ### 类型安全测试
 
+TypeScript 项目的测试不仅要验证运行时行为，还应该确保类型系统的正确性。Vitest 提供了 `expectTypeOf` 工具来进行编译时类型检查。
+
+#### 为什么需要类型测试？
+
+1. **类型推断验证**：确保 TypeScript 能正确推断复杂类型
+2. **泛型约束检查**：验证泛型参数的约束条件
+3. **类型兼容性**：确保类型定义与实际使用匹配
+4. **API 契约保证**：防止类型定义的破坏性变更
+
+#### 基础类型测试
+
 ```typescript
+import { describe, it, expectTypeOf } from 'vitest';
+
 describe('TypeSafetyTests', () => {
   it('should maintain type safety', () => {
     const processor = new DataProcessor<User>();
@@ -636,9 +649,190 @@ describe('TypeSafetyTests', () => {
     expectTypeOf(processor.process).parameter(0).toEqualTypeOf<User>();
     expectTypeOf(processor.process).returns.toEqualTypeOf<ProcessedUser>();
   });
+
+  it('should infer correct return types', () => {
+    const result = getData();
+    
+    // 验证返回值类型
+    expectTypeOf(result).toEqualTypeOf<{ id: number; name: string }>();
+    expectTypeOf(result).not.toEqualTypeOf<{ id: string; name: string }>();
+  });
+
+  it('should validate parameter types', () => {
+    function processUser(user: User): void {
+      // implementation
+    }
+
+    // 验证参数类型
+    expectTypeOf(processUser).parameter(0).toMatchTypeOf<{ id: number }>();
+    expectTypeOf(processUser).parameter(0).toHaveProperty('id');
+  });
+});
+```
+
+#### 泛型类型测试
+
+```typescript
+describe('Generic Type Tests', () => {
+  it('should work with generic constraints', () => {
+    class Storage<T extends { id: number }> {
+      store(item: T): T {
+        return item;
+      }
+    }
+
+    const storage = new Storage<User>();
+    
+    // 验证泛型类型
+    expectTypeOf(storage.store).parameter(0).toMatchTypeOf<User>();
+    expectTypeOf(storage.store).returns.toMatchTypeOf<User>();
+  });
+
+  it('should validate complex generic types', () => {
+    type ApiResponse<T> = {
+      data: T;
+      status: number;
+      message?: string;
+    };
+
+    const response: ApiResponse<User[]> = {
+      data: [],
+      status: 200
+    };
+
+    // 验证嵌套泛型类型
+    expectTypeOf(response).toMatchTypeOf<ApiResponse<User[]>>();
+    expectTypeOf(response.data).toEqualTypeOf<User[]>();
+  });
+});
+```
+
+#### 联合类型与交叉类型测试
+
+```typescript
+describe('Union and Intersection Types', () => {
+  it('should handle union types correctly', () => {
+    type Result = Success | Error;
+    type Success = { status: 'success'; data: string };
+    type Error = { status: 'error'; message: string };
+
+    function handleResult(result: Result): void {
+      // implementation
+    }
+
+    // 验证联合类型
+    expectTypeOf(handleResult).parameter(0).toMatchTypeOf<Success>();
+    expectTypeOf(handleResult).parameter(0).toMatchTypeOf<Error>();
+  });
+
+  it('should handle intersection types correctly', () => {
+    type Timestamped = { createdAt: Date; updatedAt: Date };
+    type UserWithTimestamp = User & Timestamped;
+
+    const user: UserWithTimestamp = {
+      id: 1,
+      name: 'John',
+      createdAt: new Date(),
+      updatedAt: new Date()
+    };
+
+    // 验证交叉类型包含所有属性
+    expectTypeOf(user).toHaveProperty('id');
+    expectTypeOf(user).toHaveProperty('name');
+    expectTypeOf(user).toHaveProperty('createdAt');
+    expectTypeOf(user).toHaveProperty('updatedAt');
+  });
 });
 ```
 
+#### 类型窄化测试
+
+```typescript
+describe('Type Narrowing Tests', () => {
+  it('should validate type guards', () => {
+    function isString(value: unknown): value is string {
+      return typeof value === 'string';
+    }
+
+    const value: unknown = 'test';
+    
+    if (isString(value)) {
+      // 在此作用域内，value 应该被窄化为 string 类型
+      expectTypeOf(value).toEqualTypeOf<string>();
+    }
+  });
+
+  it('should validate discriminated unions', () => {
+    type Shape = 
+      | { kind: 'circle'; radius: number }
+      | { kind: 'rectangle'; width: number; height: number };
+
+    function getArea(shape: Shape): number {
+      if (shape.kind === 'circle') {
+        // 在此分支，shape 应该被窄化为 circle 类型
+        expectTypeOf(shape).toHaveProperty('radius');
+        expectTypeOf(shape).not.toHaveProperty('width');
+        return Math.PI * shape.radius ** 2;
+      } else {
+        // 在此分支，shape 应该被窄化为 rectangle 类型
+        expectTypeOf(shape).toHaveProperty('width');
+        expectTypeOf(shape).toHaveProperty('height');
+        return shape.width * shape.height;
+      }
+    }
+  });
+});
+```
+
+#### 实用建议
+
+1. **结合运行时测试**：类型测试应该与运行时测试相辅相成
+
+```typescript
+describe('Combined Runtime and Type Tests', () => {
+  it('should validate both runtime behavior and types', () => {
+    function add(a: number, b: number): number {
+      return a + b;
+    }
+
+    // 类型测试
+    expectTypeOf(add).parameter(0).toEqualTypeOf<number>();
+    expectTypeOf(add).returns.toEqualTypeOf<number>();
+
+    // 运行时测试
+    expect(add(1, 2)).toBe(3);
+    expect(add(-1, 1)).toBe(0);
+  });
+});
+```
+
+2. **测试类型推断**：确保 TypeScript 能正确推断类型，避免过度使用 `any`
+
+```typescript
+describe('Type Inference Tests', () => {
+  it('should infer types correctly', () => {
+    const data = { id: 1, name: 'John' };
+    
+    // 验证推断的类型
+    expectTypeOf(data).toEqualTypeOf<{ id: number; name: string }>();
+    expectTypeOf(data.id).toEqualTypeOf<number>();
+    expectTypeOf(data.name).toEqualTypeOf<string>();
+  });
+});
+```
+
+3. **使用 TypeScript 编译器检查**：在 CI 中运行 `tsc --noEmit` 确保没有类型错误
+
+```bash
+# 在 package.json 中添加脚本
+{
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "pnpm type-check && vitest run"
+  }
+}
+```
+
 ---
 
 ## 性能测试

package/dist/templates/react-app/eslint.config.mjs

@@ -92,17 +92,14 @@ const eslintConfig = [
       'storybook-static/**'
     ]
   },
+
   {
     files: ['**/*.{js,jsx,ts,tsx}'],
     languageOptions: {
       parser: tseslint.parser,
       parserOptions: {
-        project: [
-          './tsconfig.app.json',
-          './tsconfig.node.json',
-          './tsconfig.test.json',
-          './tsconfig.e2e.json'
-        ],
+        // Note: 'project' is removed here to avoid conflict with projectService in the type-checked config below
+        // TypeScript files will get type information from the recommendedTypeChecked config
         tsconfigRootDir: __dirname
       }
     },
@@ -116,7 +113,7 @@ const eslintConfig = [
     rules: {
       '@qlover-eslint/ts-class-method-return': 'error',
       '@qlover-eslint/ts-class-member-accessibility': 'error',
-      '@qlover-eslint/ts-class-override': 'error',
+      '@qlover-eslint/ts-class-override': 'off',
       '@qlover-eslint/require-root-testid': [
         'error',
         {
@@ -202,6 +199,81 @@ const eslintConfig = [
       'import/no-default-export': 'error'
     }
   },
+  
+  // TypeScript files with type checking for ts-class-override rule
+  // The ts-class-override rule requires full type information to accurately detect:
+  // - Methods that override parent class methods (via extends)
+  // - Methods that implement interface methods (via implements)
+  // Without type checking, the rule falls back to AST-based heuristics which are less accurate
+  // This separate config block enables type checking only for TypeScript files to provide
+  // accurate override detection while maintaining good performance
+  ...tseslint.configs.recommendedTypeChecked.map((config) => ({
+    ...config,
+    files: ['src/**/*.{ts,tsx}'],
+    ignores: [
+      '**/dist/**',
+      '**/build/**',
+      '**/ts-build/**',
+      '**/node_modules/**',
+      '**/.nx/**',
+      '**/.cache/**',
+      '**/coverage/**',
+      '**/*.d.ts',
+      '**/*.config.ts',
+      '**/*.test.ts',
+      '**/__mocks__/**',
+      '**/__tests__/**',
+      '**/*.spec.ts',
+      ...(config.ignores || [])
+    ],
+    languageOptions: {
+      ...config.languageOptions,
+      parserOptions: {
+        ...config.languageOptions?.parserOptions,
+        project: './tsconfig.app.json',
+        tsconfigRootDir: __dirname
+      }
+    },
+    plugins: {
+      ...config.plugins,
+      '@qlover-eslint': qloverEslint
+    },
+    rules: {
+      ...config.rules,
+      // Enable ts-class-override rule with full type information
+      // This rule is disabled in the base config above and only enabled here where
+      // type information is available, ensuring accurate detection of override relationships
+      '@qlover-eslint/ts-class-override': 'error',
+      // Disable other type-checked rules to avoid performance impact
+      // We only need type checking for ts-class-override, so we disable other
+      // type-aware rules that would slow down linting without providing value
+      '@typescript-eslint/ban-ts-comment': 'off',
+      '@typescript-eslint/restrict-template-expressions': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unnecessary-type-assertion': 'off',
+      '@typescript-eslint/no-redundant-type-constituents': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/no-empty-object-type': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/no-unsafe-enum-comparison': 'off',
+      '@typescript-eslint/no-unsafe-literal-comparison': 'off',
+      '@typescript-eslint/no-unsafe-nullish-coalescing': 'off',
+      '@typescript-eslint/no-unsafe-optional-chaining': 'off',
+      '@typescript-eslint/unbound-method': 'off',
+      '@typescript-eslint/await-thenable': 'off',
+      '@typescript-eslint/no-floating-promises': 'off',
+      '@typescript-eslint/no-misused-promises': 'off',
+      '@typescript-eslint/require-await': 'off',
+      '@typescript-eslint/no-base-to-string': 'off',
+      '@typescript-eslint/prefer-promise-reject-errors': 'off',
+      '@typescript-eslint/no-duplicate-type-constituents': 'off',
+      // Disable @typescript-eslint/no-unused-vars as we use unused-imports/no-unused-vars instead
+      '@typescript-eslint/no-unused-vars': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+    }
+  })),
   {
     // TODO: antd override theme need use import type
     files: ['src/base/types/deprecated-antd.d.ts'],

package/dist/templates/react-app/package.json

@@ -36,8 +36,8 @@
     "build:staging": "npm run lint && vite build --mode staging",
     "build:prod": "npm run lint && vite build --mode production",
     "build:analyze": "vite build --mode production && start dist/stats.html",
-    "lint": "eslint ./src ./__tests__ ./config ./makes ./e2e",
-    "lint:fix": "eslint ./src ./__tests__ ./config ./makes ./e2e --ext .ts,.tsx --fix",
+    "lint": "eslint",
+    "lint:fix": "eslint --ext .ts,.tsx --fix",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,scss,md}\"",
     "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,css,scss,md}\"",
     "fix": "npm run lint:fix && npm run format",

package/dist/templates/react-app/src/base/apis/feApi/FeApiBootstarp.ts

@@ -59,6 +59,9 @@ export interface FeApiTransaction<
 export class FeApiBootstarp implements BootstrapExecutorPlugin {
   public readonly pluginName = 'FeApiBootstarp';
 
+  /**
+   * @override
+   */
   public onBefore({ parameters: { ioc } }: BootstrapContext): void {
     ioc
       .get<FeApi>(FeApi)