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

package/README.md

@@ -77,6 +77,13 @@ module.exports = {
       },
     ],
     '@foundbyte/require-json-parse-type': 'error',
+    '@foundbyte/no-restricted-literal-types': [
+      'error',
+      {
+        forbidden: ['null', 'undefined', ''],
+        allowInUnions: true,
+      },
+    ],
   },
 }
 ```
@@ -631,9 +638,15 @@ 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 }
 ```
@@ -646,6 +659,73 @@ const a = JSON.parse('{s:1}') as { s: number }
 
 **注意：**
 
-- 该规则只检查变量声明的初始化表达式直接是 `JSON.parse(...)` 的情况
+- 该规则检查变量声明的初始化表达式中是否包含 `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.js

@@ -9,6 +9,7 @@ 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 = [
@@ -44,6 +45,7 @@ module.exports = {
     'no-disabled-comments': noDisabledCommentsRule,
     'no-restricted-components': noRestrictedComponentsRule,
     'require-json-parse-type': requireJsonParseTypeRule,
+    'no-restricted-literal-types': noRestrictedLiteralTypesRule,
   },
   configs: {
     customize: (options) => {

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.js

@@ -80,6 +80,43 @@ module.exports = {
       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 节点
@@ -94,8 +131,7 @@ module.exports = {
           return
         }
 
-        const unwrappedInit = unwrapExpression(declaration.init)
-        if (!isJsonParseCall(unwrappedInit)) {
+        if (!containsJsonParse(declaration.init)) {
           return
         }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundbyte/eslint-plugin",
-  "version": "1.1.5-alpha.0",
+  "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",