@foundbyte/eslint-plugin 1.1.0 → 1.1.2

package/README.md

@@ -23,7 +23,11 @@ module.exports = {
   rules: {
     // 启用所有推荐的规则
     '@foundbyte/arrow-function-padding': 'error',
-    '@foundbyte/no-initial-as-assertion': 'error',
+    '@foundbyte/no-initial-as-assertion': ['error', {
+      excludeVariableAssertions: true,
+      excludeTypePatterns: ['^const$'],
+      excludeMethodReturns: ['parse', 'querySelector']
+    }],
     '@foundbyte/hooks-arrow-function-only': 'error',
     '@foundbyte/type-comment-requirement': ['error', {
       minCommentsPerGroup: 1,
@@ -55,7 +59,14 @@ module.exports = {
 
 **配置示例：**
 ```javascript
-'@foundbyte/no-initial-as-assertion': 'error' // 禁止在变量声明时使用 as 类型断言
+// 基本用法
+'@foundbyte/no-initial-as-assertion': 'error'
+
+// 高级配置 - 排除特定情况
+'@foundbyte/no-initial-as-assertion': ['error', {
+  excludeVariableAssertions: true,  // 排除对变量的 as 断言
+  excludeMethodReturns: ['map', 'parse']  // 排除特定方法返回类型的 as 断言
+}]
 ```
 
 **示例：**
@@ -71,12 +82,41 @@ const a = ref() as Ref<string>
 const b = computed(() => {}) as ComputedRef<number>
 const c = reactive({}) as Reactive<object>
 const d = ref({} as { a: string }) // 嵌套的类型断言也会被检测到
+
+// ✅ 当 excludeVariableAssertions 为 true 时 - 变量断言被排除
+interface ID { a?: string, b?: string }
+const d: ID = {}
+const e = d as { a?: string } // 不会报错
+
+// ✅ 当 excludeMethodReturns 包含 'map' 时 - 数组方法返回类型断言被排除
+const arr = [1, 2, 3]
+const mapped = arr.map(x => x * 2) as number[] // 不会报错
+
+// ✅ 当 excludeMethodReturns 包含 'parse' 时 - JSON.parse 返回类型断言被排除
+const jsonString = '{"name": "test"}'
+const parsed = JSON.parse(jsonString) as { name: string } // 不会报错
 ```
 
+**配置选项：**
+
+- `excludeVariableAssertions` (boolean, 默认 false): 是否排除对变量的 as 断言
+  - 当为 true 时，类似 `const a = variable as Type` 的情况不会被报错
+  - 适用于变量到变量的类型断言场景
+
+- `excludeMethodReturns` (array, 默认 []): 排除特定方法返回类型的 as 断言
+  - 支持数组方法：`map`, `filter`, `reduce` 等
+  - 支持全局函数：`JSON.parse` 等
+  - 支持链式调用：`arr.map().filter() as Type`
+
+- `excludeTypePatterns` (array, 默认 []): 排除匹配正则表达式模式的类型断言
+  - 支持正则表达式字符串数组
+  - 用于排除特定的类型断言模式，如 `as const`
+  - 示例：`['^const$', '^Readonly<.*>$']` 可以排除 `as const` 和 `as Readonly<...>`
+
 **注意：**
 - 该规则检查变量声明时的所有类型断言，包括嵌套在函数调用参数中的类型断言
 - 推荐使用显式类型注解，因为类型断言会绕过 TypeScript 的类型检查
-- 对于函数调用返回值的类型断言，该规则不会报错
+- 对于函数调用返回值的类型断言，可以通过配置选项排除特定情况
 
 ### arrow-function-padding
 

package/lib/rules/no-initial-as-assertion.d.ts

@@ -1,6 +1,24 @@
 import { Rule } from 'eslint'
 
-export interface NoInitialAsAssertionOptions {}
+export interface NoInitialAsAssertionOptions {
+  /**
+     * 是否排除对变量的 as 断言
+     * @default false
+     */
+  excludeVariableAssertions?: boolean
+
+  /**
+     * 排除特定方法返回类型的 as 断言
+     * @default []
+     */
+  excludeMethodReturns?: string[]
+
+  /**
+     * 排除匹配正则表达式模式的类型断言
+     * @default []
+     */
+  excludeTypePatterns?: string[]
+}
 
 /**
  * 禁止在初始变量定义时使用 as 类型断言

package/lib/rules/no-initial-as-assertion.js

@@ -7,13 +7,126 @@ module.exports = {
             recommended: false,
         },
         fixable: null,
-        schema: [],
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    excludeVariableAssertions: {
+                        type: 'boolean',
+                        default: false,
+                        description: '是否排除对变量的 as 断言'
+                    },
+                    excludeMethodReturns: {
+                        type: 'array',
+                        items: {
+                            type: 'string'
+                        },
+                        default: [],
+                        description: '排除特定方法返回类型的 as 断言'
+                    },
+                    excludeTypePatterns: {
+                        type: 'array',
+                        items: {
+                            type: 'string'
+                        },
+                        default: [],
+                        description: '排除匹配正则表达式模式的类型断言'
+                    }
+                },
+                additionalProperties: false
+            }
+        ],
         messages: {
             noInitialAsAssertion: '禁止在初始变量定义时使用 as 类型断言，请使用显式类型注解',
         },
     },
 
     create(context) {
+        const options = context.options[0] || {};
+        const excludeVariableAssertions = options.excludeVariableAssertions || false;
+        const excludeMethodReturns = options.excludeMethodReturns || [];
+        const excludeTypePatterns = options.excludeTypePatterns || [];
+
+        /**
+         * 检查是否是变量断言的情况
+         * @param {Object} node TSAsExpression 节点
+         * @returns {boolean}
+         */
+        function isVariableAssertion(node) {
+            // 检查是否是变量断言：const a = variable as Type
+            // 当 excludeVariableAssertions 为 true 时，返回 true 表示要排除
+            return node.expression && 
+                   node.expression.type === 'Identifier' && 
+                   excludeVariableAssertions;
+        }
+
+        /**
+         * 检查是否是排除的方法返回类型断言
+         * @param {Object} node TSAsExpression 节点
+         * @returns {boolean}
+         */
+        function isExcludedMethodReturn(node) {
+            if (!node.expression || node.expression.type !== 'CallExpression') {
+                return false;
+            }
+
+            const callExpression = node.expression;
+            if (callExpression.callee && callExpression.callee.type === 'MemberExpression') {
+                // 处理数组方法如 arr.map().filter() as Type
+                const methodName = callExpression.callee.property && callExpression.callee.property.name;
+                if (methodName && excludeMethodReturns.includes(methodName)) {
+                    return true;
+                }
+            } else if (callExpression.callee && callExpression.callee.type === 'Identifier') {
+                // 处理全局函数如 JSON.parse() as Type
+                const functionName = callExpression.callee.name;
+                if (functionName && excludeMethodReturns.includes(functionName)) {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        /**
+         * 检查是否是 as const 断言
+         * @param {Object} node TSAsExpression 节点
+         * @returns {boolean}
+         */
+        function isConstAssertion(node) {
+            // 检查是否是 as const 断言
+            return node.typeAnnotation && 
+                   node.typeAnnotation.type === 'TSTypeReference' &&
+                   node.typeAnnotation.typeName &&
+                   node.typeAnnotation.typeName.name === 'const';
+        }
+
+        /**
+         * 检查是否匹配排除的类型模式
+         * @param {Object} node TSAsExpression 节点
+         * @returns {boolean}
+         */
+        function matchesExcludedTypePattern(node) {
+            if (excludeTypePatterns.length === 0) {
+                return false;
+            }
+
+            // 获取类型注解的源代码
+            const sourceCode = context.getSourceCode();
+            const typeAnnotationText = sourceCode.getText(node.typeAnnotation);
+
+            // 检查是否匹配任何排除模式
+            return excludeTypePatterns.some(pattern => {
+                try {
+                    const regex = new RegExp(pattern);
+                    return regex.test(typeAnnotationText);
+                } catch (error) {
+                    // 如果正则表达式无效，忽略该模式
+                    return false;
+                }
+            });
+        }
+
         /**
          * 检查变量声明是否使用了 as 类型断言
          * @param {Object} node AST节点
@@ -30,6 +143,21 @@ module.exports = {
                 if (declaration.init) {
                     // 检查初始化表达式是否直接是类型断言
                     if (declaration.init.type === 'TSAsExpression') {
+                        // 排除变量断言的情况
+                        if (isVariableAssertion(declaration.init)) {
+                            return;
+                        }
+
+                        // 排除特定方法返回类型的断言
+                        if (isExcludedMethodReturn(declaration.init)) {
+                            return;
+                        }
+
+                        // 排除匹配正则表达式模式的类型断言
+                        if (matchesExcludedTypePattern(declaration.init)) {
+                            return;
+                        }
+
                         // 对于直接的类型断言，应该限制
                         // 例如：const a = 1 as number, const a = {} as { s: string }
                         context.report({
@@ -43,6 +171,16 @@ module.exports = {
                         if (declaration.init.arguments && declaration.init.arguments.length > 0) {
                             for (const arg of declaration.init.arguments) {
                                 if (arg.type === 'TSAsExpression') {
+                                    // 排除变量断言的情况
+                                    if (isVariableAssertion(arg)) {
+                                        continue;
+                                    }
+
+                                    // 排除特定方法返回类型的断言
+                                    if (isExcludedMethodReturn(arg)) {
+                                        continue;
+                                    }
+
                                     // 对于函数参数中的类型断言，应该限制
                                     // 例如：ref({} as string) 中的 {} as string
                                     context.report({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundbyte/eslint-plugin",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "ESLint plugin for enforcing code style rules including arrow function padding, Vue script lines limit, and TypeScript type comment requirements",
   "main": "index.js",
   "types": "index.d.ts",