@foundbyte/eslint-plugin 1.0.5 → 1.0.7

package/README.md

@@ -0,0 +1,232 @@
+# @foundbyte/eslint-plugin
+
+一个为 FoundByte 项目定制的 ESLint 插件，提供了一系列代码质量检查和最佳实践规则。
+
+## 安装
+
+```bash
+npm install @foundbyte/eslint-plugin --save-dev
+# 或
+yarn add @foundbyte/eslint-plugin --dev
+# 或
+pnpm add @foundbyte/eslint-plugin --dev
+```
+
+## 使用
+
+在 ESLint 配置文件中添加插件：
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  plugins: ['@foundbyte'],
+  rules: {
+    // 启用所有推荐的规则
+    '@foundbyte/arrow-function-padding': 'error',
+    '@foundbyte/hooks-arrow-function-only': 'error',
+    '@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: [''] },
+          ]
+        }
+      ]
+    }],
+  },
+}
+```
+
+## 规则列表与配置示例
+
+### arrow-function-padding
+
+要求函数体之间必须空行。
+
+**配置示例：**
+```javascript
+'@foundbyte/arrow-function-padding': 'error' // 总是要求空行
+```
+
+**示例：**
+```javascript
+// ✅ 正确
+const one = () => {}
+
+const two = () => {}
+
+// ❌ 错误
+const one = () => {}
+const two = () => {}
+```
+
+### hooks-arrow-function-only
+
+要求 React/Vue Hooks 必须使用箭头函数。
+
+**示例：**
+```javascript
+// ✅ 正确
+const useMyHook = () => {
+  const [state, setState] = useState()
+  return state
+};
+
+// ❌ 错误
+function useMyHook() {
+  const [state, setState] = useState()
+  return state
+}
+```
+
+### hooks-export-limit
+
+限制 Hooks 文件内部成员的导出数量。
+
+**配置示例：**
+```javascript
+'@foundbyte/hooks-export-limit': ['error', { maxExports: 2 }] // 最大允许的导出数量
+```
+
+**示例：**
+```javascript
+// ✅ 正确 - 只有一个导出
+export const useMyHook = () => {
+  const a = ''
+  return {
+    a
+  }
+}
+
+// ❌ 错误 - 多个导出
+export const useMyHook = () => {
+  const a = ''
+  const b = ''
+  return {
+    a,
+    b
+  }
+}
+```
+
+### type-comment-requirement
+
+要求复杂类型定义必须有类型注释。
+
+**配置示例：**
+```javascript
+'@foundbyte/type-comment-requirement': ['error', { 
+  /** 至少1个注释 */
+  minCommentsPerGroup: 1,
+  /** 每3个类型 */
+  groupSize: 3,
+}]
+```
+
+**示例：**
+```ts
+// ✅ 正确 - 有类型注释
+interface user {
+  /** 姓名 */
+  name: 'John'
+  /** 年龄 */
+  age: 30
+  ddress: { city: 'NY', zip: '10001' } 
+}
+
+// ❌ 错误 - 复杂对象没有类型注释
+interface user { name: 'John', age: 30, address: { city: 'NY', zip: '10001' } }
+```
+
+### vue-script-lines-limit
+
+限制 Vue 单文件组件中 `<script>` 标签的行数。
+
+**配置示例：**
+```javascript
+'@foundbyte/vue-script-lines-limit': ['error', { maxLines: 200 }] // 最大允许的行数
+```
+
+**示例：**
+```vue
+<!-- ✅ 正确 - script 标签行数在限制内 -->
+<script>
+export default {
+  data() {
+    return { count: 0 }
+  },
+  methods: {
+    increment() {
+      this.count++
+    }
+  }
+}
+</script>
+
+<!-- ❌ 错误 - script 标签行数超过限制 -->
+<script>
+// ... 超过 200 行代码 ...
+</script>
+```
+
+### tag-attribute-restriction
+
+限制特定标签使用某些属性或属性值。
+
+**配置示例：**
+```javascript
+'@foundbyte/tag-attribute-restriction': ['error', {
+  restrictions: [
+    {
+      tag: 'image',           // 标签名称
+      attributes: [           // 属性限制列表
+        { 
+          name: 'mode',       // 属性名称
+          disallowedValues: [ // 禁止的值列表（可选）
+            '', 
+            'scaleToFill'
+          ] 
+        },
+        { 
+          name: 'lazy-load'   // 完全禁止该属性
+        }
+      ]
+    }
+  ]
+}]
+```
+
+**支持的语法：**
+- 静态属性: `<image mode="" />`
+- 动态属性: `<image :mode="'scaleToFill'" />`
+- 无值属性: `<image lazy-load />`
+- 连字符属性名: `lazy-load`, `data-*` 等
+- JSX 属性
+
+**示例：**
+```vue
+<!-- ✅ 正确 -->
+<image src="test.jpg" mode="aspectFit" />
+
+<!-- ❌ 错误 - 禁止使用空字符串的 mode 属性 -->
+<image mode="" />
+
+<!-- ❌ 错误 - 禁止使用 scaleToFill 值 -->
+<image :mode="'scaleToFill'" />
+
+<!-- ❌ 错误 - 完全禁止 lazy-load 属性 -->
+<image lazy-load />
+```
+
+**错误消息：**
+- `标签 <image> 不允许使用属性 mode` - 当属性被完全禁止时
+- `标签 <image> 的属性 mode 不允许使用值 ""` - 当特定属性值被禁止时

package/index.js

@@ -3,6 +3,7 @@ const vueScriptLinesLimitRule = require('./lib/rules/vue-script-lines-limit')
 const typeCommentRequirementRule = require('./lib/rules/type-comment-requirement')
 const hooksExportLimitRule = require('./lib/rules/hooks-export-limit')
 const hooksArrowFunctionOnlyRule = require('./lib/rules/hooks-arrow-function-only')
+const tagAttributeRestrictionRule = require('./lib/rules/tag-attribute-restriction')
 
 module.exports = {
   rules: {
@@ -11,5 +12,6 @@ module.exports = {
     'type-comment-requirement': typeCommentRequirementRule,
     'hooks-export-limit': hooksExportLimitRule,
     'hooks-arrow-function-only': hooksArrowFunctionOnlyRule,
+    'tag-attribute-restriction': tagAttributeRestrictionRule,
   },
 }

package/lib/rules/index.d.ts

@@ -3,6 +3,7 @@ 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'
 
 import { Rule } from 'eslint'
 
@@ -35,6 +36,11 @@ export interface Rules {
    */
   'hooks-arrow-function-only': Rule.RuleModule
 
+  /**
+   * 限制特定标签使用某些属性或属性值
+   */
+  'tag-attribute-restriction': Rule.RuleModule
+
   /**
    * 索引签名，用于兼容 ESLint 插件类型
    */

package/lib/rules/tag-attribute-restriction.d.ts

@@ -0,0 +1,9 @@
+export interface TagAttributeRestrictionOptions {
+  restrictions?: Array<{
+    tag: string
+    attributes: Array<{
+      name: string
+      disallowedValues?: string[]
+    }>
+  }>
+}

package/lib/rules/tag-attribute-restriction.js

@@ -0,0 +1,304 @@
+module.exports = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: '限制特定标签使用某些属性或属性值',
+            category: 'Best Practices',
+            recommended: false,
+        },
+        fixable: null,
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    restrictions: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                tag: {
+                                    type: 'string',
+                                },
+                                attributes: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            name: {
+                                                type: 'string',
+                                            },
+                                            disallowedValues: {
+                                                type: 'array',
+                                                items: {
+                                                    type: 'string',
+                                                },
+                                            },
+                                        },
+                                        required: ['name'],
+                                        additionalProperties: false,
+                                    },
+                                },
+                            },
+                            required: ['tag', 'attributes'],
+                            additionalProperties: false,
+                        },
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            disallowedAttribute: '标签 <{{tag}}> 不允许使用属性 {{attribute}}',
+            disallowedAttributeValue: '标签 <{{tag}}> 的属性 {{attribute}} 不允许使用值 "{{value}}"',
+        },
+    },
+
+    create(context) {
+        const options = context.options[0] || {};
+        const restrictions = options.restrictions || [];
+
+        // 如果没有配置限制，则不进行检查
+        if (restrictions.length === 0) {
+            return {};
+        }
+
+        // 获取文件名，只对 .vue 文件生效
+        const filename = context.getFilename();
+        if (!filename.endsWith('.vue')) {
+            return {};
+        }
+
+        // 创建标签到限制规则的映射
+        const tagRestrictions = new Map();
+        restrictions.forEach(restriction => {
+            tagRestrictions.set(restriction.tag.toLowerCase(), restriction);
+        });
+
+        return {
+            Program(node) {
+                // 获取整个文件的源代码
+                const sourceCode = context.getSourceCode();
+                const text = sourceCode.getText();
+                
+                // 使用正则表达式匹配模板中的标签和属性
+                const tagRegex = /<(\w+)([^>]*)>/g;
+                let match;
+                
+                while ((match = tagRegex.exec(text)) !== null) {
+                    const tagName = match[1].toLowerCase();
+                    const attributesStr = match[2];
+                    
+                    const restriction = tagRestrictions.get(tagName);
+                    if (restriction) {
+                        checkTemplateAttributes(tagName, attributesStr, restriction.attributes, match.index, sourceCode);
+                    }
+                }
+            },
+
+            JSXOpeningElement(node) {
+                // 处理 JSX 元素
+                if (node.name.type === 'JSXIdentifier') {
+                    const tagName = node.name.name.toLowerCase();
+                    const restriction = tagRestrictions.get(tagName);
+
+                    if (restriction) {
+                        checkAttributes(node, tagName, restriction.attributes);
+                    }
+                }
+            },
+        };
+
+        function checkTemplateAttributes(tagName, attributesStr, attributeRestrictions, tagStartIndex, sourceCode) {
+            // 使用正则表达式匹配属性（支持静态和动态属性，支持连字符属性名）
+            const attrRegex = /(:)?([\w-]+)(?:\s*=\s*"([^"]*)")?/g;
+            let attrMatch;
+            
+            while ((attrMatch = attrRegex.exec(attributesStr)) !== null) {
+                const isDynamic = attrMatch[1] === ':'; // 是否是动态属性
+                const attributeName = attrMatch[2].toLowerCase();
+                let attributeValue = attrMatch[3] || '';
+                
+                // 处理动态属性中的字符串值
+                if (isDynamic) {
+                    // 处理空字符串值
+                    if (attributeValue === "''") {
+                        attributeValue = '';
+                    }
+                    // 处理带引号的字符串值，如 'scaleToFill'
+                    else if (attributeValue.startsWith("'") && attributeValue.endsWith("'")) {
+                        attributeValue = attributeValue.slice(1, -1);
+                    }
+                }
+                
+                attributeRestrictions.forEach(attrRestriction => {
+                    if (attributeName === attrRestriction.name.toLowerCase()) {
+                        const disallowedValues = attrRestriction.disallowedValues || [];
+                        
+                        // 如果属性存在但没有指定禁止的值，则报告错误
+                        if (disallowedValues.length === 0) {
+                            context.report({
+                                loc: {
+                                    start: sourceCode.getLocFromIndex(tagStartIndex + attrMatch.index),
+                                    end: sourceCode.getLocFromIndex(tagStartIndex + attrMatch.index + attrMatch[0].length),
+                                },
+                                messageId: 'disallowedAttribute',
+                                data: {
+                                    tag: tagName,
+                                    attribute: attrRestriction.name,
+                                },
+                            });
+                        } else if (disallowedValues.includes(attributeValue)) {
+                            context.report({
+                                loc: {
+                                    start: sourceCode.getLocFromIndex(tagStartIndex + attrMatch.index),
+                                    end: sourceCode.getLocFromIndex(tagStartIndex + attrMatch.index + attrMatch[0].length),
+                                },
+                                messageId: 'disallowedAttributeValue',
+                                data: {
+                                    tag: tagName,
+                                    attribute: attrRestriction.name,
+                                    value: attributeValue,
+                                },
+                            });
+                        }
+                    }
+                });
+            }
+        }
+
+        function checkAttributes(node, tagName, attributeRestrictions) {
+            const attributes = getAttributes(node);
+
+            attributeRestrictions.forEach(attrRestriction => {
+                const attributeName = attrRestriction.name;
+                const disallowedValues = attrRestriction.disallowedValues || [];
+
+                // 检查属性是否存在
+                const attribute = attributes.find(attr => 
+                    attr.name.toLowerCase() === attributeName.toLowerCase()
+                );
+
+                if (attribute) {
+                    // 如果属性存在但没有指定禁止的值，则报告错误
+                    if (disallowedValues.length === 0) {
+                        context.report({
+                            node: attribute.node,
+                            messageId: 'disallowedAttribute',
+                            data: {
+                                tag: tagName,
+                                attribute: attributeName,
+                            },
+                        });
+                    } else if (attribute.value) {
+                        // 检查属性值是否在禁止列表中
+                        const attributeValue = getAttributeValue(attribute.value);
+                        if (disallowedValues.includes(attributeValue)) {
+                            context.report({
+                                node: attribute.node,
+                                messageId: 'disallowedAttributeValue',
+                                data: {
+                                    tag: tagName,
+                                    attribute: attributeName,
+                                    value: attributeValue,
+                                },
+                            });
+                        }
+                    }
+                }
+            });
+        }
+
+        function getAttributes(node) {
+            const attributes = [];
+
+            // 处理 JSX 属性
+            if (node.type === 'JSXOpeningElement') {
+                node.attributes.forEach(attr => {
+                    if (attr.type === 'JSXAttribute') {
+                        attributes.push({
+                            name: attr.name.name,
+                            value: attr.value,
+                            node: attr,
+                        });
+                    }
+                });
+            }
+            // 处理 Vue 模板属性
+            else if (node.type === 'VElement') {
+                // 处理 Vue 模板的属性
+                if (node.startTag && node.startTag.attributes) {
+                    node.startTag.attributes.forEach(attr => {
+                        let attributeName = '';
+                        let valueNode = null;
+
+                        // 处理不同类型的 Vue 属性
+                        if (attr.key) {
+                            // 处理静态属性
+                            if (attr.key.type === 'VDirectiveKey') {
+                                // 处理动态属性 (:attribute)
+                                if (attr.key.name && attr.key.name.name === 'bind') {
+                                    if (attr.key.argument && attr.key.argument.type === 'VIdentifier') {
+                                        attributeName = attr.key.argument.name;
+                                    }
+                                }
+                            } else if (attr.key.type === 'VIdentifier') {
+                                // 处理静态属性
+                                attributeName = attr.key.name;
+                            } else if (attr.key.name) {
+                                // 处理其他类型的属性
+                                attributeName = attr.key.name;
+                            }
+                        }
+
+                        // 处理属性值
+                        if (attr.value) {
+                            valueNode = attr.value;
+                        }
+
+                        if (attributeName) {
+                            attributes.push({
+                                name: attributeName,
+                                value: valueNode,
+                                node: attr,
+                            });
+                        }
+                    });
+                }
+            }
+
+            return attributes;
+        }
+
+        function getAttributeValue(valueNode) {
+            if (!valueNode) {
+                return '';
+            }
+
+            // 处理字符串字面量
+            if (valueNode.type === 'Literal') {
+                return valueNode.value;
+            }
+
+            // 处理 JSX 表达式容器中的字符串
+            if (valueNode.type === 'JSXExpressionContainer') {
+                if (valueNode.expression.type === 'Literal') {
+                    return valueNode.expression.value;
+                }
+            }
+
+            // 处理 Vue 模板中的属性值
+            if (valueNode.type === 'VLiteral') {
+                return valueNode.value;
+            }
+
+            // 处理 Vue 模板中的表达式
+            if (valueNode.type === 'VExpressionContainer') {
+                // 对于表达式容器，我们无法确定具体的值，返回空字符串
+                return '';
+            }
+
+            // 对于其他类型的值，返回空字符串
+            return '';
+        }
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundbyte/eslint-plugin",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "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",