@foundbyte/eslint-plugin 1.1.4 → 1.1.5-alpha.1

package/README.md

@@ -23,45 +23,67 @@ module.exports = {
   rules: {
     // 启用所有推荐的规则
     '@foundbyte/arrow-function-padding': 'error',
-    '@foundbyte/no-initial-as-assertion': ['error', {
-      excludeVariableAssertions: true,
-      excludeTypePatterns: ['^const$', '^[A-Z]$', '^unknown$'],
-      excludeMethodReturns: ['parse', 'querySelector']
-    }],
+    '@foundbyte/no-initial-as-assertion': [
+      'error',
+      {
+        excludeVariableAssertions: true,
+        excludeTypePatterns: ['^const$', '^[A-Z]$', '^unknown$'],
+        excludeMethodReturns: ['parse', 'querySelector'],
+      },
+    ],
     '@foundbyte/hooks-arrow-function-only': 'error',
-    '@foundbyte/type-comment-requirement': ['error', {
-      minCommentsPerGroup: 1,
-      groupSize: 8,
-      includeTypes: true,
-      includeInterfaces: true,
-    }],
+    '@foundbyte/type-comment-requirement': [
+      'error',
+      {
+        minCommentsPerGroup: 1,
+        groupSize: 8,
+        includeTypes: true,
+        includeInterfaces: true,
+      },
+    ],
     '@foundbyte/hooks-export-limit': ['error', { maxExports: 20 }],
     '@foundbyte/vue-script-lines-limit': ['error', { maxLines: 300 }],
-    '@foundbyte/tag-attribute-restriction': ['error', {
-      restrictions: [
-        {
-          tag: 'image',
-          attributes: [
-            { name: 'mode', disallowedValues: [''] },
-          ]
-        }
-      ]
-    }],
-    '@foundbyte/no-restricted-components': ['error', [
+    '@foundbyte/tag-attribute-restriction': [
+      'error',
       {
-        pattern: '/^a-(textarea|table)$/',
-        message: '禁止使用的Arco Design组件，请使用Keyblade组件替代'
-      }
-    ]],
+        restrictions: [
+          {
+            tag: 'image',
+            attributes: [{ name: 'mode', disallowedValues: [''] }],
+          },
+        ],
+      },
+    ],
+    '@foundbyte/no-restricted-components': [
+      'error',
+      [
+        {
+          pattern: '/^a-(textarea|table)$/',
+          message: '禁止使用的Arco Design组件，请使用Keyblade组件替代',
+        },
+      ],
+    ],
     '@foundbyte/no-excessive-any': ['error', { maxAnyCount: 5 }],
-    '@foundbyte/no-disabled-comments': ['error', {
-       patterns: [
-        '/^\\s*eslint-disable-next-line\\s*$/', 
-        '/^\\s*eslint-disable\\s*$/',
-        '/no-explicit-any/',
-        '/vue-script-lines-limit/',
-        '/hooks-export-limit/'
-    ]}]
+    '@foundbyte/no-disabled-comments': [
+      'error',
+      {
+        patterns: [
+          '/^\\s*eslint-disable-next-line\\s*$/',
+          '/^\\s*eslint-disable\\s*$/',
+          '/no-explicit-any/',
+          '/vue-script-lines-limit/',
+          '/hooks-export-limit/',
+        ],
+      },
+    ],
+    '@foundbyte/require-json-parse-type': 'error',
+    '@foundbyte/no-restricted-literal-types': [
+      'error',
+      {
+        forbidden: ['null', 'undefined', ''],
+        allowInUnions: true,
+      },
+    ],
   },
 }
 ```
@@ -71,11 +93,13 @@ module.exports = {
 ### no-excessive-any
 
 限制 `any` 类型的使用次数，包括：
+
 - 显式 `any` 类型
 - 隐式 `any` 类型（没有类型注解且无法推导类型的变量）
 - 泛型类型中的 `any`（如 `Ref<any>`, `Promise<any>`, `any[]` 等）
 
 **配置示例：**
+
 ```javascript
 // 基本用法 - 限制 any 类型最多使用 5 次
 '@foundbyte/no-excessive-any': ['error', { maxAnyCount: 5 }]
@@ -88,6 +112,7 @@ module.exports = {
 ```
 
 **检测范围：**
+
 - 显式 `any` 类型：`const a: any = 1`
 - 隐式 `any` 类型：
   - 没有初始值的变量声明：`const a`
@@ -99,6 +124,7 @@ module.exports = {
 
 **智能类型推导：**
 以下情况不计入 any 使用：
+
 - 有初始值的变量：`const a = 1`, `const b = ref(60)`
 - 对象字面量：`const obj = { name: 'test' }`
 - 数组字面量：`const arr = [1, 2, 3]`
@@ -108,6 +134,7 @@ module.exports = {
 - 异步函数调用：`const res = await ssoMobileAuth(...)`
 
 **示例：**
+
 ```typescript
 // ✅ 正确 - 当 maxAnyCount 为 3 时
 const a: any = 1
@@ -155,6 +182,7 @@ interface MyInterface {
   - 设置为正整数表示允许的最大次数
 
 **注意：**
+
 - 该规则统计文件中所有 `any` 类型的使用，包括显式和隐式
 - 规则会智能识别可以类型推导的情况，避免过度检测
 - 建议在 TypeScript 项目中设置合理的限制，鼓励使用具体类型
@@ -165,6 +193,7 @@ interface MyInterface {
 禁止在初始变量定义时使用 `as` 类型断言，强制使用显式类型注解。
 
 **配置示例：**
+
 ```javascript
 // 基本用法
 '@foundbyte/no-initial-as-assertion': 'error'
@@ -177,6 +206,7 @@ interface MyInterface {
 ```
 
 **示例：**
+
 ```typescript
 // ✅ 正确 - 使用显式类型注解
 const a: Ref<string> = ref()
@@ -191,13 +221,16 @@ const c = reactive({}) as Reactive<object>
 const d = ref({} as { a: string }) // 嵌套的类型断言也会被检测到
 
 // ✅ 当 excludeVariableAssertions 为 true 时 - 变量断言被排除
-interface ID { a?: string, b?: string }
+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[] // 不会报错
+const mapped = arr.map((x) => x * 2) as number[] // 不会报错
 
 // ✅ 当 excludeMethodReturns 包含 'parse' 时 - JSON.parse 返回类型断言被排除
 const jsonString = '{"name": "test"}'
@@ -221,6 +254,7 @@ const parsed = JSON.parse(jsonString) as { name: string } // 不会报错
   - 示例：`['^const$', '^Readonly<.*>$']` 可以排除 `as const` 和 `as Readonly<...>`
 
 **注意：**
+
 - 该规则检查变量声明时的所有类型断言，包括嵌套在函数调用参数中的类型断言
 - 推荐使用显式类型注解，因为类型断言会绕过 TypeScript 的类型检查
 - 对于函数调用返回值的类型断言，可以通过配置选项排除特定情况
@@ -230,11 +264,13 @@ const parsed = JSON.parse(jsonString) as { name: string } // 不会报错
 要求函数体之间必须空行。
 
 **配置示例：**
+
 ```javascript
 '@foundbyte/arrow-function-padding': 'error' // 总是要求空行
 ```
 
 **示例：**
+
 ```javascript
 // ✅ 正确
 const one = () => {}
@@ -251,12 +287,13 @@ const two = () => {}
 要求 React/Vue Hooks 必须使用箭头函数。
 
 **示例：**
+
 ```javascript
 // ✅ 正确
 const useMyHook = () => {
   const [state, setState] = useState()
   return state
-};
+}
 
 // ❌ 错误
 function useMyHook() {
@@ -270,17 +307,19 @@ function useMyHook() {
 限制 Hooks 文件内部成员的导出数量。
 
 **配置示例：**
+
 ```javascript
 '@foundbyte/hooks-export-limit': ['error', { maxExports: 2 }] // 最大允许的导出数量
 ```
 
 **示例：**
+
 ```javascript
 // ✅ 正确 - 只有一个导出
 export const useMyHook = () => {
   const a = ''
   return {
-    a
+    a,
   }
 }
 
@@ -290,7 +329,7 @@ export const useMyHook = () => {
   const b = ''
   return {
     a,
-    b
+    b,
   }
 }
 ```
@@ -300,8 +339,9 @@ export const useMyHook = () => {
 要求复杂类型定义必须有类型注释。
 
 **配置示例：**
+
 ```javascript
-'@foundbyte/type-comment-requirement': ['error', { 
+'@foundbyte/type-comment-requirement': ['error', {
   /** 至少1个注释 */
   minCommentsPerGroup: 1,
   /** 每3个类型 */
@@ -310,6 +350,7 @@ export const useMyHook = () => {
 ```
 
 **示例：**
+
 ```ts
 // ✅ 正确 - 有类型注释
 interface user {
@@ -317,11 +358,15 @@ interface user {
   name: 'John'
   /** 年龄 */
   age: 30
-  ddress: { city: 'NY', zip: '10001' } 
+  ddress: { city: 'NY'; zip: '10001' }
 }
 
 // ❌ 错误 - 复杂对象没有类型注释
-interface user { name: 'John', age: 30, address: { city: 'NY', zip: '10001' } }
+interface user {
+  name: 'John'
+  age: 30
+  address: { city: 'NY'; zip: '10001' }
+}
 ```
 
 ### vue-script-lines-limit
@@ -329,11 +374,13 @@ interface user { name: 'John', age: 30, address: { city: 'NY', zip: '10001' } }
 限制 Vue 单文件组件中 `<script>` 标签的行数。
 
 **配置示例：**
+
 ```javascript
 '@foundbyte/vue-script-lines-limit': ['error', { maxLines: 200 }] // 最大允许的行数
 ```
 
 **示例：**
+
 ```vue
 <!-- ✅ 正确 - script 标签行数在限制内 -->
 <script>
@@ -344,8 +391,8 @@ export default {
   methods: {
     increment() {
       this.count++
-    }
-  }
+    },
+  },
 }
 </script>
 
@@ -360,6 +407,7 @@ export default {
 禁止使用特定的 ESLint 禁用注释，如 `eslint-disable`、`eslint-disable-next-line` 等。支持 JavaScript/TypeScript 注释和 Vue 模板中的 HTML 注释。
 
 **配置示例：**
+
 ```javascript
 '@foundbyte/no-disabled-comments': ['error', {
   patterns: [
@@ -373,6 +421,7 @@ export default {
 ```
 
 **支持的注释类型：**
+
 1. **JavaScript/TypeScript 注释**：
    - 行注释：`// eslint-disable-next-line`
    - 块注释：`/* eslint-disable */`
@@ -382,11 +431,13 @@ export default {
    - `<!-- eslint-disable-next-line -->`
 
 **检测的注释内容：**
+
 - 注释内容经过 `trim()` 处理，去除前后空白字符
 - 支持正则表达式模糊匹配
 - 支持多个模式同时匹配
 
 **示例：**
+
 ```javascript
 // ✅ 正确 - 不匹配任何禁用模式
 // 普通注释
@@ -434,11 +485,13 @@ const x: any = 1;
   - 当为 true 时，匹配区分大小写
 
 **错误消息：**
+
 - `禁止使用注释: "eslint-disable-next-line"，如必须排除，请在 .eslintignore 中排除，并写清楚排除原因`
 - `禁止使用注释: "eslint-disable"，如必须排除，请在 .eslintignore 中排除，并写清楚排除原因`
 - `禁止使用注释: "eslint-disable-next-line @typescript-eslint/no-explicit-any"，如必须排除，请在 .eslintignore 中排除，并写清楚排除原因`
 
 **注意：**
+
 - 该规则会检查所有 JavaScript/TypeScript 注释和 Vue 模板中的 HTML 注释
 - 对于 Vue 文件，规则会同时检查 `<script>` 中的 JavaScript 注释和 `<template>` 中的 HTML 注释
 - 建议只禁用特定的、有问题的规则，而不是使用无参数的 `eslint-disable` 禁用所有规则
@@ -449,6 +502,7 @@ const x: any = 1;
 通过正则表达式配置禁止使用某些组件，支持自定义错误消息。
 
 **配置示例：**
+
 ```javascript
 '@foundbyte/no-restricted-components': ['error', [
   {
@@ -463,6 +517,7 @@ const x: any = 1;
 ```
 
 **支持的语法：**
+
 - 正则表达式字符串：以 `/` 开头和结尾，如 `/^a-(textarea|table)$/`
 - 普通字符串：自动转义并创建正则表达式，如 `'a-textarea'`
 - 支持自闭合标签：`<a-textarea />`
@@ -471,14 +526,18 @@ const x: any = 1;
 - 只对 .vue 文件生效，不会影响其他文件类型
 
 **示例：**
+
 ```vue
 <!-- ✅ 正确 - 不匹配任何禁止模式的组件 -->
 <div>正常内容</div>
+
 <span>正常内容</span>
+
 <custom-component />
 
 <!-- ❌ 错误 - 匹配 a-textarea 模式 -->
 <a-textarea />
+
 <a-textarea></a-textarea>
 
 <!-- ❌ 错误 - 匹配 a-input 模式 -->
@@ -489,9 +548,11 @@ const x: any = 1;
 ```
 
 **错误消息：**
+
 - 显示配置中指定的自定义消息，如：`禁止使用 a-textarea 和 a-input 组件，请使用自定义组件替代`
 
 **注意：**
+
 - 该规则只检查 .vue 文件中的模板部分，不会检查 JavaScript/TypeScript 代码中的字符串
 - 支持同时配置多个禁止模式，每个模式独立检查
 - 正则表达式匹配组件名，不区分大小写
@@ -502,20 +563,21 @@ const x: any = 1;
 限制特定标签使用某些属性或属性值。
 
 **配置示例：**
+
 ```javascript
 '@foundbyte/tag-attribute-restriction': ['error', {
   restrictions: [
     {
       tag: 'image',           // 标签名称
       attributes: [           // 属性限制列表
-        { 
+        {
           name: 'mode',       // 属性名称
           disallowedValues: [ // 禁止的值列表（可选）
-            '', 
+            '',
             'scaleToFill'
-          ] 
+          ]
         },
-        { 
+        {
           name: 'lazy-load'   // 完全禁止该属性
         }
       ]
@@ -525,6 +587,7 @@ const x: any = 1;
 ```
 
 **支持的语法：**
+
 - 静态属性: `<image mode="" />`
 - 动态属性: `<image :mode="'scaleToFill'" />`
 - 无值属性: `<image lazy-load />`
@@ -532,6 +595,7 @@ const x: any = 1;
 - JSX 属性
 
 **示例：**
+
 ```vue
 <!-- ✅ 正确 -->
 <image src="test.jpg" mode="aspectFit" />
@@ -547,5 +611,121 @@ const x: any = 1;
 ```
 
 **错误消息：**
+
 - `标签 <image> 不允许使用属性 mode` - 当属性被完全禁止时
 - `标签 <image> 的属性 mode 不允许使用值 ""` - 当特定属性值被禁止时
+
+### require-json-parse-type
+
+要求 `JSON.parse` 的返回值在赋值给变量时必须带有显式类型注解。
+
+**配置示例：**
+
+```javascript
+// 基本用法 - 检查 const、let、var
+'@foundbyte/require-json-parse-type': 'error'
+
+// 只检查 const
+'@foundbyte/require-json-parse-type': ['error', { declarationTypes: ['const'] }]
+```
+
+**示例：**
+
+```typescript
+// ✅ 正确 - 变量带有显式类型注解
+const a: { s: number } = JSON.parse('{s:1}')
+
+// ✅ 正确 - 解构赋值带有显式类型注解
+const { s }: { s: number } = JSON.parse('{s:1}')
+
+// ✅ 正确 - 三元表达式中的 JSON.parse 带有显式类型注解
+const qualification: string[] = info.qualification ? JSON.parse(info.qualification) : []
+
+// ❌ 错误 - 缺少类型注解
+const a = JSON.parse('{s:1}')
+
+// ❌ 错误 - 三元表达式中的 JSON.parse 缺少类型注解
+const qualification = info.qualification ? JSON.parse(info.qualification) : []
+
+// ❌ 错误 - 使用 as 断言不算作变量声明类型注解
+const a = JSON.parse('{s:1}') as { s: number }
+```
+
+**配置选项：**
+
+- `declarationTypes` (array, 默认 `['const', 'let', 'var']`): 要检查的变量声明类型
+  - 可选项：`const`、`let`、`var`
+  - 例如设置为 `['const']` 则只检查 `const` 声明
+
+**注意：**
+
+- 该规则检查变量声明的初始化表达式中是否包含 `JSON.parse(...)`，包括三元表达式、逻辑表达式、对象/数组字面量等场景
+- 对于 `const a = JSON.parse('...') as Type` 也会报错，因为它要求类型注解必须声明在变量本身
+- 函数体内部的 `JSON.parse` 不影响外层变量，不会被误判
+- 如希望允许 `as` 类型断言，请搭配 `@foundbyte/no-initial-as-assertion` 规则按需配置
+
+### no-restricted-literal-types
+
+禁止在类型注解中使用指定的无意义字面量类型，例如 `null`、`undefined`、空字符串字面量 `''` 等。
+
+**配置示例：**
+
+```javascript
+// 基本用法 - 禁止 null、undefined 和空字符串字面量类型
+'@foundbyte/no-restricted-literal-types': ['error', {
+  forbidden: ['null', 'undefined', ''],
+}]
+
+// 允许联合类型中的 null / undefined
+'@foundbyte/no-restricted-literal-types': ['error', {
+  forbidden: ['null', 'undefined'],
+  allowInUnions: true,
+}]
+```
+
+**示例：**
+
+```typescript
+// ❌ 错误 - 无意义的 null 类型
+interface OrderItem {
+  seatName: null
+  refundStatus: null
+}
+
+// ❌ 错误 - 无意义的 undefined 类型
+interface Config {
+  value: undefined
+}
+
+// ❌ 错误 - 无意义的空字符串字面量类型
+interface Query {
+  keyword: ''
+}
+
+// ✅ 正确 - 使用具体类型
+interface OrderItem {
+  seatName: string
+  refundStatus: number
+}
+
+// ✅ 正确 - 联合类型中的 null / undefined 是有意义的（当 allowInUnions 为 true 时）
+interface User {
+  phone: string | null
+  email?: string
+}
+```
+
+**配置选项：**
+
+- `forbidden` (array, 必填): 要禁止的字面量类型列表
+  - 支持关键字类型：`'null'`、`'undefined'`、`'void'`、`'never'`、`'any'`、`'unknown'`、`'boolean'`、`'number'`、`'string'`、`'symbol'`、`'bigint'`、`'object'`
+  - 支持字面量值：`''`、`0`、`true`、`false` 等
+
+- `allowInUnions` (boolean, 默认 `false`): 是否允许在联合类型中使用
+  - 为 `true` 时，`string | null` 不会被报错，但独立的 `null` 类型仍然会报错
+  - 为 `false` 时，任何出现 `null` / `undefined` 等的地方都会报错
+
+**注意：**
+
+- 该规则针对类型注解中的字面量，不影响运行时值，例如 `const a = null` 不会触发
+- 建议配合 TypeScript 严格模式使用，逐步替换项目中的无意义类型声明

package/index.d.ts

@@ -1,8 +1,13 @@
-import { ESLint } from 'eslint'
+import { ESLint, Rule } from 'eslint'
 import { Rules } from './lib/rules'
-import { Rule } from 'eslint'
 
-export { ArrowFunctionPaddingOptions, HooksExportLimitOptions, TypeCommentRequirementOptions, VueScriptLinesLimitOptions, HooksArrowFunctionOnlyOptions } from './types'
+export {
+  ArrowFunctionPaddingOptions,
+  HooksArrowFunctionOnlyOptions,
+  HooksExportLimitOptions,
+  TypeCommentRequirementOptions,
+  VueScriptLinesLimitOptions,
+} from './types'
 
 declare const plugin: ESLint.Plugin & {
   rules: Rules
@@ -11,4 +16,4 @@ declare const plugin: ESLint.Plugin & {
   }
 }
 
-export { type Rules, plugin as default }
+export { plugin as default, type Rules }

package/index.js

@@ -8,30 +8,27 @@ const noInitialAsAssertionRule = require('./lib/rules/no-initial-as-assertion')
 const noExcessiveAnyRule = require('./lib/rules/no-excessive-any')
 const noDisabledCommentsRule = require('./lib/rules/no-disabled-comments')
 const noRestrictedComponentsRule = require('./lib/rules/no-restricted-components')
+const requireJsonParseTypeRule = require('./lib/rules/require-json-parse-type')
+const noRestrictedLiteralTypesRule = require('./lib/rules/no-restricted-literal-types')
 
 // 限制属性，同时相当于限制某些组件禁止使用
 const restrictions = [
   {
     // 禁止<image />直接使用空的mode: <image mode="" />
     tag: 'image',
-    attributes: [
-      { name: 'mode', disallowedValues: [''] },
-    ]
+    attributes: [{ name: 'mode', disallowedValues: [''] }],
   },
   {
     tag: 'page-meta',
     attributes: [
       // harmony 不兼容
-      { name: 'page-style' }
-    ]
+      { name: 'page-style' },
+    ],
   },
   {
     // 禁止<kb-pro-table /> 使用v-bind，请使用main.ts全局配置
     tag: 'kb-pro-table',
-    attributes: [
-      { name: 'v-bind' },
-      { name: 'bordered' },
-    ],
+    attributes: [{ name: 'v-bind' }, { name: 'bordered' }],
   },
 ]
 
@@ -47,6 +44,8 @@ module.exports = {
     'no-excessive-any': noExcessiveAnyRule,
     'no-disabled-comments': noDisabledCommentsRule,
     'no-restricted-components': noRestrictedComponentsRule,
+    'require-json-parse-type': requireJsonParseTypeRule,
+    'no-restricted-literal-types': noRestrictedLiteralTypesRule,
   },
   configs: {
     customize: (options) => {
@@ -57,38 +56,50 @@ module.exports = {
           '@foundbyte/vue-script-lines-limit': ['error', { maxLines: 300 }],
           '@foundbyte/no-excessive-any': ['error', { maxAnyCount: 5 }],
           '@foundbyte/hooks-export-limit': ['error', { maxExports: 20 }],
-          '@foundbyte/no-initial-as-assertion': ['error', {
-            excludeVariableAssertions: true,
-            excludeTypePatterns: ['^const$', '^[A-Z]$', '^unknown$', '^EAppEnv$'],
-            excludeMethodReturns: ['parse', 'querySelector'],
-          }],
-          '@foundbyte/no-restricted-components': ['error', [
+          '@foundbyte/no-initial-as-assertion': [
+            'error',
             {
-              pattern: '/^a-(textarea|table)$/',
-              message: '禁止使用的Arco Design组件，请使用Keyblade组件替代'
-            }
-          ]],
+              excludeVariableAssertions: true,
+              excludeTypePatterns: ['^const$', '^[A-Z]$', '^unknown$', '^EAppEnv$'],
+              excludeMethodReturns: ['parse', 'querySelector'],
+            },
+          ],
+          '@foundbyte/no-restricted-components': [
+            'error',
+            [
+              {
+                pattern: '/^a-(textarea|table)$/',
+                message: '禁止使用的Arco Design组件，请使用Keyblade组件替代',
+              },
+            ],
+          ],
           '@foundbyte/tag-attribute-restriction': ['error', { restrictions }],
           // 类型加注释
-          '@foundbyte/type-comment-requirement': ['error', {
-            minCommentsPerGroup: 1,
-            groupSize: 8,
-            includeTypes: true,
-            includeInterfaces: true,
-          }],
+          '@foundbyte/type-comment-requirement': [
+            'error',
+            {
+              minCommentsPerGroup: 1,
+              groupSize: 8,
+              includeTypes: true,
+              includeInterfaces: true,
+            },
+          ],
           // 禁止使用某些注释
-          '@foundbyte/no-disabled-comments': ['error', {
-            patterns: [
-              '/^\\s*eslint-disable-next-line\\s*$/',
-              '/^\\s*eslint-disable\\s*$/',
-              '/no-explicit-any/',
-              '/vue-script-lines-limit/',
-              '/hooks-export-limit/',
-            ],
-          }],
+          '@foundbyte/no-disabled-comments': [
+            'error',
+            {
+              patterns: [
+                '/^\\s*eslint-disable-next-line\\s*$/',
+                '/^\\s*eslint-disable\\s*$/',
+                '/no-explicit-any/',
+                '/vue-script-lines-limit/',
+                '/hooks-export-limit/',
+              ],
+            },
+          ],
           ...(options || {}),
-        }
+        },
       }
-    }
-  }
+    },
+  },
 }

package/lib/rules/index.d.ts

@@ -1,15 +1,15 @@
+import { Rule } from 'eslint'
+
 export { ArrowFunctionPaddingOptions } from './arrow-function-padding'
-export { HooksExportLimitOptions } from './hooks-export-limit'
-export { TypeCommentRequirementOptions } from './type-comment-requirement'
-export { VueScriptLinesLimitOptions } from './vue-script-lines-limit'
 export { HooksArrowFunctionOnlyOptions } from './hooks-arrow-function-only'
-export { TagAttributeRestrictionOptions } from './tag-attribute-restriction'
-export { NoInitialAsAssertionOptions } from './no-initial-as-assertion'
-export { NoExcessiveAnyOptions } from './no-excessive-any'
+export { HooksExportLimitOptions } from './hooks-export-limit'
 export { NoDisabledCommentsOptions } from './no-disabled-comments'
+export { NoExcessiveAnyOptions } from './no-excessive-any'
+export { NoInitialAsAssertionOptions } from './no-initial-as-assertion'
 export { NoRestrictedComponentsOptions } from './no-restricted-components'
-
-import { Rule } from 'eslint'
+export { TagAttributeRestrictionOptions } from './tag-attribute-restriction'
+export { TypeCommentRequirementOptions } from './type-comment-requirement'
+export { VueScriptLinesLimitOptions } from './vue-script-lines-limit'
 
 /**
  * @foundbyte/eslint-plugin 规则配置

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

@@ -2,21 +2,21 @@ import { Rule } from 'eslint'
 
 export interface NoInitialAsAssertionOptions {
   /**
-     * 是否排除对变量的 as 断言
-     * @default false
-     */
+   * 是否排除对变量的 as 断言
+   * @default false
+   */
   excludeVariableAssertions?: boolean
 
   /**
-     * 排除特定方法返回类型的 as 断言
-     * @default []
-     */
+   * 排除特定方法返回类型的 as 断言
+   * @default []
+   */
   excludeMethodReturns?: string[]
 
   /**
-     * 排除匹配正则表达式模式的类型断言
-     * @default []
-     */
+   * 排除匹配正则表达式模式的类型断言
+   * @default []
+   */
   excludeTypePatterns?: string[]
 }
 

package/lib/rules/no-restricted-literal-types.d.ts

@@ -0,0 +1,22 @@
+import { Rule } from 'eslint'
+
+export interface NoRestrictedLiteralTypesOptions {
+  /**
+   * 要禁止的字面量类型列表
+   * @example ['null', 'undefined', '']
+   */
+  forbidden: Array<string | number | boolean>
+
+  /**
+   * 是否允许在联合类型中使用，例如 string | null
+   * @default false
+   */
+  allowInUnions?: boolean
+}
+
+/**
+ * 禁止在类型注解中使用指定的字面量类型
+ */
+declare const rule: Rule.RuleModule
+
+export default rule

package/lib/rules/no-restricted-literal-types.js

@@ -0,0 +1,158 @@
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: '禁止在类型注解中使用指定的字面量类型',
+      category: 'Best Practices',
+      recommended: false,
+    },
+    fixable: null,
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          forbidden: {
+            type: 'array',
+            items: {
+              anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }],
+            },
+            description:
+              '要禁止的字面量类型列表，支持 null、undefined、void、never、any、unknown 等关键字，以及空字符串、0、true 等具体字面量',
+          },
+          allowInUnions: {
+            type: 'boolean',
+            default: false,
+            description: '是否允许在联合类型中使用，例如 string | null',
+          },
+        },
+        required: ['forbidden'],
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      noRestrictedLiteralType: '禁止在类型中使用 "{{type}}" 字面量类型',
+    },
+  },
+
+  create(context) {
+    const options = context.options[0] || {}
+    const forbidden = options.forbidden || []
+    const allowInUnions = options.allowInUnions || false
+
+    if (forbidden.length === 0) {
+      return {}
+    }
+
+    const forbiddenStrings = new Set()
+    const forbiddenNumbers = new Set()
+    const forbiddenBooleans = new Set()
+
+    forbidden.forEach((item) => {
+      if (typeof item === 'string') {
+        forbiddenStrings.add(item)
+      } else if (typeof item === 'number') {
+        forbiddenNumbers.add(item)
+      } else if (typeof item === 'boolean') {
+        forbiddenBooleans.add(item)
+      }
+    })
+
+    // 关键字类型映射
+    const keywordTypeMap = {
+      null: 'TSNullKeyword',
+      undefined: 'TSUndefinedKeyword',
+      void: 'TSVoidKeyword',
+      never: 'TSNeverKeyword',
+      any: 'TSAnyKeyword',
+      unknown: 'TSUnknownKeyword',
+      boolean: 'TSBooleanKeyword',
+      number: 'TSNumberKeyword',
+      string: 'TSStringKeyword',
+      symbol: 'TSSymbolKeyword',
+      bigint: 'TSBigIntKeyword',
+      object: 'TSObjectKeyword',
+    }
+
+    /**
+     * 检查类型是否位于联合类型中
+     * @param {Object} node AST 节点
+     * @returns {boolean}
+     */
+    function isInUnion(node) {
+      return node.parent && node.parent.type === 'TSUnionType'
+    }
+
+    /**
+     * 获取匹配到的 forbidden 值
+     * @param {Object} node AST 节点
+     * @returns {string|number|boolean|null}
+     */
+    function getMatchedForbidden(node) {
+      if (allowInUnions && isInUnion(node)) {
+        return null
+      }
+
+      // 关键字类型检查
+      for (const [key, typeName] of Object.entries(keywordTypeMap)) {
+        if (forbiddenStrings.has(key) && node.type === typeName) {
+          return key
+        }
+      }
+
+      // 字面量类型检查
+      if (node.type === 'TSLiteralType' && node.literal) {
+        const literal = node.literal
+
+        if (literal.type === 'Literal') {
+          if (typeof literal.value === 'string' && forbiddenStrings.has(literal.value)) {
+            return literal.value
+          }
+          if (typeof literal.value === 'number' && forbiddenNumbers.has(literal.value)) {
+            return literal.value
+          }
+          if (typeof literal.value === 'boolean' && forbiddenBooleans.has(literal.value)) {
+            return literal.value
+          }
+        }
+      }
+
+      return null
+    }
+
+    const targetTypes = [
+      'TSNullKeyword',
+      'TSUndefinedKeyword',
+      'TSVoidKeyword',
+      'TSNeverKeyword',
+      'TSAnyKeyword',
+      'TSUnknownKeyword',
+      'TSBooleanKeyword',
+      'TSNumberKeyword',
+      'TSStringKeyword',
+      'TSSymbolKeyword',
+      'TSBigIntKeyword',
+      'TSObjectKeyword',
+      'TSLiteralType',
+    ]
+
+    const visitors = {}
+    targetTypes.forEach((type) => {
+      visitors[type] = function (node) {
+        const matched = getMatchedForbidden(node)
+        if (matched === null) {
+          return
+        }
+
+        context.report({
+          node,
+          messageId: 'noRestrictedLiteralType',
+          data: {
+            type: String(matched),
+          },
+        })
+      }
+    })
+
+    return visitors
+  },
+}

package/lib/rules/require-json-parse-type.d.ts

@@ -0,0 +1,16 @@
+import { Rule } from 'eslint'
+
+export interface RequireJsonParseTypeOptions {
+  /**
+   * 要检查的变量声明类型
+   * @default ['const', 'let', 'var']
+   */
+  declarationTypes?: Array<'const' | 'let' | 'var'>
+}
+
+/**
+ * 要求 JSON.parse 的返回值必须声明显式类型
+ */
+declare const rule: Rule.RuleModule
+
+export default rule

package/lib/rules/require-json-parse-type.js

@@ -0,0 +1,156 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '要求 JSON.parse 的返回值必须声明显式类型',
+      category: 'Best Practices',
+      recommended: false,
+    },
+    fixable: null,
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          declarationTypes: {
+            type: 'array',
+            items: {
+              type: 'string',
+              enum: ['const', 'let', 'var'],
+            },
+            default: ['const', 'let', 'var'],
+            description: '要检查的变量声明类型',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      requireJsonParseType:
+        "JSON.parse 的返回值必须声明显式类型，例如：const a: { s: number } = JSON.parse('...')",
+    },
+  },
+
+  create(context) {
+    const options = context.options[0] || {}
+    const declarationTypes = options.declarationTypes || ['const', 'let', 'var']
+
+    /**
+     * 判断调用表达式是否是 JSON.parse(...)
+     * @param {Object} node AST 节点
+     * @returns {boolean}
+     */
+    function isJsonParseCall(node) {
+      if (!node || node.type !== 'CallExpression') {
+        return false
+      }
+
+      const callee = node.callee
+      if (!callee || callee.type !== 'MemberExpression') {
+        return false
+      }
+
+      const object = callee.object
+      const property = callee.property
+
+      return (
+        object &&
+        object.type === 'Identifier' &&
+        object.name === 'JSON' &&
+        property &&
+        property.type === 'Identifier' &&
+        property.name === 'parse'
+      )
+    }
+
+    /**
+     * 从变量声明的初始化表达式中取出最底层的调用表达式
+     * 用于处理 const a = JSON.parse('...') as Type 这种情况
+     * @param {Object} node AST 节点
+     * @returns {Object|null}
+     */
+    function unwrapExpression(node) {
+      if (!node) {
+        return null
+      }
+
+      if (node.type === 'TSAsExpression' || node.type === 'TSSatisfiesExpression') {
+        return unwrapExpression(node.expression)
+      }
+
+      return node
+    }
+
+    /**
+     * 递归检查表达式中是否包含 JSON.parse(...) 调用
+     * 用于处理三元表达式、逻辑表达式、对象/数组字面量等场景
+     * @param {Object} node AST 节点
+     * @returns {boolean}
+     */
+    function containsJsonParse(node) {
+      if (!node || typeof node !== 'object') {
+        return false
+      }
+
+      const unwrapped = unwrapExpression(node)
+      if (isJsonParseCall(unwrapped)) {
+        return true
+      }
+
+      // 不进入函数体内部，函数体是独立作用域，不影响外层变量类型
+      if (unwrapped.type === 'ArrowFunctionExpression' || unwrapped.type === 'FunctionExpression') {
+        return false
+      }
+
+      return Object.keys(unwrapped).some((key) => {
+        if (key === 'parent' || key === 'loc' || key === 'range') {
+          return false
+        }
+
+        const value = unwrapped[key]
+        if (Array.isArray(value)) {
+          return value.some((child) => containsJsonParse(child))
+        }
+        if (value && typeof value === 'object' && value.type) {
+          return containsJsonParse(value)
+        }
+        return false
+      })
+    }
+
+    /**
+     * 检查变量声明是否使用了 JSON.parse 并且缺少显式类型注解
+     * @param {Object} node VariableDeclaration 节点
+     */
+    function checkVariableDeclaration(node) {
+      if (!declarationTypes.includes(node.kind)) {
+        return
+      }
+
+      node.declarations.forEach((declaration) => {
+        if (!declaration.init) {
+          return
+        }
+
+        if (!containsJsonParse(declaration.init)) {
+          return
+        }
+
+        // 检查变量声明是否有显式类型注解
+        // 支持普通变量：const a: Type = ...
+        // 支持解构：const { a }: Type = ...
+        if (declaration.id && declaration.id.typeAnnotation) {
+          return
+        }
+
+        context.report({
+          node: declaration,
+          messageId: 'requireJsonParseType',
+        })
+      })
+    }
+
+    return {
+      VariableDeclaration: checkVariableDeclaration,
+    }
+  },
+}

package/package.json

@@ -1,30 +1,30 @@
 {
-    "name": "@foundbyte/eslint-plugin",
-    "version": "1.1.4",
-    "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",
-    "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
-    },
-    "keywords": [
-        "eslint",
-        "eslintplugin",
-        "arrow-function",
-        "padding",
-        "vue",
-        "script",
-        "lines-limit",
-        "typescript",
-        "type-comment",
-        "comment-requirement"
-    ],
-    "author": "",
-    "license": "ISC",
-    "publishConfig": {
-        "access": "public"
-    },
-    "peerDependencies": {
-        "eslint": ">=8.0.0"
-    }
-}
+  "name": "@foundbyte/eslint-plugin",
+  "version": "1.1.5-alpha.1",
+  "description": "ESLint plugin for enforcing code style rules including arrow function padding, Vue script lines limit, and TypeScript type comment requirements",
+  "author": "",
+  "license": "ISC",
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "arrow-function",
+    "padding",
+    "vue",
+    "script",
+    "lines-limit",
+    "typescript",
+    "type-comment",
+    "comment-requirement"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/types.d.ts

@@ -1,2 +1,10 @@
 // 导出所有规则配置类型
-export type { ArrowFunctionPaddingOptions, HooksExportLimitOptions, TypeCommentRequirementOptions, VueScriptLinesLimitOptions, HooksArrowFunctionOnlyOptions, NoExcessiveAnyOptions, NoDisabledCommentsOptions } from './lib/rules'
+export type {
+  ArrowFunctionPaddingOptions,
+  HooksArrowFunctionOnlyOptions,
+  HooksExportLimitOptions,
+  NoDisabledCommentsOptions,
+  NoExcessiveAnyOptions,
+  TypeCommentRequirementOptions,
+  VueScriptLinesLimitOptions,
+} from './lib/rules'